# Clutch cutaway: re-check of PR #1 at `81cca6e`

**PR:** yachint/car-demos #1, *Interactive clutch cutaway* (`cursor/clutch-cutaway-demo-ec31` → `main`)
**Re-checked at:** `81cca6e` (PR version 6). New since the first review:
- `7942e79` Replace the first-gear special cases with one clutch model.
- `81cca6e` Keep the release fork and the footwell out of the clutch plates.

**First review:** https://pages.yachint.in/p/clutch-cutaway-review-findings-and-accuracy-plan-ome5uevk (IDs R, P, T, M, A).
**Date:** 2026-10-19

**How this was checked:**
- I read the whole diff since `46671ce`.
- `npm test` passes **29/29** and `npm run build` succeeds.
- **Headless runs.** I stepped the PR's own `sim.js`, `lessons.js` lesson player and `explain.js` in Node at 30, 60 and 144 fps and in Slow mode, and built `vehicle.js` headless to measure part positions.
- **Browser.** I ran the app in Chrome through the Claude in Chrome extension at a 1512×714 viewport. The Chrome window was in the background (`document.visibilityState === 'hidden'`, so frames are paused). The lessons were therefore timed headless with the same code the page runs; the browser was used for screenshots of each view.

New findings are numbered **F1–F18**. All `file:line` references point at `81cca6e`.

---

## 1. Summary

**Most of the first review landed.** All 15 bugs from the code review are fixed or no longer apply, and every lesson behaves the same at every frame rate. The model now:
- treats the clutch as either gripping or slipping, with no first-gear special cases
- runs idle control all the time and stalls below 300 rpm
- uses the new engine losses and calibration
- uses one definition of open, slipping and locked everywhere
- has rewritten lessons and audio and the main 3D corrections

**What's left:**
- **Physics:** the anti-stall is too strong. With the throttle closed, any gear keeps running from about **380 rpm** and then speeds the car up, so "too high a gear" almost never stalls. The narration calls it engine braking. (F1, F2)
- **Pull away:** the lesson's text no longer matches what the model does at each step. (F3)
- **3D clutch:** the parts still don't touch. The pressure plate never reaches the disc, the release bearing never reaches the fingers, and the fingers swing through the disc hub. In the browser the corner inset is off-screen, nearly black, and in Face view it's blocked by gear teeth. (F4, F5)
- **Cabin:** the pedals moved to *behind* the steering wheel, and the Pedals camera no longer shows them. (F6)
- **Smaller items:**
  - Turning Sound off doesn't stop the road noise. (F7)
  - The gear-change checks are skipped when the engine is off. (F8)
  - Narration bugs: shifting to neutral, coasting in neutral, and grammar. (F9–F11)
  - The reverse gears turn the wrong way. (F13)
  - Overlapping labels and a few consistency details. (F15–F18)

---

## 2. Status of the first review

