Re-architect scene runtime: single imperative control plane, retire the master timeline

[Brad-Edwards]

Summary

Replace the GSAP-master-timeline runtime with a single imperative control plane, and keep the L2 scene library (system/chrome + system/templates + system/helpers) as-is. The runtime over-committed to a "master timeline sequences scenes" metaphor, but the real cinematic scenes are presenter-driven imperative loops that bypass the timeline and bolt a pause-gate onto it. That mismatch is the structural source of the recurring deck bugs (stranded async loops, audio bleed, lingering DOM on advance).

This is the next step of the rearchitect/scene-runtime work.

Diagnosis (root cause)

The premise (ADR 003) is timeline-driven presentations with a GSAP master timeline as the spine that sequences scenes. But the signature scenes — cold-open, the calgary deck, every real demo deck — are presenter-driven imperative loops (while (!advance) { beat; await sleep; }). The runtime welds the two models together in src/system/templates/presenter-driven.ts:

• create() arms an abort flag but does not run the body
• timeline() returns a GSAP timeline whose real job is a tl.call() that kicks off the body fire-and-forget, off the timeline tick; the body paces itself with aSleep({ controller }) against a separate PresenterController
• an addAdvanceGate label is reverse-engineered by composeMasterTimeline into a master addPause
• cleanup() flips signal.aborted, which the body must poll between every beat by hand

Net: the scenes that matter bypass timeline.ts (935 LOC) + composition-resolver.ts (753) + scene-loader.ts (840) and run an imperative loop beside them. We pay for the timeline engine and the scenes fight it.

Why this produces "a shit ton of bugs"

Every presenter-driven scene runs against three independent clocks that must agree, by hand:

1. the GSAP master timeline (pause gates, segment spacers, '>' positioning)
2. the fire-and-forget async body (wall-clock aSleep)
3. howler audio (its own clock)

In src/decks/local-calgary-v2/scenes/cold-open.ts the author hand-polls if (signal.aborted) return on every beat, hand-threads { controller } into every aSleep, and hand-writes a try/finally to fade audio and wipe chrome. Miss one poll → stranded loop / audio bleed / lingering DOM. The runtime promised to own lifecycle and delegated the hard part — deterministic teardown and abort — back to every scene author.

demo_thoughts decks "just work" (modulo copy-paste) because they have one clock.

Secondary overbuild

• src/runtime/audio.ts is 1,400 LOC wrapping howler (own error taxonomy, cue gates, 3 output policies, bed declarations, sprite tuples) — engine serving the engine.
• 6 workbench modes (present / loop / scrub / screenshot / paused / standalone); scrub/screenshot are structurally incompatible with a setTimeout-driven body and drive much of the L1 weight.
• 1,713 tests / ~48k LOC, all green while decks are buggy — they test internal contracts in happy-dom, not rendered behavior or cross-clock sync. False confidence plus a refactor anchor.

What's good and stays

The L2 layer earns its place. Cold-open is 234 LOC vs 643 in vanilla and reads as beats + animations, not DOM plumbing. Keep:

• src/system/chrome, src/system/templates, src/system/helpers — the actual anti-copy-paste asset
• the deck content + CSS already authored
• the SceneModule contract (src/runtime/scene.ts) and the composition-manifest idea (an ordered scene list — index.ts already is one)

Scope

Build

• A single imperative control plane: a scene is an async function receiving { chrome, audio, sleep, signal, gsap } where one controller owns sleep / pause / resume / abort.
• Automatic teardown: a disposal registry the runtime owns, so scenes stop hand-writing try/finally and abort-polling. Advance/navigate-away tears down deterministically: stop timers, abort in-flight animations, fade+stop scene audio, wipe chrome.
• Sequencing as a plain loop: run scene → await advance → run next. GSAP stays as a per-scene animation tool the scene calls, not the master spine.

Burn / collapse

