Phase 5: bootstrap IIFE → ordered phases

[rulkens]

Summary

Phase 5 of the engine internal restructure (Spec B). Lifts the
~1100-line async bootstrap IIFE out of engine.ts into 5 ordered
phase modules under src/services/engine/phases/:

• phases/initGpu.ts — GPU device + every renderer (point, pick,
  milky-way, filament, quad, disk, procedural-disk) + post-process +
  the 5 point-source asset slots from the registry.
• phases/wireSlots.ts — sidecar slots (filaments, famous-meta,
  pgc-aliases), load-progress emitter, thumbnail subsystem, parallel
  multi-survey load with synthetic fallback.
• phases/wireInput.ts — pick renderer, camera + bbox auto-framing,
  orbit controls + click handlers, input bindings, ready-status
  callback, settings-callback fan-out.
• phases/startLoop.ts — RunFrameDeps assembly, frameRef.current
  assignment, first scheduler.requestRender().
• phases/bootstrap.ts — orchestrator (runBootstrapPhases),
  BootstrapDeps shape, shared Phase signature.

The IIFE in engine.ts collapses to:

(async () => {
  try {
    await runBootstrapPhases(state, bootstrapDeps);
  } catch (err) {
    cb.onStatusChange({ kind: 'error', message: ... });
  }
})();

engine.ts goes from 1880 → 1121 lines (-759, ~40%). No
behavioural change — phase content is lifted verbatim; only closure
references rewritten as state.* / deps.*. Mutable closure
captures (frame, detachControls, handle) flow through {current}
ref boxes (same pattern Phase 3 introduced for lastReportedFps).

Test plan

• npx tsc --noEmit clean (both src + tools).
• npx vitest run — 931 / 931 passing (+6 from new bootstrap
  orchestrator test).
• New regression test (tests/services/engine/phases/bootstrap.test.ts):
  - phases run in declared order;
  - first rejection short-circuits (initGpu/wireSlots/wireInput
  throw → later phases NOT called);
  - state writes from earlier phases visible to later phases.
• Visual smoke (manual): page loads, status transitions
  initializing → loading → ready fire in order, click + dblclick
  work, settings panel echoes, destroy() detaches orbit controls.

Phase boundary table

Phase	Lines lifted (pre-Phase-5)	Reads from	Side effects	Async work
initGpu	593–776	canvas, state.gpu	state.gpu.{renderer, postProcess, filamentRenderer}; populates state.assetSlots.points via registry; stashes phaseLocals (device, context, quad/disk/procedural/milkyWay renderers)	await initGpu(canvas)
wireSlots	778–1031	state.gpu.*, state.assetSlots.points, state.subsystems.scheduler	state.assetSlots.{filaments, famousMeta, pgcAlias}; allSlots populated; state.subsystems.{loadProgress, thumbnails}; state.sources.{famousMeta, famousXrefs}; cb.onStatusChange({kind:'loading'}); fires loads	allArrivalsPromise + synthetic fallback
wireInput	1033–1323	state.sources.clouds, state.gpu.renderer, phaseLocals.device, state.cam (after construction), state.picking	state.gpu.pickRenderer; state.subsystems.{clickResolver, inputBindings}; state.cam; state.initialCamSnapshot; deps.detachControlsRef.current; cb.onStatusChange({kind:'ready'}); seedSettingsCallbacks fan-out	none direct
startLoop	1325–1372	state, every renderer (via phaseLocals + state.gpu.filamentRenderer), helpers from deps	deps.frameRef.current = real body; state.subsystems.scheduler.requestRender()	none

Deviations from the plan

• firstReadySource flows through phaseLocals, not state.
  The pre-Phase-5 IIFE captured firstReadySource as a closure local
  written by the all-arrivals subscriber and read by the
  cb.onStatusChange({kind:'ready', source}) call later in the same
  IIFE. With the IIFE split into phases, that capture crosses a phase
  boundary (wireSlots writes; wireInput reads). Promoting it to
  EngineState would expand the type for one consumer; threading it
  through phaseLocals keeps the orchestrator-internal carrier.
• PhaseLocals is a phase-internal carrier on BootstrapDeps.
  The pre-Phase-5 IIFE used its own closure scope to thread the GPU
  device, context, and IIFE-local renderers between sequential
  blocks. Phases preserve this with a deps.phaseLocals field
  (typed) that initGpu writes and wireSlots / startLoop read.
  state.gpu only carries the renderers destroy() releases
  (renderer, postProcess, filamentRenderer, pickRenderer); the rest
  live on phaseLocals to keep EngineState narrow.

Anything surprising

• The handle.focusOn(lastClickedInfo) call inside wireInput's
  onDoubleClick handler captures the public handle, which is
  declared after the bootstrap IIFE in engine.ts. We thread it
  through deps.handleRef: { current: EngineHandle | null };
  engine.ts assigns handleRef.current = handle after the handle
  literal evaluates. By the time a user can physically double-click,
  orbit controls are wired and handleRef is non-null. Same
  {current} ref pattern as frameRef/detachControlsRef.
• The pre-Phase-5 if (state.sources.clouds.size === 0) return
  early-return mid-IIFE is preserved by having wireInput and
  startLoop both check the same condition and bail. The engine
  then sits in 'loading' state with nothing wired — identical to the
  pre-Phase-5 behaviour.

🤖 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	33c9029	Commit Preview URL Branch Preview URL	May 08 2026, 12:58 AM