# Clutch cutaway: review findings and accuracy plan

**PR:** yachint/car-demos #1, *Interactive clutch cutaway* (`cursor/clutch-cutaway-demo-ec31` → `main`)
**Reviewed at:** `46671ce` (PR version 4). All `file:line` references point at this commit.
**Date:** 2026-10-19

This combines four passes over the branch:

- a code review of the diff for bugs
- a drivetrain physics audit of `src/sim.js`
- a 3D mechanics audit of `src/vehicle.js`
- an audit of the lessons, narration text and audio

Behaviour was measured by stepping `src/sim.js` headless in Node with scripted pedal inputs. Every number below comes from those runs unless it is marked as a real-car reference. `npm test` passes 18/18 at `46671ce`.

Findings are numbered by area so they can be referenced from commits:

| Prefix | Area |
| --- | --- |
| **R** | Bugs from the code review |
| **P** | Physics |
| **T** | Teaching: lessons, narration text and controls |
| **M** | 3D model |
| **A** | Audio |
| **N** | New lessons |

---

## 1. The short version

**One root cause covers about half of the bugs.** Commits `8097734` to `46671ce` changed three things:
- They moved the clutch touch point to pedal **0.82**.
- They made `engagementFromPedal` a torque fraction that jumps from 0 to **0.1** at the touch point.
- They built idle creep from first-gear special cases on top of a clutch solver that already had a sign bug.

Thresholds elsewhere still assume the old curve:
- the `open`/`slipping`/`locked` mode
- the shift gate
- the starter interlock
- the stall gate
- the slider label and the CSS bite band
- the drawn plate gap

**The single most valuable change is to replace the clutch solve and the idle/stall logic with a standard grip-or-slip model** (P1 + P3). It removes every first-gear special case. A prototype passes 17 of the 18 existing tests, and the one failure is an over-tight assertion (details in P1). It makes clutch releases behave the same from 20 to 240 fps, and it clears R1, R4, R8 and R10 outright.

### Recommended order

| Phase | What | Clears | Effort |
| --- | --- | --- | --- |
| 1 | One-line and small fixes: half-shaft spin sign, pedal order, H-pattern table, countershaft speed, 5th gear lighting, key handling, wording | M2, M3 (part), M4 (part), R5, R12, R13, T9 | S |
| 2 | Grip-or-slip clutch, idle control that is always on, stall below 300 rpm | P1, P3, R1, R4, R8, R10 | M |
| 3 | One definition of open, slipping and locked, used everywhere; starter fixes; plate gap from pedal travel | R2, R3, R6, R7, R14, R15, T5 | M |
| 4 | Engine losses and part-throttle model, then retune the lessons | P2, T1, T2, T3 | M |
| 5 | Teaching text and gear-lever rules | R9, T4, T6, T7, T8 | S–M |
| 6 | 3D mechanics: clutch release, gearbox motion, wheels, proportions | M1, M3, M5–M7 | M–L |
| 7 | Calibration, audio, new lessons, hills | P4, P5, A1–A6, N | M |

Frame-rate robustness (R11 and a fixed-step accumulator) should land with phase 2, because P1's frame-rate guarantee depends on it.

---

## 2. Bugs from the code review (R)

### R1. The engine can be dragged to 0 rpm in the bite zone without stalling
- **Where:** `src/sim.js:373` (stall gate), `src/sim.js:286` (idle control gated on brake)
- **Problem:**
  - Stall detection only runs when `engagement > 0.62`, which on the new curve is roughly the last 16% of pedal travel.
  - Idle control switches off when the clutch is loaded and `brake >= 0.12`.
  - So across the whole bite zone, the crank can be pulled to 0 rpm while `alive` stays `true`.
- **Measured:**
  - 1st gear, clutch 0.5, brake 0.5, throttle 0 for 3 s: `alive=true`, `rpm=0`, mode `slipping`, narration "Bite point". The UI keeps saying "Engine running".
  - Releasing the brake then brings the engine back to about 794 rpm **without the starter**.
  - 5th gear at pedal 0.3 also ends at 0 rpm and still alive.
  - Holding the bite (pedal 0.5) in 3rd at idle sits at 426 rpm indefinitely.
- **Fix:** P3. Use an idle controller that is always on, and stall when rpm drops below a single threshold. Remove both gates.

### R2. Holding the starter disables stall detection
- **Where:** `src/sim.js:374` (`!sim.starter` in the stall check), the starter clamp at `src/sim.js:329`, the Start button and the `E` key handler in `src/main.js`
- **Problem:**
  - While the starter is held, both the stall check and the anti-reverse flywheel guard are skipped, even when the engine is already running.
  - Start and `E` accept a press at any time.
  - The starter is not released on `pointercancel`.
- **Measured:**
  - Hold E or Start and dump the clutch in 1st: no stall.
  - Hold E while braking from 14 m/s in 3rd with the clutch up: `alive=true`, `rpm=0`, mode `locked`. The flywheel can go slightly negative, because the starter clamp allows −30 rad/s.
  - On touch, a cancelled pointer leaves the starter held, and then the engine can never stall.
- **Fix:**
  - Let the starter act only when `!alive`, and ignore it once the engine fires.
  - Never skip the stall check because of the starter.
  - Release the starter on `pointerup`, `pointercancel`, `pointerleave` and window `blur` (see R13).

### R3. The touch point (0.82) disagrees with the "open" mode and the shift gate (0.78)
- **Where:**
  - `src/sim.js:55` (`engagementFromPedal`)
  - `src/sim.js:198` (`sample()`: `engagement < 0.14` → `open`)
  - `src/sim.js:160` (`requestGear`: `clutchPedal < 0.78` refused)
  - `src/ui.js:125` (label `Down` above 0.78)
- **Problem:** engagement jumps from 0 to 0.1 at pedal 0.82, but:
  - `sample()` still reports `open` up to engagement 0.14 (pedal 0.75–0.82).
  - `requestGear` allows a shift at pedal ≥ 0.78, which is now past the touch point.
- **Measured:** at pedal 0.79, `requestGear(1)` succeeds while the plates carry about 11.5% engagement (about 37 Nm). The car creeps to 8.4 km/h while the coupler reads "Disconnected" and the narration says "Clutch open — Engine and wheels are independent".
- **Fix:** see "One source of truth" under R15.

### R4. The lock clamp drops the sign, so the clutch can push the wrong way
- **Where:** `src/sim.js:258`
  ```js
  return clamp(desired, -Math.abs(lock), Math.abs(lock))
  ```
