docs(renderer): renderer-unification design spec

[rulkens]

What

Adds the design spec for unifying skymap's renderer paths.

The recent zoom-to-Earth work added a third render path (opaque, depth-tested, f64 near-field bodies) bolted onto a frame loop that previously had two (additive HDR scene + premultiplied-OVER UI overlay). This spec proposes one compositor model that subsumes background, foreground, and pick:

• Three independent axes un-braided: slab (which view-projection + depth range), target (which texture), blend (additive / opaque / over). Today which Pass[] array a renderer lives in implicitly fixes all four of projection, precision, blend, and target.
• Compositor primitive replaces three byte-identical tone-map / composite implementations (postProcess tonemap, foregroundComposite, volumeUpsample blit).
• Flat ContentLayer registry + a data FrameStep program replace HDR_PASSES / UI_PASSES / the hand-wired foreground. Frame order becomes data (and therefore unit-testable).
• Pick becomes a parallel program over the same registry: per-slab pick targets + a pure-CPU frontmost-non-zero resolve. Space-aware, shipping at N=1 (cosmological).
• 3-phase plan: Compositor primitive → registry + program → pick fold-in. Each phase is an independently shippable, behaviour-neutral superset.

Essential differences (precision, frustum, blend) are preserved; accidental duplication is erased.

Status

Draft — under review. No code changes; this is the design doc that will drive a future writing-plans.

Spec: docs/superpowers/specs/2026-06-29-renderer-unification-design.md

🤖 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	5ba7c11	Commit Preview URL Branch Preview URL	Jul 06 2026, 05:24 PM

[rulkens]

Re-verified the spec against current main (post #394/#396) and fixed four stale spots (commit 7fe76ef):

1. Migration table — added clipPathDebugPass (in UI_PASSES since the tour work) and a note on drawPickDebugOverlay as a debug composite step. Main already has three hand-rolled composites (postProcess tonemap, volumeUpsample blit, pickDebugOverlay blit) before feat(zoom-to-Earth): true-scale foreground renderer (Plan 01 + polish) #386 adds foregroundComposite as the fourth.
2. FrameStep program — the volume prepass + flow compute are nested inside both HDR encoder branches today (shared via encodeVolumePrepass/encodeFlowCompute); the spec now says the program lifts them, and that the executor owns the single/split timing fork as an execution strategy (with TIMED_SLOT_NAMES deriving from the program).
3. Pick prerequisite — camera-for-pick must become a value from the slab table; today it's a byte snapshot of pointSpritesPass's uniforms (state.picking.lastFrameUniformBytes), which makes per-slab pick targets unimplementable. Phase 3 now starts there.
4. Phase 2 target-format idiom — renderer factories declare targetFormat explicitly; named the three coexisting initGpu idioms (positional arg, repurposed GpuContext.format, ctx-bag + positional override). GpuContext.format = swap format, always.

Also corrected the framing that the foreground path is on main (it's draft PR #386), added phase-1 merge-order handling for #386, and cited the actual tone-map curve test. Branch merged with origin/main (no history rewrite). Full audit context: docs/audits/2026-07-02-powers-of-ten-architecture-review.md (on grand-tour).

🤖 Generated with Claude Code

[rulkens]

Implementation plans added to this PR (commit 417ad8b) — three phase plans + an index under docs/superpowers/plans/2026-07-06-renderer-unification-*:

• 01-compositor (5 tasks): the Compositor primitive with all three blends + the postProcess tonemap repoint. shaders/toneMap/ is deleted; the JS-mirror curve cluster moves to compositor.ts; PostProcess.draw's signature is unchanged so renderFrame is untouched.
• 02-registry-and-program (11 tasks): the eight frame types, slabs.ts (stable NEAR0/COSMO indices), mechanical conversion of all 14 passes to ContentLayer rows, frameProgram(tone) + the strategy executor with derived timing slots, the render-target table with consolidated resize, the targetFormat factory cleanup, and PassDeps deletion. Green suite at every commit; the flip is isolated in Task 7 with a mid-plan visual check.
• 03-pick (12 tasks): pick camera becomes a value (the full 176-byte lastFrameUniformBytes layout is re-homed field-by-field, nothing unrebuildable), drawPick on the four pickable rows, the per-slab pickProgram + frontmostPick. Bonus finding folded in: proceduralDiskRenderer had a second camera byte-stash (cachedViewProj, replayed by pickDisks) — same braid, dissolved in the same phase.

One spec correction fell out of plan-time shader verification (spec updated in the same commit): volumeUpsamplePass's fragment is a deliberate 4-tap rotated-grid low-pass (grain suppression for the raymarch) and drawPickDebugOverlay's is an r32uint textureLoad visualisation — both are essential specializations, not generic composites, so neither joins the Compositor and the FRAME program has no volume→hdr composite step. The volume double-gate knot is fixed by a shared deriveVolumeLiveness projection instead. Also recorded: dstFormat can't be recovered from a pass encoder, so phase 1 maps blend→dstFormat in the constructor and phase 2 dissolves the mapping.

The superseded render-graph-restructure backlog item is removed in this PR per the spec's acceptance note.

🤖 Generated with Claude Code

[rulkens]

Plan 04 added: fold PR #386 (zoom-to-earth) onto the layer/slab/program model (docs/superpowers/plans/2026-07-06-renderer-unification-04-fold-zoom-to-earth.md, 8 tasks).

Strategy: plans 01+02 execute on main without #386, then plan 04 executes on the #386 branch (merge main in, convert, run the visual gate #386 has been waiting on, un-draft). What dissolves: encodeForegroundPass/encodeForegroundOver/foregroundLabelsPass, foregroundComposite (+3 WESL files), foregroundOffscreen, and the four ReadyFrameContext foreground fields → two ContentLayer rows, one foreground:0 target row, the activated NEAR0 slab (origin-relative f64 computeForegroundViewProj), and three appended FRAME steps. All of #386's substance (f64 compose-before-narrow path, sphere renderer, scale units, scalebar ladder, MW approach-fade) rides along untouched.

Two contract gaps the fold surfaced, fixed pre-execution in this commit:

1. Compositor alpha semantics (spec + plan 01): alpha is now a column of the blend table — replace emits 1.0, over/additive preserve source alpha via a preserveAlpha uniform derived from the blend; over is straight-alpha Porter-Duff matching feat(zoom-to-Earth): true-scale foreground renderer (Plan 01 + polish) #386's composite byte-for-byte. Plan 01 as previously written (premultiplied over + forced alpha-1.0) would have painted the foreground offscreen over the entire screen on fold.
2. Depth attachments as data (plan 04, Task 2): foreground:0 is the first row to exercise RenderTargetSpec.depth; renderTargets + executeFrame extend the first-touch-clear rule to depth.

Behaviour deltas the fold accepts (all named in the plan): foreground offscreen renders after the hdr→swap tonemap (no data dependency), pass+composite skipped entirely when no body is enabled (touched-set rule — the branch always opened both), and the foreground gains dev-only per-layer timing slots.