| Item | Status at `81cca6e` |
| --- | --- |
| R1 engine at 0 rpm in the bite | ✅ Fixed. A stall is now any rpm below 300. Holding the bite against the brake (1st, clutch 0.5, brake 0.5) idles at 593 rpm, which is physically consistent. |
| R2 starter disables stall detection | ✅ Fixed. The starter only acts on a stopped engine; it's released on pointer up, cancel and leave and on window blur. A test covers it. |
| R3 touch point vs open/shift gate | ✅ Fixed. `CLUTCH_TOUCH`, and `open` means no torque at all. |
| R4 lock clamp sign | ✅ Fixed. Replaced by the grip-or-slip solve; a test checks there are no sign flips. |
| R5 arrow keys on a slider | ✅ Fixed (`main.js:133`). |
| R6 plate gap from torque | ⚠️ The gap now follows the pedal, but the parts don't touch. See **F4**. |
| R7 starter interlock | ✅ Fixed. It needs the clutch down, even in neutral. |
| R8 soft-lock slip | ✅ Fixed (removed). |
| R9 lug copy | ✅ Split into brakes, gear, direction and lug. The "gear" case now rarely fires; see **F1** and **F11**. |
| R10 first-gear special cases | ✅ Fixed. 1st stalls on a release of 0.6 s or faster and creeps at 0.8 s or slower; reverse needs 1.0 s. Both are identical at 20–240 fps. |
| R11 frame hitch | ✅ Fixed. Fixed 1/240 s steps, frames capped at 0.1 s, and inputs are no longer interpolated across a frame. |
| R12 pedal state on lesson start | ✅ Fixed (the interpolation state is gone). |
| R13 held keys after blur | ✅ Fixed. |
| R14 idle-creep check | ✅ Fixed (`sample().idleCreep`). |
| R15 bite band | ✅ Fixed (CSS variables set from the sim constants). |
| P1 grip-or-slip clutch | ✅ Done. |
| P2 engine losses | ✅ Done. Engine braking is 0.67 m/s² clutch up vs 0.21 clutch down. |
| P3 idle control and stall from torque balance | ⚠️ Done, but the idle reserve is too strong at low rpm. See **F1**. |
| P4 calibration | ✅ Done: 2,698 rpm at 100 km/h in 5th, 7.6 km/h idle creep, 92% drivetrain efficiency, about 4% extra equivalent mass. |
| T1 Pull away | ⚠️ Peaks at 1,800 rpm with 3.9 kJ of slip, but the step text no longer matches. See **F3**. |
| T2 upshift without a blip | ✅ Done. No flare; it ends at a 34.7 km/h cruise. |
| T3 brake in gear, clutch near idle | ✅ Done, with a `when` step that sets the pedals. |
| T4 stall mechanism wording | ✅ Done. |
| T5 labels | ⚠️ Mostly done. The pedal reads "Up" when the pedal is halfway but the plates grip. See **F12**. |
| T6 narration in context | ⚠️ Mostly done. Coasting in neutral with the clutch up is still wrong (**F10**), and the engine-braking text is wrong (**F2**). |
| T7 lever rules | ⚠️ Done while the engine runs. With the engine off the checks are skipped (**F8**), and the neutral message is wrong (**F9**). |
| T8 starter copy | ✅ Done. |
| T9 wording | ✅ Done. |
| M1 clutch release direction | ⚠️ Directions are now right: the bearing and finger tips move toward the engine, the plate lifts away, and the input shaft stays put. The parts still don't touch. See **F4**. |
| M2 pedals, lever, wheel, linkage | ⚠️ Pedal order, H-pattern, lever and steering-wheel position are fixed, and the hydraulic linkage was added. But the pedals are now behind the steering wheel. See **F6**. |
| M3 gearbox motion | ⚠️ Countershaft speed, free-spinning gears, sleeves, input-to-countershaft pair, 5th pair and tooth size are fixed. The reverse gears turn the wrong way. See **F13**. |
| M4 half-shafts and differential | ⚠️ The spin sign is fixed and spider/side gears were added, but the ring and pinion no longer match `FINAL`. See **F14**. |
| M5 open wheels | ✅ Done. Brake glow verified visible in Chrome. |
| M6 disc and flywheel details | ✅ Done: 8 mm disc, 128-tooth ring gear, starter pinion meshes while cranking. |
| M7 proportions | ✅ Done: 240 mm disc, crank lowered, pistons flush with the deck, crank on-axis. |
| A1–A6 audio | ✅ All six done: cranking sound, tone from load, lugging judder, glide into the stall, grind, road layer. But see **F7**. |

---

## 3. New findings

### F1. Idle control is so strong that any gear keeps running from about 380 rpm (physics, high)
- **Where:** `src/sim.js:124–136` (`engineTorque`), `IDLE_ASSIST = 88` (`:36`), `DIE_RPM = 300` (`:21`)
- **Problem:** the idle controller can add its full 88 Nm reserve at any rpm above the combustion fade (300–480 rpm). So with the throttle closed and the clutch up, the engine recovers from far below idle and speeds the car up.
- **Measured** (6 s, throttle 0, clutch up):

| Gear | Lowest speed that survives | Engine at start | Ends at |
| --- | --- | --- | --- |
| 3rd | 8 km/h | 382 rpm | 16.5 km/h |
| 4th | 11 km/h | 378 rpm | 19.6 km/h |
| 5th | 14 km/h | 378 rpm | 18.8 km/h |

  5th from 20 km/h starts at 541 rpm and **speeds up to 27.3 km/h in 10 s with no throttle**. Clutch torque is positive throughout (`flow` +0.51 → +0.19), so the engine is driving the car.