- **Problem:** when the predicted slip crosses zero, `lock` and `desired` have opposite signs. The symmetric bound still lets `desired` through, so the clutch pushes the slip past zero in the other direction. This is exactly the step-to-step chatter the function's comment says it prevents.
- **Measured:**
  - Dead engine rolling at 10 m/s in 2nd, clutch up, traced every 1/180 s step: slip alternates −11.5 / +0.2 rpm and `flow` alternates −0.62 / +0.01, without end.
  - On a coast-to-full-throttle transition the same flip occurs for one step.
  - `accel` (body pitch) and `heat` both read this oscillation.
- **Minimal fix:**
  ```js
  return clamp(desired, Math.min(0, lock), Math.max(0, lock))
  ```
  P1 replaces the function entirely.

### R5. Arrow keys on a focused pedal slider also apply full throttle or brake
- **Where:** `src/main.js:135`
- **Problem:** the window `keydown` handler maps ArrowUp/ArrowDown to throttle/brake. `isTyping` only exempts `INPUT` and `TEXTAREA`, but the pedal tracks are `div role="slider"`.
- **Repro:** focus the clutch slider and press ArrowUp to raise it 5%. The same event sets `held.throttle = true`, so full throttle is applied while the key is down. ArrowDown on any slider applies full brake.
- **Fix:** skip the global mapping when `event.target.closest('[role="slider"]')` is set, or map only W/S globally.

### R6. The plate gap and finger pose are drawn from the torque fraction, so the plates look apart at the bite
- **Where:** `src/vehicle.js:136`
  ```js
  const open = 1 - sample.engagement
  ```
- **Problem:** engagement is now a torque fraction that stays between 0.1 and 0.38 through the whole slip zone. The cutaway therefore shows the plates mostly apart while they are touching and driving the car.
- **Measured:** in the "Hold the bite" lesson step (clutch 0.5, engagement 0.26), `spread = 0.74 × 0.07`, so the plates are drawn about 74% open while the narration says "The surfaces meet and slip". At the touch point the drawn gap is still 90% of maximum.
- **Fix:**
  - Drive the geometry from pedal position, not torque. The plate gap opens only above the touch point: `lift = clamp((pedal - TOUCH) / (1 - TOUCH), 0, 1)`, drawn exaggerated.
  - The release bearing and diaphragm fingers follow the pedal over its whole travel.
  - Slip is shown by the existing friction glow and by the two sides turning at different speeds.
  - See M1 for the correct direction of motion.

### R7. The starter interlock allows cranking in gear past the bite
- **Where:** `src/sim.js:296`
  ```js
  if (gear !== 0 && engagement > 0.3) sim.starterBlocked = true
  ```
- **Problem:** on the new curve, cranking is allowed in gear down to about pedal 0.42, where the plates carry up to about 96 Nm.
- **Measured:** a dead engine in 1st, pedal at 0.45, starter held: the engine starts and the car drives off at 7.7 km/h. This contradicts the README ("The clutch must be down, or the gearbox in neutral") and the "Press the clutch to start" narration.
- **Fix:** block unless `gear === 0 || engagement === 0` (pedal ≥ TOUCH). Also consider T8: most modern manuals require the clutch down even in neutral.

### R8. A fully released clutch slips for up to a second and shows the "Bite point" text
- **Where:** `src/sim.js:324` (±48 Nm first-gear soft lock), `src/explain.js:68–74`
- **Problem:** the soft lock makes a fully clamped clutch (pedal 0, engagement 1, capacity 320 Nm) slip at 48 Nm. `explain()` then shows the "Bite point" copy, which tells the driver to let a pedal that is already fully up come all the way up.
- **Measured:**
  - After a 0.35 s release in 1st with no throttle, for about 0.8 s the pedal reads 0 and the mode is `slipping` (625 vs 123 rpm). The narration says "Let the pedal come all the way up", and the friction disc glows as if at the bite.
  - The physics run saw the engine held at 600 rpm for 1.2 s with the pedal up.
- **Fix:** P1 removes the soft lock.

### R9. Every stall not caused by braking is explained as a standstill release
- **Where:** `src/explain.js:26–31`, plus where `stallReason` is set at `src/sim.js:373+`
- **Problem:** every stall that isn't from braking is tagged `lug`. The `lug` copy says the pedal came up while the wheels were almost stopped, which is wrong for a lugging stall while rolling, and for reverse while rolling.
- **Measured:** 5th gear at 20 km/h, clutch up, no throttle stalls with `stallReason 'lug'` at 20.5 km/h. The panel reads "The clutch closed before the car was moving … the wheels were still almost stopped".
- **Fix:** split the reason on `stallSpeed`:
  - Below about 1.5 m/s: **dump** (current copy).
  - Above that: **too high a gear**, e.g. "At this speed 5th gear holds the engine below idle. Change down, or press the clutch."
  - Rolling the opposite way to the selected gear: **wrong direction**.

### R10. Idle creep is a set of first-gear special cases, so near-identical gears behave differently
- **Where:** `src/sim.js:315–324` and `src/sim.js:286`
  - `gear === 1` only
  - a `_launchLock` latch at 0.22 m/s
  - a ±48 Nm clamp
  - idle control gated on brake position
- **Measured:**
  - In 1st, any release of 0.3 s or longer creeps. In reverse (ratio 3.16 vs 3.36), releases up to 0.6–0.7 s stall.
  - The 0.7 s reverse case depends on frame rate: it stalls at 30 Hz and creeps at 60 and 144 Hz.
  - A 0.25 s release in 1st stalls at 20, 30, 60 and 144 fps but creeps at 75, 120 and 240 fps.
  - A dump while rolling at 1.0 km/h survives; at 0.7 km/h it stalls.
- **Fix:** P1 + P3. An idle controller with limited torque and a single stall criterion covers every gear without the latch.

### R11. A frame hitch turns an instant clutch dump into a slow release
- **Where:** `src/main.js:191`
- **Problem:** frame slicing ramps the pedals linearly from the previous frame's value to the current one across the whole slow frame, and the frame cap was raised to 0.5 s. A single instant input during a hitch becomes an invented slow release.
- **Repro:** release C (a dump) during a 0.5 s hitch such as a tab switch or GC pause. The sim gets a 0.5 s ramp from 1 to 0 over 30 slices, which in 1st creeps instead of stalling. The same input at a steady 60 fps stalls.
- **Fix:**
  - Use a fixed-step accumulator (for example 1/240 s) and apply new inputs at the first sub-step (sample and hold) instead of interpolating.
  - Cap a single frame at about 0.1 s and drop the remainder rather than simulating it.
  - Pedal rate-limiting, if wanted for keyboard input, belongs on the input side and should be based on real time, not frame time.