• The dual execution model and the master-timeline-as-spine (composeMasterTimeline, advance-gate hack).
• Most of composition-resolver.ts + scene-loader.ts → small run-loop.
• audio.ts mega-wrapper → thin "play a bed, fade on scene exit" tied to the same controller.
• Speculative modes (loop / scrub / screenshot / standalone) until a real need exists; keep present + prompter.
• The tests that lock in the deleted layer.

Acceptance criteria

• A scene is authored as one async function with one control plane; no scene hand-polls an abort flag or hand-threads a controller into sleeps.
• Advance / navigate-away deterministically tears down the outgoing scene: no stranded async loop, no audio bleed into the next scene, no lingering chrome/DOM — verified by tests that assert post-advance state, not internal contracts.
• local-calgary-v2 runs end-to-end through the new runtime, reproducing the demo_thoughts calgary deck beats, without the per-scene defensive boilerplate.
• GSAP is used only within scenes; no master timeline sequences scenes.
• audio.ts reduced to the thin bed/cue surface the decks actually use.
• L2 library (system/chrome, system/templates, system/helpers) preserved; scene authoring stays at or below current LOC.
• Dead L1 modules and their tests removed; remaining suite is green and exercises rendered/teardown behavior.
• ADRs updated to reflect single-control-plane model (supersede/amend ADR 003 and the timeline/mode ADRs).

Out of scope

• Reintroducing scrub/screenshot/loop modes (separate follow-up if ever needed).
• New deck content.

Risk

• Touches the L1 runtime broadly. Mitigated by keeping the L2 library and scene contract stable as the seam, and migrating local-calgary-v2 as the proof.

[Brad-Edwards]

🛠️ Picked up by /implement — driver Claude Code, working directly on rearchitect/scene-runtime (no sub-PR / no CI-PR cycle, per maintainer direction), 2026-06-07T00:09:54Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #162). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: context_loaded (issue #162). Posted by the MCP server after re-verifying the bound workflow state. Do not edit or delete — downstream tools use this marker and binding to detect stale results.

Implementation context loaded server-side.

• Requirements: (none)
• Binding ADRs: ADR-031, ADR-036, ADR-061, ADR-062
• Existing IMPLEMENTS artifacts: 0

[Brad-Edwards]