- **Why it matters:**
  - A real engine labouring below about 600 rpm in a high gear shudders and stalls. Anti-stall adds a few tens of Nm, and only near idle.
  - Here, "too high a gear" only stalls when the start speed is already below about 380 rpm. The test `a lugging stall in too high a gear…` passes only because it starts 5th at 12 km/h (325 rpm).
  - The lessons and narration promise a lugging stall that a learner can't reproduce.
- **Fix:**
  - Reduce the idle reserve below idle, for example `reserve = IDLE_ASSIST * smoothstep(550, 750, rpm)`, and/or move the combustion fade up to about `smoothstep(450, 650, rpm)`. Keep the base idle torque so neutral idle and 1st-gear creep still settle near 835 rpm.
  - Then re-run the release sweep and creep tests. The Pull away lesson dips to 689–722 rpm today, so a fade starting near 550 rpm leaves it room.
  - Add a test: 5th at 20 km/h with the throttle closed stalls with `stallReason === 'gear'`.

### F2. The narration says "engine braking" while the engine is driving the car (narration, medium)
- **Where:** `src/explain.js:124–130`
- **Problem:** the engine-braking text is shown whenever `throttle < 0.08 && mode === 'locked' && |speed| > 4`, without checking which way torque flows.
- **Measured:** in F1's 5th-gear case, the panel says "The wheels are turning the engine … That pumping loss slows the car" while the car speeds up and `flow` is +0.5.
- **Fix:**
  - Show engine braking only when `s.flow < -0.02`.
  - Add a lugging case for when `s.flow > 0` and the engine is below idle: "Too high a gear for this speed. The engine is below idle and labouring; change down or press the clutch."

### F3. The Pull away step text no longer matches the model (lessons, medium)
- **Where:** `src/lessons.js:29–56`
- **Measured** (identical at 30, 60 and 144 fps):

| t | Step on screen | Pedal | Engine / disc rpm | km/h | Mode |
| --- | --- | --- | --- | --- | --- |
| 6.0 | "A small rise in revs" ("brings the engine up to about 1,200–1,500 rpm") | 0.63 | 722 / 58 | 0.5 | slipping |
| 7.0 | " | 0.62 | 848 / 493 | 4.4 | slipping |
| 8.0 | **"Hold the bite"** ("The surfaces meet and slip") | 0.41 | 1014 / 1014 | 9.0 | **locked** |
| 9.5 | "Pedal up — the clamp shuts" ("The two rpm readings match") | 0.10 | 1533 / 1533 | 13.7 | locked since 8.0 s |
| 11.0 | "Idle alone is enough" | 0.02 | 1800 / 1800 | 16.1 | locked |

  - The revs never rise to 1,200–1,500 before the bite. The throttle and the bite arrive together, so the engine *dips* to 722 rpm.
  - "Hold the bite" plays after the plates have already gripped.
  - The 1,800 rpm peak comes later, in 1st with the pedal up.
- **Tested replacement** (peaks at 1,182 rpm, minimum 689, 3.1 kJ of slip, ends creeping at 7.4 km/h, identical at 30, 60 and 144 fps):

| at (s) | Inputs | What the model does | Suggested title |
| --- | --- | --- | --- |
| 2.0 | `clutch: 1` | | Pedal down, plates apart |
| 4.0 | `gear: 1` | | First gear, while that gap is open |
| 5.5 | `brake: 0, throttle: 0.1` (clutch still down) | rises to about 1,150 rpm | A small rise in revs ("about 1,100–1,200 rpm") |
| 6.5 | `clutch: 0.62` | slips 6.5–8.4 s; engine dips to about 700, disc climbs | Find the bite |
| 8.5 | `clutch: 0.3` | already gripping at 767 rpm | The plates grip ("the disc has caught up; the pedal can keep coming up") |
| 9.6 | `clutch: 0.02` | locked | Pedal up — the clamp shuts |
| 11.0 | `throttle: 0` | settles at 833 rpm, 7.4 km/h | Idle alone is enough |

### F4. The clutch parts still don't touch (3D, medium)
- **Where:** `src/vehicle.js:134–149` (update), `:253–331` (build)
- **Measured** (vehicle built headless; x is forward along the shaft):