### R12. The pedal interpolation state isn't reset when a lesson is placed
- **Where:** `src/main.js:202`
- **Problem:** `applied` is not resynced when `player.play()` or `sim.place()` resets the pedal state. The next frame's slices interpolate from the previous free-drive pedals into the newly placed lesson.
- **Repro:** hold the clutch down (`applied.clutch = 1`) and start "Why it stalls" (setup clutch 0, 3rd gear, 14 m/s). If that first frame has more than one slice, the early slices feed clutch values between 1 and 0 into the placed sim. The lesson does not start from its `setup` state.
- **Fix:** after `place()`/`play()`, copy the sim's pedal state into `applied`. This goes away entirely with R11's sample-and-hold.

### R13. Held keys stay latched after the window loses focus
- **Where:** `src/main.js:146`
- **Problem:** `held.throttle`, `held.brake`, `held.clutch` and `held.starter` are cleared only on `keyup`. There is no `blur` or `visibilitychange` handler.
- **Repro:**
  - Hold W and alt-tab away: on return, full throttle stays applied with nothing pressed.
  - A stuck E has the same effect and also disables stall detection (R2).
- **Fix:** clear every held flag on `window` `blur` and on `visibilitychange` when hidden.

### R14. The narration's "Idle creep" check uses different thresholds from the sim
- **Where:** `src/explain.js:82` (`throttle < 0.22`, `brake < 0.08`, `speed 0.7–4.2`) vs the sim's idle-launch conditions (`throttle < 0.18`, `brake < 0.12`)
- **Measured:**
  - Creeping in 1st at throttle 0.17 and 1,251 rpm still shows "Idle creep … The engine is only idling".
  - With brake between 0.08 and 0.12, the sim still applies idle assist and the soft lock, but the narration falls through to the generic text.
- **Fix:** have `sample()` expose a flag such as `idleCreep` (or `governorActive`) and branch on it, rather than copying the conditions.

### R15. The clutch bite band doesn't match the sim's slip zone
- **Where:** `src/style.css:239` (band about pedal 0.135–0.80), `src/ui.js:125` ("Bite" label 0.2–0.78)
- **Problem:** the sim's plates meet at 0.82 and the clamp is rigid below about 0.26.
  - From pedal 0.80 to 0.82 the plates drive the car outside the highlighted band, with the label reading "Down".
  - From 0.135 to 0.26 the band marks the rigid-clamp region as bite.
  - So the visual hint misleads exactly where the lesson asks for precision.

### One source of truth for the clutch state (fixes R3, R7, R14, R15 and T5)
Export the pedal geometry and the clutch state from `sim.js` and derive everything from them:

```js
// sim.js
export const CLUTCH_TOUCH = 0.82   // plates meet
export const CLUTCH_CLAMP = 0.04   // full clamp load
// in sample():
//   mode: 'open' iff engagement === 0, 'locked' iff sim._locked (P1), else 'slipping'
//   idleCreep: boolean that the sim itself computes
```

Then:

- **`requestGear`:** allow the shift only when `clutchPedal >= CLUTCH_TOUCH`.
- **Starter interlock:** block unless `gear === 0 || clutchPedal >= CLUTCH_TOUCH`.
- **`ui.js` label:**
  - `Down` when `pedal >= CLUTCH_TOUCH`
  - `Bite` when `mode === 'slipping'`
  - `Up` otherwise
- **Bite band:** set `--bite-start`/`--bite-end` CSS custom properties from JS using the exported constants, instead of hard-coding them in `style.css`.
- **`explain.js`:** branch on `mode` and `idleCreep` only, never on raw thresholds.
- **`vehicle.js`:** draw the plate gap from `clutchPedal` relative to `CLUTCH_TOUCH` (R6).

---

## 3. Physics (P)

### P1. Replace the clutch solve with a standard grip-or-slip model and delete the launch special cases
- **Where:** `src/sim.js:250–259` (`clutchTorqueFor`), `src/sim.js:315–324` (soft lock and `_launchLock`)
- **What's wrong:**
  - `clutchTorqueFor` smooths friction with `tanh(slip / 3.2)` and leaves the car-side forces (drag, rolling resistance, brakes) out of `predictedSlip` (line 256).
  - Together with R4 this gives a two-step limit cycle while the clutch is meant to be locked:
    - In 1st at throttle 0.5, clutch torque alternates **2.9 ↔ 145.5 Nm** every substep.
    - The sampled `accel` flips **−0.07 ↔ 4.07 m/s²** from one frame to the next at 30 Hz, so the body pitch (`vehicle.js:220`) shows about half the true value.
    - Coasting, the slip changes sign on 359 of 360 substeps.
  - The ±48 Nm cap and the `_launchLock` latch are not physical (R8, R10).
  - Momentum at lock-up is otherwise correct: in 2nd it locks at 1,668 rpm against 1,675 rpm ideal.
- **Change:** the clutch either holds or slides. Static friction is about 1.25 × kinetic friction. The lock torque is the torque that makes the two sides' speeds equal at the end of this step, including the car-side forces:

```js
const MU_RATIO = 1.25            // static / kinetic clutch friction

// inside integrate(), after the engine torque tEng is known
const G = GEARS[gear] * FINAL
const v = sim.speed
const drag = DRAG * v * Math.abs(v)
const rolling = Math.abs(v) > 0.04 ? Math.sign(v) * ROLLING : 0
const brakeCap = BRAKE_FORCE * brake
const moving = Math.abs(v) >= 0.045
const fExt = -drag - rolling - (moving ? Math.sign(v) * brakeCap : 0)

let clutchTorque = 0
if (gear !== 0 && engagement > 0) {
  const Ir = reflectedInertia(gear)                 // MASS * R² / G²
  const held = !moving && brakeCap > 0              // car held by the brakes
  const invI = 1 / I_ENGINE + (held ? 0 : 1 / Ir)
  const inputRate = held ? 0 : (G / WHEEL_R) * fExt / MASS
  const tLock = (slip + dt * (tEng / I_ENGINE - inputRate)) / (dt * invI)
  const kinetic = engagement * CLUTCH_CAPACITY
  const limit = sim._locked ? kinetic * MU_RATIO : kinetic
  if (Math.abs(tLock) <= limit) { clutchTorque = tLock; sim._locked = true }
  else { clutchTorque = Math.sign(tLock) * kinetic; sim._locked = false }
} else sim._locked = false

// after integrating the car: snap the crank to the input shaft while locked
if (sim._locked && gear !== 0) sim.engineOmega = Math.max(0, tiedNow)
```