gc workflow phase recorded: contract (issue #162). Posted by the MCP server after re-verifying the bound workflow state. Do not edit or delete — downstream tools use this marker and binding to detect stale results.

Interface Contract — single imperative scene control plane

Binding design: ADR-032 + docs/design/issue-162-single-control-plane-preflight.md. This contract is the oracle for the plan, tests, and review. It is language-/shape-level, not an implementation.

Diagnosis correction (accurate scope)

The issue body framed this as "the real scenes are presenter-driven loops that bypass the timeline." Verified against the tree, that is only 2 of ~26 scene shapes (cold-open, ransom). The other ~24 are fixed-duration GSAP-timeline template scenes built through src/system/templates/_shared.ts (buildTemplateTimeline/buildTemplateScene) that use the master timeline as intended. So this is not "delete an unused layer" — it is:

• replace runtime master sequencing (composeMasterTimeline, advance-gate→addPause) with a plain ordered run-loop, and
• migrate per-scene GSAP animation from timeline(ctx) into the scene's async body (still GSAP, still per-scene, just owned by the scene/L2 helper, not composed into a master).

SceneModule and composition manifests stay the registry/validation boundary throughout.

Public seam being changed

1. Scene execution context (WorkbenchSceneCtx extension). The control plane passes scenes a bounded context with already-abort-bound primitives:
   • ctx.sleep(ms): Promise<void> — abort-bound dwell. Rejects/resolves-cancelled on activation supersession. Replaces aSleep(ms, { controller }).
   • ctx.waitForAdvance(): Promise<void> — abort-bound wait for presenter advance. Replaces holdUntilAdvance(controller) / the master addPause gate.
   • ctx.signal: AbortSignal — fires on navigation supersession/dispose (NOT pause). Scenes may pass it to async work; they do not poll it between beats.
   • ctx.dispose(fn) / disposal registration — register timers, intervals, listeners, GSAP tweens/timelines, audio handles, and arbitrary teardown callbacks; the control plane runs them on scene exit.
   • existing passthroughs stay: ctx.chrome, ctx.audio, ctx.gsap, ctx.stage, ctx.rng, ctx.activation, presenter info.
2. Scene body shape. A scene is an async (ctx) => void that returns when the scene is done OR is cancelled. No void run() fire-and-forget, no hand-threaded controller, no per-beat signal.aborted polling, no per-scene try/finally for runtime-owned resources.
3. Composition run-loop (replaces composeMasterTimeline sequencing). Ordered over the manifest slice: resolve+validate target (existing navigation/resolver) → preload declared assets (existing preloader) → activate one scene → await body completion OR presenter advance → tear down the activation deterministically → next. No master timeline, no addPause, no advance-gate labels.
4. Disposal registry (SceneActivation-scoped). Concrete, not a plugin framework: owns timers, intervals, listeners, GSAP animations, audio groups/handles, chrome-slot wipes, explicit disposables. Deterministic teardown on scene exit and on supersession. Repeated scene ids get distinct activation ownership (no cross-activation collision on DOM/audio/rng/disposal).
5. L2 authoring adapter. A single helper turns an async body into a valid SceneModule (the replacement for today's presenterDrivenScene bolt-on). presenterDrivenScene becomes a thin compatibility bridge to it or is replaced by an equivalent. No second scene schema, no ImperativeSceneModule, no parallel registry.
6. Template scenes. buildTemplateScene/buildTemplateTimeline refactor so their per-scene GSAP runs inside the async body (build timeline → await its completion via the control plane, with the tween registered for disposal). The ~24 template factories keep their authoring surface; ideally they change only through _shared.ts.
7. Audio service (slimmed). Scene-facing surface reduced to the deck-used set: load/play/fade/stop scene cues + beds, mute/unlock, source validated through asset policy. The control plane performs final fade/stop/unload on scene exit — scenes no longer call fadeAndStop in finally. AudioService, stopGroup, stopAll, AudioError, createHowlerAudioEngine, noopAudioEngine, and the scene.audio ⊆ scene.assets invariant remain.
8. Modes. Active runtime modes are present and prompter only. standalone/loop/paused/scrub/screenshot/rehearsal are removed from NAVIGATION_MODES, mode validation, mode-profile, docs, tests, and chrome/audio policy — together.

What stays stable (compatibility promise)

SceneModule / defineScene / assertSceneModule / sceneDeclaresAudio; CompositionManifest / assertCompositionManifest / registries; parseNavigationSearch / validateBeatGrammar / validateModeGrammar / effectiveMode / resolveSceneNavigation; validateRuntime / assertNoValidationFindings (single validator — no second graph validator); SceneActivation / SceneFailureEvent / describeError(Detailed) / formatSceneContext / onError isolation + aggregate-error semantics; PRESENTER_COMMAND_KINDS / isPresenterCommand / PresenterController / createPresenterController; asset policy (resolveAssetUrl, createAssetPreloader, DEFAULT_ALLOWED_SCHEMES, post-redirect re-check); chrome L2 (mountChromeSlots, createDomWorkbenchChrome, slots) — chrome root persists across scenes; scene exit wipes slots only.

ADR-059 engineering-contract acceptance criteria

• Interface-first. Changed seam: scene execution context + run-loop + disposal + slimmed audio + mode set (above). Stable: SceneModule, manifests, navigation parser, validation, asset policy, presenter command validation, chrome ownership.
• Whole-system fit. Builds on every incumbent named in the preflight "Required Reuse" list; no new validator/registry/schema/exception hierarchy/command bus.
• Right-sized simplicity. One control plane, one clock, one disposal owner. The disposal registry is a concrete resource list, not a generic lifecycle framework. Mode removal deletes code rather than adding policy.
• Defensive coding (in contract). Handled: navigation supersession mid-beat; advance mid-beat; partial create() that allocated before throwing; throwing cleanup; fadeAndStop post-fade timer firing after dispose; helper-level async (typeInto, topology/interval loops, staggered effects) outliving the scene; repeated scene ids. Out of contract: untrusted/sandboxed scenes (scenes remain trusted repo code per docs/scene-trust-model.md); reintroducing removed modes.
• Test strength (rendered, not internal). Each obligation is proven by a rendered/teardown assertion: post-advance there is no outgoing scene DOM in chrome slots, no scene-registered live timer/interval/listener, no scene audio still registered/playing, no stale async body mutating the next scene; chrome root survives; repeated-id activations don't collide. Tests asserting deleted master-timeline internals are removed, not carried as anchors.
• Secure from the gate. Asset/audio sources stay within scene.assets/scene.audio + resolveAssetUrl (no audioSrc/play(url)/out-of-policy beds). Present-mode audio unlock stays at the loader/workbench boundary. Presenter commands pass isPresenterCommand. Error envelopes carry ids/phase/mode/composition-index/bounded messages only — never raw scene objects, DOM, captions, GSAP timelines, Howler handles, env, cookies, headers, stacks, or raw cause. No control-plane state in URL/history/storage/env/files. Widen source-policy scan scope to src/decks/**/scenes/**.
• Architectural conformance. ADR-032 (this change) supersedes the master-timeline portions of ADR-003/011/015/016–021/023/024/025/026; ADR-001/002/008/012/013/014/028/029/031 remain binding.
• Extensibility seam. The single seam is the SceneActivation-scoped control plane at the loader boundary. Future audio buses/ducking → AudioService capabilities; richer presenter controls → new PresenterCommand.kind; inspection/export/mode reintroduction → explicit control-plane run policies chosen at the loader, never a master timeline or scene-local mode branches.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #162). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan — single imperative scene control plane

Oracle: the posted interface contract + ADR-032 + docs/design/issue-162-single-control-plane-preflight.md. Delivered as ordered increments, each independently green and committed directly to rearchitect/scene-runtime (maintainer chose direct-on-branch, no sub-PR). TDD per increment: rendered/teardown tests first.

Scope correction baked in

Verified: only 2 of ~26 scene shapes are presenter-driven (cold-open, ransom); ~24 are fixed-duration GSAP-timeline template scenes via _shared.ts that use the master timeline as intended. So this replaces runtime master sequencing and migrates per-scene GSAP into the async body — it does not delete per-scene animation. SceneModule + manifests stay the boundary.

Increments

1 — Control-plane core. New src/runtime/scene-activation-controller.ts (name TBD): activation-scoped controller owning sleep(ms), waitForAdvance(), signal (supersession AbortSignal), pause/resume, and a concrete disposal registry (timers, intervals, listeners, GSAP tweens/timelines, audio handles, chrome-slot wipes, explicit disposables). Deterministic teardown; repeated scene ids get isolated ownership keyed on SceneActivation.

• Tests first: sleep resolves-cancelled on abort and never fires its timer after dispose; waitForAdvance resolves on presenter advance and on abort; disposal runs every registered resource exactly once, in LIFO, even when one disposer throws (aggregate-error, reusing describeError); a registered interval/timer does not fire post-dispose.
• Criteria: "single control plane", "automatic teardown".

2 — Composition run-loop. New loop replacing composeMasterTimeline sequencing in the loader path: resolve+validate target (resolveSceneNavigation) → preload (createAssetPreloader) → activate one scene with a fresh controller → await body completion OR waitForAdvance → tear down → next. Reuses validateRuntime, navigation parser, SceneActivation, onError/aggregate isolation. No addPause, no advance-gate labels.

• Tests first: ordered advance through a 3-scene manifest; advance mid-beat supersedes and tears down the outgoing scene (no leftover DOM/timer/audio); a throwing scene body is isolated via onError and the loop proceeds; chrome root persists across scenes, slots wiped between.
• Criteria: "advance/navigate-away deterministic teardown", "no master timeline sequences scenes".

3 — Async-body authoring adapter + presenter-driven migration. One L2 helper adapting async (ctx) => void into a valid SceneModule (no second schema/registry). Rewrite presenterDrivenScene as a thin bridge to it (drop the tl.call kickoff, addAdvanceGate, fire-and-forget body, active.signal polling). Migrate cold-open.ts and ransom.ts to ctx.sleep/ctx.waitForAdvance/ctx.dispose — delete their hand-rolled signal.aborted polls, { controller } threading, and try/finally audio/chrome cleanup.

• Tests first: a presenter-driven scene's typing/topology/interval async is all torn down on advance (no stranded loop mutating next scene); audio bed faded+stopped by the control plane on exit (no bleed).
• Criteria: "one async function, no hand-poll/thread", "local-calgary-v2 without defensive boilerplate".

4 — Template-scene migration. Refactor _shared.ts buildTemplateScene/buildTemplateTimeline so per-scene GSAP builds inside the async body and awaits completion (tween registered for disposal) instead of contributing a master segment. The ~24 template factories keep their authoring surface; changes concentrate in _shared.ts.

• Tests first: a fixed-duration template scene runs to completion and auto-advances; its GSAP tween is disposed on exit; existing per-template behavior (chat transcript, metric ticker, terminal, etc.) preserved via rendered assertions.
• Criteria: "GSAP only inside scenes", "L2 preserved, scene LOC ≤ current".

5 — Audio slim. Reduce src/runtime/audio.ts scene-facing surface to load/play/fade/stop bed+cue + mute/unlock; control plane owns final fade/stop/unload on scene exit (fix the fadeAndStop post-fade setTimeout so it cannot fire after dispose — move the timer behind the service or register it). Keep AudioService/stopGroup/stopAll/AudioError/engines and the scene.audio ⊆ scene.assets invariant; no second audio inventory.

• Tests first: fade-and-stop timer is cancelled on dispose; supersession stops all navigation audio; unlock gate stays at loader boundary.
• Criteria: "audio.ts reduced to thin surface".

6 — Mode removal. Drop standalone/loop/paused/scrub/screenshot/rehearsal from NAVIGATION_MODES, validateModeGrammar, mode-profile, runtime dispatch, chrome/audio policy, docs, and delete their Playwright specs + Vitest mode suites together. Keep present + prompter.

• Tests first: navigation grammar accepts only present/prompter; removed mode tokens are rejected through the existing error surface.
• Criteria: "dead L1 modules + tests removed".

7 — Delete dead L1. Remove composeMasterTimeline, master-timeline transport, advance-gate machinery in timeline.ts, and the master-sequencing portions of composition-resolver.ts/scene-loader.ts. Remove tests that assert the deleted internals (do not carry as anchors). Net: no master timeline anywhere; pnpm policy source-policy scope widened to src/decks/**/scenes/**.

• Criteria: "dead L1 removed; suite green on rendered/teardown behavior".

8 — Proof + docs. local-calgary-v2 end-to-end through the new runtime (manual + a rendered integration test). ADR-032 already written by preflight; update docs/adrs/README.md/docs/design/README.md indices (done by preflight) and add a changelog fragment: changelog.d/162.changed.md (control-plane runtime + scene authoring) and changelog.d/162.removed.md (speculative modes). The PUL-Q001 screenshot-determinism plan-rule is moot under ADR-032 (screenshot mode removed); note it in the fragment.

• Criteria: "local-calgary-v2 end-to-end", "ADRs updated".

Cross-cutting (every increment)

Security/validation/error-envelope/asset-policy/presenter-command rules per the contract's "Secure from the gate" — verified in the increment that touches each surface. No requirement status transitions (none in scope). Completion gate per increment: pnpm lint && pnpm typecheck && pnpm test.

Risk

Large L1 blast radius. Mitigated by: keeping SceneModule/manifests/navigation/validation/asset-policy/presenter-command/chrome boundaries stable; building the new control plane (1–2) before deleting the old (7); migrating local-calgary-v2 as the executable proof; rendered/teardown tests as the regression net rather than the deleted internal-contract tests.

[Brad-Edwards]

Spike result (ADR-032) — verdict: KEEP L2, rewrite L1

Built the single imperative control plane (src/runtime/spike/control-plane.ts, committed 9a460fd) and ported the hardest real scenes (cold-open + a template placard) onto it.

Nav works — real-browser proof: cold-open (title slam + live topology beat) → ArrowRight → placard ("Northvane Energy"), full CSS / real GSAP / keyboard, zero runtime errors (only favicon 404s).

L2 churn = zero edits to existing L2 files. The cold-open port reused every chrome effect, typing/audio helper, template-mount call, and all deck CSS/data unchanged. Only the scene's own lifecycle glue changed:

• aSleep(ms,{controller,signal}) → ctx.sleep(ms)
• while(!signal.aborted) + per-beat polling → while(true)
• fire-and-forget void(async…) → ctx.spawn(…)
• try/finally{fadeAndStop;clear*} → ctx.dispose(…) + runtime-owned chrome reset
• presenterDrivenScene(...) wrapper → plain { id, run }

Cancellation model: by-throw — ctx.sleep/ctx.hold/ctx.runTimeline reject SceneCancelled on advance/supersession; the body unwinds itself and the runtime tears down (disposers LIFO + chrome reset). No abort-polling, no try/finally in scenes.

Codex's flip-to-nuke condition (porting forces rewriting most of L2's DOM/CSS) was not triggered.

Gates: 1719 tests + 1035 policy green; typecheck + lint clean.

Churn items for the full migration (small, identified):

1. system/templates/_shared.ts: drop addAdvanceGate + return-to-master; play + await the timeline instead. ~24 template factories ride on it unchanged.
2. End-bind chrome effects that schedule raw setTimeout (e.g. flickerOutAll) so their timers can't outlive the scene.
3. Delete master-timeline glue: presenter-driven.ts, addAdvanceGate, chrome/scrub.ts, system/transitions/*.

The deck-coupled ports + browser entry are local-only (import the gitignored local-calgary-v2 deck); the committed artifact is the control plane + a self-contained mechanics test.

[Brad-Edwards]

Full re-architecture complete — live app runs on the imperative control plane

The master timeline is gone; the runtime is the run-loop end to end.

Shipped (commits 9a460fd → c398189 on rearchitect/scene-runtime):

• present-loader.ts boots present/prompter through runSceneModules (resolve → preload → create → play the scene's own GSAP timeline standalone → hold for advance → cleanup → next). main.ts wired to it; no master-timeline adapter, transition overlay, or scrub transport.
• Deleted the dead L1: composition-resolver, scene-loader, presenter-transport, the master-timeline machinery in timeline.ts (composeMasterTimeline / MasterTimeline / advance gates), chrome/scrub, system/transitions.
• Removed the speculative modes (standalone/loop/paused/scrub/screenshot/rehearsal): navigation grammar + mode-profile trimmed to present/prompter; mode fixtures + their unit/e2e tests deleted.
• Template envelope (_shared.ts) drops the advance-gate + deactivate-on-complete; onDeactivate teardown moved into each scene's cleanup; flickerOutAll end-bound (stop handle / AbortSignal). WorkbenchSceneCtx moved to scene-ctx.ts. Changelog fragments added.
• Net −20k LOC (39 files deleted).

Verification (independently re-run):

• typecheck clean · lint clean (180 files) · 1106 unit tests pass · 1017 policy tests pass.
• Browser: ?composition=pulsar-intro navigates pi-title → pi-thesis → pi-scene via ArrowRight, one scene mounted at a time, zero console errors.

The acceptance criteria are met: one async control plane, runtime-owned teardown (no per-scene abort-polling / try-finally), GSAP only inside scenes, dead L1 + its tests removed, suite green.