| | Pedal 0 (clamped) | Pedal 0.82 (touch point) | Pedal 1 (fully down) |
| --- | --- | --- | --- |
| Disc facing to flywheel | 0 mm ✓ | 0 mm | 4 mm |
| **Pressure plate to disc** | **11 mm** | 11 mm | 16 mm |
| Bearing face to fingers (at bearing radius) | about 20 mm | about 11 mm | about 10 mm |
| Finger tips (x) | 0.702 | 0.730 | **0.735**, past the disc hub (0.708–0.724) and into the flywheel face (0.725) |

  - The pressure plate is never drawn clamping the disc. "Clamped" and "apart" differ by only 5 mm of plate travel.
  - The release bearing never reaches the fingers, so nothing visibly pushes them. This still contradicts `lessons.js:21` ("The release bearing pushes the diaphragm fingers").
  - The fingers rotate up to 0.42 rad, sweeping their tips 33 mm, while the bearing moves 36 mm from 20 mm behind. The tips pass through the disc hub and end inside the flywheel. In the browser inset, the diaphragm's star of fingers is visible with the pedal up and **disappears into the disc when the pedal is pressed**.
- **Fix:**
  - **Pressure plate:** seat it on the disc when `gap = 0`: its front face at the disc's rear face, about +8 mm from where it is now.
  - **Bearing at rest:** put it touching the finger tips (`bearingX = tipX − tube radius`).
  - **Finger angle from bearing travel:** `θ = atan(travel / (fulcrum − contactRadius))`, so the tips move exactly as far as the bearing.
  - **Travel:** limit the drawn bearing travel to about 10–12 mm, already several times real, so the tips never pass the pressure plate.
  - **Lift:** keep the plate lift at about travel / 4, only above `CLUTCH_TOUCH`.

### F5. The clutch inset is off-screen, nearly black, and blocked in Face view (UI / 3D, medium)
Seen in Chrome at a 1512×714 viewport.
- **(a) Off-screen.** The inset (`#inset`) starts at y = 591 inside a 484 px side panel that scrolls (`overflow-y: auto`), and the page itself doesn't scroll. On a typical laptop window, the close-up the lessons rely on is hidden unless the user scrolls that inner panel.
- **(b) Dark.** `renderInset()` sets `scene.environment = null` (`src/main.js:270`). Full-metal materials then render almost black: the pressure plate (alloy, metalness 1), the diaphragm fingers (0.85) and the flywheel (1). The plates are hard to tell apart.
- **(c) Face view blocked.**
  - `inputSpin` is marked as a clutch part, and it now also carries the input-to-countershaft gear (`vehicle.js:410`). From the Face camera (x ≈ 0.46) that gear's teeth fill the left of the frame.
  - The release bearing and guide sleeve fill the centre.
  - The disc isn't visible at all, although the README says Face view "looks along the shaft at the diaphragm and the disc".
- **(d)** See F4: the fingers vanish into the disc when the pedal is pressed.
- **Fix:**
  - Keep the environment map in the inset, or add a light just for the inset.
  - Move the gear into a sibling group that isn't marked as a clutch part.
  - Hide the guide and fork in Face view, or put the Face camera at a small angle so the bearing doesn't cover the fingers.
  - Fit the inset without scrolling the panel: collapse the narration at short heights, or dock the inset elsewhere.

### F6. The pedals are now behind the steering wheel, and the Pedals camera doesn't show them (3D / cabin, medium)
- **Where:** `src/vehicle.js:719–725` (pedals at x 0.12), `:752–767` (seat, steering wheel), `src/main.js:17` (`SHOTS.pedals`)
- **Measured:**
  - The pedal pads are at x 0.13, the steering wheel at x **0.28**, and the seat cushion spans x −0.39…0.09.
  - So the pedals are 15 cm *behind* the steering wheel and 4 cm ahead of the seat's front edge, level with the gearbox's 1st and 2nd gears.
  - In a real car the pedals are about 0.4–0.5 m ahead of the steering wheel.
- **In Chrome:**
  - The **Pedals** camera frames the gearbox, and the pedals sit under the control dock at the bottom-left. They only appeared after I hid the dock.
  - The "Stop cleanly" lesson switches to this camera for "Stopped, then neutral".