- **Also:**
  - Drive `sample().mode` from `sim._locked`.
  - Reset `_locked` in `engageGear`.
  - Replace the variable remainder sub-step in `step()` with a fixed-step accumulator (R11).
  - Optional: start `engagementFromPedal` at **0**, not 0.1, at the touch point (`sim.js:55`) to remove the 0 → 35 Nm jump.
- **Measured with P1 + P2 + P3 prototyped together:**
  - 17 of 18 tests pass. The 18th fails only on its `minRpm > 560` assertion: the engine dips to 517 rpm but stays alive. Loosen that assertion to "did not stall" (or `minRpm > 480`); the real requirement is that it doesn't stall.
  - The four lesson tests pass.
  - A 1.0 s release creeps, and a release of 0.6 s or faster stalls, **identically at 20–240 fps**.
  - Clutch torque is constant while locked, with no sign flips.

### P2. Add engine losses and a realistic part-throttle torque
- **Where:** `src/sim.js:281` (`torqueCurve * throttle`), `src/sim.js:310` (friction)
- **What's wrong:**
  - **Friction is tiny.** It is `0.012·ω + 1.2`, about 5 Nm at 3,000 rpm. A real 2.0 L engine with the throttle shut drags at roughly **35–45 Nm** (friction mep from Heywood/Bishop plus about 0.7 bar of pumping loss).
  - **So there is almost no engine braking.**
    - Coasting from 60 km/h in 3rd slows at 0.25 m/s² with the clutch up and 0.21 m/s² with it down. A real car does about 0.6 against 0.2.
    - With the clutch down, revs fall at 867 rpm/s; a real engine falls at about 1,500 rpm/s.
  - **Any throttle runs away.** `torqueCurve * throttle` means any throttle of 0.18 or more revs an unloaded engine to about 6,800 rpm. There is nothing that makes part throttle settle at a part speed.
  - **It burns the clutch in "Pull away".**
    - The engine reaches **6,762 rpm** before the bite and slips at about 6,570 rpm for 3 s.
    - That puts **165 kJ** into the clutch at a peak of **98 kW**.
    - A normal launch puts in about **12 kJ**: slip energy is roughly the car's kinetic energy at lock-up, ½·1280·4.4² for a 1,500 rpm launch.
- **Change:**

```js
const DISP = 2.0e-3                        // m³
const K_BAR = DISP / (4 * Math.PI) * 1e5   // 15.9 Nm per bar of mean effective pressure
const PUMP_BAR = 0.75                      // closed-throttle pumping mep
const P_AIR = 150000                       // W: air-limited indicated power at full pedal
const DIE_RPM = 300
const IDLE_KP = 0.25

function fmep(rpm) {            // bar, n = rpm / 1000
  const n = Math.max(0, rpm) / 1000
  return 0.97 + 0.15 * n + 0.05 * n * n
}
function lossTorque(rpm, m) {   // friction + pumping that grows as the throttle closes
  const w = Math.sign(rpm) * Math.min(1, Math.abs(rpm) / 200)
  return w * (fmep(rpm) + (1 - m) * PUMP_BAR) * K_BAR
}
function smoothstep(a, b, x) {
  const t = clamp((x - a) / (b - a), 0, 1)
  return t * t * (3 - 2 * t)
}

export function engineTorque(rpm, throttle, alive) {
  if (!alive) return -lossTorque(rpm, 0)
  const omega = Math.max(rpmToOmega(Math.max(rpm, 300)), 1)
  const indWot = torqueCurve(Math.max(rpm, 0)) + fmep(rpm) * K_BAR
  const pedal = Math.min(indWot, Math.pow(throttle, 1.5) * P_AIR / omega)   // air-flow limit
  const idleBase = lossTorque(IDLE_RPM, 0.16)
  const idle = clamp(idleBase + IDLE_KP * (IDLE_RPM - rpm), 0, idleBase + IDLE_ASSIST)  // P3
  let ind = Math.min(Math.max(pedal, idle), indWot)
  if (rpm > 6550) ind = Math.max(0, ind - (rpm - 6550) * 0.6)   // limiter
  ind *= smoothstep(DIE_RPM, DIE_RPM + 180, rpm)                 // combustion fades out (P3)
  return ind - lossTorque(rpm, ind / indWot)
}
```

  The separate `friction` term in `integrate()` goes away, because the losses are now inside `engineTorque`. A dead engine uses `-lossTorque(rpm, 0)` (plus the existing small `tanh` term so it settles at zero).
- **Measured with the change:**
  - Engine braking is **0.61 m/s²** in gear against 0.21 m/s² with the clutch down.
  - Revs fall at **1,530 rpm/s** with the clutch down.
  - Unloaded, pedal 0.15 settles at about 2,350 rpm, 0.3 at about 4,500 rpm, and 0.64 at the limiter.
- **Effect:** no effect on the tests. The lessons need retuning, because they were written against the old torque map:
  - "Pull away" throttle 0.64 → about **0.15–0.2**, which gives 7–14 kJ of slip.
  - The "Change gear" throttle of 0.42 at the "Match the engine" step overshoots to 4,800 rpm against a 2,400 rpm target. It wants about 0.15, or no blip at all (T2).
  - See T1–T3.

### P3. Make idle control and stalling come from the torque balance
- **Where:** `src/sim.js:286` (idle control off when `brake >= 0.12`), `src/sim.js:373` (`engagement > 0.62` gate), `src/sim.js:377` (0.4 s grace timer)
- **What's wrong:**
  - Idle control switches off at a brake threshold. Creeping in 1st, brake 0.10 keeps running but brake 0.13 stalls at 4.3 km/h.
  - Stalls are only checked when `engagement > 0.62`. Holding the bite in 3rd at idle sits at 426 rpm indefinitely (R1).
  - The 0.4 s grace timer means braking in 3rd at 0.9 kills the engine only at about 200 rpm (about 4.9 km/h), although the lesson says "under about 500 rpm".
  - At brake 0.3 it dies at 10 km/h instead. So the stall speed depends on brake pressure, which it physically shouldn't.
- **Change:**
  - Keep the idle controller on at all times. Its indicated torque is `clamp(T_loss(850) + 0.25·(850 − rpm), 0, T_loss(850) + 88)`.
    - 88 Nm (`IDLE_ASSIST`) is a defensible reserve for a drive-by-wire anti-stall. Lowering it breaks the creep tests.
  - Fade combustion torque with `smoothstep(300, 480, rpm)`.
  - The engine dies when rpm falls below `DIE_RPM = 300`. Drop the timer and both gates:
    ```js
    if (sim.alive && rpmNow < DIE_RPM) { sim.alive = false; sim.stallReason = …; sim.stallSpeed = Math.abs(sim.speed) }
    ```
    The starter must not exempt a running engine from this (R2).
