docs: Spec D — engine deeper abstractions (FrameContext, Pass, selectionSubsystem, isEngineReady)

[rulkens]

Summary

Spec D, the design follow-on to Specs A/B/C. Specs A → B → C cut engine.ts from 2377 to 1129 lines (52%) and gave every file a logical folder; what's left mangled is the abstractions still missing inside the relocated files. This spec proposes four small, independently-mergeable migrations that fix those gaps:

• D.1 FrameContext — derive the per-frame snapshot once, consume in both runFrame and renderFrame. Eliminates the duplicated drawPxPerRad / drawCamPos derivation and replaces the 5-way "is engine ready?" null-check with a single discriminated narrowing.
• D.2 Pass abstraction — formalise each draw block in renderFrame.ts as a Pass (name, enabled, draw); renderFrame becomes a for (const p of PASSES) loop over 4 HDR passes plus an inlined tone-map post-process. Each pass becomes a one-file unit under engine/frame/passes/.
• D.3 selectionSubsystem — extract the hover/select cluster from engine.ts into a sibling of tweenManager / thumbnailSubsystem.
• D.4 isEngineReady predicate — one TypeScript discriminated narrowing for "post-bootstrap" checks; replaces 7+ scattered re-spellings of the same probe.

Targets after all four PRs land: engine.ts ≤ 1000 lines, runFrame.ts ≤ 250, renderFrame.ts ≤ 150 plus 5–6 new pass files, all 931+ tests green.

Test plan

This is a design spec only — no source changes. Implementation lands as four follow-up PRs, each with at least one regression test for the contract being introduced (full test plan in the spec's Testing section).

• Reviewer reads the spec and confirms the four migrations are independently mergeable
• Reviewer sanity-checks the discovery-checklist tallies (15 selection-related references in engine.ts; 13 distinct readiness-check sites across 5 files; 22 closure-snapshot references in runFrame.ts)
• Implementation PRs land in order D.1 → D.2 → D.3 → D.4, each independently green

This PR can merge before the impl PRs (so they can reference it) or after (so the spec only lands when the work is done) — at the user's discretion.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	skymap	a7e2d8b	Commit Preview URL Branch Preview URL	May 08 2026, 02:03 AM