- **Fix:**
  - Commit `81cca6e` moved the pedals from x 0.5 back to x 0.12 to keep them out of the clutch. Instead, keep them forward in a footwell at about x 0.5–0.6 and clear the powertrain sideways.
  - Between x 0.5 and 0.6:
    - The bellhousing radius is at most about 0.165 m and the gearbox half-width is 0.17.
    - So the clutch pad's inner edge (z 0.22 − 0.0225 = 0.1975) clears both by at least 2.7 cm.
    - The pad swing (+0.07 in x) stays well clear of the flywheel at x 0.725.
  - Re-aim `SHOTS.pedals` so the pads land above the dock.

### F7. Turning Sound off doesn't silence the road noise (audio, low–medium)
- **Where:** `src/audio.js:65–76`, `:120–135`
- **Problem:**
  - The road-noise layer goes straight to `ctx.destination`, bypassing `master`.
  - `setWanted(false)` only fades `master`, and `update()` returns early when sound is off. So `roadGain` stays at its last value, up to 0.045, and the road noise keeps playing while the car moves.
- **Fix:** route `roadGain` through an output gain that `setWanted` controls, or zero `roadGain` in `setWanted(false)`. Optionally call `ctx.suspend()` when sound is off.

### F8. With the engine off, every gear-change check is skipped (gear rules, low–medium)
- **Where:** `src/sim.js:242–266` (every check is inside `this.alive && …`)
- **Measured:**
  - **1st at 100 km/h.** Stalled at 100 km/h, `requestGear(1)` with the clutch up is accepted. The dead engine is spun to **7,853 rpm**, past the 6,400 redline (the engine is clamped at 820 rad/s while the clutch slips), and the car loses 39 km/h in 2 s.
  - **Reverse at 60 km/h.** Stalled at 60 km/h going forward, `requestGear(-1)` is accepted and does nothing.
- **Fix:**
  - Keep the reverse and over-rev checks regardless of whether the engine is running.
  - Exempt a stopped engine from the clutch check only while the car is stationary. That is the "park it in gear" case: a rolling input shaft still needs the synchro.

### F9. Shifting to neutral is refused with grind and synchro text (gear rules / copy, low)
- **Where:** `src/sim.js:242–247`
- **Measured:** in 3rd at 50 km/h with the clutch up, `requestGear(0)` is refused with "The shift grinds. Push the clutch pedal down so the synchro can match speeds before the sleeve locks the gear." and the grind sound plays.
- **Problem:** taking a car out of gear doesn't involve the synchro, and off the throttle it can be done without the clutch.
- **Fix:**
  - Allow neutral when the throttle is low, or
  - keep requiring the clutch but use accurate copy ("Press the clutch to take it out of gear") with no grind.

### F10. Coasting in neutral with the clutch up says the wheels aren't turning (copy, low)
- **Where:** `src/explain.js:73–77`
- **Measured:** neutral at 50 km/h, clutch up: "Neutral, clutch closed … which is why the wheels do not turn."
- **Fix:** branch on speed the way the clutch-open case at `:59` already does.

### F11. Grammar in the generated copy (copy, low)
- `src/explain.js:33`: "At this speed **5** holds the engine below idle" should read "5th gear" or "gear 5".
- `src/explain.js:81–85`: in reverse the text reads "**Reverse the engine reaches idle** at about 8 km/h". Use "In reverse".
- Add one helper that writes "1st/2nd/…/reverse" for both.

### F12. The clutch readout says "Up" while the pedal is halfway (UI, low)
- **Where:** `src/ui.js:149–153`
- **Measured:** 1st gear, pedal held at 0.5. The plates grip (mode `locked`, 7.4 km/h), so the readout says **"Up"** with the pedal at 50%.
- **Fix:** label the pedal by its position: `Down` at or above `CLUTCH_TOUCH`, `Up` at or below about 0.1, otherwise `Bite`, or "Gripping" when locked.

### F13. The reverse gears turn the wrong way and overlap (3D, low)
- **Where:** `src/vehicle.js:156`, `:419`, `:430–434`
- **Problems:**
  - **Idler direction:** `idler.rotation.x = +counterAngle × 1.33`, the same direction as the countershaft. Two gears in mesh must turn in opposite directions.
  - **Reverse gear direction:**
    - The reverse mainshaft gear uses the forward-gear formula (`−counterAngle × ratio`), as if it meshed with the countershaft directly.
    - Driven through the idler, it should turn the same way as the countershaft. In R, the selected gear therefore spins opposite to its own shaft.
  - **Overlap:** the reverse main gear (r 0.079) and countershaft gear (r 0.04) add up to 0.119 against a 0.11 shaft spacing, so they overlap by 9 mm.