- **Measured with the change:**
  - Braking in 3rd crosses 520 rpm at 12.8 km/h and stalls at **7.2 km/h, whatever the brake pressure**.
  - In 1st, idle control holds against brake 0.3 and stalls at brake 0.5.
  - The stall and clean-stop lessons still pass.

### P4. Calibration (small, no effect on the lessons)

**Gearing.** 100 km/h in 5th measures 2,288 rpm, which is low for a 5-speed (typically 2,600–3,000). Idle creep in 1st is 8.6 km/h; real cars creep at about 5–8.
- `WHEEL_R` 0.34 m matches a 225/55R17. A 205/55R16 is about 0.31 m.
- With **`WHEEL_R = 0.31`** and **`FINAL = 3.9`**: about 2,700 rpm at 100 km/h and about 7.6 km/h creep.

**Acceleration.** 0–100 km/h measures 8.3 s; about 9–10 s is typical for 105 kW and 1.3 t.
- Add drivetrain efficiency **η ≈ 0.92** on the force through the gearbox and axle.
- Add wheel and driveline inertia, worth about **+4% equivalent mass**.

**Already right:**

| Constant | Value | Real-world check |
| --- | --- | --- |
| `DRAG` | 0.4 | ½·1.2·0.30·2.2 ✓ |
| `ROLLING` | 170 N | rolling coefficient ≈ 0.0135 ✓ |
| `CLUTCH_CAPACITY` | 320 Nm | 1.45 × peak engine torque (1.2–1.5 is typical) ✓ |
| `I_ENGINE` | 0.25 kg·m² | plausible with a dual-mass flywheel ✓ |

Braking at standstill never pushes the car backwards ✓.

### P5. Further realism that might complicate the teaching
- **Tyre traction:**
  - Every lock-up from high rpm peaks at 8.81 m/s² (0.9 g).
  - A rear-drive car with this layout tops out at a = μg·(b/L) / (1 − μh/L) ≈ 0.59 g.
  - Doing it properly means modelling the rear wheels' speed separately, with the tyre as a second grip-or-slip element (limit μ·N_r·R). That adds a third speed to explain.
  - After P2 and the lower lesson throttle, the lessons stay at or below 3.1 m/s², so this only matters for abuse in free drive.
- **Full-pedal braking:** `BRAKE_FORCE` 7600 N is 0.61 g at full pedal; a real car does about 0.9–1.0 g. Changing it means retuning the lessons' brake 0.9.
- **Hills:** a grade term (m·g·sinθ) would allow hill-start and roll-back lessons (N).
- **Later:**
  - a 0.1–0.2 s air-path lag on the idle controller
  - clutch friction that varies with slip speed and temperature (judder, fade)
  - driveline wind-up shuffle after lock-up (at 2–5 Hz the "locked" readout would oscillate)
  - bump starts
  - a starter that cranks at 200–300 rpm

---

## 4. Teaching: lessons, narration text and controls (T)

The timelines below were tested against the **current** sim at `46671ce`. After P2 lands, re-check the throttle values, because the new engine model makes the same pedal produce less runaway.

### T1. "Pull away" revs to the redline and burns the clutch
- **Where:** `src/lessons.js:31` (`throttle: 0.64` with the clutch down), `src/lessons.js:37–40` ("Hold the bite"), `src/lessons.js:45–48`
- **Problem:**
  - The engine reaches about 6,900 rpm, past the red arc.
  - "Hold the bite" slips about 4,500 rpm for 3 s (heat 0.83).
  - The player keeps its last targets (`throttle: 0.38`), so the car ends on the limiter at 71 km/h in 1st, under the text "on flat ground idle alone is enough".
- **Real practice:** instructors teach pulling away on idle or at about 1,200–1,500 rpm.
- **Tested replacement** (peaks at 1,293 rpm, ends creeping at 8.6 km/h):

| at (s) | inputs |
| --- | --- |
| 2.0 | `clutch: 1` |
| 4.0 | `gear: 1` |
| 5.5 | `brake: 0, clutch: 0.62, throttle: 0.12` |
| 7.5 | `clutch: 0.4, throttle: 0.16` |
| 9.3 | `clutch: 0.02` |
| 11.0 | `throttle: 0` |

- **Copy:** change "A little throttle" to describe a small rise to about 1,200–1,500 rpm, and keep "idle alone is enough" for the last step, which is now true.

### T2. "Change gear" blips the throttle on an upshift and overshoots
- **Where:** `src/lessons.js:56` (setup `throttle: 0.42`), `src/lessons.js:84–88` ("Match the engine", `throttle: 0.42`)
- **Problem:**
  - The engine falls to 1,100 rpm when 3rd needs about 2,000. Then 0.42 throttle flares it to 2,980 rpm, so the clutch closes about 1,000 rpm high.
  - The lesson also keeps accelerating to 118 km/h.
- **Real practice:** an upshift is lift off and clutch down together, then release as the revs fall to the new gear's speed. A blip belongs to a downshift.
- **Tested replacement** (no flare):

| at (s) | inputs |
| --- | --- |
| 3.0 | `throttle: 0, clutch: 1` |
| 3.9 | `gear: 3` |
| 4.6 | `clutch: 0.02` |
| 5.0 | `throttle: 0.3` |
| 8.0 | `throttle: 0.12` |

- **Copy:**
  - Replace "Match the engine" with something like "Let the revs fall. Third needs a lower engine speed, so the engine is already coming down to meet the disc."
  - Keep the throttle-blip idea for a downshift lesson (N).
- **Also:** lower the setup throttle so the lesson ends at a steady cruise. Ending at 0.12 avoids the run to 118 km/h.

### T3. "Stop cleanly" teaches coasting, and the live text treats braking in gear as a fault
- **Where:** `src/lessons.js:145–151` (clutch 1 with brake 0.9 at 2.5 s), `src/explain.js:54–59`
- **Problem:**
  - The lesson presses the clutch at the same moment as 0.9 brake, which is a hard stop at 5.3 m/s².
  - `explain.js` warns "The brakes are slowing the engine too" whenever you brake in gear.
- **Real practice:**
  - Brake in gear, then press the clutch as the revs approach idle.
  - Holding the clutch down for the whole stop is "coasting", which is marked as a fault on the UK driving test.
