Add the perf governor (ease motion, never blur) and gate 60fps on the reference laptop

[kateebonner]

Important

Problem

The Chat's expensive combination — high-radius backdrop-blur recomputed per frame across many glass cards over an animating Brain, while scrolling — can blow the 60fps budget on a real laptop webview (see #56 for the why). This slice builds the pre-agreed release valve and proves the budget actually holds on real hardware.

Approach

Add a frame-time governor that observes the single Brain render loop and, only under sustained over-budget load, eases the Brain's motion stepwise (dual-guard hysteresis before restoring, so it never oscillates) down to a full motion stop, then — if that still misses budget — hard-pauses to a static blurred field as the terminal valve. It never touches blur or tint: motion is the only give. The release criterion is a manual 60fps sign-off on the pinned reference laptop webview; a headless-Chromium rAF-interval trace is a pre-gate proxy only. HITL because only a human on the reference machine can close the gate.

Scope

In: the frame-time monitor + motion-ease governor (trip, ease ladder, hysteresis restore, terminal hard-pause); the paused-loop measurement guard (no phantom over-budget when the engine is paused); the blur/tint-never-degraded invariant; a dev force-full-tempo hook (pins full tempo AND disables the governor); a headless-Chromium rAF-trace proxy harness over a long-thread fixture, both themes; the manual perf-gate checklist + sign-off on the reference laptop, both themes.
Out: reducing blur radius or tint under load (the frosted look is the protected aesthetic; motion is the only give); dynamic per-frame backdrop sampling / adaptive-contrast glass (rejected in #56 as the biggest perf risk); the glass tokens and the motion engine themselves (owned by the glassed-components and full-motion slices; this slice only steers and protects them); node-cap / recency bounds and occluded-Panel paint-skipping (separate perf levers on the motion slice, not the release valve); any automated or CI substitute for the reference-laptop run (the gate is a deliberate manual sign-off).

---

Acceptance Criteria

• Trip + ease ladder: fed a frame-time sequence whose rolling p95 exceeds the 16.7ms budget continuously for a full sustained trip window, the governor steps the Brain's motion down one ease level (lower tempo); continued over-budget steps it further, down to a full motion stop. Below-budget input never triggers a step-down.
• Terminal valve: with motion already at a full stop and p95 still over budget for the sustained window, the governor hard-pauses the render loop to a static blurred field; it never steps past full-stop into any state that keeps painting motion.
• Hysteresis / no oscillation: on a frame sequence that hovers at the budget boundary (alternating just-over / just-under across windows), the governor does not change motion level every window; restoring one level up requires p95 to stay at or below the restore threshold (a fixed margin below budget) for the full, longer restore window. A single under-budget window never restores.
• Blur/tint invariant: across every governor action (ease, full-stop, hard-pause, restore), the glass blur-radius and tint-opacity tokens are byte-identical before and after; the governor exposes no path that writes a glass token.
• Rest = full fidelity: when the frame budget is being met and the engine reports at-rest/breathing, the governor holds motion at full tempo and never pre-emptively eases; full blur + full motion always apply at rest.
• Paused-loop inertness (no phantom over-budget): while the engine reports paused (window hidden, off-screen, or prefers-reduced-motion), the governor pauses its own measurement and discards the stalled inter-frame gaps, so a long paused stretch followed by resume never trips a step-down or the terminal hard-pause. Fed multi-second frame gaps tagged paused, the emitted motion level and the engine's pause state are unchanged.
• Force-full-tempo hook: enabling the dev hook pins the Brain at full tempo and disables the governor (so a gated run measures the un-eased worst case); disabling it restores normal governed behavior.
• Headless proxy harness: a headless-Chromium script loads the app with the force hook, scrolls a >=40-card thread continuously for >=10s in each theme, and emits a report of p95 and max frame time; the report is labeled a pre-gate proxy and its pass does not close the release gate.
• Perf gate (manual sign-off): on the reference laptop VS Code webview (battery-powered, pinned before the run), a >=10s continuous scroll of a >=40-card thread at full Brain tempo yields p95 <=16.7ms with zero frames >33ms, in both themes; recorded as a signed-off checklist artifact on the PR before merge.

Testing Decisions

• CREATE brain-perf-governor unit tests: drive the governor through an injected clock / frame-time source (external behavior = the emitted motion level and the engine's pause state, given frame times in). Cover: step-down ladder to full-stop on sustained over-budget; terminal hard-pause once motion is at full-stop and still over budget; hysteresis on a boundary-hovering sequence (assert no per-window flipping and that restore needs the full longer clear window below the restore threshold); the blur/tint invariant (snapshot the glass tokens before/after a full trip+restore cycle and assert equality); rest-inertness (below-budget + at-rest never eases); paused-loop inertness (feed multi-second gaps tagged paused and assert the motion level and pause state are unchanged — a stalled loop never registers a phantom over-budget frame or trips the fallback). No real rAF or wall clock — feed synthetic frame times.
• EXTEND the full-motion slice's engine motion tests ("extends slice 4 test surface"): assert the governor steers the same single tempo control slice 4 exposes and adds no second render loop or second frame-time clock — reuse its tick()/tempo assertions rather than re-deriving tempo behavior.
• CREATE a headless perf-trace smoke test: assert the harness boots the app with the force-full-tempo hook, scrolls the >=40-card fixture for >=10s in each theme, and produces a p95 + max-frame-time report object. This asserts the harness runs and reports — it is the pre-gate proxy, not the gate.
• Manual gate is not an automated test: it is a documented checklist executed on the reference laptop and signed off on the PR (this is why the slice is HITL). No test asserts the gate's numeric outcome in CI.

Key Decisions

• Budget + red line: p95 target = 16.7ms (one 60fps frame); the hard per-frame red line = 33ms (any single frame over this is a dropped frame and fails the gate).
• Trip condition: p95 over a rolling ~2s frame window exceeds 16.7ms continuously for a sustained ~2s trip window, then step down one ease level. Ease ladder: full tempo -> eased/calm (stepping down the tempo ladder toward its slowest) -> motion full-stop -> [terminal] hard-pause to a static blurred field.
• Hysteresis (dual-guard): restoring one level up requires BOTH a longer clear window (~2x the trip window) AND p95 at or below a restore threshold set a fixed margin below budget (~13ms), not merely below 16.7ms. Restoration is one level per clear window, never a jump straight back to full.
• Terminal valve = the engine's existing hard-pause (rAF stop), leaving the last high-blur frame as a static field; it is the only step past motion-full-stop, and only the return to a met budget (per hysteresis) resumes the loop.
• Governor levers, bounded: the governor's ONLY levers are the motion tempo control (from the full-motion slice) and the terminal hard-pause. It has no access to glass blur/tint tokens by construction.
• Paused-loop guard: the governor reads the engine's paused state and pauses its own measurement while paused (hidden / off-screen / prefers-reduced-motion), discarding the stalled inter-frame gaps so resume never false-trips the fallback.
• Force-full-tempo hook pins full tempo AND disables the governor, so the gate and the headless proxy both measure the un-eased worst case; if that passes on the reference laptop, the governor is a rarely-tripped safety net.
• Gate parameters (fixed): reference laptop VS Code webview, battery-powered and pinned before the run, >=40-card thread, >=10s continuous scroll, full Brain tempo, both themes, manual sign-off recorded on the PR. Headless Chromium is a proxy only and never substitutes for the sign-off.
• Data contract — governor input: a stream of per-frame durations (ms) plus the engine's current at-rest/active and paused state; output: a discrete motion level in {full, eased-N..., full-stop, hard-paused}. It reads frame times only from the existing loop; it does not run its own painting clock.

Constraints & Invariants

• The fallback MUST NOT reduce blur radius or tint opacity — ever, at any level (easing, full-stop, hard-pause, or restoring). Blur fidelity is non-negotiable; the frosted look is the protected aesthetic.
• Motion is the only give; the ease is discrete-stepwise, never a continuous flicker, and the dual-guard hysteresis must prevent per-window oscillation.
• The governor is inert at rest: full blur + full motion always apply when the budget is met; it must never pre-emptively ease.
• The headless-Chromium trace is a proxy and MUST NOT be recorded or presented as satisfying the release gate; only manual sign-off on the pinned reference laptop closes it.
• One render loop only: the governor observes and steers the existing single rAF loop — it must not spawn a second render loop or a second frame-time clock that itself burns frames.
• The governor must pause its own measurement whenever the engine is paused (window hidden, off-screen, or prefers-reduced-motion), so a stalled loop never registers phantom over-budget frames and false-trips the fallback.
• Amicode design-system law applies to any dev/gate affordance chrome; browser-first iteration (vite dev on the app), not VSIX rebuilds; npm run lint clean + app typecheck before the PR.

Prior Art / Patterns

- The old branch's `?brainForceActive` URL param in `brain-atmosphere.tsx` pins the brain at full musical tempo for perf capture — reuse/rename it as the force-full-tempo hook, and extend it to also disable the governor. - The Brain engine's existing hard-pause is the terminal valve: `pause()`/`resume()` in the current `brain-engine.ts` (and `suspend()`/`resume()` in the old-branch `engine.ts`), driving the single rAF loop. - The `TEMPI` tempo ladder (largo -> presto) and the full-motion slice's `setActive` adaptive heartbeat (the old-branch `setActive`) are the motion lever the governor eases — "extends slice 4 test surface." - `glass-tokens.ts` (`GlassTier.blur` / `alpha`) and `glass.css` (`--glass-*-blur` / `-bg`) hold the blur+tint the invariant protects — the governor must never write them. - #56's "Pre-agreed perf fallback" and ADR 0002 set the law: motion is the give, blur fidelity never degrades, the laptop-webview 60fps gate is the real target and headless Chromium is only a proxy.

Source

Part of #56. Durable record: ADR packages/app/docs/adr/0002-brain-as-chat-background.md.
Blocked by #61
Blocked by #62

[kateebonner]

Code merged into the integration branch (PR #64): governor (ease ladder → terminal hard-pause, hysteresis, blur/tint invariant test-pinned), DEV ?brainForceActive hook, and the headless perf-trace proxy. All engine + app suites green.

Left open deliberately — the remaining acceptance criterion is the hitl reference-laptop 60fps sign-off; the exact procedure + checklist is posted on PR #64. Headless dev-mode proxy (pre-gate evidence only): dark p95 25.4ms / light 25.2ms, mean ≈16.3ms — tail over budget, so the governor valve matters; the real webview call is the human gate.

🤖 Generated with Claude Code