- **Fix:**
  - Idler: `−counterAngle × (rCounter / rIdler)`.
  - Reverse main gear: `+counterAngle × (rCounter / rMain)`.
  - Shrink the pair, for example to rCounter 0.035 and rMain 0.068. That gives (0.068 / 0.035) × 1.615 = 3.14 against 3.16, with a 7 mm gap. Re-place the idler to mesh with both.

### F14. The ring and pinion no longer match `FINAL` (3D, low)
- **Where:** `src/vehicle.js:464`, `:481`
- **Problem:** the ring and pinion are still 47:13 (3.62), but `FINAL` is now 3.9, so the teeth slide past each other. The ring is also still a spur gear with the pinion beside it rather than a bevel gear meshing with it.
- **Fix:** use 43:11 (3.91) or 39:10.

### F15. The clutch labels pile up on each other (UI, low)
- **Where:** `src/vehicle.js:527–535`
- **Problem:** "Plates locked/apart", "Flywheel", "Pressure plate" and "Clutch disc" are placed within about 8 cm of each other. In the Layout, Clutch and Pedals views (screenshots), "Flywheel" and "Pressure plate" are covered.
- **Fix:** spread the anchors in height or sideways, or add short leader lines.

### F16. The steering column and clutch line cross the Clutch camera (3D, low)
- **Where:** `src/vehicle.js:356–364` (hose), `:765–768` (column)
- **Problem:** the hydraulic line loops up to y 0.74 over the gearbox, and with the steering column it crosses the Clutch camera's frame.
- **Fix:** route the line low along the transmission tunnel.

### F17. Small consistency items (low)
- **Displacement:** the engine is drawn with an 80 mm bore × 80 mm stroke × 4 cylinders = **1.6 L**, but the sim uses `DISP = 2.0e-3`. Use about 86 × 86 mm, or set `DISP` to 1.6 L.
- **Driveshaft comment:** `layout.js:7` says the driveshaft "runs at about 3°". It drops 0.12 m over 1.18 m, which is **5.8°**.
- **Dead export:** `STALL_RPM = 520` is still exported but nothing uses it.
- **Shaft overlap:** the input shaft (x 0.31–0.73) overlaps the mainshaft (x −0.07–0.55) for 24 cm on the same axis. A real input shaft ends at its gear, with the mainshaft's pilot inside it.

### F18. Keyboard users can't release the clutch slowly (input, low)
- **Where:** `src/main.js:183`
- **Problem:** holding C sets the clutch to 1, and letting go snaps it straight back. With the new physics, any release faster than 0.6 s stalls from a standstill. So a keyboard-only user can never pull away with C, only by focusing the slider and stepping it 5% at a time.
- **Fix:** limit how fast the keyboard clutch can rise, in real time (for example a full release over about 1.2 s), on the input side. The sim stays sample-and-hold.

---

## 4. Suggested order
1. **F1 + F2** together (idle reserve, engine-braking and lugging text), plus a test that 5th at 20 km/h stalls.
2. **F3** with the tested timeline above.
3. **F4 + F5**: make the clutch parts touch, and fix the inset's lighting, contents and placement.
4. **F6**: footwell position and Pedals camera.
5. **F7–F12**: audio mute, gear-change checks with the engine off, neutral copy, coasting copy, grammar, pedal readout.
6. **F13–F18**: reverse gears, ring and pinion, labels, cable routing, consistency, keyboard clutch.

## 5. Tests to add
- 5th at 20 km/h with the throttle closed and the clutch up stalls with `stallReason === 'gear'` (F1).
- The engine-braking text appears only when `flow < 0` (F2).
- Pull away: the mode is `slipping` during the "Find the bite" step, and the revs before the bite land between 1,000 and 1,300 (F3).
- With the engine stopped and rolling above 5 km/h, `requestGear(-1)` and a shift past the redline are refused (F8).
- Coasting in neutral above 10 km/h never shows "wheels do not turn" (F10).