- **Tested replacement:**

| at (s) | inputs |
| --- | --- |
| 2.5 | `brake: 0.45` |
| 5.2 | `clutch: 1` (engine at about 1,190 rpm) |
| 8.6 | `gear: 0` |
| 10.0 | `clutch: 0.04` |

- **Better still:** let `when` steps set pedals, so the clutch goes down at an rpm threshold rather than a fixed time. Today `observe()` (`src/lessons.js:241–251`) only sets text.
- **Copy for the explain panel:** "Braking in gear is normal. In 3rd the engine reaches idle at about 21 km/h; press the clutch before then."
- **Speeds at which each gear reaches idle**, from `IDLE_RPM`, `GEARS`, `FINAL` and `WHEEL_R`:

| Gear | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| km/h | 9 | 15 | 21 | 29 | 37 |

### T4. The stall explanation is wrong
- **Where:** `README.md:27`, `src/lessons.js:128`, `src/explain.js:23`, and the PR description
- **Problem:** "Under about 500 rpm the crankshaft cannot finish the next compression stroke" is false. Engines start while the starter turns them at 150–300 rpm.
- **Real mechanism:** dragged below idle, the engine cannot make the torque the wheels are demanding, so it slows further and dies.
- **Replacement wording:** "Dragged below idle, the engine can't make the torque the wheels demand, and it dies."
- **Also at `explain.js:23`:** the text says the engine "fell through 500 rpm" but reports `stallSpeed` from about 0.4 s later (about 5 km/h, about 200 rpm), so the two numbers don't belong together. Show the gear's idle speed from the T3 table instead: "In 3rd the engine reaches idle at about 21 km/h."

### T5. The clutch-state labels contradict the sim
- **Where:** `src/sim.js:198`, `src/ui.js:125`, `src/sim.js:160`, `src/explain.js:41`
- **Problem:**
  - At pedal 0.74–0.82, engagement is still 0.10–0.14 and the car creeps at 8.4 km/h, yet the mode reads `open` ("Disconnected").
  - The readout says "Down" from 0.78, and shifts are allowed there.
  - A steady creep at pedal 0.6 (2.6 rpm of slip) reads "Slipping", because `locked` needs `engagement > 0.8`.
  - `explain.js:41` uses a third threshold (`engagement < 0.2`).
- **Fix:**
  - `open` only when engagement is 0, for the mode, the readout and the shift gate.
  - `locked` from P1's grip state. If P1 isn't adopted, use `|slip| < 40 rpm`.
  - See "One source of truth" in section 2.

### T6. The live narration ignores context
All in `src/explain.js`:

| Lines | Problem | Fix |
| --- | --- | --- |
| 26–31 | The lug copy ("clutch closed before the car was moving") also fires for 5th at 20 km/h and for reverse while rolling. | R9: when `stallSpeed > 1.5 m/s`, say "too high a gear". |
| 68–74 | The slipping text always describes a standing start, even while the clutch re-engages after an upshift. | Branch on speed: below about 1 m/s, a launch; otherwise "matching the engine to the new gear". |
| 48–52 | Neutral at 49 km/h says "select first". | Above about 10 km/h, suggest the gear that suits the speed, or describe coasting. |
| 86 | "about walking pace", but the sim creeps at about 9 km/h. | Say "at about 9 km/h" (about 7.6 after P4). |
| 93 | "Compression in the cylinders resists." Most engine braking is pumping loss against the closed throttle, with fuel cut. | "The throttle is shut, so the pistons pull against a near-vacuum and the fuel is cut. That pumping loss slows the car." The sim barely models this today (P2). |

### T7. The gear-lever rules don't match a real car
- **Where:** `src/sim.js:157–172`
- **Engine off:** a shift is refused "under load" when the clutch is up. With the engine off there is no load (that is how you park in gear), so allow any gear.
- **Reverse:** allowed up to 0.7 m/s forward, and then the engine stalls. Require `|speed| < 0.1 m/s` and gearbox input below about 100 rpm, otherwise refuse with a grind (A5).
- **1st at 60 km/h:** allowed. Refuse a shift that would land the engine past the red arc, with copy that names the speed limit for that gear.
- **Real cars:** you can force a shift without the clutch, but it grinds unless rev-matched. Refusing it is a reasonable teaching rule, but the copy should say it grinds rather than claim it's impossible.

### T8. The starter text is false
- **Where:** `src/explain.js:8`, `src/explain.js:37`, and the README controls table
- **Problem:**
  - "The starter would have to turn the whole car" suggests it can't. In fact a starter will lurch a car that is in gear.
  - Most modern manual cars won't crank without the clutch down, even in neutral.
- **Copy:** "Clutch down, neutral, then Start."
- **Rule:** consider always requiring the clutch (`src/sim.js:296`, R7).

### T9. Minor wording
| Where | Now | Better |
| --- | --- | --- |
| `src/lessons.js:27` | "The gear slides in without fighting the engine." | "A synchro sleeve matches speeds and locks the gear to its shaft. The gears themselves stay in mesh." |
| `src/lessons.js:69` | "before they are asked to slide apart" | "before the sleeve is asked to unlock" |
| `src/lessons.js:94` | "because the gear multiplies it less" | "because third needs fewer engine turns per wheel turn" |
| `index.html:111` and the PR body | "the real millimetre of clearance" | "about a millimetre of real clearance" |

---

## 5. 3D model (M)

Model units are metres. +x is forward, +z is the driver's right, `WHEEL_R` is 0.34 and the wheelbase is 2.58.

### M1. The clutch release works backwards, and the diaphragm can't be seen (medium–large)
- **Where:** `src/vehicle.js:147` (bearing travel), `:152` (bearing spin), `:153` (finger pivot), `:291` (`coverSpin.x = FLY_X`), `:301`, `:314` (input shaft is a child of the disc), `:330` (solid pressure plate), `:350–362` (fork)
- **Now:**
  - The diaphragm fingers sit at x 0.717–0.723, *inside* the flywheel (x 0.708–0.772). In Face view 0 pixels of the fingers or the disc show, because the solid pressure plate covers the disc.
  - Pressing the pedal moves the release bearing **105 mm away from the engine**. The pressure plate moves back 140 mm, and the disc 70 mm.
  - Because the input shaft is a child of the disc, the shaft slides back too.
  - The fingers pivot at their outer edge with nothing pushing them. This contradicts `lessons.js:21` ("The release bearing pushes the diaphragm fingers").
- **Real push-type clutch:**
  - The order is flywheel → friction disc → pressure plate → diaphragm spring on a pressed-steel cover → release bearing on a fixed guide sleeve.
  - Pressing the pedal moves the bearing about **8–10 mm toward the engine**.
  - The fingers pivot on the cover's fulcrum ring at about 0.8 × plate radius. Their outer edge lifts the pressure plate about **1.5–2 mm** (a lever ratio of about 4:1).
- **Change:**
  - **Grouping:** put the cover, diaphragm and pressure plate in one group, behind the disc, that rotates with the flywheel.
  - **Fingers:** pivot them at the fulcrum radius. Drive the bearing toward +x by `open * travel`, and move the plate back by `travel / 4`. Exaggerate both by the same factor and note it.
  - **Pressure plate:** make it an annulus, so Face view shows the fingers and, through them, the disc hub.
  - **Input shaft:**
    - Give it its own group that does not slide, extended forward to a pilot bearing in the crank.
    - The disc slides only a millimetre or so on its splines.
  - **Release bearing:** spin its inner race with `engineAngle` only, never `inputAngle` (`:152`).
  - **Explode:** separate the cover assembly as one unit instead of bending the fingers further.
  - **Fork:** add the guide sleeve. Pivot the fork on a ball stud rather than sliding it.
  - **Gap:** drive it from pedal travel, as in R6.

### M2. Pedals, gear lever and steering wheel are in the wrong places (small)
- **Pedals** (`src/vehicle.js:627–629`):
  - The seat is at z +0.34 (`:657`), so the cabin is right-hand drive.
  - The clutch is outboard at z 0.46 and the throttle inboard at 0.22, so from the seat the pedals read **throttle – brake – clutch**. That is wrong for any car.
  - **Right-hand drive:** clutch 0.22, brake 0.34, throttle 0.46.
  - **Left-hand drive:** mirror the cabin to clutch −0.46, brake −0.34, throttle −0.22.
- **Shift pattern** (`src/vehicle.js:833–844`):
  - `leverPose` swaps the two axes, so the H lies on its side. Only 1 and R land in the right place; 2 goes forward-right and 5 back-left.
  - The on-screen gate (`index.html:144–150`) is the standard 1-3-5 over 2-4-R.
  - Use:
    ```js
    { 0: [0, 0], 1: [-0.28, -0.22], 2: [0.28, -0.22], 3: [-0.28, 0], 4: [0.28, 0], 5: [-0.28, 0.22], '-1': [0.28, 0.22] }
    ```
  - Check the sign convention against the lever's rotation axes in the scene.
- **Lever position** (`src/vehicle.js:632`):
  - Now at (−0.42, 0.58, 0.28), behind the seatback.
  - A rear-drive shifter rises from the gearbox tail on the transmission tunnel, at about (0.05, 0.6, 0.06).
- **Steering wheel** (`src/vehicle.js:666`): it is on the car's centreline. Move it to the seat's z and tilt it about 20°.
- **Clutch linkage:** the pedal drives nothing. Add a master cylinder, a hydraulic line and a slave cylinder on the bellhousing that pushes the fork, so pressing the pedal visibly moves the bearing.

### M3. Gearbox motion is inconsistent (medium)
- **Where:** `src/vehicle.js:381–405`, `src/vehicle.js:184`, `src/vehicle.js:195`, `src/sim.js:396`
- **Now:**
  - **Countershaft speed:** the gear radii (`vehicle.js:381–383`) imply a countershaft turning at input/1.6. They reproduce 3.35, 2.08, 1.42 and 1.02 against `GEARS` ✓. But the countershaft is animated at **−1.25 × input** (`sim.js:396`), so every gear pair's teeth slide past each other at a 2:1 speed mismatch.
  - **Fixed gears:** every mainshaft gear is fixed to the output shaft (`vehicle.js:395`). In neutral, the countershaft gears grind through stationary gears.
  - **Lighting:** 5th lights 4th's pair (`vehicle.js:184`), so "the gear pair that is lit" (`lessons.js:62`) is wrong in 5th.
  - **Missing parts:** no input-to-countershaft pair, no visible shafts, and no 5th pair.
  - **Reverse idler:** at z = 0 it meshes with nothing (`vehicle.js:401`).
  - **Collar:** the single collar is hidden inside the selected gear (`vehicle.js:195`, `:405`).
  - **Tooth sizes:** every gear has 18 or 16 teeth, so meshing teeth have different sizes (40 mm vs 22 mm on the 1st pair).
- **Real gearbox:** the countershaft always turns with the input shaft. The mainshaft gears spin freely on bearings, and a sliding sleeve locks the selected one to the shaft. Neutral therefore shows every gear spinning while the mainshaft stays still, which is exactly the point the lessons make.
- **Change:**
  - Countershaft angle = `−inputAngle / 1.6`. Each mainshaft gear's angle = `−counterAngle × R_counter / R_main`. The mainshaft (output) angle = `inputAngle / GEARS[gear]`, or still in neutral.
  - Add the input-to-countershaft pair at x ≈ 0.53 (radius 0.065 on the input, 0.105 on the countershaft) and a 5th pair at x ≈ 0.06 (radius 0.057 / 0.113).
  - Set `teeth = Math.round(2 * Math.PI * r / pitch)` with one tooth pitch for all gears.
  - Add three sleeves (1-2, 3-4, 5-R), about 0.07 in diameter, sliding ±0.025 toward their gear.
  - Offset the reverse idler in z so it meshes with a countershaft gear and a mainshaft reverse gear.
  - Light the input-to-countershaft pair, the selected pair and the active sleeve.

### M4. The half-shafts spin backwards, and the differential is only a sketch (small, then medium)
- **Rotation:** `ringSpin.rotation.z = +wheelAngle` (`src/vehicle.js:162`), but the wheels use `−wheelAngle` (`src/vehicle.js:203`). The half-shafts are children of `ringSpin` (`:449`), so their orange marker turns against the tyre. Negate it.
- **Ring and pinion** (`src/vehicle.js:425–429`):
  - The teeth are 26:14 (1.86), but `FINAL` is 3.62. Use something like **47:13** to match.
  - The pinion is a spur gear whose disc cuts through the ring's rim.
- **Real:** a hypoid set, with teeth cut on the ring's face, the ring offset to one side, and the pinion below the centreline.
- **Change:**
  - Model the ring as a bevel gear and lower the pinion.
  - Add a carrier with a cross-pin, 2 spider gears and 2 side gears. The spider gears don't turn on their pin when driving straight, so they can stay static.
  - Add see-through axle tubes.

### M5. The wheels render as solid discs (small)
- **Where:** `src/vehicle.js:755–786` (`makeWheel`, tyre at `:760`), brake glow at `:204`
- **Now:**
  - The tyre is a closed cylinder that encloses the rim, spokes, brake rotor and caliper; a render probe saw **0 pixels** of each.
  - So the brake glow never shows, although `lessons.js:115` points at the brake discs.
  - The caliper is also outboard of the rotor, crossing the spokes' path.
- **Change:**
  - Build the tyre with `LatheGeometry`: a sidewall from radius about 0.2 to 0.34 and an open centre.
  - Use an open rim barrel with spokes on the outer face, the rotor inboard, and the caliper straddling the rotor's edge.

### M6. Disc and flywheel details (medium)
- **Disc:**
  - Now a 36 mm solid friction-material cylinder (`src/vehicle.js:301`). The hub and damper springs are buried inside it (`:298`, `:308`), and the springs point outward from the centre (`:311`).
  - A real disc is about **8–9 mm** thick: a steel plate with two ring-shaped friction facings (inner diameter about 0.65 × outer), a splined hub, and 4–6 damper springs laid around its circumference.
- **Flywheel:**
  - Now 28 large teeth (`:253`); a real starter ring gear has about **120–135** fine teeth.
  - The bolts are hidden inside the flywheel (`:266`).
- **Starter pinion:** its centre sits on the flywheel rim (`:584`). Place it at ring-gear radius + pinion radius, and slide it into mesh only while cranking.

### M7. Proportions and alignment (medium–large)
- **Clutch size:**
  - The disc is **370 mm** across, which is truck-sized; this class uses 200–240 mm. The flywheel with its ring gear is 470 mm across, taller than the 0.4 m engine block.
  - The gearbox shaft spacing is 175 mm (real 75–90 mm) and the ring gear is 300 mm (real 190–215 mm).
  - Either scale these by about 0.65 and move the inset camera in, or say in the README and the on-screen note that they are drawn larger.
- **Driveshaft angle:**
  - With `CRANK_Y` 0.6 and the axle at 0.34, the driveshaft slopes **13°** (`src/vehicle.js:433`). U-joints normally run at 1–3°.
  - `CRANK_Y ≈ 0.44` gives 4.4°. Tilt the powertrain about 3° to match the pinion.
  - The engine heights are hard-coded (`src/vehicle.js:497–541`), so make them relative to `CRANK_Y` first.
- **Pistons and crank:**
  - At top dead centre the piston crown is at 0.837, about 90 mm below the cylinder tops (0.91) and the deck (0.94). A real crown comes up flush with the deck.
  - The cylinder sleeves have radius 0.055 against a 0.042 piston.
  - The connecting rod's taper is upside down: the small end is the thicker one (`:527`).
  - The crank is offset 50 mm in z from the flywheel axis (`crankZ`, `:512`) and stops 48 mm short of it. Set `crankZ = 0` and add a flange.
- **Body fit:** the valve cover (top at 1.105) pokes through the hood (top at 1.0) (`:502`, `:690`).
- **Bellhousing** (`:368`): the taper is reversed. The wide end faces the gearbox, and the engine end is narrower than the ring-gear teeth. It should run from x 0.57 to 0.83, wide at the engine block.
- **Driveshaft joints** (`:604`):
  - The U-joints are bare crosses with no yokes, and the shaft starts 20 mm below the mainshaft axis.
  - Add the yokes, a slip yoke and a tail housing.

---

## 6. Audio (A)
`src/audio.js`. Pitch from rpm (`rpm / 30`, the firing frequency of a four-stroke four-cylinder) is correct ✓.

| # | Change |
| --- | --- |
| A1 | **Cranking is silent** (`audio.js:99`, `:105`). Add a chug at `engineRpm / 30` while the starter turns the engine. |
| A2 | **Tone follows the throttle pedal, not engine load.** Drive it from `max(0, sample.flow)` (or clutch torque), so a closed throttle under engine braking sounds different from the same rpm under power. |
| A3 | **Add a lugging judder** below about 1,100 rpm under load: a low-frequency amplitude wobble. |
| A4 | **Add a pitch glide into the stall** and a short shudder when it dies. |
| A5 | **Add a 150 ms grind** on a refused shift (T7). |
| A6 | **Add a quiet road and tyre layer** that scales with speed, so coasting with the engine off isn't silent. |

Don't add a clutch-slip squeal: a real clutch doesn't make one.

---

## 7. New lessons (N)

**These work with the current sim:**
- **Rev-matched vs unmatched downshift:** 3rd → 2nd at 40 km/h, once with a blip and once without. This is where the blip from T2 belongs.
- **Reversing on the bite:** creep backwards with the pedal held at the bite.
- **Too high a gear:** 5th at 20 km/h, showing the lugging stall (needs the R9 copy).
- **Emergency stop:** brake hard and press the clutch at the same moment. This is the one case where clutch and brake go down together.
- **Coasting in neutral vs in gear:** a weak contrast until P2 adds engine braking.
- **Starting the engine:** clutch down, neutral, Start. This needs a `starter` target in the lesson player (`src/main.js:198`).

**These need sim changes first:**
- **Hill start:** needs a slope (P5), a handbrake, idle control that keeps running while braking (P3), and stall detection at partial clutch (P3/R1). Today, holding the bite on the brake drags the engine to 0 rpm while it still counts as running.
- **Engine braking downhill:** needs a slope and closed-throttle engine drag (P2).

---

## 8. Tests to add
- **Frame-rate invariance:** the same pedal trace stepped at 30, 60 and 144 Hz gives the same stall or creep outcome (R10, R11, P1).
- **Reverse:** a 1.0 s release in reverse creeps, the same as in 1st (R10).
- **Bite held against the brake:** 1st, clutch 0.5, brake 0.5 for 3 s → `alive === false` (R1).
- **Starter held:** a clutch dump with the starter held still stalls (R2).
- **Shift gate:** `requestGear` is refused whenever `engagementFromPedal(pedal) > 0` (R3).
- **Starter interlock:** cranking in gear is refused whenever engagement > 0 (R7).
- **Locked state:** no sign flips in clutch torque over 1 s of locked driving (R4, P1).
- **Lesson sanity:** "Pull away" peaks below 2,000 rpm, its clutch slip energy stays under 20 kJ, and the lesson ends below 15 km/h (T1).
- **Clean stop:** the clutch goes down above the gear's idle speed, and the engine stays alive (T3).
- **Update the over-tight assertion:** replace `minRpm > 560` with a check that the engine did not stall (P1).
