From 34853e025a3d59a6c38ab5a70a92fa78fcb687e8 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 02:26:30 +0200 Subject: [PATCH 01/60] docs: capture Sgr A* black-hole close-up design (grill session), park on body slab Design settled Q1-Q11 (cubemap geodesic pass, Schwarzschild, faint EHT-style glow, 2 r_s floor, zero settings); parked pending the body-slab camera work. Backlog entry added under Rendering as blocked. Co-Authored-By: Claude Fable 5 --- docs/BACKLOG.md | 1 + docs/backlog/2026-09-01-render-black-hole.md | 7 + .../render-black-hole-2026-09-01.md | 141 ++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 docs/backlog/2026-09-01-render-black-hole.md create mode 100644 docs/grill-sessions/render-black-hole-2026-09-01.md diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 35ad341780..8e111bfdf2 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -69,6 +69,7 @@ Items with a **→ details** link have a full write-up in [`backlog/`](backlog/) ## Rendering +- [ ] **Render Sgr A* (black-hole close-up)** `blocked` — design settled in a grill session (cubemap geodesic pass, Schwarzschild, EHT-style glow); parked on the body-slab camera work. → [details](backlog/2026-09-01-render-black-hole.md) - [ ] **`dirToEquirectUv` lives twice in WESL** `ready` — copied verbatim from `earth/fragment.wesl` into `earthSurfaceTile/fragment.wesl` (both load-bearing); extract to `shaders/lib/`. - [ ] **Renderer landmines from the Quest VR spike** `ready` — three hard-won traps to add to docs/RENDERER.md: per-camera (not per-frame) ctx memos, rebase-origin carrying, writeBuffer-at-submit ordering. → [details](backlog/2026-08-23-renderer-landmine-docs.md) - [ ] **Layer blend is declared twice** `needs-design` — `ContentLayer.blend` and the pipeline's `GPUBlendState` restate each other with nothing tying them; parity wants `blendStateOf` threaded through every renderer. → [details](backlog/2026-07-31-layer-blend-declared-twice.md) diff --git a/docs/backlog/2026-09-01-render-black-hole.md b/docs/backlog/2026-09-01-render-black-hole.md new file mode 100644 index 0000000000..77146144eb --- /dev/null +++ b/docs/backlog/2026-09-01-render-black-hole.md @@ -0,0 +1,7 @@ +# Render Sgr A* — black-hole close-up + +`blocked` on the body-slab work (riding the Earth RTC camera effort, PR #634 line). Design is fully settled — see the grill transcript, don't re-litigate without new evidence: [docs/grill-sessions/render-black-hole-2026-09-01.md](../grill-sessions/render-black-hole-2026-09-01.md). + +One-paragraph shape: environment-cubemap geodesic screen pass (Schwarzschild, 1D deflection LUT), faint EHT-style in-pass glow (annulus 3–6 r_s, doppler, minimal sim-clock flicker), "sky" content lensed / annotations on top, far-field orange glint crossfading in via a `SCALE_FADE_BANDS` row on the Sgr A* anchor (~500→100 AU), amortized round-robin cubemap capture, zero user settings, descent floored at ~2 r_s via per-body standoff override. + +Resume: probe precision/gates at 2 r_s under the new slab → `refactor-ground` (fold in `2026-07-30-camera-target-vs-origin-distance-gates.md` if implicated) → spec from the transcript. diff --git a/docs/grill-sessions/render-black-hole-2026-09-01.md b/docs/grill-sessions/render-black-hole-2026-09-01.md new file mode 100644 index 0000000000..d115771119 --- /dev/null +++ b/docs/grill-sessions/render-black-hole-2026-09-01.md @@ -0,0 +1,141 @@ +# Grill Session: Rendering Sgr A* (black-hole close-up) — 2026-09-01 + +Source: live brainstorming session, pivoting from a Gaia-data research question ("what's near the GC?") to the deliberate follow-up the S-star spec deferred: giving Sgr A* a visual treatment. Prior art surveyed: PR #365 `feat/gravitational-lensing` (cluster lensing). + +Goal: when the camera descends past the S-stars onto Sgr A*, show a physically-grounded black-hole close-up — shadow, photon ring, gravitationally lensed background — instead of today's nothing. + +Context findings that framed the session (Explore survey of main @ 9dce415f4): + +- Sgr A* ships as an `AnchorPointBody` (position, label, real Schwarzschild radius 12.69×10⁶ km ≈ 0.085 AU) that deliberately draws nothing; the S-star spec's non-goals name "black disc, lensing, photon ring" as a dedicated follow-up — this feature. +- The scale ladder already reaches it: focus + per-body standoff + NEAR0 adaptive frustum let the camera descend to ~1× r_s today. +- PR #365 (SIS/NFW cluster lensing, 40 commits, June 2026) is **template, not base**: different feature (background galaxies lensed by clusters, vertex-stage thin-lens), ~53-file conflicts after the `galaxyCatalog/` shader reorg, 257 commits stale. Reusable ideas: two-vec4 lens uniform pattern, precompute-a-LUT-instead-of-per-vertex-root-finding. +- Landmine: backlog item `2026-07-30-camera-target-vs-origin-distance-gates.md` names Sgr A* as the first case where origin-relative NEAR0 gate derivation diverges from target-relative reads. + +--- + +## Q1: Visual ambition + +**The question:** What should "rendering Sgr A*" deliver when the camera approaches — how big is this feature? + +**Considerations:** + +- **Option A (full lensed close-up):** a real destination — black shadow, photon ring, lensed background starfield warping as you orbit (EHT/Interstellar-class visual). Needs a dedicated lensing pass; largest scope. +- **Option B (physically-scaled marker):** point-mass lens warping nearby stars via PR #365-style vertex deflection + a glow/shadow sprite. Honest at the already-rendered scale, no new pass. +- **Option C (lensing revival first):** land PR #365's cluster lensing, then add a point-mass profile. Physics-first sequencing, two PRs. + +**Decision:** **Full lensed close-up (A).** The scale ladder already supports the descent, and the S-star spec explicitly reserved this treatment; B and C both fail to deliver the shadow/photon-ring visual that defines the object. + +## Q2: Physical honesty of the emission + +**The question:** Sgr A* is quiescent — no bright Interstellar-style accretion disc exists in reality. How honest is the close-up? + +**Considerations:** + +- **Option A (honest quiescent):** shadow + photon ring + lensed starfield only. Fully defensible; relies on lensing alone for spectacle. +- **Option B (cinematic disc):** glowing doppler-beamed disc. Spectacular but fictional for this object; large extra shader surface. +- **Option C (faint EHT-style glow):** honest scene plus a dim ring-hugging emission matched to the EHT Sgr A* image geometry. Small addition; keeps the "this is what it looks like" claim defensible with a documented false-colour note. + +**Decision:** **Faint EHT-style glow (C).** Middle path: the glow marks the object from afar and gives the lensing something to act on, while staying anchored to a real measurement. Noted honestly: at visual wavelengths Sgr A* is dark — EHT orange is 230 GHz false colour, so the glow is documented artistic licence. + +## Q3: Lensing technique + +**The question:** How is the gravitational lensing actually computed and drawn? + +**Considerations:** + +- **Option A (screen-space warp):** post-pass distorting the framebuffer around the BH. Cheap, but an Einstein ring shows sky from behind the camera, which isn't in the framebuffer — wrong exactly where it matters. +- **Option B (per-vertex deflection, PR #365 style):** bend star positions in the vertex stage, draw double images. Works for discrete points only; no shadow edge, no photon ring, can't bend backdrop imagery; thin-lens breaks down in the near field. +- **Option C (environment-cubemap geodesic pass):** inside the approach band, capture the surrounding scene into a small cubemap; a screen-quad shader traces Schwarzschild geodesics per pixel (analytic bending angle or 1D LUT — PR #365's LUT trick, one dimension smaller) sampling the cubemap. Shadow, photon ring, Einstein rings, multiple images all emerge from the geometry. + +**Decision:** **Cubemap geodesic pass (C).** Only option that produces the chosen visual; every ingredient (offscreen targets, LUT textures, fade bands) has codebase precedent, and the pass gates strictly to the close-approach band. Clarified in discussion: the glow does NOT come from the cubemap — it is synthesized in the same pass (rays crossing the emission region accumulate glow; escaping rays sample the cubemap; captured rays go black), which is what makes the asymmetric-ring look emerge rather than being painted. + +## Q4: Metric + +**The question:** Schwarzschild or Kerr? + +**Considerations:** + +- **Option A (Schwarzschild):** no spin. Closed-form-ish deflection, 1D LUT, simple shadow geometry. +- **Option B (Kerr):** spin adds frame-dragging asymmetry — but Sgr A*'s spin magnitude/orientation are poorly constrained, geodesics need a 4D LUT or full integration everywhere, and the shadow-shape difference is a few percent. + +**Decision:** **Schwarzschild (A).** We don't know the spin, so Kerr would be heavy machinery in service of an unverifiable claim; the doppler asymmetry people actually notice comes from disc-material motion, modelled regardless. + +## Q5: What gets lensed + +**The question:** Which scene content renders into the lensed cubemap, and what stays on top unlensed? + +**Considerations:** + +- **Lens everything** including orbit trails/rings/labels: physically consistent but warped annotation ellipses read as bugs, and labels must stay legible. +- **Lens the "sky" only:** star points, galaxy points, backdrop imagery into the cubemap; diagrammatic layer (orbit trails, marker rings, labels, picking) composited on top unlensed. + +**Decision:** **Lens the "sky" only.** Annotations are not light. Accepted approximation, stated explicitly: cubemap content is treated as at-infinity — valid because the strong-field region spans a few AU while the nearest real content (S-stars) sits at hundreds of AU; a star sweeping behind the hole still doubles/rings correctly. + +## Q6: Activation envelope and far-field presence + +**The question:** When does the expensive pass run, and what exists at Sgr A* before it engages? + +**Considerations:** + +- **Empty far field (status quo):** nothing until the pass engages — the object pops into existence. +- **Far-field glint + fade band:** a faint orange point-glint at the anchor from afar (the real compact source), crossfading into the geodesic pass via the existing `SCALE_FADE_BANDS` mechanism keyed on distance to the Sgr A* anchor (the same pattern the GC Milky-Way fade shipped on in #642). + +**Decision:** **Glint + fade band**, roughly engage ≤ 500 AU → fully on by ~100 AU (the shadow is subpixel until a few hundred AU, conveniently inside the S-star cluster scale). Pass cost is exactly zero outside the band. + +## Q7: Glow model + +**The question:** What emission model, and does it vary in time? + +**Considerations:** thin equatorial annulus at ~3–6 r_s (ISCO outward → the ~5 r_s lensed ring the EHT measured), Keplerian doppler brightening on the approaching side, near face-on viewing (EHT constrains inclination ≲ 30°), warm orange, calibrated fainter than the S-stars. Position angle unconstrained observationally — pick one and note it. Variability: Sgr A* flickers on minute timescales (its EHT image needed variability correction); options were skip (less shader surface) vs include minimally. + +**Decision:** annulus model as above, **flicker included, minimally** — one global sim-clock-driven brightness modulation, no patch structure. + +## Q8: Cubemap capture cost + +**The question:** Capturing the scene 6× per frame (galaxy cloud ~2.5M points) would be the most expensive thing in the app — what's the capture strategy? + +**Considerations:** + +- **Per-frame full capture:** simplest, optimize later if the harness complains. +- **Amortized:** 256²–512² rgba16float faces; round-robin one face per frame (full refresh every 6 frames — invisible for a quasi-static background); full 6-face capture once on band entry so the first view is never stale; per-pass LOD so the cloud renders reduced-count into the small target. + +**Decision:** **Amortized round-robin** with band-entry full capture and LOD'd capture passes. Perf gate: `npm run perf` before/after; ~zero outside the band, bounded inside. + +## Q9: User-facing controls + +**The question:** Any settings — toggle, strength slider? + +**Considerations:** PR #365 had a `lensStrength` slider because cluster lensing at physical 1× is invisible; here physical 1× *is* the show. A toggle would exist only as a perf escape hatch, but the pass is already proximity-gated to ~zero cost elsewhere. + +**Decision:** **Zero new settings.** Physically parameterized from the shipped anchor body (mass → r_s). Dev tuning through the existing debug panel, removed before merge. Code-is-liability default. + +## Q10: Descent floor + +**The question:** The global standoff would let the camera park at 1.0000024 × r_s. How deep is the descent allowed to go, given the shader's static-viewpoint model is only well-behaved down to about the photon sphere (1.5 r_s)? + +**Considerations:** + +- **Horizon-graze (status quo):** the last stretch shows confidently wrong physics (no local-frame aberration / sky compression). +- **Floor at ~2 r_s:** per-body standoff override (one data field; current multiplier is global). Shadow already fills most of the view; everything shown stays defensible. +- **Full GR observer view:** local-frame aberration + sky-wide redshift below the photon sphere — a significant extra shader layer. + +**Decision:** **Floor at ~2 r_s.** The full observer experience is a possible future follow-up, not this feature. + +## Q11: Sequencing — park on the body slab + +**The question:** Ground prep was about to include a precision/gate probe (AU-scale scene 8.2 kpc from render origin ≈ f32 epsilon territory; the target-vs-origin NEAR0 gate item names Sgr A* as first victim). But a **body slab** is being implemented in another worktree (riding the Earth RTC camera effort) — probe now, or wait? + +**Considerations:** + +- **Option A (park the whole feature):** wait for the body slab, then probe → refactor-ground → spec against the settled camera architecture. Same reasoning that parked inside-atmosphere on #634: don't judge a dying camera. +- **Option B (split by dependency):** prototype the pure-shader half (geodesic tracer, LUT, glow) in a standalone workbench now; spec the integration after the slab lands. + +**Decision:** **Park entirely (A).** All design decisions above are captured here; work resumes with the precision/standoff probe once the body slab has landed, and the spec is then written against the post-slab ground (refactor-ground runs at that point, folding in the target-vs-origin gate item if the probe implicates it). + +--- + +## Resume checklist (when the body slab lands) + +1. Probe: focus Sgr A*, force distance to ~2 r_s, observe jitter / frustum / S-star sprite stability under the new slab. +2. Run `refactor-ground`; decide whether `docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` becomes prep inside this feature. +3. Write the spec from this transcript (decisions Q1–Q10 are settled; don't re-litigate without new evidence). From 7170060943394e29cc8699c8fdf0d5028ac4575b Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 02:56:42 +0200 Subject: [PATCH 02/60] docs(spec): render Sgr A* black-hole close-up design Spec written against the post-#634 body-slab architecture with ground prep P1-P3 (slab candidacy from body data, per-body standoff, fixed-size render targets) as a separate prep PR. Backlog item retired into the spec. Co-Authored-By: Claude Fable 5 --- docs/BACKLOG.md | 1 - docs/backlog/2026-09-01-render-black-hole.md | 7 - .../2026-09-01-render-black-hole-design.md | 449 ++++++++++++++++++ 3 files changed, 449 insertions(+), 8 deletions(-) delete mode 100644 docs/backlog/2026-09-01-render-black-hole.md create mode 100644 docs/superpowers/specs/2026-09-01-render-black-hole-design.md diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 8e111bfdf2..35ad341780 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -69,7 +69,6 @@ Items with a **→ details** link have a full write-up in [`backlog/`](backlog/) ## Rendering -- [ ] **Render Sgr A* (black-hole close-up)** `blocked` — design settled in a grill session (cubemap geodesic pass, Schwarzschild, EHT-style glow); parked on the body-slab camera work. → [details](backlog/2026-09-01-render-black-hole.md) - [ ] **`dirToEquirectUv` lives twice in WESL** `ready` — copied verbatim from `earth/fragment.wesl` into `earthSurfaceTile/fragment.wesl` (both load-bearing); extract to `shaders/lib/`. - [ ] **Renderer landmines from the Quest VR spike** `ready` — three hard-won traps to add to docs/RENDERER.md: per-camera (not per-frame) ctx memos, rebase-origin carrying, writeBuffer-at-submit ordering. → [details](backlog/2026-08-23-renderer-landmine-docs.md) - [ ] **Layer blend is declared twice** `needs-design` — `ContentLayer.blend` and the pipeline's `GPUBlendState` restate each other with nothing tying them; parity wants `blendStateOf` threaded through every renderer. → [details](backlog/2026-07-31-layer-blend-declared-twice.md) diff --git a/docs/backlog/2026-09-01-render-black-hole.md b/docs/backlog/2026-09-01-render-black-hole.md deleted file mode 100644 index 77146144eb..0000000000 --- a/docs/backlog/2026-09-01-render-black-hole.md +++ /dev/null @@ -1,7 +0,0 @@ -# Render Sgr A* — black-hole close-up - -`blocked` on the body-slab work (riding the Earth RTC camera effort, PR #634 line). Design is fully settled — see the grill transcript, don't re-litigate without new evidence: [docs/grill-sessions/render-black-hole-2026-09-01.md](../grill-sessions/render-black-hole-2026-09-01.md). - -One-paragraph shape: environment-cubemap geodesic screen pass (Schwarzschild, 1D deflection LUT), faint EHT-style in-pass glow (annulus 3–6 r_s, doppler, minimal sim-clock flicker), "sky" content lensed / annotations on top, far-field orange glint crossfading in via a `SCALE_FADE_BANDS` row on the Sgr A* anchor (~500→100 AU), amortized round-robin cubemap capture, zero user settings, descent floored at ~2 r_s via per-body standoff override. - -Resume: probe precision/gates at 2 r_s under the new slab → `refactor-ground` (fold in `2026-07-30-camera-target-vs-origin-distance-gates.md` if implicated) → spec from the transcript. diff --git a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md new file mode 100644 index 0000000000..7cf29bdd7b --- /dev/null +++ b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md @@ -0,0 +1,449 @@ +# Render Sgr A\* — black-hole close-up + +A viewer who descends past the S-stars to within a few hundred AU of Sgr A\* +sees it for the first time: a faint orange glint that resolves, on approach, +into a lensed close-up — black shadow, photon ring, a doubled and warped +starfield bending around it, and a thin doppler-brightened emission annulus +matched to the EHT Sgr A\* image geometry. Today `AnchorPointBody` draws +nothing; this feature is that dedicated follow-up, reserved explicitly by the +S-star-orbits spec's non-goals. + +Design decisions and their rejected alternatives are recorded in +[`docs/grill-sessions/render-black-hole-2026-09-01.md`](../../grill-sessions/render-black-hole-2026-09-01.md); +this spec cross-references those as **Q1**–**Q11** rather than restating the +reasoning. **Decision provenance:** every visual-ambition, physics, technique +and scope call (Q1–Q10) and the sequencing ruling (Q11) come from that +transcript and are implemented here as settled — this spec does not +re-litigate them. What follows fills in the engineering shape the transcript +deliberately left to spec time: exact file/type contracts, draw-order +placement, and the ground preparation the post-#634 architecture requires. + +## Goal + +Within `SCALE_FADE_BANDS.sgrAStarLensing`'s band (engage ≤ 500 AU, full by +100 AU — Q6), the screen shows a physically-grounded Schwarzschild close-up of +Sgr A\* built from a captured environment cubemap and a per-pixel geodesic +trace. Outside the band, a faint orange point-glint marks the anchor from +afar, present the moment Sgr A\* is on screen at all, and crossfades out as +the close-up crossfades in. The camera may descend to 2 Schwarzschild radii +(Q10); beyond that the standoff floor stops it. Zero new user-facing settings +(Q9). + +## Non-goals + +- **No Kerr metric.** Schwarzschild only (Q4) — spin is unconstrained for + Sgr A\*, and the shadow-shape difference is a few percent. +- **No full-GR observer view below 2 r_s.** No local-frame aberration or + sky-wide redshift; the descent floor (Q10, P2) stops the camera at the + boundary where the shader's static-viewpoint model is still defensible. +- **No cinematic accretion disc.** The emission is the faint EHT-style glow + only (Q2/Q7) — visually honest, with the false-colour licence documented + inline, not a bright fictional disc. +- **No M87\* or any second black hole.** `BLACK_HOLES` is built to hold more + than one row; a second row is data, not a code change, and is explicitly + not built here. +- **No tour beat.** +- **No lensing of annotations.** Orbit trails, marker rings, labels and + picking stay unlensed, composited on top (Q5). + +## Data + +| quantity | value | +| ------------------------------------- | --------------------------------------------------- | +| Sgr A\* mass | 4.297 × 10⁶ M☉ (GRAVITY Collaboration 2019, A&A 625, L10) | +| Schwarzschild radius (derived) | `2GM/c²` ≈ 12.69 × 10⁶ km ≈ 0.085 AU — same figure `sgrAStarSchwarzschildRadiusKm.ts` hand-authored today | +| Emission annulus | 3–6 r_s (ISCO outward to the ~5 r_s EHT-measured lensed ring) | +| Inclination | ≲ 30° from face-on (EHT constraint) | +| Position angle | unconstrained observationally; one value chosen and noted as such | +| Flicker | one global sim-clock brightness modulation, minute-scale timescale, no patch structure (Q7) | +| Lensing band (Q6) | engage ≤ 500 AU, full by 100 AU | +| Descent floor (Q10) | 2 r_s, via per-body `standoffRadii` override | + +```ts +// src/data/bodies/sgrAStarMassSolar.ts — one symbol per file. +export const SGR_A_STAR_MASS_SOLAR = 4.297e6; // GRAVITY Collaboration 2019, A&A 625, L10 + +// src/utils/physics/schwarzschildRadiusM.ts — one symbol per file. +// r_s = 2GM/c²; pure function so the S-star pericentre conversion and the +// registry radius both read the SAME formula rather than a transcribed constant. +export function schwarzschildRadiusM(massSolar: number): number; +``` + +`sceneSgrAStar.ts`'s `SGR_A_STAR.radiusM` becomes +`schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` — the function returns metres, +no unit intermediate — replacing the import of +`SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM`. `sgrAStarSchwarzschildRadiusKm.ts` is +deleted; its second reader (the S-star pericentre-in-r_s card row, +`BodyOrbitInfo.pericentreSchwarzschildRadii`) switches to the same function +or reads `SGR_A_STAR.radiusM` directly — implementer's call, cited so the +two readers this file's own docblock names are not silently orphaned. + +```ts +// src/@types/data/BlackHoleRow.d.ts — one symbol per file. +export type BlackHoleRow = { + readonly bodyId: BodyId; // 'sgr-a-star' today; a second row is future data, not code (M87*) + readonly emission: { + readonly innerRs: number; // 3 + readonly outerRs: number; // 6 + readonly inclinationRad: number; // ≲30° from face-on, EHT + readonly positionAngleRad: number; // unconstrained; chosen, documented at the row + readonly flickerAmp: number; // fractional brightness modulation + readonly flickerTimescaleS: number; // ~minutes + }; +}; + +// src/data/blackHoles.ts +export const BLACK_HOLES: readonly BlackHoleRow[]; // one row: sgr-a-star +``` + +--- + +## Ground preparation + +Three prep refactors, each its own commit, packaged as its own PR sequenced +before the feature PR (checkpoint ruling, Q11 resume checklist item 2 — this +is the `refactor-ground` pass the resume checklist calls for, run once the +body slab had a real body to grow onto). All three verdicts are **bolt-on**: +the post-#634 body-slab architecture already has the joints this feature +needs; P1–P3 remove the three places that still hardcode "earth + planets" +where the correct statement is "every body-slab candidate." + +### P1 — slab candidacy derived from body data, not a hardcoded union + +**Bolt-on.** `visibleSlabBodies` (`src/services/engine/frame/visibleSlabBodies.ts:26-30`) +takes `earth`/`planets` as two separate typed params and builds its candidate +list as `earth === null ? planets : [earth, ...planets]` — closed over +exactly those two `SceneBody` arms. `AnchorPointBody` was never a candidate +because an anchor "draws nothing" (its own docblock, +`src/@types/scene/AnchorPointBody.d.ts:2-3`) — true until this feature, false +after. `BODY_SLAB_CAPACITY` (`frameProgram.ts:77`, +`1 + SCENE_PLANETS.length`) is the same hardcoded pair one level up: a +compile-time query-set size (see the GPU-timing-service note at that line) +that must stay in lock-step with whatever `visibleSlabBodies` can emit. + +Prep: `visibleSlabBodies` becomes a predicate over `SceneBody` (any arm +carrying `radiusM`), admitting anchor bodies alongside Earth and the planets; +`BODY_SLAB_CAPACITY` derives its count from the same admitted set rather than +`1 + SCENE_PLANETS.length` as a separate literal. The apparent-diameter and +frustum culls already in `visibleSlabBodies` (`bodyApparentDiameterPx`, +`isInsideFrustum`) are unchanged — an `AnchorPointBody` competes for a slab +row on the same terms a planet does, sub-pixel-culled the same way. `AnchorPointBody`'s +docblock line 2–3 ("DRAWS NOTHING: no mesh, no point, no glint") is corrected: +Sgr A\* now draws a glint and, inside the band, the lensing pass — both via +its own new `ContentLayer` rows below, not via the flat/textured/glint +partition planets use (an anchor still carries no orientation state for +`bodyRelativePose` to rotate by beyond identity, which P1 explicitly verifies +rather than assumes). + +**Proof obligation:** with Sgr A\* far outside the band (any framing wider +than the galactic centre), `visibleSlabBodies` returns exactly what it +returns today for Earth + planets — the anchor's frustum/pixel culls reject +it at any sane viewing distance until the feature's own band engages, so this +prep is a zero-behaviour-change proof over the existing test suite for every +scene except the one this feature adds. + +### P2 — per-body camera-standoff floor + +**Bolt-on.** `clampDistance` (`src/utils/camera/clampDistance.ts:70-77`) +floors at `pivotRadiusMpc * SURFACE_STANDOFF_RADII`, one global ratio +(`1.0000024`, `:38`) tuned for Earth's imagery resolution. Q10's floor is a +different multiple (2.0) for one specific body — a second global constant +would either regress Earth's tuned value or under-floor Sgr A\* with Earth's. + +Prep: an optional `standoffRadii` field on body data (the arm(s) that supply +`pivotRadiusMpc` to a focus/zoom call site), read by `clampDistance` with +`SURFACE_STANDOFF_RADII` as the default when absent — + +```ts +// src/utils/camera/clampDistance.ts — signature delta. +export function clampDistance( + d: number, + pivotRadiusMpc: number | null, + standoffRadii: number = SURFACE_STANDOFF_RADII, +): number; +``` + +Sgr A\*'s record sets `standoffRadii: 2.0` (Q10's floor). Earth, the planets +and the Sun carry no override and keep today's `1.0000024`. This is +independent of P1 — P1 is about which bodies get a SLAB ROW at all; P2 is +about how close the CAMERA may sit once one has, and applies whether or not +the camera is currently orbiting that body's slab. + +### P3 — fixed-size render targets, for the sky cubemap + +**Bolt-on, narrowest of the three.** `RenderTargetSpec` +(`src/@types/engine/frame/RenderTargetSpec.d.ts:13-33`) sizes every existing +row off the canvas: `scale` is a divisor (1, 3, or a live-setting function) +applied to `canvasSize`. Every current offscreen (`volume`, `zoa`, +`mw-aggregate`, `star-aggregates`, `foreground:0`) is canvas-proportional by +design — they exist to be upsampled back into a canvas-sized HDR target. The +sky cubemap is not: it is 256²–512² per face regardless of the viewport +(Q8), and it is six layers of ONE texture (sampled as a cube in the shader), +not six independent 2D targets — WebGPU cannot attach a `cube`-view render +target, so the six faces render as six layers of a `2d-array` texture and the +sampling shader binds that array as `texture_cube`. + +Prep: `RenderTargetSpec` gains a fixed-size form alongside the existing +canvas-divisor `scale` — + +```ts +// src/@types/engine/frame/RenderTargetSpec.d.ts — delta only. +// scale: number | ((state: EngineState) => number) ← existing, canvas-relative +// + fixedSizePx?: { readonly size: number; readonly layers: number } +// ← NEW: canvas-independent, P3 +``` + +`renderTargets.ts`'s reconcile path (the module backing this type) grows the +one branch that currently derives width/height from `canvasSize / scale` to +instead read `fixedSizePx` when present — a P3 implementation task, not +pinned further here; the contract is the field, not the branch. + +--- + +## Architecture + +### The fade band — engagement and the far-field glint + +New `SCALE_FADE_BANDS` row, following the `milkyWayApproachGc` pattern +(`milkyWayCloudLiveness.ts:38-41`) exactly: region-relative distance via +`regionRelativeDistanceMpc(camPosMpc, regionById('galactic-centre'), bodyStates)`, +fed through `fadeBand`. + +```ts +// src/services/engine/presentation/scaleFadeBands.ts — new row. +// Keyed on: CAMERA distance from the `galactic-centre` region's anchor +// (Sgr A*), Mpc — regionRelativeDistanceMpc, the milkyWayApproachGc pattern. +// A recede band (fullAt < goneAt): full strength at the CLOSE edge, gone at +// the FAR edge — the opposite direction from milkyWayApproachGc, which fades +// OUT on approach. Q6's envelope, in AU: +sgrAStarLensing: { + fullAt: 100 * SCALE_UNITS.AU_TO_MPC, + goneAt: 500 * SCALE_UNITS.AU_TO_MPC, +}, +``` + +The far-field glint's alpha is `1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc)` +— the same two edges, read in the opposite sense, rather than a second +authored pair. Two constants for one crossfade is exactly the kind of drift +risk `scaleFadeBands.ts`'s own `backdropBand` shape exists to avoid; deriving +the glint's alpha from the pass's own band alpha keeps the handoff popless by +construction, the same reasoning `bodyGlint`'s `goneAt = BODY_GLINT_MAX_PX` +share already documents. + +Two presences, on two different mechanisms — deliberately, because they live +on opposite sides of P1's apparent-diameter cull: + +- **The far-field glint** rides the existing body-glint machinery (the + subpixel-body sprite path), NOT a body-slab layer: at glint range Sgr A\* + is subpixel, so `visibleSlabBodies` correctly denies it a slab row, which + is exactly when a glint mechanism exists to take over. Its roster admits + the anchor (a P1-adjacent widening), alpha = `1 - lensingBandAlpha`, + warm-orange. Exact wiring is a plan task. No pick aspect — Sgr A\*'s + existing pick stamp is untouched by this feature. +- **`sgrAStarLensing`** — a new `ContentLayer` row, `slab: 'body'`, gated on + `view.slab.frame.bodyId === 'sgr-a-star'`: the geodesic screen pass, + detailed below. Skips its own dispatch entirely when + `lensingBandAlpha <= 0` — the exact "pass cost is exactly zero outside the + band" guarantee Q6 states. + +### The lensing pass + +**Technique (Q3):** per pixel, classify the Schwarzschild geodesic through +that screen direction from the current eye: **escape** (samples the captured +sky cubemap — lensed background), **crosses the 3–6 r_s emission annulus** +(accumulates glow: doppler + gravitational shift, one global flicker +modulation — Q7), or **captured** (black). The asymmetric ring look emerges +from this classification, not from a painted texture (grill clarification, +Q3). + +**Deflection via a precomputed LUT, not per-pixel root-finding** — the same +move PR #365 made for its NFW lens (`src/utils/lensing/buildNfwLensLut.ts`, +a CPU generator inverting the lens equation over a grid, uploaded as a GPU +texture by `createNfwLensLutTexture` and sampled from `lensing.wesl`), one +dimension smaller here because Schwarzschild's bending angle is a function of +impact parameter alone: + +```ts +// src/@types/lensing/SchwarzschildDeflectionLut.d.ts — one symbol per file. +export type SchwarzschildDeflectionLut = { + readonly samples: Float32Array; // total bending angle, radians, indexed by impact parameter + readonly minImpactParamRs: number; // in units of r_s + readonly maxImpactParamRs: number; +}; + +// src/utils/lensing/buildSchwarzschildDeflectionLut.ts — CPU generator. +export function buildSchwarzschildDeflectionLut(sampleCount: number): SchwarzschildDeflectionLut; +``` + +The pass fully classifies escape/capture from the LUT's bending angle alone — +that lookup is O(1) per pixel. A **short bounded march (~32–64 steps)** runs +only for rays whose impact parameter puts them near the 3–6 r_s annulus band, +to accumulate the emission glow along the ray (the LUT gives total +deflection, not the ray's full path, which the annulus crossing needs). This +is the one per-pixel cost that scales with anything beyond a texture fetch, +and it is bounded and gated to the annulus-adjacent subset of pixels — most +of a frame's pixels (background far from the shadow) take the O(1) path. + +**Draw order.** `CONTENT_LAYERS`' additive-HDR group interleaves the roster +("sky") rows with annotation rows today — `orbit-trails` (item 12) and +`body-glints` (item 12b) sit BETWEEN `star-points` (11) and `star-catalog` +(14/15). Q5's "sky lensed, annotations on top unlensed" requires the lensing +pass to draw strictly after every roster row it samples (`point-sprites`, +`milky-way`, `star-points`, `star-aggregates`, `star-catalog`) and strictly +before any annotation that should stay unwarped over it. `orbit-trails` and +`body-glints` therefore move to draw AFTER `sgrAStarLensing` in +`CONTENT_LAYERS`' order (a two-row reorder inside the existing additive-HDR +group — mechanical, flagged here so it is not silently dropped, not pinned +further since the exact insertion index is an implementation task). Per-pixel +alpha does the rest of the work: a ray far from the shadow deflects +negligibly, so the pass's own output there is near-transparent and the +already-drawn roster pixels underneath show through unchanged — the pass +does not need to (and does not) suppress the roster layers' own draws +elsewhere on screen. + +### Sky capture + +**What gets captured (Q5, Q8):** an explicit opt-in roster — `point-sprites` +(galaxy points), the Gaia survey stream (`star-catalog` + `star-aggregates`, +composited the same way `star-upsample` already does), and whichever +partition branch is currently rendering the S-stars (their apparent size at +GC-relative framing puts them in the `bodyGlints`/`planets`/`starSpheres` +branch of the body/star partition machinery, filtered to S-star ids). Never +the full frame program — the roster is a fixed, named list of layers, not +"everything." + +**Cubemap and per-face capture:** + +```ts +// src/services/engine/frame/skyCubemapFaceContext.ts — one symbol per file, +// the pickFrameContext.ts precedent (src/services/engine/helpers/pickFrameContext.ts): +// re-derive a full ReadyFrameContext from a synthetic camera rather than +// threading a swapped vp through every consumer, because several roster +// layers read ctx.fovYRad / ctx.canvasSize / ctx.drawPxPerRad frame-globals +// for angular sizing, not just viewProj. +export function skyCubemapFaceContext(input: { + readonly state: EngineState; + readonly eyeMpc: Readonly; // Sgr A*'s anchor position — the cubemap's eye + readonly face: CubeFace; // 0..5, ±X/±Y/±Z + readonly faceSizePx: number; +}): ReadyFrameContext | null; +``` + +256²–512² per face, `rgba16float` (Q8), via the P3 fixed-size 2d-array +target. Cubemap content is treated as at-infinity — a deliberate, stated +approximation (Q5): the strong-field region spans a few AU while the nearest +real content (the S-stars) sits at hundreds of AU, so a star crossing behind +the hole still doubles/rings correctly even though its capture-time position +is not re-projected for the viewer's exact eye offset within that few-AU +range. + +**Amortization (Q8):** full 6-face capture once on band entry (so the first +close-up view is never stale), then round-robin one face per frame — a full +refresh every 6 frames, invisible for a quasi-static background at this +distance scale. Each captured face renders the roster at reduced LOD (a +per-pass concern of the roster layers themselves, not a new mechanism). +**Escape valve:** a face is re-captured out of turn only when camera movement +or sim-clock time since its last capture exceeds a threshold — data tuning +(the threshold value), not new architecture. + +### Perf + +The fragment cost of the six-face capture is trivial: 6×256² ≈ 400k pixels, +far below the point-sprite/star-catalog draw the app already does every +frame. **The watched cost is walking the roster layers a second time** — an +extra `ReadyFrameContext`, an extra vertex pass, an extra CPU-side visibility +walk, per captured face, per frame. Mitigations, restated from Q8/Q9: + +- the roster is opt-in and fixed — never the full frame program; +- round-robin caps the extra walk at one reduced-LOD face per frame, not six; +- the threshold-based re-capture escape valve avoids re-walking a static + face every frame even within the round-robin's own cadence; +- the pass itself dispatches nothing when the band alpha is 0 (Q6) — zero + cost outside ~500 AU of Sgr A\*. + +**Hard gate:** `npm run perf` before and after (read the `perf` skill first; +worktree runs need `--url` against this worktree's own dev-server port). Zero +delta expected outside the band; bounded, measured cost expected inside it. +A neutral-or-negative reading on either measurement halts the landing +pipeline per the project's code-is-liability convention — it does not get +waved through on the strength of the design. + +### Settings + +Zero new user-facing settings (Q9) — physically parameterized from +`BLACK_HOLES` and the shipped anchor body (mass → r_s). Dev tuning of the +emission/LUT/capture constants rides the existing debug panel and is removed +before merge, the same posture the grill session settled on. + +--- + +## Testing + +**Unit-testable, pure:** + +- `schwarzschildRadiusM` against the known Sgr A\* figure (0.085 AU / + 12.69 × 10⁶ km, within float tolerance of the hand-authored constant it + replaces). +- `buildSchwarzschildDeflectionLut` against known Schwarzschild bending-angle + values at a few chosen impact parameters (the same posture + `buildNfwLensLut.test.ts` takes against its own closed-form limits). +- `fadeBand` over `SCALE_FADE_BANDS.sgrAStarLensing`'s edges (the band math + itself — direction, the 100/500 AU envelope in Mpc). +- The P1 `visibleSlabBodies` predicate, over a fixture anchor body, both + admitted (inside frustum, above pixel floor) and culled (outside either). +- Uniform packing for the emission/deflection data fed to the shader (the + usual byte-offset table discipline for a WGSL uniform struct — pinned at + plan time, not here). + +**Not unit-testable — user visual gate.** The geodesic tracer's correctness +is a shader-visual question; checklist for the gate: + +- shadow diameter reads as ~5.2 r_s (the EHT-consistent apparent size); +- an Einstein ring is visible on background stars crossing near the shadow; +- doppler asymmetry favours the correct side of the annulus (the approaching + material's side, given the chosen inclination/position-angle); +- the fade band crossfades without a pop at either edge; +- the far-field glint hands off to the close-up without a visible seam. + +**Perf** via `npm run perf`, per the Perf section above — a standing gate, +not a one-time check. + +**Prep proof obligations**, restated: P1's `visibleSlabBodies` returns the +same set it does today for every scene outside the new band (zero-change +proof); P2's `clampDistance` floor is unchanged for every body that doesn't +set `standoffRadii` (Earth's `1.0000024` untouched); P3 adds a target form, +touching no existing target row's derivation. + +--- + +## Sequencing + +1. **PR #634 (`globe-camera`)** merges first — the body-slab architecture + this entire spec is written against. +2. **Ground-preparation PR** — P1, P2, P3, each its own commit, its own PR + per the checkpoint packaging decision (unlike the S-star spec's + one-PR-with-prep-first packaging; the black-hole feature is large enough, + and cleanly separable enough from the prep, that the prep lands and is + reviewed on its own). +3. **2 r_s descent probe** (Q11's resume-checklist item 1) — focus Sgr A\*, + force distance to ~2 r_s under the merged slab, observe jitter / frustum / + S-star sprite stability. This is the first implementation task of the + feature plan, ahead of any shader work, because it validates the + precision assumption (`bodyRelativePose`'s f64-cancel-then-scale-to-metres + seam, `oneMpcSeam.test.ts`) the rest of the feature is built on. +4. **Feature implementation** — data rows, fade band, glint layer, LUT + builder, geodesic shader, cubemap capture, lensing `ContentLayer`, draw- + order reorder, debug-panel dev tuning (removed before merge). + +## Relationship to open items + +`docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` — the +Q11 resume checklist names this as a candidate to fold into prep "if the +probe implicates it." This spec does not resolve it; the descent probe +(sequencing step 3) is the point at which that judgment call gets made, not +spec time. Left standing, untouched by this spec. + +`docs/backlog/2026-09-01-render-black-hole.md` and its `BACKLOG.md` index +line describe exactly this feature; both are retired in the same change that +adds this spec, per the backlog-hygiene convention — this spec is now the +source of truth. From f60ba2b0e02ce1b939a91ceda5698665b6878821 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 10:21:46 +0200 Subject: [PATCH 03/60] docs(plan): render-black-hole implementation plan (17 tasks, 2 PR phases) Review fixes over the draft: perf halt-condition wording corrected in plan and spec (regression/unbounded halts, not neutral), per-face context hand-off responsibility named in Task 12, LUT finite-distance approximation noted as gate-judged in Task 13. Co-Authored-By: Claude Fable 5 --- .../plans/2026-09-01-render-black-hole.md | 1114 +++++++++++++++++ .../2026-09-01-render-black-hole-design.md | 6 +- 2 files changed, 1117 insertions(+), 3 deletions(-) create mode 100644 docs/superpowers/plans/2026-09-01-render-black-hole.md diff --git a/docs/superpowers/plans/2026-09-01-render-black-hole.md b/docs/superpowers/plans/2026-09-01-render-black-hole.md new file mode 100644 index 0000000000..f1f9665f18 --- /dev/null +++ b/docs/superpowers/plans/2026-09-01-render-black-hole.md @@ -0,0 +1,1114 @@ +# Render Sgr A* Black Hole Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. This plan follows `docs/superpowers/conventions/plan-style.md` — contract code (signatures, test names+assertions, byte tables) yes, implementation bodies no. + +**Goal:** Render a physically-grounded Schwarzschild close-up of Sgr A* inside a +new `sgrAStarLensing` fade band (500→100 AU), with a far-field warm-orange +glint marking it from any distance while on screen, replacing the current +"draws nothing" `AnchorPointBody`. + +**Architecture:** Two PRs. Phase A (ground-prep) widens the post-#634 body-slab +architecture's three remaining "earth + planets only" hardcodes so an anchor +body can compete for a slab row, get a camera-standoff floor, and back a +fixed-size cubemap render target — all zero-behaviour-change for every +existing scene. Phase B is the feature: black-hole physics data, the fade +band + far-field glint crossfade, a captured sky cubemap, a Schwarzschild +deflection LUT, and a new geodesic `ContentLayer` drawn after the roster it +lenses and before the annotations that must stay unwarped. + +**Tech Stack:** TypeScript, WebGPU, WESL (wesl-plugin), Vitest. + +**Spec:** `docs/superpowers/specs/2026-09-01-render-black-hole-design.md` + +## Global Constraints + +- Zero new user-facing settings (Q9) — the feature is physically parameterized + from `BLACK_HOLES` + the shipped anchor body; dev-tuning constants ride the + existing DebugPanel and are removed before merge. +- No Kerr metric, no full-GR observer view below 2 r_s, no cinematic + accretion disc, no M87*/second black hole, no tour beat, no lensing of + annotations (orbit trails, marker rings, labels, picking stay unlensed). +- `npm run perf` is a hard gate, before AND after the feature work (read + `.claude/skills/perf/SKILL.md` first; pass `--url` against this worktree's + own dev-server port). Neutral outside the band; bounded inside it. A + regression outside the band, or an unbounded/unacceptable cost inside it, + HALTS the landing pipeline — the user rules, not process momentum. +- Any file delete/rename goes through `npm run refactor -- delete/move` or + `npm run move-files -- `, spelled out in the task text — never + `git mv` + hand-edited imports. +- Phase A lands as its own PR, reviewed and merged before Phase B starts. + +--- + +## Phase A — ground-prep PR + +### Task 1: P1 — slab candidacy admits anchor bodies, `BODY_SLAB_CAPACITY` derives from the same set + +**Files:** +- Create: `src/data/bodies/sceneAnchorPointBodies.ts` +- Modify: `src/services/engine/frame/visibleSlabBodies.ts:26-46` +- Modify: `src/services/engine/frame/frameContext.ts:201-209` (the sole call site) +- Modify: `src/services/engine/frame/frameProgram.ts:77` (`BODY_SLAB_CAPACITY`) +- Modify: `src/@types/scene/AnchorPointBody.d.ts:2-3` (docblock correction) +- Modify: `src/data/sources/sgr-a-star.ts:8` (same "DRAWS NOTHING" claim, second home — goes stale the same way) +- Modify: `tests/services/engine/frame/visibleSlabBodies.test.ts` (every existing call site's `{earth, planets, ...}` args move to `{bodies, ...}`) +- Modify: `tests/data/bodies/orientationForBody.test.ts` (anchor-identity assertion) + +**Interfaces:** +- Produces: `SCENE_ANCHOR_POINT_BODIES: readonly AnchorPointBody[]` — mirrors + `SCENE_PLANETS`'s shape (`src/data/bodies/scenePlanets.ts:14`), one element + (`SGR_A_STAR`, imported from `sceneSgrAStar.ts`) today. Appending a second + `AnchorPointBody` (M87*, spec non-goal) is a data change to this array, not + a code change anywhere it's consumed. +- Consumes/produces: `visibleSlabBodies` signature changes from + `{ earth: EarthBody | null; planets: readonly PlanetBody[]; ... }` to + `{ bodies: readonly SceneBody[]; ... }` (drop the internal + `earth === null ? planets : [earth, ...planets]` concat — the caller now + assembles the candidate list). Return type stays `readonly SceneBody[]`. +- `frameContext.ts:201`'s call site becomes the concat site: `bodies:` built + from `state.data.bodies.earth`, `state.data.bodies.planets`, and + `SCENE_ANCHOR_POINT_BODIES` (spread, not the single `SGR_A_STAR` — so a + future second anchor row needs no second call-site edit). +- `BODY_SLAB_CAPACITY` becomes `1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_BODIES.length` + (the leading `1` stays Earth's reserved slot, per the existing comment at + `frameProgram.ts:71-76`). + +**Steps:** + +- [ ] Write `SCENE_ANCHOR_POINT_BODIES` (`sceneAnchorPointBodies.ts`): + `export const SCENE_ANCHOR_POINT_BODIES: readonly AnchorPointBody[] = [SGR_A_STAR];` + importing `SGR_A_STAR` from `./sceneSgrAStar`. +- [ ] Update the failing/changed tests in `visibleSlabBodies.test.ts` FIRST: + every existing case's `{ earth, planets, bodyStates, ... }` call + becomes `{ bodies: [...], bodyStates, ... }` (fold `earth`/`planets` + into one array per case, preserving each case's asserted behaviour + unchanged — this IS the zero-behaviour-change proof for those cases). +- [ ] Add the test `admits an AnchorPointBody candidate on the same terms as a planet`: + construct a synthetic `AnchorPointBody` (arbitrary `radiusM`) at a + position/distance that clears both culls with a `bodyStates` entry, + assert it appears in the result; construct a second one far outside the + frustum, assert it does not. +- [ ] Run `npm test -- visibleSlabBodies` — new tests fail (no `bodies` param + yet), existing tests fail on the old `{earth, planets}` shape. +- [ ] Implement: change `visibleSlabBodies`'s param to `bodies: readonly SceneBody[]`, + drop the internal concat (`visibleSlabBodies.ts:46`), keep every + downstream line (`FRUSTUM_CULL_MARGIN_FACTOR`, `isInsideFrustum`, + `bodyApparentDiameterPx`) untouched — they already operate on the + `SceneBody` union's shared `radiusM`/`id` fields. +- [ ] Update `frameContext.ts:201-209`'s call site to assemble `bodies` from + `state.data.bodies.earth` (null-checked), `state.data.bodies.planets`, + and `SCENE_ANCHOR_POINT_BODIES`. +- [ ] Update `BODY_SLAB_CAPACITY` (`frameProgram.ts:77`) to the three-term sum + above; import `SCENE_ANCHOR_POINT_BODIES`. +- [ ] Run `npm test -- visibleSlabBodies frameContext frameProgram` — all pass. +- [ ] Add the test (in `orientationForBody.test.ts`) `returns identity for + the Sgr A* anchor` — asserts `orientationForBody('sgr-a-star', )` equals `IDENTITY_MAT3`. This is the P1 "anchor + orientation-identity verification through bodyRelativePose": Sgr A* is + not in `BODY_TEXTURE_REGISTRY`, so `orientationForBody`'s existing + membership gate (`orientationForBody.ts:33`) already returns identity — + the test pins that fact so a future accidental texture-registry entry + for `sgr-a-star` can't silently rotate the body-slab basis + `bodyRelativePose` builds from it. +- [ ] Correct `AnchorPointBody.d.ts:2-3`'s docblock: replace "DRAWS NOTHING: + no mesh, no point, no glint" with a statement that an anchor may draw a + far-field glint and, inside its lensing band, a geodesic pass — both + via dedicated `ContentLayer` rows keyed on its id (Phase B), never via + the flat/textured/glint partition planets use. Keep the surrounding + "identity fields only" rationale (still true — `AnchorPointBody` gained + no new fields). +- [ ] Correct the matching claim at `src/data/sources/sgr-a-star.ts:8` ("It + DRAWS NOTHING: no sphere, no point, no glint") the same way — same fact, + second home, same staleness risk. +- [ ] Run `npm test` (full suite) and `npm run typecheck` — green. +- [ ] Commit. + +**Proof obligation (spec):** with Sgr A* far outside the lensing band (any +framing wider than the galactic centre), `visibleSlabBodies` returns exactly +what it returns today for Earth + planets — the anchor's frustum/pixel culls +reject it at any sane viewing distance. The updated existing test cases +(unchanged assertions, reshaped call args) are that proof for the covered +scenes. + +--- + +### Task 2: P2 — per-body camera-standoff floor (`standoffRadii`) + +**Files:** +- Modify: `src/utils/camera/clampDistance.ts:70-78` +- Modify: `src/data/bodies/sceneSgrAStar.ts` (add `standoffRadii: 2.0` to `SGR_A_STAR`) +- Modify: `src/@types/scene/AnchorPointBody.d.ts` (add optional `standoffRadii` field) +- Modify: `tests/utils/camera/clampDistance.test.ts` + +**Interfaces:** +- `clampDistance(d: number, pivotRadiusMpc: number | null, standoffRadii: number = SURFACE_STANDOFF_RADII): number` + — third param optional, defaulting to the existing global constant so every + existing call site (which passes only two args) is untouched. +- `AnchorPointBody` gains `readonly standoffRadii?: number` — optional, so + Earth/planets/Sun (which carry no such field on their own types) are + unaffected; only a call site that HAS an `AnchorPointBody`'s standoff can + read it and pass it through as `clampDistance`'s third arg (wiring the read + site — wherever the orbit-focus/zoom call composes `pivotRadiusMpc` for a + focused body — is this task's implementation, not pinned further here since + the spec doesn't name that call site and it's a one-line threaded read). + +**Steps:** + +- [ ] Add the test `clampDistance — per-body standoff` describing the + contract: with a `standoffRadii` of e.g. `2.0` and a pivot radius `R`, + `clampDistance(smallD, R, 2.0)` floors at `2.0 * R` (not + `SURFACE_STANDOFF_RADII * R`), asserted the same way the existing + `EARTH_RADIUS_MPC`-relative tests assert (body radii, not raw Mpc — see + the file's own header rationale). +- [ ] Add the test `clampDistance — omitted standoffRadii keeps Earth's + current floor unchanged`: `clampDistance(d, EARTH_RADIUS_MPC)` (two-arg + call, exactly as today's call sites use it) is byte-identical to + today's behaviour — this is the zero-change proof for every body that + doesn't opt in. +- [ ] Run `npm test -- clampDistance` — new tests fail. +- [ ] Implement the third parameter with the stated default; the floor + becomes `Math.max(MIN_DISTANCE_MPC, pivotRadiusMpc * standoffRadii)`. +- [ ] Run `npm test -- clampDistance` — passes. +- [ ] Add `standoffRadii?: number` to `AnchorPointBody.d.ts`, with a one-line + doc note citing Q10 (2 r_s descent floor) as the reason a per-body + override exists at all — the global `SURFACE_STANDOFF_RADII` stays + tuned for Earth's imagery resolution (see `clampDistance.ts:26-46`) and + must not regress. +- [ ] Set `standoffRadii: 2.0` on `SGR_A_STAR` in `sceneSgrAStar.ts`. +- [ ] Find and update the focus/zoom call site that currently calls + `clampDistance(d, pivotRadiusMpc)` for a focused `SceneBody` (a + two-arg call somewhere in the orbit-camera/focus-tween path) to read an + optional `standoffRadii` off the focused body when present, passing it + as the third arg; every other body (no such field) falls through to + the default. +- [ ] Run `npm test` and `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 3: P3 — fixed-size render targets, for the sky cubemap + +**Files:** +- Modify: `src/@types/engine/frame/RenderTargetSpec.d.ts:14-40` +- Modify: `src/services/gpu/renderTargets.ts:265-350` (`allocate`, `reconcile`) +- Modify: `tests/services/gpu/renderTargets.test.ts` + +**Interfaces:** + +```ts +// RenderTargetSpec — delta only, alongside the existing `scale`. +export type RenderTargetSpec = { + // ...unchanged fields (id, format, depth, clearValue)... + scale: number | ((state: EngineState) => number); + /** + * When present, this row's pixel size is `fixedSizePx.size` on each axis + * regardless of canvas size, and its texture has `fixedSizePx.layers` + * array layers (a `2d-array` texture, sampled as `texture_cube` by a + * consumer that binds all six as a cube — WebGPU has no cube-view render + * attachment). `scale` is ignored when this is present. + */ + fixedSizePx?: { readonly size: number; readonly layers: number }; +}; +``` + +- No existing row in `renderTargetRows` sets `fixedSizePx` — this task adds + only the type + the `reconcile`/`allocate` branch; the sky-cubemap TARGET + ROW itself is added by a Phase B task (it needs `BLACK_HOLES`-adjacent + constants that don't exist yet). + +**Steps:** + +- [ ] Add the test `createRenderTargets — a fixedSizePx row allocates at its + declared size regardless of canvas size`: construct + `createRenderTargets` with a test-only `RenderTargetSpec` row (or, if + `renderTargetRows` isn't the seam under test, inject via whatever seam + the existing tests use) carrying `fixedSizePx: { size: 256, layers: 6 }`; + assert the allocated texture's `size` descriptor is + `{ width: 256, height: 256, depthOrArrayLayers: 6 }` at a canvas of + `{ width: 900, height: 600 }`. +- [ ] Add the test `createRenderTargets — reconcile does not reallocate a + fixedSizePx row when the canvas resizes`: call `reconcile` with a + DIFFERENT canvas size than construction; assert `device.createTexture` + was NOT called again for that row's id (mirrors the existing + "reallocates... when the canvas size changes" test's call-count + assertion style at `renderTargets.test.ts:52-88`, inverted). +- [ ] Run `npm test -- renderTargets` — new tests fail (no such row exists + yet to construct against — write them against a literal test spec + object passed through whatever `renderTargetRows`-adjacent seam the + implementer adds for injectability, OR against a temporary row added to + `renderTargetRows` and removed once Phase B's real cubemap row lands; + implementer's call, documented inline in the test file). +- [ ] Add `fixedSizePx` to `RenderTargetSpec.d.ts` as above. +- [ ] In `renderTargets.ts`, grow `reconcile`'s per-row loop + (`renderTargets.ts:338-345`) so a `fixedSizePx` row computes + `[fixedSizePx.size, fixedSizePx.size]` instead of calling + `reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s))` + — the held-size comparison and `allocate` call stay shared with every + other row (a fixed size is just a size that never changes across + resizes, not a separate code path past this one branch). +- [ ] Grow `allocate` (`renderTargets.ts:293-330`) to pass + `depthOrArrayLayers: spec.fixedSizePx?.layers ?? 1` and + `dimension: '2d'` (explicit — WebGPU defaults to `'2d'` already, but + state it so a `layers > 1` row is unambiguous) in the texture + descriptor's `size`, for both the colour and (if `spec.depth`) depth + texture creation calls. +- [ ] Run `npm test -- renderTargets` — passes. +- [ ] Run `npm run typecheck` — green. +- [ ] Commit. + +--- + +## Phase A — Definition of Done (ground-prep PR) + +- **Deliverable inventory:** `SCENE_ANCHOR_POINT_BODIES` (new export); + `visibleSlabBodies`'s new `{ bodies }` signature; `BODY_SLAB_CAPACITY`'s + three-term derivation; `clampDistance`'s `standoffRadii` third parameter; + `SGR_A_STAR.standoffRadii = 2.0`; `RenderTargetSpec.fixedSizePx`; the + `renderTargets.ts` fixed-size allocation branch. +- **Named observable behaviours (smoke pass):** none visual — this PR changes + no draw output for any existing scene (the P1 proof obligation holds by + construction: Sgr A* still fails both culls at every framing wider than the + galactic centre, since Phase B's lensing/glint layers don't exist yet to + read the widened slab candidacy). +- **Deferral boundary:** the sky-cubemap render target ROW itself (data, not + the `fixedSizePx` mechanism) is Phase B. No settings, shader, or data-table + work happens here. + +--- + +## Phase B — feature PR + +### Task 4: 2 r_s descent probe (USER-ATTESTED) + +Sequencing step 3 of the spec — the FIRST implementation task of the feature +plan, ahead of any shader work, because it validates the precision assumption +(`bodyRelativePose`'s f64-cancel-then-scale-to-metres seam, +`tests/services/engine/camera/oneMpcSeam.test.ts`) the rest of the feature is +built on. + +**Files:** none created/modified by default — this is a manual/dev-server +probe. If the probe surfaces a real bug, the fix is a follow-up task (or, +per the spec's "Relationship to open items," may fold +`docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` into +scope — see the STOP-and-consult step below). + +**Steps:** + +- [ ] Start the dev server (`/dev` skill or `npm run dev`), focus Sgr A* + (already selectable/focusable today — `AnchorPointBody` is in + `SCENE_BODIES` and carries a caption). +- [ ] With Phase A merged (the slab-candidacy + standoff-floor prep live), + descend toward Sgr A* to the P2 floor (2 r_s — `standoffRadii: 2.0` + now stops the camera there). +- [ ] Observe: camera jitter at the floor, frustum near-plane behaviour + (`bodySlabRow`'s `near` derivation, `slabs.ts:219-236`), and S-star + sprite/orbit-trail stability at that range (they ride the same NEAR0 + slab and f64 rebase seam). +- [ ] **USER-ATTESTED GATE:** report findings to the user — this is a visual + judgment call, not a scripted assertion. If jitter/instability appears, + STOP and consult before proceeding: does it implicate + `docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` + (per the spec's "Relationship to open items")? That folding decision is + the user's call, made HERE, not assumed by this plan. +- [ ] On a clean probe, proceed to Task 5. On a fold-in verdict, the folded + scope becomes new tasks inserted here (not silently absorbed into a + later task's steps). + +--- + +### Task 5: Sgr A* mass + Schwarzschild radius (data + physics util) + +**Files:** +- Create: `src/data/bodies/sgrAStarMassSolar.ts` +- Create: `src/utils/physics/schwarzschildRadiusM.ts` +- Create: `tests/utils/physics/schwarzschildRadiusM.test.ts` +- Modify: `src/data/bodies/sceneSgrAStar.ts:18-42` (radiusM derivation swap) +- Modify: `src/data/bodies/sStarOrbitInfo.ts:16-21` (second reader migration) +- Delete: `src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts` + +**Interfaces:** + +```ts +// src/data/bodies/sgrAStarMassSolar.ts +export const SGR_A_STAR_MASS_SOLAR = 4.297e6; // GRAVITY Collaboration 2019, A&A 625, L10 + +// src/utils/physics/schwarzschildRadiusM.ts +export function schwarzschildRadiusM(massSolar: number): number; // r_s = 2GM/c², returns METRES +``` + +**Steps:** + +- [ ] Add the test `schwarzschildRadiusM` (in + `tests/utils/physics/schwarzschildRadiusM.test.ts`) asserting + `schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` is within float tolerance + of the KNOWN figure — 12.69e6 km = 1.269e10 m (equivalently 0.085 AU, + both cited in the spec's Data table) — a hand-computed reference value, + not a re-derivation of the same `2GM/c²` formula (that would be a + mirror test per `testing.md`). Use `Number.EPSILON`-scale relative + tolerance appropriate for a physical-constant computation (e.g. + `toBeCloseTo` with a precision chosen so the real constants G/c round + correctly, not an arbitrarily loose bound). +- [ ] Run the test — fails (function doesn't exist). +- [ ] Implement `schwarzschildRadiusM` using named physical constants (G, c) + — no existing G/c constant module was found in this codebase's + `utils/`; add them as named locals in this file with their SI values + and a one-line citation, following the `scaleUnits.ts` convention of + named locals with IAU/physical-constant citations rather than inline + magic numbers. +- [ ] Run the test — passes. +- [ ] Create `sgrAStarMassSolar.ts` with the single constant above. +- [ ] In `sceneSgrAStar.ts`, replace the `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM` + import and `radiusM: SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM * SCALE_UNITS.KM_TO_M` + (line 41) with `radiusM: schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` + (the function returns metres directly — no `KM_TO_M` step). +- [ ] In `sStarOrbitInfo.ts:16-21`, replace the + `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM`-based `SCHWARZSCHILD_RADIUS_AU` + derivation with one reading `schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` + (converted through `SCALE_UNITS.M_TO_MPC` / `SCALE_UNITS.AU_TO_MPC` — + same unit chain, new source value) — this is the file's "second + reader," the S-star pericentre-in-r_s card row's data source + (`BodyOrbitInfo.pericentreSchwarzschildRadii`, consumed by + `BodyDetailCard.tsx:206-212`), migrated per the spec's explicit + instruction rather than left orphaned. +- [ ] Delete `sgrAStarSchwarzschildRadiusKm.ts` via + `npm run refactor -- delete src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts` + (per plan-style rule 5 — never `git mv`/manual delete + hand-edited + imports; the refactor CLI confirms no remaining importers before + removing the file). +- [ ] Run `npm test` and `npm run typecheck` — green (no remaining + `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM` references). +- [ ] Commit. + +--- + +### Task 6: `BlackHoleRow` type + `BLACK_HOLES` registry + +**Files:** +- Create: `src/@types/data/BlackHoleRow.d.ts` +- Create: `src/data/blackHoles.ts` + +**Interfaces:** + +```ts +// src/@types/data/BlackHoleRow.d.ts +export type BlackHoleRow = { + readonly bodyId: BodyId; // 'sgr-a-star' today + readonly emission: { + readonly innerRs: number; // 3 + readonly outerRs: number; // 6 + readonly inclinationRad: number; // ≲30° from face-on, EHT + readonly positionAngleRad: number; // unconstrained; chosen, documented at the row + readonly flickerAmp: number; // fractional brightness modulation + readonly flickerTimescaleS: number; // ~minutes + }; +}; + +// src/data/blackHoles.ts +export const BLACK_HOLES: readonly BlackHoleRow[]; // one row: sgr-a-star +``` + +**Steps:** + +- [ ] Add `BlackHoleRow.d.ts` per the contract above, with a docblock stating + the registry is built to hold more than one row (M87* is data, not + code, per the spec's non-goals) — mirrors `SCENE_PLANETS`'s + append-only framing. +- [ ] Add `blackHoles.ts` with `BLACK_HOLES` holding the `sgr-a-star` row: + `emission.innerRs = 3`, `outerRs = 6` (ISCO-to-EHT-ring, spec Data + table); `inclinationRad`/`positionAngleRad` chosen values (document the + position-angle choice as unconstrained-but-fixed, per the spec); a + flicker amplitude + timescale (minute-scale, spec Data table — no + externally-known reference value exists for these, so pick and + document as taste/dev-tuning-adjustable via Task 15's debug panel). +- [ ] No test — this is a literal data table (a registry-restatement test + here would fail `testing.md`'s bar; the structural invariant worth + testing, if any — e.g. `bodyId` values are valid `BodyId`s — is already + enforced by `tsc` through the `BodyId` type itself). +- [ ] Run `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 7: `sgrAStarLensing` fade band + far-field glint alpha derivation + +**Files:** +- Modify: `src/services/engine/presentation/scaleFadeBands.ts` +- Modify: `tests/services/engine/presentation/scaleFadeBands.test.ts` (or + wherever `fadeBand` + `SCALE_FADE_BANDS` band-math is currently tested — + locate the existing test file for this module before adding). + +**Interfaces:** + +```ts +// scaleFadeBands.ts — new row, following the milkyWayApproachGc pattern +// (fadeBand keyed on regionRelativeDistanceMpc to 'galactic-centre'): +sgrAStarLensing: { + fullAt: 100 * SCALE_UNITS.AU_TO_MPC, + goneAt: 500 * SCALE_UNITS.AU_TO_MPC, +}, +``` + +- The far-field glint's alpha is derived, not authored, as + `1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc)` at its own call + site (Task 8) — no second band. + +**Steps:** + +- [ ] Add the test `SCALE_FADE_BANDS.sgrAStarLensing — 100/500 AU envelope in + Mpc, approach direction`: assert `fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, x)` + is `1` at/inside `100 * SCALE_UNITS.AU_TO_MPC`, `0` at/outside + `500 * SCALE_UNITS.AU_TO_MPC`, and strictly between at a midpoint — + this pins the DIRECTION (full at the close edge, per the spec's + explicit "opposite direction from milkyWayApproachGc" note), which is + an `fullAt`/`goneAt` ordering fact `fadeBand` reads structurally + (`fadeBand.ts:39`: `fullAt > goneAt ? s : 1 - s`) — a real bug (the + band authored backwards) would flip this and is exactly what a + classifier-direction test is for per `testing.md`'s boundary-test + keep-rule. +- [ ] Run the test — fails (row doesn't exist). +- [ ] Add the `sgrAStarLensing` row to `SCALE_FADE_BANDS`, per the contract + above, importing `SCALE_UNITS` (already imported in this file) — no new + import needed for `AU_TO_MPC`, it already exists in `scaleUnits.ts`. +- [ ] Run the test — passes. +- [ ] Run `npm test` and `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 8: Far-field glint — Sgr A* rides `bodyGlintsLayer` + +**Files:** +- Modify: `src/services/engine/frame/passes/bodyGlintsLayer.ts` + +**Interfaces:** +- No new exported symbols — this widens `bodyGlintsLayer`'s existing + `enabled`/`draw` internals with a second, independent packed source + alongside the `sceneBodyPartition(...).glints` branch. `SCENE_ANCHOR_POINT_BODIES` + is NOT routed through `sceneBodyPartition`/`partitionBodiesByPresentation` + (that XOR assumes every input can resolve to a mesh at ≥3px — an anchor + never does, so its own presentation partition doesn't apply; see + `partitionBodiesByPresentation.ts:40-48`'s `BODY_GLINT_MAX_PX` XOR + contract). + +**Design (why a second loop, not a wider partition):** `sceneBodyPartition` +reads `state.data.bodies.planets` only (`PlanetBody[]`); `AnchorPointBody`s +are not planets and carry no `albedo`/texture-residency data +`bodyGlintBrightness`/`bodyTextureSpec` need. The far-field glint therefore +gets its OWN brightness formula — a fixed warm-orange tint × a base +intensity constant × `1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc)` +(the crossfade against the lensing pass, spec §"The fade band") — with NO +apparent-size term (an anchor never hands off to a resolved mesh, so the +existing `bodyGlint` 1–3px band, which exists for exactly that handoff, +doesn't apply here) and NO `bodyGlintBackdrop` far-dissolve (the spec's Goal +states the glint is "present the moment Sgr A* is on screen at all" — +unconditional on far distance, unlike the seeded planets' glints). + +**Steps:** + +- [ ] Add a named constant for the glint's fixed tint (warm-orange, linear + RGB) and its base intensity, beside the layer's existing + `GLINT_MIN_BRIGHTNESS` constant. +- [ ] In `draw`, after the existing `glints` packing loop, add a second loop + over `SCENE_ANCHOR_POINT_BODIES`: for each anchor body, compute + `distMpc` via `regionRelativeDistanceMpc(camPos, regionById('galactic-centre'), states)` + (same helper/region `milkyWayCloudLiveness.ts:40` already uses for the + `milkyWayApproachGc` band), brightness = + `baseIntensity * (1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc))`, + skip below `GLINT_MIN_BRIGHTNESS` (the same shared threshold, "opacity + 0 ⇒ no render"), else pack the same 7-float camera-relative record + shape (`positionMpc - camPos`, tint, brightness) the existing loop + writes, continuing the shared `count`/`staging` buffer. +- [ ] Widen `enabled`: the layer must stay in the pass plan when the anchor + loop would pack ≥1 record even if `sceneBodyPartition(...).glints` is + empty — mirrors the existing `pickEnabled`-widening pattern the file's + header documents for the Earth caption stamp (`bodyGlintsLayer.ts:153-166`), + but for `enabled` itself since this is a VISUAL row, not a pick-only + widening. +- [ ] No `drawPick` change — the spec states Sgr A*'s existing pick stamp + (its caption) is untouched by this feature; the far-field glint carries + no pick aspect of its own. +- [ ] Add a behavioural test (in the existing + `tests/services/engine/frame/passes/bodyGlintsLayer.test.ts`) asserting + the layer's `enabled` returns `true` when the anchor's crossfade alpha + is positive even with an empty `glints` partition (construct a fixture + state/ctx placing the camera far outside the lensing band's `goneAt` + but still — this is the "present the moment it's on screen" contract, + not a distance gate on the glint itself, so pick a fixture distance + that is large but finite) — and a second test that a camera positioned + such that the anchor's computed brightness is 0 (if any such condition + exists given the "always present" design — if none does, state that in + the test file instead of writing a vacuous test, per `testing.md`). +- [ ] Run `npm test -- bodyGlintsLayer` and `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 9: `SchwarzschildDeflectionLut` type + `buildSchwarzschildDeflectionLut` + +**Files:** +- Create: `src/@types/lensing/SchwarzschildDeflectionLut.d.ts` +- Create: `src/utils/lensing/buildSchwarzschildDeflectionLut.ts` +- Create: `tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts` + +**Note:** the spec cites `buildNfwLensLut.ts` / `createNfwLensLutTexture` +(PR #365) as technique precedent. Confirmed absent from this repo and this +worktree's branch — `src/utils/lensing/` does not exist; the code lives only +on the unmerged `feat/gravitational-lensing` branch. Do not cite or import +from it; the precedent is the spec's own description (a CPU generator +inverting a lens relation over a grid), not a file to follow. + +**Interfaces:** + +```ts +// src/@types/lensing/SchwarzschildDeflectionLut.d.ts +export type SchwarzschildDeflectionLut = { + readonly samples: Float32Array; // total bending angle, radians, indexed by impact parameter + readonly minImpactParamRs: number; // in units of r_s + readonly maxImpactParamRs: number; +}; + +// src/utils/lensing/buildSchwarzschildDeflectionLut.ts +export function buildSchwarzschildDeflectionLut(sampleCount: number): SchwarzschildDeflectionLut; +``` + +**Steps:** + +- [ ] Add the test `buildSchwarzschildDeflectionLut` with 2–3 literal + reference values (hand-computed, not re-derived from the same formula + the implementation uses — a genuine independent check per + `testing.md`'s no-mirror rule): + - the WEAK-FIELD limit at a large impact parameter `b` (many `r_s`): + deflection angle `α ≈ 4GM/(c²b) = 2·r_s/b` radians — assert the LUT's + sampled value at (or interpolated near) that impact parameter is within + a stated tolerance of `2·r_s/b`. + - a STRONG-FIELD value near the photon sphere (`b` approaching + `3√3/2 · r_s ≈ 2.598 r_s`, the critical impact parameter): assert + deflection grows large/diverges in the expected direction as `b` + approaches that value from above (a monotonicity/limit assertion, not an + exact literal — the exact strong-field value depends on the numerical + integration scheme chosen for the generator, so pin the qualitative + behaviour plus one moderately-strong-field reference point computed + independently, e.g. via a standalone elliptic-integral or numerical + check the test comment shows the derivation for). + - a monotonicity property: deflection strictly decreases as `b` increases + across the sampled range (an independent property per `testing.md`'s + "Do" list, catching a sign/ordering bug the two point values might miss). +- [ ] Run the test — fails (function doesn't exist). +- [ ] Implement `buildSchwarzschildDeflectionLut`: for `sampleCount` grid + points spanning a chosen `[minImpactParamRs, maxImpactParamRs]` range + (must comfortably straddle the photon sphere at `~2.598 r_s` and reach + out to where the weak-field approximation is already accurate, so the + pass's O(1) LUT lookup covers both the escape and near-capture + regimes), numerically integrate (or closed-form where available) the + Schwarzschild bending-angle relation and populate `samples`. +- [ ] Run the test — passes. +- [ ] Run `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 10: Lensing WGSL uniform struct — byte/offset table + +**Files:** +- Create: `src/services/gpu/shaders/lib/sgrAStarLensing.wesl` (or fold into + an existing lensing-adjacent lib module if one is created by Task 13 — + implementer's call on the exact filename; the byte table below is the + contract regardless of file). +- Create/modify the matching TS packer (co-located with the renderer Task 13 + creates — see that task). + +**Byte/offset table (contract — the plan-style category-3 table the spec +explicitly defers to plan time):** + +Follows the `CameraUniforms` shared-prefix pattern from +`.claude/skills/wesl-shaders/SKILL.md` — 80-byte prefix (`viewProj` + +`viewportPx` + 2 pad floats), renderer-specific fields at offset 80+, +16-byte-aligned before any `vec3`/`vec4`: + +| Offset (bytes) | Field | Type | Notes | +|---|---|---|---| +| 0–63 | `cam.viewProj` | `mat4x4` | shared `CameraUniforms` prefix | +| 64–71 | `cam.viewportPx` | `vec2` | shared prefix | +| 72–79 | `cam._pad0`, `cam._pad1` | `f32`, `f32` | shared prefix pads | +| 80–83 | `schwarzschildRadiusM` | `f32` | r_s in metres — the pass's own scale unit | +| 84–87 | `innerRs` | `f32` | emission annulus inner edge, r_s units | +| 88–91 | `outerRs` | `f32` | emission annulus outer edge, r_s units | +| 92–95 | `inclinationRad` | `f32` | | +| 96–99 | `positionAngleRad` | `f32` | | +| 100–103 | `flickerAmp` | `f32` | | +| 104–107 | `flickerTimescaleS` | `f32` | | +| 108–111 | `flickerPhase` | `f32` | sim-clock-derived phase, uploaded per frame (not a `BLACK_HOLES` constant) | +| 112–115 | `lutMinImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.minImpactParamRs` | +| 116–119 | `lutMaxImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.maxImpactParamRs` | +| 120–123 | `lutSampleCount` | `f32` (or `u32`, matching the LUT texture's actual texel count) | | +| 124–127 | `bandAlpha` | `f32` | the fade band's own alpha this frame — gates emission/deflection strength in-shader for the crossfade, avoiding a second CPU-side branch | +| 128–139 | `anchorPosRelCamM` | `vec3` | camera-relative anchor position, metres — the f64→f32 rebase seam, same pattern `bodyGlintsLayer`/`starPointsLayer` use | +| 140–143 | `_pad2` | `f32` | pad to keep the following field 16-byte aligned if one is added later; omit if 140 already satisfies alignment for the struct's end | + +Total struct size: 144 bytes (rounds to a 16-byte multiple). The +`SchwarzschildDeflectionLut.samples` themselves are NOT part of this uniform +struct — they upload as a separate 1D texture (Task 12), sampled in-shader, +consistent with the `createNfwLensLutTexture` PRECEDENT DESCRIPTION (not the +absent file) the spec cites. + +**Steps:** + +- [ ] Write the WESL struct declaration matching the table exactly (field + order, offsets via WGSL's natural alignment rules — verify each `f32` + run before a `vec3` lands on a 16-byte boundary per the `wesl-shaders` + skill's CameraUniforms pattern). +- [ ] Write the CPU-side `Float32Array` packer function with an inline + docblock offset table matching this one (the wesl-shaders skill: "The + CPU-side Float32Array write must match the WGSL struct byte-for-byte + ... Document the offset table in a docblock on the renderer's TS + file"). +- [ ] Add a byte-offset parity test in the style of existing WGSL/TS parity + tests (`tests/services/gpu/shaders/constants.parity.test.ts` precedent, + per the wesl-shaders skill) OR a direct assertion that the packer + writes each named field at its documented float index — this is a + `testing.md` KEEP-RULE case (WGSL/TS parity + uniform byte-layout), not + a constant restatement: it catches shader/TS drift invisible until a + GPU silently reads garbage. +- [ ] Run `npm test` and `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 11: Sky-capture — fixed-size cubemap target row + `skyCubemapFaceContext` + +**Files:** +- Modify: `src/services/gpu/renderTargets.ts` (`renderTargetRows` — new row) +- Create: `src/services/engine/frame/skyCubemapFaceContext.ts` +- Create: `tests/services/engine/frame/skyCubemapFaceContext.test.ts` +- Create: `src/@types/rendering/CubeFace.d.ts` (confirmed absent from the + repo — no prior `CubeFace` type exists anywhere) + +**Interfaces:** + +```ts +// src/@types/rendering/CubeFace.d.ts — new type, one symbol per file. +export type CubeFace = 0 | 1 | 2 | 3 | 4 | 5; // ±X, ±Y, ±Z, in that index order + +// src/services/engine/frame/skyCubemapFaceContext.ts +export function skyCubemapFaceContext(input: { + readonly state: EngineState; + readonly eyeMpc: Readonly; // Sgr A*'s anchor position — the cubemap's eye + readonly face: CubeFace; + readonly faceSizePx: number; +}): ReadyFrameContext | null; +``` + +- New `renderTargetRows` entry (256² to start, per Q8): `id: 'sky-cubemap'`, + `format: HDR_TARGET_FORMAT` (matches every other additive-HDR-fed row so + the roster's additive draws keep their dynamic range), `depth: null` (the + captured roster — point-sprites, star-catalog/aggregates, S-star glints — + is depthless/additive, same profile as `hdr`), `clearValue: { r: 0, g: 0, + b: 0, a: 0 }` (same additive-identity reason every reduced-res row in the + table clears to zero — see `renderTargets.ts`'s module header), `fixedSizePx: { size: 256, + layers: 6 }` (Task 3's mechanism), `scale` unused/irrelevant when + `fixedSizePx` is set (per Task 3's contract) but the field is still + required by the type — set it to `1` as an inert placeholder. + +**Steps:** + +- [ ] Add the test `skyCubemapFaceContext — derives a ReadyFrameContext with + the eye at the anchor position, looking along the requested face axis`: + call it for each of the 6 `CubeFace` values with a fixture `eyeMpc`, + assert the returned context's camera position matches `eyeMpc` and its + view direction matches the ±X/±Y/±Z convention documented on `CubeFace` + (an independent geometric check — e.g. dot the returned forward + direction with the expected axis vector — not a re-derivation of + whatever `deriveFrameContext` internally does). +- [ ] Add the test `skyCubemapFaceContext — returns null before bootstrap` + (mirrors `pickFrameContext`'s `isReady` guard, + `pickFrameContext.ts:56-90`). +- [ ] Run the tests — fail (function doesn't exist). +- [ ] Implement `skyCubemapFaceContext` following the `pickFrameContext.ts` + precedent exactly: re-derive a full `ReadyFrameContext` via + `deriveFrameContext` from a SYNTHETIC camera pose (position = `eyeMpc`, + orientation = the face's fixed look direction/up pair, a 90° + symmetric-frustum projection sized for a cube face) rather than + threading a swapped vp through every roster-layer consumer — because + several roster layers read `ctx.fovYRad` / `ctx.canvasSize` / + `ctx.drawPxPerRad` as frame-globals for angular sizing, not just + `viewProj` (same rationale `pickFrameContext.ts:1-48`'s docblock gives + for its own re-derivation choice). +- [ ] Add the `sky-cubemap` row to `renderTargetRows` per the contract above. +- [ ] Run `npm test -- skyCubemapFaceContext renderTargets` and + `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 12: Capture scheduling + roster wiring + +**Files:** +- Create: `src/services/engine/frame/skyCubemapCaptureSchedule.ts` +- Create: `tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts` +- Modify: `src/services/engine/frame/frameProgram.ts` (capture render steps, + gated on the lensing band being active) +- Modify: `src/services/engine/frame/renderFrame.ts:99-112` (the sole + `frameProgram(...)` call site — thread the new argument) +- Modify: `src/services/engine/frame/passes/index.ts` (no new registry rows + needed if the capture reuses the EXISTING roster layers' `draw` calls + against the synthetic per-face context — confirm this during + implementation; if a layer's `draw` reads engine-global state incompatible + with a synthetic ctx, that layer needs a capture-aware branch, which is a + STOP-and-report finding, not silently worked around) + +**Interfaces:** + +```ts +// skyCubemapCaptureSchedule.ts +export type SkyCubemapCaptureSchedule = { + readonly facesToCapture: readonly CubeFace[]; // this frame's capture list +}; + +export function skyCubemapCaptureSchedule(input: { + readonly bandJustEngaged: boolean; // band alpha crossed 0→positive this frame + readonly frameIndex: number; // for round-robin + readonly lastCapturedAtMs: ReadonlyMap; + readonly nowMs: number; + readonly cameraMovedBeyondThreshold: boolean; +}): SkyCubemapCaptureSchedule; +``` + +**Amortization contract (spec):** full 6-face capture once on band entry +(`bandJustEngaged`); thereafter round-robin one face per frame +(`frameIndex % 6`); an escape valve re-captures a face out of turn when +camera movement or sim-clock time since its last capture exceeds a named +threshold CONSTANT (data tuning, not new architecture — name it +`SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS` or similar, sited beside the schedule +function). + +`frameProgram`'s signature grows a fourth parameter: +`frameProgram(tone: ToneMap, bloomEnabled: boolean, foregroundChain: readonly number[], skyCubemapFacesToCapture: readonly CubeFace[]): readonly FrameStep[]` +— an empty array outside the band emits no capture steps (Q6's zero-dispatch +guarantee). `renderFrame.ts:99-112`, the sole call site, computes this array +each frame from `skyCubemapCaptureSchedule` (fed the band alpha already +available via `ctx`/`state`) and passes it as the new fourth argument. + +**Steps:** + +- [ ] Add the test `skyCubemapCaptureSchedule — full 6-face capture on band + entry`: `bandJustEngaged: true` → `facesToCapture` has all 6 faces + regardless of `frameIndex`. +- [ ] Add the test `skyCubemapCaptureSchedule — round-robins one face per + frame otherwise`: `bandJustEngaged: false`, vary `frameIndex` across 6 + consecutive values → each yields exactly one face, cycling through all + 6 without repeats within the cycle. +- [ ] Add the test `skyCubemapCaptureSchedule — escape valve re-captures a + stale or camera-moved face out of turn`: a face whose + `lastCapturedAtMs` predates `nowMs` by more than the threshold (or + `cameraMovedBeyondThreshold: true`) appears in `facesToCapture` even + when the round-robin wouldn't select it this frame. +- [ ] Run the tests — fail. +- [ ] Implement `skyCubemapCaptureSchedule` (pure function, no GPU/engine + state — testable headlessly per the file's own test above). +- [ ] Wire the schedule into `frameProgram`: when the lensing band alpha is + positive, emit one `{ kind: 'render', target: 'sky-cubemap', slab: ... }` + step per face in `facesToCapture` (each drawing the fixed opt-in roster + — `point-sprites`, `star-catalog` + `star-aggregates`, and the S-star + partition branch — against that face's `skyCubemapFaceContext`); when + the band alpha is 0, emit NO capture steps at all (Q6's "pass cost is + exactly zero outside the band" guarantee, restated for the capture + side of the feature, not just the lensing draw itself). +- [ ] Update `frameProgram.ts`'s two static `TIMED_SLOTS`/`TIMED_SLOT_GROUPS` + builds (`frameProgram.ts:452-465`, which call + `frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN)`) to pass + all 6 `CubeFace` values as the new fourth argument — the same + "maximum, not a real frame's shorter list" sizing rationale + `MAX_FOREGROUND_CHAIN` already documents, so the DebugPanel's GPU-timing + groups include the sky-cubemap capture rows even on a frame where the + band is inactive and the real list would be empty. +- [ ] Name the runtime hand-off: `renderFrame.ts` (not `frameProgram`, which + is static) derives the scheduled faces' `skyCubemapFaceContext`s each + frame and passes them to the executor alongside the steps, so a capture + step can resolve its face's context at execution time — the exact + plumbing shape (a map on the step, a parallel array, a ctx lookup) is + the implementer's call, but the responsibility split (renderFrame + derives, executor consumes, frameProgram stays static data) is the + contract. +- [ ] Confirm (read each roster layer's `draw`) whether reusing the existing + `CONTENT_LAYERS` rows' `draw` calls against a synthetic per-face `ctx` + "just works," or whether a layer reads something a synthetic context + can't supply (e.g. a GPU handle keyed to the real frame). Report any + such finding rather than papering over it with a special case. +- [ ] Run `npm test -- skyCubemapCaptureSchedule frameProgram` and + `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 13: `ContentLayer` row `sgrAStarLensing` + the geodesic WESL shader + +**Files:** +- Create: `src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl` +- Create: `src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl` +- Create: `src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts` +- Create: `src/services/engine/frame/passes/sgrAStarLensingLayer.ts` +- Modify: `src/services/engine/frame/passes/index.ts` (register the new + layer + import export) + +**Interfaces:** +- `sgrAStarLensingLayer: ContentLayer` — `slab: 'body'`, `target: 'hdr'`, + `blend: 'over'` (per-pixel alpha lets the roster show through where + deflection is negligible — the spec's "per-pixel alpha does the rest of + the work" — which is Porter-Duff OVER semantics, not additive; `Blend.d.ts` + already enumerates `'over'` as a valid value for any target, and nothing + in the codebase restricts `'over'` to the swap-chain rows). + - `enabled(state, ctx, view)`: `view.slab.frame.kind === 'body-m' && view.slab.frame.bodyId === 'sgr-a-star'`, + AND the fade band's alpha for this frame is `> 0` (Q6's zero-dispatch + guarantee — checked the same "opacity 0 ⇒ no render" way every other + band-gated layer in this codebase already does). + - `draw`: binds the Task 10 uniform struct (viewProj/camera prefix + + black-hole physics fields + this frame's `bandAlpha` + the sky-cubemap + texture array as a `texture_cube` binding + the Task 9 LUT as a 1D + texture binding), draws a fullscreen (or bounded-to-the-shadow's + apparent-size) quad/triangle. + - No `drawPick` — the spec's non-goal list excludes picking through the + lensed region; Sgr A*'s existing pick stamp lives in `starPointsLayer` + (`ContentLayer.d.ts:95-96`'s own docblock names this: "`starPointsLayer` + draws the star roster but also stamps Sgr A*, which draws nothing + anywhere and is invited by its caption alone") and is untouched by this + feature — not moved, not widened, not gated on the new lensing band. + +**Shader classification (fragment, per spec):** for each pixel's ray, look up +total deflection from the Task 9 LUT texture by impact parameter (O(1)); if +the ray's impact parameter is below the LUT's minimum (captured) → black; if +the deflected ray direction samples the sky cubemap at infinity → that +sample (escape, lensed background); if the impact parameter falls in the +annulus-adjacent range → run the bounded 32–64-step march (spec's explicit +bound) to accumulate emission glow (doppler + gravitational shift + the +uniform's `flickerAmp`/`flickerTimescaleS`/`flickerPhase` modulation) along +the ray, composited over the escape/capture base classification. + +Known, accepted approximation: the LUT encodes infinity-to-infinity +deflection, so its error grows as the camera nears the 2 r_s floor (the +strongest-field viewpoint). This is inherent to the spec's LUT design, is +judged at Task 17's visual gate, and is NOT a bug to chase numerically — +if the floor view looks wrong there, that is a gate finding for the user, +not a licence to build finite-distance geodesics. + +**Steps:** + +- [ ] Write `vertex.wesl`: minimal fullscreen-triangle (or quad) vertex + stage producing clip position + a per-pixel view-ray direction varying, + importing `CameraUniforms` from `package::lib::camera` per the + wesl-shaders skill's shared-prefix convention (gotcha #2: `package::`, + never the npm name; gotcha #3: imports at the top). +- [ ] Write `fragment.wesl` implementing the escape/annulus/capture + classification above, sampling the Task 9 LUT texture and the Task 11 + sky-cubemap texture array as `texture_cube`. No backticks in comments + (wesl-shaders gotcha #1); no brace-list imports (gotcha #4); one + `import` per identifier (gotcha #5) — cite `lib/math.wesl` as the + "one cohesive multi-function module" precedent if any shared helper + (e.g. a ray-sphere or ray-annulus intersection) is factored out. +- [ ] Write `sgrAStarLensingRenderer.ts`: the TS pipeline (pipeline layout, + bind group with the Task 10 uniform buffer + LUT texture + cubemap + texture, `createShaderModuleWithDevLog` per the shader-compile-logger + convention every renderer in this tree already follows) — cite + `bodyGlintRenderer.ts` as the structural precedent for a small + single-draw renderer (explicit non-`'auto'` bind group layout, `label:` + on every resource). Include a texture-upload helper that turns Task 9's + `SchwarzschildDeflectionLut.samples` into a 1D GPU texture (`r32float`, + width = `samples.length`) at construction time — the direct analogue of + the spec's cited (but absent from this repo) `createNfwLensLutTexture`; + define it in this file rather than inventing a second lensing-utils + home for one function. +- [ ] Write `sgrAStarLensingLayer.ts` implementing the `ContentLayer` + contract above. +- [ ] Register `sgrAStarLensingLayer` in `passes/index.ts`'s import list and + `CONTENT_LAYERS` array (position per Task 14's reorder — this task adds + the row; Task 14 fixes its exact index relative to `orbit-trails` / + `body-glints`). +- [ ] Manual dev-server smoke check that the shader module compiles (no + `Invalid ShaderModule` in the console per the wesl-shaders skill's + dev-mode logger) — this is not the full visual gate (Task 17), just + confirming the pipeline builds. +- [ ] Run `npm test` and `npm run typecheck` — green. +- [ ] Commit. + +--- + +### Task 14: Draw-order reorder — lensing before `orbit-trails`/`body-glints` + +**Files:** +- Modify: `src/services/engine/frame/passes/index.ts` + +**Interfaces:** none new — a reorder of `CONTENT_LAYERS`'s existing array +(`passes/index.ts:245-380`). + +**Steps:** + +- [ ] Re-read `passes/index.ts`'s current order at the time of this task + (Task 13 already inserted `sgrAStarLensingLayer` somewhere) — confirm + the current indices of `milkyWayAggregateLayer`/`milkyWayUpsampleLayer`/`milkyWayLayer`/`starPointsLayer` + (which the lensing pass must draw AFTER, since it samples the roster) + and `orbitTrailsLayer`/`bodyGlintsLayer` (items 12/12b in the module + header's numbered list at the time this plan was written — re-verify + against the live file, since Task 8 modified `bodyGlintsLayer` but not + its position). +- [ ] Move `sgrAStarLensingLayer` to sit AFTER `starAggregateUpsampleLayer`/`constellationsLayer` + (the last roster row the lensing pass samples — point-sprites, + milky-way, star-points, star-aggregates, star-catalog are all upstream + by the time `constellationsLayer` runs) and BEFORE `orbitTrailsLayer`. +- [ ] Move `orbitTrailsLayer` and `bodyGlintsLayer` to sit AFTER + `sgrAStarLensingLayer` in the array (a two-row reorder — the spec's + explicit "orbit-trails and body-glints therefore move to draw AFTER + sgrAStarLensing"). +- [ ] Update the module header's numbered draw-order comment (`passes/index.ts:1-198`) + to reflect the new positions — this comment is the file's own + authoritative map and must not go stale (it directly documents load- + bearing order, unlike a narrative aside). +- [ ] Run `npm test` and `npm run typecheck` — green (no test should assert + the old literal order without a real reason; if one does, per + `testing.md` judge whether it's a legitimate order-dependency test — + update it if so, delete it if it was a restatement). +- [ ] Commit. + +--- + +### Task 15: Debug-panel dev-tuning knobs (temporary, removed before merge) + +**Files:** +- Create (temporary): `src/components/DebugPanel/SgrAStarLensingTuningSection.tsx` +- Create (temporary): `src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` +- Modify (temporary, then reverted in this same task's later step): + `src/components/DebugPanel/DebugPanel.tsx` + +**Precedent:** `ZoneOfAvoidanceTuningSection.tsx` + +`ZoneOfAvoidanceTuningSectionContainer.tsx` (and their sibling +`MilkyWayTuningSection*` pair) are this codebase's existing "a subsystem's +look knobs ride the debug panel" pattern — mount/unmount shape, container +owning the store read/write, section owning the sliders. Follow that +structure for the emission/LUT/capture constants named as dev-tunable in the +spec's Settings section (flicker amplitude/timescale, position angle, +inclination — whatever Task 6's literal `BLACK_HOLES` values and Task 12's +capture threshold constant benefit from live-tuning during Task 17's visual +gate). + +**Steps:** + +- [ ] Add the tuning section + container following the + `ZoneOfAvoidanceTuningSection*` structural precedent, wired to mutate + the relevant constants at runtime (via whatever live-settings seam + that precedent uses — read its container before implementing, don't + invent a new one). +- [ ] Mount it in `DebugPanel.tsx` alongside the other tuning sections. +- [ ] Use it during Task 17's visual gate to converge on final values for + `BLACK_HOLES`'s emission fields and the capture threshold constant. +- [ ] **Removal step (same task, after Task 17 converges on final values):** + bake the tuned values back into `BLACK_HOLES` (Task 6) and the capture + threshold constant (Task 12) as the shipped literals, then DELETE + `SgrAStarLensingTuningSection.tsx` + its container via + `npm run refactor -- delete src/components/DebugPanel/SgrAStarLensingTuningSection.tsx src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` + and remove its mount line from `DebugPanel.tsx` — this removal is part + of THIS task, not deferred to a cleanup task, per the spec's explicit + "removed before merge" posture (Q9). +- [ ] Run `npm test` and `npm run typecheck` — green. +- [ ] Commit (the removal is its own commit within this task, after the + tuning-driven values are baked in — so the history shows tuning added, + then values baked + tuning removed, not squashed into one commit that + hides the knob ever existed). + +--- + +### Task 16: Perf baseline + re-measure (hard gate) + +**Files:** none — measurement only. + +**Steps:** + +- [ ] BEFORE any Phase B code lands (i.e., run this against Phase A's merged + state, or the earliest point in Phase B history before Task 5): + read `.claude/skills/perf/SKILL.md` first, then run `npm run perf` + with `--url http://localhost:` (read + the port off this worktree's own `npm run dev` output — never another + branch's server). Record the baseline numbers outside the band (Sgr A* + far off-frame) and note there is no "inside the band" baseline yet + (the feature doesn't exist). +- [ ] AFTER Task 15 (all feature work + tuning-removal done): re-run + `npm run perf` the same way, twice — once with Sgr A* far outside the + lensing band (expect a neutral delta vs. the baseline — Q6's zero-cost + guarantee), once with the camera inside the band (expect a bounded, + not unbounded, cost — the six-face capture amortized per Q8, the LUT + lookup O(1) per pixel, the bounded 32–64-step march only for + annulus-adjacent pixels). +- [ ] Report both readings plainly. Per the spec's Perf section and the + project's code-is-liability convention: a regression outside the band, + or an unbounded/unacceptable cost inside it, HALTS the landing + pipeline — this is the user's ruling to make, not something this task + auto-resolves by tuning until + the numbers look acceptable. If the outside-band delta is non-neutral, + that is itself a bug to find (the spec's guarantee is exactly zero + dispatch outside the band) before considering the inside-band number + at all. + +--- + +### Task 17: Final visual gate (USER-ATTESTED) + +**Files:** none — manual verification against the running dev server. + +**Steps:** + +- [ ] With the dev server running and the feature complete, focus Sgr A* and + descend into the lensing band. Verify, with the user, EACH of the + spec's five checklist items verbatim: + - [ ] shadow diameter reads as ~5.2 r_s (the EHT-consistent apparent size); + - [ ] an Einstein ring is visible on background stars crossing near the + shadow; + - [ ] doppler asymmetry favours the correct side of the annulus (the + approaching material's side, given the chosen inclination/position + angle); + - [ ] the fade band crossfades without a pop at either edge; + - [ ] the far-field glint hands off to the close-up without a visible seam. +- [ ] Report the outcome per item. Any failing item is a STOP — fix and + re-gate, not a partial ship. +- [ ] Only once every item passes AND Task 16's perf gate is clean does this + plan's feature work count as ready for `/feature-done`. + +--- + +## Definition of Done + +**Deliverable inventory:** +- Phase A: `SCENE_ANCHOR_POINT_BODIES`, `visibleSlabBodies`'s `{bodies}` + signature, the three-term `BODY_SLAB_CAPACITY`, `clampDistance`'s + `standoffRadii` param, `SGR_A_STAR.standoffRadii`, `RenderTargetSpec.fixedSizePx`. +- Phase B: `SGR_A_STAR_MASS_SOLAR`, `schwarzschildRadiusM`, `BlackHoleRow` + + `BLACK_HOLES`, `SCALE_FADE_BANDS.sgrAStarLensing`, the far-field glint + addition to `bodyGlintsLayer`, `SchwarzschildDeflectionLut` + + `buildSchwarzschildDeflectionLut`, the `sky-cubemap` render target row, + `CubeFace`, `skyCubemapFaceContext`, `skyCubemapCaptureSchedule`, the + `sgrAStarLensing` `ContentLayer` (WESL shader pair + TS renderer + + layer), the `CONTENT_LAYERS` reorder, `sgrAStarSchwarzschildRadiusKm.ts` + deleted with both its readers migrated. + +**Named observable behaviours (manual smoke pass):** +- Sgr A* shows a faint warm-orange glint from any distance while on screen, + with no mesh (confirms `AnchorPointBody`'s corrected docblock is honest). +- Descending inside 500 AU, the glint crossfades into a lensed close-up with + no pop; inside 100 AU the close-up is fully engaged. +- The close-up shows: a black shadow (~5.2 r_s), an Einstein ring on + background stars, a doppler-asymmetric emission annulus, and orbit + trails/S-star sprites/labels/marker rings drawn crisp and UNWARPED on top + (Q5 — lensing never touches annotations). +- The camera cannot descend past 2 r_s (Task 4's probe target, backed by + Task 2's `standoffRadii: 2.0`). +- Outside the band, `npm run perf` shows no measurable regression versus the + pre-feature baseline; inside the band, the cost is bounded, not runaway. + +**Deferral boundary (from the spec's non-goals — do not chase these):** +- No Kerr metric (Schwarzschild only). +- No full-GR observer view below 2 r_s (no local-frame aberration/redshift; + the descent floor stops the camera at the boundary where the shader's + static-viewpoint model is still defensible). +- No cinematic accretion disc (EHT-style faint glow only). +- No M87* or any second black hole (`BLACK_HOLES` holds room for one; not + populated here). +- No tour beat. +- No lensing of annotations (orbit trails, marker rings, labels, picking + stay unlensed, composited on top). +- No new user-facing settings. diff --git a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md index 7cf29bdd7b..ec95707c8f 100644 --- a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md +++ b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md @@ -364,9 +364,9 @@ walk, per captured face, per frame. Mitigations, restated from Q8/Q9: **Hard gate:** `npm run perf` before and after (read the `perf` skill first; worktree runs need `--url` against this worktree's own dev-server port). Zero delta expected outside the band; bounded, measured cost expected inside it. -A neutral-or-negative reading on either measurement halts the landing -pipeline per the project's code-is-liability convention — it does not get -waved through on the strength of the design. +A regression outside the band, or an unbounded/unacceptable cost inside it, +halts the landing pipeline per the project's code-is-liability convention — +it does not get waved through on the strength of the design. ### Settings From b2dcb9b4bbae55cbd58c4369c3ff855eda2e30c9 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 11:16:15 +0200 Subject: [PATCH 04/60] feat(bodies): admit anchor bodies as slab candidates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit visibleSlabBodies now takes a flat `bodies: readonly SceneBody[]` list instead of hardcoding `{earth, planets}` and concatenating internally — the caller assembles the candidate list, so an AnchorPointBody (Sgr A*) can join the roster on the same frustum/pixel-cull terms as a planet. BODY_SLAB_CAPACITY sums the same three sources. Zero behaviour change for every existing scene: the anchor's culls reject it at any sane viewing distance, and the new SCENE_ANCHOR_POINT_BODIES array mirrors SCENE_PLANETS so a second anchor is a data append, not a call-site edit. Also corrects the stale "DRAWS NOTHING" docblock claim in AnchorPointBody.d.ts and sgr-a-star.ts — a future anchor may draw a far-field glint and lensing-band geodesic pass via dedicated ContentLayer rows. Co-Authored-By: Claude Fable 5 --- src/@types/scene/AnchorPointBody.d.ts | 8 ++-- src/data/bodies/sceneAnchorPointBodies.ts | 11 +++++ src/data/sources/sgr-a-star.ts | 9 ++-- src/services/engine/frame/frameContext.ts | 11 ++++- src/services/engine/frame/frameProgram.ts | 10 ++-- .../engine/frame/visibleSlabBodies.ts | 19 ++++---- tests/data/bodies/orientationForBody.test.ts | 8 ++++ .../engine/frame/visibleSlabBodies.test.ts | 48 ++++++++++++++----- 8 files changed, 88 insertions(+), 36 deletions(-) create mode 100644 src/data/bodies/sceneAnchorPointBodies.ts diff --git a/src/@types/scene/AnchorPointBody.d.ts b/src/@types/scene/AnchorPointBody.d.ts index 694b21e4bd..ca61b60491 100644 --- a/src/@types/scene/AnchorPointBody.d.ts +++ b/src/@types/scene/AnchorPointBody.d.ts @@ -1,7 +1,9 @@ /** - * AnchorPointBody — a scene body that is positioned, named and selectable but - * DRAWS NOTHING: no mesh, no point, no glint. Its whole on-screen presence is - * its caption. + * AnchorPointBody — a scene body that is positioned, named and selectable. + * Today it draws only its caption; a future anchor may also draw a far-field + * glint and, inside its lensing band, a geodesic pass — both via dedicated + * `ContentLayer` rows keyed on its id, never via the flat/textured/glint + * partition planets use. * * Identity fields only, so a record cannot carry photometry or a texture it has * no renderer for. That is the difference from `StarBody`, whose `absMag` / diff --git a/src/data/bodies/sceneAnchorPointBodies.ts b/src/data/bodies/sceneAnchorPointBodies.ts new file mode 100644 index 0000000000..d10be67514 --- /dev/null +++ b/src/data/bodies/sceneAnchorPointBodies.ts @@ -0,0 +1,11 @@ +/** + * SCENE_ANCHOR_POINT_BODIES — every `AnchorPointBody` slab-candidacy + * (`visibleSlabBodies`) and capacity accounting (`BODY_SLAB_CAPACITY`) walk. + * Mirrors `SCENE_PLANETS`'s shape so a second anchor (e.g. M87*) is a data + * append here, not a second call-site edit. + */ + +import { SGR_A_STAR } from './sceneSgrAStar'; +import type { AnchorPointBody } from '../../@types/scene/AnchorPointBody'; + +export const SCENE_ANCHOR_POINT_BODIES: readonly AnchorPointBody[] = [SGR_A_STAR]; diff --git a/src/data/sources/sgr-a-star.ts b/src/data/sources/sgr-a-star.ts index 67498b7387..daf1721b01 100644 --- a/src/data/sources/sgr-a-star.ts +++ b/src/data/sources/sgr-a-star.ts @@ -5,10 +5,11 @@ import { Source } from '../source'; * Sagittarius A\* — the Galactic Centre's supermassive black hole, and the * focus every S-star orbit hangs off. * - * It DRAWS NOTHING: no sphere, no point, no glint. Its whole on-screen presence - * is its caption, so `bearsLabel` is the one capability flag that matters here - * and the caption production path (`captionPriority` / `captionFadeRules` / - * `sceneBodyLabels`) is where its visibility actually lives. + * Today it draws only its caption, so `bearsLabel` is the one capability flag + * that matters here and the caption production path (`captionPriority` / + * `captionFadeRules` / `sceneBodyLabels`) is where its visibility actually + * lives. A future far-field glint and lensing-band geodesic pass ride + * dedicated `ContentLayer` rows keyed on its id, not this flag. * * Its own registry row rather than a member of the curated star map, for the * reason the Sun's row records: a row makes the star map's gate a plain diff --git a/src/services/engine/frame/frameContext.ts b/src/services/engine/frame/frameContext.ts index 914ad9e1b0..b7320c4452 100644 --- a/src/services/engine/frame/frameContext.ts +++ b/src/services/engine/frame/frameContext.ts @@ -91,6 +91,7 @@ import type { CameraPose } from '../../../@types/camera/CameraPose'; import type { CameraProjection } from '../../../@types/camera/CameraProjection'; import type { Mat3 } from '../../../@types/math/Mat3'; import type { BodyPoseProvider } from '../../../@types/engine/camera/BodyPoseProvider'; +import type { SceneBody } from '../../../@types/scene/SceneBody'; import { computeViewProj } from '../../../utils/camera/computeViewProj'; import { imagePlaneBasis } from '../../../utils/camera/imagePlaneBasis'; import { frameUp } from '../../../utils/camera/frameUp'; @@ -105,6 +106,7 @@ import { ZERO_FOCUS } from '../subsystems/structureFocusSubsystem'; import { deriveSlabs } from './slabs'; import { deriveBodyStates } from './deriveBodyStates'; import { visibleSlabBodies } from './visibleSlabBodies'; +import { SCENE_ANCHOR_POINT_BODIES } from '../../../data/bodies/sceneAnchorPointBodies'; import { visibleStars } from './visibleStars'; import { partitionStarsByResolution, STAR_RESOLVE_PX } from './partitionStarsByResolution'; @@ -198,9 +200,14 @@ export function deriveFrameContext( cam.target[2] - cam.position[2], ]); + const { earth, planets } = state.data.bodies; + const slabBodyCandidates: readonly SceneBody[] = + earth === null + ? [...planets, ...SCENE_ANCHOR_POINT_BODIES] + : [earth, ...planets, ...SCENE_ANCHOR_POINT_BODIES]; + const visibleBodies = visibleSlabBodies({ - earth: state.data.bodies.earth, - planets: state.data.bodies.planets, + bodies: slabBodyCandidates, bodyStates, camPosMpc: cam.position, camForwardMpc: camForward, diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index b7b6f89c9e..13468940b8 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -66,15 +66,17 @@ import type { ToneMap } from '../../../@types/rendering/ToneMap'; import { COSMO, NEAR0, groupKeyOf, isBodySlabIndex, layerTimingSlotName, slabName } from './slabs'; import { CONTENT_LAYERS } from './passes'; import { SCENE_PLANETS } from '../../../data/bodies/scenePlanets'; +import { SCENE_ANCHOR_POINT_BODIES } from '../../../data/bodies/sceneAnchorPointBodies'; /** * Upper bound on body rows `deriveSlabs` can emit in one frame: Earth (the * NEAR0-adjacent body baked into `earthLayer`, not a `SCENE_PLANETS` row) - * plus every `SCENE_PLANETS` entry. `TIMED_SLOTS` allocates one slot per - * capacity row (not per row actually drawn this frame) so the query-set size - * is a compile-time constant — see `createGpuTimingService`. + * plus every `SCENE_PLANETS` entry plus every `SCENE_ANCHOR_POINT_BODIES` + * entry. `TIMED_SLOTS` allocates one slot per capacity row (not per row + * actually drawn this frame) so the query-set size is a compile-time + * constant — see `createGpuTimingService`. */ -export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length; +export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_BODIES.length; /** * Build this frame's step program. `tone` is threaded into the LONE tone-map — diff --git a/src/services/engine/frame/visibleSlabBodies.ts b/src/services/engine/frame/visibleSlabBodies.ts index 7f1476dbdf..a51f666f07 100644 --- a/src/services/engine/frame/visibleSlabBodies.ts +++ b/src/services/engine/frame/visibleSlabBodies.ts @@ -1,6 +1,4 @@ import type { BodyState } from '../../../@types/scene/BodyState'; -import type { EarthBody } from '../../../@types/scene/EarthBody'; -import type { PlanetBody } from '../../../@types/scene/PlanetBody'; import type { SceneBody } from '../../../@types/scene/SceneBody'; import type { Vec3 } from '../../../@types/math/Vec3'; import { bodyApparentDiameterPx } from '../../../utils/scene/bodyApparentDiameterPx'; @@ -10,9 +8,9 @@ import { SCALE_UNITS } from '../../../data/scaleUnits'; import { SUB_PIXEL_BODY_CULL_PX } from './subPixelBodyCullPx'; /** - * visibleSlabBodies — which of `[earth, ...planets]` get a body slab row this - * frame: apparent diameter clears `SUB_PIXEL_BODY_CULL_PX` (spec §4) AND the - * body's angular disc reaches inside the view frustum — off-axis angle minus + * visibleSlabBodies — which of `bodies` get a body slab row this frame: + * apparent diameter clears `SUB_PIXEL_BODY_CULL_PX` (spec §4) AND the body's + * angular disc reaches inside the view frustum — off-axis angle minus * angular radius, vs. the frustum half-diagonal, never a projected-CENTRE * test (`saturn-vanish-investigation.md` Phase 2: centre/clip-axis confusion * is exactly the bug class this avoids). Both culls key on the SAME `rEffM` @@ -21,11 +19,12 @@ import { SUB_PIXEL_BODY_CULL_PX } from './subPixelBodyCullPx'; * the pixel floor while the bare globe doesn't, and this roster gate runs * upstream of any per-layer gate that might otherwise still draw it (radar * frame finding 2). A missing `bodyStates` entry is dropped, not thrown - * (feeds a slab COUNT the frame program pool-sizes from, spec §6). + * (feeds a slab COUNT the frame program pool-sizes from, spec §6). The + * candidate list is the caller's to assemble — this gate treats every + * `SceneBody` union arm identically, culling on its shared `radiusM`/`id`. */ export function visibleSlabBodies(input: { - readonly earth: EarthBody | null; - readonly planets: readonly PlanetBody[]; + readonly bodies: readonly SceneBody[]; readonly bodyStates: ReadonlyMap; readonly camPosMpc: Readonly; readonly camForwardMpc: Readonly; @@ -34,8 +33,7 @@ export function visibleSlabBodies(input: { readonly fovYRad: number; }): readonly SceneBody[] { const { - earth, - planets, + bodies: candidates, bodyStates, camPosMpc, camForwardMpc, @@ -43,7 +41,6 @@ export function visibleSlabBodies(input: { viewportHeightPx, fovYRad, } = input; - const candidates: readonly SceneBody[] = earth === null ? planets : [earth, ...planets]; // Half-diagonal (corner, not edge — the widest off-axis angle a fully // on-screen body can have), padded by FRUSTUM_CULL_MARGIN_FACTOR: this is diff --git a/tests/data/bodies/orientationForBody.test.ts b/tests/data/bodies/orientationForBody.test.ts index 1f583d6033..3e0fd639a5 100644 --- a/tests/data/bodies/orientationForBody.test.ts +++ b/tests/data/bodies/orientationForBody.test.ts @@ -43,4 +43,12 @@ describe('orientationForBody', () => { expect(orientationForBody('titan', CONST_J2000)).toEqual([...IDENTITY_MAT3]); expect(orientationForBody('titan', CONST_J2000 + 5000)).toEqual([...IDENTITY_MAT3]); }); + + it('returns identity for the Sgr A* anchor', () => { + // Sgr A* is not in BODY_TEXTURE_REGISTRY, so the membership gate above + // already returns identity for it. This pins that fact so a future + // accidental texture-registry entry for 'sgr-a-star' can't silently + // rotate the body-slab basis bodyRelativePose builds from it. + expect(orientationForBody('sgr-a-star', CONST_J2000)).toEqual([...IDENTITY_MAT3]); + }); }); diff --git a/tests/services/engine/frame/visibleSlabBodies.test.ts b/tests/services/engine/frame/visibleSlabBodies.test.ts index b492a566bf..927899dbb3 100644 --- a/tests/services/engine/frame/visibleSlabBodies.test.ts +++ b/tests/services/engine/frame/visibleSlabBodies.test.ts @@ -11,6 +11,7 @@ import { SCENE_PLANETS } from '../../../../src/data/bodies/scenePlanets'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import { PROXY_SCALE } from '../../../../src/utils/scene/proxyScale'; import type { PlanetBody } from '../../../../src/@types/scene/PlanetBody'; +import type { AnchorPointBody } from '../../../../src/@types/scene/AnchorPointBody'; import type { BodyState } from '../../../../src/@types/scene/BodyState'; import type { Vec3 } from '../../../../src/@types/math/Vec3'; @@ -55,8 +56,7 @@ describe('visibleSlabBodies', () => { ]); const visible = visibleSlabBodies({ - earth: null, - planets: [belowFloor, aboveFloor], + bodies: [belowFloor, aboveFloor], bodyStates, camPosMpc: [0, 0, 0], camForwardMpc: FORWARD_X, @@ -79,8 +79,7 @@ describe('visibleSlabBodies', () => { const bodyStates = new Map([['earth', makeState()]]); const visible = visibleSlabBodies({ - earth, - planets: [orphan], + bodies: [earth, orphan], bodyStates, camPosMpc: [1000, 0, 0], // camera AT earth's stored position ⇒ distance 0 ⇒ inside its own shell, always kept camForwardMpc: FORWARD_X, @@ -107,8 +106,7 @@ describe('visibleSlabBodies', () => { const bodyStates = new Map([['saturn', makeState([dMpc, 0, 0])]]); const visible = visibleSlabBodies({ - earth: null, - planets: [saturn], + bodies: [saturn], bodyStates, camPosMpc: [0, 0, 0], camForwardMpc: FORWARD_X, @@ -138,8 +136,7 @@ describe('visibleSlabBodies', () => { ['wide', makeState(offAxisPositionMpc(offAxisDeg, distanceMpc))], ]); return visibleSlabBodies({ - earth: null, - planets: [wideBody], + bodies: [wideBody], bodyStates, camPosMpc: [0, 0, 0], camForwardMpc: FORWARD_X, @@ -180,8 +177,7 @@ describe('visibleSlabBodies', () => { ]); const visible = visibleSlabBodies({ - earth: null, - planets: [straddling], + bodies: [straddling], bodyStates, camPosMpc: [0, 0, 0], camForwardMpc: FORWARD_X, @@ -209,8 +205,7 @@ describe('visibleSlabBodies', () => { ]); const visible = visibleSlabBodies({ - earth: null, - planets: [saturn], + bodies: [saturn], bodyStates, camPosMpc: [0, 0, 0], camForwardMpc: FORWARD_X, @@ -222,4 +217,33 @@ describe('visibleSlabBodies', () => { expect(visible.map((b) => b.id)).toEqual(['saturn']); }); }); + + it('admits an AnchorPointBody candidate on the same terms as a planet', () => { + const visibleAnchor: AnchorPointBody = { + id: 'visible-anchor', + label: 'Visible anchor', + radiusM: 3.2e22, + }; + const hiddenAnchor: AnchorPointBody = { + id: 'hidden-anchor', + label: 'Hidden anchor', + radiusM: 3.2e22, + }; + const bodyStates = new Map([ + ['visible-anchor', makeState()], + ['hidden-anchor', makeState(offAxisPositionMpc(180, 1000))], + ]); + + const visible = visibleSlabBodies({ + bodies: [visibleAnchor, hiddenAnchor], + bodyStates, + camPosMpc: [0, 0, 0], + camForwardMpc: FORWARD_X, + viewportWidthPx: 1000, + viewportHeightPx: 1000, + fovYRad: Math.PI / 2, + }); + + expect(visible.map((body) => body.id)).toEqual(['visible-anchor']); + }); }); From 23969f785a4b9f95513a7d12ab66d9b5e23a5f94 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 11:22:47 +0200 Subject: [PATCH 05/60] feat(render-targets): add fixedSizePx for canvas-independent multi-layer targets Adds the RenderTargetSpec.fixedSizePx field and the reconcile/allocate branch that honours it, ahead of the sky-cubemap target row that needs a fixed 2d-array texture regardless of canvas size (Phase B). No production row sets it yet; createRenderTargets gains a test-only extraRows injection seam so the branch is exercisable now. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/RenderTargetSpec.d.ts | 8 ++ src/services/gpu/renderTargets.ts | 23 +++++- tests/services/gpu/renderTargets.test.ts | 74 ++++++++++++++++--- 3 files changed, 90 insertions(+), 15 deletions(-) diff --git a/src/@types/engine/frame/RenderTargetSpec.d.ts b/src/@types/engine/frame/RenderTargetSpec.d.ts index fc2fdfbdd1..cf9c3efdf7 100644 --- a/src/@types/engine/frame/RenderTargetSpec.d.ts +++ b/src/@types/engine/frame/RenderTargetSpec.d.ts @@ -37,4 +37,12 @@ export type RenderTargetSpec = { * pass, not fixed table data. */ clearValue: GPUColor; + /** + * When present, this row's pixel size is `fixedSizePx.size` on each axis + * regardless of canvas size, and its texture has `fixedSizePx.layers` + * array layers (a `2d-array` texture, sampled as `texture_cube` by a + * consumer that binds all six as a cube — WebGPU has no cube-view render + * attachment). `scale` is ignored when this is present. + */ + fixedSizePx?: { readonly size: number; readonly layers: number }; }; diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 73f1297cb8..321615d966 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -267,10 +267,15 @@ export function createRenderTargets( swapFormat: GPUTextureFormat, size: Size, state: EngineState, + // Test-only injection seam: appends rows the production table + // (`renderTargetRows`) doesn't declare yet, so `fixedSizePx` behaviour is + // exercisable before Phase B lands the real sky-cubemap row. No production + // caller passes this. + extraRows: readonly RenderTargetSpec[] = [], ): RenderTargets { // `let`, not `const`: setSwapFormat below replaces this array wholesale // rather than mutating a row in place (house preference for immutability). - let specs = renderTargetRows(swapFormat); + let specs = [...renderTargetRows(swapFormat), ...extraRows]; // Only offscreen rows get textures — the swap row is executor-resolved // from the acquired frame view (see the module header). Computed once: // setSwapFormat never touches an offscreen row, so this stays valid. @@ -297,7 +302,11 @@ export function createRenderTargets( const texture = device.createTexture({ label: `render-target-${spec.id}`, format: spec.format, - size: { width, height }, + // 'dimension: 2d' is WebGPU's default, but stated explicitly so a + // `fixedSizePx.layers > 1` row (a 2d-array texture, e.g. the sky + // cubemap's 6 faces) reads unambiguously beside `depthOrArrayLayers`. + dimension: '2d', + size: { width, height, depthOrArrayLayers: spec.fixedSizePx?.layers ?? 1 }, // RENDER_ATTACHMENT lets the content layers' pipelines write into the // target; TEXTURE_BINDING lets the compositor / upsample fragment // shaders sample from it — for 'foreground:0' this is ALSO what the @@ -314,7 +323,8 @@ export function createRenderTargets( const depthTexture = device.createTexture({ label: `render-target-${spec.id}-depth`, format: spec.depth, - size: { width, height }, + dimension: '2d', + size: { width, height, depthOrArrayLayers: spec.fixedSizePx?.layers ?? 1 }, // RENDER_ATTACHMENT only: this feeds the depth-test while the // foreground pass draws opaque geometry, and nothing samples it // downstream any more. The caption occlusion pass (lib/sceneDepth.wesl) @@ -337,7 +347,12 @@ export function createRenderTargets( // (`reducedTargetSize` is the shared sizing rule; see its docblock.) function reconcile(s: EngineState, canvas: Size): void { for (const spec of offscreenSpecs) { - const [width, height] = reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s)); + // A fixed-size row is a size that never changes across resizes, not a + // separate code path past this one branch: the held-size comparison + // and `allocate` call below stay shared with every other row. + const [width, height] = spec.fixedSizePx + ? [spec.fixedSizePx.size, spec.fixedSizePx.size] + : reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s)); const held = sizes.get(spec.id); if (held !== undefined && held.width === width && held.height === height) continue; allocate(spec, width, height); diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index 6486fb8397..7c1af39ec6 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -11,6 +11,7 @@ import { describe, it, expect, vi } from 'vitest'; import { createRenderTargets } from '../../../src/services/gpu/renderTargets'; import type { EngineState } from '../../../src/@types/engine/state/EngineState'; +import type { RenderTargetSpec } from '../../../src/@types/engine/frame/RenderTargetSpec'; function mockDevice(): GPUDevice { return { @@ -32,6 +33,19 @@ function stateWithDivisor(aggregateDivisor: number): EngineState { return { settings: { milkyWay: { aggregateDivisor } } } as unknown as EngineState; } +// `fixedSizePx` has no row in the production table yet (Phase B adds the +// real sky-cubemap row); `createRenderTargets`'s 5th `extraRows` param is a +// test-only injection seam so the allocation branch can be exercised now. +// No production caller passes it. +const FIXED_SIZE_ROW: RenderTargetSpec = { + id: 'test:cubemap', + format: 'rgba16float', + depth: null, + scale: 1, + clearValue: { r: 0, g: 0, b: 0, a: 0 }, + fixedSizePx: { size: 256, layers: 6 }, +}; + describe('createRenderTargets', () => { it('viewOf returns a live view per offscreen row and throws for swap', () => { const targets = createRenderTargets( @@ -72,9 +86,9 @@ describe('createRenderTargets', () => { const aggDesc = create.mock.calls.find( (c) => c[0].label === 'render-target-star-aggregates', )![0]; - expect(hdrDesc.size).toEqual({ width: 900, height: 600 }); - expect(volDesc.size).toEqual({ width: 300, height: 200 }); - expect(aggDesc.size).toEqual({ width: 450, height: 300 }); + expect(hdrDesc.size).toEqual({ width: 900, height: 600, depthOrArrayLayers: 1 }); + expect(volDesc.size).toEqual({ width: 300, height: 200, depthOrArrayLayers: 1 }); + expect(aggDesc.size).toEqual({ width: 450, height: 300, depthOrArrayLayers: 1 }); expect(hdrDesc.format).toBe('rgba16float'); expect(volDesc.format).toBe('rgba16float'); expect(aggDesc.format).toBe('rgba16float'); @@ -95,15 +109,53 @@ describe('createRenderTargets', () => { const aggResized = create.mock.calls .filter((c) => c[0].label === 'render-target-star-aggregates') .at(-1)![0]; - expect(hdrResized.size).toEqual({ width: 1200, height: 900 }); - expect(volResized.size).toEqual({ width: 400, height: 300 }); - expect(aggResized.size).toEqual({ width: 600, height: 450 }); + expect(hdrResized.size).toEqual({ width: 1200, height: 900, depthOrArrayLayers: 1 }); + expect(volResized.size).toEqual({ width: 400, height: 300, depthOrArrayLayers: 1 }); + expect(aggResized.size).toEqual({ width: 600, height: 450, depthOrArrayLayers: 1 }); // New views replaced the old ones. expect(targets.viewOf('hdr')).not.toBe(hdrViewBefore); expect(targets.viewOf('volume')).not.toBe(volViewBefore); expect(targets.viewOf('star-aggregates')).not.toBe(aggViewBefore); }); + it('a fixedSizePx row allocates at its declared size regardless of canvas size', () => { + const device = mockDevice(); + const create = device.createTexture as ReturnType; + createRenderTargets( + device, + SWAP_FORMAT, + { width: 900, height: 600 }, + stateWithDivisor(MW_DIVISOR), + [FIXED_SIZE_ROW], + ); + + const desc = create.mock.calls.find((c) => c[0].label === 'render-target-test:cubemap')![0]; + expect(desc.size).toEqual({ width: 256, height: 256, depthOrArrayLayers: 6 }); + expect(desc.dimension).toBe('2d'); + }); + + it('reconcile does not reallocate a fixedSizePx row when the canvas resizes', () => { + const device = mockDevice(); + const create = device.createTexture as ReturnType; + const targets = createRenderTargets( + device, + SWAP_FORMAT, + { width: 900, height: 600 }, + stateWithDivisor(MW_DIVISOR), + [FIXED_SIZE_ROW], + ); + const callsBefore = create.mock.calls.filter( + (c) => c[0].label === 'render-target-test:cubemap', + ).length; + + targets.reconcile(stateWithDivisor(MW_DIVISOR), { width: 1200, height: 900 }); + + const callsAfter = create.mock.calls.filter( + (c) => c[0].label === 'render-target-test:cubemap', + ).length; + expect(callsAfter).toBe(callsBefore); + }); + it("reconcile reallocates a row whose state-driven scale moved and leaves the other rows' views untouched", () => { const device = mockDevice(); const create = device.createTexture as ReturnType; @@ -126,7 +178,7 @@ describe('createRenderTargets', () => { const mwResized = create.mock.calls .filter((c) => c[0].label === 'render-target-mw-aggregate') .at(-1)![0]; - expect(mwResized.size).toEqual({ width: 200, height: 150 }); + expect(mwResized.size).toEqual({ width: 200, height: 150, depthOrArrayLayers: 1 }); expect(targets.sizeOf('mw-aggregate')).toEqual({ width: 200, height: 150 }); // Exactly one row moved: one new texture, and every other row's view is // still the object its consumers resolved before the call. @@ -160,7 +212,7 @@ describe('createRenderTargets', () => { createRenderTargets(device, SWAP_FORMAT, { width: 2, height: 2 }, stateWithDivisor(MW_DIVISOR)); const volDesc = create.mock.calls.find((c) => c[0].label === 'render-target-volume')![0]; // floor(2 / 3) = 0 → clamped up to 1. - expect(volDesc.size).toEqual({ width: 1, height: 1 }); + expect(volDesc.size).toEqual({ width: 1, height: 1, depthOrArrayLayers: 1 }); }); it('allocates and resizes a depth texture alongside colour for rows that declare depth', () => { @@ -180,9 +232,9 @@ describe('createRenderTargets', () => { (c) => c[0].label === 'render-target-foreground:0-depth', )![0]; expect(fgColour.format).toBe('rgba16float'); - expect(fgColour.size).toEqual({ width: 800, height: 600 }); + expect(fgColour.size).toEqual({ width: 800, height: 600, depthOrArrayLayers: 1 }); expect(fgDepth.format).toBe('depth32float'); - expect(fgDepth.size).toEqual({ width: 800, height: 600 }); + expect(fgDepth.size).toEqual({ width: 800, height: 600, depthOrArrayLayers: 1 }); // Depth carries ONLY RENDER_ATTACHMENT (feeds the depth-test) — nothing // samples it downstream any more (each painter-chain row clears its own // depth, spec §7.3, so it can't back a cross-row occlusion test). @@ -203,7 +255,7 @@ describe('createRenderTargets', () => { const fgDepthResized = create.mock.calls .filter((c) => c[0].label === 'render-target-foreground:0-depth') .at(-1)![0]; - expect(fgDepthResized.size).toEqual({ width: 1024, height: 768 }); + expect(fgDepthResized.size).toEqual({ width: 1024, height: 768, depthOrArrayLayers: 1 }); expect( create.mock.calls.filter((c) => c[0].label === 'render-target-foreground:0-depth').length, ).toBe(depthCallsBefore + 1); From f92f9edcdc6bfb408b7d172222395ec373282763 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 11:24:14 +0200 Subject: [PATCH 06/60] fix(bodies): update stale visibleSlabBodies test header comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding: the test file's module-header comment still described the pre-change `[earth, ...planets]` signature after task 1's `{ bodies }` param rename — mirrors the src file's already-correct header at visibleSlabBodies.ts:11. Co-Authored-By: Claude Fable 5 --- tests/services/engine/frame/visibleSlabBodies.test.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/services/engine/frame/visibleSlabBodies.test.ts b/tests/services/engine/frame/visibleSlabBodies.test.ts index 927899dbb3..b17c58dc5b 100644 --- a/tests/services/engine/frame/visibleSlabBodies.test.ts +++ b/tests/services/engine/frame/visibleSlabBodies.test.ts @@ -1,7 +1,7 @@ /** - * visibleSlabBodies — which of `[earth, ...planets]` clear the sub-pixel - * apparent-diameter floor AND the view-frustum angular cull, and so get a - * body slab row this frame. + * visibleSlabBodies — which of `bodies` clear the sub-pixel apparent-diameter + * floor AND the view-frustum angular cull, and so get a body slab row this + * frame. */ import { describe, it, expect } from 'vitest'; From cc1d7f31d2b8f5110e611b7e7135cc065586c706 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 11:37:12 +0200 Subject: [PATCH 07/60] feat(camera): per-body standoff floor, wired to Sgr A*'s 2 r_s MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit clampDistance gains an optional standoffRadii third param (default SURFACE_STANDOFF_RADII) so a focused body can override the Earth-tuned global zoom floor. AnchorPointBody carries the override; SGR_A_STAR sets it to 2.0 (Q10's descent floor). Threaded through the zoom path that actually reaches clampDistance for a focused body — zoomedDistance/zoomedPose, applyWheelZoom, and both attachOrbitControls zoom sites (pinch, wheel-during-gesture) — via a new pivotStandoffRadii(row) helper mirroring pivotRadiusMpc, read the same way in wireInput.ts. Every other body (no override) falls through to the existing default unchanged. Co-Authored-By: Claude Fable 5 --- src/@types/camera/OrbitControlsOptions.d.ts | 7 ++ src/@types/engine/SelectionRow.d.ts | 3 + src/@types/scene/AnchorPointBody.d.ts | 2 + src/data/bodies/sceneSgrAStar.ts | 3 + src/services/camera/orbitControls.ts | 13 ++- src/services/engine/camera/applyWheelZoom.ts | 21 +++- .../engine/camera/pivotStandoffRadii.ts | 17 +++ .../engine/helpers/extractSelectionRow.ts | 2 + src/services/engine/phases/wireInput.ts | 6 ++ src/utils/camera/clampDistance.ts | 12 ++- src/utils/camera/zoomedDistance.ts | 11 +- src/utils/camera/zoomedPose.ts | 6 +- tests/services/camera/orbitControls.test.ts | 100 +++++++++++++++++- .../engine/camera/pivotStandoffRadii.test.ts | 58 ++++++++++ .../services/engine/phases/wireInput.test.ts | 34 ++++++ tests/utils/camera/clampDistance.test.ts | 22 ++++ 16 files changed, 304 insertions(+), 13 deletions(-) create mode 100644 src/services/engine/camera/pivotStandoffRadii.ts create mode 100644 tests/services/engine/camera/pivotStandoffRadii.test.ts diff --git a/src/@types/camera/OrbitControlsOptions.d.ts b/src/@types/camera/OrbitControlsOptions.d.ts index 0f4966fc0c..16f4878691 100644 --- a/src/@types/camera/OrbitControlsOptions.d.ts +++ b/src/@types/camera/OrbitControlsOptions.d.ts @@ -70,6 +70,13 @@ export type OrbitControlsOptions = { * (tests, or no scene) ⇒ only the global floor applies. */ pivotRadiusMpc?: () => number | null; + /** + * Per-pivot override of `clampDistance`'s global `SURFACE_STANDOFF_RADII` + * (e.g. Sgr A*'s Q10 floor of 2 r_s), read alongside `pivotRadiusMpc` at the + * same two call sites. A getter for the same reason; the engine wires it to + * `pivotStandoffRadii(selectFocusRow(...))`. Omitted ⇒ the global ratio. + */ + standoffRadii?: () => number; /** * Called on the first pointer contact that begins a new gesture (i.e. when * `activePointers.size === 1` on `pointerdown`). Subsequent fingers (pinch diff --git a/src/@types/engine/SelectionRow.d.ts b/src/@types/engine/SelectionRow.d.ts index a2ae97347a..4ebdc1d9a9 100644 --- a/src/@types/engine/SelectionRow.d.ts +++ b/src/@types/engine/SelectionRow.d.ts @@ -31,6 +31,9 @@ export type SelectionRow = readonly label: string; readonly positionMpc: Vec3; readonly radiusM: number; + // Carried through from `AnchorPointBody.standoffRadii` (e.g. Sgr A*'s + // Q10 floor) — the zoom clamp reads it via `pivotStandoffRadii`. + readonly standoffRadii?: number; } // Star arm — the self-contained display projection of a picked star, its // physical fields (`positionMpc`/`absMag`/`bpRp`) snapshotted off the loaded diff --git a/src/@types/scene/AnchorPointBody.d.ts b/src/@types/scene/AnchorPointBody.d.ts index ca61b60491..723b82d360 100644 --- a/src/@types/scene/AnchorPointBody.d.ts +++ b/src/@types/scene/AnchorPointBody.d.ts @@ -19,4 +19,6 @@ export type AnchorPointBody = { readonly id: string; readonly label: string; readonly radiusM: number; + /** Per-body override of `clampDistance`'s Earth-tuned `SURFACE_STANDOFF_RADII` — e.g. Sgr A*'s Q10 floor of 2 r_s. */ + readonly standoffRadii?: number; }; diff --git a/src/data/bodies/sceneSgrAStar.ts b/src/data/bodies/sceneSgrAStar.ts index 0157971c1d..dd5508ba42 100644 --- a/src/data/bodies/sceneSgrAStar.ts +++ b/src/data/bodies/sceneSgrAStar.ts @@ -39,6 +39,9 @@ export const SGR_A_STAR: AnchorPointBody = { label: SGR_A_STAR_ENTRY.label, // Wire/authored value is km; runtime convention is metres. radiusM: SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM * SCALE_UNITS.KM_TO_M, + // Q10's descent floor: the camera may approach to 2 r_s, well inside the + // Earth-tuned global SURFACE_STANDOFF_RADII (~1.0000024). + standoffRadii: 2.0, }; export const SGR_A_STAR_ANCHOR: AnchorBody = { diff --git a/src/services/camera/orbitControls.ts b/src/services/camera/orbitControls.ts index 0de4cc73a5..82d1fd410f 100644 --- a/src/services/camera/orbitControls.ts +++ b/src/services/camera/orbitControls.ts @@ -198,6 +198,10 @@ export function attachOrbitControls( // live through the caller's getter rather than cached, since this module // never sees the scene and focus can change while controls stay attached. const pivotRadius = (): number | null => options?.pivotRadiusMpc?.() ?? null; + // Same live-read reasoning, for the per-pivot standoff override (e.g. Sgr + // A*'s 2 r_s floor). Undefined (no getter, or the getter's own default) + // reaches `zoomedDistance`'s own default unchanged. + const standoffRadius = (): number | undefined => options?.standoffRadii?.(); // ── Pointer down — begin drag ────────────────────────────────────────────── @@ -361,7 +365,12 @@ export function attachOrbitControls( if (activePointers.size < 2 || lastPinchDist === 0) return; const newDist = currentPinchDistance(); if (newDist > 0) { - cam.distance = zoomedDistance(cam.distance, lastPinchDist / newDist, pivotRadius()); + cam.distance = zoomedDistance( + cam.distance, + lastPinchDist / newDist, + pivotRadius(), + standoffRadius(), + ); lastPinchDist = newDist; updatePosition(cam); options?.onChange?.(); @@ -517,7 +526,7 @@ export function attachOrbitControls( // Wheel DURING a drag/pinch: fold the zoom into the live `cam` register. // The `orbitDrag` driver (priority 80) is active and renders `poseOf(cam)`, // so the zoom shows immediately and rides the `onGestureEnd` commit. - cam.distance = zoomedDistance(cam.distance, factor, pivotRadius()); + cam.distance = zoomedDistance(cam.distance, factor, pivotRadius(), standoffRadius()); updatePosition(cam); options?.onChange?.(); return; diff --git a/src/services/engine/camera/applyWheelZoom.ts b/src/services/engine/camera/applyWheelZoom.ts index e45f30a0db..f1f7f458b9 100644 --- a/src/services/engine/camera/applyWheelZoom.ts +++ b/src/services/engine/camera/applyWheelZoom.ts @@ -51,6 +51,10 @@ * to the centre. All three arms need it: follow orbits the body by definition, * and the autoRotate / resting arms orbit it too whenever the frame loop's * pivot-pin is centring them on it. + * + * `standoffRadii` is the same focused body's `pivotStandoffRadii` read, + * forwarded alongside `pivotRadiusMpc` for the same three arms — optional so + * every existing caller (no per-body override) reaches the shared default. */ import { autoRotateElapsed } from './cameraClock'; @@ -68,14 +72,25 @@ export function applyWheelZoom( autoRotate: { active: boolean; rate: number }, nowMs: number, pivotRadiusMpc: number | null, + standoffRadii?: number, ): CameraPose | null { if (prevActiveId === 'followBody' && clock.followDistanceTarget !== null) { - clock.followDistanceTarget = zoomedDistance(clock.followDistanceTarget, factor, pivotRadiusMpc); + clock.followDistanceTarget = zoomedDistance( + clock.followDistanceTarget, + factor, + pivotRadiusMpc, + standoffRadii, + ); return null; } if (prevActiveId === 'autoRotate') { const elapsed = autoRotateElapsed(clock, autoRotate.active, base, nowMs); - return zoomedPose(spinAutoRotate(base, autoRotate.rate, elapsed), factor, pivotRadiusMpc); + return zoomedPose( + spinAutoRotate(base, autoRotate.rate, elapsed), + factor, + pivotRadiusMpc, + standoffRadii, + ); } - return zoomedPose(base, factor, pivotRadiusMpc); + return zoomedPose(base, factor, pivotRadiusMpc, standoffRadii); } diff --git a/src/services/engine/camera/pivotStandoffRadii.ts b/src/services/engine/camera/pivotStandoffRadii.ts new file mode 100644 index 0000000000..f7ec327ef5 --- /dev/null +++ b/src/services/engine/camera/pivotStandoffRadii.ts @@ -0,0 +1,17 @@ +/** + * pivotStandoffRadii — the per-focus override of `clampDistance`'s global + * `SURFACE_STANDOFF_RADII`, read the same way `pivotRadiusMpc` reads the pivot + * radius: off a resolved `SelectionRow`'s 'body' arm (`AnchorPointBody. + * standoffRadii`, e.g. Sgr A*'s Q10 floor of 2 r_s). Every other row — + * including a survey star, which has no per-record override field — falls + * through to the global ratio, so this is a sibling read, not a branch on + * `pivotRadiusMpc`'s own result. + */ + +import { SURFACE_STANDOFF_RADII } from '../../../utils/camera/clampDistance'; +import type { SelectionRow } from '../../../@types/engine/SelectionRow'; + +export function pivotStandoffRadii(row: SelectionRow | null): number { + if (row === null || row.type !== 'body') return SURFACE_STANDOFF_RADII; + return row.standoffRadii ?? SURFACE_STANDOFF_RADII; +} diff --git a/src/services/engine/helpers/extractSelectionRow.ts b/src/services/engine/helpers/extractSelectionRow.ts index 29d0de19dc..d17b98d23c 100644 --- a/src/services/engine/helpers/extractSelectionRow.ts +++ b/src/services/engine/helpers/extractSelectionRow.ts @@ -60,6 +60,8 @@ const EXTRACT_ROW: { label: body.label, positionMpc: [p[0], p[1], p[2]], radiusM: body.radiusM, + // Only the AnchorPointBody arm of the SceneBody union carries this field. + standoffRadii: 'standoffRadii' in body ? body.standoffRadii : undefined, }; }, // The star's physical fields are resolved off the LIVE catalog through the diff --git a/src/services/engine/phases/wireInput.ts b/src/services/engine/phases/wireInput.ts index 547b2284fa..23ef6d1ee3 100644 --- a/src/services/engine/phases/wireInput.ts +++ b/src/services/engine/phases/wireInput.ts @@ -30,6 +30,7 @@ import { createOrbitCamera } from '../../../utils/camera/createOrbitCamera'; import { attachOrbitControls } from '../../camera/orbitControls'; import { applyWheelZoom } from '../camera/applyWheelZoom'; import { pivotRadiusMpc } from '../camera/pivotRadiusMpc'; +import { pivotStandoffRadii } from '../camera/pivotStandoffRadii'; import { seedCameraFromBase } from '../../camera/seedCameraFromBase'; import { constructGpuHandles } from '../gpuHandles/constructGpuHandles'; import { GPU_HANDLE_ROWS } from '../gpuHandles/gpuHandleRegistry'; @@ -349,6 +350,9 @@ export async function wireInput(state: EngineState, deps: BootstrapDeps): Promis // The zoom floor's input, read live off the resolved focus row — same // derivation the `onZoom` path below uses. pivotRadiusMpc: () => pivotRadiusMpc(selectFocusRow(store.getState())), + // The zoom floor's per-body override (e.g. Sgr A*'s Q10 floor) — same + // derivation the `onZoom` path below uses. + standoffRadii: () => pivotStandoffRadii(selectFocusRow(store.getState())), // Discrete wheel zoom (no gesture in progress). The zoom goes to whichever // driver owns the distance this frame: while a body is followed the @@ -374,6 +378,8 @@ export async function wireInput(state: EngineState, deps: BootstrapDeps): Promis // Floors the zoom just off a focused body's surface for every arm of // applyWheelZoom, not only the follow driver. pivotRadiusMpc(selectFocusRow(root)), + // Per-body override of that floor (e.g. Sgr A*'s Q10 floor). + pivotStandoffRadii(selectFocusRow(root)), ); if (zoomed !== null) store.dispatch(commitCameraPose(zoomed)); // Unconditional — the follow branch (applyWheelZoom.ts:72-75) mutates followDistanceTarget diff --git a/src/utils/camera/clampDistance.ts b/src/utils/camera/clampDistance.ts index 4497285d58..746e5e0cf9 100644 --- a/src/utils/camera/clampDistance.ts +++ b/src/utils/camera/clampDistance.ts @@ -60,18 +60,24 @@ export const MAX_DISTANCE_MPC = 30000; /** * Clamp a candidate distance to the zoom envelope: ceiling `MAX_DISTANCE_MPC`, - * floor `max(MIN_DISTANCE_MPC, pivotRadiusMpc · SURFACE_STANDOFF_RADII)`. + * floor `max(MIN_DISTANCE_MPC, pivotRadiusMpc · standoffRadii)`. * * @param d Candidate `cam.distance`, Mpc. * @param pivotRadiusMpc Physical radius of the orbit pivot, Mpc, or `null` when * it has no surface to stand off from (empty space, a galaxy, a structure, * the Milky Way — volumes the camera flies INTO, never a floor). + * @param standoffRadii Per-pivot override of `SURFACE_STANDOFF_RADII` — see + * `AnchorPointBody.standoffRadii` for why a body needs its own ratio. */ -export function clampDistance(d: number, pivotRadiusMpc: number | null): number { +export function clampDistance( + d: number, + pivotRadiusMpc: number | null, + standoffRadii: number = SURFACE_STANDOFF_RADII, +): number { const floor = pivotRadiusMpc === null ? MIN_DISTANCE_MPC - : Math.max(MIN_DISTANCE_MPC, pivotRadiusMpc * SURFACE_STANDOFF_RADII); + : Math.max(MIN_DISTANCE_MPC, pivotRadiusMpc * standoffRadii); if (d < floor) return floor; if (d > MAX_DISTANCE_MPC) return MAX_DISTANCE_MPC; return d; diff --git a/src/utils/camera/zoomedDistance.ts b/src/utils/camera/zoomedDistance.ts index 2426674164..f80ab1eb0b 100644 --- a/src/utils/camera/zoomedDistance.ts +++ b/src/utils/camera/zoomedDistance.ts @@ -19,14 +19,19 @@ * * `clampDistance` is called from inside here, not by the caller, so the * envelope stays enforced in exactly one place. + * + * `standoffRadii` is forwarded straight to every `clampDistance` call — + * optional so the flat-space arm and every existing caller (no per-body + * override) reach `clampDistance`'s own default unchanged. */ -import { clampDistance } from './clampDistance'; +import { clampDistance, SURFACE_STANDOFF_RADII } from './clampDistance'; export function zoomedDistance( distance: number, factor: number, pivotRadiusMpc: number | null, + standoffRadii: number = SURFACE_STANDOFF_RADII, ): number { if (pivotRadiusMpc === null) { return clampDistance(distance * factor, null); @@ -37,8 +42,8 @@ export function zoomedDistance( // Degenerate: `clampDistance` should prevent the camera reaching the // surface at all. Fall back to plain proportional scaling rather than // invent a geometric taper for a zero/negative altitude. - return clampDistance(distance * factor, pivotRadiusMpc); + return clampDistance(distance * factor, pivotRadiusMpc, standoffRadii); } - return clampDistance(pivotRadiusMpc + h * factor, pivotRadiusMpc); + return clampDistance(pivotRadiusMpc + h * factor, pivotRadiusMpc, standoffRadii); } diff --git a/src/utils/camera/zoomedPose.ts b/src/utils/camera/zoomedPose.ts index 439b4edb98..6955950ccf 100644 --- a/src/utils/camera/zoomedPose.ts +++ b/src/utils/camera/zoomedPose.ts @@ -17,6 +17,9 @@ * Pure by design: the wheel handler reads `camera.base` from the store, hands * it here, and dispatches the result — so the zoom arithmetic (and its clamp * behaviour) is unit-testable without a store, a canvas, or a render loop. + * + * `standoffRadii` forwards straight to `zoomedDistance`, optional for the same + * reason: every caller without a per-body override reaches the shared default. */ import { zoomedDistance } from './zoomedDistance'; @@ -26,11 +29,12 @@ export function zoomedPose( base: CameraPose, factor: number, pivotRadiusMpc: number | null, + standoffRadii?: number, ): CameraPose { return { target: [base.target[0], base.target[1], base.target[2]], yaw: base.yaw, pitch: base.pitch, - distance: zoomedDistance(base.distance, factor, pivotRadiusMpc), + distance: zoomedDistance(base.distance, factor, pivotRadiusMpc, standoffRadii), }; } diff --git a/tests/services/camera/orbitControls.test.ts b/tests/services/camera/orbitControls.test.ts index 669e0c4173..50409f5c49 100644 --- a/tests/services/camera/orbitControls.test.ts +++ b/tests/services/camera/orbitControls.test.ts @@ -38,7 +38,8 @@ * a discrete wheel zoom (no gesture) fires `onZoom` instead. * - `pivotRadiusMpc` reaches BOTH in-module clamp sites (pinch, and a wheel * during a held gesture), so a zoom-in on a framed body stops just off its - * surface instead of passing through the centre. + * surface instead of passing through the centre. `standoffRadii` reaches + * the same two sites for a body's own floor override (Sgr A*'s 2 r_s). * * Vitest runs in `node` here (no jsdom), so — matching * `inputBindings.test.ts` — we hand-roll EventTarget recorders for the @@ -472,6 +473,103 @@ describe('attachOrbitControls — the zoom floor stops at a focused body’s sur }); }); +describe('attachOrbitControls — the standoff override reaches both zoom sites', () => { + // Same two in-module sites as the surface-floor tests above, but exercising + // the `standoffRadii` getter (Sgr A*'s Q10 2 r_s floor is the real case): + // without it reaching pinch + wheel-during-gesture, a body with an override + // would still stop at the Earth-tuned global ratio instead of its own. + const STANDOFF = 3.0; // well above SURFACE_STANDOFF_RADII (~1.0000024) + + it('pinching in floors at the override, not the global ratio', () => { + const cam = makeCamera(); + cam.distance = EARTH_RADIUS_MPC * 10; + const { canvas, rec } = makeCanvas(); + + attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { + pivotRadiusMpc: () => EARTH_RADIUS_MPC, + standoffRadii: () => STANDOFF, + }); + + rec.fire('pointerdown', { + pointerId: 1, + pointerType: 'touch', + button: 0, + clientX: 0, + clientY: 0, + }); + rec.fire('pointerdown', { + pointerId: 2, + pointerType: 'touch', + button: 0, + clientX: 10, + clientY: 0, + }); + for (const x of [1000, 100000, 10000000]) { + win.fire('pointermove', { pointerId: 2, clientX: x, clientY: 0 }); + } + + const radii = cam.distance / EARTH_RADIUS_MPC; + expect(radii).toBeGreaterThanOrEqual(STANDOFF); + expect(radii).toBeLessThan(STANDOFF * 1.05); + }); + + it('a wheel tick during a held gesture floors at the override, not the global ratio', () => { + const cam = makeCamera(); + cam.distance = EARTH_RADIUS_MPC * 10; + const { canvas, rec } = makeCanvas(); + + attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { + pivotRadiusMpc: () => EARTH_RADIUS_MPC, + standoffRadii: () => STANDOFF, + }); + + rec.fire('pointerdown', { + pointerId: 1, + pointerType: 'mouse', + button: 0, + clientX: 100, + clientY: 100, + }); + rec.fire('wheel', { deltaY: -20000, preventDefault: vi.fn() }); + + const radii = cam.distance / EARTH_RADIUS_MPC; + expect(radii).toBeGreaterThanOrEqual(STANDOFF); + expect(radii).toBeLessThan(STANDOFF * 1.05); + }); + + it('with no standoffRadii getter, the pinch floor is the global ratio unchanged', () => { + const cam = makeCamera(); + cam.distance = EARTH_RADIUS_MPC * 4; + const { canvas, rec } = makeCanvas(); + + attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { + pivotRadiusMpc: () => EARTH_RADIUS_MPC, + }); + + rec.fire('pointerdown', { + pointerId: 1, + pointerType: 'touch', + button: 0, + clientX: 0, + clientY: 0, + }); + rec.fire('pointerdown', { + pointerId: 2, + pointerType: 'touch', + button: 0, + clientX: 10, + clientY: 0, + }); + for (const x of [1000, 100000, 10000000]) { + win.fire('pointermove', { pointerId: 2, clientX: x, clientY: 0 }); + } + + const radii = cam.distance / EARTH_RADIUS_MPC; + expect(radii).toBeGreaterThan(1); + expect(radii).toBeLessThan(1.05); + }); +}); + describe('attachOrbitControls — orbit-drag rate damps near a focused body’s surface', () => { // The flat 0.005 rad/px orbit rate rotates about the pivot's CENTRE, so the // ground distance it sweeps scales with the pivot's radius — irrelevant to diff --git a/tests/services/engine/camera/pivotStandoffRadii.test.ts b/tests/services/engine/camera/pivotStandoffRadii.test.ts new file mode 100644 index 0000000000..4a9af3db6f --- /dev/null +++ b/tests/services/engine/camera/pivotStandoffRadii.test.ts @@ -0,0 +1,58 @@ +/** + * pivotStandoffRadii — which focus rows override the global standoff ratio. + * + * The one case that matters: a body row carrying `standoffRadii` (Sgr A*'s + * Q10 floor) must reach the clamp instead of the Earth-tuned global ratio. + * Everything else — no override on the row, a star, a galaxy, no focus at + * all — must fall through to `SURFACE_STANDOFF_RADII` so every other body's + * floor stays byte-identical to today. + */ + +import { describe, it, expect } from 'vitest'; + +import { pivotStandoffRadii } from '../../../../src/services/engine/camera/pivotStandoffRadii'; +import { SURFACE_STANDOFF_RADII } from '../../../../src/utils/camera/clampDistance'; +import { makeGalaxyRow } from '../../../fixtures/makeGalaxyRow'; +import type { SelectionRow } from '../../../../src/@types/engine/SelectionRow'; + +describe('pivotStandoffRadii', () => { + it('reads a body row’s own override', () => { + const sgrAStar: SelectionRow = { + type: 'body', + id: 'sgr-a-star', + label: 'Sagittarius A*', + positionMpc: [0, 0, 0], + radiusM: 1.269e10, + standoffRadii: 2.0, + }; + expect(pivotStandoffRadii(sgrAStar)).toBe(2.0); + }); + + it('falls through to the global ratio for a body row with no override', () => { + const earth: SelectionRow = { + type: 'body', + id: 'earth', + label: 'Earth', + positionMpc: [0, 0, 0], + radiusM: 6371000, + }; + expect(pivotStandoffRadii(earth)).toBe(SURFACE_STANDOFF_RADII); + }); + + it('falls through to the global ratio for a star row — no per-record override field', () => { + const star: SelectionRow = { + type: 'star', + index: 7, + positionMpc: [1, 2, 3], + absMag: 4, + bpRp: 0.6, + radiusM: 696340000, + }; + expect(pivotStandoffRadii(star)).toBe(SURFACE_STANDOFF_RADII); + }); + + it('falls through to the global ratio for a galaxy and for no focus at all', () => { + expect(pivotStandoffRadii(makeGalaxyRow({ diameterKpc: 30 }))).toBe(SURFACE_STANDOFF_RADII); + expect(pivotStandoffRadii(null)).toBe(SURFACE_STANDOFF_RADII); + }); +}); diff --git a/tests/services/engine/phases/wireInput.test.ts b/tests/services/engine/phases/wireInput.test.ts index dc5a16c73f..f439b81308 100644 --- a/tests/services/engine/phases/wireInput.test.ts +++ b/tests/services/engine/phases/wireInput.test.ts @@ -103,6 +103,7 @@ import { requestFocus } from '../../../../src/state/selection/requestFocus'; import { EARTH_REF } from '../../../../src/data/selection/earthRef'; import { setSelectionRow } from '../../../../src/state/selectionRows/selectionRowsSlice'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; +import { SURFACE_STANDOFF_RADII } from '../../../../src/utils/camera/clampDistance'; import type { OrbitControlsOptions } from '../../../../src/@types/camera/OrbitControlsOptions'; // ── Fixtures ───────────────────────────────────────────────────────── @@ -302,6 +303,39 @@ describe('wireInput', () => { expect(read!()).toBeCloseTo(6371 * SCALE_UNITS.KM_TO_MPC, 30); }); + it('hands the orbit controls a live read of the focused body’s standoff override', async () => { + // Same wiring gap, one field over: without this getter, Sgr A*'s Q10 floor + // (`standoffRadii: 2.0`) never reaches the pinch / wheel-during-gesture + // sites and the camera stops at the Earth-tuned global ratio instead. + const state = makeState(); + const deps = makeDeps(); + attachOrbitControlsSpy.mockClear(); + + await wireInput(state, deps); + + const options = attachOrbitControlsSpy.mock.calls[0]?.[2] as OrbitControlsOptions | undefined; + const read = options?.standoffRadii; + expect(read).toBeTypeOf('function'); + + // Nothing resolved yet: no per-body override, so the global ratio applies. + expect(read!()).toBe(SURFACE_STANDOFF_RADII); + + deps.cb.store.dispatch( + setSelectionRow({ + slot: 'focus', + row: { + type: 'body', + id: 'sgr-a-star', + label: 'Sagittarius A*', + positionMpc: [0, 0, 0], + radiusM: 1.269e10, + standoffRadii: 2.0, + }, + }), + ); + expect(read!()).toBe(2.0); + }); + it('defers the seed to a galaxy/star id still parked in a deferred resolve', async () => { const state = makeState(); const deps = makeDeps(); diff --git a/tests/utils/camera/clampDistance.test.ts b/tests/utils/camera/clampDistance.test.ts index a11b9360ef..6674befcf3 100644 --- a/tests/utils/camera/clampDistance.test.ts +++ b/tests/utils/camera/clampDistance.test.ts @@ -15,6 +15,7 @@ import { clampDistance, MIN_DISTANCE_MPC, MAX_DISTANCE_MPC, + SURFACE_STANDOFF_RADII, } from '../../../src/utils/camera/clampDistance'; import { SCALE_UNITS } from '../../../src/data/scaleUnits'; import { bodyFocusDistance } from '../../../src/services/engine/camera/bodyFocusDistance'; @@ -85,3 +86,24 @@ describe('clampDistance — pivoted on a body', () => { expect(clampDistance(framing, EARTH_RADIUS_MPC)).toBe(framing); }); }); + +describe('clampDistance — per-body standoff', () => { + it('floors at the given ratio instead of SURFACE_STANDOFF_RADII', () => { + // Sgr A*'s descent floor (2 r_s) is far outside the Earth-tuned global + // ratio, so a body that opts in must be floored at ITS OWN multiple, not + // the shared constant. + const radiusMpc = EARTH_RADIUS_MPC; // any body radius exercises the same math + const belowFloor = radiusMpc * 0.5; // deep inside the body + expect(clampDistance(belowFloor, radiusMpc, 2.0)).toBeCloseTo(radiusMpc * 2.0, 30); + }); + + it('omitted standoffRadii keeps Earth’s current floor unchanged', () => { + // The zero-change proof: every existing two-arg call site (every body that + // doesn't carry a `standoffRadii` override) must be byte-identical to + // today's behaviour. + const belowFloor = EARTH_RADIUS_MPC * 0.5; + expect(clampDistance(belowFloor, EARTH_RADIUS_MPC)).toBe( + clampDistance(belowFloor, EARTH_RADIUS_MPC, SURFACE_STANDOFF_RADII), + ); + }); +}); From 872e9a83bcac695b8d72d3d24cd30a78b8873191 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 11:45:01 +0200 Subject: [PATCH 08/60] test(selection): cover the standoffRadii narrowing in extractSelectionRow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every existing zoom-path test hand-builds a SelectionRow with standoffRadii already set, so the 'standoffRadii' in body narrowing in extractSelectionRow.ts had no coverage against the real SCENE_BODIES seed — a typo'd property or a reversed condition would silently drop Sgr A*'s Q10 floor with the suite green. Adds a test against the real SGR_A_STAR seed plus an explicit undefined-field assertion for a body with no override, so a reversed condition fails on either side. Verified by temporarily reversing the condition: the new Sgr A* case goes red (undefined vs 2), confirming it catches the regression. Co-Authored-By: Claude Fable 5 --- .../helpers/extractSelectionRow.test.ts | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tests/services/engine/helpers/extractSelectionRow.test.ts b/tests/services/engine/helpers/extractSelectionRow.test.ts index f7b3cafac7..9d535d20e9 100644 --- a/tests/services/engine/helpers/extractSelectionRow.test.ts +++ b/tests/services/engine/helpers/extractSelectionRow.test.ts @@ -8,6 +8,7 @@ import { decodeStarCatalog, } from '../../../../src/data/starCatalog/starCatalogFormat'; import { SCENE_EARTH } from '../../../../src/data/bodies/sceneEarth'; +import { SGR_A_STAR } from '../../../../src/data/bodies/sceneSgrAStar'; import { SCENE_BODIES } from '../../../../src/data/bodies/sceneBodies'; import { SOLAR_RADIUS_KM } from '../../../../src/data/bodies/solarRadiusKm'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; @@ -121,6 +122,27 @@ describe('extractSelectionRow', () => { }); }); + it('body ref for a body with no standoffRadii override → the row field is undefined', () => { + // Earth carries no `standoffRadii` on its seed. Explicit `.toBeUndefined()` + // (not the earlier `toEqual` case, which is lenient about missing keys) so + // a reversed `'standoffRadii' in body` condition — one that would instead + // stamp a real number onto every non-overriding body — fails here too. + const row = extractSelectionRow({ type: 'body', id: 'earth' }, deps, SIM_DAYS); + expect(row !== null && row.type === 'body' && row.standoffRadii).toBeUndefined(); + }); + + it('body ref for Sgr A* carries its standoffRadii override through', () => { + // The real regression this guards: `extractSelectionRow`'s + // `'standoffRadii' in body` narrowing is exercised here against the ACTUAL + // SCENE_BODIES seed (not a hand-built row with the field already set, the + // way every downstream zoom test constructs its fixtures) — a typo'd + // property name or a reversed condition would silently drop Sgr A*'s Q10 + // floor while every other test in the suite stays green. + const row = extractSelectionRow({ type: 'body', id: SGR_A_STAR.id }, deps, SIM_DAYS); + expect(row !== null && row.type === 'body' && row.standoffRadii).toBe(SGR_A_STAR.standoffRadii); + expect(SGR_A_STAR.standoffRadii).toBe(2.0); // guards against both sides drifting to `undefined` + }); + it('body ref resolves the position at the PASSED simDays, not a fixed epoch', () => { // The whole point of the fix: two different simDays for the same orbiting // body must yield two different positions, sourced from deriveBodyStates at From 6923db0de2d5b22ea00d62eda200a71c2e14e466 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 12:35:01 +0200 Subject: [PATCH 09/60] refactor(camera): merge pivotRadiusMpc + standoffRadii into one PivotFraming getter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 2 threaded the per-body camera-standoff floor as a second parallel getter lane beside pivotRadiusMpc through the orbit-controls input stack (OrbitControlsOptions -> orbitControls -> applyWheelZoom -> zoomedPose -> zoomedDistance -> clampDistance). Reworks that into a single `pivotFraming: () => PivotFraming` getter carrying { radiusMpc, floorMpc } in one bundle, per the user's rejection of the two-lane shape. floorMpc is precomputed at the lane source (pivotRadiusMpc.ts's new pivotFraming(), built beside the untouched pivotRadiusMpc() scalar export that runFrame.ts/frameContext.ts/logCameraState.ts still consume directly), so clampDistance drops back to a plain two-arg (distance, floorMpc) clamp with no pivot-radius/standoff-ratio knowledge of its own. zoomedDistance keeps reading the bundle's raw radiusMpc for its altitude-taper anchor (h = distance - radiusMpc) alongside the precomputed floor — the two fields diverge on purpose, which is why they ride one bundle instead of collapsing into a single number. Deletes pivotStandoffRadii.ts (merged into pivotFraming); Sgr A*'s 2 r_s override stays covered by pivotRadiusMpc.test.ts's pivotFraming describe block plus a wireInput.ts wiring test. Co-Authored-By: Claude Fable 5 --- src/@types/camera/OrbitControlsOptions.d.ts | 25 +++---- src/@types/camera/PivotFraming.d.ts | 14 ++++ src/services/camera/orbitControls.ts | 31 ++++---- src/services/engine/camera/applyWheelZoom.ts | 36 +++------- src/services/engine/camera/pivotRadiusMpc.ts | 33 +++++++-- .../engine/camera/pivotStandoffRadii.ts | 17 ----- src/services/engine/phases/wireInput.ts | 16 ++--- src/utils/camera/clampDistance.ts | 34 ++++----- src/utils/camera/zoomedDistance.ts | 36 ++++------ src/utils/camera/zoomedPose.ts | 25 +++---- tests/services/camera/orbitControls.test.ts | 44 +++++++----- .../engine/camera/applyWheelZoom.test.ts | 28 +++++--- .../engine/camera/pivotRadiusMpc.test.ts | 67 +++++++++++++++++- .../engine/camera/pivotStandoffRadii.test.ts | 58 --------------- .../services/engine/phases/wireInput.test.ts | 47 ++++++------- tests/utils/camera/clampDistance.test.ts | 70 ++++++------------- tests/utils/camera/zoomedDistance.test.ts | 22 ++++-- tests/utils/camera/zoomedPose.test.ts | 32 ++++++--- 18 files changed, 311 insertions(+), 324 deletions(-) create mode 100644 src/@types/camera/PivotFraming.d.ts delete mode 100644 src/services/engine/camera/pivotStandoffRadii.ts delete mode 100644 tests/services/engine/camera/pivotStandoffRadii.test.ts diff --git a/src/@types/camera/OrbitControlsOptions.d.ts b/src/@types/camera/OrbitControlsOptions.d.ts index 16f4878691..6d4969ceb2 100644 --- a/src/@types/camera/OrbitControlsOptions.d.ts +++ b/src/@types/camera/OrbitControlsOptions.d.ts @@ -5,6 +5,8 @@ * behaviour as the original single-argument overload (orbit only, no click). */ +import type { PivotFraming } from './PivotFraming'; + export type OrbitControlsOptions = { /** * Called when the user clicks (as opposed to drags) on the canvas. @@ -59,24 +61,17 @@ export type OrbitControlsOptions = { */ onZoom?: (factor: number) => void; /** - * Physical radius (Mpc) of whatever the camera currently orbits, or `null` - * when the pivot has no surface. Read at the start of a pinch or - * wheel-during-gesture so `clampDistance` floors the distance just off - * that surface instead of at the absolute floor (~309 km, deep inside - * Earth). + * Radius + zoom floor of whatever the camera currently orbits. Read at the + * start of a pinch, a wheel-during-gesture, and every orbit-drag move, so + * `zoomedDistance`/`clampDistance` taper into and floor at that surface + * (rather than the absolute floor, ~309 km deep inside Earth) and + * `orbitRadPerPixel` damps drag sensitivity near it. * * A getter, not a cached value — this module holds no scene state; the - * engine wires it to `pivotRadiusMpc(selectFocusRow(...))`. Omitted - * (tests, or no scene) ⇒ only the global floor applies. - */ - pivotRadiusMpc?: () => number | null; - /** - * Per-pivot override of `clampDistance`'s global `SURFACE_STANDOFF_RADII` - * (e.g. Sgr A*'s Q10 floor of 2 r_s), read alongside `pivotRadiusMpc` at the - * same two call sites. A getter for the same reason; the engine wires it to - * `pivotStandoffRadii(selectFocusRow(...))`. Omitted ⇒ the global ratio. + * engine wires it to `pivotFraming(selectFocusRow(...))`. Omitted (tests, + * or no scene) ⇒ no pivot, only the global/absolute floor applies. */ - standoffRadii?: () => number; + pivotFraming?: () => PivotFraming; /** * Called on the first pointer contact that begins a new gesture (i.e. when * `activePointers.size === 1` on `pointerdown`). Subsequent fingers (pinch diff --git a/src/@types/camera/PivotFraming.d.ts b/src/@types/camera/PivotFraming.d.ts new file mode 100644 index 0000000000..11632dc992 --- /dev/null +++ b/src/@types/camera/PivotFraming.d.ts @@ -0,0 +1,14 @@ +/** + * PivotFraming — everything the zoom/orbit lane needs about the camera's + * current pivot, in one bundle. `radiusMpc` and `floorMpc` diverge on purpose: + * `zoomedDistance`'s taper anchors on the RAW radius (`h = distance - + * radiusMpc`), while `clampDistance`'s floor is the standoff-and-MIN-adjusted + * value — collapsing them into one number would lose the taper anchor. + */ + +export type PivotFraming = { + /** Physical radius of the pivot body in Mpc; null when the pivot has no surface. */ + readonly radiusMpc: number | null; + /** Camera distance floor in Mpc — standoff already applied, MIN clamp already applied. */ + readonly floorMpc: number; +}; diff --git a/src/services/camera/orbitControls.ts b/src/services/camera/orbitControls.ts index 82d1fd410f..a8387ad0d6 100644 --- a/src/services/camera/orbitControls.ts +++ b/src/services/camera/orbitControls.ts @@ -62,11 +62,13 @@ import type { OrbitCamera } from '../../@types/camera/OrbitCamera'; import type { OrbitControlsOptions } from '../../@types/camera/OrbitControlsOptions'; +import type { PivotFraming } from '../../@types/camera/PivotFraming'; import { updatePosition } from '../../utils/camera/updatePosition'; import { zoomedDistance } from '../../utils/camera/zoomedDistance'; import { orbitRadPerPixel } from '../../utils/camera/orbitRadPerPixel'; import { imagePlaneBasis } from '../../utils/camera/imagePlaneBasis'; import { frameUp } from '../../utils/camera/frameUp'; +import { MIN_DISTANCE_MPC } from '../../utils/camera/clampDistance'; import { vec3 } from 'wgpu-matrix'; import type { Vec3 } from '../../@types/math/Vec3'; import type { ImagePlaneBasis } from '../../@types/camera/ImagePlaneBasis'; @@ -94,6 +96,9 @@ import type { ImagePlaneBasis } from '../../@types/camera/ImagePlaneBasis'; */ const PITCH_LIMIT = Math.PI / 2 - 0.01; +/** No focused pivot: no surface to taper/damp against, absolute floor only. */ +const NO_PIVOT: PivotFraming = { radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }; + // ─── Controls ───────────────────────────────────────────────────────────────── /** @@ -193,15 +198,12 @@ export function attachOrbitControls( /** Squared pixel distance between pointerdown and pointerup. */ const CLICK_THRESHOLD_SQ = 4 * 4; // 4 px radius → 16 when squared - // Both zoom paths below (pinch, and a wheel tick during a held gesture) need - // the focused body's radius to taper/floor `zoomedDistance` against — read - // live through the caller's getter rather than cached, since this module - // never sees the scene and focus can change while controls stay attached. - const pivotRadius = (): number | null => options?.pivotRadiusMpc?.() ?? null; - // Same live-read reasoning, for the per-pivot standoff override (e.g. Sgr - // A*'s 2 r_s floor). Undefined (no getter, or the getter's own default) - // reaches `zoomedDistance`'s own default unchanged. - const standoffRadius = (): number | undefined => options?.standoffRadii?.(); + // Both zoom paths below (pinch, and a wheel tick during a held gesture), plus + // the orbit-drag rate, need the focused body's radius/floor to taper/damp + // against — read live through the caller's getter rather than cached, since + // this module never sees the scene and focus can change while controls stay + // attached. + const pivot = (): PivotFraming => options?.pivotFraming?.() ?? NO_PIVOT; // ── Pointer down — begin drag ────────────────────────────────────────────── @@ -365,12 +367,7 @@ export function attachOrbitControls( if (activePointers.size < 2 || lastPinchDist === 0) return; const newDist = currentPinchDistance(); if (newDist > 0) { - cam.distance = zoomedDistance( - cam.distance, - lastPinchDist / newDist, - pivotRadius(), - standoffRadius(), - ); + cam.distance = zoomedDistance(cam.distance, lastPinchDist / newDist, pivot()); lastPinchDist = newDist; updatePosition(cam); options?.onChange?.(); @@ -470,7 +467,7 @@ export function attachOrbitControls( // focused body's surface so the ground under the cursor tracks the drag // (see the util's module header for the derivation and its limits). const cssHeight = canvas.clientHeight || 1; - const radPerPixel = orbitRadPerPixel(cam.fovYRad, cam.distance, cssHeight, pivotRadius()); + const radPerPixel = orbitRadPerPixel(cam.fovYRad, cam.distance, cssHeight, pivot().radiusMpc); cam.yaw -= dx * radPerPixel; @@ -526,7 +523,7 @@ export function attachOrbitControls( // Wheel DURING a drag/pinch: fold the zoom into the live `cam` register. // The `orbitDrag` driver (priority 80) is active and renders `poseOf(cam)`, // so the zoom shows immediately and rides the `onGestureEnd` commit. - cam.distance = zoomedDistance(cam.distance, factor, pivotRadius(), standoffRadius()); + cam.distance = zoomedDistance(cam.distance, factor, pivot()); updatePosition(cam); options?.onChange?.(); return; diff --git a/src/services/engine/camera/applyWheelZoom.ts b/src/services/engine/camera/applyWheelZoom.ts index f1f7f458b9..db03a6d535 100644 --- a/src/services/engine/camera/applyWheelZoom.ts +++ b/src/services/engine/camera/applyWheelZoom.ts @@ -45,16 +45,12 @@ * drag path writes it via the recapture edge (a committed base.distance); this * function is the WHEEL half of 'any user zoom'. * - * `pivotRadiusMpc` is the radius of whatever the camera orbits (see the helper - * of the same name), forwarded to every arm's `zoomedDistance` call so the zoom - * tapers into just off a focused body's surface instead of scaling raw distance - * to the centre. All three arms need it: follow orbits the body by definition, - * and the autoRotate / resting arms orbit it too whenever the frame loop's - * pivot-pin is centring them on it. - * - * `standoffRadii` is the same focused body's `pivotStandoffRadii` read, - * forwarded alongside `pivotRadiusMpc` for the same three arms — optional so - * every existing caller (no per-body override) reaches the shared default. + * `pivot` bundles the radius + floor of whatever the camera orbits (see + * `pivotRadiusMpc.ts`'s `pivotFraming`), forwarded to every arm's + * `zoomedDistance` call so the zoom tapers into just off a focused body's + * surface instead of scaling raw distance to the centre. All three arms need + * it: follow orbits the body by definition, and the autoRotate / resting arms + * orbit it too whenever the frame loop's pivot-pin is centring them on it. */ import { autoRotateElapsed } from './cameraClock'; @@ -63,6 +59,7 @@ import { zoomedDistance } from '../../../utils/camera/zoomedDistance'; import { zoomedPose } from '../../../utils/camera/zoomedPose'; import type { CameraClock } from '../../../@types/engine/camera/CameraClock'; import type { CameraPose } from '../../../@types/camera/CameraPose'; +import type { PivotFraming } from '../../../@types/camera/PivotFraming'; export function applyWheelZoom( clock: CameraClock, @@ -71,26 +68,15 @@ export function applyWheelZoom( factor: number, autoRotate: { active: boolean; rate: number }, nowMs: number, - pivotRadiusMpc: number | null, - standoffRadii?: number, + pivot: PivotFraming, ): CameraPose | null { if (prevActiveId === 'followBody' && clock.followDistanceTarget !== null) { - clock.followDistanceTarget = zoomedDistance( - clock.followDistanceTarget, - factor, - pivotRadiusMpc, - standoffRadii, - ); + clock.followDistanceTarget = zoomedDistance(clock.followDistanceTarget, factor, pivot); return null; } if (prevActiveId === 'autoRotate') { const elapsed = autoRotateElapsed(clock, autoRotate.active, base, nowMs); - return zoomedPose( - spinAutoRotate(base, autoRotate.rate, elapsed), - factor, - pivotRadiusMpc, - standoffRadii, - ); + return zoomedPose(spinAutoRotate(base, autoRotate.rate, elapsed), factor, pivot); } - return zoomedPose(base, factor, pivotRadiusMpc, standoffRadii); + return zoomedPose(base, factor, pivot); } diff --git a/src/services/engine/camera/pivotRadiusMpc.ts b/src/services/engine/camera/pivotRadiusMpc.ts index 1cca5e63d5..6809d8f833 100644 --- a/src/services/engine/camera/pivotRadiusMpc.ts +++ b/src/services/engine/camera/pivotRadiusMpc.ts @@ -2,18 +2,41 @@ * pivotRadiusMpc — the physical radius (Mpc) of whatever sits at the camera's * orbit pivot, or `null` when the pivot has no surface. * - * The one place that maps a resolved `SelectionRow` onto `clampDistance`'s - * floor argument, so the zoom floor, the pinch floor, and the follow driver's - * distance target all derive it from the same rule. A body or survey star is a - * surface the camera can crash into; a galaxy, a structure, or the Milky Way is - * a volume the camera flies INTO, so those stay `null` and unfloored. + * The one place that maps a resolved `SelectionRow` onto a pivot radius. A + * body or survey star is a surface the camera can crash into; a galaxy, a + * structure, or the Milky Way is a volume the camera flies INTO, so those stay + * `null` and unfloored. `runFrame.ts`/`frameContext.ts`/`logCameraState.ts` + * consume this scalar directly (altitude math, debug logging) — `pivotFraming` + * below is the orbit-controls lane's own bundle, built beside it in the same + * file rather than displacing this export. */ import { SCALE_UNITS } from '../../../data/scaleUnits'; +import { MIN_DISTANCE_MPC, SURFACE_STANDOFF_RADII } from '../../../utils/camera/clampDistance'; import type { SelectionRow } from '../../../@types/engine/SelectionRow'; +import type { PivotFraming } from '../../../@types/camera/PivotFraming'; export function pivotRadiusMpc(row: SelectionRow | null): number | null { if (row === null) return null; if (row.type !== 'body' && row.type !== 'star') return null; return row.radiusM * SCALE_UNITS.M_TO_MPC; } + +/** + * pivotFraming — the orbit-controls lane's single getter target: radius + + * precomputed zoom floor for the resolved focus row. `standoffRadii` reads a + * body row's own override (Sgr A*'s Q10 floor) else the global ratio. + * `radiusMpc ?? 0` makes a surfaceless pivot's floor collapse to + * `MIN_DISTANCE_MPC`, matching the old null-radius clamp exactly. + */ +export function pivotFraming(row: SelectionRow | null): PivotFraming { + const radiusMpc = pivotRadiusMpc(row); + const standoffRadii = + row !== null && row.type === 'body' + ? (row.standoffRadii ?? SURFACE_STANDOFF_RADII) + : SURFACE_STANDOFF_RADII; + return { + radiusMpc, + floorMpc: Math.max(MIN_DISTANCE_MPC, (radiusMpc ?? 0) * standoffRadii), + }; +} diff --git a/src/services/engine/camera/pivotStandoffRadii.ts b/src/services/engine/camera/pivotStandoffRadii.ts deleted file mode 100644 index f7ec327ef5..0000000000 --- a/src/services/engine/camera/pivotStandoffRadii.ts +++ /dev/null @@ -1,17 +0,0 @@ -/** - * pivotStandoffRadii — the per-focus override of `clampDistance`'s global - * `SURFACE_STANDOFF_RADII`, read the same way `pivotRadiusMpc` reads the pivot - * radius: off a resolved `SelectionRow`'s 'body' arm (`AnchorPointBody. - * standoffRadii`, e.g. Sgr A*'s Q10 floor of 2 r_s). Every other row — - * including a survey star, which has no per-record override field — falls - * through to the global ratio, so this is a sibling read, not a branch on - * `pivotRadiusMpc`'s own result. - */ - -import { SURFACE_STANDOFF_RADII } from '../../../utils/camera/clampDistance'; -import type { SelectionRow } from '../../../@types/engine/SelectionRow'; - -export function pivotStandoffRadii(row: SelectionRow | null): number { - if (row === null || row.type !== 'body') return SURFACE_STANDOFF_RADII; - return row.standoffRadii ?? SURFACE_STANDOFF_RADII; -} diff --git a/src/services/engine/phases/wireInput.ts b/src/services/engine/phases/wireInput.ts index 23ef6d1ee3..09455f84ec 100644 --- a/src/services/engine/phases/wireInput.ts +++ b/src/services/engine/phases/wireInput.ts @@ -29,8 +29,7 @@ import { createOrbitCamera } from '../../../utils/camera/createOrbitCamera'; import { attachOrbitControls } from '../../camera/orbitControls'; import { applyWheelZoom } from '../camera/applyWheelZoom'; -import { pivotRadiusMpc } from '../camera/pivotRadiusMpc'; -import { pivotStandoffRadii } from '../camera/pivotStandoffRadii'; +import { pivotFraming } from '../camera/pivotRadiusMpc'; import { seedCameraFromBase } from '../../camera/seedCameraFromBase'; import { constructGpuHandles } from '../gpuHandles/constructGpuHandles'; import { GPU_HANDLE_ROWS } from '../gpuHandles/gpuHandleRegistry'; @@ -347,12 +346,9 @@ export async function wireInput(state: EngineState, deps: BootstrapDeps): Promis state.subsystems.scheduler.requestRender(); }, - // The zoom floor's input, read live off the resolved focus row — same - // derivation the `onZoom` path below uses. - pivotRadiusMpc: () => pivotRadiusMpc(selectFocusRow(store.getState())), - // The zoom floor's per-body override (e.g. Sgr A*'s Q10 floor) — same - // derivation the `onZoom` path below uses. - standoffRadii: () => pivotStandoffRadii(selectFocusRow(store.getState())), + // The zoom floor's input (radius + precomputed floor), read live off the + // resolved focus row — same derivation the `onZoom` path below uses. + pivotFraming: () => pivotFraming(selectFocusRow(store.getState())), // Discrete wheel zoom (no gesture in progress). The zoom goes to whichever // driver owns the distance this frame: while a body is followed the @@ -377,9 +373,7 @@ export async function wireInput(state: EngineState, deps: BootstrapDeps): Promis performance.now(), // Floors the zoom just off a focused body's surface for every arm of // applyWheelZoom, not only the follow driver. - pivotRadiusMpc(selectFocusRow(root)), - // Per-body override of that floor (e.g. Sgr A*'s Q10 floor). - pivotStandoffRadii(selectFocusRow(root)), + pivotFraming(selectFocusRow(root)), ); if (zoomed !== null) store.dispatch(commitCameraPose(zoomed)); // Unconditional — the follow branch (applyWheelZoom.ts:72-75) mutates followDistanceTarget diff --git a/src/utils/camera/clampDistance.ts b/src/utils/camera/clampDistance.ts index 746e5e0cf9..0e70ca08e2 100644 --- a/src/utils/camera/clampDistance.ts +++ b/src/utils/camera/clampDistance.ts @@ -4,10 +4,9 @@ * The limits here are the single source of truth for how far the orbit camera * may sit from its target — wheel zoom, pinch zoom, focus tweens, and initial * framing all route through `clampDistance` so the envelope can never drift. - * The floor takes the orbited body's physical radius and stands off from its - * surface (a framed body's target is its CENTRE), so `pivotRadiusMpc` is a - * REQUIRED `number | null` param — optional would let a call site silently - * fall back to the global floor, the drift this module exists to prevent. + * The floor stands off from the orbited body's surface (a framed body's target + * is its CENTRE); callers precompute it via `PivotFraming.floorMpc` rather than + * passing a radius here, so this module has no pivot-radius branch to drift. */ // ─── Distance limits ────────────────────────────────────────────────────────── @@ -60,25 +59,18 @@ export const MAX_DISTANCE_MPC = 30000; /** * Clamp a candidate distance to the zoom envelope: ceiling `MAX_DISTANCE_MPC`, - * floor `max(MIN_DISTANCE_MPC, pivotRadiusMpc · standoffRadii)`. + * floor `floorMpc`. * - * @param d Candidate `cam.distance`, Mpc. - * @param pivotRadiusMpc Physical radius of the orbit pivot, Mpc, or `null` when - * it has no surface to stand off from (empty space, a galaxy, a structure, - * the Milky Way — volumes the camera flies INTO, never a floor). - * @param standoffRadii Per-pivot override of `SURFACE_STANDOFF_RADII` — see - * `AnchorPointBody.standoffRadii` for why a body needs its own ratio. + * `floorMpc` is precomputed by the caller (`PivotFraming.floorMpc`, built in + * `pivotRadiusMpc.ts`'s `pivotFraming`) as `max(MIN_DISTANCE_MPC, + * (radiusMpc ?? 0) * standoffRadii)` — this function no longer knows about a + * pivot radius or a standoff ratio, only the resulting number. + * + * @param d Candidate `cam.distance`, Mpc. + * @param floorMpc Precomputed distance floor, Mpc. */ -export function clampDistance( - d: number, - pivotRadiusMpc: number | null, - standoffRadii: number = SURFACE_STANDOFF_RADII, -): number { - const floor = - pivotRadiusMpc === null - ? MIN_DISTANCE_MPC - : Math.max(MIN_DISTANCE_MPC, pivotRadiusMpc * standoffRadii); - if (d < floor) return floor; +export function clampDistance(d: number, floorMpc: number): number { + if (d < floorMpc) return floorMpc; if (d > MAX_DISTANCE_MPC) return MAX_DISTANCE_MPC; return d; } diff --git a/src/utils/camera/zoomedDistance.ts b/src/utils/camera/zoomedDistance.ts index f80ab1eb0b..c4645b0b49 100644 --- a/src/utils/camera/zoomedDistance.ts +++ b/src/utils/camera/zoomedDistance.ts @@ -9,41 +9,35 @@ * standoff floor (`SURFACE_STANDOFF_RADII`). * * The fix scales ALTITUDE geometrically instead: with `h = distance - - * pivotRadiusMpc`, `distance' = pivotRadiusMpc + h * factor`. As `h → 0` the + * pivot.radiusMpc`, `distance' = pivot.radiusMpc + h * factor`. As `h → 0` the * steps shrink without bound (the Google Earth model). For `h >> - * pivotRadiusMpc` (every astronomical viewing distance) this degenerates to - * the old model exactly — `pivotRadiusMpc + h * factor ≈ distance * factor` — + * pivot.radiusMpc` (every astronomical viewing distance) this degenerates to + * the old model exactly — `pivot.radiusMpc + h * factor ≈ distance * factor` — * so deep-space feel is unchanged and the taper only engages on final - * approach. `pivotRadiusMpc === null` (no surface — empty space, a galaxy, a + * approach. `pivot.radiusMpc === null` (no surface — empty space, a galaxy, a * structure, the Milky Way) degenerates to it exactly too. * * `clampDistance` is called from inside here, not by the caller, so the - * envelope stays enforced in exactly one place. - * - * `standoffRadii` is forwarded straight to every `clampDistance` call — - * optional so the flat-space arm and every existing caller (no per-body - * override) reach `clampDistance`'s own default unchanged. + * envelope stays enforced in exactly one place — `pivot.floorMpc` is already + * the standoff-and-MIN-adjusted floor, so it forwards straight through. */ -import { clampDistance, SURFACE_STANDOFF_RADII } from './clampDistance'; +import { clampDistance } from './clampDistance'; +import type { PivotFraming } from '../../@types/camera/PivotFraming'; -export function zoomedDistance( - distance: number, - factor: number, - pivotRadiusMpc: number | null, - standoffRadii: number = SURFACE_STANDOFF_RADII, -): number { - if (pivotRadiusMpc === null) { - return clampDistance(distance * factor, null); +export function zoomedDistance(distance: number, factor: number, pivot: PivotFraming): number { + const { radiusMpc, floorMpc } = pivot; + if (radiusMpc === null) { + return clampDistance(distance * factor, floorMpc); } - const h = distance - pivotRadiusMpc; + const h = distance - radiusMpc; if (h <= 0) { // Degenerate: `clampDistance` should prevent the camera reaching the // surface at all. Fall back to plain proportional scaling rather than // invent a geometric taper for a zero/negative altitude. - return clampDistance(distance * factor, pivotRadiusMpc, standoffRadii); + return clampDistance(distance * factor, floorMpc); } - return clampDistance(pivotRadiusMpc + h * factor, pivotRadiusMpc, standoffRadii); + return clampDistance(radiusMpc + h * factor, floorMpc); } diff --git a/src/utils/camera/zoomedPose.ts b/src/utils/camera/zoomedPose.ts index 6955950ccf..de282a712d 100644 --- a/src/utils/camera/zoomedPose.ts +++ b/src/utils/camera/zoomedPose.ts @@ -7,34 +7,27 @@ * yaw, and pitch carry over unchanged. The target is copied into a fresh array * so the result never aliases the input pose's (frozen, store-owned) target. * - * `pivotRadiusMpc` is forwarded straight to `zoomedDistance` — it is the radius - * of whatever the pose orbits, so the taper (and the floor beneath it) stands - * off that body's surface (`null` when there is no surface). It is threaded - * rather than defaulted because a wheel tick under an active auto-rotate spins - * AROUND a focused body: the pose this function zooms is pivoted on that body - * just as much as the follow driver's is. + * `pivot` is forwarded straight to `zoomedDistance` — it describes whatever + * the pose orbits, so the taper (and the floor beneath it) stand off that + * body's surface. It is threaded rather than defaulted because a wheel tick + * under an active auto-rotate spins AROUND a focused body: the pose this + * function zooms is pivoted on that body just as much as the follow driver's + * is. * * Pure by design: the wheel handler reads `camera.base` from the store, hands * it here, and dispatches the result — so the zoom arithmetic (and its clamp * behaviour) is unit-testable without a store, a canvas, or a render loop. - * - * `standoffRadii` forwards straight to `zoomedDistance`, optional for the same - * reason: every caller without a per-body override reaches the shared default. */ import { zoomedDistance } from './zoomedDistance'; import type { CameraPose } from '../../@types/camera/CameraPose'; +import type { PivotFraming } from '../../@types/camera/PivotFraming'; -export function zoomedPose( - base: CameraPose, - factor: number, - pivotRadiusMpc: number | null, - standoffRadii?: number, -): CameraPose { +export function zoomedPose(base: CameraPose, factor: number, pivot: PivotFraming): CameraPose { return { target: [base.target[0], base.target[1], base.target[2]], yaw: base.yaw, pitch: base.pitch, - distance: zoomedDistance(base.distance, factor, pivotRadiusMpc, standoffRadii), + distance: zoomedDistance(base.distance, factor, pivot), }; } diff --git a/tests/services/camera/orbitControls.test.ts b/tests/services/camera/orbitControls.test.ts index 50409f5c49..28c9480822 100644 --- a/tests/services/camera/orbitControls.test.ts +++ b/tests/services/camera/orbitControls.test.ts @@ -36,10 +36,10 @@ * - `onGestureEnd` fires exactly when ALL contacts are lifted. * - `onChange` fires after any orbit, pan, pinch, or in-gesture wheel change; * a discrete wheel zoom (no gesture) fires `onZoom` instead. - * - `pivotRadiusMpc` reaches BOTH in-module clamp sites (pinch, and a wheel + * - `pivotFraming` reaches BOTH in-module clamp sites (pinch, and a wheel * during a held gesture), so a zoom-in on a framed body stops just off its - * surface instead of passing through the centre. `standoffRadii` reaches - * the same two sites for a body's own floor override (Sgr A*'s 2 r_s). + * surface instead of passing through the centre — including a body's own + * floor override (Sgr A*'s 2 r_s), carried in the same bundle. * * Vitest runs in `node` here (no jsdom), so — matching * `inputBindings.test.ts` — we hand-roll EventTarget recorders for the @@ -51,10 +51,22 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; import { attachOrbitControls } from '../../../src/services/camera/orbitControls'; import { createOrbitCamera } from '../../../src/utils/camera/createOrbitCamera'; import { SCALE_UNITS } from '../../../src/data/scaleUnits'; +import { MIN_DISTANCE_MPC, SURFACE_STANDOFF_RADII } from '../../../src/utils/camera/clampDistance'; import type { OrbitCamera } from '../../../src/@types/camera/OrbitCamera'; +import type { PivotFraming } from '../../../src/@types/camera/PivotFraming'; /** Earth's mean radius (km → Mpc) — the pivot radius for the zoom-floor cases. */ const EARTH_RADIUS_MPC = 6371 * SCALE_UNITS.KM_TO_MPC; +/** The bundle a resolved Earth focus row resolves to (`pivotFraming`, no override). */ +const earthPivot = (): PivotFraming => ({ + radiusMpc: EARTH_RADIUS_MPC, + floorMpc: EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII, +}); +/** Same, but with a per-body standoff override (Sgr A*'s Q10 case is the real one). */ +const earthPivotWithStandoff = (standoffRadii: number): PivotFraming => ({ + radiusMpc: EARTH_RADIUS_MPC, + floorMpc: Math.max(MIN_DISTANCE_MPC, EARTH_RADIUS_MPC * standoffRadii), +}); type Listener = (e: unknown) => void; @@ -419,7 +431,7 @@ describe('attachOrbitControls — the zoom floor stops at a focused body’s sur const { canvas, rec } = makeCanvas(); attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, + pivotFraming: earthPivot, }); rec.fire('pointerdown', { @@ -455,7 +467,7 @@ describe('attachOrbitControls — the zoom floor stops at a focused body’s sur const { canvas, rec } = makeCanvas(); attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, + pivotFraming: earthPivot, }); rec.fire('pointerdown', { @@ -475,9 +487,9 @@ describe('attachOrbitControls — the zoom floor stops at a focused body’s sur describe('attachOrbitControls — the standoff override reaches both zoom sites', () => { // Same two in-module sites as the surface-floor tests above, but exercising - // the `standoffRadii` getter (Sgr A*'s Q10 2 r_s floor is the real case): - // without it reaching pinch + wheel-during-gesture, a body with an override - // would still stop at the Earth-tuned global ratio instead of its own. + // `pivotFraming`'s per-body floor override (Sgr A*'s Q10 2 r_s is the real + // case): without it reaching pinch + wheel-during-gesture, a body with an + // override would still stop at the Earth-tuned global ratio instead of its own. const STANDOFF = 3.0; // well above SURFACE_STANDOFF_RADII (~1.0000024) it('pinching in floors at the override, not the global ratio', () => { @@ -486,8 +498,7 @@ describe('attachOrbitControls — the standoff override reaches both zoom sites' const { canvas, rec } = makeCanvas(); attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, - standoffRadii: () => STANDOFF, + pivotFraming: () => earthPivotWithStandoff(STANDOFF), }); rec.fire('pointerdown', { @@ -519,8 +530,7 @@ describe('attachOrbitControls — the standoff override reaches both zoom sites' const { canvas, rec } = makeCanvas(); attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, - standoffRadii: () => STANDOFF, + pivotFraming: () => earthPivotWithStandoff(STANDOFF), }); rec.fire('pointerdown', { @@ -537,13 +547,13 @@ describe('attachOrbitControls — the standoff override reaches both zoom sites' expect(radii).toBeLessThan(STANDOFF * 1.05); }); - it('with no standoffRadii getter, the pinch floor is the global ratio unchanged', () => { + it('with no standoff override in the bundle, the pinch floor is the global ratio unchanged', () => { const cam = makeCamera(); cam.distance = EARTH_RADIUS_MPC * 4; const { canvas, rec } = makeCanvas(); attachOrbitControls(canvas as unknown as HTMLCanvasElement, cam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, + pivotFraming: earthPivot, }); rec.fire('pointerdown', { @@ -585,14 +595,14 @@ describe('attachOrbitControls — orbit-drag rate damps near a focused body’s nearCam.distance = EARTH_RADIUS_MPC * 1.02; // ~127 km altitude, near-surface regime const { canvas: nearCanvas, rec: nearRec } = makeCanvas(); attachOrbitControls(nearCanvas as unknown as HTMLCanvasElement, nearCam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, + pivotFraming: earthPivot, }); const farCam = makeCamera(); farCam.distance = EARTH_RADIUS_MPC * 1000; // deep orbital view of the same body const { canvas: farCanvas, rec: farRec } = makeCanvas(); attachOrbitControls(farCanvas as unknown as HTMLCanvasElement, farCam, { - pivotRadiusMpc: () => EARTH_RADIUS_MPC, + pivotFraming: earthPivot, }); // Identical drag (+50 px) on both, driven through the same window — each @@ -624,7 +634,7 @@ describe('attachOrbitControls — orbit-drag rate damps near a focused body’s }); it('with no pivot radius, a drag yaws by exactly today’s flat dx * 0.005', () => { - // No pivotRadiusMpc option at all ⇒ pivotRadius() resolves to null ⇒ + // No pivotFraming option at all ⇒ pivot() resolves to NO_PIVOT ⇒ // orbitRadPerPixel returns the flat cap unchanged — the deep-space / // unfocused path this change must not touch. const cam = makeCamera(); diff --git a/tests/services/engine/camera/applyWheelZoom.test.ts b/tests/services/engine/camera/applyWheelZoom.test.ts index 6bb0efa671..3500f61597 100644 --- a/tests/services/engine/camera/applyWheelZoom.test.ts +++ b/tests/services/engine/camera/applyWheelZoom.test.ts @@ -17,15 +17,27 @@ import { createCameraClock, autoRotateElapsed, } from '../../../../src/services/engine/camera/cameraClock'; -import { MAX_DISTANCE_MPC } from '../../../../src/utils/camera/clampDistance'; +import { + MIN_DISTANCE_MPC, + MAX_DISTANCE_MPC, + SURFACE_STANDOFF_RADII, +} from '../../../../src/utils/camera/clampDistance'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import type { CameraPose } from '../../../../src/@types/camera/CameraPose'; +import type { PivotFraming } from '../../../../src/@types/camera/PivotFraming'; const BASE: CameraPose = { target: [0, 0, 0], yaw: 1, pitch: 0.2, distance: 100 }; const FRAME_MS = 1000 / 60; const SPIN_OFF = { active: false, rate: 0 }; /** Earth's mean radius (km → Mpc) — the pivot radius for the surface-floor case. */ const EARTH_RADIUS_MPC = 6371 * SCALE_UNITS.KM_TO_MPC; +/** No focused pivot — the absolute floor, no taper anchor. */ +const NO_PIVOT: PivotFraming = { radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }; +/** The bundle a resolved Earth focus row resolves to (`pivotFraming`, no override). */ +const EARTH_PIVOT: PivotFraming = { + radiusMpc: EARTH_RADIUS_MPC, + floorMpc: EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII, +}; describe('applyWheelZoom', () => { it('scales the follow distance target in place while following (zoom is not swallowed)', () => { @@ -36,7 +48,7 @@ describe('applyWheelZoom', () => { const clock = createCameraClock(); clock.followDistanceTarget = 50; - const result = applyWheelZoom(clock, 'followBody', BASE, 1.2, SPIN_OFF, 0, null); + const result = applyWheelZoom(clock, 'followBody', BASE, 1.2, SPIN_OFF, 0, NO_PIVOT); expect(result).toBeNull(); // nothing to commit into the store expect(clock.followDistanceTarget).toBeCloseTo(60, 9); // 50 * 1.2 @@ -45,7 +57,7 @@ describe('applyWheelZoom', () => { it('clamps the scaled follow target to the shared zoom envelope', () => { const clock = createCameraClock(); clock.followDistanceTarget = MAX_DISTANCE_MPC; - applyWheelZoom(clock, 'followBody', BASE, 1000, SPIN_OFF, 0, null); + applyWheelZoom(clock, 'followBody', BASE, 1000, SPIN_OFF, 0, NO_PIVOT); expect(clock.followDistanceTarget).toBe(MAX_DISTANCE_MPC); }); @@ -57,7 +69,7 @@ describe('applyWheelZoom', () => { // standing between the camera and the mantle. const clock = createCameraClock(); clock.followDistanceTarget = EARTH_RADIUS_MPC * 4; - applyWheelZoom(clock, 'followBody', BASE, 1e-6, SPIN_OFF, 0, EARTH_RADIUS_MPC); + applyWheelZoom(clock, 'followBody', BASE, 1e-6, SPIN_OFF, 0, EARTH_PIVOT); const radii = clock.followDistanceTarget! / EARTH_RADIUS_MPC; expect(radii).toBeGreaterThan(1); @@ -66,7 +78,7 @@ describe('applyWheelZoom', () => { it('commits the zoomed base when the resting driver owns the distance', () => { const clock = createCameraClock(); - const result = applyWheelZoom(clock, 'resting', BASE, 2, SPIN_OFF, 0, null); + const result = applyWheelZoom(clock, 'resting', BASE, 2, SPIN_OFF, 0, NO_PIVOT); expect(result).not.toBeNull(); expect(result!.distance).toBeCloseTo(200, 9); // 100 * 2 // The follow target is untouched — resting reads base, not the follow clock. @@ -91,7 +103,7 @@ describe('applyWheelZoom', () => { 0.5, { active: true, rate }, 500, - null, + NO_PIVOT, ); expect(result).not.toBeNull(); @@ -111,7 +123,7 @@ describe('applyWheelZoom', () => { 0.5, { active: false, rate: 0.01 }, 500, - null, + NO_PIVOT, ); expect(result).not.toBeNull(); expect(result!.yaw).toBe(BASE.yaw); // no spin folded in @@ -124,7 +136,7 @@ describe('applyWheelZoom', () => { // the framing distance on its first produce. const clock = createCameraClock(); clock.followDistanceTarget = null; - const result = applyWheelZoom(clock, 'followBody', BASE, 1.1, SPIN_OFF, 0, null); + const result = applyWheelZoom(clock, 'followBody', BASE, 1.1, SPIN_OFF, 0, NO_PIVOT); expect(result).not.toBeNull(); expect(result!.distance).toBeCloseTo(110, 9); }); diff --git a/tests/services/engine/camera/pivotRadiusMpc.test.ts b/tests/services/engine/camera/pivotRadiusMpc.test.ts index 1bc9564853..e123f03e48 100644 --- a/tests/services/engine/camera/pivotRadiusMpc.test.ts +++ b/tests/services/engine/camera/pivotRadiusMpc.test.ts @@ -11,7 +11,14 @@ import { describe, it, expect } from 'vitest'; -import { pivotRadiusMpc } from '../../../../src/services/engine/camera/pivotRadiusMpc'; +import { + pivotRadiusMpc, + pivotFraming, +} from '../../../../src/services/engine/camera/pivotRadiusMpc'; +import { + MIN_DISTANCE_MPC, + SURFACE_STANDOFF_RADII, +} from '../../../../src/utils/camera/clampDistance'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import { makeGalaxyRow } from '../../../fixtures/makeGalaxyRow'; import type { SelectionRow } from '../../../../src/@types/engine/SelectionRow'; @@ -52,3 +59,61 @@ describe('pivotRadiusMpc', () => { expect(pivotRadiusMpc(null)).toBeNull(); }); }); + +describe('pivotFraming', () => { + it('floors a body row at the global ratio when it carries no override', () => { + expect(pivotFraming(EARTH_ROW).floorMpc).toBeCloseTo( + 6371 * SCALE_UNITS.KM_TO_MPC * SURFACE_STANDOFF_RADII, + 30, + ); + }); + + it('floors a body row at its own override — Sgr A’s Q10 descent floor (2 r_s)', () => { + // Far outside the Earth-tuned global ratio, so a body that opts in must be + // floored at ITS OWN multiple, not the shared constant. + const sgrAStar: SelectionRow = { + type: 'body', + id: 'sgr-a-star', + label: 'Sagittarius A*', + positionMpc: [0, 0, 0], + radiusM: 1.269e10, + standoffRadii: 2.0, + }; + const radiusMpc = 1.269e10 * SCALE_UNITS.M_TO_MPC; + expect(pivotFraming(sgrAStar)).toEqual({ radiusMpc, floorMpc: radiusMpc * 2.0 }); + }); + + it('a body smaller than the absolute floor still gets the absolute floor', () => { + // A 10 km moonlet's own standoff (~10.2 km) is far below MIN_DISTANCE_MPC + // (~309 km), where the near-plane ratio stops being well conditioned. The + // floor is a max of the two, so the absolute floor wins for tiny pivots. + const moonlet: SelectionRow = { + type: 'body', + id: 'moonlet', + label: 'Moonlet', + positionMpc: [0, 0, 0], + radiusM: 10000, + }; + expect(pivotFraming(moonlet).floorMpc).toBe(MIN_DISTANCE_MPC); + }); + + it('falls through to the global ratio for a star, and to the absolute floor for a galaxy / no focus', () => { + const star: SelectionRow = { + type: 'star', + index: 7, + positionMpc: [1, 2, 3], + absMag: 4, + bpRp: 0.6, + radiusM: 696340000, + }; + expect(pivotFraming(star).floorMpc).toBeCloseTo( + 696340 * SCALE_UNITS.KM_TO_MPC * SURFACE_STANDOFF_RADII, + 30, + ); + expect(pivotFraming(makeGalaxyRow({ diameterKpc: 30 }))).toEqual({ + radiusMpc: null, + floorMpc: MIN_DISTANCE_MPC, + }); + expect(pivotFraming(null)).toEqual({ radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }); + }); +}); diff --git a/tests/services/engine/camera/pivotStandoffRadii.test.ts b/tests/services/engine/camera/pivotStandoffRadii.test.ts deleted file mode 100644 index 4a9af3db6f..0000000000 --- a/tests/services/engine/camera/pivotStandoffRadii.test.ts +++ /dev/null @@ -1,58 +0,0 @@ -/** - * pivotStandoffRadii — which focus rows override the global standoff ratio. - * - * The one case that matters: a body row carrying `standoffRadii` (Sgr A*'s - * Q10 floor) must reach the clamp instead of the Earth-tuned global ratio. - * Everything else — no override on the row, a star, a galaxy, no focus at - * all — must fall through to `SURFACE_STANDOFF_RADII` so every other body's - * floor stays byte-identical to today. - */ - -import { describe, it, expect } from 'vitest'; - -import { pivotStandoffRadii } from '../../../../src/services/engine/camera/pivotStandoffRadii'; -import { SURFACE_STANDOFF_RADII } from '../../../../src/utils/camera/clampDistance'; -import { makeGalaxyRow } from '../../../fixtures/makeGalaxyRow'; -import type { SelectionRow } from '../../../../src/@types/engine/SelectionRow'; - -describe('pivotStandoffRadii', () => { - it('reads a body row’s own override', () => { - const sgrAStar: SelectionRow = { - type: 'body', - id: 'sgr-a-star', - label: 'Sagittarius A*', - positionMpc: [0, 0, 0], - radiusM: 1.269e10, - standoffRadii: 2.0, - }; - expect(pivotStandoffRadii(sgrAStar)).toBe(2.0); - }); - - it('falls through to the global ratio for a body row with no override', () => { - const earth: SelectionRow = { - type: 'body', - id: 'earth', - label: 'Earth', - positionMpc: [0, 0, 0], - radiusM: 6371000, - }; - expect(pivotStandoffRadii(earth)).toBe(SURFACE_STANDOFF_RADII); - }); - - it('falls through to the global ratio for a star row — no per-record override field', () => { - const star: SelectionRow = { - type: 'star', - index: 7, - positionMpc: [1, 2, 3], - absMag: 4, - bpRp: 0.6, - radiusM: 696340000, - }; - expect(pivotStandoffRadii(star)).toBe(SURFACE_STANDOFF_RADII); - }); - - it('falls through to the global ratio for a galaxy and for no focus at all', () => { - expect(pivotStandoffRadii(makeGalaxyRow({ diameterKpc: 30 }))).toBe(SURFACE_STANDOFF_RADII); - expect(pivotStandoffRadii(null)).toBe(SURFACE_STANDOFF_RADII); - }); -}); diff --git a/tests/services/engine/phases/wireInput.test.ts b/tests/services/engine/phases/wireInput.test.ts index f439b81308..d4a70bed40 100644 --- a/tests/services/engine/phases/wireInput.test.ts +++ b/tests/services/engine/phases/wireInput.test.ts @@ -103,7 +103,10 @@ import { requestFocus } from '../../../../src/state/selection/requestFocus'; import { EARTH_REF } from '../../../../src/data/selection/earthRef'; import { setSelectionRow } from '../../../../src/state/selectionRows/selectionRowsSlice'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; -import { SURFACE_STANDOFF_RADII } from '../../../../src/utils/camera/clampDistance'; +import { + MIN_DISTANCE_MPC, + SURFACE_STANDOFF_RADII, +} from '../../../../src/utils/camera/clampDistance'; import type { OrbitControlsOptions } from '../../../../src/@types/camera/OrbitControlsOptions'; // ── Fixtures ───────────────────────────────────────────────────────── @@ -265,7 +268,7 @@ describe('wireInput', () => { expect(selectFocusRef(root)).toEqual(jupiter); }); - it('hands the orbit controls a live read of the focused body’s radius', async () => { + it('hands the orbit controls a live read of the focused body’s radius + zoom floor', async () => { // The zoom floor lives in clampDistance, but the pinch / wheel-during-gesture // sites inside orbitControls can only apply it if this phase supplies the // getter. Drop the wiring and the camera silently scrolls through the planet @@ -279,15 +282,16 @@ describe('wireInput', () => { await wireInput(state, deps); const options = attachOrbitControlsSpy.mock.calls[0]?.[2] as OrbitControlsOptions | undefined; - const read = options?.pivotRadiusMpc; + const read = options?.pivotFraming; expect(read).toBeTypeOf('function'); // Nothing resolved yet (the row cache is saga-filled and no saga runs here): // no surface to stand off from, so the absolute floor applies. - expect(read!()).toBeNull(); + expect(read!()).toEqual({ radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }); - // With Earth's row resolved, the getter reports its radius in Mpc — read - // through on every call, so a focus change needs no re-attach. + // With Earth's row resolved, the getter reports its radius (Mpc) and the + // global-ratio floor — read through on every call, so a focus change needs + // no re-attach. deps.cb.store.dispatch( setSelectionRow({ slot: 'focus', @@ -300,26 +304,14 @@ describe('wireInput', () => { }, }), ); - expect(read!()).toBeCloseTo(6371 * SCALE_UNITS.KM_TO_MPC, 30); - }); - - it('hands the orbit controls a live read of the focused body’s standoff override', async () => { - // Same wiring gap, one field over: without this getter, Sgr A*'s Q10 floor - // (`standoffRadii: 2.0`) never reaches the pinch / wheel-during-gesture - // sites and the camera stops at the Earth-tuned global ratio instead. - const state = makeState(); - const deps = makeDeps(); - attachOrbitControlsSpy.mockClear(); - - await wireInput(state, deps); - - const options = attachOrbitControlsSpy.mock.calls[0]?.[2] as OrbitControlsOptions | undefined; - const read = options?.standoffRadii; - expect(read).toBeTypeOf('function'); - - // Nothing resolved yet: no per-body override, so the global ratio applies. - expect(read!()).toBe(SURFACE_STANDOFF_RADII); - + const earthRadiusMpc = 6371 * SCALE_UNITS.KM_TO_MPC; + expect(read!().radiusMpc).toBeCloseTo(earthRadiusMpc, 30); + expect(read!().floorMpc).toBeCloseTo(earthRadiusMpc * SURFACE_STANDOFF_RADII, 30); + + // Swapping to a body with its own override (Sgr A*'s Q10 floor of 2 r_s) + // changes the floor to ITS multiple, not the Earth-tuned global ratio — + // without this getter reaching `pivotFraming`, the camera would stop at + // the wrong surface. deps.cb.store.dispatch( setSelectionRow({ slot: 'focus', @@ -333,7 +325,8 @@ describe('wireInput', () => { }, }), ); - expect(read!()).toBe(2.0); + const sgrARadiusMpc = 1.269e10 * SCALE_UNITS.M_TO_MPC; + expect(read!()).toEqual({ radiusMpc: sgrARadiusMpc, floorMpc: sgrARadiusMpc * 2.0 }); }); it('defers the seed to a galaxy/star id still parked in a deferred resolve', async () => { diff --git a/tests/utils/camera/clampDistance.test.ts b/tests/utils/camera/clampDistance.test.ts index 6674befcf3..215a7deb00 100644 --- a/tests/utils/camera/clampDistance.test.ts +++ b/tests/utils/camera/clampDistance.test.ts @@ -1,13 +1,12 @@ /** - * clampDistance — the shared zoom envelope, and the per-pivot floor that stops - * the camera at a framed body's surface. + * clampDistance — the shared zoom envelope: ceiling `MAX_DISTANCE_MPC`, floor + * whatever `floorMpc` the caller precomputed. * - * The floor is the interesting half. The camera dollies toward its orbit target, - * which for a body is the CENTRE, so a global floor is meaningless in body radii: - * the absolute floor (1e-17 Mpc ≈ 309 km) is 0.048 Earth radii, i.e. thousands of - * km inside the planet. These tests are written in BODY RADII rather than Mpc so - * they assert the property ("outside the surface, close to it") instead of - * restating the standoff constant. + * `floorMpc` derivation (radius · standoff, MIN-floored, per-body override) + * moved to `pivotFraming` (`pivotRadiusMpc.test.ts`) — these tests pin the + * two-arg clamp itself. Distances near a body are written in BODY RADII + * rather than Mpc so they assert the property ("outside the surface, close + * to it") instead of restating the standoff constant. */ import { describe, it, expect } from 'vitest'; @@ -25,44 +24,48 @@ import { bodyFocusDistance } from '../../../src/services/engine/camera/bodyFocus * distance `galaxyFocusDistance()` can return — see * `src/services/engine/camera/galaxyFocusDistance.ts: MIN_FOCUS_DISTANCE_MPC`. * A sub-floor wheel-zoom input must not ratchet that distance outward; - * `clampDistance(GALAXY_FOCUS_MIN_MPC, null)` must return the value unchanged. + * `clampDistance(GALAXY_FOCUS_MIN_MPC, MIN_DISTANCE_MPC)` must return the + * value unchanged. */ const GALAXY_FOCUS_MIN_MPC = 0.15; /** Earth's mean radius (km → Mpc) — spelled out so the test owns its subject. */ const EARTH_RADIUS_MPC = 6371 * SCALE_UNITS.KM_TO_MPC; -describe('clampDistance — no pivot radius (empty space, galaxy, structure)', () => { +/** The floor a focus row with no standoff override resolves to — see `pivotFraming`. */ +const EARTH_FLOOR_MPC = EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII; + +describe('clampDistance — floor at the absolute minimum (no pivot: empty space, galaxy, structure)', () => { it('floors at MIN_DISTANCE_MPC', () => { // 1e-30 is well below the absolute floor. - expect(clampDistance(1e-30, null)).toBe(MIN_DISTANCE_MPC); + expect(clampDistance(1e-30, MIN_DISTANCE_MPC)).toBe(MIN_DISTANCE_MPC); }); it('caps at MAX_DISTANCE_MPC', () => { // A distance beyond the observable-universe limit is clamped to MAX. - expect(clampDistance(1e9, null)).toBe(MAX_DISTANCE_MPC); + expect(clampDistance(1e9, MIN_DISTANCE_MPC)).toBe(MAX_DISTANCE_MPC); }); it('does not ratchet the galaxy focus-on end distance', () => { - // The per-pivot floor must never reach up into galaxy-focus territory: a - // focus tween that ends at 0.15 Mpc has to pass through untouched, or every + // The floor must never reach up into galaxy-focus territory: a focus + // tween that ends at 0.15 Mpc has to pass through untouched, or every // galaxy focus would be pushed back out again. - expect(clampDistance(GALAXY_FOCUS_MIN_MPC, null)).toBe(GALAXY_FOCUS_MIN_MPC); + expect(clampDistance(GALAXY_FOCUS_MIN_MPC, MIN_DISTANCE_MPC)).toBe(GALAXY_FOCUS_MIN_MPC); }); it('returns an in-bounds value unchanged', () => { const mid = 10; // 10 Mpc — squarely inside [1e-17, 30000] - expect(clampDistance(mid, null)).toBe(mid); + expect(clampDistance(mid, MIN_DISTANCE_MPC)).toBe(mid); }); }); -describe('clampDistance — pivoted on a body', () => { +describe('clampDistance — floored at a precomputed body surface', () => { it('zooming in repeatedly settles just OUTSIDE the surface, never inside', () => { // Simulate the real gesture: exponential wheel ticks, each ~10% closer, far // more of them than it takes to blow through the planet (0.9^300 ≈ 1e-14). let distance = EARTH_RADIUS_MPC * 10; for (let i = 0; i < 300; i++) { - distance = clampDistance(distance * 0.9, EARTH_RADIUS_MPC); + distance = clampDistance(distance * 0.9, EARTH_FLOOR_MPC); } const radii = distance / EARTH_RADIUS_MPC; @@ -70,40 +73,11 @@ describe('clampDistance — pivoted on a body', () => { expect(radii).toBeLessThan(1.05); // and close enough to inspect it }); - it('a body smaller than the absolute floor still gets the absolute floor', () => { - // A 10 km moonlet's own standoff (~10.2 km) is far below MIN_DISTANCE_MPC - // (~309 km), where the near-plane ratio stops being well conditioned. The - // floor is a max of the two, so the absolute floor wins for tiny pivots. - const moonletRadiusMpc = 10 * SCALE_UNITS.KM_TO_MPC; - expect(clampDistance(1e-30, moonletRadiusMpc)).toBe(MIN_DISTANCE_MPC); - }); - it('leaves the body-framing distance untouched — only a deliberate zoom reaches the floor', () => { // Cross-check between two constants that have to stay ordered: the standoff // must sit INSIDE the screen-fill framing distance, or every fresh body focus // would be clamped and land somewhere other than where the framing asked for. const framing = bodyFocusDistance(EARTH_RADIUS_MPC, (Math.PI / 180) * 60); - expect(clampDistance(framing, EARTH_RADIUS_MPC)).toBe(framing); - }); -}); - -describe('clampDistance — per-body standoff', () => { - it('floors at the given ratio instead of SURFACE_STANDOFF_RADII', () => { - // Sgr A*'s descent floor (2 r_s) is far outside the Earth-tuned global - // ratio, so a body that opts in must be floored at ITS OWN multiple, not - // the shared constant. - const radiusMpc = EARTH_RADIUS_MPC; // any body radius exercises the same math - const belowFloor = radiusMpc * 0.5; // deep inside the body - expect(clampDistance(belowFloor, radiusMpc, 2.0)).toBeCloseTo(radiusMpc * 2.0, 30); - }); - - it('omitted standoffRadii keeps Earth’s current floor unchanged', () => { - // The zero-change proof: every existing two-arg call site (every body that - // doesn't carry a `standoffRadii` override) must be byte-identical to - // today's behaviour. - const belowFloor = EARTH_RADIUS_MPC * 0.5; - expect(clampDistance(belowFloor, EARTH_RADIUS_MPC)).toBe( - clampDistance(belowFloor, EARTH_RADIUS_MPC, SURFACE_STANDOFF_RADII), - ); + expect(clampDistance(framing, EARTH_FLOOR_MPC)).toBe(framing); }); }); diff --git a/tests/utils/camera/zoomedDistance.test.ts b/tests/utils/camera/zoomedDistance.test.ts index 144ee1802f..e6f9b331ab 100644 --- a/tests/utils/camera/zoomedDistance.test.ts +++ b/tests/utils/camera/zoomedDistance.test.ts @@ -19,11 +19,19 @@ import { describe, it, expect } from 'vitest'; import { zoomedDistance } from '../../../src/utils/camera/zoomedDistance'; -import { SURFACE_STANDOFF_RADII } from '../../../src/utils/camera/clampDistance'; +import { MIN_DISTANCE_MPC, SURFACE_STANDOFF_RADII } from '../../../src/utils/camera/clampDistance'; import { SCALE_UNITS } from '../../../src/data/scaleUnits'; +import type { PivotFraming } from '../../../src/@types/camera/PivotFraming'; /** Earth's mean radius (km → Mpc). */ const EARTH_RADIUS_MPC = 6371 * SCALE_UNITS.KM_TO_MPC; +/** The bundle a resolved Earth focus row resolves to (`pivotFraming`, no override). */ +const EARTH_PIVOT: PivotFraming = { + radiusMpc: EARTH_RADIUS_MPC, + floorMpc: EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII, +}; +/** No focused pivot — the absolute floor, no taper anchor. */ +const NO_PIVOT: PivotFraming = { radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }; describe('zoomedDistance', () => { it('tapers into the standoff floor: zoom-in steps shrink and never overshoot it', () => { @@ -37,7 +45,7 @@ describe('zoomedDistance', () => { const stepSizes: number[] = []; for (let i = 0; i < 8; i++) { - const next = zoomedDistance(distance, factor, EARTH_RADIUS_MPC); + const next = zoomedDistance(distance, factor, EARTH_PIVOT); // Never overshoots below the standoff floor. expect(next).toBeGreaterThanOrEqual(floor - 1e-30); // Each notch is still a zoom-IN (distance strictly decreases) until it @@ -58,7 +66,7 @@ describe('zoomedDistance', () => { // camera settles AT the floor rather than ever crossing it — the // asymptotic approach the taper is meant to produce. for (let i = 0; i < 100; i++) { - distance = zoomedDistance(distance, factor, EARTH_RADIUS_MPC); + distance = zoomedDistance(distance, factor, EARTH_PIVOT); } expect(distance).toBeCloseTo(floor, 9); }); @@ -71,7 +79,7 @@ describe('zoomedDistance', () => { const factor = 0.87; const plainModel = distance * factor; - const result = zoomedDistance(distance, factor, EARTH_RADIUS_MPC); + const result = zoomedDistance(distance, factor, EARTH_PIVOT); expect(Math.abs(result - plainModel) / plainModel).toBeLessThan(1e-5); }); @@ -80,8 +88,8 @@ describe('zoomedDistance', () => { // null means "no surface to taper against" — deep space, a galaxy, a // structure. The taper must not engage; distance scales exactly as it did // before this change existed. - expect(zoomedDistance(100, 2, null)).toBe(200); - expect(zoomedDistance(100, 0.5, null)).toBe(50); + expect(zoomedDistance(100, 2, NO_PIVOT)).toBe(200); + expect(zoomedDistance(100, 0.5, NO_PIVOT)).toBe(50); }); it('falls back to the proportional model (still respecting the floor) if already at or below the surface', () => { @@ -90,7 +98,7 @@ describe('zoomedDistance', () => { // fallback should still land the camera on the standoff floor rather than // diverging or returning something below the pivot's surface. const distance = EARTH_RADIUS_MPC * 0.5; // already inside the body - const result = zoomedDistance(distance, 0.9, EARTH_RADIUS_MPC); + const result = zoomedDistance(distance, 0.9, EARTH_PIVOT); expect(result).toBeCloseTo(EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII, 12); }); }); diff --git a/tests/utils/camera/zoomedPose.test.ts b/tests/utils/camera/zoomedPose.test.ts index 67110d753f..1144e033d8 100644 --- a/tests/utils/camera/zoomedPose.test.ts +++ b/tests/utils/camera/zoomedPose.test.ts @@ -2,7 +2,7 @@ * zoomedPose — unit tests for the wheel-zoom pose computation. * * Confirms distance scales by the factor and clamps to the shared envelope, - * that the pivot radius reaches the clamp (so a zoom on a resting or spun pose + * that the pivot bundle reaches the clamp (so a zoom on a resting or spun pose * pinned to a body still stops at its surface), that orientation * (target/yaw/pitch) carries over, and that the returned target is a fresh array * (no aliasing of the input pose's array). @@ -11,9 +11,14 @@ import { describe, it, expect } from 'vitest'; import { zoomedPose } from '../../../src/utils/camera/zoomedPose'; -import { MIN_DISTANCE_MPC, MAX_DISTANCE_MPC } from '../../../src/utils/camera/clampDistance'; +import { + MIN_DISTANCE_MPC, + MAX_DISTANCE_MPC, + SURFACE_STANDOFF_RADII, +} from '../../../src/utils/camera/clampDistance'; import { SCALE_UNITS } from '../../../src/data/scaleUnits'; import type { CameraPose } from '../../../src/@types/camera/CameraPose'; +import type { PivotFraming } from '../../../src/@types/camera/PivotFraming'; const makePose = (distance: number): CameraPose => ({ target: [1, 2, 3], @@ -24,40 +29,47 @@ const makePose = (distance: number): CameraPose => ({ /** Earth's mean radius (km → Mpc). */ const EARTH_RADIUS_MPC = 6371 * SCALE_UNITS.KM_TO_MPC; +/** The bundle a resolved Earth focus row resolves to (`pivotFraming`, no override). */ +const EARTH_PIVOT: PivotFraming = { + radiusMpc: EARTH_RADIUS_MPC, + floorMpc: EARTH_RADIUS_MPC * SURFACE_STANDOFF_RADII, +}; +/** No focused pivot — the absolute floor, no taper anchor. */ +const NO_PIVOT: PivotFraming = { radiusMpc: null, floorMpc: MIN_DISTANCE_MPC }; describe('zoomedPose', () => { it('scales distance by the factor', () => { - const result = zoomedPose(makePose(100), 2, null); + const result = zoomedPose(makePose(100), 2, NO_PIVOT); expect(result.distance).toBe(200); }); it('zooming in (factor < 1) reduces distance', () => { - const result = zoomedPose(makePose(100), 0.5, null); + const result = zoomedPose(makePose(100), 0.5, NO_PIVOT); expect(result.distance).toBe(50); }); it('clamps to the maximum distance', () => { - const result = zoomedPose(makePose(MAX_DISTANCE_MPC), 1000, null); + const result = zoomedPose(makePose(MAX_DISTANCE_MPC), 1000, NO_PIVOT); expect(result.distance).toBe(MAX_DISTANCE_MPC); }); it('clamps to the minimum distance', () => { - const result = zoomedPose(makePose(MIN_DISTANCE_MPC), 0.0001, null); + const result = zoomedPose(makePose(MIN_DISTANCE_MPC), 0.0001, NO_PIVOT); expect(result.distance).toBe(MIN_DISTANCE_MPC); }); it('floors at a pivoted body’s surface rather than the absolute minimum', () => { // The frame loop pins a resting / auto-rotating pose to the focused body, so - // the zoom it applies has to floor off that body's surface too — the radius + // the zoom it applies has to floor off that body's surface too — the bundle // must reach the clamp, not be dropped on the way through. - const result = zoomedPose(makePose(EARTH_RADIUS_MPC * 4), 1e-6, EARTH_RADIUS_MPC); + const result = zoomedPose(makePose(EARTH_RADIUS_MPC * 4), 1e-6, EARTH_PIVOT); const radii = result.distance / EARTH_RADIUS_MPC; expect(radii).toBeGreaterThan(1); expect(radii).toBeLessThan(1.05); }); it('carries target, yaw, and pitch over unchanged', () => { - const result = zoomedPose(makePose(100), 2, null); + const result = zoomedPose(makePose(100), 2, NO_PIVOT); expect(result.target).toEqual([1, 2, 3]); expect(result.yaw).toBe(0.5); expect(result.pitch).toBe(-0.3); @@ -65,7 +77,7 @@ describe('zoomedPose', () => { it('returns a fresh target array — not the input pose’s', () => { const base = makePose(100); - const result = zoomedPose(base, 2, null); + const result = zoomedPose(base, 2, NO_PIVOT); expect(result.target).not.toBe(base.target); }); }); From 3f9134900f3397135588391836700867357cb696 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 12:45:35 +0200 Subject: [PATCH 10/60] refactor(camera): fix review findings on the PivotFraming merge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 2b review (fix round 1): - SelectionRow.d.ts's standoffRadii comment still named the deleted pivotStandoffRadii helper; points at pivotFraming instead. - pivotRadiusMpc.ts's module header ran 12 lines, over the ≤10 budget; trimmed both doc comments to their load-bearing why (outside-lane consumers, the null-radius floor equivalence) and dropped restated detail. Co-Authored-By: Claude Fable 5 --- src/@types/engine/SelectionRow.d.ts | 2 +- src/services/engine/camera/pivotRadiusMpc.ts | 21 +++++++------------- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/src/@types/engine/SelectionRow.d.ts b/src/@types/engine/SelectionRow.d.ts index 4ebdc1d9a9..90aade6093 100644 --- a/src/@types/engine/SelectionRow.d.ts +++ b/src/@types/engine/SelectionRow.d.ts @@ -32,7 +32,7 @@ export type SelectionRow = readonly positionMpc: Vec3; readonly radiusM: number; // Carried through from `AnchorPointBody.standoffRadii` (e.g. Sgr A*'s - // Q10 floor) — the zoom clamp reads it via `pivotStandoffRadii`. + // Q10 floor) — the zoom clamp reads it via `pivotFraming`. readonly standoffRadii?: number; } // Star arm — the self-contained display projection of a picked star, its diff --git a/src/services/engine/camera/pivotRadiusMpc.ts b/src/services/engine/camera/pivotRadiusMpc.ts index 6809d8f833..df42062a07 100644 --- a/src/services/engine/camera/pivotRadiusMpc.ts +++ b/src/services/engine/camera/pivotRadiusMpc.ts @@ -1,14 +1,9 @@ /** - * pivotRadiusMpc — the physical radius (Mpc) of whatever sits at the camera's - * orbit pivot, or `null` when the pivot has no surface. - * - * The one place that maps a resolved `SelectionRow` onto a pivot radius. A - * body or survey star is a surface the camera can crash into; a galaxy, a - * structure, or the Milky Way is a volume the camera flies INTO, so those stay - * `null` and unfloored. `runFrame.ts`/`frameContext.ts`/`logCameraState.ts` - * consume this scalar directly (altitude math, debug logging) — `pivotFraming` - * below is the orbit-controls lane's own bundle, built beside it in the same - * file rather than displacing this export. + * pivotRadiusMpc — physical radius (Mpc) of the camera's orbit pivot, or + * `null` when it has no surface (galaxy/structure/Milky Way — flown INTO, + * never floored). `runFrame.ts`/`frameContext.ts`/`logCameraState.ts` import + * this scalar directly, so `pivotFraming` (the orbit-controls zoom-floor + * bundle) is built beside it below rather than displacing it. */ import { SCALE_UNITS } from '../../../data/scaleUnits'; @@ -23,10 +18,8 @@ export function pivotRadiusMpc(row: SelectionRow | null): number | null { } /** - * pivotFraming — the orbit-controls lane's single getter target: radius + - * precomputed zoom floor for the resolved focus row. `standoffRadii` reads a - * body row's own override (Sgr A*'s Q10 floor) else the global ratio. - * `radiusMpc ?? 0` makes a surfaceless pivot's floor collapse to + * pivotFraming — orbit-controls' single getter target: radius + precomputed + * zoom floor. `radiusMpc ?? 0` collapses a surfaceless pivot's floor to * `MIN_DISTANCE_MPC`, matching the old null-radius clamp exactly. */ export function pivotFraming(row: SelectionRow | null): PivotFraming { From 2fab16ed6efc4e6f4071b390799f66791d00599f Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:24:38 +0200 Subject: [PATCH 11/60] feat(bodies): Schwarzschild radius from mass via physics util Replace SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM constant with mass-derived physics util schwarzschildRadiusM(). Enables mass-keyed derivations (deflection LUT, emission annulus) to share the same computation. - Add schwarzschildRadiusM(massSolar): m with G/c constants - Add SGR_A_STAR_MASS_SOLAR = 4.297e6 (GRAVITY Collab 2019) - sceneSgrAStar.ts: radiusM = schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR) - sStarOrbitInfo.ts: migrate pericentre/r_s card row to new source - Delete sgrAStarSchwarzschildRadiusKm.ts (0 remaining refs) Co-Authored-By: Claude Fable 5 --- src/data/bodies/sStarOrbitInfo.ts | 5 +++-- src/data/bodies/sceneSgrAStar.ts | 7 ++++--- src/data/bodies/sgrAStarMassSolar.ts | 7 +++++++ .../bodies/sgrAStarSchwarzschildRadiusKm.ts | 14 -------------- src/utils/physics/schwarzschildRadiusM.ts | 19 +++++++++++++++++++ .../physics/schwarzschildRadiusM.test.ts | 14 ++++++++++++++ 6 files changed, 47 insertions(+), 19 deletions(-) create mode 100644 src/data/bodies/sgrAStarMassSolar.ts delete mode 100644 src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts create mode 100644 src/utils/physics/schwarzschildRadiusM.ts create mode 100644 tests/utils/physics/schwarzschildRadiusM.test.ts diff --git a/src/data/bodies/sStarOrbitInfo.ts b/src/data/bodies/sStarOrbitInfo.ts index 9d5ad89fc6..b7f7db433a 100644 --- a/src/data/bodies/sStarOrbitInfo.ts +++ b/src/data/bodies/sStarOrbitInfo.ts @@ -10,15 +10,16 @@ */ import { pericentreSpeedKmS } from '../../utils/orbit/pericentreSpeedKmS'; +import { schwarzschildRadiusM } from '../../utils/physics/schwarzschildRadiusM'; import { SCALE_UNITS } from '../scaleUnits'; import { sStar } from './makers/sStar'; import { SGR_A_STAR } from './sceneSgrAStar'; -import { SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM } from './sgrAStarSchwarzschildRadiusKm'; +import { SGR_A_STAR_MASS_SOLAR } from './sgrAStarMassSolar'; import { S_STAR_SEEDS } from './sStarElements'; import type { BodyOrbitInfo } from '../../@types/engine/BodyOrbitInfo'; const SCHWARZSCHILD_RADIUS_AU = - (SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM * SCALE_UNITS.KM_TO_MPC) / SCALE_UNITS.AU_TO_MPC; + (schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR) * SCALE_UNITS.M_TO_MPC) / SCALE_UNITS.AU_TO_MPC; const S_STAR_ORBIT_INFO: ReadonlyMap = new Map( S_STAR_SEEDS.map((seed): [string, BodyOrbitInfo] => { diff --git a/src/data/bodies/sceneSgrAStar.ts b/src/data/bodies/sceneSgrAStar.ts index dd5508ba42..ed36f05685 100644 --- a/src/data/bodies/sceneSgrAStar.ts +++ b/src/data/bodies/sceneSgrAStar.ts @@ -16,9 +16,10 @@ */ import { raDecDistToCartesian } from '../../utils/math/raDecDistToCartesian'; +import { schwarzschildRadiusM } from '../../utils/physics/schwarzschildRadiusM'; import { SCALE_UNITS } from '../scaleUnits'; import { SGR_A_STAR_ENTRY } from '../sources/sgr-a-star'; -import { SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM } from './sgrAStarSchwarzschildRadiusKm'; +import { SGR_A_STAR_MASS_SOLAR } from './sgrAStarMassSolar'; import type { AnchorBody } from '../../@types/scene/AnchorBody'; import type { AnchorPointBody } from '../../@types/scene/AnchorPointBody'; @@ -37,8 +38,8 @@ const SGR_A_STAR_DISTANCE_PC = 8178; export const SGR_A_STAR: AnchorPointBody = { id: SGR_A_STAR_ENTRY.id, label: SGR_A_STAR_ENTRY.label, - // Wire/authored value is km; runtime convention is metres. - radiusM: SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM * SCALE_UNITS.KM_TO_M, + // schwarzschildRadiusM returns metres directly. + radiusM: schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR), // Q10's descent floor: the camera may approach to 2 r_s, well inside the // Earth-tuned global SURFACE_STANDOFF_RADII (~1.0000024). standoffRadii: 2.0, diff --git a/src/data/bodies/sgrAStarMassSolar.ts b/src/data/bodies/sgrAStarMassSolar.ts new file mode 100644 index 0000000000..e3905d9f69 --- /dev/null +++ b/src/data/bodies/sgrAStarMassSolar.ts @@ -0,0 +1,7 @@ +/** + * sgrAStarMassSolar — Sgr A* mass in solar masses. + * + * GRAVITY Collaboration 2019, A&A 625, L10 — the same orbit fit that gives + * the 8178 pc distance the anchor uses. + */ +export const SGR_A_STAR_MASS_SOLAR = 4.297e6; diff --git a/src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts b/src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts deleted file mode 100644 index 64802870a3..0000000000 --- a/src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts +++ /dev/null @@ -1,14 +0,0 @@ -/** - * sgrAStarSchwarzschildRadiusKm — the one home for Sgr A*'s event-horizon scale - * in kilometres, the sibling of `solarRadiusKm`. - * - * Sgr A* draws no geometry, so this is not a mesh size: it is the radius the - * body registry carries (in metres — the figure its InfoCard prints), and - * the divisor that expresses an S-star pericentre in Schwarzschild radii. Two - * readers, so one constant. - * - * `r_s = 2GM/c²` for `M = 4.297 × 10⁶ M☉` (GRAVITY Collaboration 2019, A&A 625, - * L10 — the same orbit fit that gives the 8178 pc distance the anchor uses), or - * 0.085 AU. - */ -export const SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM = 12.69e6; diff --git a/src/utils/physics/schwarzschildRadiusM.ts b/src/utils/physics/schwarzschildRadiusM.ts new file mode 100644 index 0000000000..2273c2c868 --- /dev/null +++ b/src/utils/physics/schwarzschildRadiusM.ts @@ -0,0 +1,19 @@ +/** + * schwarzschildRadiusM — Schwarzschild radius in metres. + * + * r_s = 2GM/c² is the radius of the event horizon for a non-rotating black hole. + */ + +// Named locals: SI physical constants. References: IAU, CODATA 2018, NIST. +// Speed of light (exact by definition since 1983). +const C_M_S = 299792458; +// Gravitational constant. +const G_M3_KG_S2 = 6.67430e-11; +// One solar mass in kg. +const SOLAR_MASS_KG = 1.98892e30; + +export function schwarzschildRadiusM(massSolar: number): number { + const massKg = massSolar * SOLAR_MASS_KG; + const cSquared = C_M_S * C_M_S; + return (2 * G_M3_KG_S2 * massKg) / cSquared; +} diff --git a/tests/utils/physics/schwarzschildRadiusM.test.ts b/tests/utils/physics/schwarzschildRadiusM.test.ts new file mode 100644 index 0000000000..e8ed642733 --- /dev/null +++ b/tests/utils/physics/schwarzschildRadiusM.test.ts @@ -0,0 +1,14 @@ +import { describe, it, expect } from 'vitest'; + +import { schwarzschildRadiusM } from '../../../src/utils/physics/schwarzschildRadiusM'; +import { SGR_A_STAR_MASS_SOLAR } from '../../../src/data/bodies/sgrAStarMassSolar'; + +describe('schwarzschildRadiusM', () => { + it('computes Sgr A* Schwarzschild radius within float tolerance', () => { + // r_s = 2GM/c² for M = 4.297 × 10⁶ M☉ ≈ 1.2693 × 10¹⁰ m. + // Hand-computed reference value, not a re-derivation of the same formula. + const expectedM = 1.2693371e10; + const precision = -6; // Allows ~0.03% relative tolerance for physical constants. + expect(schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)).toBeCloseTo(expectedM, precision); + }); +}); From bbaf0712a5e13908e23fdd344747723c4b62c5e6 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:28:33 +0200 Subject: [PATCH 12/60] feat(engine): add sgrAStarLensing fade band for black-hole lens pass Implements the scale-fade band that engages the black-hole lens pass on close approach to Sgr A*. The band inverts the direction of milkyWayApproachGc (full at close edge, 0 at far edge) and pins the edge ordering via a classifier test that would catch a backwards band. Co-Authored-By: Claude Fable 5 --- .../engine/presentation/scaleFadeBands.ts | 7 ++++++ .../presentation/scaleFadeBands.test.ts | 23 +++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/src/services/engine/presentation/scaleFadeBands.ts b/src/services/engine/presentation/scaleFadeBands.ts index 571d41799e..bc038e4f01 100644 --- a/src/services/engine/presentation/scaleFadeBands.ts +++ b/src/services/engine/presentation/scaleFadeBands.ts @@ -141,4 +141,11 @@ export const SCALE_FADE_BANDS = { // `goneAt` IS the partition-boundary symbol `BODY_GLINT_MAX_PX` — one // source, cannot drift. bodyGlint: { fullAt: 1, goneAt: BODY_GLINT_MAX_PX }, + + // Keyed on: CAMERA distance from the `galactic-centre` region's anchor + // (Sgr A*), Mpc. An approach fade — opposite direction from + // milkyWayApproachGc. Engages the black-hole lens pass on close approach + // to Sgr A*; the far-field glint alpha is derived from this band + // (1 - fadeBand) at its call site. + sgrAStarLensing: { fullAt: 100 * SCALE_UNITS.AU_TO_MPC, goneAt: 500 * SCALE_UNITS.AU_TO_MPC }, } as const satisfies Readonly>; diff --git a/tests/services/engine/presentation/scaleFadeBands.test.ts b/tests/services/engine/presentation/scaleFadeBands.test.ts index c04c103e48..50b8ce311e 100644 --- a/tests/services/engine/presentation/scaleFadeBands.test.ts +++ b/tests/services/engine/presentation/scaleFadeBands.test.ts @@ -16,6 +16,7 @@ import { FOREGROUND_MAX_DISTANCE_MPC } from '../../../../src/services/engine/fra import { SOLAR_SYSTEM_LABEL_MAX_DISTANCE_MPC } from '../../../../src/services/engine/frame/solarSystemLabelMaxDistance'; import { regionById } from '../../../../src/utils/scene/regionById'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; +import { fadeBand } from '../../../../src/utils/math/fadeBand'; const NEIGHBOURHOOD_EXTENT_MPC = regionById('solar-neighbourhood').extentMpc; const SOLAR_SYSTEM_EXTENT_MPC = regionById('solar-system').extentMpc; @@ -71,3 +72,25 @@ describe('both backdrop bands derive from one shape', () => { ); }); }); + +describe('sgrAStarLensing band — 100/500 AU envelope in Mpc, approach direction', () => { + it('the sgrAStarLensing fade band engages on approach to Sgr A*', () => { + // The band classification is critical: since fullAt < goneAt, fadeBand + // returns 1 at the close edge and 0 at the far edge, implementing a fade-IN + // as the camera approaches. A retune that swapped the edges would flip the + // direction and cause the lens pass to fade OUT on approach (the opposite of + // the intended effect). This test pins the edge ordering; classifiers catch + // backwards bands. + const fullAtMpc = 100 * SCALE_UNITS.AU_TO_MPC; + const goneAtMpc = 500 * SCALE_UNITS.AU_TO_MPC; + + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, fullAtMpc)).toBe(1); + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, goneAtMpc)).toBe(0); + + // A midpoint value is strictly between 0 and 1, confirming the smooth ramp. + const midpointMpc = (fullAtMpc + goneAtMpc) / 2; + const midpointAlpha = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, midpointMpc); + expect(midpointAlpha).toBeGreaterThan(0); + expect(midpointAlpha).toBeLessThan(1); + }); +}); From d3498bdd0e6c3f0488a5f4cdaf4f501b5f1a13a3 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:28:13 +0200 Subject: [PATCH 13/60] feat(data): add BLACK_HOLES registry and BlackHoleRow type Introduces BlackHoleRow type in src/@types/data/BlackHoleRow.d.ts defining the emission parameters for supermassive black holes (inner/outer Schwarzschild radii, inclination, position angle, flicker). Adds BLACK_HOLES append-only registry in src/data/blackHoles.ts with the Sgr A* entry. Co-Authored-By: Claude Fable 5 --- src/@types/data/BlackHoleRow.d.ts | 22 +++++++++++++++++++ src/data/blackHoles.ts | 35 +++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 src/@types/data/BlackHoleRow.d.ts create mode 100644 src/data/blackHoles.ts diff --git a/src/@types/data/BlackHoleRow.d.ts b/src/@types/data/BlackHoleRow.d.ts new file mode 100644 index 0000000000..77026866b3 --- /dev/null +++ b/src/@types/data/BlackHoleRow.d.ts @@ -0,0 +1,22 @@ +/** + * `BlackHoleRow` — static data binding for supermassive black holes in the scene. + * + * Built as an append-only registry holding more than one row; M87* is data (not + * code) pending a data-driven black-hole catalog. Each row ties an identity to + * disk-emission parameters (inner/outer radii in Schwarzschild units, inclination, + * rotation, stochastic flicker) readable by the renderer on close approach. + */ + +import type { BodyId } from './body/BodyId'; + +export type BlackHoleRow = { + readonly bodyId: BodyId; + readonly emission: { + readonly innerRs: number; // Schwarzschild radii; inner edge of the accretion disc + readonly outerRs: number; // Schwarzschild radii; photon ring / EHT imaging radius + readonly inclinationRad: number; // radians; face-on view ≲30° per EHT observations + readonly positionAngleRad: number; // radians; major-axis orientation angle (unconstrained, tuned for visual) + readonly flickerAmp: number; // fractional brightness modulation (0..1) + readonly flickerTimescaleS: number; // seconds; typical timescale of flicker variations + }; +}; diff --git a/src/data/blackHoles.ts b/src/data/blackHoles.ts new file mode 100644 index 0000000000..9a21e7b7d9 --- /dev/null +++ b/src/data/blackHoles.ts @@ -0,0 +1,35 @@ +/** + * `BLACK_HOLES` — static registry of supermassive black holes in the scene. + * + * Append-only table binding each black hole identity to its disk-emission parameters. + * Today holding only Sgr A* (our Galactic Centre); M87* is data (not code) once a + * data-driven catalog exists. Emission tuning (inclination, position angle, flicker) + * is visual taste until observational anchoring data becomes available. + */ + +import type { BlackHoleRow } from '../@types/data/BlackHoleRow'; + +export const BLACK_HOLES: readonly BlackHoleRow[] = [ + { + bodyId: 'sgr-a-star', + emission: { + // ISCO (innermost stable circular orbit) to EHT photon ring (Event Horizon + // Telescope's nominal imaging radius). Hard constraint: no physical spin, + // Schwarzschild only. + innerRs: 3, + outerRs: 6, + // Face-on view is ≲30° per EHT polarimetry. Chosen value at ~20°; the exact + // angle is unconstrained but fixed for reproducible renders. + inclinationRad: Math.PI / 9, // ~20° + // Major-axis position angle (E of N, standard astronomical convention). + // Entirely unconstrained; set to 45° for visual variety. Adjust here or via + // Task 15 debug panel. + positionAngleRad: Math.PI / 4, // 45° + // Stochastic brightening/dimming at minute-to-hour timescales (Sgr A* manifests + // minute-scale near-IR flares; we borrow that timescale). Amplitude is tasteful + // dev tuning — no published NIR variability-index texture yet. Range 0..1. + flickerAmp: 0.15, // ±15% brightness modulation + flickerTimescaleS: 120, // ~2 minutes + }, + }, +]; From aacd4510e29744fefc9b344292270ae1ba9dc2ce Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:34:33 +0200 Subject: [PATCH 14/60] fix(bodies): test reference from spec, comment budget, tolerance clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review findings (fix round 1): 1. Test: use spec's externally cited figure (12.69e6 km = 1.269e10 m, GRAVITY 2019) with explicit ~0.1% relative tolerance, not back-filled implementation output. Show reference source in test comment. 2. schwarzschildRadiusM.ts: consolidate inline comments to stay within budget (≤3 comment lines, half of 6 code lines). 3. Test tolerance comment: clarify ~0.1% relative (not 0.004% absolute). UI impact noted: S-star pericentre card shifts ~0.027%, Sgr A* radius from 12.69e6 km to 12.69337e6 km — expected outcome of using mass-derived constant. Co-Authored-By: Claude Fable 5 --- src/utils/physics/schwarzschildRadiusM.ts | 9 ++------- tests/utils/physics/schwarzschildRadiusM.test.ts | 16 ++++++++++------ 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/src/utils/physics/schwarzschildRadiusM.ts b/src/utils/physics/schwarzschildRadiusM.ts index 2273c2c868..de1fbc61f7 100644 --- a/src/utils/physics/schwarzschildRadiusM.ts +++ b/src/utils/physics/schwarzschildRadiusM.ts @@ -1,15 +1,10 @@ /** - * schwarzschildRadiusM — Schwarzschild radius in metres. - * - * r_s = 2GM/c² is the radius of the event horizon for a non-rotating black hole. + * schwarzschildRadiusM — Schwarzschild radius in metres; r_s = 2GM/c². + * SI constants: c (exact), G (CODATA 2018), M☉ (NIST). */ -// Named locals: SI physical constants. References: IAU, CODATA 2018, NIST. -// Speed of light (exact by definition since 1983). const C_M_S = 299792458; -// Gravitational constant. const G_M3_KG_S2 = 6.67430e-11; -// One solar mass in kg. const SOLAR_MASS_KG = 1.98892e30; export function schwarzschildRadiusM(massSolar: number): number { diff --git a/tests/utils/physics/schwarzschildRadiusM.test.ts b/tests/utils/physics/schwarzschildRadiusM.test.ts index e8ed642733..8189119c64 100644 --- a/tests/utils/physics/schwarzschildRadiusM.test.ts +++ b/tests/utils/physics/schwarzschildRadiusM.test.ts @@ -4,11 +4,15 @@ import { schwarzschildRadiusM } from '../../../src/utils/physics/schwarzschildRa import { SGR_A_STAR_MASS_SOLAR } from '../../../src/data/bodies/sgrAStarMassSolar'; describe('schwarzschildRadiusM', () => { - it('computes Sgr A* Schwarzschild radius within float tolerance', () => { - // r_s = 2GM/c² for M = 4.297 × 10⁶ M☉ ≈ 1.2693 × 10¹⁰ m. - // Hand-computed reference value, not a re-derivation of the same formula. - const expectedM = 1.2693371e10; - const precision = -6; // Allows ~0.03% relative tolerance for physical constants. - expect(schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)).toBeCloseTo(expectedM, precision); + it('computes Sgr A* Schwarzschild radius within relative tolerance', () => { + // Reference: GRAVITY Collaboration 2019, A&A 625, L10 — the spec's + // externally cited figure is 12.69e6 km = 1.269e10 m (not back-filled + // from the implementation's output). + const expectedM = 1.269e10; + const result = schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR); + const relError = Math.abs(result - expectedM) / expectedM; + // ~0.1% relative tolerance catches physics bugs (wrong power, missing 2, + // unit slip are all ≫0.1%) while allowing constant-precision drift. + expect(relError).toBeLessThan(0.001); }); }); From 494e4222ae8e6531a255e563fbe4857a10eed4fd Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:34:30 +0200 Subject: [PATCH 15/60] feat(gpu): add SgrAStarLensingUniforms struct + CPU packer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 10 of the Sgr A* black-hole render plan: the 144-byte uniform byte-layout contract between the (not-yet-written) lens WGSL pass and its CPU-side uploader. Follows the CameraUniforms shared-prefix pattern — 80-byte cam prefix, renderer-specific scalars at offset 80+, anchorPosRelCamM (the f64->f32 rebase seam) 16-byte aligned at 128. Adds a byte-offset parity test in the style of packAtmosphereUniforms.test.ts, driving the real packer with distinct sentinel values per slot. Co-Authored-By: Claude Fable 5 --- .../gpu/shaders/lib/sgrAStarLensing.wesl | 60 ++++++++++ src/utils/gpu/packSgrAStarLensingUniforms.ts | 106 +++++++++++++++++ .../gpu/packSgrAStarLensingUniforms.test.ts | 108 ++++++++++++++++++ 3 files changed, 274 insertions(+) create mode 100644 src/services/gpu/shaders/lib/sgrAStarLensing.wesl create mode 100644 src/utils/gpu/packSgrAStarLensingUniforms.ts create mode 100644 tests/utils/gpu/packSgrAStarLensingUniforms.test.ts diff --git a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl new file mode 100644 index 0000000000..3379dde059 --- /dev/null +++ b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl @@ -0,0 +1,60 @@ +// lib/sgrAStarLensing.wesl — byte-layout contract (exceeds the usual header +// budget on that basis, same allowance camera.wesl takes) for the Sgr A* +// lens pass's per-frame uniform buffer. +// +// This is the struct-only half of the contract task-10 owns; the pass that +// binds it (the lens vertex/fragment pair, LUT texture sampling, the fold +// image itself) is Task 13's job, not this file's. 'SchwarzschildDeflectionLut +// .samples' upload as a separate 1D texture, NOT a field here — only the two +// scalars that address it ('lutMinImpactParamRs'/'lutMaxImpactParamRs') and +// its texel count ride in the uniform buffer. +// +// ## Byte layout (canonical — the offset authority for the CPU packer) +// +// offset 0 : cam: CameraUniforms (80 B shared prefix — viewProj +// 0..63, viewportPx 64..71, +// _pad0 72..75, _pad1 76..79) +// offset 80 : schwarzschildRadiusM f32 — r_s in metres +// offset 84 : innerRs f32 — emission annulus inner edge, r_s units +// offset 88 : outerRs f32 — emission annulus outer edge, r_s units +// offset 92 : inclinationRad f32 +// offset 96 : positionAngleRad f32 +// offset 100 : flickerAmp f32 +// offset 104 : flickerTimescaleS f32 +// offset 108 : flickerPhase f32 — sim-clock-derived, per-frame +// offset 112 : lutMinImpactParamRs f32 — SchwarzschildDeflectionLut.minImpactParamRs +// offset 116 : lutMaxImpactParamRs f32 — SchwarzschildDeflectionLut.maxImpactParamRs +// offset 120 : lutSampleCount f32 — LUT texture's texel count +// offset 124 : bandAlpha f32 — fade band's own alpha this frame +// offset 128 : anchorPosRelCamM vec3 — camera-relative anchor, metres (f64->f32 rebase seam) +// offset 140 : _pad2 f32 — rounds the struct to 144 / 16-byte +// total: 144 bytes. +// +// The 12 scalar fields (80..127, 48 bytes) exactly fill the run up to 128, +// so 'anchorPosRelCamM' lands on a 16-byte boundary with no implicit padding +// — the same "count the scalars before a vec3" check 'camera.wesl' and +// 'milkyWay/sprites/io.wesl' document. The CPU-side 'Float32Array' must +// write each field at the matching f32 index (see 'packSgrAStarLensingUniforms.ts', +// the single source of truth for that half of the contract) or the GPU +// silently reads garbage — no compile error, no runtime error, just a wrong +// (or on iOS, dropped) frame. + +import package::lib::camera::CameraUniforms; + +struct SgrAStarLensingUniforms { + cam: CameraUniforms, + schwarzschildRadiusM: f32, + innerRs: f32, + outerRs: f32, + inclinationRad: f32, + positionAngleRad: f32, + flickerAmp: f32, + flickerTimescaleS: f32, + flickerPhase: f32, + lutMinImpactParamRs: f32, + lutMaxImpactParamRs: f32, + lutSampleCount: f32, + bandAlpha: f32, + anchorPosRelCamM: vec3, + _pad2: f32, +}; diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts new file mode 100644 index 0000000000..b1fe903d9d --- /dev/null +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -0,0 +1,106 @@ +/** + * packSgrAStarLensingUniforms — pure packer for the 144-byte + * `SgrAStarLensingUniforms` struct (`shaders/lib/sgrAStarLensing.wesl`). + * + * Task 10's half of the uniform contract between the Sgr A* lens pass + * (Task 13, not yet written) and its WGSL. The struct is the shared + * `CameraUniforms` prefix (`writeCameraPrefix`, the same helper every + * world-space renderer uses) plus the lens's own scalar params, the LUT + * addressing pair, this frame's fade-band alpha, and the camera-relative + * anchor position (the f64->f32 rebase seam `bodyGlintsLayer` / + * `starPointsLayer` already use — the caller subtracts the eye and folds + * it into `viewProj` before calling this). + * + * ## Byte layout (must stay byte-exact with `shaders/lib/sgrAStarLensing.wesl`) + * + * f32 0..15 (byte 0.. 63): cam.viewProj mat4x4 + * f32 16..17 (byte 64.. 71): cam.viewportPx vec2 + * f32 18..19 (byte 72.. 79): cam._pad0 / _pad1 untouched (zero) + * f32 20 (byte 80.. 83): schwarzschildRadiusM f32 + * f32 21 (byte 84.. 87): innerRs f32 + * f32 22 (byte 88.. 91): outerRs f32 + * f32 23 (byte 92.. 95): inclinationRad f32 + * f32 24 (byte 96.. 99): positionAngleRad f32 + * f32 25 (byte 100..103): flickerAmp f32 + * f32 26 (byte 104..107): flickerTimescaleS f32 + * f32 27 (byte 108..111): flickerPhase f32 + * f32 28 (byte 112..115): lutMinImpactParamRs f32 + * f32 29 (byte 116..119): lutMaxImpactParamRs f32 + * f32 30 (byte 120..123): lutSampleCount f32 + * f32 31 (byte 124..127): bandAlpha f32 + * f32 32..34 (byte 128..139): anchorPosRelCamM vec3 + * f32 35 (byte 140..143): _pad2 — untouched (zero) + * + * Total: 144 bytes / 36 f32. The 12 scalars at f32 20..31 exactly fill the + * run up to f32 32, so `anchorPosRelCamM` lands on a 16-byte boundary with + * no implicit padding — see the .wesl module header for the alignment + * argument. + * + * `lutSampleCount` is packed as `f32` (the brief allows `f32` or `u32`; a + * texel count round-trips exactly through f32 up to 2^24, far beyond any + * plausible LUT size, so there is no precision reason to special-case a + * `u32` write into this otherwise-uniform `Float32Array`). + * + * @param viewProj 16-element column-major view-projection, already camera-rebased. + * @param viewportPx Viewport size in device pixels. + * @param schwarzschildRadiusM r_s in metres — the pass's own scale unit. + * @param innerRs Emission annulus inner edge, r_s units. + * @param outerRs Emission annulus outer edge, r_s units. + * @param inclinationRad Disk inclination, radians. + * @param positionAngleRad Disk position angle, radians. + * @param flickerAmp Emission flicker amplitude. + * @param flickerTimescaleS Emission flicker timescale, seconds. + * @param flickerPhase Sim-clock-derived flicker phase, uploaded per frame. + * @param lutMinImpactParamRs `SchwarzschildDeflectionLut.minImpactParamRs`. + * @param lutMaxImpactParamRs `SchwarzschildDeflectionLut.maxImpactParamRs`. + * @param lutSampleCount The LUT texture's texel count. + * @param bandAlpha This frame's fade-band alpha (gates emission/deflection strength in-shader). + * @param anchorPosRelCamM Camera-relative anchor position, metres. + */ + +import type { Mat4 } from 'wgpu-matrix'; +import type { Vec2 } from '../../@types/math/Vec2'; +import type { Vec3 } from '../../@types/math/Vec3'; +import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/cameraUniforms'; + +/** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 + * scalars + anchorPosRelCamM (3) + pad (1) = 36. */ +export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 16; + +export function packSgrAStarLensingUniforms( + viewProj: Float32Array | Mat4, + viewportPx: Vec2, + schwarzschildRadiusM: number, + innerRs: number, + outerRs: number, + inclinationRad: number, + positionAngleRad: number, + flickerAmp: number, + flickerTimescaleS: number, + flickerPhase: number, + lutMinImpactParamRs: number, + lutMaxImpactParamRs: number, + lutSampleCount: number, + bandAlpha: number, + anchorPosRelCamM: Readonly, +): Float32Array { + const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); + writeCameraPrefix(out, viewProj, viewportPx); // f32 0..17; 18..19 stay zero + out[20] = schwarzschildRadiusM; // byte 80 + out[21] = innerRs; // byte 84 + out[22] = outerRs; // byte 88 + out[23] = inclinationRad; // byte 92 + out[24] = positionAngleRad; // byte 96 + out[25] = flickerAmp; // byte 100 + out[26] = flickerTimescaleS; // byte 104 + out[27] = flickerPhase; // byte 108 + out[28] = lutMinImpactParamRs; // byte 112 + out[29] = lutMaxImpactParamRs; // byte 116 + out[30] = lutSampleCount; // byte 120 + out[31] = bandAlpha; // byte 124 + out[32] = anchorPosRelCamM[0]; // byte 128 — vec3, 16-byte aligned + out[33] = anchorPosRelCamM[1]; // byte 132 + out[34] = anchorPosRelCamM[2]; // byte 136 + // out[35] (byte 140) stays zero — _pad2, rounds the struct to 144. + return out; +} diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts new file mode 100644 index 0000000000..ce8751a17d --- /dev/null +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -0,0 +1,108 @@ +/** + * SgrAStarLensingUniforms byte-layout guard. + * + * The WGSL `SgrAStarLensingUniforms` struct in `shaders/lib/sgrAStarLensing.wesl` + * and the CPU-side `packSgrAStarLensingUniforms` must agree byte-for-byte: a + * mismatch produces no GPU error, just a wrong (or, on iOS, silently dropped) + * frame. This is the `testing.md` keep-rule for uniform layouts — it fails on a + * real drift no compiler check catches (Task 13's lens pass, not yet written, + * is the eventual consumer of this contract). + * + * Drives the real packer with distinct, non-round values in every slot (no + * two sentinels equal, so a swapped pair of fields is caught) and reads the + * returned `Float32Array` at the offsets the struct pins. + */ + +import { describe, it, expect } from 'vitest'; +import { + packSgrAStarLensingUniforms, + SGR_A_STAR_LENSING_UNIFORM_FLOATS, +} from '../../../src/utils/gpu/packSgrAStarLensingUniforms'; +import type { Vec2 } from '../../../src/@types/math/Vec2'; +import type { Vec3 } from '../../../src/@types/math/Vec3'; + +// A recognisable viewProj: 1..16 so any transposition or off-by-one +// placement of a later field into the matrix block shows up as a wrong value. +const VIEW_PROJ = new Float32Array(16); +for (let i = 0; i < 16; i++) VIEW_PROJ[i] = i + 1; + +const VIEWPORT_PX: Vec2 = [1920, 1080]; + +// Distinct, non-round scalars — dyadic fractions where possible so the +// float32 round-trip is exact and `toBe` needs no tolerance, yet no two +// sentinels are equal (swap-proof). +const SCHWARZSCHILD_RADIUS_M = 12030000128; // ~r_s of Sgr A*, snapped to a float32-exact multiple of 2048 +const INNER_RS = 2.5; +const OUTER_RS = 12.5; +const INCLINATION_RAD = 0.9375; // dyadic (15/16) — float32-exact, unlike 0.9625 +const POSITION_ANGLE_RAD = 1.1875; +const FLICKER_AMP = 0.34375; +const FLICKER_TIMESCALE_S = 315.5; +const FLICKER_PHASE = 0.71875; +const LUT_MIN_IMPACT_PARAM_RS = 2.09375; +const LUT_MAX_IMPACT_PARAM_RS = 40.5; +const LUT_SAMPLE_COUNT = 256; +const BAND_ALPHA = 0.578125; +const ANCHOR_POS_REL_CAM_M: Vec3 = [3.5, -1.25, 7.75]; + +describe('SgrAStarLensingUniforms byte offsets', () => { + it('packs a 144-byte / 36-f32 record with each field at its documented offset', () => { + const rec = packSgrAStarLensingUniforms( + VIEW_PROJ, + VIEWPORT_PX, + SCHWARZSCHILD_RADIUS_M, + INNER_RS, + OUTER_RS, + INCLINATION_RAD, + POSITION_ANGLE_RAD, + FLICKER_AMP, + FLICKER_TIMESCALE_S, + FLICKER_PHASE, + LUT_MIN_IMPACT_PARAM_RS, + LUT_MAX_IMPACT_PARAM_RS, + LUT_SAMPLE_COUNT, + BAND_ALPHA, + ANCHOR_POS_REL_CAM_M, + ); + + expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); + expect(rec.length).toBe(36); // 144 bytes + expect(rec.byteLength).toBe(144); + + // cam.viewProj — all 16 floats verbatim at bytes 0..63. + for (let i = 0; i < 16; i++) expect(rec[i]).toBe(VIEW_PROJ[i]); + + // cam.viewportPx — vec2 at byte 64 (float index 16). + expect(rec[16]).toBe(VIEWPORT_PX[0]); // byte 64 + expect(rec[17]).toBe(VIEWPORT_PX[1]); // byte 68 + + // cam._pad0/_pad1 — untouched, stay zero. + expect(rec[18]).toBe(0); // byte 72 + expect(rec[19]).toBe(0); // byte 76 + + // Renderer-specific scalars, offset 80+ (float index 20+). + expect(rec[20]).toBe(SCHWARZSCHILD_RADIUS_M); // byte 80 + expect(rec[21]).toBe(INNER_RS); // byte 84 + expect(rec[22]).toBe(OUTER_RS); // byte 88 + expect(rec[23]).toBe(INCLINATION_RAD); // byte 92 + expect(rec[24]).toBe(POSITION_ANGLE_RAD); // byte 96 + expect(rec[25]).toBe(FLICKER_AMP); // byte 100 + expect(rec[26]).toBe(FLICKER_TIMESCALE_S); // byte 104 + expect(rec[27]).toBe(FLICKER_PHASE); // byte 108 + expect(rec[28]).toBe(LUT_MIN_IMPACT_PARAM_RS); // byte 112 + expect(rec[29]).toBe(LUT_MAX_IMPACT_PARAM_RS); // byte 116 + expect(rec[30]).toBe(LUT_SAMPLE_COUNT); // byte 120 + expect(rec[31]).toBe(BAND_ALPHA); // byte 124 + + // anchorPosRelCamM — vec3 at byte 128 (float index 32), 16-byte aligned: + // the 12 preceding scalars exactly fill the run up to 32, so no implicit + // padding was inserted ahead of it. + expect(rec[32]).toBe(ANCHOR_POS_REL_CAM_M[0]); // byte 128 + expect(rec[33]).toBe(ANCHOR_POS_REL_CAM_M[1]); // byte 132 + expect(rec[34]).toBe(ANCHOR_POS_REL_CAM_M[2]); // byte 136 + + // _pad2 — the vec3's trailing slot, rounds the struct to 144. Untouched, + // stays zero. + expect(rec[35]).toBe(0); // byte 140 + }); +}); From f09e75274848e10a69ca83996d5d3ee998fea59b Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:36:31 +0200 Subject: [PATCH 16/60] feat(engine): sky-cubemap render-target row + skyCubemapFaceContext MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The black-hole lens's sky-capture half: a fixed-size 6-layer 2d-array `sky-cubemap` row (Task 3's `fixedSizePx` mechanism) plus a per-face synthetic camera derivation, following the `pickFrameContext.ts` precedent — re-deriving a full `ReadyFrameContext` so roster layers' frame-global reads (fovYRad, canvasSize, drawPxPerRad) stay correct rather than threading a swapped vp by hand. Co-Authored-By: Claude Fable 5 --- src/@types/rendering/CubeFace.d.ts | 7 + .../engine/frame/skyCubemapFaceContext.ts | 99 ++++++++++ src/services/gpu/renderTargets.ts | 12 ++ .../frame/skyCubemapFaceContext.test.ts | 170 ++++++++++++++++++ tests/services/gpu/renderTargets.test.ts | 16 +- 5 files changed, 297 insertions(+), 7 deletions(-) create mode 100644 src/@types/rendering/CubeFace.d.ts create mode 100644 src/services/engine/frame/skyCubemapFaceContext.ts create mode 100644 tests/services/engine/frame/skyCubemapFaceContext.test.ts diff --git a/src/@types/rendering/CubeFace.d.ts b/src/@types/rendering/CubeFace.d.ts new file mode 100644 index 0000000000..4341b4b660 --- /dev/null +++ b/src/@types/rendering/CubeFace.d.ts @@ -0,0 +1,7 @@ +/** + * CubeFace — index into a `2d-array` render target's 6 layers when the array + * is later sampled as a `texture_cube` (see `RenderTargetSpec.fixedSizePx`). + * Order and orientation follow the WebGPU/D3D `texture_cube` convention, so a + * later cube-view bind of the captured layers needs no re-mapping. + */ +export type CubeFace = 0 | 1 | 2 | 3 | 4 | 5; // ±X, ±Y, ±Z, in that index order diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts new file mode 100644 index 0000000000..0a5d658e07 --- /dev/null +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -0,0 +1,99 @@ +/** + * skyCubemapFaceContext — one face of the black-hole sky cubemap's capture + * camera, as a value. Mirrors `pickFrameContext.ts` exactly: several roster + * layers read `ctx.fovYRad`/`ctx.canvasSize`/`ctx.drawPxPerRad` as + * frame-globals, not just `viewProj`, so this re-derives a full + * `ReadyFrameContext` from a synthetic camera (eye = `eyeMpc`, forward = the + * face's fixed axis, a 90° symmetric frustum) instead of threading a swapped + * vp through every roster-layer consumer. + */ + +import type { EngineState } from '../../../@types/engine/state/EngineState'; +import type { ReadyFrameContext } from '../../../@types/engine/frame/ReadyFrameContext'; +import type { CameraPose } from '../../../@types/camera/CameraPose'; +import type { CubeFace } from '../../../@types/rendering/CubeFace'; +import type { Vec3 } from '../../../@types/math/Vec3'; +import type { Mat3 } from '../../../@types/math/Mat3'; +import { deriveFrameContext } from './frameContext'; +import { deriveSourceMasks } from './deriveSourceMasks'; +import { mat3FromColumns } from '../../../utils/math/mat3FromColumns'; +import { cross3 } from '../../../utils/math/cross3'; + +/** + * Forward axis per `CubeFace` (index order ±X/±Y/±Z, see `CubeFace.d.ts`). + * `FACE_UP` is the WebGPU/D3D `texture_cube` convention's per-face up + * reference: world ±Y is parallel to forward on the ±Y faces, so those two + * borrow world ±Z instead. A later cube-view bind of this row's 6 layers + * relies on both tables matching that convention exactly. + */ +const FACE_FORWARD: readonly Vec3[] = [ + [1, 0, 0], + [-1, 0, 0], + [0, 1, 0], + [0, -1, 0], + [0, 0, 1], + [0, 0, -1], +]; +const FACE_UP: readonly Vec3[] = [ + [0, -1, 0], + [0, -1, 0], + [0, 0, 1], + [0, 0, -1], + [0, -1, 0], + [0, -1, 0], +]; + +/** + * One basis per face, doing double duty as both `poseBasis` and `upBasis`. + * With `yaw = pitch = 0` fixed below, `updatePosition` decodes local +Z + * through `poseBasis` — so this basis' THIRD column is set to `-forward` + * (target → eye), placing the derived eye exactly on `target - forward`. + * `ORIENTATION_FRAMES`' own convention puts a basis' pole in the MIDDLE + * column, which `frameUp` reads for screen-up — so the same matrix's middle + * column carries `FACE_UP`, and one basis serves both roles with no risk of + * the two drifting apart. + */ +const FACE_BASES: readonly Mat3[] = FACE_FORWARD.map((forward, i): Mat3 => { + const up = FACE_UP[i]!; + const back: Vec3 = [-forward[0], -forward[1], -forward[2]]; + return mat3FromColumns(cross3(up, back), up, back); +}); + +export function skyCubemapFaceContext(input: { + readonly state: EngineState; + readonly eyeMpc: Readonly; + readonly face: CubeFace; + readonly faceSizePx: number; +}): ReadyFrameContext | null { + const { state, eyeMpc, face, faceSizePx } = input; + const forward = FACE_FORWARD[face]!; + const basis = FACE_BASES[face]!; + // target = eyeMpc + forward, distance = 1: `updatePosition` then derives + // position = target + 1·(-forward) = eyeMpc exactly, for every face. + const target: Vec3 = [eyeMpc[0] + forward[0], eyeMpc[1] + forward[1], eyeMpc[2] + forward[2]]; + const pose: CameraPose = { target, yaw: 0, pitch: 0, distance: 1 }; + + const ctx = deriveFrameContext( + state, + // deriveFrameContext only reads `.width`/`.height` off this — there is no + // real canvas for an offscreen capture, so a size-shaped stub stands in. + { width: faceSizePx, height: faceSizePx } as unknown as HTMLCanvasElement, + pose, + // 90° symmetric frustum sized for a cube face; near/far ride the live + // engine projection so the capture clips at the same distances the main + // camera does. + { + fovYRad: Math.PI / 2, + aspect: 1, + near: state.cameraRuntime.projection.near, + far: state.cameraRuntime.projection.far, + }, + basis, + basis, + // Draw mask, not pick: this is a real capture pass, not a click target. + deriveSourceMasks(state).draw, + performance.now(), + state.cameraRuntime.lastRenderedSimDays.current, + ); + return ctx.isReady ? ctx : null; +} diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 321615d966..d00cfbce54 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -252,6 +252,18 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT clearValue: { r: 0, g: 0, b: 0, a: 0 }, }), ), + // The black-hole lens's captured environment: 6 layers of a fixed-size + // 2d-array, later bound as a `texture_cube` (see `CubeFace.d.ts`). Same + // depthless/additive/zero-clear profile as `hdr` — the captured roster + // (point-sprites, star-catalog/aggregates, S-star glints) is additive. + { + id: 'sky-cubemap', + format: HDR_TARGET_FORMAT, + depth: null, + scale: 1, // unused: fixedSizePx below overrides it (required by the type). + clearValue: { r: 0, g: 0, b: 0, a: 0 }, + fixedSizePx: { size: 256, layers: 6 }, + }, { id: 'swap', format: swapFormat, diff --git a/tests/services/engine/frame/skyCubemapFaceContext.test.ts b/tests/services/engine/frame/skyCubemapFaceContext.test.ts new file mode 100644 index 0000000000..9533b1c467 --- /dev/null +++ b/tests/services/engine/frame/skyCubemapFaceContext.test.ts @@ -0,0 +1,170 @@ +/** + * skyCubemapFaceContext — unit tests for the black-hole sky cubemap's + * per-face capture camera. + * + * Mirrors `pickFrameContext.test.ts`'s fixture shape (same bootstrap-gate + * handles, same `settings`/`subsystems` shape `deriveSourceMasks` reads) — + * see that file's header for why each field is there. + */ + +import { describe, it, expect } from 'vitest'; + +import { skyCubemapFaceContext } from '../../../../src/services/engine/frame/skyCubemapFaceContext'; +import { deriveSourceMasks } from '../../../../src/services/engine/frame/deriveSourceMasks'; +import { GALAXY_CATALOG_SOURCES } from '../../../../src/data/sources'; +import { galaxyCatalogIdOf } from '../../../../src/utils/galaxyCatalogIdOf'; +import type { EngineState } from '../../../../src/@types/engine/state/EngineState'; +import type { OrbitCamera } from '../../../../src/@types/camera/OrbitCamera'; +import type { CameraPose } from '../../../../src/@types/camera/CameraPose'; +import type { CameraProjection } from '../../../../src/@types/camera/CameraProjection'; +import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; +import type { Vec3 } from '../../../../src/@types/math/Vec3'; +import type { FadeId } from '../../../../src/@types/animation/FadeId'; + +const LAST_POSE: CameraPose = { target: [1, 2, 3], yaw: 0.5, pitch: 0.1, distance: 50 }; +const PROJECTION: CameraProjection = { fovYRad: 1.2, aspect: 16 / 9, near: 0.1, far: 10000 }; +const LAST_SIM_DAYS = 2460000.0; +const EYE_MPC: Readonly = [12, -34, 56]; + +// Index order matches `CubeFace`'s doc comment: ±X, ±Y, ±Z. +const EXPECTED_AXIS: readonly Vec3[] = [ + [1, 0, 0], + [-1, 0, 0], + [0, 1, 0], + [0, -1, 0], + [0, 0, 1], + [0, 0, -1], +]; + +/** + * Build an `EngineState`-shaped fixture with every bootstrap-gate handle + * populated (so `isEngineReady` passes by default) and a `cameraRuntime` + * carrying the live projection + last-frame epoch that + * `skyCubemapFaceContext` reads for near/far and `simDays`. + */ +function makeState( + overrides: { + cam?: OrbitCamera | null; + galaxyPointRenderer?: unknown; + renderTargets?: unknown; + galaxyPickRenderer?: unknown; + compositor?: unknown; + texturedDisks?: unknown; + } = {}, +): EngineState { + const cam = + overrides.cam === undefined + ? ({ + target: [0, 0, 0], + yaw: 0, + pitch: 0, + distance: 100, + position: new Float32Array(3), + } as unknown as OrbitCamera) + : overrides.cam; + const galaxyPointRenderer = + overrides.galaxyPointRenderer === undefined ? ({} as unknown) : overrides.galaxyPointRenderer; + const renderTargets = + overrides.renderTargets === undefined ? ({} as unknown) : overrides.renderTargets; + const galaxyPickRenderer = + overrides.galaxyPickRenderer === undefined ? ({} as unknown) : overrides.galaxyPickRenderer; + const compositor = overrides.compositor === undefined ? ({} as unknown) : overrides.compositor; + const texturedDisks = + overrides.texturedDisks === undefined ? ({} as unknown) : overrides.texturedDisks; + + const items = Object.fromEntries( + GALAXY_CATALOG_SOURCES.map((s) => [ + galaxyCatalogIdOf(s), + { enabled: true, labelEnabled: true }, + ]), + ); + + return { + cam, + gpu: { galaxyPointRenderer, renderTargets, galaxyPickRenderer, compositor }, + subsystems: { + texturedDisks, + fades: { opacityOf: (id: FadeId) => (id.kind === 'galaxyCatalog' ? 0 : 0) }, + }, + settings: { + galaxyCatalogs: { items }, + orientation: 'equatorial', + starCatalogs: { enabled: false, items: { famousStar: { enabled: false } } }, + bodies: { items: { sun: { enabled: false }, 's-star': { enabled: false } } }, + }, + selectionRows: { hover: null, select: null, focus: null }, + data: { bodies: { earth: null, planets: [], stars: [] } }, + cameraRuntime: { + lastPose: { current: LAST_POSE }, + projection: PROJECTION, + lastRenderedSimDays: { current: LAST_SIM_DAYS }, + }, + } as unknown as EngineState; +} + +describe('skyCubemapFaceContext', () => { + it('derives a ReadyFrameContext with the eye at the anchor position, looking along the requested face axis', () => { + const state = makeState(); + for (let face = 0; face < 6; face++) { + const ctx = skyCubemapFaceContext({ + state, + eyeMpc: EYE_MPC, + face: face as CubeFace, + faceSizePx: 256, + }); + expect(ctx).not.toBeNull(); + if (ctx === null) continue; + + expect(ctx.drawCamPos).toEqual(EYE_MPC); + + // Independent geometric check: the forward direction (target − eye, + // read off the assembled camera, not re-derived from yaw/pitch) must + // point exactly along this face's expected axis. + const cam = ctx.cam; + const fx = cam.target[0] - cam.position[0]; + const fy = cam.target[1] - cam.position[1]; + const fz = cam.target[2] - cam.position[2]; + const len = Math.hypot(fx, fy, fz); + const forward: Vec3 = [fx / len, fy / len, fz / len]; + const expectedAxis = EXPECTED_AXIS[face]!; + const dot = + forward[0] * expectedAxis[0] + forward[1] * expectedAxis[1] + forward[2] * expectedAxis[2]; + expect(dot).toBeCloseTo(1, 10); + } + }); + + it('returns null before bootstrap', () => { + expect( + skyCubemapFaceContext({ + state: makeState({ cam: null }), + eyeMpc: EYE_MPC, + face: 0, + faceSizePx: 256, + }), + ).toBeNull(); + expect( + skyCubemapFaceContext({ + state: makeState({ galaxyPointRenderer: null }), + eyeMpc: EYE_MPC, + face: 0, + faceSizePx: 256, + }), + ).toBeNull(); + expect( + skyCubemapFaceContext({ + state: makeState({ galaxyPickRenderer: null }), + eyeMpc: EYE_MPC, + face: 0, + faceSizePx: 256, + }), + ).toBeNull(); + }); + + it('carries the draw mask, not the pick mask, as visibleSourceMask', () => { + const state = makeState(); + const ctx = skyCubemapFaceContext({ state, eyeMpc: EYE_MPC, face: 0, faceSizePx: 256 }); + expect(ctx).not.toBeNull(); + if (ctx === null) return; + expect(ctx.visibleSourceMask).toBe(deriveSourceMasks(state).draw); + }); +}); diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index 7c1af39ec6..e8cfb44b6f 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -76,11 +76,11 @@ describe('createRenderTargets', () => { // Construction allocated the offscreen rows: hdr @ scale 1 (colour), // volume @ scale 3 (colour), zoa @ scale 5 (colour), star-aggregates @ // scale 2 (colour), mw-aggregate @ scale 2 (colour), foreground:0 @ - // scale 1 (colour + depth), and the five bloom-pyramid mips - // bloom0..bloom4 @ scale 2/4/8/16/32 (colour only) → 12 textures. hdr at - // full size, volume at floor(size/3), star-aggregates and mw-aggregate - // at floor(size/2). - expect(create.mock.calls).toHaveLength(12); + // scale 1 (colour + depth), the five bloom-pyramid mips bloom0..bloom4 @ + // scale 2/4/8/16/32 (colour only), and sky-cubemap @ fixedSizePx (colour) + // → 13 textures. hdr at full size, volume at floor(size/3), + // star-aggregates and mw-aggregate at floor(size/2). + expect(create.mock.calls).toHaveLength(13); const hdrDesc = create.mock.calls.find((c) => c[0].label === 'render-target-hdr')![0]; const volDesc = create.mock.calls.find((c) => c[0].label === 'render-target-volume')![0]; const aggDesc = create.mock.calls.find( @@ -98,8 +98,10 @@ describe('createRenderTargets', () => { const aggViewBefore = targets.viewOf('star-aggregates'); targets.reconcile(stateWithDivisor(MW_DIVISOR), { width: 1200, height: 900 }); - // Each offscreen row reallocated at the new size/scale → 12 more textures. - expect(create.mock.calls).toHaveLength(24); + // Each SCALE-driven offscreen row reallocated at the new canvas size → 12 + // more textures; sky-cubemap's fixedSizePx row holds its declared size + // and is not one of them. + expect(create.mock.calls).toHaveLength(25); const hdrResized = create.mock.calls .filter((c) => c[0].label === 'render-target-hdr') .at(-1)![0]; From 03ca898d6b650c01731fc740b1842d24766ef754 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:37:09 +0200 Subject: [PATCH 17/60] feat(lensing): Schwarzschild deflection LUT for the Sgr A* lensing pass CPU-side bending-angle table (task 9 of the render-black-hole plan): buildSchwarzschildDeflectionLut integrates (du/dphi)^2 = 1/b^2 - u^2 + u^3 via bisection for the turning point plus composite Simpson's rule under a theta = arcsin(u/u0) substitution that regularises the integrable sqrt singularity at the photon sphere. Sub-critical impact parameters (capture) sample as Infinity. Reference values in the test were hand-derived independently via mpmath high-precision quadrature under a different (algebraic r-space) substitution, cross-checked against scipy's adaptive quadrature, never re-derived from the module's own formula. Co-Authored-By: Claude Fable 5 --- .../lensing/SchwarzschildDeflectionLut.d.ts | 14 +++ .../buildSchwarzschildDeflectionLut.ts | 70 +++++++++++++++ .../buildSchwarzschildDeflectionLut.test.ts | 86 +++++++++++++++++++ 3 files changed, 170 insertions(+) create mode 100644 src/@types/lensing/SchwarzschildDeflectionLut.d.ts create mode 100644 src/utils/lensing/buildSchwarzschildDeflectionLut.ts create mode 100644 tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts diff --git a/src/@types/lensing/SchwarzschildDeflectionLut.d.ts b/src/@types/lensing/SchwarzschildDeflectionLut.d.ts new file mode 100644 index 0000000000..fd9cc72d2d --- /dev/null +++ b/src/@types/lensing/SchwarzschildDeflectionLut.d.ts @@ -0,0 +1,14 @@ +/** + * Output of `buildSchwarzschildDeflectionLut` — total light-bending angle + * as a function of impact parameter, for the Sgr A* lensing pass's O(1) + * per-pixel lookup. `samples[i]` is the angle for the impact parameter at + * grid index i, linearly spaced between `minImpactParamRs` and + * `maxImpactParamRs`. A ray with impact parameter at or below the photon + * sphere's critical value (3√3/2 · r_s) is captured; its sample is + * `Infinity`, the sentinel the consuming pass tests for. + */ +export type SchwarzschildDeflectionLut = { + readonly samples: Float32Array; // total bending angle, radians, indexed by impact parameter + readonly minImpactParamRs: number; // in units of r_s + readonly maxImpactParamRs: number; +}; diff --git a/src/utils/lensing/buildSchwarzschildDeflectionLut.ts b/src/utils/lensing/buildSchwarzschildDeflectionLut.ts new file mode 100644 index 0000000000..25b9521741 --- /dev/null +++ b/src/utils/lensing/buildSchwarzschildDeflectionLut.ts @@ -0,0 +1,70 @@ +/** + * CPU-side Schwarzschild bending-angle LUT (units r_s = 1, so b is "in r_s"). + * Photon orbits obey (du/dphi)^2 = f(u) = 1/b^2 - u^2 + u^3, u = 1/r; the + * turning point u0 (root of f in [0, 2/3], the photon-sphere bound) is found + * by bisection. The bending integral has an integrable sqrt singularity at + * u0; substituting u = u0*sin(theta) regularises it (cos(theta) and sqrt(f) + * both vanish linearly as theta -> pi/2), so Simpson's rule over theta + * converges normally. See the test file for the theta=pi/2 endpoint limit + * and an independent cross-check of the resulting values. + */ + +import type { SchwarzschildDeflectionLut } from '../../@types/lensing/SchwarzschildDeflectionLut'; + +const CRITICAL_IMPACT_PARAM_RS = (3 * Math.sqrt(3)) / 2; // b_c = 3root3/2 r_s, photon-sphere impact parameter +const MIN_IMPACT_PARAM_RS = 1; // below b_c throughout: exercises the capture sentinel +const MAX_IMPACT_PARAM_RS = 50; // deep weak-field: 2/b ~ 0.04 rad, matches the asymptotic formula closely +const PHOTON_SPHERE_U = 2 / 3; // u = 1/r at r = 1.5 r_s, the upper bound for the turning-point search +const BISECTION_ITERATIONS = 80; // well past double precision (2^-80 interval width) +const QUADRATURE_INTERVALS = 400; // even, composite Simpson's rule sub-intervals over theta + +function turningPointU(invBSq: number): number { + let lo = 0; + let hi = PHOTON_SPHERE_U; + for (let i = 0; i < BISECTION_ITERATIONS; i++) { + const mid = (lo + hi) / 2; + const g = mid * mid * mid - mid * mid + invBSq; + if (g > 0) { + lo = mid; + } else { + hi = mid; + } + } + return (lo + hi) / 2; +} + +function bendingAngleRadians(impactParamRs: number): number { + if (impactParamRs <= CRITICAL_IMPACT_PARAM_RS) { + return Infinity; // no turning point outside the photon sphere: captured + } + + const invBSq = 1 / (impactParamRs * impactParamRs); + const u0 = turningPointU(invBSq); + const endpointValue = Math.sqrt(2 / (2 - 3 * u0)); // theta -> pi/2 limit, derived in the test file + + const sampleAt = (theta: number): number => { + const u = u0 * Math.sin(theta); + const f = Math.max(0, u * u * u - u * u + invBSq); // clamp: rounding can dip f just below 0 at theta near pi/2 + return (u0 * Math.cos(theta)) / Math.sqrt(f); + }; + + const step = Math.PI / 2 / QUADRATURE_INTERVALS; + let simpsonSum = sampleAt(0) + endpointValue; + for (let i = 1; i < QUADRATURE_INTERVALS; i++) { + simpsonSum += (i % 2 === 0 ? 2 : 4) * sampleAt(i * step); + } + const halfDeflection = (step / 3) * simpsonSum; + return 2 * halfDeflection - Math.PI; +} + +export function buildSchwarzschildDeflectionLut(sampleCount: number): SchwarzschildDeflectionLut { + const minImpactParamRs = MIN_IMPACT_PARAM_RS; + const maxImpactParamRs = MAX_IMPACT_PARAM_RS; + const samples = new Float32Array(sampleCount); + for (let i = 0; i < sampleCount; i++) { + const t = sampleCount > 1 ? i / (sampleCount - 1) : 0; + const impactParamRs = minImpactParamRs + t * (maxImpactParamRs - minImpactParamRs); + samples[i] = bendingAngleRadians(impactParamRs); + } + return { samples, minImpactParamRs, maxImpactParamRs }; +} diff --git a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts new file mode 100644 index 0000000000..e38d8e40a2 --- /dev/null +++ b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts @@ -0,0 +1,86 @@ +import { describe, it, expect } from 'vitest'; +import { buildSchwarzschildDeflectionLut } from '../../../src/utils/lensing/buildSchwarzschildDeflectionLut'; +import type { SchwarzschildDeflectionLut } from '../../../src/@types/lensing/SchwarzschildDeflectionLut'; + +// Critical impact parameter (photon sphere), b_c = 3*sqrt(3)/2 r_s ≈ 2.598076 — +// a textbook constant, not derived from the module under test. +const CRITICAL_IMPACT_PARAM_RS = (3 * Math.sqrt(3)) / 2; + +// Linear interpolation over the LUT's own reported [min, max] range — used +// only far from the photon sphere, where neighbouring grid samples can't +// straddle the finite/captured (Infinity) boundary. +function sampleAt(lut: SchwarzschildDeflectionLut, impactParamRs: number): number { + const t = (impactParamRs - lut.minImpactParamRs) / (lut.maxImpactParamRs - lut.minImpactParamRs); + const gridPos = t * (lut.samples.length - 1); + const i0 = Math.floor(gridPos); + const i1 = Math.min(i0 + 1, lut.samples.length - 1); + const frac = gridPos - i0; + return lut.samples[i0]! * (1 - frac) + lut.samples[i1]! * frac; +} + +describe('buildSchwarzschildDeflectionLut', () => { + it('straddles the photon sphere and reaches a weak-field-accurate impact parameter', () => { + const lut = buildSchwarzschildDeflectionLut(4096); + expect(lut.minImpactParamRs).toBeLessThan(CRITICAL_IMPACT_PARAM_RS); + expect(lut.maxImpactParamRs).toBeGreaterThan(20); + }); + + it('matches the weak-field asymptotic formula alpha = 2*r_s/b at a large impact parameter', () => { + // alpha ~= 4GM/(c^2 b) = 2 r_s/b (r_s units, r_s = 1) is the leading PPN + // term; the next order is O(r_s/b) *relative* to that leading term, so at + // b = 30 r_s a few-percent deviation is expected, not exact agreement. + const lut = buildSchwarzschildDeflectionLut(4096); + const b = 30; + const weakFieldFormula = 2 / b; + expect(Math.abs(sampleAt(lut, b) - weakFieldFormula)).toBeLessThan(0.01); + }); + + it('matches an independently computed weak-field reference to high precision', () => { + // Independent reference for b = 30 r_s: mpmath (40-digit arbitrary + // precision) integrating alpha = 2*int_{r0}^inf dr/(r^2 sqrt(F(r))) - pi, + // F(r) = 1/b^2 - 1/r^2 + 1/r^3, r0 = F's root above the photon sphere + // (r = 1.5 r_s), via the substitution r = r0 + s^2 (s in [0, inf)) — + // an algebraic regularisation in r-space, distinct from this module's + // theta = arcsin(u/u0) trig substitution in u = 1/r space. Cross-checked + // against scipy.integrate.quad (double precision, adaptive Gauss-Kronrod) + // to ~1e-13 relative agreement before being taken as ground truth here. + const lut = buildSchwarzschildDeflectionLut(4096); + const reference = 0.0701508083168968; + expect(Math.abs(sampleAt(lut, 30) - reference)).toBeLessThan(1e-4); + }); + + it('matches an independently computed moderately-strong-field reference', () => { + // Same independent method as above, evaluated at b = 3.0 r_s (~15% above + // the critical impact parameter — moderately strong field, well clear of + // the photon-sphere divergence): reference alpha = 1.71938831023017 rad. + const lut = buildSchwarzschildDeflectionLut(4096); + const reference = 1.71938831023017; + expect(Math.abs(sampleAt(lut, 3.0) - reference)).toBeLessThan(1e-3); + }); + + it('grows large approaching the photon sphere from above, and is Infinity (captured) at or below it', () => { + const lut = buildSchwarzschildDeflectionLut(4096); + const firstFiniteIndex = lut.samples.findIndex((v) => Number.isFinite(v)); + expect(firstFiniteIndex).toBeGreaterThan(0); // some captured region exists below it + // The finite sample closest to the photon sphere should already be well + // beyond the weak-field regime (~0.07 rad at b = 30 r_s checked above). + expect(lut.samples[firstFiniteIndex]).toBeGreaterThan(3); + + const belowCriticalIndex = Math.round( + ((2 - lut.minImpactParamRs) / (lut.maxImpactParamRs - lut.minImpactParamRs)) * (lut.samples.length - 1), + ); + expect(lut.samples[belowCriticalIndex]).toBe(Infinity); + }); + + it('strictly decreases across the escaping (finite) branch as impact parameter grows', () => { + // The sign/ordering check the two point-value tests above could miss: + // a formula with e.g. a flipped sign would still hit isolated literals + // by coincidence far more easily than it would preserve a monotonic + // trend across the whole finite range. + const lut = buildSchwarzschildDeflectionLut(4096); + const firstFiniteIndex = lut.samples.findIndex((v) => Number.isFinite(v)); + for (let i = firstFiniteIndex; i < lut.samples.length - 1; i++) { + expect(lut.samples[i]!).toBeGreaterThan(lut.samples[i + 1]!); + } + }); +}); From ab85df30e0b783dbd810fb7645f7497917456a35 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:42:14 +0200 Subject: [PATCH 18/60] fix(gpu): add WESL-parsing parity leg for SgrAStarLensingUniforms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding (fix round 1) on 0423762fa: the existing parity test only re-asserted the packer's own documented offsets against itself, never reading sgrAStarLensing.wesl — a field reorder there would sail through undetected. Adds sgrAStarLensingUniformsLayout.parity.test.ts, following the atmosphereUniformsLayout.parity.test.ts / nodeParamsLayout.test.ts precedent: parse the struct out of the .wesl file, derive its std140 offsets, then drive the real packer with a sentinel per field and assert each sentinel lands where the STRUCT says it should. Verified it catches a reorder by transiently swapping two fields in the .wesl and confirming the new test fails, then reverting. Kept the existing packSgrAStarLensingUniforms.test.ts (hardcoded offset table) as a second, independent leg — the same two-file split packAtmosphereUniforms.test.ts / atmosphereUniformsLayout.parity.test.ts already establishes in this directory, not redundant with the new WESL-driven check. Co-Authored-By: Claude Fable 5 --- ...rAStarLensingUniformsLayout.parity.test.ts | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts new file mode 100644 index 0000000000..07156428e5 --- /dev/null +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -0,0 +1,164 @@ +/** + * SgrAStarLensingUniforms WESL<->packer parity — nothing previously read the + * WGSL struct itself, so a field reorder in `sgrAStarLensing.wesl` (a field + * inserted ahead of `anchorPosRelCamM`, say) would drift silently past + * `packSgrAStarLensingUniforms.test.ts` (which only re-asserts the packer's + * own documented offsets against itself) and hand the GPU a shifted struct. + * This parses `struct SgrAStarLensingUniforms` out of the .wesl file, derives + * its std140 float offsets, then drives the REAL packer with a distinct + * sentinel per field and asserts each sentinel lands where the struct — not + * the packer — says it should. Follows the `atmosphereUniformsLayout.parity + * .test.ts` / `nodeParamsLayout.test.ts` precedent for locating/parsing the + * struct and computing WGSL alignment; the embedded `cam: CameraUniforms` + * prefix is treated as an opaque 80-byte block (its own byte-for-byte parity + * lives in `cameraUniforms.test.ts` and this file's sibling + * `packSgrAStarLensingUniforms.test.ts`, which both cover its content). + */ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, resolve } from 'node:path'; +import { + packSgrAStarLensingUniforms, + SGR_A_STAR_LENSING_UNIFORM_FLOATS, +} from '../../../src/utils/gpu/packSgrAStarLensingUniforms'; +import type { Vec2 } from '../../../src/@types/math/Vec2'; +import type { Vec3 } from '../../../src/@types/math/Vec3'; + +const here = dirname(fileURLToPath(import.meta.url)); +const repoRoot = resolve(here, '../../..'); +const weslPath = resolve(repoRoot, 'src/services/gpu/shaders/lib/sgrAStarLensing.wesl'); + +/** std140 alignment + size for the types SgrAStarLensingUniforms uses. + * `lanes: 0` marks the embedded `CameraUniforms` prefix — its block offset + * still comes from this table (it advances the cursor 80 bytes), but its + * content is not asserted here; see the module header for why. */ +const WESL_TYPES: Record = { + f32: { align: 4, size: 4, lanes: 1 }, + 'vec3': { align: 16, size: 12, lanes: 3 }, + CameraUniforms: { align: 16, size: 80, lanes: 0 }, +}; + +function roundUp(value: number, align: number): number { + return Math.ceil(value / align) * align; +} + +function structFields(source: string, name: string): Array<{ name: string; type: string }> { + const body = source.match(new RegExp(`struct\\s+${name}\\s*\\{([^}]*)\\}`))?.[1]; + if (!body) throw new Error(`struct ${name} not found in sgrAStarLensing.wesl`); + return body + .split(',') + .map((line) => line.replace(/\/\/.*$/gm, '').trim()) + .filter((line) => line.length > 0) + .map((line) => { + const [fieldName, type] = line.split(':').map((part) => part.trim()); + if (!fieldName || !type) throw new Error(`unparsable SgrAStarLensingUniforms field: '${line}'`); + return { name: fieldName, type }; + }); +} + +type FieldLayout = { name: string; floatOffset: number; lanes: number }; + +/** Std140 layout, in declaration order, converted to float indices (every + * member here is 4-byte aligned, so bytes/4 is exact). */ +function structLayout(fields: Array<{ name: string; type: string }>): { + layout: FieldLayout[]; + totalFloats: number; +} { + const layout: FieldLayout[] = []; + let cursor = 0; + let maxAlign = 4; + for (const { name, type } of fields) { + const spec = WESL_TYPES[type]; + if (!spec) throw new Error(`unhandled WESL type '${type}' on field ${name}`); + const offset = roundUp(cursor, spec.align); + layout.push({ name, floatOffset: offset / 4, lanes: spec.lanes }); + cursor = offset + spec.size; + maxAlign = Math.max(maxAlign, spec.align); + } + return { layout, totalFloats: roundUp(cursor, maxAlign) / 4 }; +} + +describe('SgrAStarLensingUniforms WESL/packer parity', () => { + const wesl = readFileSync(weslPath, 'utf8'); + const { layout, totalFloats } = structLayout(structFields(wesl, 'SgrAStarLensingUniforms')); + + it('struct float count matches SGR_A_STAR_LENSING_UNIFORM_FLOATS', () => { + expect(totalFloats).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); + }); + + it('the real packer writes each field at the offset the struct declares', () => { + // One non-overlapping sentinel per field, so a swap between any two + // fields — or a packer that missed a WESL reorder — lands a recognisable + // value at the WRONG offset instead of matching by luck. The cam prefix's + // own inputs are unchecked here (see module header), so any distinct + // values will do. + const viewProj = Float32Array.from({ length: 16 }, (_, i) => i + 1); // 1..16 + const viewportPx: Vec2 = [17, 18]; + const schwarzschildRadiusM = 501; + const innerRs = 502; + const outerRs = 503; + const inclinationRad = 504; + const positionAngleRad = 505; + const flickerAmp = 506; + const flickerTimescaleS = 507; + const flickerPhase = 508; + const lutMinImpactParamRs = 509; + const lutMaxImpactParamRs = 510; + const lutSampleCount = 511; + const bandAlpha = 512; + const anchorPosRelCamM: Vec3 = [601, 602, 603]; + + const rec = packSgrAStarLensingUniforms( + viewProj, + viewportPx, + schwarzschildRadiusM, + innerRs, + outerRs, + inclinationRad, + positionAngleRad, + flickerAmp, + flickerTimescaleS, + flickerPhase, + lutMinImpactParamRs, + lutMaxImpactParamRs, + lutSampleCount, + bandAlpha, + anchorPosRelCamM, + ); + + const vectorByField: Record = { anchorPosRelCamM }; + const scalarByField: Record = { + schwarzschildRadiusM, + innerRs, + outerRs, + inclinationRad, + positionAngleRad, + flickerAmp, + flickerTimescaleS, + flickerPhase, + lutMinImpactParamRs, + lutMaxImpactParamRs, + lutSampleCount, + bandAlpha, + }; + const zeroPadFields = new Set(['_pad2']); + + for (const field of layout) { + if (field.lanes === 0) { + // The opaque cam: CameraUniforms prefix — content unchecked here. + continue; + } else if (field.lanes === 3) { + const vec = vectorByField[field.name]; + if (!vec) throw new Error(`no sentinel vector for field '${field.name}'`); + for (let lane = 0; lane < 3; lane++) expect(rec[field.floatOffset + lane]).toBe(vec[lane]); + } else if (zeroPadFields.has(field.name)) { + expect(rec[field.floatOffset]).toBe(0); + } else { + const value = scalarByField[field.name]; + if (value === undefined) throw new Error(`no sentinel for field '${field.name}'`); + expect(rec[field.floatOffset]).toBe(value); + } + } + }); +}); From 8f1cfa9d7e00122db24f5582d524d4c508abf923 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:46:46 +0200 Subject: [PATCH 19/60] =?UTF-8?q?fix(lensing):=20review=20round=201=20?= =?UTF-8?q?=E2=80=94=20fix=20dangling=20comment=20pointer,=20trim=20d.ts?= =?UTF-8?q?=20header,=20format?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - buildSchwarzschildDeflectionLut.ts: the module header and endpointValue comment both claimed the theta->pi/2 endpoint-limit derivation lived in the test file; it didn't. Point to the definition site instead and state the (Taylor-expansion) derivation inline in one comment there. - SchwarzschildDeflectionLut.d.ts: trim the header to the load-bearing core — units, grid-indexing convention, capture sentinel. - buildSchwarzschildDeflectionLut.test.ts: npx prettier --write (one line over print width). Co-Authored-By: Claude Fable 5 --- src/@types/lensing/SchwarzschildDeflectionLut.d.ts | 11 ++++------- src/utils/lensing/buildSchwarzschildDeflectionLut.ts | 10 ++++++---- .../lensing/buildSchwarzschildDeflectionLut.test.ts | 3 ++- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/@types/lensing/SchwarzschildDeflectionLut.d.ts b/src/@types/lensing/SchwarzschildDeflectionLut.d.ts index fd9cc72d2d..4c70d90c82 100644 --- a/src/@types/lensing/SchwarzschildDeflectionLut.d.ts +++ b/src/@types/lensing/SchwarzschildDeflectionLut.d.ts @@ -1,11 +1,8 @@ /** - * Output of `buildSchwarzschildDeflectionLut` — total light-bending angle - * as a function of impact parameter, for the Sgr A* lensing pass's O(1) - * per-pixel lookup. `samples[i]` is the angle for the impact parameter at - * grid index i, linearly spaced between `minImpactParamRs` and - * `maxImpactParamRs`. A ray with impact parameter at or below the photon - * sphere's critical value (3√3/2 · r_s) is captured; its sample is - * `Infinity`, the sentinel the consuming pass tests for. + * Schwarzschild bending angle by impact parameter (units r_s): `samples[i]` + * is the angle at the grid point linearly spaced between `minImpactParamRs` + * and `maxImpactParamRs`. At or below the critical impact parameter (photon + * sphere), the ray is captured — sample is `Infinity`. */ export type SchwarzschildDeflectionLut = { readonly samples: Float32Array; // total bending angle, radians, indexed by impact parameter diff --git a/src/utils/lensing/buildSchwarzschildDeflectionLut.ts b/src/utils/lensing/buildSchwarzschildDeflectionLut.ts index 25b9521741..68ae5bb184 100644 --- a/src/utils/lensing/buildSchwarzschildDeflectionLut.ts +++ b/src/utils/lensing/buildSchwarzschildDeflectionLut.ts @@ -4,9 +4,9 @@ * turning point u0 (root of f in [0, 2/3], the photon-sphere bound) is found * by bisection. The bending integral has an integrable sqrt singularity at * u0; substituting u = u0*sin(theta) regularises it (cos(theta) and sqrt(f) - * both vanish linearly as theta -> pi/2), so Simpson's rule over theta - * converges normally. See the test file for the theta=pi/2 endpoint limit - * and an independent cross-check of the resulting values. + * both vanish linearly as theta -> pi/2, see endpointValue below), so + * Simpson's rule over theta converges normally. See the test file for an + * independent cross-check of the resulting values. */ import type { SchwarzschildDeflectionLut } from '../../@types/lensing/SchwarzschildDeflectionLut'; @@ -40,7 +40,9 @@ function bendingAngleRadians(impactParamRs: number): number { const invBSq = 1 / (impactParamRs * impactParamRs); const u0 = turningPointU(invBSq); - const endpointValue = Math.sqrt(2 / (2 - 3 * u0)); // theta -> pi/2 limit, derived in the test file + // theta -> pi/2 limit: f(u0 sin(theta)) ~ u0^2(2-3u0)/2 * (pi/2-theta)^2 and + // cos(theta) ~ (pi/2-theta) there, so sampleAt's ratio tends to this finite value. + const endpointValue = Math.sqrt(2 / (2 - 3 * u0)); const sampleAt = (theta: number): number => { const u = u0 * Math.sin(theta); diff --git a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts index e38d8e40a2..2b81149c69 100644 --- a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts +++ b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts @@ -67,7 +67,8 @@ describe('buildSchwarzschildDeflectionLut', () => { expect(lut.samples[firstFiniteIndex]).toBeGreaterThan(3); const belowCriticalIndex = Math.round( - ((2 - lut.minImpactParamRs) / (lut.maxImpactParamRs - lut.minImpactParamRs)) * (lut.samples.length - 1), + ((2 - lut.minImpactParamRs) / (lut.maxImpactParamRs - lut.minImpactParamRs)) * + (lut.samples.length - 1), ); expect(lut.samples[belowCriticalIndex]).toBe(Infinity); }); From 45912e20adf9c23e7b2717600b84c9eedd925b89 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:46:48 +0200 Subject: [PATCH 20/60] fix(engine): sky-cubemap capture gets its own near plane, not the cosmo camera's MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit skyCubemapFaceContext reused the live projection's near (0.01 Mpc / 10 kpc), but the capture's own content — S-stars and the field around Sgr A* — sits at hundreds of AU, seven orders of magnitude inside that plane, clipping it all invisible. SKY_CAPTURE_NEAR_MPC (0.1 AU) is sized for the capture scene instead; far still rides the live projection so distant stars/galaxies survive. depth: null on the sky-cubemap row means this costs nothing but clipping range. Co-Authored-By: Claude Fable 5 --- .../engine/frame/skyCubemapFaceContext.ts | 20 +++++++++++++++---- .../frame/skyCubemapFaceContext.test.ts | 14 +++++++++++++ 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts index 0a5d658e07..eed285935a 100644 --- a/src/services/engine/frame/skyCubemapFaceContext.ts +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -18,6 +18,18 @@ import { deriveFrameContext } from './frameContext'; import { deriveSourceMasks } from './deriveSourceMasks'; import { mat3FromColumns } from '../../../utils/math/mat3FromColumns'; import { cross3 } from '../../../utils/math/cross3'; +import { SCALE_UNITS } from '../../../data/scaleUnits'; + +/** + * The synthetic frustum's near plane, NOT the live cosmo camera's (`0.01 + * Mpc` / 10 kpc, sized for the whole scene). The capture's actual content — + * S-stars and the field around Sgr A* — sits at hundreds of AU, seven orders + * of magnitude inside that near plane; reusing it would clip every S-star + * invisible. `sky-cubemap` is depthless (`depth: null`), so near/far affect + * only clipping, never depth precision — free to pick a value sized for the + * capture scene instead of the main camera's. + */ +const SKY_CAPTURE_NEAR_MPC = 0.1 * SCALE_UNITS.AU_TO_MPC; /** * Forward axis per `CubeFace` (index order ±X/±Y/±Z, see `CubeFace.d.ts`). @@ -79,13 +91,13 @@ export function skyCubemapFaceContext(input: { // real canvas for an offscreen capture, so a size-shaped stub stands in. { width: faceSizePx, height: faceSizePx } as unknown as HTMLCanvasElement, pose, - // 90° symmetric frustum sized for a cube face; near/far ride the live - // engine projection so the capture clips at the same distances the main - // camera does. + // 90° symmetric frustum sized for a cube face. near = SKY_CAPTURE_NEAR_MPC + // (see its docblock); far rides the live engine projection so distant + // stars/galaxies at cosmological range still survive the capture. { fovYRad: Math.PI / 2, aspect: 1, - near: state.cameraRuntime.projection.near, + near: SKY_CAPTURE_NEAR_MPC, far: state.cameraRuntime.projection.far, }, basis, diff --git a/tests/services/engine/frame/skyCubemapFaceContext.test.ts b/tests/services/engine/frame/skyCubemapFaceContext.test.ts index 9533b1c467..b6c9d94fc1 100644 --- a/tests/services/engine/frame/skyCubemapFaceContext.test.ts +++ b/tests/services/engine/frame/skyCubemapFaceContext.test.ts @@ -13,6 +13,7 @@ import { skyCubemapFaceContext } from '../../../../src/services/engine/frame/sky import { deriveSourceMasks } from '../../../../src/services/engine/frame/deriveSourceMasks'; import { GALAXY_CATALOG_SOURCES } from '../../../../src/data/sources'; import { galaxyCatalogIdOf } from '../../../../src/utils/galaxyCatalogIdOf'; +import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import type { EngineState } from '../../../../src/@types/engine/state/EngineState'; import type { OrbitCamera } from '../../../../src/@types/camera/OrbitCamera'; import type { CameraPose } from '../../../../src/@types/camera/CameraPose'; @@ -167,4 +168,17 @@ describe('skyCubemapFaceContext', () => { if (ctx === null) return; expect(ctx.visibleSourceMask).toBe(deriveSourceMasks(state).draw); }); + + it("clips well below the S-star scale, not the live cosmo camera's 10-kpc near plane", () => { + // The capture's actual content (S-stars, the field around Sgr A*) sits + // at hundreds of AU — reusing the live projection's near (0.01 Mpc / + // 10 kpc, PROJECTION above) would clip it all invisible. This is the + // regression the fix addresses; see skyCubemapFaceContext's + // SKY_CAPTURE_NEAR_MPC docblock. + const state = makeState(); + const ctx = skyCubemapFaceContext({ state, eyeMpc: EYE_MPC, face: 0, faceSizePx: 256 }); + expect(ctx).not.toBeNull(); + if (ctx === null) return; + expect(ctx.cam.near).toBeLessThan(100 * SCALE_UNITS.AU_TO_MPC); + }); }); From 84f47c7810206dcb72205725a3c432aee08b0645 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 13:58:08 +0200 Subject: [PATCH 21/60] feat(engine): Sgr A* far-field glint rides bodyGlintsLayer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Widens bodyGlintsLayer with a second, independent packed source for SCENE_ANCHOR_POINT_BODIES: a fixed warm-orange marker that crossfades out as the black-hole lens pass engages on close approach to Sgr A* (1 - fadeBand(sgrAStarLensing, distMpc)). An anchor never resolves to a mesh, so it rides its own brightness formula outside sceneBodyPartition's glint/mesh XOR, with no apparent-size or solar-system-backdrop fade — the marker is meant to read from anywhere, not just near the Sun. enabled's widening mirrors pickEnabled's existing Earth-caption pattern: checked before (not after) the solar-system backdrop gate, since the anchor's own visibility criterion is independent of it. Co-Authored-By: Claude Fable 5 --- .../engine/frame/passes/bodyGlintsLayer.ts | 82 ++++++++- .../frame/passes/bodyGlintsLayer.test.ts | 157 +++++++++++++++--- 2 files changed, 212 insertions(+), 27 deletions(-) diff --git a/src/services/engine/frame/passes/bodyGlintsLayer.ts b/src/services/engine/frame/passes/bodyGlintsLayer.ts index 68c05362a6..fbe2e1f189 100644 --- a/src/services/engine/frame/passes/bodyGlintsLayer.ts +++ b/src/services/engine/frame/passes/bodyGlintsLayer.ts @@ -2,7 +2,7 @@ * bodyGlintsLayer — the `glints` branch of the per-frame body partition as * brightness-scaled additive point sprites in the depthless HDR accumulation. * - * ### What it draws — the sub-pixel bodies + * ### What it draws — the sub-pixel bodies, plus Sgr A*'s far-field marker * * The `glints` branch of `sceneBodyPartition` — every seeded body whose apparent * diameter stays below `BODY_GLINT_MAX_PX`. Its siblings `planetsLayer` / @@ -11,6 +11,13 @@ * where sub-pixel bodies simply vanished (the mesh culled them and nothing drew * the glint) is closed here. * + * A SECOND, independent source rides the same buffer: `SCENE_ANCHOR_POINT_BODIES` + * (today, only Sgr A*). An anchor never resolves to a mesh, so the partition's + * XOR doesn't apply to it — it gets its own fixed tint/intensity, crossfading + * OUT as the black-hole lens pass engages on close approach, with none of the + * seeded glints' apparent-size or solar-system-backdrop fades (it is meant to + * read from anywhere, not just near the Sun). + * * ### Brightness = apparent size x albedo x phase, then the cross-fade * * Each glint's stored `brightness` is `bodyGlintBrightness` (apparent size x @@ -66,11 +73,13 @@ import type { ContentLayer } from '../../../../@types/engine/frame/ContentLayer' import type { EngineState } from '../../../../@types/engine/state/EngineState'; import type { ReadyFrameContext } from '../../../../@types/engine/frame/ReadyFrameContext'; import type { Vec3 } from '../../../../@types/math/Vec3'; +import type { BodyState } from '../../../../@types/scene/BodyState'; import type { BodyGlintPick } from '../../../../@types/rendering/BodyPickRenderer'; import { NEAR0 } from '../slabs'; import { RENDER_ORIGIN_MPC } from '../../../../data/renderOrigin'; import { Source } from '../../../../data/sources'; import { SCENE_PLANETS } from '../../../../data/bodies/scenePlanets'; +import { SCENE_ANCHOR_POINT_BODIES } from '../../../../data/bodies/sceneAnchorPointBodies'; import { packSelection, PICK_SENTINEL_OFFSET } from '../../../../data/selectionEncoding'; import { sceneBodyPartition } from '../sceneBodyPartition'; import { sceneBodyStates } from '../sceneBodyStates'; @@ -106,6 +115,18 @@ const GLINT_MIN_BRIGHTNESS = 1e-4; // stays attached to the content it dissolves rather than to the render origin. const GLINT_BACKDROP_REGION = regionById('solar-system'); +// Sgr A*'s far-field glint keys on distance from ITS OWN region — independent +// of `GLINT_BACKDROP_REGION`, which the anchor's marker does not dissolve +// against (see the module header). +const GALACTIC_CENTRE_REGION = regionById('galactic-centre'); + +// A fixed warm-orange marker, not a photometric measurement — an anchor +// carries no albedo (`AnchorPointBody`'s header) to derive one from. Tuned to +// read clearly against the additive HDR field it shares with the seeded-body +// glints. +const SGR_A_STAR_GLINT_TINT: Vec3 = [1, 0.55, 0.2]; +const SGR_A_STAR_GLINT_BASE_INTENSITY = 0.8; + /** * The one fact "the Earth caption invites a click": the seeded Earth exists AND * the camera is within the solar-system caption range. `pickEnabled` (admit this @@ -119,6 +140,23 @@ function earthCaptionPickable(state: EngineState, ctx: ReadyFrameContext): boole return state.data.bodies.earth !== null && ctx.cam.distance < SOLAR_SYSTEM_LABEL_MAX_DISTANCE_MPC; } +/** + * Sgr A*'s far-field glint alpha: the fixed base intensity crossfaded OUT as + * the black-hole lens pass engages on close approach (spec §"The fade band"). + * `enabled`'s widening and `draw`'s pack loop both call this — the same + * "the gate and the emit cannot disagree" contract `GLINT_BACKDROP_REGION`'s + * check already keeps for the seeded glints (see the module header). + */ +function sgrAStarGlintBrightness( + camPosMpc: Readonly, + states: ReadonlyMap, +): number { + const distMpc = regionRelativeDistanceMpc(camPosMpc, GALACTIC_CENTRE_REGION, states); + return ( + SGR_A_STAR_GLINT_BASE_INTENSITY * (1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc)) + ); +} + export const bodyGlintsLayer: ContentLayer = { name: 'body-glints', slab: NEAR0, @@ -127,10 +165,20 @@ export const bodyGlintsLayer: ContentLayer = { enabled(state, ctx, _view) { // Handle first (short-circuits before any ctx / state.data read — matches - // starPointsLayer), shared distance gate second, far-dissolve band third, - // partition last. + // starPointsLayer), shared distance gate second, the anchor widening + // third, far-dissolve band fourth, partition last. if (state.gpu.bodyGlintRenderer === null) return false; if (ctx.cam.distance >= FOREGROUND_MAX_DISTANCE_MPC) return false; + const states = sceneBodyStates(state, ctx); + // Sgr A*'s far-field glint is unconditional on the solar-system backdrop + // (SCENE_ANCHOR_POINT_BODIES never resolves to a mesh, so the near/far + // dissolves built for the seeded planets don't apply — module header), so + // it is checked BEFORE that gate: an empty `glints` partition, or a camera + // the backdrop has already dissolved, must not drop the row while the + // anchor's own crossfade is still positive. Mirrors `pickEnabled`'s + // Earth-caption widening, which bypasses the same gate for the same + // reason (the caption's own visibility criterion is independent of it). + if (sgrAStarGlintBrightness(ctx.drawCamPos, states) > GLINT_MIN_BRIGHTNESS) return true; // Once the far-dissolve band has zeroed the glint backdrop, DISABLE the layer // rather than pack invisible points — the "opacity 0 ⇒ no render" house rule, // mirroring `starPointsLayer`'s `starBackdrop` gate (which also empties the @@ -141,11 +189,7 @@ export const bodyGlintsLayer: ContentLayer = { // `bodyGlintBackdrop` completes deep inside `FOREGROUND_MAX_DISTANCE_MPC`, so // this is the binding — and smooth — gate for the glints; without it they draw // at full additive brightness all the way to the coarse gate. - const regionDistMpc = regionRelativeDistanceMpc( - ctx.drawCamPos, - GLINT_BACKDROP_REGION, - sceneBodyStates(state, ctx), - ); + const regionDistMpc = regionRelativeDistanceMpc(ctx.drawCamPos, GLINT_BACKDROP_REGION, states); if (fadeBand(SCALE_FADE_BANDS.bodyGlintBackdrop, regionDistMpc) <= 0) return false; return sceneBodyPartition(state, ctx).glints.length > 0; }, @@ -232,6 +276,28 @@ export const bodyGlintsLayer: ContentLayer = { staging[base + 6] = brightness; count++; } + + // A second, independent packed source, appended to the SAME buffer/count: + // Sgr A*'s far-field glint. SCENE_ANCHOR_POINT_BODIES never resolves to a + // mesh, so it isn't part of `glints` and carries none of the seeded + // bodies' apparent-size or backdrop terms — see the module header and + // `sgrAStarGlintBrightness`. + for (const anchor of SCENE_ANCHOR_POINT_BODIES) { + if (count >= MAX_GLINTS) break; + const brightness = sgrAStarGlintBrightness(camPos, states); + if (brightness <= GLINT_MIN_BRIGHTNESS) continue; + + const anchorPositionMpc = states.get(anchor.id)!.positionMpc; + const base = count * INSTANCE_FLOATS; + staging[base + 0] = anchorPositionMpc[0] - camPos[0]; + staging[base + 1] = anchorPositionMpc[1] - camPos[1]; + staging[base + 2] = anchorPositionMpc[2] - camPos[2]; + staging[base + 3] = SGR_A_STAR_GLINT_TINT[0]; + staging[base + 4] = SGR_A_STAR_GLINT_TINT[1]; + staging[base + 5] = SGR_A_STAR_GLINT_TINT[2]; + staging[base + 6] = brightness; + count++; + } if (count === 0) return; // Fold the eye offset into the vp so it pairs with the camera-relative diff --git a/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts b/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts index dc72bf27f5..ee747cfd66 100644 --- a/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts +++ b/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts @@ -21,6 +21,7 @@ import { describe, it, expect, vi } from 'vitest'; import { bodyGlintsLayer } from '../../../../../src/services/engine/frame/passes/bodyGlintsLayer'; +import { sceneBodyStates } from '../../../../../src/services/engine/frame/sceneBodyStates'; import { INSTANCE_FLOATS } from '../../../../../src/services/gpu/renderers/bodies/bodyGlintRenderer'; import { FOREGROUND_MAX_DISTANCE_MPC } from '../../../../../src/services/engine/frame/foregroundMaxDistance'; import { SOLAR_SYSTEM_LABEL_MAX_DISTANCE_MPC } from '../../../../../src/services/engine/frame/solarSystemLabelMaxDistance'; @@ -30,6 +31,7 @@ import { rebaseViewProj } from '../../../../../src/utils/camera/rebaseViewProj'; import { narrowMat4 } from '../../../../../src/utils/math/narrowMat4'; import { Source } from '../../../../../src/data/sources'; import { SCENE_PLANETS } from '../../../../../src/data/bodies/scenePlanets'; +import { SGR_A_STAR_ANCHOR } from '../../../../../src/data/bodies/sceneSgrAStar'; import { packSelection, PICK_SENTINEL_OFFSET } from '../../../../../src/data/selectionEncoding'; import { SCALE_UNITS } from '../../../../../src/data/scaleUnits'; import { makeSlab } from '../../../../fixtures/makeSlab'; @@ -60,6 +62,15 @@ vi.mock('../../../../../src/services/engine/frame/sceneBodyStates', () => ({ orientation: [1, 0, 0, 0, 1, 0, 0, 0, 1] as BodyState['orientation'], meanAnomalyRad: 0, }); + // The 'galactic-centre' region's anchor — Sgr A*'s real position. Every + // `draw` call now packs the far-field glint unconditionally (task 8), so an + // absent entry here wouldn't just read Infinity, it would crash on + // `.positionMpc` of undefined the moment that glint tries to pack. + m.set(SGR_A_STAR_ANCHOR.id, { + positionMpc: SGR_A_STAR_ANCHOR.positionMpc, + orientation: [1, 0, 0, 0, 1, 0, 0, 0, 1] as BodyState['orientation'], + meanAnomalyRad: 0, + }); for (const b of (state.data.bodies.planets ?? []) as readonly SeededPlanet[]) { m.set(b.id, { positionMpc: b.positionMpc, orientation: b.orientation, meanAnomalyRad: 0 }); } @@ -164,6 +175,39 @@ function makeState(bodyGlintRenderer: unknown, planets: readonly PlanetBody[]): } as unknown as EngineState; } +/** + * A `sceneBodyStates` override pinning Sgr A* at an arbitrary position instead + * of its real one — everything else matches the default factory above. Used + * ONLY by the far-dissolve test below to isolate the SEEDED-glints' solar- + * system backdrop dissolve from task 8's always-on far-field glint, which + * would otherwise give `enabled` an unrelated second reason to stay true. + */ +function statesWithAnchorPinnedAt( + anchorPositionMpc: Vec3, +): (state: EngineState) => ReadonlyMap { + return (state) => { + const m = new Map(); + m.set('sun', { positionMpc: [0, 0, 0], orientation: IDENTITY, meanAnomalyRad: 0 }); + m.set(SGR_A_STAR_ANCHOR.id, { + positionMpc: anchorPositionMpc, + orientation: IDENTITY, + meanAnomalyRad: 0, + }); + for (const b of (state.data.bodies.planets ?? []) as readonly SeededPlanet[]) { + m.set(b.id, { positionMpc: b.positionMpc, orientation: b.orientation, meanAnomalyRad: 0 }); + } + const earth = state.data.bodies.earth as SeededPlanet | null; + if (earth) { + m.set(earth.id, { + positionMpc: earth.positionMpc, + orientation: earth.orientation, + meanAnomalyRad: 0, + }); + } + return m; + }; +} + describe('bodyGlintsLayer.enabled', () => { it('is false while the renderer handle is null (short-circuits before ctx / state.data)', () => { expect( @@ -214,13 +258,58 @@ describe('bodyGlintsLayer.enabled — far dissolve (the bite)', () => { const glint = bodyAt('mars', 1, [0.6, 0.32, 0.23]); const state = makeState(makeRenderer(), [glint]); - expect(bodyGlintsLayer.enabled(state, makeCtx([dMid, 0, 0]), makeNear0View(CAM_POS))).toBe( - true, - ); - // The bite: unfixed `enabled` has no far-dissolve check, so this reads true. - expect(bodyGlintsLayer.enabled(state, makeCtx([dGone, 0, 0]), makeNear0View(CAM_POS))).toBe( - false, - ); + // Task 8's always-on Sgr A* far-field glint is a SEPARATE, legitimate + // reason for `enabled` to stay true regardless of the solar-system + // backdrop — its own coverage lives in the "Sgr A* far-field glint" + // describe block below. Pin it at each call's own camera position (so its + // crossfade reads 0, well within `sgrAStarLensing.fullAt`) to isolate the + // SEEDED glint's backdrop dissolve, the concern under test here. + const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; + try { + vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt([dMid, 0, 0])); + expect(bodyGlintsLayer.enabled(state, makeCtx([dMid, 0, 0]), makeNear0View(CAM_POS))).toBe( + true, + ); + vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt([dGone, 0, 0])); + // The bite: unfixed `enabled` has no far-dissolve check, so this reads true. + expect(bodyGlintsLayer.enabled(state, makeCtx([dGone, 0, 0]), makeNear0View(CAM_POS))).toBe( + false, + ); + } finally { + vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); + } + }); +}); + +describe('bodyGlintsLayer — Sgr A* far-field glint (task 8)', () => { + it('enabled is true when the anchor alpha is positive even with an empty glints partition', () => { + // No seeded planets — the row can only be admitted by the anchor. CAM_POS + // sits deep in the solar system, astronomically farther from the real Sgr + // A* than `sgrAStarLensing.goneAt` (500 AU) — a large but finite distance, + // not the "unresolved anchor" Infinity case — so the crossfade alone + // carries `enabled`. This is the "present the moment it's on screen" + // contract: no far-side dissolve narrows it back off. + const state = makeState(makeRenderer(), []); + expect(bodyGlintsLayer.enabled(state, makeCtx(CAM_POS), makeNear0View(CAM_POS))).toBe(true); + }); + + it('draw skips the anchor once its own crossfade reaches 0 (camera within the lensing band fullAt)', () => { + // `1 - fadeBand(sgrAStarLensing, distMpc)` is the one way the anchor's + // brightness reaches 0: the lens pass has fully engaged (distMpc <= + // fullAt, 100 AU). `draw` does not gate the anchor on the solar-system + // backdrop (unlike the seeded glints — see the module header), so pinning + // the mock anchor AT the test camera isolates exactly this skip: no + // seeded planets, so an empty batch means the renderer never draws. + const renderer = makeRenderer(); + const state = makeState(renderer, []); + const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; + try { + vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt(CAM_POS)); + bodyGlintsLayer.draw(PASS_STUB, makeNear0View(CAM_POS), makeCtx(CAM_POS), state); + expect(renderer.draw).not.toHaveBeenCalled(); + } finally { + vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); + } }); }); @@ -260,7 +349,11 @@ describe('bodyGlintsLayer.draw — far-dissolve brightness scaling', () => { makeState(renderer, [body]), ); const [, instances, count] = renderer.draw.mock.calls[0]!; - expect(count).toBe(1); + // 2 records: the seeded body (index 0, read below) plus the always-on + // Sgr A* far-field glint (index 1) — see task 8. The camera sits deep in + // the solar system here, astronomically far from the real Sgr A*, so its + // crossfade is full regardless of which of the two test cameras is used. + expect(count).toBe(2); return instances[6]!; }; @@ -298,10 +391,20 @@ describe('bodyGlintsLayer.pickEnabled (Bug B — Earth-stamp-only frame stays in it('is true when Earth is seeded within the caption gate even with an empty glints branch — while enabled is false', () => { const state = stampState(earthWithinGate); const view = makeNear0View(camWithin); - // No glints → the VISUAL draw gate is off. - expect(bodyGlintsLayer.enabled(state, makeCtx(camWithin), view)).toBe(false); - // But the Earth caption stamp must still be recorded → pick gate admits the row. - expect(bodyGlintsLayer.pickEnabled!(state, makeCtx(camWithin), view)).toBe(true); + // No glints, no Earth-caption dependency on `enabled` → the VISUAL draw + // gate is off. Isolate this from task 8's always-on Sgr A* far-field + // glint (its own coverage lives in the "Sgr A* far-field glint" describe + // block) by pinning the mock anchor at the test camera, well inside + // `sgrAStarLensing.fullAt`. + const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; + try { + vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt(camWithin)); + expect(bodyGlintsLayer.enabled(state, makeCtx(camWithin), view)).toBe(false); + // But the Earth caption stamp must still be recorded → pick gate admits the row. + expect(bodyGlintsLayer.pickEnabled!(state, makeCtx(camWithin), view)).toBe(true); + } finally { + vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); + } }); it('is false with no Earth and no glints, and false beyond the caption gate', () => { @@ -320,7 +423,7 @@ describe('bodyGlintsLayer.pickEnabled (Bug B — Earth-stamp-only frame stays in }); describe('bodyGlintsLayer.draw', () => { - it('skips the zero-brightness (unlit far side) body and packs only the lit mid-fade one', () => { + it('skips the zero-brightness (unlit far side) body and packs the lit mid-fade one plus the always-on Sgr A* glint', () => { const renderer = makeRenderer(); const state = makeState(renderer, [LIT, UNLIT]); const view = makeNear0View(CAM_POS); @@ -330,8 +433,11 @@ describe('bodyGlintsLayer.draw', () => { expect(renderer.draw).toHaveBeenCalledTimes(1); const [passArg, instances, count, vpArg, viewportArg] = renderer.draw.mock.calls[0]!; expect(passArg).toBe(PASS_STUB); - // The unlit body added nothing → exactly one record packed. - expect(count).toBe(1); + // The unlit body added nothing; the lit body packs at index 0 (checked + // below) and Sgr A*'s far-field glint (task 8) always packs a second + // record at index 1 — the camera here is astronomically far from Sgr A*'s + // real position, so its crossfade is full. + expect(count).toBe(2); // The single packed record's brightness is a strict fraction in (0, 1): the // phase term (full phase = 1) × size × albedo × the partial cross-fade. const brightness = instances[6]!; @@ -351,13 +457,26 @@ describe('bodyGlintsLayer.draw', () => { expect(viewportArg).toBe(view.viewportPx); }); - it('is a no-op when every glint is unlit (nothing packed → no draw)', () => { + it('packs only the Sgr A* glint when every seeded glint is unlit (task 8: the anchor draws unconditionally)', () => { const renderer = makeRenderer(); - // Only the unlit body present: its brightness rounds to 0, so the batch is - // empty and the additive pass submits nothing. + // Only the unlit body present: its brightness rounds to 0 and it packs + // nothing — but Sgr A*'s far-field glint is a SEPARATE, always-on source + // (see the module header), so the batch is not empty: it holds exactly + // the anchor's own record. const state = makeState(renderer, [UNLIT]); bodyGlintsLayer.draw(PASS_STUB, makeNear0View(CAM_POS), makeCtx(CAM_POS), state); - expect(renderer.draw).not.toHaveBeenCalled(); + + expect(renderer.draw).toHaveBeenCalledTimes(1); + const [, instances, count] = renderer.draw.mock.calls[0]!; + expect(count).toBe(1); + // The surviving record is Sgr A*'s, not the unlit body's: its anchor is + // rebased off the REAL Sgr A* position, not UNLIT's fixture position. + // Digits capped well below f64: the anchor sits at real-astronomical + // (~8 kpc) scale, so the Float32Array staging buffer's narrowing rounds + // at a coarser absolute precision than the KM-scale fixtures elsewhere in + // this file. + expect(instances[0]!).toBeCloseTo(SGR_A_STAR_ANCHOR.positionMpc[0] - CAM_POS[0], 6); + expect(instances[6]!).toBeGreaterThan(0); }); it('is a no-op when the bodyGlintRenderer handle is null (pre-bootstrap)', () => { From b21a5fc1c6d0316c7a4d81c9feb7290a73005fe2 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 14:19:17 +0200 Subject: [PATCH 22/60] fix(engine): review fixes for Sgr A* far-field glint (task 8 round 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Derives MAX_GLINTS from SCENE_PLANETS.length + SCENE_ANCHOR_POINT_BODIES.length + a small named margin (mirrors BODY_SLAB_CAPACITY's derivation pattern) instead of the hand-picked 24, which had silently saturated to exactly the current seed count with zero headroom. Inverts the bodyGlintsLayer.test.ts sceneBodyStates mock's default: the anchor now co-locates with the Sun (inert for every near-Sun fixture) instead of its real ~8 kpc position, so only the tests that actually exercise the far-field glint or whose own camera range crosses into sgrAStarLensing's fade zone need an explicit override — down from 4 reconciled tests to 4 explicit setups, all using mockImplementationOnce instead of the previous getMockImplementation / mockImplementation / try-finally save-restore. Also drops the dead SCENE_PLANETS import (comment-only references) and corrects sgr-a-star.ts's stale comment claiming the far-field glint would ride a dedicated ContentLayer row — it rides the existing bodyGlintsLayer instead. Co-Authored-By: Claude Fable 5 --- src/data/sources/sgr-a-star.ts | 7 +- .../gpu/renderers/bodies/bodyGlintRenderer.ts | 25 ++- .../frame/passes/bodyGlintsLayer.test.ts | 178 +++++++++--------- 3 files changed, 111 insertions(+), 99 deletions(-) diff --git a/src/data/sources/sgr-a-star.ts b/src/data/sources/sgr-a-star.ts index daf1721b01..ed3b128697 100644 --- a/src/data/sources/sgr-a-star.ts +++ b/src/data/sources/sgr-a-star.ts @@ -5,11 +5,12 @@ import { Source } from '../source'; * Sagittarius A\* — the Galactic Centre's supermassive black hole, and the * focus every S-star orbit hangs off. * - * Today it draws only its caption, so `bearsLabel` is the one capability flag + * Today it draws its caption plus a far-field glint (`bodyGlintsLayer`, keyed + * on `SCENE_ANCHOR_POINT_BODIES`), so `bearsLabel` is the one capability flag * that matters here and the caption production path (`captionPriority` / * `captionFadeRules` / `sceneBodyLabels`) is where its visibility actually - * lives. A future far-field glint and lensing-band geodesic pass ride - * dedicated `ContentLayer` rows keyed on its id, not this flag. + * lives. A future lensing-band geodesic pass rides its own dedicated + * `ContentLayer` row keyed on its id, not this flag. * * Its own registry row rather than a member of the curated star map, for the * reason the Sun's row records: a row makes the star map's gate a plain diff --git a/src/services/gpu/renderers/bodies/bodyGlintRenderer.ts b/src/services/gpu/renderers/bodies/bodyGlintRenderer.ts index 935d199a97..e079feba4b 100644 --- a/src/services/gpu/renderers/bodies/bodyGlintRenderer.ts +++ b/src/services/gpu/renderers/bodies/bodyGlintRenderer.ts @@ -56,15 +56,28 @@ import fsCode from '../../shaders/bodies/bodyGlint/fragment.wesl?static'; import { createShaderModuleWithDevLog } from '../../shaderCompileLogger'; import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../lib/cameraUniforms'; import { ADDITIVE_BLEND } from '../../lib/blendStates'; +import { SCENE_PLANETS } from '../../../../data/bodies/scenePlanets'; +import { SCENE_ANCHOR_POINT_BODIES } from '../../../../data/bodies/sceneAnchorPointBodies'; + +// Headroom past today's exact seed count, so a new SCENE_PLANETS or +// SCENE_ANCHOR_POINT_BODIES entry can still land without touching this file. +const GLINT_CAPACITY_MARGIN = 4; /** - * Upper bound on body glints drawn per frame. The glints branch is a subset of - * the seeded bodies (the flat/textured branches take the rest), so it never - * exceeds the ~21 seeded planets/moons; this caps the instance buffer with - * headroom — see "Why draw takes the batch" above, its instance buffer is a - * single fixed-capacity allocation. + * Upper bound on body glints drawn per frame: worst case every `SCENE_PLANETS` + * entry AND every `SCENE_ANCHOR_POINT_BODIES` entry packs as a glint the same + * frame (the glints branch is a SUBSET of `SCENE_PLANETS` in practice — the + * flat/textured branches take the rest — so this is a safe over-count, not a + * tight one), plus `GLINT_CAPACITY_MARGIN` headroom. Mirrors + * `BODY_SLAB_CAPACITY`'s derivation in `frameProgram.ts` — sized off the + * registries, not a hand-picked number that silently goes stale as the seed + * tables grow. Both pack loops in `bodyGlintsLayer` `break` on `count >= + * MAX_GLINTS` with no error, so zero margin would let the next seeded body + * silently starve a glint — see "Why draw takes the batch" above, its + * instance buffer is a single fixed-capacity allocation. */ -export const MAX_GLINTS = 24; +export const MAX_GLINTS = + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_BODIES.length + GLINT_CAPACITY_MARGIN; /** * Per-glint instance record: position (f32x3) + colour (f32x3) + brightness diff --git a/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts b/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts index ee747cfd66..f5b77d8ae5 100644 --- a/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts +++ b/tests/services/engine/frame/passes/bodyGlintsLayer.test.ts @@ -30,7 +30,6 @@ import { fadeBand } from '../../../../../src/utils/math/fadeBand'; import { rebaseViewProj } from '../../../../../src/utils/camera/rebaseViewProj'; import { narrowMat4 } from '../../../../../src/utils/math/narrowMat4'; import { Source } from '../../../../../src/data/sources'; -import { SCENE_PLANETS } from '../../../../../src/data/bodies/scenePlanets'; import { SGR_A_STAR_ANCHOR } from '../../../../../src/data/bodies/sceneSgrAStar'; import { packSelection, PICK_SENTINEL_OFFSET } from '../../../../../src/data/selectionEncoding'; import { SCALE_UNITS } from '../../../../../src/data/scaleUnits'; @@ -62,12 +61,17 @@ vi.mock('../../../../../src/services/engine/frame/sceneBodyStates', () => ({ orientation: [1, 0, 0, 0, 1, 0, 0, 0, 1] as BodyState['orientation'], meanAnomalyRad: 0, }); - // The 'galactic-centre' region's anchor — Sgr A*'s real position. Every - // `draw` call now packs the far-field glint unconditionally (task 8), so an - // absent entry here wouldn't just read Infinity, it would crash on - // `.positionMpc` of undefined the moment that glint tries to pack. + // The 'galactic-centre' region's anchor — co-located with the Sun, NOT + // Sgr A*'s real ~8 kpc position. `draw`/`enabled` now read this anchor + // unconditionally (task 8's far-field glint), so an absent entry would + // crash on `.positionMpc` of undefined; a REAL-position entry would instead + // make every near-Sun fixture in this file read Sgr A* as "far" (crossfade + // full), forcing unrelated tests to fight the glint off. Co-locating at the + // origin keeps the anchor INERT by default (distance 0 is deep inside + // `sgrAStarLensing.fullAt`, 100 AU) — the far-field-glint tests below move + // it out explicitly via `statesWithAnchorPinnedAt`. m.set(SGR_A_STAR_ANCHOR.id, { - positionMpc: SGR_A_STAR_ANCHOR.positionMpc, + positionMpc: [0, 0, 0], orientation: [1, 0, 0, 0, 1, 0, 0, 0, 1] as BodyState['orientation'], meanAnomalyRad: 0, }); @@ -177,10 +181,14 @@ function makeState(bodyGlintRenderer: unknown, planets: readonly PlanetBody[]): /** * A `sceneBodyStates` override pinning Sgr A* at an arbitrary position instead - * of its real one — everything else matches the default factory above. Used - * ONLY by the far-dissolve test below to isolate the SEEDED-glints' solar- - * system backdrop dissolve from task 8's always-on far-field glint, which - * would otherwise give `enabled` an unrelated second reason to stay true. + * of its default origin-co-located one — everything else matches the default + * factory above. Paired with `mockImplementationOnce` (queued once per + * anticipated `sceneBodyStates` call — `enabled` and `draw` each make 1 or 2 + * depending on which branch they take) rather than a persistent + * `mockImplementation`, so there is nothing to restore afterward. Used where a + * test's own camera range crosses into `sgrAStarLensing`'s partial-fade zone + * (the far-dissolve test below) or needs the anchor moved OUT to a visible + * distance (the far-field-glint tests). */ function statesWithAnchorPinnedAt( anchorPositionMpc: Vec3, @@ -258,58 +266,58 @@ describe('bodyGlintsLayer.enabled — far dissolve (the bite)', () => { const glint = bodyAt('mars', 1, [0.6, 0.32, 0.23]); const state = makeState(makeRenderer(), [glint]); - // Task 8's always-on Sgr A* far-field glint is a SEPARATE, legitimate - // reason for `enabled` to stay true regardless of the solar-system - // backdrop — its own coverage lives in the "Sgr A* far-field glint" - // describe block below. Pin it at each call's own camera position (so its - // crossfade reads 0, well within `sgrAStarLensing.fullAt`) to isolate the - // SEEDED glint's backdrop dissolve, the concern under test here. - const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; - try { - vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt([dMid, 0, 0])); - expect(bodyGlintsLayer.enabled(state, makeCtx([dMid, 0, 0]), makeNear0View(CAM_POS))).toBe( - true, - ); - vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt([dGone, 0, 0])); - // The bite: unfixed `enabled` has no far-dissolve check, so this reads true. - expect(bodyGlintsLayer.enabled(state, makeCtx([dGone, 0, 0]), makeNear0View(CAM_POS))).toBe( - false, - ); - } finally { - vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); - } + // dMid (~181 AU) and dGone (~605 AU) both land INSIDE `sgrAStarLensing`'s + // own (100, 500 AU) range — the default origin-co-located anchor is only + // inert within 100 AU, so at these two specific camera positions it would + // otherwise give `enabled` a SECOND, unrelated reason to stay/go true (its + // own coverage lives in the "Sgr A* far-field glint" describe block + // below). Pin it at each call's own camera position instead (distance 0, + // always inert) to isolate the SEEDED glint's backdrop dissolve, the + // concern under test here. `enabled` calls `sceneBodyStates` twice when it + // reaches `sceneBodyPartition` (the dMid case) and once when the backdrop + // gate alone already returns false (the dGone case) — queue exactly that + // many `mockImplementationOnce` per call. + const pinAtDMid = statesWithAnchorPinnedAt([dMid, 0, 0]); + vi.mocked(sceneBodyStates).mockImplementationOnce(pinAtDMid).mockImplementationOnce(pinAtDMid); + expect(bodyGlintsLayer.enabled(state, makeCtx([dMid, 0, 0]), makeNear0View(CAM_POS))).toBe( + true, + ); + vi.mocked(sceneBodyStates).mockImplementationOnce(statesWithAnchorPinnedAt([dGone, 0, 0])); + // The bite: unfixed `enabled` has no far-dissolve check, so this reads true. + expect(bodyGlintsLayer.enabled(state, makeCtx([dGone, 0, 0]), makeNear0View(CAM_POS))).toBe( + false, + ); }); }); describe('bodyGlintsLayer — Sgr A* far-field glint (task 8)', () => { it('enabled is true when the anchor alpha is positive even with an empty glints partition', () => { - // No seeded planets — the row can only be admitted by the anchor. CAM_POS - // sits deep in the solar system, astronomically farther from the real Sgr - // A* than `sgrAStarLensing.goneAt` (500 AU) — a large but finite distance, - // not the "unresolved anchor" Infinity case — so the crossfade alone - // carries `enabled`. This is the "present the moment it's on screen" - // contract: no far-side dissolve narrows it back off. + // No seeded planets — the row can only be admitted by the anchor. Move it + // OUT to its real ~8 kpc position (the default fixture keeps it inert, + // co-located with the Sun) — astronomically farther than + // `sgrAStarLensing.goneAt` (500 AU), a large but finite distance, not the + // "unresolved anchor" Infinity case — so the crossfade alone carries + // `enabled`. This is the "present the moment it's on screen" contract: no + // far-side dissolve narrows it back off. `enabled` calls `sceneBodyStates` + // once here (the anchor check short-circuits before `sceneBodyPartition`). const state = makeState(makeRenderer(), []); + vi.mocked(sceneBodyStates).mockImplementationOnce( + statesWithAnchorPinnedAt(SGR_A_STAR_ANCHOR.positionMpc), + ); expect(bodyGlintsLayer.enabled(state, makeCtx(CAM_POS), makeNear0View(CAM_POS))).toBe(true); }); - it('draw skips the anchor once its own crossfade reaches 0 (camera within the lensing band fullAt)', () => { + it('draw skips the anchor once its own crossfade reaches 0 (the default fixture keeps it inert)', () => { // `1 - fadeBand(sgrAStarLensing, distMpc)` is the one way the anchor's // brightness reaches 0: the lens pass has fully engaged (distMpc <= - // fullAt, 100 AU). `draw` does not gate the anchor on the solar-system - // backdrop (unlike the seeded glints — see the module header), so pinning - // the mock anchor AT the test camera isolates exactly this skip: no - // seeded planets, so an empty batch means the renderer never draws. + // fullAt, 100 AU). The default fixture already co-locates the mock anchor + // with the Sun — well within `fullAt` of CAM_POS (~0.0067 AU) — so no + // override is needed: no seeded planets, so an empty batch means the + // renderer never draws. const renderer = makeRenderer(); const state = makeState(renderer, []); - const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; - try { - vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt(CAM_POS)); - bodyGlintsLayer.draw(PASS_STUB, makeNear0View(CAM_POS), makeCtx(CAM_POS), state); - expect(renderer.draw).not.toHaveBeenCalled(); - } finally { - vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); - } + bodyGlintsLayer.draw(PASS_STUB, makeNear0View(CAM_POS), makeCtx(CAM_POS), state); + expect(renderer.draw).not.toHaveBeenCalled(); }); }); @@ -342,6 +350,13 @@ describe('bodyGlintsLayer.draw — far-dissolve brightness scaling', () => { orientation: IDENTITY, }; const renderer = makeRenderer(); + // dMid (~181 AU) sits inside `sgrAStarLensing`'s own (100, 500 AU) range, + // where the default origin-co-located anchor is no longer inert — pin it + // at each call's own camera regardless of camX so this test's only + // packed record stays the seeded body, at both cameras. `draw` calls + // `sceneBodyStates` twice (via `sceneBodyPartition` and its own read). + const pinAtCam = statesWithAnchorPinnedAt(camPos); + vi.mocked(sceneBodyStates).mockImplementationOnce(pinAtCam).mockImplementationOnce(pinAtCam); bodyGlintsLayer.draw( PASS_STUB, makeNear0View(camPos), @@ -349,11 +364,7 @@ describe('bodyGlintsLayer.draw — far-dissolve brightness scaling', () => { makeState(renderer, [body]), ); const [, instances, count] = renderer.draw.mock.calls[0]!; - // 2 records: the seeded body (index 0, read below) plus the always-on - // Sgr A* far-field glint (index 1) — see task 8. The camera sits deep in - // the solar system here, astronomically far from the real Sgr A*, so its - // crossfade is full regardless of which of the two test cameras is used. - expect(count).toBe(2); + expect(count).toBe(1); return instances[6]!; }; @@ -392,19 +403,17 @@ describe('bodyGlintsLayer.pickEnabled (Bug B — Earth-stamp-only frame stays in const state = stampState(earthWithinGate); const view = makeNear0View(camWithin); // No glints, no Earth-caption dependency on `enabled` → the VISUAL draw - // gate is off. Isolate this from task 8's always-on Sgr A* far-field - // glint (its own coverage lives in the "Sgr A* far-field glint" describe - // block) by pinning the mock anchor at the test camera, well inside - // `sgrAStarLensing.fullAt`. - const defaultImpl = vi.mocked(sceneBodyStates).getMockImplementation()!; - try { - vi.mocked(sceneBodyStates).mockImplementation(statesWithAnchorPinnedAt(camWithin)); - expect(bodyGlintsLayer.enabled(state, makeCtx(camWithin), view)).toBe(false); - // But the Earth caption stamp must still be recorded → pick gate admits the row. - expect(bodyGlintsLayer.pickEnabled!(state, makeCtx(camWithin), view)).toBe(true); - } finally { - vi.mocked(sceneBodyStates).mockImplementation(defaultImpl); - } + // gate is off. `camWithin` is only 1e-6 Mpc — tiny in Mpc terms, but that + // is still ~206,000 AU, well past `sgrAStarLensing.goneAt` (500 AU) — so + // the default origin-co-located anchor reads as "far" (crossfade full), + // an unrelated second reason for `enabled` to go true. Pin it AT the test + // camera instead (distance 0, always inert) to isolate the Earth-caption + // concern under test here. `enabled` calls `sceneBodyStates` once (the + // backdrop gate alone already returns false, before `sceneBodyPartition`). + vi.mocked(sceneBodyStates).mockImplementationOnce(statesWithAnchorPinnedAt(camWithin)); + expect(bodyGlintsLayer.enabled(state, makeCtx(camWithin), view)).toBe(false); + // But the Earth caption stamp must still be recorded → pick gate admits the row. + expect(bodyGlintsLayer.pickEnabled!(state, makeCtx(camWithin), view)).toBe(true); }); it('is false with no Earth and no glints, and false beyond the caption gate', () => { @@ -423,7 +432,7 @@ describe('bodyGlintsLayer.pickEnabled (Bug B — Earth-stamp-only frame stays in }); describe('bodyGlintsLayer.draw', () => { - it('skips the zero-brightness (unlit far side) body and packs the lit mid-fade one plus the always-on Sgr A* glint', () => { + it('skips the zero-brightness (unlit far side) body and packs only the lit mid-fade one', () => { const renderer = makeRenderer(); const state = makeState(renderer, [LIT, UNLIT]); const view = makeNear0View(CAM_POS); @@ -433,11 +442,12 @@ describe('bodyGlintsLayer.draw', () => { expect(renderer.draw).toHaveBeenCalledTimes(1); const [passArg, instances, count, vpArg, viewportArg] = renderer.draw.mock.calls[0]!; expect(passArg).toBe(PASS_STUB); - // The unlit body added nothing; the lit body packs at index 0 (checked - // below) and Sgr A*'s far-field glint (task 8) always packs a second - // record at index 1 — the camera here is astronomically far from Sgr A*'s - // real position, so its crossfade is full. - expect(count).toBe(2); + // The unlit body added nothing → exactly one record packed. (Task 8's + // Sgr A* far-field glint doesn't contribute here: the default fixture + // keeps it co-located with the Sun, well inside `sgrAStarLensing.fullAt` + // of CAM_POS — see "Sgr A* far-field glint" describe block for its own + // coverage.) + expect(count).toBe(1); // The single packed record's brightness is a strict fraction in (0, 1): the // phase term (full phase = 1) × size × albedo × the partial cross-fade. const brightness = instances[6]!; @@ -457,26 +467,14 @@ describe('bodyGlintsLayer.draw', () => { expect(viewportArg).toBe(view.viewportPx); }); - it('packs only the Sgr A* glint when every seeded glint is unlit (task 8: the anchor draws unconditionally)', () => { + it('is a no-op when every glint is unlit (nothing packed → no draw)', () => { const renderer = makeRenderer(); - // Only the unlit body present: its brightness rounds to 0 and it packs - // nothing — but Sgr A*'s far-field glint is a SEPARATE, always-on source - // (see the module header), so the batch is not empty: it holds exactly - // the anchor's own record. + // Only the unlit body present: its brightness rounds to 0, so the batch is + // empty and the additive pass submits nothing. (Task 8's Sgr A* far-field + // glint doesn't contribute either — see the note above.) const state = makeState(renderer, [UNLIT]); bodyGlintsLayer.draw(PASS_STUB, makeNear0View(CAM_POS), makeCtx(CAM_POS), state); - - expect(renderer.draw).toHaveBeenCalledTimes(1); - const [, instances, count] = renderer.draw.mock.calls[0]!; - expect(count).toBe(1); - // The surviving record is Sgr A*'s, not the unlit body's: its anchor is - // rebased off the REAL Sgr A* position, not UNLIT's fixture position. - // Digits capped well below f64: the anchor sits at real-astronomical - // (~8 kpc) scale, so the Float32Array staging buffer's narrowing rounds - // at a coarser absolute precision than the KM-scale fixtures elsewhere in - // this file. - expect(instances[0]!).toBeCloseTo(SGR_A_STAR_ANCHOR.positionMpc[0] - CAM_POS[0], 6); - expect(instances[6]!).toBeGreaterThan(0); + expect(renderer.draw).not.toHaveBeenCalled(); }); it('is a no-op when the bodyGlintRenderer handle is null (pre-bootstrap)', () => { From 2a8a3298502f4765a0d84b1e98a114e5e367b111 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 14:07:43 +0200 Subject: [PATCH 23/60] feat(engine): amortized sky-cubemap capture schedule + frameProgram wiring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit skyCubemapCaptureSchedule is a pure round-robin scheduler for the Sgr A* lens's 6-face sky capture: full sweep on band entry, one face/frame otherwise, with a staleness/camera-move escape valve. frameProgram grows a fourth parameter (the faces to capture this frame) and emits one 'sky-cubemap' render step per face, gated on the lensing band alpha so zero steps are emitted outside it. renderFrame derives the schedule each frame from the band alpha (keyed on camera distance from the galactic-centre anchor, same as every other sgrAStarLensing consumer) and threads it through; the schedule's own cross-frame bookkeeping (lastCapturedAtMs, frameIndex, band-active edge, last-sweep camera position) lives on a new cameraRuntime.skyCubemapCapture Resource, following the same amortized-Resources pattern its sibling fields use. FrameStep's 'render' kind grows an optional `face` field, and a new renderStepTimingSlotName helper (slabs.ts) disambiguates the 6 capture steps' timing-slot names — they all share (target, slab), unlike a body row which gets its own slab index for free. Finding (not resolved here): no ContentLayer row targets 'sky-cubemap' today, so these steps currently select an empty group and draw nothing. The schedule, timing-slot derivation, and DebugPanel plumbing are ready; wiring the actual roster (point-sprites/star-points/star-catalog/ star-aggregates) into the capture target is follow-up work — see the Task 12 report for the full writeup of why "reuse the existing layers' draw calls" doesn't fall out for free under the current (target, slab) grouping model. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/FrameStep.d.ts | 12 +++ src/@types/engine/state/CameraRuntime.d.ts | 10 ++ .../state/SkyCubemapCaptureRuntime.d.ts | 25 +++++ src/services/engine/engine.ts | 9 ++ src/services/engine/frame/executeFrame.ts | 9 +- src/services/engine/frame/frameProgram.ts | 64 +++++++++++-- src/services/engine/frame/renderFrame.ts | 67 +++++++++++++- .../engine/frame/skyCubemapCaptureSchedule.ts | 69 ++++++++++++++ src/services/engine/frame/slabs.ts | 17 ++++ .../playClipFlyout.integration.test.ts | 6 ++ .../engine/camera/commitOnEdge.test.ts | 6 ++ .../engine/frame/frameProgram.test.ts | 32 ++++--- .../services/engine/frame/renderFrame.test.ts | 13 +++ .../engine/frame/renderFrame.timing.test.ts | 10 ++ .../frame/skyCubemapCaptureSchedule.test.ts | 91 +++++++++++++++++++ .../engine/frame/targetParity.test.ts | 13 ++- .../engine/frame/timedSlotsGroupKeys.test.ts | 2 +- tests/visual/renderFrameSplitBaseline.test.ts | 10 ++ 18 files changed, 432 insertions(+), 33 deletions(-) create mode 100644 src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts create mode 100644 src/services/engine/frame/skyCubemapCaptureSchedule.ts create mode 100644 tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts diff --git a/src/@types/engine/frame/FrameStep.d.ts b/src/@types/engine/frame/FrameStep.d.ts index b3801c7d91..078a2755bf 100644 --- a/src/@types/engine/frame/FrameStep.d.ts +++ b/src/@types/engine/frame/FrameStep.d.ts @@ -39,6 +39,7 @@ */ import type { CompositeStep } from './CompositeStep'; +import type { CubeFace } from '../../rendering/CubeFace'; export type FrameStep = | { kind: 'compute'; name: string } @@ -54,6 +55,17 @@ export type FrameStep = * foreground row — declare `'clear'` to restart depth mid-frame. */ depthLoad?: 'clear' | 'load'; + /** + * Which array layer of a `fixedSizePx` target this step writes — today + * only the black-hole lens's 6-face sky-cubemap capture (Task 12). + * Absent for every ordinary render step. Its sole job is disambiguating + * several `(target, slab)` steps that would otherwise collide: all six + * faces share `('sky-cubemap', NEAR0)`, unlike a body row (which gets + * its own `slab` index and so is unique without help) — see + * `timedSlotRowsOf`'s per-step naming and `executeFrame`'s matching + * timing-slot lookup, frameProgram.ts / executeFrame.ts. + */ + face?: CubeFace; } | { kind: 'composite'; step: CompositeStep } | { kind: 'bloom' }; diff --git a/src/@types/engine/state/CameraRuntime.d.ts b/src/@types/engine/state/CameraRuntime.d.ts index 86be510000..752955fe6f 100644 --- a/src/@types/engine/state/CameraRuntime.d.ts +++ b/src/@types/engine/state/CameraRuntime.d.ts @@ -62,6 +62,13 @@ * and is its SINGLE writer — the one place that answers 'which * way is up this frame' for every reader. * + * `skyCubemapCapture` — the black-hole lens's amortized sky-capture + * bookkeeping (`lastCapturedAtMs`, round-robin + * `frameIndex`, the band-active edge, last-sweep camera + * position). Not boxed — `renderFrame` is its only + * reader/writer, so no other module needs a shared live + * reference. See `SkyCubemapCaptureRuntime.d.ts`. + * * Constructed in `engine.ts` alongside `frameRef`, this bag is the single source * of truth for all four Resources: `wireInput`, `startLoop`, `runFrame`, and the * focus handlers all read from `state.cameraRuntime`, so there is no duplication @@ -72,6 +79,7 @@ import type { CameraClock } from '../camera/CameraClock'; import type { CameraProjection } from '../../camera/CameraProjection'; import type { CameraPose } from '../../camera/CameraPose'; import type { Mat3 } from '../../math/Mat3'; +import type { SkyCubemapCaptureRuntime } from './SkyCubemapCaptureRuntime'; export type CameraRuntime = { /** The animation clock — mutated by tweenElapsed / autoRotateElapsed once per frame. */ @@ -93,4 +101,6 @@ export type CameraRuntime = { * `runFrame` writes it, once per frame from `resolveFrameBasis`. */ upBasis: { current: Mat3 }; + /** The black-hole lens's amortized sky-capture bookkeeping; single-writer `renderFrame`. */ + skyCubemapCapture: SkyCubemapCaptureRuntime; }; diff --git a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts new file mode 100644 index 0000000000..c2f4d13f8e --- /dev/null +++ b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts @@ -0,0 +1,25 @@ +/** + * SkyCubemapCaptureRuntime — cross-frame memory for the black-hole lens's + * amortized sky-cubemap capture (Task 12). `skyCubemapCaptureSchedule` is + * pure, but its inputs (`lastCapturedAtMs`, the round-robin `frameIndex`, the + * `bandJustEngaged` edge) need somewhere to live between frames — + * `renderFrame` "owns no cross-frame state" by design (see its module + * header), so this rides in `cameraRuntime` alongside the same + * amortized-Resources pattern its sibling fields (`lastPose`, + * `lastRenderedSimDays`, …) already follow. Single-writer: only + * `renderFrame` reads or writes it. + */ + +import type { CubeFace } from '../../rendering/CubeFace'; +import type { Vec3 } from '../../math/Vec3'; + +export type SkyCubemapCaptureRuntime = { + /** Wall-clock ms each face was last captured, for the schedule's staleness check. */ + lastCapturedAtMs: Map; + /** Monotonic per-frame counter driving the round-robin (`frameIndex % 6`). */ + frameIndex: number; + /** The lensing band's active/inactive state last frame — `bandJustEngaged`'s edge. */ + wasBandActive: boolean; + /** Camera position at the last FULL sweep (band entry or escape valve), for the movement check. `null` before the first sweep. */ + lastSweepCamPosMpc: Readonly | null; +}; diff --git a/src/services/engine/engine.ts b/src/services/engine/engine.ts index 544060cbec..434eb1fcd0 100644 --- a/src/services/engine/engine.ts +++ b/src/services/engine/engine.ts @@ -181,6 +181,15 @@ export function createEngine(canvas: HTMLCanvasElement, cb: EngineCallbacks): En // valid; `runFrame` overwrites it with the resolved B(t) each frame. Copied // so the seed never aliases the shared registry entry. upBasis: { current: [...ORIENTATION_FRAMES[DEFAULT_ORIENTATION]] }, + // Sky-cubemap capture bookkeeping (Task 12) — empty/false/null until the + // first frame the lensing band goes active; `renderFrame` is the sole + // writer thereafter. + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, }; // ── Settings — the injected Redux store ────────────────────────── diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 1a276e7adf..9baf0c12ae 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -65,7 +65,7 @@ import type { ContentLayer } from '../../../@types/engine/frame/ContentLayer'; import type { RenderStrategy } from '../../../@types/engine/frame/RenderStrategy'; import type { SlabView } from '../../../@types/engine/frame/SlabView'; import type { GpuTimingService } from '../../../@types/gpu/timing/GpuTimingService'; -import { slabViewOf, groupKeyOf, layerTimingSlotName } from './slabs'; +import { slabViewOf, groupKeyOf, layerTimingSlotName, renderStepTimingSlotName } from './slabs'; import { encodeFlowCompute } from './encodeFlowCompute'; import { encodeAtmosphereSkyView } from './encodeAtmosphereSkyView'; import { runBloom } from './runBloom'; @@ -217,7 +217,12 @@ export function executeFrame(args: ExecuteFrameArgs): void { // comes from the shared `groupKeyOf` helper (slabs.ts) — the same // definition `timedSlotRowsOf` allocates the slot under — so // `descriptorFor(groupKey)` resolves exactly that slot. - const groupKey = groupKeyOf(step.target, step.slab); + // `renderStepTimingSlotName` appends `step.face` when present — the + // sky-cubemap capture's 6 faces all share `('sky-cubemap', NEAR0)`, so + // the bare groupKey would look up the SAME slot for all 6 (see its doc, + // slabs.ts); for every other step `step.face` is absent and this is a + // no-op passthrough of `groupKey`. + const groupKey = renderStepTimingSlotName(groupKeyOf(step.target, step.slab), step.face); renderGroup(strategy, { encoder, ctx, diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index 13468940b8..f580515b11 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -63,7 +63,16 @@ import type { FrameStep } from '../../../@types/engine/frame/FrameStep'; import type { ContentLayer } from '../../../@types/engine/frame/ContentLayer'; import type { ToneMap } from '../../../@types/rendering/ToneMap'; -import { COSMO, NEAR0, groupKeyOf, isBodySlabIndex, layerTimingSlotName, slabName } from './slabs'; +import type { CubeFace } from '../../../@types/rendering/CubeFace'; +import { + COSMO, + NEAR0, + groupKeyOf, + isBodySlabIndex, + layerTimingSlotName, + renderStepTimingSlotName, + slabName, +} from './slabs'; import { CONTENT_LAYERS } from './passes'; import { SCENE_PLANETS } from '../../../data/bodies/scenePlanets'; import { SCENE_ANCHOR_POINT_BODIES } from '../../../data/bodies/sceneAnchorPointBodies'; @@ -100,11 +109,28 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * back-to-front) expands the ONE `foreground:0` render into one step per * entry, each `depthLoad: 'clear'` so a nearer body row doesn't test against * a farther row's depth — see the push loop below. + * + * `skyCubemapFacesToCapture` (`skyCubemapCaptureSchedule`'s output, computed + * by `renderFrame` each frame from the lensing band alpha — Task 12) is the + * black-hole lens's amortized sky-capture list: empty outside the band, so + * NO capture steps are emitted at all (Q6's zero-dispatch guarantee — this is + * the capture side of that contract, not just the lensing draw itself). + * Placed in the compute prelude's wake, ahead of every other render step, so + * a same-frame lensing draw (Task 13) can sample a cubemap this frame + * actually wrote. One step per requested face, at the NEAR0 slab — the + * majority of the fixed opt-in roster (star-points, star-catalog, + * star-aggregates) projects through NEAR0; `point-sprites` is COSMO-slab and + * is NOT yet reachable through this step (see the finding recorded in the + * Task 12 report — no `ContentLayer` row targets `'sky-cubemap'` today, so + * these steps presently select an empty group and draw nothing; they exist + * so the schedule, the timing-slot derivation, and the DebugPanel plumbing + * are ready for the roster wiring that follows). */ export function frameProgram( tone: ToneMap, bloomEnabled: boolean, foregroundChain: readonly number[], + skyCubemapFacesToCapture: readonly CubeFace[], ): readonly FrameStep[] { const steps: FrameStep[] = []; @@ -118,6 +144,10 @@ export function frameProgram( // is unaffected. steps.push({ kind: 'compute', name: 'atmosphereSkyView' }); + for (const face of skyCubemapFacesToCapture) { + steps.push({ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face }); + } + steps.push({ kind: 'render', target: 'volume', slab: COSMO }); // Zone-of-avoidance band raymarch into its own reduced-res offscreen — // the twin of the volume render immediately above. Precedes the hdr @@ -266,6 +296,10 @@ export const PASS_GROUP_TITLES: Readonly> = { 'zoa·COSMO': 'Volumes & aggregates', 'star-aggregates·NEAR0': 'Volumes & aggregates', 'mw-aggregate·NEAR0': 'Volumes & aggregates', + // The black-hole lens's amortized sky-capture steps (Task 12) — 0-6 of + // them per frame depending on `skyCubemapCaptureSchedule`, so its own + // group rather than folding into an existing title. + 'sky-cubemap·NEAR0': 'Sky capture', 'hdr·COSMO': 'Cosmos · HDR', 'hdr·NEAR0': 'Near field · HDR', 'foreground:0·NEAR0': 'Foreground bodies · depth', @@ -333,11 +367,14 @@ function timedSlotRowsOf( // AFTER the layer loop so the group total trails its layers in draw order. // Emitted unconditionally for shape-stability; simply unused when the // group is empty (the executor's `if (group.length === 0) break;` opens no - // pass, so no timing is billed against it). `groupKey` is - // unique per step (each has a distinct `(target, slab)`) and never - // collides with a layer name, so it earns its own timing slot and, in the - // DebugPanel's grouped lists, its own row under the step's group title. - rows.push({ name: groupKey, groupKey }); + // pass, so no timing is billed against it). `groupKey` is unique per step + // for every ordinary render step (each has a distinct `(target, slab)`) + // and never collides with a layer name — EXCEPT the sky-cubemap capture + // steps, which share `('sky-cubemap', NEAR0)` across all 6 faces; + // `renderStepTimingSlotName` appends the face there so each still earns + // its own slot (see its doc, slabs.ts). The DebugPanel bucket still uses + // the shared `groupKey`, so all 6 land under one "Sky capture" group. + rows.push({ name: renderStepTimingSlotName(groupKey, step.face), groupKey }); } else if (step.kind === 'composite') { // A composite merges whole textures rather than projecting geometry — it // belongs to no slab, and all composites share the one infra group. @@ -451,8 +488,17 @@ const MAX_FOREGROUND_CHAIN: readonly number[] = [ ...Array.from({ length: BODY_SLAB_CAPACITY }, (_, k) => k + 2), ]; +/** + * All 6 `CubeFace` values — the same "maximum, not a real frame's shorter + * list" sizing rationale `MAX_FOREGROUND_CHAIN` documents above, so the + * DebugPanel's GPU-timing groups include the sky-cubemap capture rows even + * on a frame where the lensing band is inactive and the real capture list + * would be empty. + */ +const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; + export const TIMED_SLOTS: readonly string[] = timedSlotsOf( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN), + frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), CONTENT_LAYERS, ); @@ -462,7 +508,7 @@ export const TIMED_SLOTS: readonly string[] = timedSlotsOf( * `CONTENT_LAYERS` gets a grouped row here with zero DebugPanel edits. */ export const TIMED_SLOT_GROUPS: readonly TimedSlotGroup[] = timedSlotGroupsOf( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN), + frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), CONTENT_LAYERS, ); @@ -501,7 +547,7 @@ function plainLayerGroupKeys( * project them into the same groups the timing list uses. */ const PASS_GROUP_KEYS: ReadonlyMap = plainLayerGroupKeys( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN), + frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), CONTENT_LAYERS, ); diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 15369a62fe..5349281416 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -32,9 +32,13 @@ * * ### Why pass an explicit input bag instead of capturing closure? * - * This module owns no cross-frame state — every value it reads is recomputed - * each frame. A free function taking a struct of inputs is trivially testable - * and bounds the encoder lifetime to the function body. + * This module owns no cross-frame state of its OWN — every local value it + * computes is recomputed each frame. It DOES read/write one Resource, Task + * 12's `state.cameraRuntime.skyCubemapCapture` (the black-hole lens's + * amortized sky-capture bookkeeping), the same amortized-Resources shape + * `cameraRuntime`'s other fields already carry — see + * `SkyCubemapCaptureRuntime.d.ts`. A free function taking a struct of inputs + * is trivially testable and bounds the encoder lifetime to the function body. * * ### What stays in `runFrame()` (NOT here) * @@ -48,12 +52,27 @@ import type { RenderFrameInput } from '../../../@types/engine/frame/RenderFrameInput'; import type { RenderStrategy } from '../../../@types/engine/frame/RenderStrategy'; +import type { CubeFace } from '../../../@types/rendering/CubeFace'; import { executeFrame } from './executeFrame'; import { frameProgram } from './frameProgram'; import { resolveStrategy } from './resolveStrategy'; import { foregroundChainOrder } from './slabs'; import { CONTENT_LAYERS } from './passes'; import { hdrActiveOf } from '../../../utils/gpu/hdrActiveOf'; +import { + skyCubemapCaptureSchedule, + SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU, +} from './skyCubemapCaptureSchedule'; +import { sceneBodyStates } from './sceneBodyStates'; +import { regionById } from '../../../utils/scene/regionById'; +import { regionRelativeDistanceMpc } from '../../../utils/scene/regionRelativeDistanceMpc'; +import { distanceMpc } from '../../../utils/math/distanceMpc'; +import { fadeBand } from '../../../utils/math/fadeBand'; +import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; +import { SCALE_UNITS } from '../../../data/scaleUnits'; + +const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC = + SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU * SCALE_UNITS.AU_TO_MPC; /** * Encode and submit one frame. Synchronous: by the time it returns, the GPU @@ -92,6 +111,47 @@ export function renderFrame(input: RenderFrameInput): void { // makes that in-between frame correct, not just a safe fallback. const hdrActive = hdrActiveOf(ctx.renderTargets); const hdrOn = hdrActive && state.settings.hdr.enabled; + + // The black-hole lens's amortized sky-cubemap capture schedule (Task 12). + // `bandAlpha` keys on the CAMERA's distance from the galactic-centre + // anchor, same quantity + region every `sgrAStarLensing`-band consumer + // reads (`scaleFadeBands.ts`). Bookkeeping lives on `cameraRuntime`, not + // here — see `SkyCubemapCaptureRuntime.d.ts` for why `renderFrame` (which + // owns no cross-frame state of its own) is still this bag's sole writer. + const captureRuntime = state.cameraRuntime.skyCubemapCapture; + const gcDistanceMpc = regionRelativeDistanceMpc( + ctx.drawCamPos, + regionById('galactic-centre'), + sceneBodyStates(state, ctx), + ); + const bandActive = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, gcDistanceMpc) > 0; + const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; + // Every captured face's content (which galaxies/stars are visible, their + // backdrop-fade alpha) is keyed on the PLAYER's camera position, not the + // fixed capture eye at Sgr A* — so a big enough move stales every face at + // once, same as band entry. + const cameraMovedBeyondThreshold = + captureRuntime.lastSweepCamPosMpc !== null && + distanceMpc(ctx.drawCamPos, captureRuntime.lastSweepCamPosMpc) > + SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC; + const skyCubemapFacesToCapture: readonly CubeFace[] = bandActive + ? skyCubemapCaptureSchedule({ + bandJustEngaged, + frameIndex: captureRuntime.frameIndex, + lastCapturedAtMs: captureRuntime.lastCapturedAtMs, + nowMs: ctx.nowMs, + cameraMovedBeyondThreshold, + }).facesToCapture + : []; + for (const face of skyCubemapFacesToCapture) { + captureRuntime.lastCapturedAtMs.set(face, ctx.nowMs); + } + if (bandJustEngaged || cameraMovedBeyondThreshold) { + captureRuntime.lastSweepCamPosMpc = ctx.drawCamPos; + } + captureRuntime.wasBandActive = bandActive; + captureRuntime.frameIndex += 1; + executeFrame({ encoder, ctx, @@ -109,6 +169,7 @@ export function renderFrame(input: RenderFrameInput): void { // Painter-ordered NEAR0 + body-row indices (Task 4) — the chain the // foreground:0 render expands into, one step per entry. foregroundChainOrder(ctx.slabs), + skyCubemapFacesToCapture, ), layers: CONTENT_LAYERS, strategy, diff --git a/src/services/engine/frame/skyCubemapCaptureSchedule.ts b/src/services/engine/frame/skyCubemapCaptureSchedule.ts new file mode 100644 index 0000000000..1d57cdf97e --- /dev/null +++ b/src/services/engine/frame/skyCubemapCaptureSchedule.ts @@ -0,0 +1,69 @@ +/** + * skyCubemapCaptureSchedule — the black-hole sky cubemap's amortized capture + * schedule, as a pure function. A full 6-face capture (re-drawing the roster + * from a fixed eye) is too costly every frame, so this spreads the cost: one + * full sweep on band ENTRY, then one face per frame in round-robin, with an + * escape valve that pulls a face out of turn once it's gone stale (by age, + * or because a camera move invalidates the whole cubemap at once). + * + * No GPU/engine state: every input is a plain value (`renderFrame.ts`'s call + * site derives `bandJustEngaged`/`cameraMovedBeyondThreshold`), so this is + * testable headlessly. + */ + +import type { CubeFace } from '../../../@types/rendering/CubeFace'; + +const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; + +/** + * How long a face may go without a recapture before the escape valve pulls + * it back into the schedule out of turn, regardless of the round-robin's own + * pick this frame. Data tuning, not architecture — sited beside the schedule + * function it gates. + */ +export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; + +/** + * How far the camera may drift from its position at the last full sweep + * (band entry or a prior escape-valve sweep) before `renderFrame` derives + * `cameraMovedBeyondThreshold: true` — every face's captured content (which + * galaxies/stars are visible, their backdrop-fade alpha) is keyed on the + * PLAYER's camera position, not the fixed capture eye at Sgr A*, so a big + * enough move stales the whole cubemap at once. Sited here (not in + * `renderFrame.ts`, the actual comparison site) beside its sibling time + * threshold — both are this feature's data-tuning knobs. Roughly a tenth of + * the lensing band's `fullAt` edge (100 AU, `scaleFadeBands.ts`), eye-tuned. + */ +export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU = 10; + +export type SkyCubemapCaptureSchedule = { + readonly facesToCapture: readonly CubeFace[]; // this frame's capture list +}; + +export function skyCubemapCaptureSchedule(input: { + readonly bandJustEngaged: boolean; // band alpha crossed 0→positive this frame + readonly frameIndex: number; // for round-robin + readonly lastCapturedAtMs: ReadonlyMap; + readonly nowMs: number; + readonly cameraMovedBeyondThreshold: boolean; +}): SkyCubemapCaptureSchedule { + const { bandJustEngaged, frameIndex, lastCapturedAtMs, nowMs, cameraMovedBeyondThreshold } = + input; + + if (bandJustEngaged || cameraMovedBeyondThreshold) { + // A moved eye invalidates every face at once — same as band entry, no + // partial-sweep half-state to reason about. + return { facesToCapture: ALL_CUBE_FACES }; + } + + const roundRobinFace = (frameIndex % 6) as CubeFace; + const faces = new Set([roundRobinFace]); + for (const face of ALL_CUBE_FACES) { + const lastCapturedAt = lastCapturedAtMs.get(face); + // Absent ⇒ never captured, which is staler than any threshold — the + // capacity row exists (Task 3) but no sweep has touched this face yet. + const staleMs = lastCapturedAt === undefined ? Infinity : nowMs - lastCapturedAt; + if (staleMs > SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS) faces.add(face); + } + return { facesToCapture: [...faces] }; +} diff --git a/src/services/engine/frame/slabs.ts b/src/services/engine/frame/slabs.ts index 3ffc4c0bc0..cc734cd02e 100644 --- a/src/services/engine/frame/slabs.ts +++ b/src/services/engine/frame/slabs.ts @@ -101,6 +101,23 @@ export function layerTimingSlotName(layerName: string, slabIndex: number): strin return isBodySlabIndex(slabIndex) ? `${layerName}·${slabName(slabIndex)}` : layerName; } +/** + * The per-STEP query-set slot name for a render step that may carry a + * `face` (Task 12's sky-cubemap capture) — `groupKey` unchanged, or + * `'·FACE[n]'` when a face is present. Six capture steps share one + * `(target, slab)` — `('sky-cubemap', NEAR0)` — because the array-layer they + * write isn't part of the `(target, slab)` key at all (unlike a body row, + * which gets its OWN `slab` index and so is already unique), so `groupKeyOf` + * alone collides across faces; this is `layerTimingSlotName`'s counterpart + * one level up, disambiguating the STEP's own slot rather than a layer's. + * `timedSlotRowsOf` (frameProgram.ts) allocates under this name; + * `executeFrame`'s merged pass must resolve the identical name via + * `descriptorFor`, so both call this rather than templating `·FACE[n]` twice. + */ +export function renderStepTimingSlotName(groupKey: string, face: number | undefined): string { + return face === undefined ? groupKey : `${groupKey}·FACE[${face}]`; +} + /** * The single source of each slab's depth convention: `false` ⇒ the classic * smaller-z-wins / clear-`1.0` / `mat4d.perspective` set; `true` ⇒ reversed-Z diff --git a/tests/services/engine/animation/playClipFlyout.integration.test.ts b/tests/services/engine/animation/playClipFlyout.integration.test.ts index 0d1d90378b..9cbb382f32 100644 --- a/tests/services/engine/animation/playClipFlyout.integration.test.ts +++ b/tests/services/engine/animation/playClipFlyout.integration.test.ts @@ -118,6 +118,12 @@ function makeEngineState(startDistance: number): { prevActiveId: { current: 'resting' as string }, lastRenderedSimDays: { current: 0 }, upBasis: { current: ORIENTATION_FRAMES.ecliptic }, + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, }, }; diff --git a/tests/services/engine/camera/commitOnEdge.test.ts b/tests/services/engine/camera/commitOnEdge.test.ts index 18788385c9..a07a62d9ab 100644 --- a/tests/services/engine/camera/commitOnEdge.test.ts +++ b/tests/services/engine/camera/commitOnEdge.test.ts @@ -94,6 +94,12 @@ function makeEngineState(): { prevActiveId: { current: 'resting' as string }, lastRenderedSimDays: { current: 0 }, upBasis: { current: ORIENTATION_FRAMES.ecliptic }, + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, }, }; diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index 877e8e463e..c199ecc9f0 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -95,7 +95,7 @@ describe('frameProgram', () => { // Bloom OFF — the base thirteen-step shape (the bloom-enabled program splices // one bloom step between the foreground composite and the tone-map; see the // bloom-gating tests below). - expect(frameProgram(TONE, false, [NEAR0])).toEqual([ + expect(frameProgram(TONE, false, [NEAR0], [])).toEqual([ { kind: 'compute', name: 'flow' }, { kind: 'compute', name: 'atmosphereSkyView' }, { kind: 'render', target: 'volume', slab: COSMO }, @@ -123,7 +123,7 @@ describe('frameProgram', () => { // starts fresh rather than fighting a farther row's. The surrounding // steps — the preceding (hdr, NEAR0) render and the following // foreground:0→hdr composite — are unmoved. - const program = frameProgram(TONE, false, [NEAR0, 3, 2]); + const program = frameProgram(TONE, false, [NEAR0, 3, 2], []); const hdrNear0Idx = program.findIndex( (step) => step.kind === 'render' && step.target === 'hdr' && step.slab === NEAR0, ); @@ -148,7 +148,7 @@ describe('frameProgram', () => { // so this is a no-op at runtime, but the step must still exist in the // program or a future chain-emitting frame's stale-touched bookkeeping // would be one step off. - const program = frameProgram(TONE, false, []); + const program = frameProgram(TONE, false, [], []); const hdrNear0Idx = program.findIndex( (step) => step.kind === 'render' && step.target === 'hdr' && step.slab === NEAR0, ); @@ -167,7 +167,7 @@ describe('frameProgram', () => { // hdr→swap replace-composite carries the one real tone object (identity, // not just equal values). Exactly one composite therefore carries a // non-null tone — that lone tone-map is what gives the frame one curve. - const program = frameProgram(TONE, false, [NEAR0]); + const program = frameProgram(TONE, false, [NEAR0], []); const composites = program.filter((step) => step.kind === 'composite'); const [foregroundComposite, hdrComposite] = composites; if (foregroundComposite?.kind !== 'composite' || hdrComposite?.kind !== 'composite') { @@ -187,7 +187,7 @@ describe('frameProgram', () => { // BEFORE the tone-map, otherwise they'd be double-tonemapped (or skip the // curve entirely). Assert the linear body composite's index is below the // tone-map's. - const program = frameProgram(TONE, false, [NEAR0]); + const program = frameProgram(TONE, false, [NEAR0], []); const isComposite = (source: string, dest: string) => (step: FrameStep) => step.kind === 'composite' && step.step.source === source && step.step.dest === dest; const foregroundIdx = program.findIndex(isComposite('foreground:0', 'hdr')); @@ -210,7 +210,7 @@ describe('frameProgram', () => { viewportPx: [1920, 1080], starSphereRangeM: null, }); - for (const step of frameProgram(TONE, true, [NEAR0])) { + for (const step of frameProgram(TONE, true, [NEAR0], [])) { if (step.kind === 'render') { expect([NEAR0, COSMO]).toContain(step.slab); expect(slabs[step.slab]).toBeDefined(); @@ -223,7 +223,7 @@ describe('frameProgram', () => { // the lone hdr→swap tone curve — so the single `{ kind: 'bloom' }` step must // sit after the linear foreground:0→hdr composite and before the hdr→swap // tone-map. Exactly one composite still carries a non-null tone. - const program = frameProgram(TONE, true, [NEAR0]); + const program = frameProgram(TONE, true, [NEAR0], []); const bloomSteps = program.filter((step) => step.kind === 'bloom'); expect(bloomSteps).toHaveLength(1); @@ -250,8 +250,8 @@ describe('frameProgram', () => { // Only `enabled` shapes the step list. Bloom-off is the base program; bloom-on // is that base with exactly ONE `{ kind: 'bloom' }` step spliced in between the // foreground composite and the tone-map — nothing else changes. - const off = frameProgram(TONE, false, [NEAR0]); - const on = frameProgram(TONE, true, [NEAR0]); + const off = frameProgram(TONE, false, [NEAR0], []); + const on = frameProgram(TONE, true, [NEAR0], []); const bloomSteps = on.filter((step) => step.kind === 'bloom'); expect(bloomSteps).toEqual([{ kind: 'bloom' }]); @@ -289,7 +289,7 @@ describe('timedSlotsOf', () => { // into HDR before the tone-map), so its group-key slot sits above them. The // zoa render step matches no fake layer either, so it contributes only // its own group-key slot, right after volume·COSMO. - expect(timedSlotsOf(frameProgram(TONE, false, [NEAR0]), layers)).toEqual([ + expect(timedSlotsOf(frameProgram(TONE, false, [NEAR0], []), layers)).toEqual([ 'volume·COSMO', 'zoa·COSMO', 'point-sprites', @@ -316,7 +316,7 @@ describe('timedSlotsOf', () => { ]; // Bloom ON adds the single `'bloom'` slot; every render step now has a // distinct `(target, slab)`, so no slot name collides. - const slots = timedSlotsOf(frameProgram(TONE, true, [NEAR0]), layers); + const slots = timedSlotsOf(frameProgram(TONE, true, [NEAR0], []), layers); expect(new Set(slots).size).toBe(slots.length); }); @@ -351,7 +351,7 @@ describe('timedSlotsOf', () => { // group-key slot (the merged-pass timing slot Joint 2 adds), so // 'volume·COSMO' follows scalar-volume, 'hdr·COSMO' follows the eight COSMO // hdr layers, and so on down to 'swap·NEAR0' after the near-field captions. - expect(timedSlotsOf(frameProgram(TONE, true, [2, NEAR0]), CONTENT_LAYERS)).toEqual([ + expect(timedSlotsOf(frameProgram(TONE, true, [2, NEAR0], []), CONTENT_LAYERS)).toEqual([ 'scalar-volume', 'volume·COSMO', 'zone-of-avoidance', @@ -468,7 +468,7 @@ describe('timedSlotGroupsOf', () => { fakeLayer('labels', 'swap', COSMO), fakeLayer('earth', 'foreground:0', NEAR0), ]; - const groups = timedSlotGroupsOf(frameProgram(TONE, false, [NEAR0]), layers); + const groups = timedSlotGroupsOf(frameProgram(TONE, false, [NEAR0], []), layers); // Group titles in draw/table order. The two composites and pick collapse // into one trailing group. @@ -508,9 +508,11 @@ describe('timedSlotGroupsOf', () => { // milky-way-aggregate (mw-aggregate·NEAR0) are non-adjacent steps that all // map to "Volumes & aggregates"; the two composites and pick — scattered // through execution order — collapse into - // the trailing "Composites & pick". + // the trailing "Composites & pick". "Sky capture" is TIMED_SLOTS' 6 capture + // steps (Task 12's ALL_CUBE_FACES sizing, one row per face). expect(TIMED_SLOT_GROUPS.map((g) => g.title)).toEqual([ 'Volumes & aggregates', + 'Sky capture', 'Cosmos · HDR', 'Near field · HDR', 'Foreground bodies · depth', @@ -579,7 +581,7 @@ describe('timedSlotGroupsOf', () => { enabled: vi.fn(() => true), draw: vi.fn(), }; - const groups = timedSlotGroupsOf(frameProgram(TONE, false, [NEAR0, 2, 3]), [bodyLayer]); + const groups = timedSlotGroupsOf(frameProgram(TONE, false, [NEAR0, 2, 3], []), [bodyLayer]); const foreground = groups.find((g) => g.title === 'Foreground bodies · depth')!; expect(foreground.rows.map((r) => r.name)).toEqual([ 'foreground:0·NEAR0', diff --git a/tests/services/engine/frame/renderFrame.test.ts b/tests/services/engine/frame/renderFrame.test.ts index 023d376ac2..76cfb987a5 100644 --- a/tests/services/engine/frame/renderFrame.test.ts +++ b/tests/services/engine/frame/renderFrame.test.ts @@ -569,6 +569,19 @@ function makeInput( fades: { opacityOf: () => 1 }, clipPlayer: { clipOpacityOf: () => 1 }, }, + // Task 12's sky-cubemap capture bookkeeping — renderFrame reads/writes + // this every frame now, regardless of whether the lensing band is + // active (the fixture camera sits Mpc-scale away from Sgr A*, so the + // band alpha is 0 and `facesToCapture` stays empty; see + // `skyCubemapCaptureSchedule`'s call site in renderFrame.ts). + cameraRuntime: { + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, + }, } as never, device, context, diff --git a/tests/services/engine/frame/renderFrame.timing.test.ts b/tests/services/engine/frame/renderFrame.timing.test.ts index 191fc91959..c565dc54b9 100644 --- a/tests/services/engine/frame/renderFrame.timing.test.ts +++ b/tests/services/engine/frame/renderFrame.timing.test.ts @@ -372,6 +372,16 @@ function makeMinimalInputWithTiming(timingService: GpuTimingService): { fades: { opacityOf: (id: { kind: string }) => (id.kind === 'milkyWay' ? 1 : 0) }, clipPlayer: { clipOpacityOf: () => 1 }, }, + // Task 12's sky-cubemap capture bookkeeping — see the matching fixture + // comment in renderFrame.test.ts. + cameraRuntime: { + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, + }, } as never, device, context, diff --git a/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts b/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts new file mode 100644 index 0000000000..90cd95c352 --- /dev/null +++ b/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts @@ -0,0 +1,91 @@ +/** + * skyCubemapCaptureSchedule — unit tests for the black-hole sky cubemap's + * amortized capture schedule. Pure function, no GPU/engine state: every + * input is a plain value, so the round-robin/escape-valve logic is + * exercised headlessly. + */ + +import { describe, it, expect } from 'vitest'; + +import { skyCubemapCaptureSchedule } from '../../../../src/services/engine/frame/skyCubemapCaptureSchedule'; +import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; + +const ALL_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; + +describe('skyCubemapCaptureSchedule', () => { + it('full 6-face capture on band entry', () => { + for (let frameIndex = 0; frameIndex < 12; frameIndex++) { + const { facesToCapture } = skyCubemapCaptureSchedule({ + bandJustEngaged: true, + frameIndex, + lastCapturedAtMs: new Map(), + nowMs: 1000, + cameraMovedBeyondThreshold: false, + }); + expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); + } + }); + + it('round-robins one face per frame otherwise', () => { + const seen: CubeFace[] = []; + for (let frameIndex = 0; frameIndex < 6; frameIndex++) { + const { facesToCapture } = skyCubemapCaptureSchedule({ + bandJustEngaged: false, + frameIndex, + lastCapturedAtMs: new Map(ALL_FACES.map((f) => [f, 1000])), + nowMs: 1000, + cameraMovedBeyondThreshold: false, + }); + expect(facesToCapture).toHaveLength(1); + seen.push(facesToCapture[0]!); + } + expect([...seen].sort()).toEqual([...ALL_FACES]); + expect(new Set(seen).size).toBe(6); + }); + + it('escape valve re-captures a stale face out of turn', () => { + // Face 2 is the round-robin's own pick at frameIndex 2 (frameIndex % 6), + // so pick a DIFFERENT frame (0) and make a DIFFERENT face (2) stale — + // it must appear alongside the round-robin's own face (0). + const lastCapturedAtMs = new Map([ + [0, 100_000], + [1, 100_000], + [2, 0], // captured at t=0 — far older than the recapture threshold + [3, 100_000], + [4, 100_000], + [5, 100_000], + ]); + const { facesToCapture } = skyCubemapCaptureSchedule({ + bandJustEngaged: false, + frameIndex: 0, + lastCapturedAtMs, + nowMs: 100_000, + cameraMovedBeyondThreshold: false, + }); + expect(facesToCapture).toContain(0); // this frame's round-robin face + expect(facesToCapture).toContain(2); // the stale escape-valve face + }); + + it('escape valve re-captures every face out of turn when the camera moved', () => { + const lastCapturedAtMs = new Map(ALL_FACES.map((f) => [f, 100_000])); + const { facesToCapture } = skyCubemapCaptureSchedule({ + bandJustEngaged: false, + frameIndex: 0, + lastCapturedAtMs, + nowMs: 100_000, + cameraMovedBeyondThreshold: true, + }); + expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); + }); + + it('a face missing from lastCapturedAtMs (never captured) is always stale', () => { + const { facesToCapture } = skyCubemapCaptureSchedule({ + bandJustEngaged: false, + frameIndex: 3, // round-robin would pick face 3 alone + lastCapturedAtMs: new Map(), // every face uncaptured + nowMs: 0, + cameraMovedBeyondThreshold: false, + }); + expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); + }); +}); diff --git a/tests/services/engine/frame/targetParity.test.ts b/tests/services/engine/frame/targetParity.test.ts index 4acbd12287..dc9dd01a46 100644 --- a/tests/services/engine/frame/targetParity.test.ts +++ b/tests/services/engine/frame/targetParity.test.ts @@ -28,9 +28,16 @@ describe('render-target parity', () => { }); it('every frameProgram step names a declared render-target row', () => { - const program = frameProgram({ exposure: 1, curve: 0, hdrKnee: 0, hdrHeadroom: 0 }, true, [ - NEAR0, - ]); + // All 6 faces requested, so this also covers the sky-cubemap capture + // steps' `target` — a wrong string there would silently draw nothing + // (see the module header), so it earns the same parity check as every + // other step. + const program = frameProgram( + { exposure: 1, curve: 0, hdrKnee: 0, hdrHeadroom: 0 }, + true, + [NEAR0], + [0, 1, 2, 3, 4, 5], + ); for (const step of program) { if (step.kind === 'render') { expect(ROW_IDS.has(step.target)).toBe(true); diff --git a/tests/services/engine/frame/timedSlotsGroupKeys.test.ts b/tests/services/engine/frame/timedSlotsGroupKeys.test.ts index 1471d563f7..232b32dd5a 100644 --- a/tests/services/engine/frame/timedSlotsGroupKeys.test.ts +++ b/tests/services/engine/frame/timedSlotsGroupKeys.test.ts @@ -24,7 +24,7 @@ describe('timedSlotsOf — per-render-step group keys', () => { // Bloom ON so the derivation covers the single `'bloom'` slot the sub-pipeline // adds alongside the per-render-step group keys. const slots = timedSlotsOf( - frameProgram({ exposure: 1, curve: 0, hdrKnee: 0, hdrHeadroom: 0 }, true, [NEAR0]), + frameProgram({ exposure: 1, curve: 0, hdrKnee: 0, hdrHeadroom: 0 }, true, [NEAR0], []), CONTENT_LAYERS, ); diff --git a/tests/visual/renderFrameSplitBaseline.test.ts b/tests/visual/renderFrameSplitBaseline.test.ts index 3c92c82df6..d7f36ba501 100644 --- a/tests/visual/renderFrameSplitBaseline.test.ts +++ b/tests/visual/renderFrameSplitBaseline.test.ts @@ -500,6 +500,16 @@ describe('renderFrame visual baseline', () => { }, clipPlayer: { clipOpacityOf: () => 1 }, }, + // Task 12's sky-cubemap capture bookkeeping — see the matching + // fixture comment in renderFrame.test.ts. + cameraRuntime: { + skyCubemapCapture: { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }, + }, } as never, device, context, From ef31b088f2386d654c63c127cbb04267e64fca17 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 14:26:45 +0200 Subject: [PATCH 24/60] fix(engine): build the sky-cubemap runtime hand-off (round 1 review fix) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 1 (31d1c94be) shipped the capture schedule and frameProgram wiring but never built the brief's "runtime hand-off" step: renderFrame deriving each scheduled face's skyCubemapFaceContext and passing it to the executor so a capture step resolves its OWN camera instead of the frame-wide one. That omission went undisclosed in the round-1 report, unlike the (correctly flagged) roster-target-string finding — a real compliance gap, not a judgment call. Fixed here: ExecuteFrameArgs grows an optional skyCubemapFaceContexts map; executeFrame's 'render' case resolves a face-carrying step's SlabView/ enabled/draw ctx from that map instead of the frame-wide ctx, skipping the step cleanly when a face has no context (mirrors skyCubemapFaceContext itself returning null pre-bootstrap). renderFrame derives the map each frame — one skyCubemapFaceContext call per scheduled face, eye = Sgr A*'s anchor, faceSizePx read off the sky-cubemap row's own declared size — and threads it through. The draw group these steps select is still empty (the separate, still-open roster-wiring finding from round 1); this only builds the ctx/view hand-off. Also trims skyCubemapCaptureSchedule.ts's comment budget (33/28 → 12/28 comment/code lines) per the review's minor finding. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/ExecuteFrameArgs.d.ts | 12 ++ src/services/engine/frame/executeFrame.ts | 29 +++- src/services/engine/frame/renderFrame.ts | 26 +++ .../engine/frame/skyCubemapCaptureSchedule.ts | 31 +--- .../engine/frame/executeFrame.test.ts | 73 ++++++++ .../renderFrame.skyCubemapHandOff.test.ts | 156 ++++++++++++++++++ 6 files changed, 297 insertions(+), 30 deletions(-) create mode 100644 tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts diff --git a/src/@types/engine/frame/ExecuteFrameArgs.d.ts b/src/@types/engine/frame/ExecuteFrameArgs.d.ts index 22b96900b6..6665b7a339 100644 --- a/src/@types/engine/frame/ExecuteFrameArgs.d.ts +++ b/src/@types/engine/frame/ExecuteFrameArgs.d.ts @@ -17,6 +17,15 @@ * - `timing` supplies the per-pass `timestampWrites` descriptor (a no-op in * production); `swapView` is this frame's acquired swap-chain view, the * one render target that is not an allocated offscreen texture. + * - `skyCubemapFaceContexts` is the black-hole lens's per-face camera + * override (Task 12's runtime hand-off): a step carrying `face` + * resolves its `SlabView`/`ctx` from THIS map instead of the frame-wide + * `ctx` above. `renderFrame` derives it each frame (one + * `skyCubemapFaceContext` call per scheduled face); `frameProgram` + * stays static and never sees it. Absent/missing-face ⇒ that step is + * skipped cleanly (no throw) — the same outcome as + * `skyCubemapFaceContext` itself returning `null` for a pre-bootstrap + * frame. */ import type { ReadyFrameContext } from './ReadyFrameContext'; @@ -25,6 +34,7 @@ import type { ContentLayer } from './ContentLayer'; import type { RenderStrategy } from './RenderStrategy'; import type { EngineState } from '../state/EngineState'; import type { GpuTimingService } from '../../gpu/timing/GpuTimingService'; +import type { CubeFace } from '../../rendering/CubeFace'; export type ExecuteFrameArgs = { /** The single per-frame command encoder every step records into. */ @@ -43,4 +53,6 @@ export type ExecuteFrameArgs = { timing: GpuTimingService; /** This frame's swap-chain view — the `'swap'` target's texture view. */ swapView: GPUTextureView; + /** Per-face camera override for sky-cubemap capture steps; see above. */ + skyCubemapFaceContexts?: ReadonlyMap; }; diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 9baf0c12ae..d9e0274db0 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -167,7 +167,17 @@ function timestampSpread( } export function executeFrame(args: ExecuteFrameArgs): void { - const { encoder, ctx, state, program, layers, strategy, timing, swapView } = args; + const { + encoder, + ctx, + state, + program, + layers, + strategy, + timing, + swapView, + skyCubemapFaceContexts, + } = args; // Per-`executeFrame` first-touch bookkeeping: a target id enters this set the // first time a pass is opened against it, flipping subsequent passes from @@ -189,6 +199,17 @@ export function executeFrame(args: ExecuteFrameArgs): void { break; } case 'render': { + // The runtime hand-off (Task 12): a step carrying `face` (the + // black-hole lens's sky-cubemap capture) resolves EVERY per-step value + // below — slab view, enable gate, draw ctx — from ITS OWN camera + // (`renderFrame`'s per-face `skyCubemapFaceContext` derivation), not + // the frame-wide `ctx`. A missing map entry (that face's + // `skyCubemapFaceContext` returned null — e.g. a pre-bootstrap frame) + // skips the step cleanly, the same outcome an empty group already + // produces below. For every ordinary step `step.face` is undefined and + // `stepCtx` is just `ctx` — a no-op passthrough. + const stepCtx = step.face === undefined ? ctx : skyCubemapFaceContexts?.get(step.face); + if (stepCtx === undefined) break; // The DebugPanel renderer-toggle override is one-way: it hides a layer // whose own `enabled()` gate returned true, and can never force-enable // one whose gate returned false — hence the check follows the gate. @@ -199,7 +220,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { // (not after, as before body slabs): a 'body' layer's `enabled` needs // the view to read `view.slab.frame.bodyId`, and a step whose slab is // a body row still resolves cheaply even when its group ends up empty. - const view = slabViewOf(ctx, step.slab); + const view = slabViewOf(stepCtx, step.slab); const group = layers.filter( (l) => l.target === step.target && @@ -209,7 +230,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { // going through `isBodySlabIndex` (slabs.ts) — the index-only // sibling check `frameProgram.ts` uses where no `Slab` is in hand. (l.slab === step.slab || (l.slab === 'body' && view.slab.frame.kind === 'body-m')) && - l.enabled(state, ctx, view) && + l.enabled(state, stepCtx, view) && disabledPasses[l.name] !== true, ); if (group.length === 0) break; @@ -225,7 +246,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { const groupKey = renderStepTimingSlotName(groupKeyOf(step.target, step.slab), step.face); renderGroup(strategy, { encoder, - ctx, + ctx: stepCtx, state, timing, swapView, diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 5349281416..c2c839c091 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -53,6 +53,7 @@ import type { RenderFrameInput } from '../../../@types/engine/frame/RenderFrameInput'; import type { RenderStrategy } from '../../../@types/engine/frame/RenderStrategy'; import type { CubeFace } from '../../../@types/rendering/CubeFace'; +import type { ReadyFrameContext } from '../../../@types/engine/frame/ReadyFrameContext'; import { executeFrame } from './executeFrame'; import { frameProgram } from './frameProgram'; import { resolveStrategy } from './resolveStrategy'; @@ -63,6 +64,7 @@ import { skyCubemapCaptureSchedule, SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU, } from './skyCubemapCaptureSchedule'; +import { skyCubemapFaceContext } from './skyCubemapFaceContext'; import { sceneBodyStates } from './sceneBodyStates'; import { regionById } from '../../../utils/scene/regionById'; import { regionRelativeDistanceMpc } from '../../../utils/scene/regionRelativeDistanceMpc'; @@ -70,6 +72,7 @@ import { distanceMpc } from '../../../utils/math/distanceMpc'; import { fadeBand } from '../../../utils/math/fadeBand'; import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; import { SCALE_UNITS } from '../../../data/scaleUnits'; +import { SGR_A_STAR_ANCHOR } from '../../../data/bodies/sceneSgrAStar'; const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC = SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU * SCALE_UNITS.AU_TO_MPC; @@ -152,6 +155,28 @@ export function renderFrame(input: RenderFrameInput): void { captureRuntime.wasBandActive = bandActive; captureRuntime.frameIndex += 1; + // The runtime hand-off (Task 12's brief, "Name the runtime hand-off"): + // `frameProgram` only knows WHICH faces to capture (static data); resolving + // each face's own synthetic camera is `renderFrame`'s job, done fresh every + // frame since the schedule's face LIST can change frame to frame. + // `faceSizePx` reads the sky-cubemap row's own declared size rather than a + // hard-coded constant, so the two can never drift. A face whose context + // comes back null (pre-bootstrap) is simply omitted — `executeFrame` treats + // a missing map entry as "skip this step cleanly" (see its module header). + const skyCubemapFaceContexts = new Map(); + if (skyCubemapFacesToCapture.length > 0) { + const faceSizePx = ctx.renderTargets.specOf('sky-cubemap').fixedSizePx!.size; + for (const face of skyCubemapFacesToCapture) { + const faceCtx = skyCubemapFaceContext({ + state, + eyeMpc: SGR_A_STAR_ANCHOR.positionMpc, + face, + faceSizePx, + }); + if (faceCtx !== null) skyCubemapFaceContexts.set(face, faceCtx); + } + } + executeFrame({ encoder, ctx, @@ -175,6 +200,7 @@ export function renderFrame(input: RenderFrameInput): void { strategy, timing: timingService, swapView, + skyCubemapFaceContexts, }); timingService.endFrame(timingCtx, encoder); diff --git a/src/services/engine/frame/skyCubemapCaptureSchedule.ts b/src/services/engine/frame/skyCubemapCaptureSchedule.ts index 1d57cdf97e..9f51c34e72 100644 --- a/src/services/engine/frame/skyCubemapCaptureSchedule.ts +++ b/src/services/engine/frame/skyCubemapCaptureSchedule.ts @@ -1,39 +1,18 @@ /** * skyCubemapCaptureSchedule — the black-hole sky cubemap's amortized capture - * schedule, as a pure function. A full 6-face capture (re-drawing the roster - * from a fixed eye) is too costly every frame, so this spreads the cost: one - * full sweep on band ENTRY, then one face per frame in round-robin, with an - * escape valve that pulls a face out of turn once it's gone stale (by age, - * or because a camera move invalidates the whole cubemap at once). - * - * No GPU/engine state: every input is a plain value (`renderFrame.ts`'s call - * site derives `bandJustEngaged`/`cameraMovedBeyondThreshold`), so this is - * testable headlessly. + * schedule: a full 6-face sweep on band ENTRY, then one face per frame in + * round-robin, with an escape valve for a stale or camera-moved face. Pure — + * every input is a plain value — so it's testable headlessly. */ import type { CubeFace } from '../../../@types/rendering/CubeFace'; const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; -/** - * How long a face may go without a recapture before the escape valve pulls - * it back into the schedule out of turn, regardless of the round-robin's own - * pick this frame. Data tuning, not architecture — sited beside the schedule - * function it gates. - */ +/** Escape-valve staleness threshold. Data tuning, sited beside the schedule it gates. */ export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; -/** - * How far the camera may drift from its position at the last full sweep - * (band entry or a prior escape-valve sweep) before `renderFrame` derives - * `cameraMovedBeyondThreshold: true` — every face's captured content (which - * galaxies/stars are visible, their backdrop-fade alpha) is keyed on the - * PLAYER's camera position, not the fixed capture eye at Sgr A*, so a big - * enough move stales the whole cubemap at once. Sited here (not in - * `renderFrame.ts`, the actual comparison site) beside its sibling time - * threshold — both are this feature's data-tuning knobs. Roughly a tenth of - * the lensing band's `fullAt` edge (100 AU, `scaleFadeBands.ts`), eye-tuned. - */ +/** Escape-valve camera-movement threshold, AU — see `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation for the comparison and why. */ export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU = 10; export type SkyCubemapCaptureSchedule = { diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index d82aa8c70d..9f42ddac7f 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -31,6 +31,7 @@ import type { TimingSlotName } from '../../../../src/@types/gpu/timing/TimingSlo import type { SlabView } from '../../../../src/@types/engine/frame/SlabView'; import type { Slab } from '../../../../src/@types/engine/frame/Slab'; import type { BodyId } from '../../../../src/@types/data/body/BodyId'; +import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; // ── Encoder / pass recorder ────────────────────────────────────────────────── // @@ -141,6 +142,7 @@ const VOLUME_VIEW = { __id: 'volume-view' } as unknown as GPUTextureView; const FG_VIEW = { __id: 'foreground-view' } as unknown as GPUTextureView; const FG_DEPTH_VIEW = { __id: 'foreground-depth-view' } as unknown as GPUTextureView; const SWAP_VIEW = { __id: 'swap-view' } as unknown as GPUTextureView; +const SKY_CUBEMAP_VIEW = { __id: 'sky-cubemap-view' } as unknown as GPUTextureView; const EXEC_SPECS = [ { @@ -171,6 +173,14 @@ const EXEC_SPECS = [ scale: 1, clearValue: { r: 0, g: 0, b: 0, a: 1 }, }, + { + id: 'sky-cubemap', + format: 'rgba16float' as const, + depth: null, + scale: 1, + clearValue: { r: 0, g: 0, b: 0, a: 0 }, + fixedSizePx: { size: 256, layers: 6 }, + }, ]; function makeCtx(): ReadyFrameContext { @@ -202,6 +212,7 @@ function makeCtx(): ReadyFrameContext { if (id === 'hdr') return HDR_VIEW; if (id === 'volume') return VOLUME_VIEW; if (id === 'foreground:0') return FG_VIEW; + if (id === 'sky-cubemap') return SKY_CUBEMAP_VIEW; throw new Error(`mock renderTargets: no view for '${id}'`); }, depthViewOf: (id: string) => { @@ -258,6 +269,7 @@ function makeArgs(over: { state?: EngineState; env?: ReturnType; ctx?: ReadyFrameContext; + skyCubemapFaceContexts?: ReadonlyMap; }): { args: ExecuteFrameArgs; env: ReturnType } { const env = over.env ?? makeEncoderEnv(); const args: ExecuteFrameArgs = { @@ -269,6 +281,7 @@ function makeArgs(over: { strategy: over.strategy ?? 'merged', timing: over.timing ?? makeNoTiming(), swapView: SWAP_VIEW, + skyCubemapFaceContexts: over.skyCubemapFaceContexts, }; return { args, env }; } @@ -726,4 +739,64 @@ describe('executeFrame', () => { executeFrame(args); expect(layer.draw).not.toHaveBeenCalled(); }); + + describe('sky-cubemap capture hand-off (Task 12)', () => { + // A step carrying `face` must resolve its OWN camera (`enabled`/`draw`'s + // `ctx`), not the frame-wide `args.ctx` — the runtime hand-off `renderFrame` + // derives per scheduled face via `skyCubemapFaceContext` and threads in as + // `skyCubemapFaceContexts`. Two distinct fixture contexts stand in for two + // faces' synthetic cameras; identity (`toBe`), not content, is what proves + // routing, since a real face ctx and the frame ctx share the same shape. + it("resolves each capture step's own face ctx, never the frame-wide ctx", () => { + const layer = makeLayer({ name: 'probe', target: 'sky-cubemap', slab: NEAR0 }); + const face0Ctx = makeCtx(); + const face1Ctx = makeCtx(); + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }, + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 1 }, + ]; + const skyCubemapFaceContexts = new Map([ + [0, face0Ctx], + [1, face1Ctx], + ]); + const { args } = makeArgs({ program, layers: [layer], skyCubemapFaceContexts }); + executeFrame(args); + + expect(layer.enabled).toHaveBeenCalledTimes(2); + expect(layer.draw).toHaveBeenCalledTimes(2); + expect(layer.enabled.mock.calls[0]![1]).toBe(face0Ctx); + expect(layer.draw.mock.calls[0]![2]).toBe(face0Ctx); + expect(layer.enabled.mock.calls[1]![1]).toBe(face1Ctx); + expect(layer.draw.mock.calls[1]![2]).toBe(face1Ctx); + // Neither call reached for the frame-wide ctx — the whole point of the + // per-step override. + expect(layer.draw.mock.calls[0]![2]).not.toBe(args.ctx); + expect(layer.draw.mock.calls[1]![2]).not.toBe(args.ctx); + }); + + it('skips a capture step cleanly when its face has no context (skyCubemapFaceContext returned null)', () => { + const layer = makeLayer({ name: 'probe', target: 'sky-cubemap', slab: NEAR0 }); + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 2 }, + ]; + // Map has no entry for face 2 — mirrors renderFrame omitting a face whose + // skyCubemapFaceContext call returned null (pre-bootstrap frame). + const { args } = makeArgs({ + program, + layers: [layer], + skyCubemapFaceContexts: new Map(), + }); + expect(() => executeFrame(args)).not.toThrow(); + expect(layer.enabled).not.toHaveBeenCalled(); + expect(layer.draw).not.toHaveBeenCalled(); + }); + + it('an ordinary (non-face) render step is unaffected by an absent skyCubemapFaceContexts map', () => { + const layer = makeLayer({ name: 'a', target: 'hdr' }); + const program: FrameStep[] = [{ kind: 'render', target: 'hdr', slab: COSMO }]; + const { args } = makeArgs({ program, layers: [layer] }); + executeFrame(args); + expect(layer.draw.mock.calls[0]![2]).toBe(args.ctx); + }); + }); }); diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts new file mode 100644 index 0000000000..84d8486fcb --- /dev/null +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -0,0 +1,156 @@ +/** + * renderFrame — sky-cubemap runtime hand-off (Task 12's "Name the runtime + * hand-off" step, built in round 1's fix-up). + * + * `executeFrame` and `skyCubemapFaceContext` are both mocked: this file + * is about the WIRING — renderFrame calling `skyCubemapFaceContext` once per + * scheduled face with the black hole's eye/face/row-declared size, and + * threading the resulting map into `executeFrame`'s `skyCubemapFaceContexts` + * — not the GPU pass machinery `renderFrame.test.ts` already covers. + */ + +import { describe, it, expect, vi, beforeEach } from 'vitest'; + +// `vi.mock` factories are hoisted above imports (and above plain top-level +// `const`s) — `vi.hoisted` is the sanctioned escape hatch for a mock fn both +// the factory AND the test body need to reference. +const { executeFrameMock, skyCubemapFaceContextMock } = vi.hoisted(() => ({ + executeFrameMock: vi.fn(), + skyCubemapFaceContextMock: vi.fn(), +})); +vi.mock('../../../../src/services/engine/frame/executeFrame', () => ({ + executeFrame: executeFrameMock, +})); +vi.mock('../../../../src/services/engine/frame/skyCubemapFaceContext', () => ({ + skyCubemapFaceContext: skyCubemapFaceContextMock, +})); + +import { renderFrame } from '../../../../src/services/engine/frame/renderFrame'; +import { createDisabledGpuTimingService } from '../../../../src/services/gpu/timing/gpuTimingService'; +import { SGR_A_STAR_ANCHOR } from '../../../../src/data/bodies/sceneSgrAStar'; +import type { ReadyFrameContext } from '../../../../src/@types/engine/frame/ReadyFrameContext'; +import type { EngineState } from '../../../../src/@types/engine/state/EngineState'; +import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; + +const ALL_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; + +/** A fresh, never-captured-before `skyCubemapCapture` Resource. */ +function makeCaptureRuntime() { + return { + lastCapturedAtMs: new Map(), + frameIndex: 0, + wasBandActive: false, + lastSweepCamPosMpc: null, + }; +} + +function makeState(): EngineState { + return { + gpu: { focusUniform: null }, + settings: { + tonemap: { exposure: 1, curve: 0 }, + hdr: { enabled: false, knee: 0, headroom: 0 }, + bloom: { enabled: false }, + debug: { renderStrategy: 'auto' }, + }, + cameraRuntime: { skyCubemapCapture: makeCaptureRuntime() }, + } as unknown as EngineState; +} + +/** `drawCamPos` at the anchor itself ⇒ distance 0 ⇒ deep inside the lensing band (fullAt = 100 AU). */ +function makeCtx(drawCamPos: readonly [number, number, number]): ReadyFrameContext { + return { + isReady: true, + drawCamPos, + simDays: 0, + nowMs: 1000, + focus: {}, + slabs: [], + renderTargets: { + specOf: (id: string) => { + if (id === 'sky-cubemap') return { fixedSizePx: { size: 256, layers: 6 } }; + if (id === 'swap') return { format: 'bgra8unorm' }; + throw new Error(`mock renderTargets: no spec row for '${id}'`); + }, + }, + } as unknown as ReadyFrameContext; +} + +function makeInput(ctx: ReadyFrameContext, state: EngineState) { + return { + ctx, + state, + device: { + createCommandEncoder: vi.fn( + () => ({ finish: vi.fn(() => ({})) }) as unknown as GPUCommandEncoder, + ), + queue: { submit: vi.fn() }, + } as unknown as GPUDevice, + context: { + getCurrentTexture: () => ({ createView: () => ({}) as GPUTextureView }), + } as unknown as GPUCanvasContext, + timingService: createDisabledGpuTimingService(), + }; +} + +describe('renderFrame — sky-cubemap runtime hand-off', () => { + beforeEach(() => { + executeFrameMock.mockClear(); + skyCubemapFaceContextMock.mockClear(); + }); + + it('derives each scheduled face via skyCubemapFaceContext(eye=Sgr A*, faceSizePx=row size) and threads the map into executeFrame', () => { + const faceCtxByFace = new Map(); + skyCubemapFaceContextMock.mockImplementation((input: { face: CubeFace }) => { + const ctx = { __face: input.face } as unknown as ReadyFrameContext; + faceCtxByFace.set(input.face, ctx); + return ctx; + }); + + const ctx = makeCtx(SGR_A_STAR_ANCHOR.positionMpc); + renderFrame(makeInput(ctx, makeState())); + + // Distance 0 from the anchor, first frame ever ⇒ bandJustEngaged ⇒ full sweep. + expect(skyCubemapFaceContextMock).toHaveBeenCalledTimes(6); + for (const call of skyCubemapFaceContextMock.mock.calls) { + expect(call[0]).toMatchObject({ eyeMpc: SGR_A_STAR_ANCHOR.positionMpc, faceSizePx: 256 }); + } + expect(skyCubemapFaceContextMock.mock.calls.map((c) => c[0].face).sort()).toEqual([ + ...ALL_FACES, + ]); + + expect(executeFrameMock).toHaveBeenCalledTimes(1); + const handedOff = executeFrameMock.mock.calls[0]![0].skyCubemapFaceContexts as Map< + CubeFace, + ReadyFrameContext + >; + expect(handedOff.size).toBe(6); + for (const face of ALL_FACES) expect(handedOff.get(face)).toBe(faceCtxByFace.get(face)); + }); + + it('omits a face from the hand-off map when skyCubemapFaceContext returns null', () => { + skyCubemapFaceContextMock.mockReturnValue(null); + const ctx = makeCtx(SGR_A_STAR_ANCHOR.positionMpc); + renderFrame(makeInput(ctx, makeState())); + + expect(skyCubemapFaceContextMock).toHaveBeenCalledTimes(6); + const handedOff = executeFrameMock.mock.calls[0]![0].skyCubemapFaceContexts as Map< + CubeFace, + ReadyFrameContext + >; + expect(handedOff.size).toBe(0); + }); + + it('never calls skyCubemapFaceContext while the lensing band is inactive', () => { + // Mpc-scale, orders of magnitude past the band's AU-scale goneAt edge. + const ctx = makeCtx([1000, 0, 0]); + renderFrame(makeInput(ctx, makeState())); + + expect(skyCubemapFaceContextMock).not.toHaveBeenCalled(); + const handedOff = executeFrameMock.mock.calls[0]![0].skyCubemapFaceContexts as Map< + CubeFace, + ReadyFrameContext + >; + expect(handedOff.size).toBe(0); + }); +}); From 13ee8d3bd52eec4863ee1deeeec70b0f312a5187 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 15:07:30 +0200 Subject: [PATCH 25/60] feat(lensing): sky-cubemap capture selects by opt-in flag, not target (Ruling 6) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The black-hole lens's sky-cubemap capture steps (Task 12) all target 'sky-cubemap', so target-matching could never select a draw group for them — no roster layer's own `target` is 'sky-cubemap'. Add `ContentLayer.skyCapture?: true` and have executeFrame's capture-step branch select its group by that flag instead of `target`, keeping the existing slab match unchanged. Zero-cost guarantee holds: no layer carries the flag yet (see the next commit's report), so a capture step's group is still empty and the step still draws nothing. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/ContentLayer.d.ts | 13 +++++ src/services/engine/frame/executeFrame.ts | 10 +++- src/services/engine/frame/frameProgram.ts | 17 ++++--- .../engine/frame/executeFrame.test.ts | 51 ++++++++++++++++++- 4 files changed, 82 insertions(+), 9 deletions(-) diff --git a/src/@types/engine/frame/ContentLayer.d.ts b/src/@types/engine/frame/ContentLayer.d.ts index b35530b43b..ed7373112b 100644 --- a/src/@types/engine/frame/ContentLayer.d.ts +++ b/src/@types/engine/frame/ContentLayer.d.ts @@ -57,6 +57,19 @@ export type ContentLayer = { * a target's mixed blends is the intended guardrail, not yet built. */ readonly blend: Blend; + /** + * Opt-in to the black-hole lens's sky-cubemap capture roster (Task 12/13, + * Ruling 6). A capture step (`FrameStep.face` present) selects its group by + * THIS flag instead of `target` — the six capture steps all target + * `'sky-cubemap'`, not this layer's own `target`, so target-matching can't + * select the roster at all (see `executeFrame`'s capture-step branch). + * `slab` still gates normally: a capture step only picks up flagged layers + * whose `slab` matches the step's own slab. Absent (the default) on every + * layer that isn't part of the captured sky content. `true`-only (never + * `false`) so a layer either carries the flag or doesn't — no + * three-state confusion with `undefined`. + */ + readonly skyCapture?: true; /** * Whether this layer should record draw commands this frame, given the * step's already-resolved `SlabView` — a `'body'` layer reads diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index d9e0274db0..2b3b497d17 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -221,9 +221,17 @@ export function executeFrame(args: ExecuteFrameArgs): void { // the view to read `view.slab.frame.bodyId`, and a step whose slab is // a body row still resolves cheaply even when its group ends up empty. const view = slabViewOf(stepCtx, step.slab); + // A capture step (Task 12's sky-cubemap sweep) selects its group by + // the `skyCapture` opt-in flag, not `target`: every capture step + // targets 'sky-cubemap', but the roster's own layers keep their + // ordinary `target` ('hdr', typically) for their NORMAL per-frame + // draw — target-matching could never select them for a capture step + // (Ruling 6, resolving Task 12's own recorded finding). `step.face` + // is the same discriminant `stepCtx` above already reads. + const isCaptureStep = step.face !== undefined; const group = layers.filter( (l) => - l.target === step.target && + (isCaptureStep ? l.skyCapture === true : l.target === step.target) && // A 'body' layer matches every body-slab step, not one fixed // index — Task 7 emits one such step per body row. `view.slab` is // in hand here, so this reads `frame.kind` directly rather than diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index f580515b11..ba50be7326 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -118,13 +118,16 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * Placed in the compute prelude's wake, ahead of every other render step, so * a same-frame lensing draw (Task 13) can sample a cubemap this frame * actually wrote. One step per requested face, at the NEAR0 slab — the - * majority of the fixed opt-in roster (star-points, star-catalog, - * star-aggregates) projects through NEAR0; `point-sprites` is COSMO-slab and - * is NOT yet reachable through this step (see the finding recorded in the - * Task 12 report — no `ContentLayer` row targets `'sky-cubemap'` today, so - * these steps presently select an empty group and draw nothing; they exist - * so the schedule, the timing-slot derivation, and the DebugPanel plumbing - * are ready for the roster wiring that follows). + * fixed opt-in roster (`ContentLayer.skyCapture`, Ruling 6) is selected by + * that flag rather than by `target` (see `executeFrame`'s capture-step + * branch), so a flagged NEAR0-slab layer is reachable here; a COSMO-slab + * candidate (`point-sprites`) would need its OWN COSMO-slab capture step, + * which this program does not emit — moot today, since Task 13's + * verification found every current roster candidate's GPU renderer assumes + * at most one `draw()` call per submitted frame (the `queue.writeBuffer`/ + * `submit` landmine, docs/RENDERER.md), an invariant a multi-face capture + * sweep breaks; no layer carries `skyCapture` yet, so these steps still + * select an empty group and draw nothing pending that renderer-side fix. */ export function frameProgram( tone: ToneMap, diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index 9f42ddac7f..29cc9ffd06 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -120,12 +120,16 @@ function makeLayer(init: { // `slab.frame.bodyId`) instead of the constant `enabled` flag above. enabledFor?: (view: SlabView) => boolean; log?: string[]; + // Ruling 6: opts this fixture layer into the sky-cubemap capture roster — + // see `ContentLayer.skyCapture`'s doc. + skyCapture?: true; }): SpyLayer { return { name: init.name, slab: init.slab ?? COSMO, target: init.target, blend: 'additive', + ...(init.skyCapture ? { skyCapture: true as const } : {}), enabled: vi.fn((_state, _ctx, view) => init.enabledFor ? init.enabledFor(view) : (init.enabled ?? true), ), @@ -748,7 +752,7 @@ describe('executeFrame', () => { // faces' synthetic cameras; identity (`toBe`), not content, is what proves // routing, since a real face ctx and the frame ctx share the same shape. it("resolves each capture step's own face ctx, never the frame-wide ctx", () => { - const layer = makeLayer({ name: 'probe', target: 'sky-cubemap', slab: NEAR0 }); + const layer = makeLayer({ name: 'probe', target: 'hdr', slab: NEAR0, skyCapture: true }); const face0Ctx = makeCtx(); const face1Ctx = makeCtx(); const program: FrameStep[] = [ @@ -798,5 +802,50 @@ describe('executeFrame', () => { executeFrame(args); expect(layer.draw.mock.calls[0]![2]).toBe(args.ctx); }); + + // Ruling 6: capture steps select by `skyCapture`, not `target` — the + // whole point being that a roster layer keeps its ordinary `target` + // ('hdr') for its normal per-frame draw and is ALSO reachable from a + // capture step via the flag alone. + it("selects a capture step group by the skyCapture flag, ignoring the layer's own target", () => { + const layer = makeLayer({ name: 'roster', target: 'hdr', slab: NEAR0, skyCapture: true }); + const program: FrameStep[] = [{ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 3 }]; + const faceCtx = makeCtx(); + const { args, env } = makeArgs({ + program, + layers: [layer], + skyCubemapFaceContexts: new Map([[3, faceCtx]]), + }); + executeFrame(args); + expect(layer.draw).toHaveBeenCalledTimes(1); + // The pass it drew into is the 'sky-cubemap' colour attachment, not + // 'hdr' — the step's target wins for the PASS, regardless of the + // layer's own `target` field (which only gated selection above). + expect(attachmentOfDraw(env, layer).view).toBe(SKY_CUBEMAP_VIEW); + }); + + it('never selects a capture step group by target alone — a layer targeting sky-cubemap without the flag is skipped', () => { + const layer = makeLayer({ name: 'unflagged', target: 'sky-cubemap', slab: NEAR0 }); + const program: FrameStep[] = [{ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }]; + const faceCtx = makeCtx(); + const { args } = makeArgs({ + program, + layers: [layer], + skyCubemapFaceContexts: new Map([[0, faceCtx]]), + }); + executeFrame(args); + expect(layer.draw).not.toHaveBeenCalled(); + }); + + it('a skyCapture-flagged layer is NOT drawn by its own ordinary (non-capture) render step under target-matching alone — slab/target still gate normally', () => { + // The flag only changes SELECTION for a capture step; an ordinary step + // still requires target-matching, so a flagged layer with a mismatched + // target is skipped exactly as before Ruling 6. + const layer = makeLayer({ name: 'roster', target: 'hdr', slab: NEAR0, skyCapture: true }); + const program: FrameStep[] = [{ kind: 'render', target: 'sky-cubemap', slab: NEAR0 }]; + const { args } = makeArgs({ program, layers: [layer] }); + executeFrame(args); + expect(layer.draw).not.toHaveBeenCalled(); + }); }); }); From 9e8de25304ce77f22209b4f3ebf978a1dee5b55d Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 15:07:52 +0200 Subject: [PATCH 26/60] =?UTF-8?q?feat(lensing):=20Sgr=20A*=20geodesic=20le?= =?UTF-8?q?ns=20pass=20=E2=80=94=20layer,=20renderer,=20and=20WESL=20shade?= =?UTF-8?q?r?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the sgr-a-star-lensing ContentLayer (Task 13): a 'body'-slab row drawing only on Sgr A*'s own body-m slab, gated on the fade band's alpha (Q6's zero-dispatch guarantee). The vertex stage builds a camera-facing billboard from the anchor's camera-relative position alone (the locked 144-byte uniform contract carries no camera basis or inverse-viewProj to unproject a screen ray from otherwise); the fragment classifies each ray as captured (black), escaping (a Task-9-LUT-deflected sample of the Task-11 sky cubemap), or crossing the accretion annulus (a bounded 48-step march with doppler + gravitational-shift + flicker modulation), composited premultiplied- OVER so a captured ray truly occludes the additive light behind it. Infinity encoding: the LUT's captured samples (b <= b_c) are replaced with a large finite sentinel before the r32float upload — raw IEEE Infinity round-trips through the texel exactly, but a fast-math shader compiler isn't guaranteed to preserve Infinity arithmetic (docs/RENDERER.md already tracks float edge-case flushing as a live landmine), so a threshold comparison well clear of both the sentinel and any real quadrature result is the robust encoding either way. Ground preparation this needed: RenderTargets.cubeViewOf (a dimension:'cube' view over a 6-layer row — viewOf's default 2d-array view can't bind as texture_cube) and lib/math.wesl's rotateAroundAxis (Rodrigues' formula, used for the deflection rotation and the disk plane's tilt/spin — no prior 3D-rotation primitive existed). Headless verification: `npm run perf -- --scenario galactic-centre` against this worktree's dev server reports an empty page-errors section (no Invalid ShaderModule/pipeline error) — the renderer's pipeline is constructed at engine bootstrap, so this catches a shader compile error even though the camera isn't in-band. Full npx vitest run and npm run typecheck are green. Known limitation (not this task's gate — Task 17's visual gate): frameProgram never emits an (hdr, BODY[k]) render step, only (foreground:0, BODY[k]) ones, so this layer is registered and its pipeline compiles but nothing currently invokes its draw(). Wiring that step is Task 14's job per its own forward reference in this layer's file-list. Co-Authored-By: Claude Fable 5 --- .../engine/handles/EngineGpuHandles.d.ts | 10 + src/@types/rendering/RenderTargets.d.ts | 10 + .../rendering/SgrAStarLensingRenderer.d.ts | 31 +++ src/services/engine/engine.ts | 4 + src/services/engine/frame/passes/index.ts | 17 ++ .../frame/passes/sgrAStarLensingLayer.ts | 119 +++++++++++ .../engine/gpuHandles/gpuHandleRegistry.ts | 6 + src/services/gpu/renderTargets.ts | 27 +++ .../bodies/sgrAStarLensingRenderer.ts | 195 ++++++++++++++++++ .../bodies/sgrAStarLensing/fragment.wesl | 184 +++++++++++++++++ .../bodies/sgrAStarLensing/vertex.wesl | 61 ++++++ src/services/gpu/shaders/lib/math.wesl | 19 ++ .../frame/passes/createUpsampleLayer.test.ts | 3 + .../engine/frame/passes/passes.test.ts | 28 ++- .../frame/passes/volumeUpsampleLayer.test.ts | 3 + .../initGpu.hdrCapabilityWiring.test.ts | 12 ++ tests/services/gpu/renderTargets.test.ts | 15 ++ tests/utils/gpu/hdrActiveOf.test.ts | 1 + 18 files changed, 735 insertions(+), 10 deletions(-) create mode 100644 src/@types/rendering/SgrAStarLensingRenderer.d.ts create mode 100644 src/services/engine/frame/passes/sgrAStarLensingLayer.ts create mode 100644 src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts create mode 100644 src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl create mode 100644 src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl diff --git a/src/@types/engine/handles/EngineGpuHandles.d.ts b/src/@types/engine/handles/EngineGpuHandles.d.ts index 9d4c73fa21..e6e5e1f510 100644 --- a/src/@types/engine/handles/EngineGpuHandles.d.ts +++ b/src/@types/engine/handles/EngineGpuHandles.d.ts @@ -49,6 +49,7 @@ import type { CloudShellRenderer } from '../../rendering/CloudShellRenderer'; import type { AtmosphereShellRenderer } from '../../rendering/AtmosphereShellRenderer'; import type { StarPointRenderer } from '../../rendering/StarPointRenderer'; import type { BodyGlintRenderer } from '../../rendering/BodyGlintRenderer'; +import type { SgrAStarLensingRenderer } from '../../rendering/SgrAStarLensingRenderer'; import type { StarCatalogRenderer } from '../../rendering/StarCatalogRenderer'; import type { StarCatalogPickRenderer } from '../../rendering/StarCatalogPickRenderer'; import type { BodyPickRenderer } from '../../rendering/BodyPickRenderer'; @@ -572,6 +573,15 @@ export type EngineGpuHandles = { * uniform buffers). */ bodyGlintRenderer: BodyGlintRenderer | null; + /** + * The Sgr A* lens pass (Task 13): a single billboard draw classifying + * capture/escape/annulus rays against the Task 9 LUT and the Task 11 sky + * cubemap, premultiplied-OVER into the depthless `hdr` target on Sgr A*'s + * own body-m slab row (`sgr-a-star-lensing` layer). Null until `initGpu` + * constructs it; excluded from `isEngineReady` and null-checked at use by + * `sgrAStarLensingLayer`. + */ + sgrAStarLensingRenderer: SgrAStarLensingRenderer | null; /** * The survey (Gaia bin) stars as additive point sprites into the depthless * HDR target — the wide-field twin of `starPointRenderer`, fed from an diff --git a/src/@types/rendering/RenderTargets.d.ts b/src/@types/rendering/RenderTargets.d.ts index 9aae2868d0..6dc701eeef 100644 --- a/src/@types/rendering/RenderTargets.d.ts +++ b/src/@types/rendering/RenderTargets.d.ts @@ -51,6 +51,16 @@ export type RenderTargets = { * the acquired frame view, not an allocated texture this owner holds. */ viewOf(id: string): GPUTextureView; + /** + * A `dimension: 'cube'` view over a row whose spec declares + * `fixedSizePx.layers === 6` (today, only `'sky-cubemap'`) — `viewOf`'s + * default view on a >1-layer texture is `2d-array`, which a + * `texture_cube` binding rejects, so a cube-sampling consumer (the Sgr A* + * lens fragment) needs this instead. Stable until the next `reconcile()` + * that changes this row's size, same guarantee as `viewOf`. Throws for a + * row with fewer than 6 layers, `swap`, and any unknown id. + */ + cubeViewOf(id: string): GPUTextureView; /** * Current depth-attachment view for a row whose spec declares `depth` * (`foreground:0`). Stable until the next `reconcile()` that changes this diff --git a/src/@types/rendering/SgrAStarLensingRenderer.d.ts b/src/@types/rendering/SgrAStarLensingRenderer.d.ts new file mode 100644 index 0000000000..2d0e1a2600 --- /dev/null +++ b/src/@types/rendering/SgrAStarLensingRenderer.d.ts @@ -0,0 +1,31 @@ +/** + * SgrAStarLensingRenderer — handle for the Sgr A* lens pass: a camera-facing + * billboard classifying each ray as captured (black), escaping (a + * LUT-deflected sample of the captured sky cubemap), or crossing the + * accretion annulus (bounded-march emission), composited premultiplied-OVER + * into the depthless `hdr` target. + * + * The LUT (Task 9's `SchwarzschildDeflectionLut`) is built once at + * construction and uploaded to a static `r32float` texture — `lut` is + * exposed back so the layer can read `minImpactParamRs`/`maxImpactParamRs`/ + * `samples.length` for the uniform pack without re-deriving them. + */ + +import type { Renderer } from './Renderer'; +import type { SchwarzschildDeflectionLut } from '../lensing/SchwarzschildDeflectionLut'; + +export type SgrAStarLensingRenderer = Renderer & { + /** The CPU-side LUT this renderer's texture was built from — see the module header. */ + readonly lut: SchwarzschildDeflectionLut; + /** + * Draw the lens billboard into the current (depthless, premultiplied-OVER) + * pass. `uniforms` is the packed 144-byte `SgrAStarLensingUniforms` + * (`packSgrAStarLensingUniforms`); `skyCubemapView` is this frame's + * `dimension: 'cube'` view over the `sky-cubemap` render target + * (`RenderTargets.cubeViewOf`) — read fresh by the caller every frame and + * rebound here rather than cached at construction, the same reason + * `additiveUpsample`'s bind group is rebuilt per draw (a cached bind group + * would risk binding a view a `reconcile()` already replaced). + */ + draw(pass: GPURenderPassEncoder, uniforms: Float32Array, skyCubemapView: GPUTextureView): void; +}; diff --git a/src/services/engine/engine.ts b/src/services/engine/engine.ts index 434eb1fcd0..4efd2a1abe 100644 --- a/src/services/engine/engine.ts +++ b/src/services/engine/engine.ts @@ -379,6 +379,10 @@ export function createEngine(canvas: HTMLCanvasElement, cb: EngineCallbacks): En // half of the body LOD, sibling of starPointRenderer. null until initGpu; // excluded from isEngineReady, null-checked at use by bodyGlintsLayer. bodyGlintRenderer: null, + // The Sgr A* lens pass — a single billboard draw on Sgr A*'s own + // body-m slab row. null until initGpu; excluded from isEngineReady, + // null-checked at use by sgrAStarLensingLayer. + sgrAStarLensingRenderer: null, starCatalogRenderer: null, starCatalogPickRenderer: null, // r32uint pick provider for the NEAR0 foreground bodies (Earth / planets / diff --git a/src/services/engine/frame/passes/index.ts b/src/services/engine/frame/passes/index.ts index 25dde16c73..18ff9ea6e8 100644 --- a/src/services/engine/frame/passes/index.ts +++ b/src/services/engine/frame/passes/index.ts @@ -58,6 +58,12 @@ * partition) as brightness-scaled additive points * (size x albedo x phase, cross-fading with the mesh * over 1-3 px), sibling of star-points (f64 rebase seam) + * 12c. sgr-a-star-lensing — the black-hole lens pass (Task 13): a `body`-slab + * row drawing ONLY on Sgr A*'s own row, PREMULTIPLIED + * OVER (not additive) into hdr — captured rays occlude + * the additive light already accumulated behind them; + * escaping rays sample the Task 11 sky-cubemap bent by + * the Task 9 LUT. Index provisional pending Task 14. * 13. star-aggregates — the survey (Gaia bin) AGGREGATE stream (interior * flux-mip glows), drawn LINEAR into the half-res * `star-aggregates` offscreen by its own render step @@ -234,6 +240,7 @@ import { constellationsLayer } from './constellationsLayer'; import { orbitTrailsLayer } from './orbitTrailsLayer'; import { foregroundLabelsLayer } from './foregroundLabelsLayer'; import { atmosphereShellLayer } from './atmosphereShellLayer'; +import { sgrAStarLensingLayer } from './sgrAStarLensingLayer'; /** * The flat content-layer registry, in deterministic draw order. HDR @@ -296,6 +303,15 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // star-points. Additive into HDR through NEAR0, so its position among the // additive rows is a listing choice, not a compositing one. bodyGlintsLayer, + // The Sgr A* lens pass (Task 13): a 'body'-slab row, listed here beside its + // nearest sibling in shape (body-glints, also a per-body-row hdr draw) — + // Task 14 owns its final index. Its blend is 'over' (Blend.d.ts), not + // additive like its neighbours in this run, so — unlike the additive rows + // around it — its position IS load-bearing once it draws at all: it must + // occlude/replace light already accumulated by the additive COSMO+NEAR0 + // steps, which frameProgram's own step order (independent of this array) + // already guarantees run first. + sgrAStarLensingLayer, // The survey (Gaia bin) stars split into two streams sharing one per-frame // walk: the AGGREGATE glow field draws LINEAR into the half-res // `star-aggregates` offscreen by its OWN render step (so its position here is @@ -408,6 +424,7 @@ export { texturedBodiesLayer } from './texturedBodiesLayer'; export { ringsLayer } from './ringsLayer'; export { starPointsLayer } from './starPointsLayer'; export { bodyGlintsLayer } from './bodyGlintsLayer'; +export { sgrAStarLensingLayer } from './sgrAStarLensingLayer'; export { starCatalogLayer } from './starCatalogLayer'; export { starAggregatesLayer } from './starAggregatesLayer'; export { starAggregateUpsampleLayer } from './starAggregateUpsampleLayer'; diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts new file mode 100644 index 0000000000..7c0a8db58c --- /dev/null +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -0,0 +1,119 @@ +/** + * sgrAStarLensingLayer — the Sgr A* lens pass's `ContentLayer` row. + * + * `slab: 'body'`: the frame program expands a `'body'` layer into one render + * step per body-m slab row, so `enabled`/`draw` are called once per body — + * narrowed here to Sgr A*'s own row (the anchor's `visibleSlabBodies` + * candidacy, same seam `planetsLayer` reads for a seeded planet). `blend: + * 'over'` (Porter-Duff, premultiplied) rather than the additive convention + * most `hdr` layers use: the black hole's captured disc must truly occlude + * the additive starlight already accumulated behind it, and per-pixel alpha + * lets the roster drawn earlier show through wherever deflection is + * negligible — `Blend.d.ts` enumerates `'over'` for any target, not just the + * swap-chain rows. + * + * No `drawPick`: Sgr A*'s existing pick stamp lives in `starPointsLayer` + * (see `ContentLayer.d.ts`'s own docblock) and is untouched by this layer. + */ + +import type { ContentLayer } from '../../../../@types/engine/frame/ContentLayer'; +import type { EngineState } from '../../../../@types/engine/state/EngineState'; +import type { ReadyFrameContext } from '../../../../@types/engine/frame/ReadyFrameContext'; +import type { Vec3 } from '../../../../@types/math/Vec3'; +import { BLACK_HOLES } from '../../../../data/blackHoles'; +import { SGR_A_STAR } from '../../../../data/bodies/sceneSgrAStar'; +import { SGR_A_STAR_MASS_SOLAR } from '../../../../data/bodies/sgrAStarMassSolar'; +import { schwarzschildRadiusM } from '../../../../utils/physics/schwarzschildRadiusM'; +import { packSgrAStarLensingUniforms } from '../../../../utils/gpu/packSgrAStarLensingUniforms'; +import { regionById } from '../../../../utils/scene/regionById'; +import { regionRelativeDistanceMpc } from '../../../../utils/scene/regionRelativeDistanceMpc'; +import { sceneBodyStates } from '../sceneBodyStates'; +import { fadeBand } from '../../../../utils/math/fadeBand'; +import { SCALE_FADE_BANDS } from '../../presentation/scaleFadeBands'; + +const GALACTIC_CENTRE_REGION = regionById('galactic-centre'); + +// One row today (Sgr A* only) — found once at module scope rather than +// re-scanned every frame, the same "hoist the constant lookup" convention +// `starPointsLayer`'s module-scope regions follow. `BLACK_HOLES` is authored +// data guaranteed to carry this row; a missing row is a wiring bug worth +// failing loudly on, not a silent no-op layer. +const BLACK_HOLE = BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id); +if (BLACK_HOLE === undefined) { + throw new Error(`sgrAStarLensingLayer: BLACK_HOLES carries no row for '${SGR_A_STAR.id}'`); +} + +const SCHWARZSCHILD_RADIUS_M = schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR); + +/** This frame's fade-band alpha (Q6's zero-dispatch gate) — shared by `enabled` and `draw`. */ +function bandAlphaFor(state: EngineState, ctx: ReadyFrameContext): number { + const distMpc = regionRelativeDistanceMpc( + ctx.drawCamPos, + GALACTIC_CENTRE_REGION, + sceneBodyStates(state, ctx), + ); + return fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc); +} + +export const sgrAStarLensingLayer: ContentLayer = { + name: 'sgr-a-star-lensing', + slab: 'body', + target: 'hdr', + blend: 'over', + + enabled(state, ctx, view) { + if (view.slab.frame.kind !== 'body-m' || view.slab.frame.bodyId !== SGR_A_STAR.id) { + return false; + } + if (state.gpu.sgrAStarLensingRenderer === null) return false; + return bandAlphaFor(state, ctx) > 0; + }, + + draw(pass, view, ctx, state) { + const renderer = state.gpu.sgrAStarLensingRenderer; + if (renderer === null || view.slab.frame.kind !== 'body-m') return; + if (view.slab.frame.bodyId !== SGR_A_STAR.id) return; + + // The SAME pose-provider closure `deriveSlabs` built this row's + // `view.slab.vp` from — see `planetsLayer`'s identical seam. + const pose = ctx.bodyPose(view.slab.frame.bodyId); + if (pose === null) return; + + const bandAlpha = bandAlphaFor(state, ctx); + if (bandAlpha <= 0) return; // "opacity 0 ⇒ no render" house rule + + // Sgr A*'s position relative to the camera, in the SAME body-local frame + // `view.slab.vp` was built in (camera at the origin) — the negation of + // `pose.eyeRelBodyM` (camera relative to the body). No separate + // rebaseViewProj step: unlike the NEAR0 layers, a body-m row's vp is + // already camera-centred (see `bodySlabRow`, slabs.ts). + const anchorPosRelCamM: Vec3 = [ + -pose.eyeRelBodyM[0], + -pose.eyeRelBodyM[1], + -pose.eyeRelBodyM[2], + ]; + + const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / BLACK_HOLE.emission.flickerTimescaleS; + + const uniforms = packSgrAStarLensingUniforms( + view.vp, + view.viewportPx, + SCHWARZSCHILD_RADIUS_M, + BLACK_HOLE.emission.innerRs, + BLACK_HOLE.emission.outerRs, + BLACK_HOLE.emission.inclinationRad, + BLACK_HOLE.emission.positionAngleRad, + BLACK_HOLE.emission.flickerAmp, + BLACK_HOLE.emission.flickerTimescaleS, + flickerPhase, + renderer.lut.minImpactParamRs, + renderer.lut.maxImpactParamRs, + renderer.lut.samples.length, + bandAlpha, + anchorPosRelCamM, + ); + + const skyCubemapView = ctx.renderTargets.cubeViewOf('sky-cubemap'); + renderer.draw(pass, uniforms, skyCubemapView); + }, +}; diff --git a/src/services/engine/gpuHandles/gpuHandleRegistry.ts b/src/services/engine/gpuHandles/gpuHandleRegistry.ts index 88879ad09e..aad2790e10 100644 --- a/src/services/engine/gpuHandles/gpuHandleRegistry.ts +++ b/src/services/engine/gpuHandles/gpuHandleRegistry.ts @@ -44,6 +44,7 @@ import { createStarRenderer } from '../../gpu/renderers/bodies/starRenderer'; import { createPlanetRenderer } from '../../gpu/renderers/bodies/planetRenderer'; import { createStarPointRenderer } from '../../gpu/renderers/bodies/starPointRenderer'; import { createBodyGlintRenderer } from '../../gpu/renderers/bodies/bodyGlintRenderer'; +import { createSgrAStarLensingRenderer } from '../../gpu/renderers/bodies/sgrAStarLensingRenderer'; import { createStarCatalogRenderer } from '../../gpu/renderers/starCatalog/starCatalogRenderer'; import { createStarCatalogPickRenderer } from '../../gpu/renderers/starCatalog/starCatalogPickRenderer'; import { createBodyPickRenderer } from '../../gpu/renderers/bodies/bodyPickRenderer'; @@ -363,6 +364,11 @@ export const GPU_HANDLE_ROWS = [ construct: (_state: EngineState, deps: GpuHandleConstructDeps) => createBodyGlintRenderer(deps.ctx.device, HDR_TARGET_FORMAT), }, + { + key: 'sgrAStarLensingRenderer', + construct: (_state: EngineState, deps: GpuHandleConstructDeps) => + createSgrAStarLensingRenderer(deps.ctx.device, HDR_TARGET_FORMAT), + }, { key: 'starCatalogRenderer', construct: (_state: EngineState, deps: GpuHandleConstructDeps) => diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index d00cfbce54..f07e931d7e 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -300,6 +300,12 @@ export function createRenderTargets( // depth attachment", which is exactly what `depthViewOf` throws on. const textures = new Map(); const views = new Map(); + // A dimension:'cube' view alongside `views`' default (2d-array) one, for the + // one row whose 6 layers are later sampled as a `texture_cube` (see + // `RenderTargets.cubeViewOf`'s doc). Keyed off `fixedSizePx.layers === 6` + // (data-driven, not a hardcoded 'sky-cubemap' id check) so a future second + // 6-layer row gets one for free. + const cubeViews = new Map(); const depthTextures = new Map(); const depthViews = new Map(); // Recorded beside `textures`/`views` so `sizeOf` never reads a texture's @@ -329,6 +335,17 @@ export function createRenderTargets( }); textures.set(spec.id, texture); views.set(spec.id, texture.createView()); + if (spec.fixedSizePx?.layers === 6) { + cubeViews.set( + spec.id, + texture.createView({ + label: `render-target-${spec.id}-cube-view`, + dimension: 'cube', + baseArrayLayer: 0, + arrayLayerCount: 6, + }), + ); + } if (spec.depth) { depthTextures.get(spec.id)?.destroy(); @@ -406,6 +423,15 @@ export function createRenderTargets( } return view; }, + cubeViewOf(id: string): GPUTextureView { + const view = cubeViews.get(id); + if (!view) { + // Covers a row with < 6 layers, 'swap', unknown ids, and + // use-after-destroy — same loud-failure discipline as `viewOf`. + throw new Error(`renderTargets: no cube view for target '${id}'`); + } + return view; + }, depthViewOf(id: string): GPUTextureView { const view = depthViews.get(id); if (!view) { @@ -425,6 +451,7 @@ export function createRenderTargets( for (const texture of depthTextures.values()) texture.destroy(); textures.clear(); views.clear(); + cubeViews.clear(); depthTextures.clear(); depthViews.clear(); sizes.clear(); diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts new file mode 100644 index 0000000000..773504cdea --- /dev/null +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -0,0 +1,195 @@ +/** + * sgrAStarLensingRenderer — the Sgr A* lens pass: one billboard draw per + * frame classifying capture/escape/annulus rays against the Task 9 LUT and + * the Task 11 sky cubemap. Structural precedent: `bodyGlintRenderer.ts` (a + * small single-draw body renderer, explicit non-'auto' bind group layout, + * `label:` on every resource). + * + * ### The LUT texture — `Infinity` encoding (Task 13's brief, decided here) + * + * `buildSchwarzschildDeflectionLut`'s captured samples are IEEE `Infinity`. + * That round-trips through an `r32float` texel's raw bits exactly, but a + * fast-math shader compiler is not guaranteed to preserve Infinity + * arithmetic (this codebase already treats float edge-case flushing as a + * live landmine — see the renderer landmines). Rather than ship raw + * Infinity through the upload and rely on GPU-side comparisons behaving, + * this helper replaces every `Infinity` sample with `CAPTURE_SENTINEL_RAD` + * — a large finite value comfortably separated from any real (finite) + * quadrature result — before `writeTexture`. The fragment's + * `CAPTURE_THRESHOLD_RAD` (half the sentinel) is the GPU-side counterpart; + * the two constants don't need to agree exactly, only that the threshold + * sits between the largest real bend angle and the sentinel. + * + * ### Why a `texture_2d` of height 1, not `texture_1d` + * + * docs/RENDERER.md's iOS/WebKit landmine: `textureSampleLevel` has no 1D + * overload, and WebKit rejects `texture_1d` sampling Chrome accepts. Every + * 1D LUT in this codebase is an N×1 `texture_2d` instead — this one follows + * the same convention. + */ + +import type { Renderer } from '../../../../@types/rendering/Renderer'; +import type { SgrAStarLensingRenderer } from '../../../../@types/rendering/SgrAStarLensingRenderer'; +import type { SchwarzschildDeflectionLut } from '../../../../@types/lensing/SchwarzschildDeflectionLut'; +import vsCode from '../../shaders/bodies/sgrAStarLensing/vertex.wesl?static'; +import fsCode from '../../shaders/bodies/sgrAStarLensing/fragment.wesl?static'; +import { createShaderModuleWithDevLog } from '../../shaderCompileLogger'; +import { PREMULTIPLIED_OVER_BLEND } from '../../lib/blendStates'; +import { buildSchwarzschildDeflectionLut } from '../../../../utils/lensing/buildSchwarzschildDeflectionLut'; + +/** + * LUT texel count: dense enough that the fragment's 2-tap lerp reads as + * smooth across the escape region without the strong near-critical + * curvature aliasing (Simpson quadrature is cheap CPU-side and this runs + * once at construction, so there is no reason to skimp). + */ +export const LUT_SAMPLE_COUNT = 512; + +/** + * Stand-in for a captured LUT sample once uploaded to the `r32float` + * texture — see the module header's "Infinity encoding" section. Comfortably + * larger than any finite bend angle `buildSchwarzschildDeflectionLut` can + * produce (the quadrature stays a low-two-digit-radian value even one grid + * step from the critical impact parameter) and comfortably smaller than + * `f32`'s own range, so the value survives the GPU upload with no risk of + * becoming `inf` itself. + */ +export const CAPTURE_SENTINEL_RAD = 1000; + +function createLutTexture(device: GPUDevice, lut: SchwarzschildDeflectionLut): GPUTexture { + const texture = device.createTexture({ + label: 'sgr-a-star-lensing-lut-texture', + format: 'r32float', + dimension: '2d', + size: { width: lut.samples.length, height: 1 }, + usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST, + }); + // Infinity -> CAPTURE_SENTINEL_RAD, everything else passes through + // unchanged — see the module header. + const uploadable = new Float32Array(lut.samples.length); + for (let i = 0; i < lut.samples.length; i++) { + const sample = lut.samples[i]!; + uploadable[i] = Number.isFinite(sample) ? sample : CAPTURE_SENTINEL_RAD; + } + // No 256-byte bytesPerRow alignment requirement here — that constraint is + // copyBufferToTexture/copyTextureToBuffer only; queue.writeTexture is exempt. + device.queue.writeTexture( + { texture }, + uploadable, + { bytesPerRow: lut.samples.length * 4 }, + { width: lut.samples.length, height: 1 }, + ); + return texture; +} + +export function createSgrAStarLensingRenderer( + device: GPUDevice, + targetFormat: GPUTextureFormat, +): SgrAStarLensingRenderer { + const lut = buildSchwarzschildDeflectionLut(LUT_SAMPLE_COUNT); + const lutTexture = createLutTexture(device, lut); + const lutView = lutTexture.createView({ label: 'sgr-a-star-lensing-lut-view' }); + + // ── Uniform buffer (144 bytes, byte-exact with SgrAStarLensingUniforms) ── + const uniformBuffer = device.createBuffer({ + label: 'sgr-a-star-lensing-uniform-buffer', + size: 144, + usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, + }); + + const skySampler = device.createSampler({ + label: 'sgr-a-star-lensing-sky-sampler', + magFilter: 'linear', + minFilter: 'linear', + }); + + // ── Bind group layout (explicit, not 'auto') ────────────────────────────── + const bindGroupLayout = device.createBindGroupLayout({ + label: 'sgr-a-star-lensing-bgl', + entries: [ + { + binding: 0, + visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, + buffer: { type: 'uniform' }, + }, + { + // r32float is not sampler-filterable by default — 'unfilterable-float' + // matches the fragment's textureLoad-only access (see the module header). + binding: 1, + visibility: GPUShaderStage.FRAGMENT, + texture: { sampleType: 'unfilterable-float' }, + }, + { + binding: 2, + visibility: GPUShaderStage.FRAGMENT, + texture: { sampleType: 'float', viewDimension: 'cube' }, + }, + { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } }, + ], + }); + + const vsModule = createShaderModuleWithDevLog(device, vsCode, 'sgrAStarLensing.vertex'); + const fsModule = createShaderModuleWithDevLog(device, fsCode, 'sgrAStarLensing.fragment'); + + const pipeline = device.createRenderPipeline({ + label: 'sgr-a-star-lensing-pipeline', + layout: device.createPipelineLayout({ + label: 'sgr-a-star-lensing-pipeline-layout', + bindGroupLayouts: [bindGroupLayout], + }), + vertex: { module: vsModule, entryPoint: 'vs' }, + fragment: { + module: fsModule, + entryPoint: 'fs', + targets: [{ format: targetFormat, blend: PREMULTIPLIED_OVER_BLEND }], + }, + primitive: { topology: 'triangle-list' }, + // NO depthStencil: the hdr target has no depth attachment. + }); + + function draw( + pass: GPURenderPassEncoder, + uniforms: Float32Array, + skyCubemapView: GPUTextureView, + ): void { + device.queue.writeBuffer(uniformBuffer, 0, uniforms); + + // Rebuilt every draw because `skyCubemapView` is the caller's fresh + // per-frame read of `RenderTargets.cubeViewOf` — the SAME reason + // `additiveUpsample`'s bind group is rebuilt per draw rather than cached + // (a cached bind group risks binding a view a `reconcile()` replaced). + // The LUT view and sampler are stable renderer-owned resources; rebuilding + // the whole group anyway keeps this one call site simple, and one + // bind-group alloc per frame for a single-draw pass is negligible. + const bindGroup = device.createBindGroup({ + label: 'sgr-a-star-lensing-bg', + layout: bindGroupLayout, + entries: [ + { binding: 0, resource: { buffer: uniformBuffer } }, + { binding: 1, resource: lutView }, + { binding: 2, resource: skyCubemapView }, + { binding: 3, resource: skySampler }, + ], + }); + + pass.setPipeline(pipeline); + pass.setBindGroup(0, bindGroup); + // Six vertices, one billboard quad — the vertex stage maps + // vertex_index 0..5 through lib/billboard's quadCorner. + pass.draw(6); + } + + function destroy(): void { + lutTexture.destroy(); + uniformBuffer.destroy(); + } + + const renderer: SgrAStarLensingRenderer = { + label: 'sgrAStarLensingRenderer', + lut, + draw, + destroy, + }; + renderer satisfies Renderer; + return renderer; +} diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl new file mode 100644 index 0000000000..6779349838 --- /dev/null +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -0,0 +1,184 @@ +// bodies/sgrAStarLensing/fragment.wesl — Schwarzschild ray classification: +// capture (black), escape (LUT-deflected sky-cubemap sample), or annulus +// (bounded emission march), composited over the escape/capture base. +// +// 'Infinity' encoding (Task 9's 'SchwarzschildDeflectionLut.samples', decided +// here per Task 13's brief): the renderer's texture-upload helper +// ('sgrAStarLensingRenderer.ts') replaces every 'Infinity' sample with a +// large finite sentinel before uploading to the r32float texture — raw IEEE +// Infinity round-trips through an r32float texel exactly, but a fast-math +// shader compiler is not guaranteed to preserve Infinity arithmetic +// (this codebase already treats float edge-case flushing as a live +// landmine), so a threshold comparison well below the sentinel and well +// above any real quadrature result is the robust encoding either way — see +// 'CAPTURE_THRESHOLD_RAD' below. +// +// The captured/escape split happens IN THE LUT sample itself (samples with +// impact parameter at or below the photon-sphere bound are Infinity, hence +// sentinel, by construction — see buildSchwarzschildDeflectionLut.ts), so +// 'captured' here means 'the sampled bend angle is the sentinel', not a +// separate geometric test. + +import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; +import package::lib::math::rotateAroundAxis; +import package::lib::math::saturate; +import package::lib::math::TAU; + +@group(0) @binding(0) var u: SgrAStarLensingUniforms; +@group(0) @binding(1) var lutTex: texture_2d; +@group(0) @binding(2) var skyTex: texture_cube; +@group(0) @binding(3) var skySampler: sampler; + +struct FsIn { + @location(0) posRelCamM: vec3, +}; + +// Half of the renderer's CPU-side sentinel (see the module header) — the two +// sides don't need to agree on an exact value, only that this sits well +// below the sentinel and well above any real (finite) quadrature result, +// which stays a low-two-digit-radian value even one grid step from the +// critical impact parameter (see buildSchwarzschildDeflectionLut.ts's +// Simpson integration). +const CAPTURE_THRESHOLD_RAD: f32 = 500.0; + +const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound +const DISK_HALF_THICKNESS_RS: f32 = 0.15; // thin-disk approximation, tuned for looks +const DOPPLER_STRENGTH: f32 = 0.6; // tuned for looks — see BLACK_HOLES's own "visual taste" note + +// Two-tap manual lerp over the LUT (an r32float texture is not +// sampler-filterable without the optional 'float32-filterable' feature, so +// this uses textureLoad, not textureSample — see the WebKit texture_1d note +// in docs/RENDERER.md, the reason the LUT is a texture_2d of height 1 +// rather than a texture_1d in the first place). Either tap reading the +// sentinel propagates it through unblended, so a lerp never averages a real +// angle with the capture sentinel into a bogus finite value. +fn sampleLut(impactParamRs: f32) -> f32 { + let span = max(u.lutMaxImpactParamRs - u.lutMinImpactParamRs, 1e-6); + let t = saturate((impactParamRs - u.lutMinImpactParamRs) / span); + let lastIndex = u.lutSampleCount - 1.0; + let fIdx = t * lastIndex; + let i0 = i32(floor(fIdx)); + let i1 = min(i0 + 1, i32(lastIndex)); + let a0 = textureLoad(lutTex, vec2(i0, 0), 0).r; + let a1 = textureLoad(lutTex, vec2(i1, 0), 0).r; + if (a0 >= CAPTURE_THRESHOLD_RAD || a1 >= CAPTURE_THRESHOLD_RAD) { + return CAPTURE_THRESHOLD_RAD; + } + return mix(a0, a1, fract(fIdx)); +} + +// Disk-plane normal from (inclination, positionAngle): tilt a fixed world-+Y +// reference about world +X, then spin the tilted normal's azimuth about +// world +Y. Deliberately NOT the Galactic-Centre sky frame 'sStar.ts' orients +// S-star orbits against — that frame's RA/Dec basis has no field in this +// uniform's locked 144 bytes, and 'BLACK_HOLES''s own doc already calls +// inclination/positionAngle "visual taste" rather than fit to observations — +// so a fixed world reference is a documented simplification, not a silent +// mismatch with the S-star orbits' frame. +fn diskNormal() -> vec3 { + let tilted = rotateAroundAxis(vec3(0.0, 1.0, 0.0), vec3(1.0, 0.0, 0.0), u.inclinationRad); + return normalize(rotateAroundAxis(tilted, vec3(0.0, 1.0, 0.0), u.positionAngleRad)); +} + +// Bounded march along the UNDEFLECTED ray (spec's 32-64-step bound) for the +// accretion annulus's own emission, composited over the escape/capture base +// the caller already resolved. Returns (premultiplied-ish linear emission, +// coverage) — coverage feeds the caller's alpha, not the light itself. +fn annulusEmission(rayDir: vec3, toAnchor: vec3) -> vec4 { + let normal = diskNormal(); + let marchMaxM = u.outerRs * u.schwarzschildRadiusM * 3.0; + let stepLenM = marchMaxM / f32(MARCH_STEPS); + let halfThicknessM = DISK_HALF_THICKNESS_RS * u.schwarzschildRadiusM; + + var emission = vec3(0.0); + var coverage = 0.0; + for (var i = 0; i < MARCH_STEPS; i++) { + let t = (f32(i) + 0.5) * stepLenM; + let p = rayDir * t - toAnchor; // position relative to the hole's centre + let distToPlane = dot(p, normal); + if (abs(distToPlane) > halfThicknessM) { + continue; + } + let inPlane = p - normal * distToPlane; + let radialM = length(inPlane); + let radialRs = radialM / u.schwarzschildRadiusM; + if (radialRs < u.innerRs || radialRs > u.outerRs) { + continue; + } + + let radialDir = inPlane / max(radialM, 1e-6); + let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point + let dopplerFactor = 1.0 + DOPPLER_STRENGTH * dot(orbitDir, -rayDir); + // Kepler orbital period ~ r^1.5: a cheap differential-rotation phase + // offset per radius (closer annuli lead the outer ones), not a fitted + // light curve — visual taste, as above. + let periodScale = pow(max(radialRs, 0.1), 1.5); + let localPhase = u.flickerPhase + (radialRs / periodScale) * TAU; + let flicker = 1.0 + u.flickerAmp * sin(localPhase); + let redshift = 1.0 / sqrt(max(1.0 - 1.0 / radialRs, 0.05)); + let heat = saturate(1.0 - (radialRs - u.innerRs) / max(u.outerRs - u.innerRs, 1e-6)); + let tint = mix(vec3(1.0, 0.45, 0.15), vec3(1.0, 0.85, 0.65), heat); + let falloff = 1.0 / max(radialRs * radialRs, 1.0); + + let contribution = falloff * flicker * dopplerFactor * redshift * (stepLenM / u.schwarzschildRadiusM); + emission += tint * contribution; + coverage = max(coverage, saturate(contribution)); + } + return vec4(emission, coverage); +} + +@fragment +fn fs(in: FsIn) -> @location(0) vec4 { + let rayDir = normalize(in.posRelCamM); + let toAnchor = u.anchorPosRelCamM; + // Perpendicular distance from the hole's centre to the ray through the + // origin (the camera) — the impact parameter. Clamped to the ray's + // forward half: the billboard is centred on the anchor and faces the + // camera, so a negative closestT is unreachable in practice, but the + // clamp keeps the geometry well-defined if float error ever puts a + // corner fragment just behind the plane's own centre. + let closestT = max(dot(toAnchor, rayDir), 0.0); + let offsetVec = toAnchor - rayDir * closestT; + let impactParamM = length(offsetVec); + let impactParamRs = impactParamM / u.schwarzschildRadiusM; + + var color = vec3(0.0); + var alpha = 0.0; + + if (impactParamRs < u.lutMinImpactParamRs) { + // Below the LUT's own sampled domain — deep inside the capture region + // the LUT never samples a finite value for. + alpha = u.bandAlpha; + } else { + let bendAngle = sampleLut(impactParamRs); + if (bendAngle >= CAPTURE_THRESHOLD_RAD) { + alpha = u.bandAlpha; + } else { + // Gravitational lensing displaces the apparent background AWAY from + // the lens centre (the Einstein-ring displacement) — rotate the + // straight-line ray away from the hole by the LUT's bend angle to + // recover the asymptotic sky direction this photon actually left + // from. Sign/axis convention: verify visually at the Task 17 gate + // (the known LUT approximation the brief accepts); flip the sign here + // if the ring reads backward. + let axis = normalize(cross(rayDir, toAnchor)); + let deflected = normalize(rotateAroundAxis(rayDir, axis, -bendAngle)); + color = textureSampleLevel(skyTex, skySampler, deflected, 0.0).rgb; + + // Soft edge fade toward the billboard's rim so the roster drawn + // earlier still shows through once deflection is negligible — 'over' + // blend, per-pixel alpha does the rest (see ContentLayer.d.ts's note + // on this row's blend). + let edgeFade = 1.0 - smoothstep(u.lutMaxImpactParamRs * 0.7, u.lutMaxImpactParamRs, impactParamRs); + alpha = u.bandAlpha * edgeFade; + } + + let annulus = annulusEmission(rayDir, toAnchor); + color += annulus.rgb; + alpha = max(alpha, u.bandAlpha * annulus.a); + } + + // Premultiplied — this row's blend is PREMULTIPLIED_OVER (Blend.d.ts's + // 'over'), so the fragment multiplies its own colour by coverage. + return vec4(color * alpha, alpha); +} diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl new file mode 100644 index 0000000000..cf1432db60 --- /dev/null +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl @@ -0,0 +1,61 @@ +// bodies/sgrAStarLensing/vertex.wesl — camera-facing billboard covering +// Sgr A*'s visible lensing halo. +// +// Not a literal fullscreen triangle: the locked 144-byte +// 'SgrAStarLensingUniforms' (Task 10) carries no inverse-viewProj and no +// camera-right/up basis, so there is no way to unproject a screen uv into a +// world ray the way 'atmosphere/shell/fragment.wesl''s 'insideRayDir' does. +// A world-space billboard sidesteps that: each fragment's +// perspective-interpolated position on the flat quad IS the exact point +// where the camera ray through that pixel crosses the plane, so the +// fragment recovers its own ray direction by normalizing the interpolated +// position — no inverse matrix needed. The quad's basis is built from +// 'anchorPosRelCamM' alone (a look-at billboard, no separate camera basis +// input either) — see 'vs' below. + +import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; +import package::lib::camera::worldToClip; +import package::lib::billboard::quadCorner; + +@group(0) @binding(0) var u: SgrAStarLensingUniforms; + +// Billboard half-size, as a multiple of the LUT's own max sampled impact +// parameter ('u.lutMaxImpactParamRs') — generous margin so the +// escape/annulus classification never runs off the quad's rasterized edge +// under normal (non-2-r_s-floor) viewing. The fragment's own edge fade reads +// 'u.lutMaxImpactParamRs' directly, so this margin and that fade can't drift +// apart into a visible seam. +const BILLBOARD_MARGIN: f32 = 1.5; + +struct VsOut { + @builtin(position) clip: vec4, + // Camera-relative world position of this point on the billboard PLANE, + // perspective-interpolated across the quad — not yet normalized; the + // fragment renormalizes after interpolation (interpolating a direction + // linearly and normalizing afterward is the house rule after any + // matrix/interpolation transform). + @location(0) posRelCamM: vec3, +}; + +@vertex +fn vs(@builtin(vertex_index) vi: u32) -> VsOut { + let toAnchor = u.anchorPosRelCamM; + let anchorDistM = length(toAnchor); + // Look-at billboard basis from the anchor direction alone (no separate + // camera-right/up uniform — see the module header). Degenerate only when + // the anchor sits exactly along world +Y, unreachable while the camera is + // actually looking toward the black hole (this layer's 'enabled' gate). + let forward = toAnchor / max(anchorDistM, 1e-6); + let worldUp = vec3(0.0, 1.0, 0.0); + let right = normalize(cross(worldUp, forward)); + let up = cross(forward, right); + + let worldRadiusM = u.schwarzschildRadiusM * u.lutMaxImpactParamRs * BILLBOARD_MARGIN; + let corner = quadCorner(vi); + let posRelCamM = toAnchor + right * (corner.x * worldRadiusM) + up * (corner.y * worldRadiusM); + + var out: VsOut; + out.clip = worldToClip(u.cam, posRelCamM); + out.posRelCamM = posRelCamM; + return out; +} diff --git a/src/services/gpu/shaders/lib/math.wesl b/src/services/gpu/shaders/lib/math.wesl index ee8d9fd0c5..8abc30d4f9 100644 --- a/src/services/gpu/shaders/lib/math.wesl +++ b/src/services/gpu/shaders/lib/math.wesl @@ -120,3 +120,22 @@ fn toPolar(p: vec2) -> vec2 { fn toRect(p: vec2) -> vec2 { return p.x * vec2(cos(p.y), sin(p.y)); } + +// ── rotateAroundAxis ───────────────────────────────────────────────── +// +// Rodrigues' rotation formula: rotate 'v' by 'angleRad' about 'axis' +// (right-hand rule). First consumer: the Sgr A* lens fragment +// (bodies/sgrAStarLensing/fragment.wesl), which has no camera-basis +// uniform to build a billboard/deflection frame from and derives both +// from a single direction vector instead — a general enough primitive +// to live beside 'rot2' rather than inline in that one shader. +// +// 'axis' MUST already be a unit vector — the formula silently returns a +// scaled/skewed result for a non-unit axis rather than erroring, so +// every call site normalizes its own axis before calling this. + +fn rotateAroundAxis(v: vec3, axis: vec3, angleRad: f32) -> vec3 { + let c = cos(angleRad); + let s = sin(angleRad); + return v * c + cross(axis, v) * s + axis * dot(axis, v) * (1.0 - c); +} diff --git a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts index 16001222ef..0b94fe0676 100644 --- a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts @@ -66,6 +66,9 @@ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFra }, sizeOf: vi.fn(), viewOf: (id: string) => (id === 'test-target' ? offscreenView : ({} as GPUTextureView)), + cubeViewOf: (id: string): GPUTextureView => { + throw new Error(`fixture renderTargets: no cube view for '${id}'`); + }, depthViewOf: (id: string): GPUTextureView => { throw new Error(`fixture renderTargets: no depth view for '${id}'`); }, diff --git a/tests/services/engine/frame/passes/passes.test.ts b/tests/services/engine/frame/passes/passes.test.ts index 9534a096e5..73d35c963e 100644 --- a/tests/services/engine/frame/passes/passes.test.ts +++ b/tests/services/engine/frame/passes/passes.test.ts @@ -29,6 +29,7 @@ import { starCatalogLayer, starAggregatesLayer, starAggregateUpsampleLayer, + sgrAStarLensingLayer, foregroundLabelsLayer, near0SelectionRingLayer, clipPathDebugLayer, @@ -393,12 +394,17 @@ describe('CONTENT_LAYERS blend legality', () => { // it's a correctness bug, not a new legal combination. expect(layer.blend).toBe('additive'); } else if (layer.target === 'hdr') { - // hdr admits exactly one multiplicative row: the Milky Way dust pass - // extincts the emission already accumulated in HDR rather than adding - // to it, which is why its position in the near-hdr group is - // load-bearing. A second multiplicative hdr row should fail this test - // and be a deliberate decision. - expect(layer.blend).toBe(layer === milkyWayLayer ? 'multiply' : 'additive'); + // hdr admits two exceptions to its additive default: the Milky Way + // dust pass extincts the emission already accumulated (its position + // in the near-hdr group is load-bearing for that), and the Sgr A* + // lens pass composites premultiplied-OVER so a captured ray truly + // occludes the additive light behind it instead of adding to it + // (Blend.d.ts's own doc names 'over' legal for any target, not just + // the swap-chain rows). A third non-additive hdr row should fail + // this test and be a deliberate decision. + const expected = + layer === milkyWayLayer ? 'multiply' : layer === sgrAStarLensingLayer ? 'over' : 'additive'; + expect(layer.blend).toBe(expected); } else if (layer.target === 'foreground:0') { // The `foreground:0` group is opaque bodies EXCEPT the three translucent // overlays — the ring, Earth's cloud shell, and Earth's in-scatter @@ -438,14 +444,16 @@ describe('CONTENT_LAYERS blend legality', () => { ); } } - // Ten layers blend OVER: the four COSMO swap overlays, the three (swap, + // Eleven layers blend OVER: the four COSMO swap overlays, the three (swap, // NEAR0) overlays (the near0 star selection ring, foreground-labels, and the // clip-path inspector route — moved here from the COSMO swap group so a // near-field clip's parsec-scale route is not clipped by the cosmological - // near plane), and the three translucent foreground members — the ring, + // near plane), the three translucent foreground members — the ring, // Earth's cloud shell, and Earth's in-scatter atmosphere (the three OVER - // members of the otherwise-opaque foreground group). - expect(CONTENT_LAYERS.filter((layer) => layer.blend === 'over')).toHaveLength(10); + // members of the otherwise-opaque foreground group) — and the Sgr A* lens + // pass, the one 'body'-slab, 'hdr'-target OVER row (see the hdr branch + // above). + expect(CONTENT_LAYERS.filter((layer) => layer.blend === 'over')).toHaveLength(11); }); }); diff --git a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts index 5e9902e4b3..fc940ac7f5 100644 --- a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts @@ -68,6 +68,9 @@ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFra }, sizeOf: vi.fn(), viewOf: (id: string) => (id === 'volume' ? offscreenView : ({} as GPUTextureView)), + cubeViewOf: (id: string): GPUTextureView => { + throw new Error(`fixture renderTargets: no cube view for '${id}'`); + }, // No row in this fixture declares depth, and the upsample layer never // asks for a depth view — throwing mirrors the real table's behaviour // for depthless rows. diff --git a/tests/services/engine/phases/initGpu.hdrCapabilityWiring.test.ts b/tests/services/engine/phases/initGpu.hdrCapabilityWiring.test.ts index af15bf2ce1..215ef5ee42 100644 --- a/tests/services/engine/phases/initGpu.hdrCapabilityWiring.test.ts +++ b/tests/services/engine/phases/initGpu.hdrCapabilityWiring.test.ts @@ -289,6 +289,18 @@ vi.mock( createBodyGlintRenderer: vi.fn(() => makeStub('bodyGlintRenderer')), }), ); +// The Sgr A* lens renderer's constructor builds a real LUT texture +// (createTexture + writeTexture), which the plain stub device above doesn't +// support — mock the factory like every other renderer here. +vi.mock( + '../../../../src/services/gpu/renderers/bodies/sgrAStarLensingRenderer', + async (importOriginal) => ({ + ...(await importOriginal< + typeof import('../../../../src/services/gpu/renderers/bodies/sgrAStarLensingRenderer') + >()), + createSgrAStarLensingRenderer: vi.fn(() => makeStub('sgrAStarLensingRenderer')), + }), +); // The survey star-catalog renderer's constructor uses the full device API // (limits + createBuffer + bind groups + pipeline), so a `limits` patch on // the plain stub device wouldn't survive the next line — mock the factory diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index e8cfb44b6f..68a6fc71d8 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -136,6 +136,21 @@ describe('createRenderTargets', () => { expect(desc.dimension).toBe('2d'); }); + it('cubeViewOf returns a dimension:cube view for a 6-layer row and throws for a non-cube row', () => { + const device = mockDevice(); + const targets = createRenderTargets( + device, + SWAP_FORMAT, + { width: 800, height: 600 }, + stateWithDivisor(MW_DIVISOR), + [FIXED_SIZE_ROW], + ); + expect(targets.cubeViewOf('test:cubemap')).toBeDefined(); + // 'hdr' has no fixedSizePx (a single layer), so it gets no cube view. + expect(() => targets.cubeViewOf('hdr')).toThrow(); + expect(() => targets.cubeViewOf('nope')).toThrow(); + }); + it('reconcile does not reallocate a fixedSizePx row when the canvas resizes', () => { const device = mockDevice(); const create = device.createTexture as ReturnType; diff --git a/tests/utils/gpu/hdrActiveOf.test.ts b/tests/utils/gpu/hdrActiveOf.test.ts index 2cc6c19c8d..e33918b30c 100644 --- a/tests/utils/gpu/hdrActiveOf.test.ts +++ b/tests/utils/gpu/hdrActiveOf.test.ts @@ -16,6 +16,7 @@ function makeStub(specs: readonly RenderTargetSpec[]): RenderTargets { }, sizeOf: vi.fn(), viewOf: vi.fn(), + cubeViewOf: vi.fn(), depthViewOf: vi.fn(), reconcile: vi.fn(), setSwapFormat: vi.fn(), From bb00481fc3de373f13a56715bf0727df05ef1a59 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 15:26:22 +0200 Subject: [PATCH 27/60] fix(lensing): centre the annulus march on closest approach, not the camera MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit annulusEmission marched t from 0 (the camera) to ~18 r_s along the ray, but the hole itself sits at length(toAnchor) from the camera — up to 500 AU (~5900 r_s), the whole span the fade band is tuned for. The march never reached the disk outside the last ~1.5 AU of approach, so the required emission-glow feature never rendered across virtually the entire active band. Thread the already-computed closestT into annulusEmission and centre the march window there instead (spec's 32-64-step bound is unaffected: still 48 steps, now spanning +/- 1.5 outerRs about closestT rather than [0, 3*outerRs] from the camera). The escape/capture classification was already closestT-relative and is untouched. Also trims both new .wesl files to the project's comment budget (module header <=10 lines, comment lines <=half code lines) per code review — most of the trimmed material was design-log walkthrough rather than load-bearing landmine/contract content, so no exceeds- budget callout was needed. Fixes a stray backtick pair reintroduced during the fragment.wesl rewrite (WESL parser gotcha #1). Co-Authored-By: Claude Fable 5 --- .../bodies/sgrAStarLensing/fragment.wesl | 114 +++++++----------- .../bodies/sgrAStarLensing/vertex.wesl | 39 ++---- 2 files changed, 53 insertions(+), 100 deletions(-) diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index 6779349838..cc550f33c7 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -2,22 +2,11 @@ // capture (black), escape (LUT-deflected sky-cubemap sample), or annulus // (bounded emission march), composited over the escape/capture base. // -// 'Infinity' encoding (Task 9's 'SchwarzschildDeflectionLut.samples', decided -// here per Task 13's brief): the renderer's texture-upload helper -// ('sgrAStarLensingRenderer.ts') replaces every 'Infinity' sample with a -// large finite sentinel before uploading to the r32float texture — raw IEEE -// Infinity round-trips through an r32float texel exactly, but a fast-math -// shader compiler is not guaranteed to preserve Infinity arithmetic -// (this codebase already treats float edge-case flushing as a live -// landmine), so a threshold comparison well below the sentinel and well -// above any real quadrature result is the robust encoding either way — see -// 'CAPTURE_THRESHOLD_RAD' below. -// -// The captured/escape split happens IN THE LUT sample itself (samples with -// impact parameter at or below the photon-sphere bound are Infinity, hence -// sentinel, by construction — see buildSchwarzschildDeflectionLut.ts), so -// 'captured' here means 'the sampled bend angle is the sentinel', not a -// separate geometric test. +// 'Infinity' encoding: the LUT's captured samples (b <= b_c, see +// buildSchwarzschildDeflectionLut.ts) are non-finite; 'sgrAStarLensingRenderer +// .ts' replaces them with a finite sentinel before the r32float upload (raw +// Infinity isn't guaranteed to survive a fast-math shader compiler), so +// 'CAPTURE_THRESHOLD_RAD' below is a threshold check, not an isinf() test. import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; import package::lib::math::rotateAroundAxis; @@ -33,25 +22,18 @@ struct FsIn { @location(0) posRelCamM: vec3, }; -// Half of the renderer's CPU-side sentinel (see the module header) — the two -// sides don't need to agree on an exact value, only that this sits well -// below the sentinel and well above any real (finite) quadrature result, -// which stays a low-two-digit-radian value even one grid step from the -// critical impact parameter (see buildSchwarzschildDeflectionLut.ts's -// Simpson integration). +// Half the renderer's sentinel — the two sides need not agree exactly, only +// that this sits between any real (finite) bend angle and the sentinel. const CAPTURE_THRESHOLD_RAD: f32 = 500.0; const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound const DISK_HALF_THICKNESS_RS: f32 = 0.15; // thin-disk approximation, tuned for looks const DOPPLER_STRENGTH: f32 = 0.6; // tuned for looks — see BLACK_HOLES's own "visual taste" note -// Two-tap manual lerp over the LUT (an r32float texture is not -// sampler-filterable without the optional 'float32-filterable' feature, so -// this uses textureLoad, not textureSample — see the WebKit texture_1d note -// in docs/RENDERER.md, the reason the LUT is a texture_2d of height 1 -// rather than a texture_1d in the first place). Either tap reading the -// sentinel propagates it through unblended, so a lerp never averages a real -// angle with the capture sentinel into a bogus finite value. +// Two-tap manual lerp (r32float isn't sampler-filterable without the +// optional feature, hence textureLoad + a texture_2d, not texture_1d — +// WebKit rejects the latter, docs/RENDERER.md). Either tap hitting the +// sentinel propagates it unblended, never averaging a real angle with it. fn sampleLut(impactParamRs: f32) -> f32 { let span = max(u.lutMaxImpactParamRs - u.lutMinImpactParamRs, 1e-6); let t = saturate((impactParamRs - u.lutMinImpactParamRs) / span); @@ -67,33 +49,33 @@ fn sampleLut(impactParamRs: f32) -> f32 { return mix(a0, a1, fract(fIdx)); } -// Disk-plane normal from (inclination, positionAngle): tilt a fixed world-+Y -// reference about world +X, then spin the tilted normal's azimuth about -// world +Y. Deliberately NOT the Galactic-Centre sky frame 'sStar.ts' orients -// S-star orbits against — that frame's RA/Dec basis has no field in this -// uniform's locked 144 bytes, and 'BLACK_HOLES''s own doc already calls -// inclination/positionAngle "visual taste" rather than fit to observations — -// so a fixed world reference is a documented simplification, not a silent -// mismatch with the S-star orbits' frame. +// Tilt a fixed world-+Y reference by inclination, then spin its azimuth by +// positionAngle — NOT the Galactic-Centre sky frame S-star orbits use (that +// RA/Dec basis has no field in this uniform); BLACK_HOLES already calls both +// angles "visual taste", so a fixed world reference is a documented choice. fn diskNormal() -> vec3 { let tilted = rotateAroundAxis(vec3(0.0, 1.0, 0.0), vec3(1.0, 0.0, 0.0), u.inclinationRad); return normalize(rotateAroundAxis(tilted, vec3(0.0, 1.0, 0.0), u.positionAngleRad)); } -// Bounded march along the UNDEFLECTED ray (spec's 32-64-step bound) for the -// accretion annulus's own emission, composited over the escape/capture base -// the caller already resolved. Returns (premultiplied-ish linear emission, -// coverage) — coverage feeds the caller's alpha, not the light itself. -fn annulusEmission(rayDir: vec3, toAnchor: vec3) -> vec4 { +// Bounded march (spec's 32-64-step bound) for the annulus's own emission, +// composited over the escape/capture base. Centred on 'closestT' (the ray's +// own closest approach to the hole, computed once in 'fs') rather than on +// t=0 (the camera): the hole sits at 'length(toAnchor)' from the camera, +// almost always far outside a 't in [0, marchHalfM]' window sized off +// 'outerRs', so marching from the camera would miss the disk for virtually +// the whole fade band. Returns (linear emission, coverage); coverage feeds +// the caller's alpha, not the light itself. +fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32) -> vec4 { let normal = diskNormal(); - let marchMaxM = u.outerRs * u.schwarzschildRadiusM * 3.0; - let stepLenM = marchMaxM / f32(MARCH_STEPS); + let marchHalfM = u.outerRs * u.schwarzschildRadiusM * 1.5; + let stepLenM = (2.0 * marchHalfM) / f32(MARCH_STEPS); let halfThicknessM = DISK_HALF_THICKNESS_RS * u.schwarzschildRadiusM; var emission = vec3(0.0); var coverage = 0.0; for (var i = 0; i < MARCH_STEPS; i++) { - let t = (f32(i) + 0.5) * stepLenM; + let t = max(closestT - marchHalfM + (f32(i) + 0.5) * stepLenM, 0.0); let p = rayDir * t - toAnchor; // position relative to the hole's centre let distToPlane = dot(p, normal); if (abs(distToPlane) > halfThicknessM) { @@ -109,9 +91,8 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3) -> vec4 { let radialDir = inPlane / max(radialM, 1e-6); let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point let dopplerFactor = 1.0 + DOPPLER_STRENGTH * dot(orbitDir, -rayDir); - // Kepler orbital period ~ r^1.5: a cheap differential-rotation phase - // offset per radius (closer annuli lead the outer ones), not a fitted - // light curve — visual taste, as above. + // Kepler period ~ r^1.5: a cheap per-radius phase offset (closer annuli + // lead the outer ones), not a fitted light curve — visual taste, as above. let periodScale = pow(max(radialRs, 0.1), 1.5); let localPhase = u.flickerPhase + (radialRs / periodScale) * TAU; let flicker = 1.0 + u.flickerAmp * sin(localPhase); @@ -131,12 +112,10 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3) -> vec4 { fn fs(in: FsIn) -> @location(0) vec4 { let rayDir = normalize(in.posRelCamM); let toAnchor = u.anchorPosRelCamM; - // Perpendicular distance from the hole's centre to the ray through the - // origin (the camera) — the impact parameter. Clamped to the ray's - // forward half: the billboard is centred on the anchor and faces the - // camera, so a negative closestT is unreachable in practice, but the - // clamp keeps the geometry well-defined if float error ever puts a - // corner fragment just behind the plane's own centre. + // Impact parameter: perpendicular distance from the hole to the ray + // through the camera (the origin). Clamped forward — the billboard faces + // the camera and is centred on the anchor, so negative t is unreachable + // outside float error at a corner fragment. let closestT = max(dot(toAnchor, rayDir), 0.0); let offsetVec = toAnchor - rayDir * closestT; let impactParamM = length(offsetVec); @@ -146,39 +125,30 @@ fn fs(in: FsIn) -> @location(0) vec4 { var alpha = 0.0; if (impactParamRs < u.lutMinImpactParamRs) { - // Below the LUT's own sampled domain — deep inside the capture region - // the LUT never samples a finite value for. - alpha = u.bandAlpha; + alpha = u.bandAlpha; // below the LUT's own domain — deep in the capture region } else { let bendAngle = sampleLut(impactParamRs); if (bendAngle >= CAPTURE_THRESHOLD_RAD) { alpha = u.bandAlpha; } else { - // Gravitational lensing displaces the apparent background AWAY from - // the lens centre (the Einstein-ring displacement) — rotate the - // straight-line ray away from the hole by the LUT's bend angle to - // recover the asymptotic sky direction this photon actually left - // from. Sign/axis convention: verify visually at the Task 17 gate - // (the known LUT approximation the brief accepts); flip the sign here - // if the ring reads backward. + // Lensing displaces the apparent background AWAY from the lens centre + // (Einstein-ring displacement): rotate the ray away from the hole by + // the LUT's bend angle to recover the source's asymptotic direction. + // Sign/axis unverified visually (Task 17 gate); flip if it reads backward. let axis = normalize(cross(rayDir, toAnchor)); let deflected = normalize(rotateAroundAxis(rayDir, axis, -bendAngle)); color = textureSampleLevel(skyTex, skySampler, deflected, 0.0).rgb; - // Soft edge fade toward the billboard's rim so the roster drawn - // earlier still shows through once deflection is negligible — 'over' - // blend, per-pixel alpha does the rest (see ContentLayer.d.ts's note - // on this row's blend). + // Soft edge fade to the billboard's rim so the earlier-drawn roster + // shows through once deflection is negligible (Blend.d.ts's 'over'). let edgeFade = 1.0 - smoothstep(u.lutMaxImpactParamRs * 0.7, u.lutMaxImpactParamRs, impactParamRs); alpha = u.bandAlpha * edgeFade; } - let annulus = annulusEmission(rayDir, toAnchor); + let annulus = annulusEmission(rayDir, toAnchor, closestT); color += annulus.rgb; alpha = max(alpha, u.bandAlpha * annulus.a); } - // Premultiplied — this row's blend is PREMULTIPLIED_OVER (Blend.d.ts's - // 'over'), so the fragment multiplies its own colour by coverage. - return vec4(color * alpha, alpha); + return vec4(color * alpha, alpha); // premultiplied, per PREMULTIPLIED_OVER_BLEND } diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl index cf1432db60..20aff461c2 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl @@ -1,17 +1,9 @@ // bodies/sgrAStarLensing/vertex.wesl — camera-facing billboard covering -// Sgr A*'s visible lensing halo. -// -// Not a literal fullscreen triangle: the locked 144-byte -// 'SgrAStarLensingUniforms' (Task 10) carries no inverse-viewProj and no -// camera-right/up basis, so there is no way to unproject a screen uv into a -// world ray the way 'atmosphere/shell/fragment.wesl''s 'insideRayDir' does. -// A world-space billboard sidesteps that: each fragment's -// perspective-interpolated position on the flat quad IS the exact point -// where the camera ray through that pixel crosses the plane, so the -// fragment recovers its own ray direction by normalizing the interpolated -// position — no inverse matrix needed. The quad's basis is built from -// 'anchorPosRelCamM' alone (a look-at billboard, no separate camera basis -// input either) — see 'vs' below. +// Sgr A*'s lensing halo. Not a fullscreen triangle: the locked 144-byte +// 'SgrAStarLensingUniforms' carries no inverse-viewProj/camera basis, so a +// flat quad's exact perspective-interpolated plane position stands in for +// an unprojected ray (the fragment normalizes it) — the quad's own basis is +// a look-at built from 'anchorPosRelCamM' alone. import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; import package::lib::camera::worldToClip; @@ -19,21 +11,14 @@ import package::lib::billboard::quadCorner; @group(0) @binding(0) var u: SgrAStarLensingUniforms; -// Billboard half-size, as a multiple of the LUT's own max sampled impact -// parameter ('u.lutMaxImpactParamRs') — generous margin so the -// escape/annulus classification never runs off the quad's rasterized edge -// under normal (non-2-r_s-floor) viewing. The fragment's own edge fade reads -// 'u.lutMaxImpactParamRs' directly, so this margin and that fade can't drift -// apart into a visible seam. +// Half-size as a multiple of the LUT's max impact parameter — margin past +// the fragment's matching edge fade so the two can't drift apart. const BILLBOARD_MARGIN: f32 = 1.5; struct VsOut { @builtin(position) clip: vec4, - // Camera-relative world position of this point on the billboard PLANE, - // perspective-interpolated across the quad — not yet normalized; the - // fragment renormalizes after interpolation (interpolating a direction - // linearly and normalizing afterward is the house rule after any - // matrix/interpolation transform). + // Camera-relative billboard-plane position, perspective-interpolated + // (the fragment renormalizes after interpolation). @location(0) posRelCamM: vec3, }; @@ -41,10 +26,8 @@ struct VsOut { fn vs(@builtin(vertex_index) vi: u32) -> VsOut { let toAnchor = u.anchorPosRelCamM; let anchorDistM = length(toAnchor); - // Look-at billboard basis from the anchor direction alone (no separate - // camera-right/up uniform — see the module header). Degenerate only when - // the anchor sits exactly along world +Y, unreachable while the camera is - // actually looking toward the black hole (this layer's 'enabled' gate). + // Look-at basis from the anchor direction alone; degenerate only along + // world +Y, unreachable while the camera looks toward the hole ('enabled'). let forward = toAnchor / max(anchorDistM, 1e-6); let worldUp = vec3(0.0, 1.0, 0.0); let right = normalize(cross(worldUp, forward)); From 93aff85aff2d79f0835d44bd54bfce3968b1c467 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 15:51:14 +0200 Subject: [PATCH 28/60] feat(lensing): draw-order reorder + wire the missing (hdr, BODY[k]) step (Task 14) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sgrAStarLensingLayer moves after the sky roster (constellations, its last sample) and before orbit-trails/body-glints, which move to draw after it (spec "Draw order", Q5). frameProgram never emitted an (hdr, BODY[k]) step before this — the layer compiled and registered but was structurally unreachable (Task 13's own recorded finding, Ruling 8). Wired the minimal step, band-gated for zero cost outside the fade band, mirroring the sky-capture steps' pattern and MAX_FOREGROUND_CHAIN's static-pool sizing. orbit-trails/body-glints still share the (hdr, NEAR0) step with the roster, so the lens pass also draws over them today — flagged as a residual limitation with options in task-14-report.md rather than guessed at. Co-Authored-By: Claude Fable 5 --- src/services/engine/frame/frameProgram.ts | 65 ++++++++- src/services/engine/frame/passes/index.ts | 134 ++++++++++-------- src/services/engine/frame/renderFrame.ts | 19 ++- .../engine/frame/frameProgram.test.ts | 75 +++++++++- .../engine/frame/passes/passes.test.ts | 47 +++--- 5 files changed, 255 insertions(+), 85 deletions(-) diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index ba50be7326..411d46e36a 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -128,12 +128,27 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * `submit` landmine, docs/RENDERER.md), an invariant a multi-face capture * sweep breaks; no layer carries `skyCapture` yet, so these steps still * select an empty group and draw nothing pending that renderer-side fix. + * + * `sgrAStarLensingBodySlabs` (Task 14, Ruling 8) is the black-hole lens's OWN + * missing step: no step here ever matched `sgrAStarLensingLayer` (`slab: + * 'body'`, `target: 'hdr'`) before this task — it registered and compiled but + * never drew (Task 13's own recorded finding). `renderFrame` resolves Sgr + * A*'s body-m row each frame and passes it here ONLY inside the fade band, so + * an inactive band emits no step at all (same zero-dispatch guarantee as + * `skyCubemapFacesToCapture`). One `(hdr, slab)` render step per entry, + * placed after the `(hdr, NEAR0)` roster step so the lens's OVER blend + * occludes the roster light already accumulated there. It also ends up + * drawing over `orbit-trails`/`body-glints` (the SAME shared step, per + * `passes/index.ts`'s registry order) — fully keeping those two unwarped + * needs splitting that shared step, which this one new step does not do; see + * the task 14 report. */ export function frameProgram( tone: ToneMap, bloomEnabled: boolean, foregroundChain: readonly number[], skyCubemapFacesToCapture: readonly CubeFace[], + sgrAStarLensingBodySlabs: readonly number[] = [], ): readonly FrameStep[] { const steps: FrameStep[] = []; @@ -187,6 +202,13 @@ export function frameProgram( // by the COSMO step above, so this pass loads rather than clears. steps.push({ kind: 'render', target: 'hdr', slab: NEAR0 }); + // The black-hole lens's own (hdr, BODY[k]) step(s) — see this function's + // doc for why it exists and its residual limitation. Runs after the (hdr, + // NEAR0) roster above; empty (inactive band) contributes no step. + for (const slab of sgrAStarLensingBodySlabs) { + steps.push({ kind: 'render', target: 'hdr', slab }); + } + // Near-field foreground bodies (zoom-to-earth fold). Rendered into their // depth-bearing foreground target, then composited OVER hdr in LINEAR // space (tone: null) so the Sun/Earth pixels join the HDR accumulator @@ -305,6 +327,13 @@ export const PASS_GROUP_TITLES: Readonly> = { 'sky-cubemap·NEAR0': 'Sky capture', 'hdr·COSMO': 'Cosmos · HDR', 'hdr·NEAR0': 'Near field · HDR', + // One `hdr·BODY[k]` row per capacity slot — today only the black-hole lens + // (`sgrAStarLensingLayer`) targets `hdr` on a body-m slab, so every slot + // buckets under one title regardless of which row Sgr A* lands in this + // frame, same reasoning as the `foreground:0·BODY[k]` block below. + ...Object.fromEntries( + Array.from({ length: BODY_SLAB_CAPACITY }, (_, k) => [`hdr·${slabName(k + 2)}`, 'Sgr A* lensing']), + ), 'foreground:0·NEAR0': 'Foreground bodies · depth', // One `foreground:0·BODY[k]` row per capacity slot, derived from `slabName` // rather than authored — a new SCENE_PLANETS row widens BODY_SLAB_CAPACITY @@ -500,8 +529,26 @@ const MAX_FOREGROUND_CHAIN: readonly number[] = [ */ const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; +/** + * The MAXIMUM sgrAStarLensing body-slab list — every capacity index (Task + * 14), the same "maximum, not a real frame" sizing `MAX_FOREGROUND_CHAIN` + * documents above: Sgr A*'s painter-order row moves with whichever OTHER + * bodies are visible, so the query-set pool must cover every capacity slot + * it could land on, not just today's live value. + */ +const MAX_SGR_A_STAR_LENSING_BODY_SLABS: readonly number[] = Array.from( + { length: BODY_SLAB_CAPACITY }, + (_, k) => k + 2, +); + export const TIMED_SLOTS: readonly string[] = timedSlotsOf( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), + frameProgram( + PLACEHOLDER_TONE, + true, + MAX_FOREGROUND_CHAIN, + ALL_CUBE_FACES, + MAX_SGR_A_STAR_LENSING_BODY_SLABS, + ), CONTENT_LAYERS, ); @@ -511,7 +558,13 @@ export const TIMED_SLOTS: readonly string[] = timedSlotsOf( * `CONTENT_LAYERS` gets a grouped row here with zero DebugPanel edits. */ export const TIMED_SLOT_GROUPS: readonly TimedSlotGroup[] = timedSlotGroupsOf( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), + frameProgram( + PLACEHOLDER_TONE, + true, + MAX_FOREGROUND_CHAIN, + ALL_CUBE_FACES, + MAX_SGR_A_STAR_LENSING_BODY_SLABS, + ), CONTENT_LAYERS, ); @@ -550,7 +603,13 @@ function plainLayerGroupKeys( * project them into the same groups the timing list uses. */ const PASS_GROUP_KEYS: ReadonlyMap = plainLayerGroupKeys( - frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN, ALL_CUBE_FACES), + frameProgram( + PLACEHOLDER_TONE, + true, + MAX_FOREGROUND_CHAIN, + ALL_CUBE_FACES, + MAX_SGR_A_STAR_LENSING_BODY_SLABS, + ), CONTENT_LAYERS, ); diff --git a/src/services/engine/frame/passes/index.ts b/src/services/engine/frame/passes/index.ts index 18ff9ea6e8..22d1d35ba3 100644 --- a/src/services/engine/frame/passes/index.ts +++ b/src/services/engine/frame/passes/index.ts @@ -35,12 +35,15 @@ * 8. horizon-shell — translucent sphere at the observable-universe edge * 9. structure-markers — at-rest halo + ring for cluster / SC / void structures * - * Six more near-field rows follow, projected through the near0 slab (COSMO's - * fixed near plane would clip their kpc-to-AU-scale anchors). Five accumulate + * Nine more near-field rows follow, projected through the near0 slab (COSMO's + * fixed near plane would clip their kpc-to-AU-scale anchors). Seven accumulate * into the HDR target via the shared `(hdr, NEAR0)` render step (milky-way, - * star-points, orbit-trails, star-catalog, star-upsample); the sixth, - * `star-aggregates`, has its OWN `(star-aggregates, NEAR0)` render step into the - * half-res offscreen that `star-upsample` then composites back: + * star-points, star-catalog, star-upsample, constellations, orbit-trails, + * body-glints); `star-aggregates` has its OWN `(star-aggregates, NEAR0)` render + * step into the half-res offscreen `star-upsample` composites back, and + * `sgr-a-star-lensing` has its OWN `(hdr, BODY[k])` render step (Task 14) — its + * position below is registry-order documentation, not the mechanism that keeps + * it after the roster and before orbit-trails/body-glints; see `frameProgram.ts`: * * 10. milky-way — star/dust point cloud at the galactic centre * (the fixed 10 kpc COSMO near plane clipped the @@ -51,86 +54,97 @@ * stars (partitionStarsByResolution) as additive * point sprites, riding the same tone-map as the * galaxies - * 12. orbit-trails — accurate Keplerian orbit trails (Earth / Jupiter / - * Moon) as screen-space conics with a brightness - * lobe at the body's position (f64 compose seam) - * 12b. body-glints — the sub-pixel bodies (the glints branch of the body - * partition) as brightness-scaled additive points - * (size x albedo x phase, cross-fading with the mesh - * over 1-3 px), sibling of star-points (f64 rebase seam) - * 12c. sgr-a-star-lensing — the black-hole lens pass (Task 13): a `body`-slab - * row drawing ONLY on Sgr A*'s own row, PREMULTIPLIED - * OVER (not additive) into hdr — captured rays occlude - * the additive light already accumulated behind them; - * escaping rays sample the Task 11 sky-cubemap bent by - * the Task 9 LUT. Index provisional pending Task 14. - * 13. star-aggregates — the survey (Gaia bin) AGGREGATE stream (interior + * 12. star-aggregates — the survey (Gaia bin) AGGREGATE stream (interior * flux-mip glows), drawn LINEAR into the half-res * `star-aggregates` offscreen by its own render step * (the fill-bound half of the star pass) - * 14. star-catalog — the survey LEAF stream (real point-source stars), + * 13. star-catalog — the survey LEAF stream (real point-source stars), * drawn full-res into HDR as a per-frame flux-mip * cut of additive point sprites (f64 rebase seam), * crossfading to the procedural Milky-Way cloud - * 15. star-upsample — composites the half-res `star-aggregates` offscreen + * 14. star-upsample — composites the half-res `star-aggregates` offscreen * back into HDR, applying the hue-preserving knee to * the summed aggregate field (the LOD-symmetry fix) + * 15. constellations — additive stick-figure lines between the real stars, + * drawn after the star streams so the figures read + * over the starfield; the LAST roster row the lens + * pass below samples + * 16. sgr-a-star-lensing — the black-hole lens pass (Tasks 13-14): a `body`-slab + * row drawing ONLY on Sgr A*'s own row, PREMULTIPLIED + * OVER (not additive) into hdr — captured rays occlude + * the additive roster light already accumulated behind + * them; escaping rays sample the Task 11 sky-cubemap + * bent by the Task 9 LUT. Its OWN `(hdr, BODY[k])` + * step (`frameProgram.ts`) runs after the `(hdr, + * NEAR0)` roster step above so it draws over items + * 10-15 + * 17. orbit-trails — accurate Keplerian orbit trails (Earth / Jupiter / + * Moon) as screen-space conics with a brightness + * lobe at the body's position (f64 compose seam); + * moved here (from between 11 and 13) so it draws + * unwarped over the lens pass, per spec "Draw order" + * 17b. body-glints — the sub-pixel bodies (the glints branch of the body + * partition) as brightness-scaled additive points + * (size x albedo x phase, cross-fading with the mesh + * over 1-3 px), sibling of star-points (f64 rebase + * seam); moved alongside orbit-trails for the same + * reason * * The next six are premultiplied-OVER overlays, projected through the * cosmological slab (except near0-selection-ring, which rides near0) and drawn * post-tone-map onto the swap chain: * - * 16. selection-ring — per-galaxy / Milky-Way / structure selection halo + * 18. selection-ring — per-galaxy / Milky-Way / structure selection halo * (COSMO slab) - * 17. near0-selection-ring — the same halo for a NEAR0-slab pick (a survey + * 19. near0-selection-ring — the same halo for a NEAR0-slab pick (a survey * star): shared renderer + selectionHalo gate, * projected through near0 with the f64 rebase seam - * 18. disk-radius-ring — debug: catalog-disk-radius calibration ring - * 19. marker-lines — screen-space thick-line overlay (e.g. label stems) - * 20. labels — MSDF text labels - * 21. clip-path-debug — debug: clip-path inspector route + gizmo + * 20. disk-radius-ring — debug: catalog-disk-radius calibration ring + * 21. marker-lines — screen-space thick-line overlay (e.g. label stems) + * 22. labels — MSDF text labels + * 23. clip-path-debug — debug: clip-path inspector route + gizmo * * The final rows leave the cosmological slab entirely — the near-field * foreground group, projected through the near0 slab (whose near/far track * the camera's orbit distance) so the true-scale bodies are never clipped by * the cosmological near plane: * - * 22. earth — true-scale Blue-Marble-textured Earth (f64 compose + * 24. earth — true-scale Blue-Marble-textured Earth (f64 compose * seam), opaque (depth-tested) into the `foreground:0` * target - * 23. cloud-shell — Earth's translucent cloud deck, drawn right after + * 25. cloud-shell — Earth's translucent cloud deck, drawn right after * the opaque surface so it depth-tests against it (far * hemisphere occluded), writing no depth and blending * straight-alpha OVER (like the ring — a blend * exception in the otherwise opaque foreground group) - * 24. star-spheres — the resolved partition of the stars (the Sun + + * 26. star-spheres — the resolved partition of the stars (the Sun + * any star crossing STAR_RESOLVE_PX) as true-scale * flat-emissive spheres (f64 compose seam), opaque * into the same `foreground:0` target - * 25. field-star-sphere — the close-range sphere for the ONE nearest + * 27. field-star-sphere — the close-range sphere for the ONE nearest * resolvable Gaia field star (presence derived from * proximity, not selection), reusing the same star * renderer + f64 compose seam, opaque into the same * target - * 26. planets — the flat branch of the body partition: resolved + * 28. planets — the flat branch of the body partition: resolved * bodies without a resident surface texture, as * true-scale flat-lit albedo spheres (f64 compose * seam), opaque into the same target - * 27. textured-bodies — the textured branch of the body partition: resolved + * 29. textured-bodies — the textured branch of the body partition: resolved * bodies whose surface texture is resident, as lit * surface-mapped spheres (Saturn's ring casts an * analytic on-planet shadow); opaque into the same * target (f64 compose seam) - * 28. rings — Saturn's translucent ring overlay, drawn LAST in the + * 30. rings — Saturn's translucent ring overlay, drawn LAST in the * (foreground:0, NEAR0) group so it depth-tests against * the opaque spheres already stamped there (far ring * half occluded), writing no depth and blending * straight-alpha OVER — like cloud-shell, a blend * exception in the otherwise opaque foreground group - * 29. foreground-labels — scene-body name captions, premultiplied-OVER onto + * 31. foreground-labels — scene-body name captions, premultiplied-OVER onto * the swap chain post-tone-map (like the COSMO labels, * but anchored through the near0 vp) - * 30. atmosphere-shell — Earth's physically-based in-scatter atmosphere, + * 32. atmosphere-shell — Earth's physically-based in-scatter atmosphere, * the LAST content-layer row (spec §8.3): a * translucent proxy sphere at the atmosphere-top * radius, drawn last in the (foreground:0, NEAR0) @@ -279,10 +293,14 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // hdr layers above and before the tone-map — so the HDR-target members ride // the same tone curve as the galaxies. Milky Way FIRST — its dust pass is // multiplicative, and leading the group keeps the local starfield below out of - // that multiply (see the header) — then star points, the conic orbit trails, - // and the survey (Gaia bin) star streams. All the HDR members are additive, so - // their relative order is a listing choice, not a compositing one — with the - // one exception noted on the Milky Way rows below. + // that multiply (see the header) — then the survey (Gaia bin) star streams and + // the constellation figures: the whole additive "sky" roster the Sgr A* lens + // pass (below) samples. `orbit-trails`/`body-glints` trail LAST in this group, + // after the lens pass's own step, so they stay unwarped over it (spec "Draw + // order", Q5) rather than sitting among the roster they used to interleave + // with. All the HDR members here are additive, so their relative order among + // THEMSELVES is a listing choice, not a compositing one — with the one + // exception noted on the Milky Way rows below. // // The Milky Way cloud is three rows, and their order IS load-bearing. The // star billboards draw into the reduced-resolution `mw-aggregate` offscreen @@ -297,21 +315,6 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ milkyWayUpsampleLayer, milkyWayLayer, starPointsLayer, - orbitTrailsLayer, - // The sub-pixel bodies (the glints branch of the body partition) as - // brightness-scaled additive points — the far half of the body LOD, sibling of - // star-points. Additive into HDR through NEAR0, so its position among the - // additive rows is a listing choice, not a compositing one. - bodyGlintsLayer, - // The Sgr A* lens pass (Task 13): a 'body'-slab row, listed here beside its - // nearest sibling in shape (body-glints, also a per-body-row hdr draw) — - // Task 14 owns its final index. Its blend is 'over' (Blend.d.ts), not - // additive like its neighbours in this run, so — unlike the additive rows - // around it — its position IS load-bearing once it draws at all: it must - // occlude/replace light already accumulated by the additive COSMO+NEAR0 - // steps, which frameProgram's own step order (independent of this array) - // already guarantees run first. - sgrAStarLensingLayer, // The survey (Gaia bin) stars split into two streams sharing one per-frame // walk: the AGGREGATE glow field draws LINEAR into the half-res // `star-aggregates` offscreen by its OWN render step (so its position here is @@ -326,8 +329,27 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // through NEAR0 into HDR, so they ride the same tone-map as the stars they // connect and join the existing (hdr, NEAR0) render step. Drawn after the star // streams so the figure lines read over the starfield; additive blend makes - // that a listing choice, not a compositing one. + // that a listing choice, not a compositing one. The LAST roster row the Sgr + // A* lens pass samples (below). constellationsLayer, + // The Sgr A* lens pass (Task 13/14): a 'body'-slab row, blend 'over' + // (Blend.d.ts) rather than additive like its neighbours, so — unlike the + // additive rows around it — its position IS load-bearing: it must draw AFTER + // every roster row above (so its captured/escaping rays occlude the additive + // light already accumulated behind them) and BEFORE orbit-trails/body-glints + // below (so those stay unwarped on top, spec "Draw order", Q5). Registry + // order alone can't enforce this against `orbit-trails`/`body-glints` — they + // share this SAME (hdr, NEAR0) render step with the roster above, so their + // relative draw order actually comes from `frameProgram`'s own step order + // (see its module header) wedging a dedicated (hdr, BODY[k]) step here; this + // array position is the documentation of that intent, not its enforcement. + sgrAStarLensingLayer, + orbitTrailsLayer, + // The sub-pixel bodies (the glints branch of the body partition) as + // brightness-scaled additive points — the far half of the body LOD, sibling of + // star-points. Additive into HDR through NEAR0, so its position among the + // additive rows is a listing choice, not a compositing one. + bodyGlintsLayer, // Swap-target rows: post-tone-map, premultiplied-OVER overlays. Selection // ring leads so marker-lines and labels composite over its stroke; the debug // clip-path overlay is the very last swap row (below, past the NEAR0 group) so diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index c2c839c091..05970daba4 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -72,7 +72,7 @@ import { distanceMpc } from '../../../utils/math/distanceMpc'; import { fadeBand } from '../../../utils/math/fadeBand'; import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; import { SCALE_UNITS } from '../../../data/scaleUnits'; -import { SGR_A_STAR_ANCHOR } from '../../../data/bodies/sceneSgrAStar'; +import { SGR_A_STAR, SGR_A_STAR_ANCHOR } from '../../../data/bodies/sceneSgrAStar'; const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC = SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU * SCALE_UNITS.AU_TO_MPC; @@ -128,6 +128,22 @@ export function renderFrame(input: RenderFrameInput): void { sceneBodyStates(state, ctx), ); const bandActive = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, gcDistanceMpc) > 0; + + // Sgr A*'s own body-m slab row this frame, if the band is active (Task 14, + // Ruling 8): `frameProgram` never emitted an (hdr, BODY[k]) step for + // `sgrAStarLensingLayer` before this task, so it compiled and registered + // but never drew (Task 13's own finding). Resolved here, not in + // `frameProgram`, because the row's painter-order index comes from + // `deriveSlabs` (computed upstream of this function) — the same + // "resolve here, hand data down" split `earthSlab` in `runFrame.ts` + // already follows for the identical `frame.kind === 'body-m'` lookup. + // `null` outside the band, or when the row isn't in `ctx.slabs` this frame + // (e.g. frustum-culled despite the distance band). + const sgrAStarBodySlab = bandActive + ? (ctx.slabs.find( + (slab) => slab.frame.kind === 'body-m' && slab.frame.bodyId === SGR_A_STAR.id, + )?.index ?? null) + : null; const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; // Every captured face's content (which galaxies/stars are visible, their // backdrop-fade alpha) is keyed on the PLAYER's camera position, not the @@ -195,6 +211,7 @@ export function renderFrame(input: RenderFrameInput): void { // foreground:0 render expands into, one step per entry. foregroundChainOrder(ctx.slabs), skyCubemapFacesToCapture, + sgrAStarBodySlab === null ? [] : [sgrAStarBodySlab], ), layers: CONTENT_LAYERS, strategy, diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index c199ecc9f0..52bd270fff 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -246,6 +246,31 @@ describe('frameProgram', () => { ).toHaveLength(1); }); + it('sgrAStarLensingBodySlabs: emits an (hdr, slab) step per entry, after (hdr, NEAR0) and before the foreground chain', () => { + // Task 14 (Ruling 8): before this, no step ever matched + // sgrAStarLensingLayer's (slab: 'body', target: 'hdr') row. One render + // step per requested body-slab index, positioned so the lens's OVER blend + // occludes the (hdr, NEAR0) roster already accumulated above it. + const program = frameProgram(TONE, false, [NEAR0], [], [4]); + const hdrNear0Idx = program.findIndex( + (step) => step.kind === 'render' && step.target === 'hdr' && step.slab === NEAR0, + ); + expect(program[hdrNear0Idx + 1]).toEqual({ kind: 'render', target: 'hdr', slab: 4 }); + const foregroundIdx = program.findIndex( + (step) => step.kind === 'render' && step.target === 'foreground:0', + ); + expect(hdrNear0Idx + 1).toBeLessThan(foregroundIdx); + }); + + it('sgrAStarLensingBodySlabs omitted or empty: no extra step, program identical to the base list (zero-cost outside the band)', () => { + const withDefault = frameProgram(TONE, false, [NEAR0], []); + const withEmpty = frameProgram(TONE, false, [NEAR0], [], []); + const base = frameProgram(TONE, false, [NEAR0], [], undefined); + expect(withDefault).toEqual(base); + expect(withEmpty).toEqual(base); + expect(base.some((step) => step.kind === 'render' && step.slab >= 2)).toBe(false); + }); + it('bloom disabled: no bloom step emitted and program otherwise identical', () => { // Only `enabled` shapes the step list. Bloom-off is the base program; bloom-on // is that base with exactly ONE `{ kind: 'bloom' }` step spliced in between the @@ -330,12 +355,15 @@ describe('timedSlotsOf', () => { // closest sibling — then the two aggregate offscreens, // each its OWN NEAR0 render step ahead of the hdr NEAR0 step: // star-aggregates, then milky-way-aggregate. The (hdr, NEAR0) step follows - // with milky-way-upsample + milky-way + star-points + orbit-trails + - // star-catalog + star-upsample before the tone-map — milky-way-upsample + // with milky-way-upsample + milky-way + star-points + star-catalog + + // star-upsample + constellations before the tone-map — milky-way-upsample // precedes milky-way so the dust extincts the cloud's own starlight, that // pair leads the group so the multiplicative dust never darkens the local // starfield, and star-upsample sits adjacent to the star-catalog leaf draw - // it composites. The + // it composites. orbit-trails + body-glints trail LAST in this group + // (Task 14) — this fixture passes no sgrAStarLensingBodySlabs, so its + // own (hdr, BODY[k]) step (which would otherwise sit between this group + // and the foreground:0 step) is absent, zero-cost. The // foreground:0 body render now comes NEXT (before the composites) — one // render STEP per foregroundChain entry (Task 9-11: earth, cloud-shell, // planets, textured-bodies, rings, and atmosphere-shell all ride the @@ -373,11 +401,11 @@ describe('timedSlotsOf', () => { 'milky-way-upsample', 'milky-way', 'star-points', - 'orbit-trails', - 'body-glints', 'star-catalog', 'star-upsample', 'constellations', + 'orbit-trails', + 'body-glints', 'hdr·NEAR0', // The body-m step (Task 9-11): every 'body'-slab layer matches EVERY // body row, so earth, cloud-shell, planets, textured-bodies, rings, and @@ -415,6 +443,24 @@ describe('timedSlotsOf', () => { 'pick', ]); }); + + it('reaches sgrAStarLensingLayer once a body slab is passed (Task 14 regression: Task 13 found no step ever matched it)', () => { + // Before Task 14, frameProgram never emitted an (hdr, BODY[k]) step, so + // this name never appeared in ANY derived slot list regardless of the + // real CONTENT_LAYERS registry or chain contents — the layer compiled + // and registered but was structurally unreachable. Passing Sgr A*'s own + // slab index (4, arbitrary — any body-slab index widens the same way) + // must now surface its row, positioned right after the (hdr, NEAR0) + // group's own slot. + const slots = timedSlotsOf( + frameProgram(TONE, false, [NEAR0], [], [4]), + CONTENT_LAYERS, + ); + const hdrNear0Idx = slots.indexOf('hdr·NEAR0'); + expect(hdrNear0Idx).toBeGreaterThanOrEqual(0); + expect(slots[hdrNear0Idx + 1]).toBe('sgr-a-star-lensing·BODY[2]'); + expect(slots[hdrNear0Idx + 2]).toBe('hdr·BODY[2]'); + }); }); describe('TIMED_SLOTS — body slot pool', () => { @@ -441,6 +487,19 @@ describe('TIMED_SLOTS — body slot pool', () => { expect(names).toContain(`foreground:0·BODY[${BODY_SLAB_CAPACITY - 1}]`); }); + it('also allocates one hdr·BODY[k] slot per registry row (Task 14 — the lens pass pool)', () => { + // Same "maximum, not a real frame" sizing as the foreground:0 pool above, + // for the black-hole lens's own (hdr, BODY[k]) step: Sgr A*'s + // painter-order row varies with which other bodies are visible, so + // TIMED_SLOTS must cover every capacity slot it could land on. + const bodySlots = TIMED_SLOTS.filter((name) => name.startsWith('hdr·BODY[')); + expect(bodySlots).toHaveLength(BODY_SLAB_CAPACITY); + expect(bodySlots[0]).toBe('hdr·BODY[0]'); + expect(bodySlots[bodySlots.length - 1]).toBe(`hdr·BODY[${BODY_SLAB_CAPACITY - 1}]`); + const group = TIMED_SLOT_GROUPS.find((g) => g.title === 'Sgr A* lensing')!; + expect(group.rows.map((r) => r.name)).toContain('hdr·BODY[0]'); + }); + it('every real TIMED_SLOTS name is unique (buildTimingSlotMap precondition, M2)', () => { // The regression: a 'body' layer used to contribute its bare name once per // capacity row (~26 identical 'planets' entries), which collided on one @@ -509,12 +568,16 @@ describe('timedSlotGroupsOf', () => { // map to "Volumes & aggregates"; the two composites and pick — scattered // through execution order — collapse into // the trailing "Composites & pick". "Sky capture" is TIMED_SLOTS' 6 capture - // steps (Task 12's ALL_CUBE_FACES sizing, one row per face). + // steps (Task 12's ALL_CUBE_FACES sizing, one row per face). "Sgr A* + // lensing" is Task 14's own (hdr, BODY[k]) pool, sized off + // MAX_SGR_A_STAR_LENSING_BODY_SLABS the same way "Foreground bodies" + // is sized off MAX_FOREGROUND_CHAIN. expect(TIMED_SLOT_GROUPS.map((g) => g.title)).toEqual([ 'Volumes & aggregates', 'Sky capture', 'Cosmos · HDR', 'Near field · HDR', + 'Sgr A* lensing', 'Foreground bodies · depth', 'Bloom', 'Overlays', diff --git a/tests/services/engine/frame/passes/passes.test.ts b/tests/services/engine/frame/passes/passes.test.ts index 73d35c963e..94b37fdffb 100644 --- a/tests/services/engine/frame/passes/passes.test.ts +++ b/tests/services/engine/frame/passes/passes.test.ts @@ -225,20 +225,25 @@ const FOREGROUND_NAMES = ['star-spheres', 'field-star-sphere']; // Milky-Way cloud's UPSAMPLE composite first, then the cloud's dust pass (its // multiplicative transmittance must land on the upsampled starlight, and must // never darken the local starfield drawn after it), then the far-partition -// star points, the orbit trails, the survey star LEAF catalog, and the survey -// aggregate UPSAMPLE composite (adjacent to the leaf draw it composites). -// Neither aggregate STREAM is here — the Milky Way's star billboards target -// 'mw-aggregate' and the survey's target 'star-aggregates', so both sit -// outside the hdr group. +// star points, the survey star LEAF catalog, the survey aggregate UPSAMPLE +// composite (adjacent to the leaf draw it composites), and the constellation +// figures — that whole run is the "sky" roster the Sgr A* lens pass samples +// from its OWN (hdr, BODY[k]) step (frameProgram.ts). `orbit-trails` and +// `body-glints` trail LAST here (Task 14) so they draw unwarped over the lens +// pass rather than sitting among the roster it samples. Neither aggregate +// STREAM is here — the Milky Way's star billboards target 'mw-aggregate' and +// the survey's target 'star-aggregates', so both sit outside the hdr group; +// `sgrAStarLensingLayer` itself is ALSO not here — its slab is 'body', not +// NEAR0. const NEAR_HDR_NAMES = [ 'milky-way-upsample', 'milky-way', 'star-points', - 'orbit-trails', - 'body-glints', 'star-catalog', 'star-upsample', 'constellations', + 'orbit-trails', + 'body-glints', ]; // The near-field swap group: the overlays that pair the swap target with the @@ -275,18 +280,22 @@ describe('CONTENT_LAYERS migration table (hdr group)', () => { }); describe('CONTENT_LAYERS migration table (near-field hdr group)', () => { - it('the (hdr, NEAR0) group holds milky-way-upsample, milky-way, star-points, orbit-trails, star-catalog, additive', () => { + it('the (hdr, NEAR0) group holds the sky roster, then orbit-trails/body-glints LAST (Task 14), additive', () => { // The hdr rows outside the cosmological slab: the Milky-Way cloud's - // upsample + dust, the far-partition neighbourhood stars, and the orbit - // trails, projected through NEAR0 (COSMO's FIXED 0.01 Mpc near plane would - // clip their kpc-to-AU-scale anchors — for the Milky Way it clipped the - // disc mid-descent before the approach fade completed) but accumulating - // into the same HDR target so they ride the galaxies' tone-map. Drawn by - // the program's dedicated (hdr, NEAR0) step before the hdr→swap composite. - // The two Milky-Way rows MUST lead, in this order: the upsample adds the - // cloud's own starlight into HDR, then the multiplicative dust extincts it - // along with the cosmological accumulation behind it — and leading the - // group keeps the local starfield drawn after out of that multiply. + // upsample + dust, the far-partition neighbourhood stars, the survey + // catalog/upsample, and the constellation figures, projected through + // NEAR0 (COSMO's FIXED 0.01 Mpc near plane would clip their kpc-to-AU-scale + // anchors — for the Milky Way it clipped the disc mid-descent before the + // approach fade completed) but accumulating into the same HDR target so + // they ride the galaxies' tone-map. Drawn by the program's dedicated (hdr, + // NEAR0) step before the hdr→swap composite. The two Milky-Way rows MUST + // lead, in this order: the upsample adds the cloud's own starlight into + // HDR, then the multiplicative dust extincts it along with the + // cosmological accumulation behind it — and leading the group keeps the + // local starfield drawn after out of that multiply. `orbit-trails` and + // `body-glints` moved LAST here (Task 14, spec "Draw order") so they draw + // over the Sgr A* lens pass's OWN (hdr, BODY[k]) step rather than being + // sampled by it. const nearHdr = CONTENT_LAYERS.filter( (layer) => layer.target === 'hdr' && layer.slab === NEAR0, ); @@ -964,8 +973,8 @@ describe('drawPick migration-table rows', () => { 'structure-markers', 'milky-way', 'star-points', - 'body-glints', 'star-catalog', + 'body-glints', 'labels', 'earth', 'star-spheres', From e3310f5ceecd694949ae1fd923108a8435784fb6 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 16:14:30 +0200 Subject: [PATCH 29/60] feat(lensing): band-gated (hdr, NEAR0) step split for the S-star trails/glints (Task 14b, Ruling 9) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit orbit-trails and body-glints shared the pre-lens (hdr, NEAR0) roster step, so the Sgr A* lens's OVER blend drew over them even though they should stay unwarped on top — evidenced by Task 14's review as a real, not edge-case, gap (39 bound S-star trails cull in exactly when the lens band engages). Option A: ContentLayer.hdrPostLensing opts a layer into a 'post' half of the roster step, which frameProgram only splits out (via FrameStep.lensPhase) when the lens's own step actually fires — zero-cost and byte-identical to today outside the band. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/ContentLayer.d.ts | 11 ++++ src/@types/engine/frame/FrameStep.d.ts | 15 +++++ src/services/engine/frame/executeFrame.ts | 22 ++++++- src/services/engine/frame/frameProgram.ts | 66 ++++++++++++------- .../engine/frame/passes/bodyGlintsLayer.ts | 5 ++ src/services/engine/frame/passes/index.ts | 33 ++++++---- .../engine/frame/passes/orbitTrailsLayer.ts | 6 ++ src/services/engine/frame/slabs.ts | 30 ++++++++- .../engine/frame/executeFrame.test.ts | 56 +++++++++++++++- .../engine/frame/frameProgram.test.ts | 24 +++++-- 10 files changed, 222 insertions(+), 46 deletions(-) diff --git a/src/@types/engine/frame/ContentLayer.d.ts b/src/@types/engine/frame/ContentLayer.d.ts index ed7373112b..867070dbbc 100644 --- a/src/@types/engine/frame/ContentLayer.d.ts +++ b/src/@types/engine/frame/ContentLayer.d.ts @@ -70,6 +70,17 @@ export type ContentLayer = { * three-state confusion with `undefined`. */ readonly skyCapture?: true; + /** + * Opt-in to the `'post'` half of the black-hole lens's `(hdr, NEAR0)` + * step split (Task 14b, Ruling 9): set only by `orbitTrailsLayer` and + * `bodyGlintsLayer`, the two rows the spec keeps unwarped ON TOP of the + * lens rather than sampled by it. `frameProgram` only emits the split + * (and a `'post'` step) when the lens's own `(hdr, BODY[k])` step fires — + * outside the band this flag is inert and every `(hdr, NEAR0)` layer + * shares the one untagged step, exactly as before. `true`-only, same + * three-state-avoidance reasoning as `skyCapture` above. + */ + readonly hdrPostLensing?: true; /** * Whether this layer should record draw commands this frame, given the * step's already-resolved `SlabView` — a `'body'` layer reads diff --git a/src/@types/engine/frame/FrameStep.d.ts b/src/@types/engine/frame/FrameStep.d.ts index 078a2755bf..5474996685 100644 --- a/src/@types/engine/frame/FrameStep.d.ts +++ b/src/@types/engine/frame/FrameStep.d.ts @@ -66,6 +66,21 @@ export type FrameStep = * timing-slot lookup, frameProgram.ts / executeFrame.ts. */ face?: CubeFace; + /** + * Splits the shared `(hdr, NEAR0)` roster step around the black-hole + * lens's own `(hdr, BODY[k])` step (Task 14b, Ruling 9), so + * `orbit-trails`/`body-glints` draw AFTER the lens rather than being + * sampled by it. Absent ⇒ every layer matches, the pre-Task-14b + * behaviour. `'pre'` admits every `(hdr, NEAR0)` layer EXCEPT those + * opted into `ContentLayer.hdrPostLensing`; `'post'` (emitted only + * when the lens step fires) admits ONLY those. Two steps sharing one + * `(target, slab)` would otherwise collide on one GPU-timing group + * slot — `slabs.ts`'s `matchesLensPhase` is the single predicate both + * `timedSlotRowsOf` and `executeFrame` read, and + * `renderStepTimingSlotName` gives the `'post'` step's group-total + * slot a distinct name so it can't collide with `'pre'`'s. + */ + lensPhase?: 'pre' | 'post'; } | { kind: 'composite'; step: CompositeStep } | { kind: 'bloom' }; diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 2b3b497d17..a832dc4d4a 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -65,7 +65,13 @@ import type { ContentLayer } from '../../../@types/engine/frame/ContentLayer'; import type { RenderStrategy } from '../../../@types/engine/frame/RenderStrategy'; import type { SlabView } from '../../../@types/engine/frame/SlabView'; import type { GpuTimingService } from '../../../@types/gpu/timing/GpuTimingService'; -import { slabViewOf, groupKeyOf, layerTimingSlotName, renderStepTimingSlotName } from './slabs'; +import { + slabViewOf, + groupKeyOf, + layerTimingSlotName, + renderStepTimingSlotName, + matchesLensPhase, +} from './slabs'; import { encodeFlowCompute } from './encodeFlowCompute'; import { encodeAtmosphereSkyView } from './encodeAtmosphereSkyView'; import { runBloom } from './runBloom'; @@ -238,6 +244,10 @@ export function executeFrame(args: ExecuteFrameArgs): void { // going through `isBodySlabIndex` (slabs.ts) — the index-only // sibling check `frameProgram.ts` uses where no `Slab` is in hand. (l.slab === step.slab || (l.slab === 'body' && view.slab.frame.kind === 'body-m')) && + // The black-hole lens's (hdr, NEAR0) split (Task 14b): a step + // carrying `lensPhase` further narrows the group to the layers + // that opted into `hdrPostLensing` accordingly — see slabs.ts. + matchesLensPhase(l.hdrPostLensing, step.lensPhase) && l.enabled(state, stepCtx, view) && disabledPasses[l.name] !== true, ); @@ -250,8 +260,14 @@ export function executeFrame(args: ExecuteFrameArgs): void { // sky-cubemap capture's 6 faces all share `('sky-cubemap', NEAR0)`, so // the bare groupKey would look up the SAME slot for all 6 (see its doc, // slabs.ts); for every other step `step.face` is absent and this is a - // no-op passthrough of `groupKey`. - const groupKey = renderStepTimingSlotName(groupKeyOf(step.target, step.slab), step.face); + // no-op passthrough of `groupKey`. It appends a `'post'` lens-phase + // suffix the same way, so the split roster's two halves don't collide + // on one query-set slot. + const groupKey = renderStepTimingSlotName( + groupKeyOf(step.target, step.slab), + step.face, + step.lensPhase, + ); renderGroup(strategy, { encoder, ctx: stepCtx, diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index 411d46e36a..af86a3dc57 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -70,6 +70,7 @@ import { groupKeyOf, isBodySlabIndex, layerTimingSlotName, + matchesLensPhase, renderStepTimingSlotName, slabName, } from './slabs'; @@ -131,17 +132,19 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * * `sgrAStarLensingBodySlabs` (Task 14, Ruling 8) is the black-hole lens's OWN * missing step: no step here ever matched `sgrAStarLensingLayer` (`slab: - * 'body'`, `target: 'hdr'`) before this task — it registered and compiled but + * 'body'`, `target: 'hdr'`) before Task 14 — it registered and compiled but * never drew (Task 13's own recorded finding). `renderFrame` resolves Sgr * A*'s body-m row each frame and passes it here ONLY inside the fade band, so * an inactive band emits no step at all (same zero-dispatch guarantee as * `skyCubemapFacesToCapture`). One `(hdr, slab)` render step per entry, * placed after the `(hdr, NEAR0)` roster step so the lens's OVER blend - * occludes the roster light already accumulated there. It also ends up - * drawing over `orbit-trails`/`body-glints` (the SAME shared step, per - * `passes/index.ts`'s registry order) — fully keeping those two unwarped - * needs splitting that shared step, which this one new step does not do; see - * the task 14 report. + * occludes the roster light already accumulated there. A non-empty list also + * means the band is active, so the `(hdr, NEAR0)` roster step ABOVE this one + * splits into `'pre'`/`'post'` halves around it (Task 14b, Ruling 9): + * `orbit-trails`/`body-glints` opt into the `'post'` half via + * `ContentLayer.hdrPostLensing`, so they draw AFTER the lens rather than + * being sampled by it, while an inactive band leaves the roster as the one + * untagged step it always was. See `slabs.ts`'s `matchesLensPhase`. */ export function frameProgram( tone: ToneMap, @@ -200,13 +203,19 @@ export function frameProgram( // still accumulating into HDR BEFORE the tone-map composite below — one // tone curve for stars and galaxies. The hdr target is already touched // by the COSMO step above, so this pass loads rather than clears. - steps.push({ kind: 'render', target: 'hdr', slab: NEAR0 }); - - // The black-hole lens's own (hdr, BODY[k]) step(s) — see this function's - // doc for why it exists and its residual limitation. Runs after the (hdr, - // NEAR0) roster above; empty (inactive band) contributes no step. - for (const slab of sgrAStarLensingBodySlabs) { - steps.push({ kind: 'render', target: 'hdr', slab }); + // Task 14b (Ruling 9): outside the band this is the one untagged step it + // always was — byte-identical to pre-Task-14b. Inside it, the roster + // splits around the lens's own (hdr, BODY[k]) step(s) below so + // `orbit-trails`/`body-glints` (ContentLayer.hdrPostLensing) draw AFTER + // the lens instead of being sampled by it — see this function's doc. + if (sgrAStarLensingBodySlabs.length > 0) { + steps.push({ kind: 'render', target: 'hdr', slab: NEAR0, lensPhase: 'pre' }); + for (const slab of sgrAStarLensingBodySlabs) { + steps.push({ kind: 'render', target: 'hdr', slab }); + } + steps.push({ kind: 'render', target: 'hdr', slab: NEAR0, lensPhase: 'post' }); + } else { + steps.push({ kind: 'render', target: 'hdr', slab: NEAR0 }); } // Near-field foreground bodies (zoom-to-earth fold). Rendered into their @@ -332,7 +341,10 @@ export const PASS_GROUP_TITLES: Readonly> = { // buckets under one title regardless of which row Sgr A* lands in this // frame, same reasoning as the `foreground:0·BODY[k]` block below. ...Object.fromEntries( - Array.from({ length: BODY_SLAB_CAPACITY }, (_, k) => [`hdr·${slabName(k + 2)}`, 'Sgr A* lensing']), + Array.from({ length: BODY_SLAB_CAPACITY }, (_, k) => [ + `hdr·${slabName(k + 2)}`, + 'Sgr A* lensing', + ]), ), 'foreground:0·NEAR0': 'Foreground bodies · depth', // One `foreground:0·BODY[k]` row per capacity slot, derived from `slabName` @@ -371,9 +383,11 @@ function timedSlotRowsOf( // Every layer matched by this step shares the step's `(target, slab)`, so // one groupKey covers the whole run. The key comes from the shared // `groupKeyOf` helper (slabs.ts) — the same definition the merged executor - // resolves against, so the two can't drift. Every render step now has a - // distinct `(target, slab)` (the pyramid's reused-target repeats moved into - // the single `'bloom'` step), so no dedup is needed here. + // resolves against, so the two can't drift. Two render steps can now + // share one `(target, slab)` — the black-hole lens's `'pre'`/`'post'` + // roster split (Task 14b) — but never share a LAYER (`matchesLensPhase` + // partitions the registry between them), so no per-layer dedup is + // needed; only the group-TOTAL row below needs the split disambiguated. const groupKey = groupKeyOf(step.target, step.slab); for (const layer of layers) { // A 'body' layer has no fixed slab index — it matches every body-row @@ -384,7 +398,11 @@ function timedSlotRowsOf( // same fact (slabs.ts). const matchesStep = layer.slab === step.slab || (layer.slab === 'body' && isBodySlabIndex(step.slab)); - if (layer.target === step.target && matchesStep) { + if ( + layer.target === step.target && + matchesStep && + matchesLensPhase(layer.hdrPostLensing, step.lensPhase) + ) { // `layerTimingSlotName` carries the row into the slot NAME for a body // step, so two body rows sharing one layer (Jupiter + a moon, both // drawn by `planetsLayer`) each get their own query-set slot instead @@ -402,11 +420,13 @@ function timedSlotRowsOf( // pass, so no timing is billed against it). `groupKey` is unique per step // for every ordinary render step (each has a distinct `(target, slab)`) // and never collides with a layer name — EXCEPT the sky-cubemap capture - // steps, which share `('sky-cubemap', NEAR0)` across all 6 faces; - // `renderStepTimingSlotName` appends the face there so each still earns - // its own slot (see its doc, slabs.ts). The DebugPanel bucket still uses - // the shared `groupKey`, so all 6 land under one "Sky capture" group. - rows.push({ name: renderStepTimingSlotName(groupKey, step.face), groupKey }); + // steps (share `('sky-cubemap', NEAR0)` across all 6 faces) and the + // lens's `'pre'`/`'post'` roster split (share `('hdr', NEAR0)`); + // `renderStepTimingSlotName` appends the face or the `'post'` phase + // there so each still earns its own slot (see its doc, slabs.ts). The + // DebugPanel bucket still uses the shared `groupKey`, so all 6 capture + // faces — and both split halves — land under one title each. + rows.push({ name: renderStepTimingSlotName(groupKey, step.face, step.lensPhase), groupKey }); } else if (step.kind === 'composite') { // A composite merges whole textures rather than projecting geometry — it // belongs to no slab, and all composites share the one infra group. diff --git a/src/services/engine/frame/passes/bodyGlintsLayer.ts b/src/services/engine/frame/passes/bodyGlintsLayer.ts index fbe2e1f189..13cd7bb153 100644 --- a/src/services/engine/frame/passes/bodyGlintsLayer.ts +++ b/src/services/engine/frame/passes/bodyGlintsLayer.ts @@ -162,6 +162,11 @@ export const bodyGlintsLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', + // Opts into the black-hole lens's `'post'` split half (Task 14b, Ruling 9) + // so this layer's own Sgr A* far-field marker (and any solar-system glint + // that happens to overlap it on screen) draws unwarped ON TOP of the lens + // rather than being sampled by it — see frameProgram.ts's step-split doc. + hdrPostLensing: true, enabled(state, ctx, _view) { // Handle first (short-circuits before any ctx / state.data read — matches diff --git a/src/services/engine/frame/passes/index.ts b/src/services/engine/frame/passes/index.ts index 22d1d35ba3..aace9862d0 100644 --- a/src/services/engine/frame/passes/index.ts +++ b/src/services/engine/frame/passes/index.ts @@ -41,9 +41,12 @@ * star-points, star-catalog, star-upsample, constellations, orbit-trails, * body-glints); `star-aggregates` has its OWN `(star-aggregates, NEAR0)` render * step into the half-res offscreen `star-upsample` composites back, and - * `sgr-a-star-lensing` has its OWN `(hdr, BODY[k])` render step (Task 14) — its - * position below is registry-order documentation, not the mechanism that keeps - * it after the roster and before orbit-trails/body-glints; see `frameProgram.ts`: + * `sgr-a-star-lensing` has its OWN `(hdr, BODY[k])` render step (Task 14). Its + * position below is registry-order documentation for items 10-15 — but for + * orbit-trails/body-glints (17/17b) the ordering IS enforced, by + * `ContentLayer.hdrPostLensing` splitting the shared `(hdr, NEAR0)` step + * around the lens step whenever the band is active (Task 14b, Ruling 9); see + * `frameProgram.ts`: * * 10. milky-way — star/dust point cloud at the galactic centre * (the fixed 10 kpc COSMO near plane clipped the @@ -79,16 +82,19 @@ * NEAR0)` roster step above so it draws over items * 10-15 * 17. orbit-trails — accurate Keplerian orbit trails (Earth / Jupiter / - * Moon) as screen-space conics with a brightness + * Moon, and the 39 bound S-stars orbiting Sgr A* + * itself) as screen-space conics with a brightness * lobe at the body's position (f64 compose seam); - * moved here (from between 11 and 13) so it draws - * unwarped over the lens pass, per spec "Draw order" + * opts into the lens's `'post'` split half + * (`hdrPostLensing`) so it draws unwarped over the + * lens pass whenever the band is active, per spec + * "Draw order" (Task 14b, Ruling 9) * 17b. body-glints — the sub-pixel bodies (the glints branch of the body * partition) as brightness-scaled additive points * (size x albedo x phase, cross-fading with the mesh * over 1-3 px), sibling of star-points (f64 rebase - * seam); moved alongside orbit-trails for the same - * reason + * seam); opts into the lens's `'post'` split half + * for the same reason * * The next six are premultiplied-OVER overlays, projected through the * cosmological slab (except near0-selection-ring, which rides near0) and drawn @@ -339,10 +345,13 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // light already accumulated behind them) and BEFORE orbit-trails/body-glints // below (so those stay unwarped on top, spec "Draw order", Q5). Registry // order alone can't enforce this against `orbit-trails`/`body-glints` — they - // share this SAME (hdr, NEAR0) render step with the roster above, so their - // relative draw order actually comes from `frameProgram`'s own step order - // (see its module header) wedging a dedicated (hdr, BODY[k]) step here; this - // array position is the documentation of that intent, not its enforcement. + // share this SAME (hdr, NEAR0) render step with the roster above. The real + // enforcement is `ContentLayer.hdrPostLensing` (Task 14b, Ruling 9): those + // two opt in, so `frameProgram` splits the shared step into `'pre'`/`'post'` + // halves around this row's own `(hdr, BODY[k])` step whenever the band is + // active (see its module header); this array position stays the + // documentation of the intent, registry order deciding each half's internal + // ordering. sgrAStarLensingLayer, orbitTrailsLayer, // The sub-pixel bodies (the glints branch of the body partition) as diff --git a/src/services/engine/frame/passes/orbitTrailsLayer.ts b/src/services/engine/frame/passes/orbitTrailsLayer.ts index 615cb003a0..3dfa2382dc 100644 --- a/src/services/engine/frame/passes/orbitTrailsLayer.ts +++ b/src/services/engine/frame/passes/orbitTrailsLayer.ts @@ -91,6 +91,12 @@ export const orbitTrailsLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', + // 39 bound S-star trails orbit Sgr A* and cull in exactly when the + // black-hole lens's band is active (bodyRegions.ts's galactic-centre + // region) — this opts the layer into the lens's `'post'` split half so + // they draw unwarped ON TOP of it rather than being sampled by it + // (Task 14b, Ruling 9; see frameProgram.ts's step-split doc). + hdrPostLensing: true, enabled(state, ctx, _view) { if (state.gpu.orbitTrailRenderer === null) return false; diff --git a/src/services/engine/frame/slabs.ts b/src/services/engine/frame/slabs.ts index cc734cd02e..6f4758f76b 100644 --- a/src/services/engine/frame/slabs.ts +++ b/src/services/engine/frame/slabs.ts @@ -114,8 +114,34 @@ export function layerTimingSlotName(layerName: string, slabIndex: number): strin * `executeFrame`'s merged pass must resolve the identical name via * `descriptorFor`, so both call this rather than templating `·FACE[n]` twice. */ -export function renderStepTimingSlotName(groupKey: string, face: number | undefined): string { - return face === undefined ? groupKey : `${groupKey}·FACE[${face}]`; +export function renderStepTimingSlotName( + groupKey: string, + face: number | undefined, + lensPhase?: 'pre' | 'post', +): string { + if (face !== undefined) return `${groupKey}·FACE[${face}]`; + // Only 'post' needs disambiguating: 'pre' keeps the bare groupKey because + // no frame ever emits an untagged (hdr, NEAR0) step alongside it (the + // split is all-or-nothing per frame — see frameProgram.ts) — so 'pre' and + // the untagged single-step case can safely share one name. + return lensPhase === 'post' ? `${groupKey}·POST_LENSING` : groupKey; +} + +/** + * The Task 14b (Ruling 9) lens-phase gate: whether a layer belongs to a + * render step's group, given the step's `lensPhase` (FrameStep.d.ts). Single- + * sourced here because `frameProgram.ts`'s `timedSlotRowsOf` (the derived + * timing-slot list) and `executeFrame`'s group filter (the actual draw + * selection) must never disagree on which layers a `'pre'`/`'post'` step + * selects — a drift would either draw a layer the timing list never billed, + * or bill a slot for a layer that never drew. + */ +export function matchesLensPhase( + hdrPostLensing: true | undefined, + stepLensPhase: 'pre' | 'post' | undefined, +): boolean { + if (stepLensPhase === undefined) return true; + return stepLensPhase === 'post' ? hdrPostLensing === true : hdrPostLensing !== true; } /** diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index 29cc9ffd06..9f4b2a02da 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -123,6 +123,9 @@ function makeLayer(init: { // Ruling 6: opts this fixture layer into the sky-cubemap capture roster — // see `ContentLayer.skyCapture`'s doc. skyCapture?: true; + // Task 14b (Ruling 9): opts this fixture layer into the black-hole lens's + // 'post' step split half — see `ContentLayer.hdrPostLensing`'s doc. + hdrPostLensing?: true; }): SpyLayer { return { name: init.name, @@ -130,6 +133,7 @@ function makeLayer(init: { target: init.target, blend: 'additive', ...(init.skyCapture ? { skyCapture: true as const } : {}), + ...(init.hdrPostLensing ? { hdrPostLensing: true as const } : {}), enabled: vi.fn((_state, _ctx, view) => init.enabledFor ? init.enabledFor(view) : (init.enabled ?? true), ), @@ -809,7 +813,9 @@ describe('executeFrame', () => { // capture step via the flag alone. it("selects a capture step group by the skyCapture flag, ignoring the layer's own target", () => { const layer = makeLayer({ name: 'roster', target: 'hdr', slab: NEAR0, skyCapture: true }); - const program: FrameStep[] = [{ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 3 }]; + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 3 }, + ]; const faceCtx = makeCtx(); const { args, env } = makeArgs({ program, @@ -826,7 +832,9 @@ describe('executeFrame', () => { it('never selects a capture step group by target alone — a layer targeting sky-cubemap without the flag is skipped', () => { const layer = makeLayer({ name: 'unflagged', target: 'sky-cubemap', slab: NEAR0 }); - const program: FrameStep[] = [{ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }]; + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }, + ]; const faceCtx = makeCtx(); const { args } = makeArgs({ program, @@ -848,4 +856,48 @@ describe('executeFrame', () => { expect(layer.draw).not.toHaveBeenCalled(); }); }); + + describe('black-hole lens (hdr, NEAR0) roster split (Task 14b, Ruling 9)', () => { + // A step's `lensPhase` narrows the (target, slab) group by + // `ContentLayer.hdrPostLensing` — 'pre' excludes flagged layers, 'post' + // admits only them. This is the mechanism that keeps orbit-trails/ + // body-glints drawing AFTER the lens step instead of under it. + it("a 'pre' step excludes hdrPostLensing layers; a 'post' step draws only them", () => { + const roster = makeLayer({ name: 'roster', target: 'hdr', slab: NEAR0 }); + const trails = makeLayer({ + name: 'orbit-trails', + target: 'hdr', + slab: NEAR0, + hdrPostLensing: true, + }); + const program: FrameStep[] = [ + { kind: 'render', target: 'hdr', slab: NEAR0, lensPhase: 'pre' }, + { kind: 'render', target: 'hdr', slab: NEAR0, lensPhase: 'post' }, + ]; + const { args } = makeArgs({ program, layers: [roster, trails] }); + executeFrame(args); + expect(roster.draw).toHaveBeenCalledTimes(1); + expect(trails.draw).toHaveBeenCalledTimes(1); + // Each drew into a DIFFERENT pass — the 'pre'/'post' split opens two + // passes even though both steps share (target: 'hdr', slab: NEAR0). + expect(roster.draw.mock.calls[0]![0]).not.toBe(trails.draw.mock.calls[0]![0]); + }); + + it('a step with no lensPhase draws every matching layer regardless of hdrPostLensing — the untagged, outside-the-band shape', () => { + const roster = makeLayer({ name: 'roster', target: 'hdr', slab: NEAR0 }); + const trails = makeLayer({ + name: 'orbit-trails', + target: 'hdr', + slab: NEAR0, + hdrPostLensing: true, + }); + const program: FrameStep[] = [{ kind: 'render', target: 'hdr', slab: NEAR0 }]; + const { args } = makeArgs({ program, layers: [roster, trails] }); + executeFrame(args); + expect(roster.draw).toHaveBeenCalledTimes(1); + expect(trails.draw).toHaveBeenCalledTimes(1); + // Both drew into the SAME single pass — one untagged step, one group. + expect(roster.draw.mock.calls[0]![0]).toBe(trails.draw.mock.calls[0]![0]); + }); + }); }); diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index 52bd270fff..21da534281 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -269,6 +269,25 @@ describe('frameProgram', () => { expect(withDefault).toEqual(base); expect(withEmpty).toEqual(base); expect(base.some((step) => step.kind === 'render' && step.slab >= 2)).toBe(false); + // Task 14b (Ruling 9): the split discriminant must not leak outside the + // band either — the (hdr, NEAR0) step stays the single untagged step it + // always was, byte-identical to pre-Task-14b. + expect(base.some((step) => step.kind === 'render' && 'lensPhase' in step)).toBe(false); + }); + + it('sgrAStarLensingBodySlabs active: orbit-trails/body-glints move to their own step AFTER the lens step (Task 14b, Ruling 9)', () => { + // Ruling 9's evidenced gap: orbit-trails and body-glints (the S-star + // trails and the Sgr A* far-field glint among them) used to share the + // pre-lens (hdr, NEAR0) roster step and so drew UNDER the lens's OVER + // blend. `ContentLayer.hdrPostLensing` moves them into a step that runs + // after the lens's own (hdr, BODY[k]) step instead — checked here + // against the REAL registry, so a missing flag on either layer (they'd + // stay in 'pre', ahead of the lens) fails this. + const slots = timedSlotsOf(frameProgram(TONE, false, [NEAR0], [], [4]), CONTENT_LAYERS); + const lensLayerIdx = slots.indexOf('sgr-a-star-lensing·BODY[2]'); + expect(lensLayerIdx).toBeGreaterThanOrEqual(0); + expect(slots.indexOf('orbit-trails')).toBeGreaterThan(lensLayerIdx); + expect(slots.indexOf('body-glints')).toBeGreaterThan(lensLayerIdx); }); it('bloom disabled: no bloom step emitted and program otherwise identical', () => { @@ -452,10 +471,7 @@ describe('timedSlotsOf', () => { // slab index (4, arbitrary — any body-slab index widens the same way) // must now surface its row, positioned right after the (hdr, NEAR0) // group's own slot. - const slots = timedSlotsOf( - frameProgram(TONE, false, [NEAR0], [], [4]), - CONTENT_LAYERS, - ); + const slots = timedSlotsOf(frameProgram(TONE, false, [NEAR0], [], [4]), CONTENT_LAYERS); const hdrNear0Idx = slots.indexOf('hdr·NEAR0'); expect(hdrNear0Idx).toBeGreaterThanOrEqual(0); expect(slots[hdrNear0Idx + 1]).toBe('sgr-a-star-lensing·BODY[2]'); From 46d779fa2d868d75f0d852c1e37f23129f45cd8a Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 16:39:22 +0200 Subject: [PATCH 30/60] fix(sgr-a-lensing): jitter, vertical falloff, and bent-ray annulus march MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three user-reported visual defects in the accretion-glow shader, all in-design fixes within the existing LUT/infinity-deflection architecture: - Banding: jitter the march start per pixel (hash21Hq(fragCoord)) and replace the hard inner/outer/thickness cutoffs with soft exp/smoothstep density weights, so samples fade into the annulus instead of switching on at a fixed slab boundary. - Missing vertical falloff: add a Gaussian scale-height profile (DISK_SCALE_HEIGHT_RS = 0.4 r_s) through the disk's thickness. - Unlensed disk image: two-segment bent-ray approximation — segment 1 marches the straight camera ray to closest approach, segment 2 bends by the LUT's deflection angle and continues from there. Reuses the same axis/rotation the escape branch already computes for its sky sample, so both consumers share one basis. Captured rays keep the straight march and terminate black, unchanged. Step budget stays at 48 total (24 per segment). No uniform-struct changes. Co-Authored-By: Claude Fable 5 --- .../bodies/sgrAStarLensing/fragment.wesl | 136 ++++++++++++------ 1 file changed, 89 insertions(+), 47 deletions(-) diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index cc550f33c7..9eb7c3772f 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -12,6 +12,7 @@ import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; import package::lib::math::rotateAroundAxis; import package::lib::math::saturate; import package::lib::math::TAU; +import package::lib::util::hash21Hq; @group(0) @binding(0) var u: SgrAStarLensingUniforms; @group(0) @binding(1) var lutTex: texture_2d; @@ -27,7 +28,10 @@ struct FsIn { const CAPTURE_THRESHOLD_RAD: f32 = 500.0; const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound -const DISK_HALF_THICKNESS_RS: f32 = 0.15; // thin-disk approximation, tuned for looks +// Split across the bent-ray march's two segments (Task 13c finding 3). +const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; +const DISK_SCALE_HEIGHT_RS: f32 = 0.4; // vertical falloff scale height, thin-disk taste (T15 tuning knob) +const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // inner/outer annulus edge softening width const DOPPLER_STRENGTH: f32 = 0.6; // tuned for looks — see BLACK_HOLES's own "visual taste" note // Two-tap manual lerp (r32float isn't sampler-filterable without the @@ -58,58 +62,93 @@ fn diskNormal() -> vec3 { return normalize(rotateAroundAxis(tilted, vec3(0.0, 1.0, 0.0), u.positionAngleRad)); } +// Per-sample density is the product of two SOFT profiles (findings 1 & 2) +// instead of hard cutoffs, so a sample easing into the annulus fades in +// rather than switching on. 'viewDir' is the local ray direction at 'p' +// (straight in segment 1, bent in segment 2) — Doppler beaming reads off +// whichever way the photon is actually travelling there. +fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3, stepLenM: f32) -> vec4 { + let distToPlaneRs = dot(p, normal) / u.schwarzschildRadiusM; + let verticalWeight = exp(-(distToPlaneRs * distToPlaneRs) / (DISK_SCALE_HEIGHT_RS * DISK_SCALE_HEIGHT_RS)); + if (verticalWeight < 1e-3) { + return vec4(0.0); + } + + let inPlane = p - normal * dot(p, normal); + let radialM = length(inPlane); + let radialRs = radialM / u.schwarzschildRadiusM; + let radialWeight = smoothstep(u.innerRs - RADIAL_EDGE_FEATHER_RS, u.innerRs + RADIAL_EDGE_FEATHER_RS, radialRs) + * (1.0 - smoothstep(u.outerRs - RADIAL_EDGE_FEATHER_RS, u.outerRs + RADIAL_EDGE_FEATHER_RS, radialRs)); + if (radialWeight < 1e-3) { + return vec4(0.0); + } + + let radialDir = inPlane / max(radialM, 1e-6); + let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point + let dopplerFactor = 1.0 + DOPPLER_STRENGTH * dot(orbitDir, -viewDir); + // Kepler period ~ r^1.5: a cheap per-radius phase offset (closer annuli + // lead the outer ones), not a fitted light curve — visual taste, as above. + let periodScale = pow(max(radialRs, 0.1), 1.5); + let localPhase = u.flickerPhase + (radialRs / periodScale) * TAU; + let flicker = 1.0 + u.flickerAmp * sin(localPhase); + let redshift = 1.0 / sqrt(max(1.0 - 1.0 / radialRs, 0.05)); + let heat = saturate(1.0 - (radialRs - u.innerRs) / max(u.outerRs - u.innerRs, 1e-6)); + let tint = mix(vec3(1.0, 0.45, 0.15), vec3(1.0, 0.85, 0.65), heat); + let falloff = 1.0 / max(radialRs * radialRs, 1.0); // radial profile: brightest at the inner edge, EHT-style + + let density = verticalWeight * radialWeight; + let contribution = falloff * flicker * dopplerFactor * redshift * density * (stepLenM / u.schwarzschildRadiusM); + return vec4(tint * contribution, saturate(contribution)); +} + // Bounded march (spec's 32-64-step bound) for the annulus's own emission, // composited over the escape/capture base. Centred on 'closestT' (the ray's -// own closest approach to the hole, computed once in 'fs') rather than on -// t=0 (the camera): the hole sits at 'length(toAnchor)' from the camera, -// almost always far outside a 't in [0, marchHalfM]' window sized off -// 'outerRs', so marching from the camera would miss the disk for virtually -// the whole fade band. Returns (linear emission, coverage); coverage feeds -// the caller's alpha, not the light itself. -fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32) -> vec4 { +// own closest approach) rather than t=0 (the camera) — the hole sits far +// outside a march window sized off 'outerRs' otherwise. + +// Two-segment bent-ray approximation (finding 3): segment 1 walks the +// straight camera ray to closest approach; segment 2 continues from that +// kink along 'deflectedDir', the same rotated direction the escape branch +// samples the sky with. A captured ray has no LUT deflection to bend by, so +// it stays on segment 1 for the full budget and plunges to the horizon, +// same as before this fix. 'jitterSeed' offsets the march start per pixel +// (finding 1); both segments share one offset since they share one step +// length. +fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflectedDir: vec3, captured: bool, jitterSeed: vec2) -> vec4 { let normal = diskNormal(); let marchHalfM = u.outerRs * u.schwarzschildRadiusM * 1.5; - let stepLenM = (2.0 * marchHalfM) / f32(MARCH_STEPS); - let halfThicknessM = DISK_HALF_THICKNESS_RS * u.schwarzschildRadiusM; + let stepLenM = marchHalfM / f32(SEGMENT_STEPS); + let jitter = hash21Hq(jitterSeed) * stepLenM; var emission = vec3(0.0); var coverage = 0.0; - for (var i = 0; i < MARCH_STEPS; i++) { - let t = max(closestT - marchHalfM + (f32(i) + 0.5) * stepLenM, 0.0); + + for (var i = 0; i < SEGMENT_STEPS; i++) { + let t = max(closestT - marchHalfM + jitter + (f32(i) + 0.5) * stepLenM, 0.0); let p = rayDir * t - toAnchor; // position relative to the hole's centre - let distToPlane = dot(p, normal); - if (abs(distToPlane) > halfThicknessM) { - continue; - } - let inPlane = p - normal * distToPlane; - let radialM = length(inPlane); - let radialRs = radialM / u.schwarzschildRadiusM; - if (radialRs < u.innerRs || radialRs > u.outerRs) { - continue; - } + let emissionSample = annulusSampleContribution(p, normal, rayDir, stepLenM); + emission += emissionSample.rgb; + coverage = max(coverage, emissionSample.a); + } - let radialDir = inPlane / max(radialM, 1e-6); - let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point - let dopplerFactor = 1.0 + DOPPLER_STRENGTH * dot(orbitDir, -rayDir); - // Kepler period ~ r^1.5: a cheap per-radius phase offset (closer annuli - // lead the outer ones), not a fitted light curve — visual taste, as above. - let periodScale = pow(max(radialRs, 0.1), 1.5); - let localPhase = u.flickerPhase + (radialRs / periodScale) * TAU; - let flicker = 1.0 + u.flickerAmp * sin(localPhase); - let redshift = 1.0 / sqrt(max(1.0 - 1.0 / radialRs, 0.05)); - let heat = saturate(1.0 - (radialRs - u.innerRs) / max(u.outerRs - u.innerRs, 1e-6)); - let tint = mix(vec3(1.0, 0.45, 0.15), vec3(1.0, 0.85, 0.65), heat); - let falloff = 1.0 / max(radialRs * radialRs, 1.0); - - let contribution = falloff * flicker * dopplerFactor * redshift * (stepLenM / u.schwarzschildRadiusM); - emission += tint * contribution; - coverage = max(coverage, saturate(contribution)); + if (captured) { + return vec4(emission, coverage); } + + let kink = rayDir * closestT; // camera-relative position at closest approach — the bend point + for (var i = 0; i < SEGMENT_STEPS; i++) { + let d = jitter + (f32(i) + 0.5) * stepLenM; + let p = kink + deflectedDir * d - toAnchor; + let emissionSample = annulusSampleContribution(p, normal, deflectedDir, stepLenM); + emission += emissionSample.rgb; + coverage = max(coverage, emissionSample.a); + } + return vec4(emission, coverage); } @fragment -fn fs(in: FsIn) -> @location(0) vec4 { +fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4 { let rayDir = normalize(in.posRelCamM); let toAnchor = u.anchorPosRelCamM; // Impact parameter: perpendicular distance from the hole to the ray @@ -128,15 +167,18 @@ fn fs(in: FsIn) -> @location(0) vec4 { alpha = u.bandAlpha; // below the LUT's own domain — deep in the capture region } else { let bendAngle = sampleLut(impactParamRs); - if (bendAngle >= CAPTURE_THRESHOLD_RAD) { + let captured = bendAngle >= CAPTURE_THRESHOLD_RAD; + // Lensing displaces the apparent background AWAY from the lens centre: + // rotate the ray away from the hole by the LUT's bend angle to recover + // the source's asymptotic direction (sign/axis unverified visually, + // Task 17 gate). Reused below as the annulus march's segment-2 bend + // (finding 3) — one basis for both consumers. + let axis = normalize(cross(rayDir, toAnchor)); + let deflected = normalize(rotateAroundAxis(rayDir, axis, -bendAngle)); + + if (captured) { alpha = u.bandAlpha; } else { - // Lensing displaces the apparent background AWAY from the lens centre - // (Einstein-ring displacement): rotate the ray away from the hole by - // the LUT's bend angle to recover the source's asymptotic direction. - // Sign/axis unverified visually (Task 17 gate); flip if it reads backward. - let axis = normalize(cross(rayDir, toAnchor)); - let deflected = normalize(rotateAroundAxis(rayDir, axis, -bendAngle)); color = textureSampleLevel(skyTex, skySampler, deflected, 0.0).rgb; // Soft edge fade to the billboard's rim so the earlier-drawn roster @@ -145,7 +187,7 @@ fn fs(in: FsIn) -> @location(0) vec4 { alpha = u.bandAlpha * edgeFade; } - let annulus = annulusEmission(rayDir, toAnchor, closestT); + let annulus = annulusEmission(rayDir, toAnchor, closestT, deflected, captured, fragCoord.xy); color += annulus.rgb; alpha = max(alpha, u.bandAlpha * annulus.a); } From a99d2412ae8635e36e93e3f2902fe8e70dbd4a62 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 16:53:02 +0200 Subject: [PATCH 31/60] =?UTF-8?q?feat(black-hole):=20viewSlot=20=E2=80=94?= =?UTF-8?q?=20sky-cubemap=20capture=20actually=20draws=20(Task=2013b)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The capture sweep records several draw() calls (per-face synthetic contexts + the real view) before one submit(); the three roster renderers each wrote one shared per-frame buffer, so only the last call's camera survived (docs/RENDERER.md landmine #1). ReadyFrameContext grows `viewSlot` (0 = main view, 1-6 = a capture face), and a new view-slot buffer ring (src/utils/gpu/createViewSlotUniformRing.ts — one physical buffer + bind group per slot, chosen over dynamic offsets so the canonical fade/source bind-group layouts stay untouched) keys galaxyPointRenderer's uniform + per-catalog fade buffers, starPointRenderer's uniform + instance buffers, and starCatalogRenderer's camera uniform + per-(source,stream) NodeParams/ prefix buffer pairs. point-sprites, star-catalog, star-aggregates, and star-points now carry skyCapture: true. frameProgram also widens to emit a COSMO capture step alongside the existing NEAR0 one per requested face — point-sprites lives on COSMO, so without it the flag had no effect (the capture step never selected it). Co-Authored-By: Claude Fable 5 --- .../engine/frame/ReadyFrameContext.d.ts | 14 ++ .../rendering/GalaxyPointDrawSettings.d.ts | 10 +- src/@types/rendering/StarCatalogRenderer.d.ts | 9 ++ src/@types/rendering/StarPointRenderer.d.ts | 24 ++-- src/@types/rendering/ViewSlotUniformRing.d.ts | 16 +++ src/services/engine/frame/frameContext.ts | 3 + src/services/engine/frame/frameProgram.ts | 31 +++-- .../frame/passes/galaxyPointSpritesLayer.ts | 6 + .../frame/passes/starAggregatesLayer.ts | 16 ++- .../engine/frame/passes/starCatalogLayer.ts | 7 +- .../engine/frame/passes/starPointsLayer.ts | 8 +- .../engine/frame/skyCubemapFaceContext.ts | 6 +- .../engine/gpuHandles/gpuHandleRegistry.ts | 4 + .../gpu/renderers/bodies/starPointRenderer.ts | 105 ++++++++------ .../renderers/galaxyCatalog/catalogStore.ts | 44 +++--- .../galaxyCatalog/galaxyPointRenderer.ts | 68 +++++---- .../starCatalog/starCatalogRenderer.ts | 86 +++++++----- src/utils/gpu/createViewSlotUniformRing.ts | 75 ++++++++++ src/utils/gpu/packGalaxyPointUniforms.ts | 17 ++- .../engine/frame/frameContext.test.ts | 17 +++ .../engine/frame/frameProgram.test.ts | 31 +++++ .../frame/passes/clipPathDebugLayer.test.ts | 1 + .../frame/passes/createUpsampleLayer.test.ts | 1 + .../frame/passes/filamentsLayer.test.ts | 1 + .../frame/passes/flowFieldLayer.test.ts | 1 + .../engine/frame/passes/passes.test.ts | 7 +- .../frame/passes/proceduralDisksLayer.test.ts | 1 + .../frame/passes/selectionRingLayer.test.ts | 1 + .../frame/passes/texturedDisksLayer.test.ts | 1 + .../frame/passes/volumeUpsampleLayer.test.ts | 1 + .../services/engine/frame/renderFrame.test.ts | 1 + .../frame/skyCubemapFaceContext.test.ts | 4 + tests/services/engine/frame/slabs.test.ts | 1 + .../bodies/starPointRenderer.test.ts | 70 ++++++++-- .../galaxyCatalog/galaxyPointRenderer.test.ts | 102 +++++++++++--- .../starCatalogRenderer.frustumCull.test.ts | 1 + .../starCatalogRenderer.viewSlot.test.ts | 131 ++++++++++++++++++ .../shaders/milkyWayPickUniformParity.test.ts | 1 + .../gpu/createViewSlotUniformRing.test.ts | 97 +++++++++++++ .../utils/gpu/packGalaxyPointUniforms.test.ts | 3 + 40 files changed, 830 insertions(+), 193 deletions(-) create mode 100644 src/@types/rendering/ViewSlotUniformRing.d.ts create mode 100644 src/utils/gpu/createViewSlotUniformRing.ts create mode 100644 tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts create mode 100644 tests/utils/gpu/createViewSlotUniformRing.test.ts diff --git a/src/@types/engine/frame/ReadyFrameContext.d.ts b/src/@types/engine/frame/ReadyFrameContext.d.ts index 25587946b3..b74e6230e1 100644 --- a/src/@types/engine/frame/ReadyFrameContext.d.ts +++ b/src/@types/engine/frame/ReadyFrameContext.d.ts @@ -107,6 +107,20 @@ export type ReadyFrameContext = { simDays: number; /** Vertical field-of-view in radians (`cam.fovYRad`) — the source `drawPxPerRad` is derived from. */ fovYRad: number; + /** + * Which physical GPU destination this frame's draws land in: `0` = the + * main view, `1..6` = a black-hole sky-cubemap capture face (`face + 1`, + * `skyCubemapFaceContext`). A capture sweep records several `draw()` calls + * against DIFFERENT synthetic contexts before one `submit()` — the + * `queue.writeBuffer`-before-`submit` landmine (docs/RENDERER.md #1) means a + * renderer-owned buffer shared across those calls would keep only the LAST + * write. A roster renderer keys its per-frame writes on this field (via a + * view-slot buffer helper, `src/utils/gpu/`) instead of overwriting one + * shared destination, so each call's bytes survive to its own draw. + * `deriveFrameContext` stamps `0`; only `skyCubemapFaceContext` stamps a + * face slot. + */ + viewSlot: number; /** Structure-focus recession blend 0→1, from structureFocus.produceFocusUniforms (ticked once/frame). */ focusBlend: number; /** Galaxy-catalog draw mask (deriveSourceMasks(state).draw), this frame. */ diff --git a/src/@types/rendering/GalaxyPointDrawSettings.d.ts b/src/@types/rendering/GalaxyPointDrawSettings.d.ts index caca942020..4a4d396db4 100644 --- a/src/@types/rendering/GalaxyPointDrawSettings.d.ts +++ b/src/@types/rendering/GalaxyPointDrawSettings.d.ts @@ -55,9 +55,17 @@ export type GalaxyPointDrawSettings = { * Look up the registry-managed opacity for a given source. Called * once per visible source per frame from the points draw loop; * the renderer writes the returned value into the per-source - * fadeBuffer. The renderer passes the numeric source code; + * fade ring's `viewSlot` slot. The renderer passes the numeric source code; * the `galaxyPointSpritesLayer` closure resolves it to the catalog's string * id and reads `state.subsystems.fades.opacityOf({ kind: 'galaxyCatalog', id }, now)`. */ readonly fadeOpacityOf: (source: SourceType) => number; + /** + * `ReadyFrameContext.viewSlot` — which view-slot buffer this call's + * per-frame uniform/fade writes land in (Task 13b). `0` for the main view; + * `1..6` for a sky-cubemap capture face. Lets several `draw()` calls with + * different cameras share one submit without one overwriting another's + * bytes before the GPU reads them (see `createViewSlotUniformRing`'s doc). + */ + viewSlot: number; }; diff --git a/src/@types/rendering/StarCatalogRenderer.d.ts b/src/@types/rendering/StarCatalogRenderer.d.ts index 6cab8a82f9..f9b7121274 100644 --- a/src/@types/rendering/StarCatalogRenderer.d.ts +++ b/src/@types/rendering/StarCatalogRenderer.d.ts @@ -189,6 +189,15 @@ export type StarCatalogDrawArgs = { * Ignored for aggregate nodes, whose glow spills a world (not angular) slack. */ readonly glowMarginAngleRad: number; + /** + * `ReadyFrameContext.viewSlot` (Task 13b) — which view-slot's camera + * uniform + NodeParams/prefix buffer PAIR this call's writes land in. `0` + * for the main view; `1..6` for a sky-cubemap capture face. A capture + * sweep calls `draw` once per face plus once for the real view, all before + * one `submit()`, so each call needs its own destination (see + * `createViewSlotUniformRing`'s doc for the race this closes). + */ + readonly viewSlot: number; }; /** diff --git a/src/@types/rendering/StarPointRenderer.d.ts b/src/@types/rendering/StarPointRenderer.d.ts index e825dd2d90..fec00f29a0 100644 --- a/src/@types/rendering/StarPointRenderer.d.ts +++ b/src/@types/rendering/StarPointRenderer.d.ts @@ -25,13 +25,17 @@ import type { PositionedStar } from '../scene/PositionedStar'; export type StarPointRenderer = Renderer & { /** - * Upload the instance buffer from the seeded star bodies — position - * (`positionMpc` narrowed to f32, camera-relative per the layer's rebase), - * linear-RGB `color`, and `absMag` per star, 28 bytes each. Replaces any - * previous upload; an empty array clears the renderer back to drawing - * nothing. + * Upload `viewSlot`'s instance buffer from the seeded star bodies — + * position (`positionMpc` narrowed to f32, camera-relative per the + * layer's rebase), linear-RGB `color`, and `absMag` per star, 28 bytes + * each. Replaces any previous upload ON THAT SLOT; an empty array clears + * the slot back to drawing nothing. `viewSlot` (Task 13b) gives each + * sky-cubemap capture face — and the real view — its OWN buffer, because + * their camera-relative positions differ and all calls land before one + * `submit()` (see `createViewSlotUniformRing`'s doc for the race this + * avoids). */ - setStars(stars: readonly PositionedStar[]): void; + setStars(stars: readonly PositionedStar[], viewSlot: number): void; /** * Draw every uploaded star as an instanced billboard into the current * (depthless, additive) pass. `viewProj` is the length-16 view-projection @@ -40,13 +44,17 @@ export type StarPointRenderer = Renderer & { * the shared star appearance the survey stage also reads — `sizePx` (base * dot radius, the `starCatalogs.sizePx` slider) and `brightness` (the exposure * trim, already folded with the camera-distance ramp by the layer) — so a - * famous leaf and a survey leaf render pixel-identically. No-op until + * famous leaf and a survey leaf render pixel-identically. `viewSlot` is + * `ReadyFrameContext.viewSlot` (Task 13b) — which view-slot buffer this + * call's camera uniform lands in, so a sky-cubemap capture sweep's several + * `draw()` calls (different cameras, one submit) don't overwrite each + * other's bytes (see `createViewSlotUniformRing`'s doc). No-op until * `setStars` has delivered a non-empty upload. */ draw( pass: GPURenderPassEncoder, viewProj: Float32Array, viewportPx: Vec2, - opts: { sizePx: number; brightness: number }, + opts: { sizePx: number; brightness: number; viewSlot: number }, ): void; }; diff --git a/src/@types/rendering/ViewSlotUniformRing.d.ts b/src/@types/rendering/ViewSlotUniformRing.d.ts new file mode 100644 index 0000000000..6aecddac0f --- /dev/null +++ b/src/@types/rendering/ViewSlotUniformRing.d.ts @@ -0,0 +1,16 @@ +/** + * ViewSlotUniformRing — a fixed-size uniform buffer, multiplexed across the + * frame's view slots (`ReadyFrameContext.viewSlot`) so a sky-cubemap capture + * sweep's several `draw()` calls (different synthetic contexts, one shared + * `submit()`) never overwrite each other's bytes before the GPU reads them — + * see `createViewSlotUniformRing`'s doc for the write-before-submit race this + * exists to close. + */ +export type ViewSlotUniformRing = { + /** Upload `data` into `slot`'s own physical buffer, immediately. */ + writeSlot(slot: number, data: BufferSource): void; + /** The bind group bound to `slot`'s own physical buffer. */ + bindGroupOf(slot: number): GPUBindGroup; + /** Release every slot's buffer. */ + destroy(): void; +}; diff --git a/src/services/engine/frame/frameContext.ts b/src/services/engine/frame/frameContext.ts index e69d0031d7..7698ba92ed 100644 --- a/src/services/engine/frame/frameContext.ts +++ b/src/services/engine/frame/frameContext.ts @@ -303,6 +303,9 @@ export function deriveFrameContext( nowMs, simDays, fovYRad: cam.fovYRad, + // The main view. `skyCubemapFaceContext` overrides this to `face + 1` on + // the contexts it derives — see `ReadyFrameContext.viewSlot`'s doc. + viewSlot: 0, focusBlend: 0, visibleSourceMask, focus: ZERO_FOCUS, diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index af86a3dc57..7d817da8fc 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -118,17 +118,17 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * the capture side of that contract, not just the lensing draw itself). * Placed in the compute prelude's wake, ahead of every other render step, so * a same-frame lensing draw (Task 13) can sample a cubemap this frame - * actually wrote. One step per requested face, at the NEAR0 slab — the - * fixed opt-in roster (`ContentLayer.skyCapture`, Ruling 6) is selected by - * that flag rather than by `target` (see `executeFrame`'s capture-step - * branch), so a flagged NEAR0-slab layer is reachable here; a COSMO-slab - * candidate (`point-sprites`) would need its OWN COSMO-slab capture step, - * which this program does not emit — moot today, since Task 13's - * verification found every current roster candidate's GPU renderer assumes - * at most one `draw()` call per submitted frame (the `queue.writeBuffer`/ - * `submit` landmine, docs/RENDERER.md), an invariant a multi-face capture - * sweep breaks; no layer carries `skyCapture` yet, so these steps still - * select an empty group and draw nothing pending that renderer-side fix. + * actually wrote. TWO steps per requested face — COSMO then NEAR0 — because + * the fixed opt-in roster (`ContentLayer.skyCapture`, Ruling 6) spans both + * slabs: `point-sprites` projects through COSMO, `star-catalog` / + * `star-aggregates` / `star-points` through NEAR0. A capture step selects + * its group by the flag rather than by `target` (`executeFrame`'s + * capture-step branch), but `slab` still gates normally — one step per slab + * is what makes BOTH halves of the roster reachable (Task 13b; a single + * NEAR0-only step left the COSMO half permanently unselected, the flag + * having no effect). Order (COSMO before NEAR0) mirrors the real `(hdr, + * COSMO)` → `(hdr, NEAR0)` sequence below, so the capture composites in the + * same order the live frame would. * * `sgrAStarLensingBodySlabs` (Task 14, Ruling 8) is the black-hole lens's OWN * missing step: no step here ever matched `sgrAStarLensingLayer` (`slab: @@ -166,6 +166,7 @@ export function frameProgram( steps.push({ kind: 'compute', name: 'atmosphereSkyView' }); for (const face of skyCubemapFacesToCapture) { + steps.push({ kind: 'render', target: 'sky-cubemap', slab: COSMO, face }); steps.push({ kind: 'render', target: 'sky-cubemap', slab: NEAR0, face }); } @@ -330,9 +331,11 @@ export const PASS_GROUP_TITLES: Readonly> = { 'zoa·COSMO': 'Volumes & aggregates', 'star-aggregates·NEAR0': 'Volumes & aggregates', 'mw-aggregate·NEAR0': 'Volumes & aggregates', - // The black-hole lens's amortized sky-capture steps (Task 12) — 0-6 of - // them per frame depending on `skyCubemapCaptureSchedule`, so its own - // group rather than folding into an existing title. + // The black-hole lens's amortized sky-capture steps (Task 12) — 0-12 of + // them per frame (COSMO + NEAR0 per requested face, Task 13b) depending on + // `skyCubemapCaptureSchedule`, so its own group rather than folding into + // an existing title. + 'sky-cubemap·COSMO': 'Sky capture', 'sky-cubemap·NEAR0': 'Sky capture', 'hdr·COSMO': 'Cosmos · HDR', 'hdr·NEAR0': 'Near field · HDR', diff --git a/src/services/engine/frame/passes/galaxyPointSpritesLayer.ts b/src/services/engine/frame/passes/galaxyPointSpritesLayer.ts index 086eb00107..5bfd1bbff1 100644 --- a/src/services/engine/frame/passes/galaxyPointSpritesLayer.ts +++ b/src/services/engine/frame/passes/galaxyPointSpritesLayer.ts @@ -27,6 +27,11 @@ export const galaxyPointSpritesLayer: ContentLayer = { slab: COSMO, target: 'hdr', blend: 'additive', + // Sky-cubemap capture roster (Task 13b, Ruling 6): the galaxy points are + // part of the black-hole lens's captured "sky". Draw-safe against a + // synthetic per-face ctx — every read below is `view`/`ctx`/`state`, none + // of it frame-real-camera-specific. + skyCapture: true, enabled(_state, _ctx, _view) { return true; @@ -50,6 +55,7 @@ export const galaxyPointSpritesLayer: ContentLayer = { : SELECTION_NONE_SENTINEL; galaxyPointRenderer.draw(pass, view.vp, view.viewportPx, { + viewSlot: ctx.viewSlot, pointSizePx: state.settings.galaxyCatalogs.sizePx, brightness: state.settings.galaxyCatalogs.brightness, selectedPacked, diff --git a/src/services/engine/frame/passes/starAggregatesLayer.ts b/src/services/engine/frame/passes/starAggregatesLayer.ts index 851722f13e..c3465fe03d 100644 --- a/src/services/engine/frame/passes/starAggregatesLayer.ts +++ b/src/services/engine/frame/passes/starAggregatesLayer.ts @@ -38,6 +38,12 @@ export const starAggregatesLayer: ContentLayer = { slab: NEAR0, target: 'star-aggregates', blend: 'additive', + // Sky-cubemap capture roster (Task 13b, Ruling 6): the survey AGGREGATE + // stream is part of the black-hole lens's captured "sky", drawn straight + // into the capture target (a capture step selects by this flag, not by + // `target` — see `executeFrame`'s capture-step branch) rather than through + // its usual half-res-offscreen + knee'd upsample. + skyCapture: true, enabled: starCatalogVisible, @@ -56,6 +62,14 @@ export const starAggregatesLayer: ContentLayer = { // mutated: one `SlabView` is shared by every layer in the render step. const { width: vw, height: vh } = ctx.renderTargets.sizeOf('star-aggregates'); - drawStream(renderer, pass, { ...view, viewportPx: [vw, vh] }, prep, 'aggregate', ctx.fovYRad); + drawStream( + renderer, + pass, + { ...view, viewportPx: [vw, vh] }, + prep, + 'aggregate', + ctx.fovYRad, + ctx.viewSlot, + ); }, }; diff --git a/src/services/engine/frame/passes/starCatalogLayer.ts b/src/services/engine/frame/passes/starCatalogLayer.ts index 903dff19ad..e45ee30c55 100644 --- a/src/services/engine/frame/passes/starCatalogLayer.ts +++ b/src/services/engine/frame/passes/starCatalogLayer.ts @@ -870,6 +870,7 @@ function drawStream( prep: PreparedStarCut, stream: StarDrawStream, fovYRad: number, + viewSlot: number, ): void { const rebasedVp = narrowMat4(rebaseViewProj(view.slab.vp, view.camPos)); // Extract the six clip planes ONCE from the SAME rebased vp the draws use — the @@ -900,6 +901,7 @@ function drawStream( aggregateIntensityCap: prep.aggregateIntensityCap, frustumPlanes, glowMarginAngleRad, + viewSlot, }); } } @@ -911,6 +913,9 @@ export const starCatalogLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', + // Sky-cubemap capture roster (Task 13b, Ruling 6): the survey LEAF stream + // is part of the black-hole lens's captured "sky". + skyCapture: true, enabled: starCatalogVisible, @@ -920,7 +925,7 @@ export const starCatalogLayer: ContentLayer = { const prep = prepareStarCut(state, ctx); if (prep === null) return; // The LEAF stream: full-resolution point stars into HDR, per-glow knee. - drawStream(renderer, pass, view, prep, 'leaf', ctx.fovYRad); + drawStream(renderer, pass, view, prep, 'leaf', ctx.fovYRad, ctx.viewSlot); }, // Pick aspect — stamps every visible LEAF star's packed identity into the diff --git a/src/services/engine/frame/passes/starPointsLayer.ts b/src/services/engine/frame/passes/starPointsLayer.ts index 4a1ba1cb48..4814450f0b 100644 --- a/src/services/engine/frame/passes/starPointsLayer.ts +++ b/src/services/engine/frame/passes/starPointsLayer.ts @@ -139,6 +139,10 @@ export const starPointsLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', + // Sky-cubemap capture roster (Task 13b, Ruling 6): the S-star partition + // branch is part of the black-hole lens's captured "sky" — NOT + // body-glints, whichever branch the S-stars fall into at capture range. + skyCapture: true, enabled(state, ctx, _view) { // Handle first, distance second, backdrop-band third, partition last — @@ -237,7 +241,7 @@ export const starPointsLayer: ContentLayer = { star.color[2] * backdropFade, ] as Vec3, })); - renderer.setStars(rebasedPoints); + renderer.setStars(rebasedPoints, ctx.viewSlot); // Fold the eye offset into the vp so it pairs with the camera-relative // anchors. Uses the slab's f64 `vp`, NOT the f32-narrowed `view.vp` — @@ -263,7 +267,7 @@ export const starPointsLayer: ContentLayer = { state.settings.starCatalogs.exposureMidX, state.settings.starCatalogs.exposureFarX, ); - renderer.draw(pass, rebasedVp, view.viewportPx, { sizePx, brightness }); + renderer.draw(pass, rebasedVp, view.viewportPx, { sizePx, brightness, viewSlot: ctx.viewSlot }); }, // Pick aspect — stamps the POINT-partition scene stars into the NEAR0 r32uint diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts index eed285935a..ff4c174895 100644 --- a/src/services/engine/frame/skyCubemapFaceContext.ts +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -107,5 +107,9 @@ export function skyCubemapFaceContext(input: { performance.now(), state.cameraRuntime.lastRenderedSimDays.current, ); - return ctx.isReady ? ctx : null; + // Stamp this face's view slot (`face + 1` — slot 0 is the main view; see + // `ReadyFrameContext.viewSlot`'s doc) so a roster renderer's view-slot + // buffer helper keys this call's writes into a destination the main + // view's own `viewSlot: 0` draw never touches. + return ctx.isReady ? { ...ctx, viewSlot: face + 1 } : null; } diff --git a/src/services/engine/gpuHandles/gpuHandleRegistry.ts b/src/services/engine/gpuHandles/gpuHandleRegistry.ts index aad2790e10..befb720b11 100644 --- a/src/services/engine/gpuHandles/gpuHandleRegistry.ts +++ b/src/services/engine/gpuHandles/gpuHandleRegistry.ts @@ -355,6 +355,10 @@ export const GPU_HANDLE_ROWS = [ ...star, positionMpc: bootBodyStates.get(star.id)!.positionMpc, })), + // Boot seed, no frame yet — the main view's slot. `starPointsLayer` + // re-uploads every real frame (its own module header), so this is + // overwritten before the first draw. + 0, ); return starPointRenderer; }, diff --git a/src/services/gpu/renderers/bodies/starPointRenderer.ts b/src/services/gpu/renderers/bodies/starPointRenderer.ts index da5ce79ce8..66c1a687a0 100644 --- a/src/services/gpu/renderers/bodies/starPointRenderer.ts +++ b/src/services/gpu/renderers/bodies/starPointRenderer.ts @@ -64,6 +64,10 @@ import vsCode from '../../shaders/bodies/starPoints/vertex.wesl?static'; import fsCode from '../../shaders/bodies/starPoints/fragment.wesl?static'; import { createShaderModuleWithDevLog } from '../../shaderCompileLogger'; import { writeCameraPrefix } from '../../lib/cameraUniforms'; +import { + createViewSlotUniformRing, + VIEW_SLOT_COUNT, +} from '../../../../utils/gpu/createViewSlotUniformRing'; import { ADDITIVE_BLEND } from '../../lib/blendStates'; /** @@ -90,19 +94,14 @@ export function createStarPointRenderer( device: GPUDevice, targetFormat: GPUTextureFormat, ): StarPointRenderer { - // ── Uniform buffer + CPU scratch ────────────────────────────────────────── + // ── Uniform ring + CPU scratch ───────────────────────────────────────────── // // The 80-byte CameraUniforms prefix (floats 0..15 = viewProj, 16..17 = // viewportPx, 18..19 = named pads, stay 0) plus the sizePx / brightness tail // at floats 20 / 21 (22..23 pad, stay 0). See STAR_POINT_UNIFORM_BYTES. - const uniformBuffer = device.createBuffer({ - label: 'star-points-uniform-buffer', - size: STAR_POINT_UNIFORM_BYTES, - usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, - }); const uniformScratch = new Float32Array(STAR_POINT_UNIFORM_BYTES / 4); - // ── Bind group (explicit layout, not 'auto') ────────────────────────────── + // ── Bind group layout (explicit, not 'auto') ────────────────────────────── const bindGroupLayout = device.createBindGroupLayout({ label: 'star-points-bgl', entries: [ @@ -113,10 +112,15 @@ export function createStarPointRenderer( }, ], }); - const bindGroup = device.createBindGroup({ - label: 'star-points-bg', + // One physical buffer + bind group per view slot (Task 13b): a sky-cubemap + // capture sweep calls `draw()` several times per frame with different + // cameras, all before one `submit()` — a shared buffer would keep only the + // last call's camera (see `createViewSlotUniformRing`'s doc). + const uniformRing = createViewSlotUniformRing({ + device, + label: 'star-points-uniform', + byteSize: STAR_POINT_UNIFORM_BYTES, layout: bindGroupLayout, - entries: [{ binding: 0, resource: { buffer: uniformBuffer } }], }); // ── Shader modules ──────────────────────────────────────────────────────── @@ -161,31 +165,34 @@ export function createStarPointRenderer( // NO depthStencil: the hdr target has no depth attachment. }); - // ── Star instance buffer (late-bound via setStars) ──────────────────────── + // ── Star instance buffers (late-bound via setStars) ─────────────────────── // // Grow-only reuse, NOT replace-on-upload. `starPointsLayer.draw` calls // `setStars` EVERY frame — the camera-relative anchors it hands us change // per frame (the eye is subtracted in f64 before narrowing here). A // create/destroy of the GPU buffer per call would mean a fresh allocation - // and release 60×/sec on a hot path. Instead the buffer is allocated once - // sized to the first non-empty set and reallocated ONLY when a later set - // exceeds the current capacity; each call re-uploads the live subset via - // `writeBuffer`. With the static `SCENE_STARS` seed the star count never - // grows post-boot, so this is one bounded allocation for the process - // lifetime. `capacityStars` (buffer capacity) is tracked separately from - // `starCount` (the live count `draw` instances) so a shrink reuses the - // larger buffer and draws the smaller subset. + // and release 60×/sec on a hot path. Instead each `viewSlot` (Task 13b) gets + // its OWN buffer, allocated once sized to that slot's first non-empty set + // and reallocated ONLY when a later set on that SAME slot exceeds its + // capacity. One buffer per slot, not one shared buffer, because a + // sky-cubemap capture sweep calls `setStars` once per face plus once for the + // real view — different camera-relative positions — all before one + // `submit()`; a shared buffer would keep only the last call's positions + // (see `createViewSlotUniformRing`'s doc — the same race, for a + // variable-length upload the fixed-size ring can't carry). `capacity[slot]` + // is tracked separately from `count[slot]` so a shrink reuses the larger + // buffer and draws the smaller subset. - let instanceBuffer: GPUBuffer | null = null; - let capacityStars = 0; - let starCount = 0; + const instanceBuffers: (GPUBuffer | null)[] = new Array(VIEW_SLOT_COUNT).fill(null); + const capacityStars: number[] = new Array(VIEW_SLOT_COUNT).fill(0); + const starCounts: number[] = new Array(VIEW_SLOT_COUNT).fill(0); - function setStars(stars: readonly PositionedStar[]): void { - starCount = stars.length; - // Empty set clears the renderer to the no-op draw state; keep any - // existing buffer allocated (it is bounded, and a later non-empty set - // reuses it). `createBuffer({ size: 0 })` is forbidden by the spec, so - // never allocate here. + function setStars(stars: readonly PositionedStar[], viewSlot: number): void { + starCounts[viewSlot] = stars.length; + // Empty set clears this slot to the no-op draw state; keep any existing + // buffer allocated (it is bounded, and a later non-empty set reuses it). + // `createBuffer({ size: 0 })` is forbidden by the spec, so never allocate + // here. if (stars.length === 0) return; const interleaved = new Float32Array(stars.length * FLOATS_PER_STAR); @@ -203,19 +210,21 @@ export function createStarPointRenderer( interleaved[base + 6] = star.absMag; } - // Reallocate only when the current buffer can't hold the new set. + // Reallocate only when this slot's current buffer can't hold the new set. // `destroy()` on the old one is safe even if a prior frame referenced // it — WebGPU defers the actual release until in-flight work completes. - if (instanceBuffer === null || stars.length > capacityStars) { - instanceBuffer?.destroy(); - capacityStars = stars.length; - instanceBuffer = device.createBuffer({ - label: 'star-points-instance-buffer', - size: capacityStars * STAR_STRIDE, + let buffer = instanceBuffers[viewSlot]!; + if (buffer === null || stars.length > capacityStars[viewSlot]!) { + buffer?.destroy(); + capacityStars[viewSlot] = stars.length; + buffer = device.createBuffer({ + label: `star-points-instance-buffer-slot${viewSlot}`, + size: capacityStars[viewSlot]! * STAR_STRIDE, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST, }); + instanceBuffers[viewSlot] = buffer; } - device.queue.writeBuffer(instanceBuffer, 0, interleaved); + device.queue.writeBuffer(buffer, 0, interleaved); } // ── draw ────────────────────────────────────────────────────────────────── @@ -224,21 +233,25 @@ export function createStarPointRenderer( pass: GPURenderPassEncoder, viewProj: Float32Array, viewportPx: Vec2, - opts: { sizePx: number; brightness: number }, + opts: { sizePx: number; brightness: number; viewSlot: number }, ): void { + const { viewSlot } = opts; + const instanceBuffer = instanceBuffers[viewSlot]!; + const starCount = starCounts[viewSlot]!; if (instanceBuffer === null || starCount === 0) return; // uniformScratch[18..19] are CameraUniforms' named pads and [22..23] the // tail's alignment pad — never written, so they hold their construction-time // zeros across frames. sizePx / brightness ride the tail at floats 20 / 21 - // (byte-exact with StarPointUniforms in starPoints/io.wesl). + // (byte-exact with StarPointUniforms in starPoints/io.wesl). Written into + // THIS call's own `viewSlot` buffer (Task 13b) — see the ring's doc. writeCameraPrefix(uniformScratch, viewProj, viewportPx); uniformScratch[UNIFORM_SIZEPX_INDEX] = opts.sizePx; uniformScratch[UNIFORM_BRIGHTNESS_INDEX] = opts.brightness; - device.queue.writeBuffer(uniformBuffer, 0, uniformScratch); + uniformRing.writeSlot(viewSlot, uniformScratch); pass.setPipeline(pipeline); - pass.setBindGroup(0, bindGroup); + pass.setBindGroup(0, uniformRing.bindGroupOf(viewSlot)); pass.setVertexBuffer(0, instanceBuffer); // Six vertices per instanced billboard quad — the vertex stage maps // vertex_index 0..5 through lib/billboard's quadCorner. @@ -248,11 +261,13 @@ export function createStarPointRenderer( // ── destroy ─────────────────────────────────────────────────────────────── function destroy(): void { - instanceBuffer?.destroy(); - instanceBuffer = null; - capacityStars = 0; - starCount = 0; - uniformBuffer.destroy(); + for (let slot = 0; slot < VIEW_SLOT_COUNT; slot++) { + instanceBuffers[slot]?.destroy(); + instanceBuffers[slot] = null; + capacityStars[slot] = 0; + starCounts[slot] = 0; + } + uniformRing.destroy(); } const renderer: StarPointRenderer = { diff --git a/src/services/gpu/renderers/galaxyCatalog/catalogStore.ts b/src/services/gpu/renderers/galaxyCatalog/catalogStore.ts index 9d930d2b92..daaaabd18a 100644 --- a/src/services/gpu/renderers/galaxyCatalog/catalogStore.ts +++ b/src/services/gpu/renderers/galaxyCatalog/catalogStore.ts @@ -53,9 +53,11 @@ import type { BuildPointInterleavedBufferInput } from '../../../../@types/engine import type { BuildPointInterleavedBufferResult } from '../../../../@types/engine/BuildPointInterleavedBufferResult'; import type { FadeUniformsBgl } from '../../../../@types/rendering/FadeUniformsBgl'; import type { SourceUniformsBgl } from '../../../../@types/rendering/SourceUniformsBgl'; +import type { ViewSlotUniformRing } from '../../../../@types/rendering/ViewSlotUniformRing'; import { GALAXY_CATALOG_SOURCES, SOURCE_REGISTRY } from '../../../../data/sources'; import { cloneGalaxyCatalogForTransfer } from '../../../../data/galaxyCatalog/galaxyCatalogTransfer'; import { runDisposableWorker } from '../../../../utils/worker/runDisposableWorker'; +import { createViewSlotUniformRing } from '../../../../utils/gpu/createViewSlotUniformRing'; import { SLOTS_PER_GALAXY_POINT } from './galaxyPointVertexLayout'; // `?worker` emits the worker as a separate chunk and exports a class @@ -148,9 +150,14 @@ type LoadedSource = { * cloud itself; freed when the source unloads. */ interleaved: Float32Array; - /** Per-source FadeUniforms (opacity + pad) written once per frame. */ - fadeBuffer: GPUBuffer; - fadeBindGroup: GPUBindGroup; + /** + * Per-source FadeUniforms (opacity + pad), one physical buffer per view + * slot (Task 13b) — a sky-cubemap capture sweep draws this catalog once + * per face plus once for the real view, all before one `submit()`, so a + * single shared buffer would keep only the last call's opacity (see + * `createViewSlotUniformRing`'s doc). + */ + fade: ViewSlotUniformRing; /** Per-source SourceUniforms (6-bit sourceCode + pad) written once at upload. */ sourceBuffer: GPUBuffer; sourceBindGroup: GPUBindGroup; @@ -166,8 +173,7 @@ export type CatalogDrawEntry = { source: SourceType; count: number; vertexBuffer: GPUBuffer; - fadeBuffer: GPUBuffer; - fadeBindGroup: GPUBindGroup; + fade: ViewSlotUniformRing; sourceBindGroup: GPUBindGroup; }; @@ -289,7 +295,7 @@ export function createCatalogStore(init: { const stale = galaxyCatalogs.get(id); if (stale) { stale.buffer.destroy(); - stale.fadeBuffer.destroy(); + stale.fade.destroy(); stale.sourceBuffer.destroy(); } galaxyCatalogs.delete(id); @@ -309,7 +315,7 @@ export function createCatalogStore(init: { const prev = galaxyCatalogs.get(id); if (prev) { prev.buffer.destroy(); - prev.fadeBuffer.destroy(); + prev.fade.destroy(); prev.sourceBuffer.destroy(); } @@ -320,15 +326,13 @@ export function createCatalogStore(init: { }); device.queue.writeBuffer(buffer, 0, interleaved); - const fadeBuffer = device.createBuffer({ - label: `points-fade-uniform-${id}`, - size: 16, - usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, - }); - const fadeBindGroup = device.createBindGroup({ - label: `points-fade-bg-${id}`, + // One physical 16-byte fade buffer per view slot (Task 13b) — see + // `LoadedSource.fade`'s doc. + const fade = createViewSlotUniformRing({ + device, + label: `points-fade-${id}`, + byteSize: 16, layout: fadeBgl, - entries: [{ binding: 0, resource: { buffer: fadeBuffer } }], }); // SourceUniforms: 6-bit sourceCode + per-source sbBoost + @@ -358,8 +362,7 @@ export function createCatalogStore(init: { buffer, count: galaxyCatalog.count, interleaved, - fadeBuffer, - fadeBindGroup, + fade, sourceBuffer, sourceBindGroup, }); @@ -372,7 +375,7 @@ export function createCatalogStore(init: { const entry = galaxyCatalogs.get(id); if (!entry) return; entry.buffer.destroy(); - entry.fadeBuffer.destroy(); + entry.fade.destroy(); entry.sourceBuffer.destroy(); galaxyCatalogs.delete(id); const source = CODE_OF_ID.get(id); @@ -527,8 +530,7 @@ export function createCatalogStore(init: { source: code, count: entry.count, vertexBuffer: entry.buffer, - fadeBuffer: entry.fadeBuffer, - fadeBindGroup: entry.fadeBindGroup, + fade: entry.fade, sourceBindGroup: entry.sourceBindGroup, }; } @@ -550,7 +552,7 @@ export function createCatalogStore(init: { function destroy(): void { for (const entry of galaxyCatalogs.values()) { entry.buffer.destroy(); - entry.fadeBuffer.destroy(); + entry.fade.destroy(); entry.sourceBuffer.destroy(); } galaxyCatalogs.clear(); diff --git a/src/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.ts b/src/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.ts index f920efde94..5f4b14d7a7 100644 --- a/src/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.ts +++ b/src/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.ts @@ -50,6 +50,7 @@ import type { FadeUniformsBgl } from '../../../../@types/rendering/FadeUniformsB import type { SourceUniformsBgl } from '../../../../@types/rendering/SourceUniformsBgl'; import type { FocusUniformsBgl } from '../../../../@types/rendering/FocusUniformsBgl'; import { packGalaxyPointUniforms } from '../../../../utils/gpu/packGalaxyPointUniforms'; +import { createViewSlotUniformRing } from '../../../../utils/gpu/createViewSlotUniformRing'; import { ADDITIVE_BLEND } from '../../lib/blendStates'; import { POINT_STRIDE, @@ -107,20 +108,24 @@ export function createGalaxyPointRenderer(init: { const vsModule = createShaderModuleWithDevLog(device, vsCode, 'points.vertex'); const fsModule = createShaderModuleWithDevLog(device, colorFsCode, 'points.colorFragment'); + // @group(0) per-frame Uniforms (points-pipeline-specific). Named so the + // view-slot ring below (Task 13b) can build its per-slot bind groups + // against the SAME layout the pipeline binds. + const uniformsBgl = device.createBindGroupLayout({ + label: 'points-bgl-group0', + entries: [ + { + binding: 0, + visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, + buffer: { type: 'uniform' }, + }, + ], + }); + const pipelineLayout = device.createPipelineLayout({ label: 'points-pipeline-layout', bindGroupLayouts: [ - // @group(0) per-frame Uniforms (points-pipeline-specific). - device.createBindGroupLayout({ - label: 'points-bgl-group0', - entries: [ - { - binding: 0, - visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, - buffer: { type: 'uniform' }, - }, - ], - }), + uniformsBgl, fadeBgl, // @group(1) FadeUniforms (canonical) sourceBgl, // @group(2) SourceUniforms (canonical, shared with GalaxyPickRenderer) // @group(3) FocusUniforms — a single shared/global binding (only @@ -162,16 +167,15 @@ export function createGalaxyPointRenderer(init: { primitive: { topology: 'triangle-list' }, }); - const uniformBuffer = device.createBuffer({ - label: 'points-uniform-buffer', - size: UNIFORM_BYTES, - usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, - }); - - const bindGroup = device.createBindGroup({ - label: 'points-bg-uniforms', - layout: pipeline.getBindGroupLayout(0), - entries: [{ binding: 0, resource: { buffer: uniformBuffer } }], + // One physical buffer + bind group per view slot (Task 13b): a sky-cubemap + // capture sweep calls `draw()` several times — different camera, same + // submit — before this frame's `submit()`, so a single shared buffer would + // keep only the last call's viewProj/viewport (see the ring's own doc). + const uniformRing = createViewSlotUniformRing({ + device, + label: 'points-uniform', + byteSize: UNIFORM_BYTES, + layout: uniformsBgl, }); // 16 bytes (opacity + pad) of scratch reused per-source-per-frame @@ -209,7 +213,7 @@ export function createGalaxyPointRenderer(init: { viewportPx: Vec2, settings: GalaxyPointDrawSettings, ): void { - const { visibleSourceMask, focusBindGroup } = settings; + const { visibleSourceMask, focusBindGroup, viewSlot } = settings; // Materialised because the "nothing loaded, skip the uniform write // entirely" early-out needs to know emptiness before the loop. At @@ -221,12 +225,16 @@ export function createGalaxyPointRenderer(init: { // Pack 176 bytes — see `UNIFORM_BYTES` for the layout, and // `points/io.wesl::Uniforms` for the WGSL-side struct. `pickPass` // defaults to 0 (visual pass); the pick path packs its own image via - // `pickUniformBytesOf`, never this buffer. + // `pickUniformBytesOf`, never this buffer. Written into THIS call's own + // `viewSlot` buffer (Task 13b) — a sky-cubemap capture sweep calls + // `draw()` several times per frame with different cameras, all before + // one `submit()`, so a shared buffer would keep only the last call's + // bytes (see `createViewSlotUniformRing`'s doc). const buf = packGalaxyPointUniforms(viewProj, viewportPx, settings); - device.queue.writeBuffer(uniformBuffer, 0, buf); + uniformRing.writeSlot(viewSlot, buf); pass.setPipeline(pipeline); - pass.setBindGroup(0, bindGroup); + pass.setBindGroup(0, uniformRing.bindGroupOf(viewSlot)); // @group(3) focus is the engine's shared focus bind group (one POI // focused at a time, written once per frame in renderFrame). Bind once // before the per-source loop, not per source like fade/source. @@ -247,11 +255,13 @@ export function createGalaxyPointRenderer(init: { const fadeOpacity = settings.fadeOpacityOf(source); if (fadeOpacity === 0) continue; - // One 16-byte fade writeBuffer per visible galaxy catalog per frame. + // One 16-byte fade writeBuffer per visible galaxy catalog per frame, + // into this call's own `viewSlot` slot of the catalog's fade ring — + // same writeBuffer/submit reasoning as the uniform above. fadeScratchF32[0] = fadeOpacity; - device.queue.writeBuffer(catalog.fadeBuffer, 0, fadeScratchBuffer); + catalog.fade.writeSlot(viewSlot, fadeScratchBuffer); - pass.setBindGroup(1, catalog.fadeBindGroup); + pass.setBindGroup(1, catalog.fade.bindGroupOf(viewSlot)); pass.setBindGroup(2, catalog.sourceBindGroup); pass.setVertexBuffer(0, catalog.vertexBuffer); pass.draw(3, catalog.count); @@ -275,7 +285,7 @@ export function createGalaxyPointRenderer(init: { */ function destroy(): void { store.destroy(); - uniformBuffer.destroy(); + uniformRing.destroy(); } const renderer: GalaxyPointRenderer = { diff --git a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts index ce8eb3e1f7..461e7c081f 100644 --- a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts +++ b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts @@ -105,6 +105,10 @@ import { writeCameraPrefix } from '../../lib/cameraUniforms'; import { ADDITIVE_BLEND } from '../../lib/blendStates'; import { sphereOutsideFrustum } from '../../../../utils/camera/sphereOutsideFrustum'; import { DEFAULT_STAR_SIZE_PX } from '../../../../data/defaults'; +import { + createViewSlotUniformRing, + VIEW_SLOT_COUNT, +} from '../../../../utils/gpu/createViewSlotUniformRing'; // The NodeParams / StarUniforms byte layout lives in ONE home both star // renderers import — see starCatalogLayout.ts (the WESL structs in // shaders/starCatalog/io.wesl are the source of truth). This renderer never @@ -124,11 +128,15 @@ import { } from './starCatalogLayout'; /** - * One draw stream's per-source storage buffers: the contiguous NodeParams block - * and the parallel prefix sum, plus their shared grow-only capacity. A stream - * (leaf or aggregate) owns its OWN pair — the two streams draw into different - * passes in the same frame, so a shared pair would read only the last-written - * stream's bytes at submit (the writeBuffer/submit landmine). + * One draw stream's per-source, per-view-slot storage buffers: the + * contiguous NodeParams block and the parallel prefix sum, plus their shared + * grow-only capacity. A stream (leaf or aggregate) owns its OWN pair per + * `ReadyFrameContext.viewSlot` (Task 13b) — a sky-cubemap capture sweep draws + * a source's cut once per face plus once for the real view, ALL before one + * `submit()`, and every one of those calls is a DIFFERENT cut (different + * camera), so a pair shared across view slots would read only the + * last-written call's bytes at submit (the writeBuffer/submit landmine — + * the same reason the two STREAMS already never share a pair). */ type StreamBuffers = { /** @@ -146,6 +154,11 @@ function emptyStreamBuffers(): StreamBuffers { return { nodeParamsBuffer: null, prefixBuffer: null, drawCapacity: 0 }; } +/** One draw stream's buffer pair, one per view slot (index = `viewSlot`). */ +function emptyStreamBuffersRing(): StreamBuffers[] { + return Array.from({ length: VIEW_SLOT_COUNT }, emptyStreamBuffers); +} + /** One committed catalog's GPU resources + the octree kept for the layer. */ type LoadedStarSource = { catalog: StarCatalog; @@ -153,8 +166,8 @@ type LoadedStarSource = { recordsBuffer: GPUBuffer; /** `@group(2)` bind group over `recordsBuffer`, built at upload. */ recordsBindGroup: GPUBindGroup; - /** The two draw streams' per-source buffer pairs (see `StreamBuffers`). */ - streams: Record; + /** The two draw streams' per-view-slot buffer-pair rings (see `StreamBuffers`). */ + streams: Record; }; export function createStarCatalogRenderer( @@ -165,11 +178,6 @@ export function createStarCatalogRenderer( // Sized to STAR_UNIFORM_BYTES: the 80-byte CameraUniforms prefix plus the // source-independent `sizePx` + `brightness` + `glowOverlap` scalars, matching // `struct StarUniforms`. - const cameraBuffer = device.createBuffer({ - label: 'star-catalog-camera-uniform', - size: STAR_UNIFORM_BYTES, - usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, - }); const cameraScratch = new Float32Array(STAR_UNIFORM_BYTES / 4); // ── Bind-group layouts (explicit, not 'auto' — layouts don't cross pipelines) ─ @@ -177,6 +185,16 @@ export function createStarCatalogRenderer( label: 'star-catalog-camera-bgl', entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } }], }); + // One physical camera buffer + bind group per view slot (Task 13b): the + // camera is shared across SOURCES within one `draw` call, but NOT across + // view slots — a capture sweep's several `draw` calls (different faces, + // one submit) each carry a different vp (see the module header). + const cameraRing = createViewSlotUniformRing({ + device, + label: 'star-catalog-camera-uniform', + byteSize: STAR_UNIFORM_BYTES, + layout: cameraBgl, + }); const drawBgl = device.createBindGroupLayout({ label: 'star-catalog-draw-bgl', entries: [ @@ -208,12 +226,6 @@ export function createStarCatalogRenderer( ], }); - const cameraBindGroup = device.createBindGroup({ - label: 'star-catalog-camera-bg', - layout: cameraBgl, - entries: [{ binding: 0, resource: { buffer: cameraBuffer } }], - }); - // ── Shader modules + pipeline (additive, depthless — the hdr row has no depth) ─ const vsModule = createShaderModuleWithDevLog(device, vsCode, 'starCatalog.vertex'); const fsModule = createShaderModuleWithDevLog(device, fsCode, 'starCatalog.fragment'); @@ -306,15 +318,17 @@ export function createStarCatalogRenderer( catalog, recordsBuffer, recordsBindGroup, - streams: { leaf: emptyStreamBuffers(), aggregate: emptyStreamBuffers() }, + streams: { leaf: emptyStreamBuffersRing(), aggregate: emptyStreamBuffersRing() }, }); } - /** Release both stream buffer pairs of a source (replace / unload / teardown). */ + /** Release every stream × view-slot buffer pair of a source (replace / unload / teardown). */ function destroyStreams(entry: LoadedStarSource): void { for (const stream of ['leaf', 'aggregate'] as const) { - entry.streams[stream].nodeParamsBuffer?.destroy(); - entry.streams[stream].prefixBuffer?.destroy(); + for (const buffers of entry.streams[stream]) { + buffers.nodeParamsBuffer?.destroy(); + buffers.prefixBuffer?.destroy(); + } } } @@ -394,26 +408,30 @@ export function createStarCatalogRenderer( aggregateIntensityCap, frustumPlanes, glowMarginAngleRad, + viewSlot, } = args; const entry = sources.get(source); if (!entry || drawCount === 0) return; - const buffers = entry.streams[stream]; - - // Camera uniform: identical bytes every source, so this repeated write is - // idempotent (see the module header). floats 18/19 stay zero-init. - // `sizePx`, `brightness`, `glowOverlap` and `aggregateIntensityCap` ride this - // buffer too — all four are source-independent (the same base star-dot size + - // exposure trim + glow spread + aggregate peak ceiling for every source this + const buffers = entry.streams[stream][viewSlot]!; + + // Camera uniform: identical bytes every source WITHIN one view slot (see + // the module header), but NOT across view slots — a sky-cubemap capture + // sweep's several `draw` calls (different faces, one submit) each carry + // a different vp, so this call's bytes land in THIS `viewSlot`'s own + // buffer (Task 13b). floats 18/19 stay zero-init. `sizePx`, `brightness`, + // `glowOverlap` and `aggregateIntensityCap` ride this buffer too — all + // four are source-independent (the same base star-dot size + exposure + // trim + glow spread + aggregate peak ceiling for every source this // frame), so appending them to the shared camera prefix is safe: each - // source's repeated write lands the identical values. Written here, ONCE per - // source before its draw, so there is no mid-frame mutation for the + // source's repeated write lands the identical values. Written here, ONCE + // per source before its draw, so there is no mid-frame mutation for the // writeBuffer/submit ordering race to corrupt. writeCameraPrefix(cameraScratch, vp, viewportPx); cameraScratch[SIZE_PX_FLOAT_INDEX] = sizePx; cameraScratch[BRIGHTNESS_FLOAT_INDEX] = brightness; cameraScratch[GLOW_OVERLAP_FLOAT_INDEX] = glowOverlap; cameraScratch[AGG_INTENSITY_CAP_FLOAT_INDEX] = aggregateIntensityCap; - device.queue.writeBuffer(cameraBuffer, 0, cameraScratch); + cameraRing.writeSlot(viewSlot, cameraScratch); // Pack every SURVIVING draw's params contiguously and build the exclusive // prefix sum of record counts in the same pass. Culled nodes are skipped @@ -524,7 +542,7 @@ export function createStarCatalogRenderer( }); pass.setPipeline(pipelines[stream]); - pass.setBindGroup(0, cameraBindGroup); + pass.setBindGroup(0, cameraRing.bindGroupOf(viewSlot)); pass.setBindGroup(1, drawBindGroup); pass.setBindGroup(2, entry.recordsBindGroup); // ONE instanced draw for the whole cut: the vertex stage routes each instance @@ -558,7 +576,7 @@ export function createStarCatalogRenderer( destroyStreams(entry); } sources.clear(); - cameraBuffer.destroy(); + cameraRing.destroy(); } const renderer: StarCatalogRenderer = { diff --git a/src/utils/gpu/createViewSlotUniformRing.ts b/src/utils/gpu/createViewSlotUniformRing.ts new file mode 100644 index 0000000000..2c617152a5 --- /dev/null +++ b/src/utils/gpu/createViewSlotUniformRing.ts @@ -0,0 +1,75 @@ +/** + * createViewSlotUniformRing — one fixed-size uniform buffer PER view slot + * (Task 13b, Ruling 7), so a renderer's per-frame `writeBuffer` survives a + * sky-cubemap capture sweep intact. + * + * A capture sweep calls a roster renderer's `draw()` once per face (a + * synthetic `ReadyFrameContext`) plus once for the real view, ALL before one + * `submit()`. A single shared buffer keeps only the LAST of those writes — + * `queue.writeBuffer` calls apply in call order, but every recorded draw only + * reads its bound buffer's contents at `submit()` time, by which point every + * write already landed (docs/RENDERER.md landmine #1). Giving each + * `ctx.viewSlot` its OWN physical buffer + bind group closes the race: a + * call's write and the draw recorded against it always agree on which bytes + * are theirs, because no other call ever touches that buffer. + * + * Ring-of-buffers, not one buffer + 256-byte-aligned dynamic offsets: the + * bind-group layouts this ring is built against are shared, canonical + * objects in several call sites (`FadeUniformsBgl`, `SourceUniformsBgl`) — + * consumed as-is by sibling pipelines (`galaxyPickRenderer`) that only ever + * bind slot 0. Making the layout's binding `hasDynamicOffset: true` would + * force every consumer, including ones with no multi-slot need, to supply an + * offset at bind time — a shared-type change for a single-caller feature. A + * private ring needs no layout change at all: 7 slots × ≤176 B is a rounding + * error in VRAM, so the memory a dynamic-offset scheme would save isn't + * worth the wider blast radius. + */ + +import type { ViewSlotUniformRing } from '../../@types/rendering/ViewSlotUniformRing'; + +/** Slot 0 is the main view; 1..6 are the sky-cubemap's six capture faces. */ +export const VIEW_SLOT_COUNT = 7; + +export function createViewSlotUniformRing(init: { + readonly device: GPUDevice; + readonly label: string; + readonly byteSize: number; + readonly layout: GPUBindGroupLayout; + /** @default VIEW_SLOT_COUNT */ + readonly slotCount?: number; +}): ViewSlotUniformRing { + const { device, label, byteSize, layout } = init; + const slotCount = init.slotCount ?? VIEW_SLOT_COUNT; + + const buffers: GPUBuffer[] = []; + const bindGroups: GPUBindGroup[] = []; + for (let slot = 0; slot < slotCount; slot++) { + const buffer = device.createBuffer({ + label: `${label}-slot${slot}`, + size: byteSize, + usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, + }); + buffers.push(buffer); + bindGroups.push( + device.createBindGroup({ + label: `${label}-bg-slot${slot}`, + layout, + entries: [{ binding: 0, resource: { buffer } }], + }), + ); + } + + function writeSlot(slot: number, data: BufferSource): void { + device.queue.writeBuffer(buffers[slot]!, 0, data); + } + + function bindGroupOf(slot: number): GPUBindGroup { + return bindGroups[slot]!; + } + + function destroy(): void { + for (const buffer of buffers) buffer.destroy(); + } + + return { writeSlot, bindGroupOf, destroy }; +} diff --git a/src/utils/gpu/packGalaxyPointUniforms.ts b/src/utils/gpu/packGalaxyPointUniforms.ts index 15469fdb16..71e9141d2d 100644 --- a/src/utils/gpu/packGalaxyPointUniforms.ts +++ b/src/utils/gpu/packGalaxyPointUniforms.ts @@ -52,12 +52,17 @@ export function packGalaxyPointUniforms( viewProj: Mat4, viewportPx: readonly [number, number], // Only the packed byte-layout fields are read here — never the draw-only - // `focusBindGroup` / `fadeOpacityOf` GPU-callback fields or the shader-side - // `visibleSourceMask`. Narrowing the parameter lets the pick path assemble a - // pure-value input (`pickUniformBytesOf`) without fabricating GPU objects, - // while the visual `draw()` still passes its full `GalaxyPointDrawSettings` (a - // superset satisfies the `Omit`). - settings: Omit, + // `focusBindGroup` / `fadeOpacityOf` GPU-callback fields, the shader-side + // `visibleSourceMask`, or `viewSlot` (Task 13b — which physical buffer the + // CALLER writes these bytes into, not a byte this struct encodes). + // Narrowing the parameter lets the pick path assemble a pure-value input + // (`pickUniformBytesOf`) without fabricating GPU objects, while the visual + // `draw()` still passes its full `GalaxyPointDrawSettings` (a superset + // satisfies the `Omit`). + settings: Omit< + GalaxyPointDrawSettings, + 'focusBindGroup' | 'fadeOpacityOf' | 'visibleSourceMask' | 'viewSlot' + >, // 0 = visual pass, 1 = pick pass. A packed field rather than a post-upload // override so the buffer this returns is the complete image for either pass. pickPass: number = 0, diff --git a/tests/services/engine/frame/frameContext.test.ts b/tests/services/engine/frame/frameContext.test.ts index 4979cf4179..5129753259 100644 --- a/tests/services/engine/frame/frameContext.test.ts +++ b/tests/services/engine/frame/frameContext.test.ts @@ -357,6 +357,23 @@ describe('deriveFrameContext — ready branch', () => { expect(ctx.focus.blend).toBe(0); }); + it('stamps viewSlot 0 — the main view (Task 13b; skyCubemapFaceContext overrides to face + 1)', () => { + const ctx = deriveFrameContext( + makeState(), + makeCanvas(), + RESTING_POSE, + PROJECTION, + BASIS, + BASIS, + 0, + 0, + CONST_J2000, + ); + expect(ctx.isReady).toBe(true); + if (!ctx.isReady) return; + expect(ctx.viewSlot).toBe(0); + }); + it('stamps nowMs onto the ready context', () => { const ctx = deriveFrameContext( makeState(), diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index 21da534281..ea7bb10c90 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -115,6 +115,37 @@ describe('frameProgram', () => { ]); }); + it('emits a COSMO capture step alongside NEAR0 per requested face (Task 13b)', () => { + // The fixed opt-in roster spans both slabs — `point-sprites` (COSMO), + // `star-catalog`/`star-aggregates`/`star-points` (NEAR0) — and a capture + // step's `slab` still gates its group normally (only `target` selection + // is bypassed for a capture step). A NEAR0-only capture step would leave + // the COSMO half of the roster permanently unselected regardless of its + // `skyCapture` flag, so each requested face must get ONE step per slab. + const program = frameProgram(TONE, false, [NEAR0], [0, 2]); + const captureSteps = program.filter( + (step) => step.kind === 'render' && step.target === 'sky-cubemap', + ); + expect(captureSteps).toEqual([ + { kind: 'render', target: 'sky-cubemap', slab: COSMO, face: 0 }, + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }, + { kind: 'render', target: 'sky-cubemap', slab: COSMO, face: 2 }, + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 2 }, + ]); + // Ahead of every other render step, so a same-frame lensing draw can + // sample a cubemap this frame actually wrote. + expect(program[0]).toEqual({ kind: 'compute', name: 'flow' }); + expect(program[1]).toEqual({ kind: 'compute', name: 'atmosphereSkyView' }); + expect(program[2]).toEqual(captureSteps[0]); + }); + + it('emits no capture steps when no faces are requested (Q6 zero-dispatch)', () => { + const program = frameProgram(TONE, false, [NEAR0], []); + expect(program.some((step) => step.kind === 'render' && step.target === 'sky-cubemap')).toBe( + false, + ); + }); + it('expands the foreground chain in painter order', () => { // Chain [NEAR0, 3, 2] (an out-of-numeric-order chain, as a painter-order // chain legitimately is — index order is assignment order, not draw diff --git a/tests/services/engine/frame/passes/clipPathDebugLayer.test.ts b/tests/services/engine/frame/passes/clipPathDebugLayer.test.ts index d7fcd32e1d..460635a285 100644 --- a/tests/services/engine/frame/passes/clipPathDebugLayer.test.ts +++ b/tests/services/engine/frame/passes/clipPathDebugLayer.test.ts @@ -48,6 +48,7 @@ function makeCtx(): ReadyFrameContext { }; return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts index 0b94fe0676..04aee6cfd3 100644 --- a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts @@ -36,6 +36,7 @@ const FIXTURE_SPECS = [ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFrameContext { return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/filamentsLayer.test.ts b/tests/services/engine/frame/passes/filamentsLayer.test.ts index f069127b97..eb2e9a288d 100644 --- a/tests/services/engine/frame/passes/filamentsLayer.test.ts +++ b/tests/services/engine/frame/passes/filamentsLayer.test.ts @@ -21,6 +21,7 @@ function makeCtx(focusBlend: number): ReadyFrameContext { const cosmoSlab: Slab = makeCosmoSlab({ vp: Float64Array.from(vp as unknown as Float32Array) }); return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/flowFieldLayer.test.ts b/tests/services/engine/frame/passes/flowFieldLayer.test.ts index 66c3fb578b..4f3a73c95d 100644 --- a/tests/services/engine/frame/passes/flowFieldLayer.test.ts +++ b/tests/services/engine/frame/passes/flowFieldLayer.test.ts @@ -18,6 +18,7 @@ import type { Mat4 } from 'wgpu-matrix'; function makeCtx(): ReadyFrameContext { return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/passes.test.ts b/tests/services/engine/frame/passes/passes.test.ts index 94b37fdffb..a7f37a4b2c 100644 --- a/tests/services/engine/frame/passes/passes.test.ts +++ b/tests/services/engine/frame/passes/passes.test.ts @@ -88,6 +88,7 @@ function makeCtx(overrides: Partial = {}): ReadyFrameContext const cosmoSlab: Slab = makeCosmoSlab({ vp: Float64Array.from(vp as unknown as Float32Array) }); return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), cam, vp, @@ -412,7 +413,11 @@ describe('CONTENT_LAYERS blend legality', () => { // the swap-chain rows). A third non-additive hdr row should fail // this test and be a deliberate decision. const expected = - layer === milkyWayLayer ? 'multiply' : layer === sgrAStarLensingLayer ? 'over' : 'additive'; + layer === milkyWayLayer + ? 'multiply' + : layer === sgrAStarLensingLayer + ? 'over' + : 'additive'; expect(layer.blend).toBe(expected); } else if (layer.target === 'foreground:0') { // The `foreground:0` group is opaque bodies EXCEPT the three translucent diff --git a/tests/services/engine/frame/passes/proceduralDisksLayer.test.ts b/tests/services/engine/frame/passes/proceduralDisksLayer.test.ts index 1edb9309ee..08624ab072 100644 --- a/tests/services/engine/frame/passes/proceduralDisksLayer.test.ts +++ b/tests/services/engine/frame/passes/proceduralDisksLayer.test.ts @@ -26,6 +26,7 @@ function makeCtx(overrides: Partial = {}): ReadyFrameContext const vp = new Float32Array(16) as unknown as Mat4; return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), cam, vp, diff --git a/tests/services/engine/frame/passes/selectionRingLayer.test.ts b/tests/services/engine/frame/passes/selectionRingLayer.test.ts index a5a10d0529..66d8af54e9 100644 --- a/tests/services/engine/frame/passes/selectionRingLayer.test.ts +++ b/tests/services/engine/frame/passes/selectionRingLayer.test.ts @@ -26,6 +26,7 @@ function makeCtx(): ReadyFrameContext { const cosmoSlab: Slab = makeCosmoSlab({ vp: Float64Array.from(vp) }); return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/texturedDisksLayer.test.ts b/tests/services/engine/frame/passes/texturedDisksLayer.test.ts index f4baee04f4..9716499628 100644 --- a/tests/services/engine/frame/passes/texturedDisksLayer.test.ts +++ b/tests/services/engine/frame/passes/texturedDisksLayer.test.ts @@ -25,6 +25,7 @@ function makeCtx(): ReadyFrameContext { const cam = makeCam(); return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts index fc940ac7f5..51cb0c8825 100644 --- a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts @@ -38,6 +38,7 @@ const FIXTURE_SPECS = [ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFrameContext { return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/renderFrame.test.ts b/tests/services/engine/frame/renderFrame.test.ts index 76cfb987a5..e7984670aa 100644 --- a/tests/services/engine/frame/renderFrame.test.ts +++ b/tests/services/engine/frame/renderFrame.test.ts @@ -390,6 +390,7 @@ function makeInput( }); const ctx = { isReady: true as const, + viewSlot: 0, renderedTargets: new Set(), // Nothing in this file reads bodyPose. bodyPose: () => null, diff --git a/tests/services/engine/frame/skyCubemapFaceContext.test.ts b/tests/services/engine/frame/skyCubemapFaceContext.test.ts index b6c9d94fc1..a50a3cde91 100644 --- a/tests/services/engine/frame/skyCubemapFaceContext.test.ts +++ b/tests/services/engine/frame/skyCubemapFaceContext.test.ts @@ -117,6 +117,10 @@ describe('skyCubemapFaceContext', () => { if (ctx === null) continue; expect(ctx.drawCamPos).toEqual(EYE_MPC); + // viewSlot = face + 1 (Task 13b) — slot 0 is reserved for the main + // view, so a roster renderer's view-slot buffer never confuses this + // face's write with the real frame's. + expect(ctx.viewSlot).toBe(face + 1); // Independent geometric check: the forward direction (target − eye, // read off the assembled camera, not re-derived from yaw/pitch) must diff --git a/tests/services/engine/frame/slabs.test.ts b/tests/services/engine/frame/slabs.test.ts index 2e6d8d1df7..0578b6648f 100644 --- a/tests/services/engine/frame/slabs.test.ts +++ b/tests/services/engine/frame/slabs.test.ts @@ -480,6 +480,7 @@ describe('slabViewOf', () => { const slabs = deriveSlabs(baseInput({ cam, cosmoVp })); return { isReady: true, + viewSlot: 0, renderedTargets: new Set(), cam, vp: cosmoVp, diff --git a/tests/services/gpu/renderers/bodies/starPointRenderer.test.ts b/tests/services/gpu/renderers/bodies/starPointRenderer.test.ts index 4fec80c70a..0e59bed482 100644 --- a/tests/services/gpu/renderers/bodies/starPointRenderer.test.ts +++ b/tests/services/gpu/renderers/bodies/starPointRenderer.test.ts @@ -74,12 +74,12 @@ describe('createStarPointRenderer', () => { expect(() => renderer.destroy()).not.toThrow(); }); - const DRAW_OPTS = { sizePx: 2.5, brightness: 1 }; + const DRAW_OPTS = { sizePx: 2.5, brightness: 1, viewSlot: 0 }; it('setStars and draw are callable with the right arity', () => { const renderer = createStarPointRenderer(mockDevice(), 'rgba16float'); expect(typeof renderer.setStars).toBe('function'); - expect(renderer.setStars.length).toBe(1); + expect(renderer.setStars.length).toBe(2); expect(typeof renderer.draw).toBe('function'); expect(renderer.draw.length).toBe(4); }); @@ -95,14 +95,14 @@ describe('createStarPointRenderer', () => { expect(before.draw).not.toHaveBeenCalled(); // Two stars uploaded — one instanced draw of 6 vertices × 2 instances. - renderer.setStars([SUN, SIRIUS]); + renderer.setStars([SUN, SIRIUS], 0); const after = mockPass(); renderer.draw(after, new Float32Array(16), [1920, 1080], DRAW_OPTS); expect(after.draw).toHaveBeenCalledTimes(1); expect(after.draw).toHaveBeenCalledWith(6, 2); // Empty upload clears the renderer back to the no-op state. - renderer.setStars([]); + renderer.setStars([], 0); const cleared = mockPass(); renderer.draw(cleared, new Float32Array(16), [1920, 1080], DRAW_OPTS); expect(cleared.draw).not.toHaveBeenCalled(); @@ -116,16 +116,21 @@ describe('createStarPointRenderer', () => { // The StarPointUniforms buffer is the CameraUniforms prefix (80 B) plus the // sizePx / brightness tail rounded to 96 B — must match starPoints/io.wesl. + // One physical buffer per view slot (Task 13b); slot 0's is checked here. const uniformCreate = createBuffer.mock.calls.find( - ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-uniform-buffer', + ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-uniform-slot0', ); expect((uniformCreate![0] as GPUBufferDescriptor).size).toBe(96); - renderer.setStars([SUN, SIRIUS]); - renderer.draw(mockPass(), new Float32Array(16), [1920, 1080], { sizePx: 3.5, brightness: 42 }); + renderer.setStars([SUN, SIRIUS], 0); + renderer.draw(mockPass(), new Float32Array(16), [1920, 1080], { + sizePx: 3.5, + brightness: 42, + viewSlot: 0, + }); const uniformWrite = writeBuffer.mock.calls.find( - ([buffer]) => (buffer as { label?: string }).label === 'star-points-uniform-buffer', + ([buffer]) => (buffer as { label?: string }).label === 'star-points-uniform-slot0', ); const scratch = uniformWrite![2] as Float32Array; // sizePx at float 20 (byte 80), brightness at float 21 (byte 84); the pad @@ -145,23 +150,64 @@ describe('createStarPointRenderer', () => { const instanceCreates = () => createBuffer.mock.calls.filter( - ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-instance-buffer', + ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-instance-buffer-slot0', ).length; const instanceUploads = () => writeBuffer.mock.calls.filter( - ([buffer]) => (buffer as { label?: string }).label === 'star-points-instance-buffer', + ([buffer]) => (buffer as { label?: string }).label === 'star-points-instance-buffer-slot0', ).length; // Per-frame `starPointsLayer.draw` re-hands camera-relative anchors each // frame, so `setStars` fires every frame with the same star count. That // must NOT churn a fresh GPU buffer per call: allocate once, re-upload. - renderer.setStars([SUN, SIRIUS]); - renderer.setStars([SUN, SIRIUS]); + renderer.setStars([SUN, SIRIUS], 0); + renderer.setStars([SUN, SIRIUS], 0); expect(instanceCreates()).toBe(1); expect(instanceUploads()).toBe(2); }); + it('viewSlot — two draw() calls with different viewSlot land their camera uniform in different buffers', () => { + const device = mockDevice(); + const renderer = createStarPointRenderer(device, 'rgba16float'); + const writeBuffer = device.queue.writeBuffer as unknown as ReturnType; + + // Two "faces" of a capture sweep, each with its own star set and camera, + // both drawn before the frame's single submit — the writeBuffer/submit + // race `viewSlot` exists to close (docs/RENDERER.md landmine #1). + renderer.setStars([SUN], 1); + renderer.setStars([SIRIUS], 2); + renderer.draw(mockPass(), new Float32Array(16), [256, 256], { + sizePx: 2.5, + brightness: 1, + viewSlot: 1, + }); + renderer.draw(mockPass(), new Float32Array(16), [256, 256], { + sizePx: 2.5, + brightness: 1, + viewSlot: 2, + }); + + const uniformSlot1 = writeBuffer.mock.calls.find( + ([buffer]) => (buffer as { label?: string }).label === 'star-points-uniform-slot1', + ); + const uniformSlot2 = writeBuffer.mock.calls.find( + ([buffer]) => (buffer as { label?: string }).label === 'star-points-uniform-slot2', + ); + // Distinct GPU buffer objects — slot 2's write never touched slot 1's. + expect(uniformSlot1![0]).not.toBe(uniformSlot2![0]); + + const instanceSlot1 = device.createBuffer as unknown as ReturnType; + const slot1Label = instanceSlot1.mock.calls.find( + ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-instance-buffer-slot1', + ); + const slot2Label = instanceSlot1.mock.calls.find( + ([desc]) => (desc as GPUBufferDescriptor).label === 'star-points-instance-buffer-slot2', + ); + expect(slot1Label).toBeDefined(); + expect(slot2Label).toBeDefined(); + }); + it('bakes the additive depthless profile — targetFormat + one/one blend, no depthStencil', () => { const renderPipelines: GPURenderPipelineDescriptor[] = []; createStarPointRenderer(mockDevice(renderPipelines), 'rgba16float'); diff --git a/tests/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.test.ts b/tests/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.test.ts index 6818717491..a757a5827b 100644 --- a/tests/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.test.ts +++ b/tests/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer.test.ts @@ -22,6 +22,7 @@ import { describe, it, expect } from 'vitest'; import { createGalaxyPointRenderer } from '../../../../../src/services/gpu/renderers/galaxyCatalog/galaxyPointRenderer'; // `BuildRunner` belongs to the store; the renderer only forwards it. import type { BuildRunner } from '../../../../../src/services/gpu/renderers/galaxyCatalog/catalogStore'; +import { VIEW_SLOT_COUNT } from '../../../../../src/utils/gpu/createViewSlotUniformRing'; import { buildPointInterleavedBuffer } from '../../../../../src/services/engine/bake/buildPointInterleavedBuffer'; import { Source, SOURCE_REGISTRY } from '../../../../../src/data/sources'; import type { GalaxyCatalog } from '../../../../../src/@types/data/galaxyCatalog/GalaxyCatalog'; @@ -200,7 +201,7 @@ function makeDestroyTrackingDevice(createdBuffers: TrackedBuffer[]): GPUDevice { } describe('GalaxyPointRenderer.destroy', () => { - it("releases the renderer's uniform buffer", () => { + it("releases the renderer's uniform ring", () => { const buffers: TrackedBuffer[] = []; const device = makeDestroyTrackingDevice(buffers); const renderer = createGalaxyPointRenderer({ @@ -211,10 +212,11 @@ describe('GalaxyPointRenderer.destroy', () => { focusBgl: makeStubFocusBgl(), buildRunner: testRunner, }); - // The constructor allocates one buffer: the renderer's own uniform. - // The cluster-focus uniform is shared and owned by the engine - // (state.gpu.focusUniform), not the renderer. - expect(buffers).toHaveLength(1); + // The constructor allocates VIEW_SLOT_COUNT buffers: the renderer's own + // per-view-slot uniform ring (Task 13b). The cluster-focus uniform is + // shared and owned by the engine (state.gpu.focusUniform), not the + // renderer. + expect(buffers).toHaveLength(VIEW_SLOT_COUNT); for (const b of buffers) expect(b.destroyCount).toBe(0); renderer.destroy(); @@ -222,7 +224,7 @@ describe('GalaxyPointRenderer.destroy', () => { for (const b of buffers) expect(b.destroyCount).toBe(1); }); - it('releases each per-source buffer + fade uniform', async () => { + it('releases each per-source buffer + fade ring', async () => { const buffers: TrackedBuffer[] = []; const device = makeDestroyTrackingDevice(buffers); const renderer = createGalaxyPointRenderer({ @@ -233,26 +235,26 @@ describe('GalaxyPointRenderer.destroy', () => { focusBgl: makeStubFocusBgl(), buildRunner: testRunner, }); - // Constructor allocates 1 buffer: the renderer's own uniform (the - // cluster-focus uniform is shared/engine-owned, not per renderer). - expect(buffers).toHaveLength(1); - + // Constructor allocates the renderer's own per-view-slot uniform ring + // (the cluster-focus uniform is shared/engine-owned, not per renderer). + expect(buffers).toHaveLength(VIEW_SLOT_COUNT); + + // upload() allocates VIEW_SLOT_COUNT + 2 more buffers per source: the + // vertex buffer, the per-view-slot FadeUniforms ring (Task 13b), and the + // SourceUniforms 16-byte uniform. + const perUpload = VIEW_SLOT_COUNT + 2; await renderer.upload(idOf(Source.SDSS), makeCloud(2)); - // upload() allocates 3 more buffers per source: the vertex buffer, - // the FadeUniforms 16-byte uniform, and the SourceUniforms 16-byte - // uniform (unified-fade architecture). - expect(buffers).toHaveLength(4); + expect(buffers).toHaveLength(VIEW_SLOT_COUNT + perUpload); await renderer.upload(idOf(Source.TwoMRS), makeCloud(3)); - // Second source: another vertex + fade + source triple. - expect(buffers).toHaveLength(7); + expect(buffers).toHaveLength(VIEW_SLOT_COUNT + 2 * perUpload); // Sanity: every tracked buffer starts at 0 destroys. for (const b of buffers) expect(b.destroyCount).toBe(0); renderer.destroy(); - // All seven buffers (renderer uniform + 2 sources × {vertex, fade, + // Every buffer (renderer's ring + 2 sources × {vertex, fade ring, // source}) should be destroyed exactly once. for (const b of buffers) expect(b.destroyCount).toBe(1); }); @@ -343,6 +345,7 @@ describe('GalaxyPointRenderer.draw — GalaxyPointDrawSettings shape', () => { pxFadeEnd: 0, focusBindGroup: FOCUS_BIND_GROUP, fadeOpacityOf: () => 1, + viewSlot: 0, }); expect(calls).toContain('setPipeline'); @@ -395,6 +398,7 @@ describe('GalaxyPointRenderer.draw — GalaxyPointDrawSettings shape', () => { focusBindGroup: FOCUS_BIND_GROUP, // SDSS fully faded → skipped; GLADE at partial opacity → drawn. fadeOpacityOf: (source) => (source === Source.SDSS ? 0 : 0.5), + viewSlot: 0, }); // Exactly one instanced draw fired (GLADE's 10 instances); SDSS's was @@ -402,3 +406,67 @@ describe('GalaxyPointRenderer.draw — GalaxyPointDrawSettings shape', () => { expect(drawnCounts).toEqual([10]); }); }); + +describe('GalaxyPointRenderer.draw — viewSlot (Task 13b)', () => { + it('two draw() calls with different viewSlot land their @group(0) uniform and fade writes in different buffers', async () => { + const buffers: TrackedBuffer[] = []; + const device = makeDestroyTrackingDevice(buffers); + const renderer = createGalaxyPointRenderer({ + device, + targetFormat: 'rgba16float', + fadeBgl: makeStubFadeBgl(), + sourceBgl: makeStubSourceBgl(), + focusBgl: makeStubFocusBgl(), + buildRunner: testRunner, + }); + await renderer.upload(idOf(Source.SDSS), makeCloud(2)); + + const bindGroupsAt0: unknown[] = []; + const bindGroupsAt1: unknown[] = []; + const pass = { + setPipeline: () => {}, + setBindGroup: (slot: number, bg: unknown) => { + if (slot === 0) bindGroupsAt0.push(bg); + if (slot === 1) bindGroupsAt1.push(bg); + }, + setVertexBuffer: () => {}, + draw: () => {}, + } as unknown as GPURenderPassEncoder; + + const settings = (viewSlot: number) => ({ + pointSizePx: 1, + brightness: 1, + selectedPacked: 0xffffffff >>> 0, + visibleSourceMask: 0xffffffff, + camPosWorld: [0, 0, 0] as const, + pxPerRad: 1, + provenance: { + orientation: { highlight: false, filter: 'all' as const }, + size: { highlight: false, filter: 'all' as const }, + }, + biasMode: 0, + absMagLimit: 0, + depthFadeEnabled: false, + sbScale: 8, + sbMax: 30, + falloffStrength: 0.8, + pxFadeStart: 0, + pxFadeEnd: 0, + focusBindGroup: FOCUS_BIND_GROUP, + fadeOpacityOf: () => 1, + viewSlot, + }); + + // A sky-cubemap capture sweep: two `draw()` calls (different faces) in + // the same frame, both before one `submit()`. + renderer.draw(pass, new Float32Array(16) as unknown as Mat4, [256, 256], settings(1)); + renderer.draw(pass, new Float32Array(16) as unknown as Mat4, [256, 256], settings(2)); + + // The @group(0) per-frame uniform and the @group(1) per-catalog fade + // each resolve to a DIFFERENT physical bind group per view slot — slot + // 2's write can never land in slot 1's buffer (the writeBuffer/submit + // race this ring closes; docs/RENDERER.md landmine #1). + expect(bindGroupsAt0[0]).not.toBe(bindGroupsAt0[1]); + expect(bindGroupsAt1[0]).not.toBe(bindGroupsAt1[1]); + }); +}); diff --git a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts index bc8b81e16b..bbfdce97b1 100644 --- a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts +++ b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts @@ -100,6 +100,7 @@ function twoNodeArgs( aggregateIntensityCap: 0.06, frustumPlanes, glowMarginAngleRad: 0.0001, + viewSlot: 0, }; } diff --git a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts new file mode 100644 index 0000000000..fcc426c9da --- /dev/null +++ b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts @@ -0,0 +1,131 @@ +/** + * starCatalogRenderer — view-slot isolation (Task 13b). + * + * A sky-cubemap capture sweep calls `draw()` several times per frame — one + * per requested face plus once for the real view — all before the frame's + * single `submit()`. Each call carries a different camera and (for the + * SAME source + stream) a different octree cut. These tests pin the fix for + * the writeBuffer/submit race (docs/RENDERER.md landmine #1): two `draw()` + * calls with different `viewSlot` must land their camera uniform AND their + * NodeParams/prefix pair in DIFFERENT GPU buffers, never the same one. + */ + +import { describe, it, expect, vi } from 'vitest'; + +import { createStarCatalogRenderer } from '../../../../../src/services/gpu/renderers/starCatalog/starCatalogRenderer'; +import { Source } from '../../../../../src/data/sources'; +import type { StarCatalog } from '../../../../../src/@types/data/starCatalog/StarCatalog'; +import type { StarCatalogDrawArgs } from '../../../../../src/@types/rendering/StarCatalogRenderer'; + +function mockDevice(): GPUDevice { + return { + createShaderModule: vi.fn(() => ({ + getCompilationInfo: () => Promise.resolve({ messages: [] }), + })), + createBuffer: vi.fn((desc: GPUBufferDescriptor) => ({ label: desc.label, destroy: vi.fn() })), + createBindGroupLayout: vi.fn(() => ({})), + createBindGroup: vi.fn(() => ({})), + createPipelineLayout: vi.fn(() => ({})), + createRenderPipeline: vi.fn(() => ({})), + queue: { writeBuffer: vi.fn() }, + } as unknown as GPUDevice; +} + +function mockPass(): GPURenderPassEncoder { + return { + setPipeline: vi.fn(), + setBindGroup: vi.fn(), + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; +} + +const CATALOG = { records: new Uint8Array(2 * 6) } as unknown as StarCatalog; + +function oneNodeArgs(viewSlot: number): StarCatalogDrawArgs { + return { + source: Source.GaiaStars, + stream: 'leaf', + vp: new Float32Array(16), + viewportPx: [1280, 720], + drawCount: 1, + firstRecord: new Uint32Array([0]), + recordCount: new Uint32Array([2]), + originRelCamMpc: new Float32Array([0, 0, -5]), + cellScaleMpc: new Float32Array([0.02]), + isAggregate: new Uint8Array([0]), + subtreeStarCount: new Float32Array([1]), + opacity: new Float32Array([1]), + sizePx: 2.5, + brightness: 1, + glowOverlap: 1, + aggregateIntensityCap: 0.06, + frustumPlanes: null, + glowMarginAngleRad: 0, + viewSlot, + }; +} + +describe('starCatalogRenderer viewSlot isolation', () => { + it('two draw() calls with different viewSlot bind different @group(0) camera buffers', () => { + const device = mockDevice(); + const renderer = createStarCatalogRenderer(device, 'rgba16float'); + renderer.upload(Source.GaiaStars, CATALOG); + + const bindGroupsAt0: unknown[] = []; + const pass = { + setPipeline: vi.fn(), + setBindGroup: (slot: number, bg: unknown) => { + if (slot === 0) bindGroupsAt0.push(bg); + }, + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; + + // A sky-cubemap capture sweep: two faces, same source, same frame, + // before one submit(). + renderer.draw(pass, oneNodeArgs(1)); + renderer.draw(pass, oneNodeArgs(2)); + + expect(bindGroupsAt0).toHaveLength(2); + expect(bindGroupsAt0[0]).not.toBe(bindGroupsAt0[1]); + }); + + it('two draw() calls with different viewSlot write the camera uniform into different physical buffers', () => { + const device = mockDevice(); + const renderer = createStarCatalogRenderer(device, 'rgba16float'); + renderer.upload(Source.GaiaStars, CATALOG); + + renderer.draw(mockPass(), oneNodeArgs(1)); + renderer.draw(mockPass(), oneNodeArgs(2)); + + const writeBuffer = device.queue.writeBuffer as unknown as ReturnType; + const cameraWrites = writeBuffer.mock.calls.filter( + ([buf]) => + (buf as { label?: string }).label === 'star-catalog-camera-uniform-slot1' || + (buf as { label?: string }).label === 'star-catalog-camera-uniform-slot2', + ); + expect(cameraWrites).toHaveLength(2); + // Distinct buffer objects — slot 2's write never touched slot 1's buffer. + expect(cameraWrites[0]![0]).not.toBe(cameraWrites[1]![0]); + }); + + it('two draw() calls with different viewSlot allocate different NodeParams/prefix buffer pairs for the SAME source', () => { + const device = mockDevice(); + const renderer = createStarCatalogRenderer(device, 'rgba16float'); + renderer.upload(Source.GaiaStars, CATALOG); + + renderer.draw(mockPass(), oneNodeArgs(1)); + renderer.draw(mockPass(), oneNodeArgs(2)); + + const createBuffer = device.createBuffer as unknown as ReturnType; + const nodeParamsCreates = createBuffer.mock.calls.filter(([desc]) => + (desc as GPUBufferDescriptor).label?.includes('leaf-node-params'), + ); + const prefixCreates = createBuffer.mock.calls.filter(([desc]) => + (desc as GPUBufferDescriptor).label?.includes('leaf-prefix'), + ); + // One pair allocated per view slot — a shared pair would allocate once + // and just re-write it, which is exactly the race this closes. + expect(nodeParamsCreates.length).toBeGreaterThanOrEqual(2); + expect(prefixCreates.length).toBeGreaterThanOrEqual(2); + }); +}); diff --git a/tests/services/gpu/shaders/milkyWayPickUniformParity.test.ts b/tests/services/gpu/shaders/milkyWayPickUniformParity.test.ts index 1b898109cc..977ec8712a 100644 --- a/tests/services/gpu/shaders/milkyWayPickUniformParity.test.ts +++ b/tests/services/gpu/shaders/milkyWayPickUniformParity.test.ts @@ -99,6 +99,7 @@ function packSentinels(): ArrayBuffer { pxFadeEnd: 0, focusBindGroup: {} as unknown as GPUBindGroup, fadeOpacityOf: () => 1, + viewSlot: 0, }; return packGalaxyPointUniforms( viewProj as unknown as Mat4, diff --git a/tests/utils/gpu/createViewSlotUniformRing.test.ts b/tests/utils/gpu/createViewSlotUniformRing.test.ts new file mode 100644 index 0000000000..8882718568 --- /dev/null +++ b/tests/utils/gpu/createViewSlotUniformRing.test.ts @@ -0,0 +1,97 @@ +/** + * createViewSlotUniformRing — the view-slot buffer helper's own unit tests. + * + * Every renderer conversion (galaxyPointRenderer, starPointRenderer, + * starCatalogRenderer) leans on this ring for slot isolation; these tests + * pin the ring's own contract directly rather than re-deriving it per + * renderer: N distinct physical buffers + bind groups, `writeSlot` targets + * only its own slot's buffer, and `destroy` releases every one of them. + */ + +import { describe, it, expect, vi } from 'vitest'; +import { + createViewSlotUniformRing, + VIEW_SLOT_COUNT, +} from '../../../src/utils/gpu/createViewSlotUniformRing'; + +function mockDevice(): GPUDevice { + return { + createBuffer: vi.fn((desc: GPUBufferDescriptor) => ({ + label: desc.label, + size: desc.size, + destroy: vi.fn(), + })), + createBindGroup: vi.fn((desc: GPUBindGroupDescriptor) => ({ label: desc.label })), + queue: { writeBuffer: vi.fn() }, + } as unknown as GPUDevice; +} + +const LAYOUT = {} as unknown as GPUBindGroupLayout; + +describe('createViewSlotUniformRing', () => { + it('allocates VIEW_SLOT_COUNT buffers and bind groups by default, each sized byteSize', () => { + const device = mockDevice(); + createViewSlotUniformRing({ device, label: 'x', byteSize: 32, layout: LAYOUT }); + + const createBuffer = device.createBuffer as unknown as ReturnType; + const createBindGroup = device.createBindGroup as unknown as ReturnType; + expect(createBuffer).toHaveBeenCalledTimes(VIEW_SLOT_COUNT); + expect(createBindGroup).toHaveBeenCalledTimes(VIEW_SLOT_COUNT); + for (const [desc] of createBuffer.mock.calls) { + expect((desc as GPUBufferDescriptor).size).toBe(32); + } + }); + + it('honours an explicit slotCount', () => { + const device = mockDevice(); + createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT, slotCount: 3 }); + const createBuffer = device.createBuffer as unknown as ReturnType; + expect(createBuffer).toHaveBeenCalledTimes(3); + }); + + it('bindGroupOf returns a DIFFERENT bind group per slot', () => { + const device = mockDevice(); + const ring = createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT }); + const bg1 = ring.bindGroupOf(1); + const bg2 = ring.bindGroupOf(2); + expect(bg1).not.toBe(bg2); + // Stable identity across repeated reads of the SAME slot. + expect(ring.bindGroupOf(1)).toBe(bg1); + }); + + it('writeSlot(slot, …) writes into ONLY that slot physical buffer — the writeBuffer/submit race this closes', () => { + const device = mockDevice(); + const ring = createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT }); + const writeBuffer = device.queue.writeBuffer as unknown as ReturnType; + + // Two "faces" of a capture sweep, both writing before one submit(). + ring.writeSlot(1, new Float32Array([1, 2, 3, 4])); + ring.writeSlot(2, new Float32Array([5, 6, 7, 8])); + + expect(writeBuffer).toHaveBeenCalledTimes(2); + const buf1 = writeBuffer.mock.calls[0]![0]; + const buf2 = writeBuffer.mock.calls[1]![0]; + // Distinct destinations — slot 2's write can never land in slot 1's + // buffer, so a later read of slot 1 can never observe slot 2's bytes. + expect(buf1).not.toBe(buf2); + }); + + it('destroy releases every slot buffer exactly once', () => { + const device = mockDevice(); + const createBuffer = device.createBuffer as unknown as ReturnType; + const ring = createViewSlotUniformRing({ + device, + label: 'x', + byteSize: 16, + layout: LAYOUT, + slotCount: 4, + }); + const buffers = createBuffer.mock.results.map((r) => r.value as { destroy: () => void }); + + ring.destroy(); + + for (const buffer of buffers) { + expect(buffer.destroy).toHaveBeenCalledTimes(1); + } + }); +}); diff --git a/tests/utils/gpu/packGalaxyPointUniforms.test.ts b/tests/utils/gpu/packGalaxyPointUniforms.test.ts index eeb1839c9f..15523ec300 100644 --- a/tests/utils/gpu/packGalaxyPointUniforms.test.ts +++ b/tests/utils/gpu/packGalaxyPointUniforms.test.ts @@ -75,6 +75,9 @@ const SETTINGS: GalaxyPointDrawSettings = { // concern owned by the renderer. The pure packer receives the settings // shape, not the render loop. fadeOpacityOf: () => 1, + // packGalaxyPointUniforms omits viewSlot (Task 13b) from what it reads — + // it's the CALLER's GPU-destination choice, not a byte this struct encodes. + viewSlot: 0, }; // ─── Tests ──────────────────────────────────────────────────────────────────── From 0fe91316b44abbb5e179fe5b687c898dbbef4c42 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 16:59:16 +0200 Subject: [PATCH 32/60] fix(sgr-a-lensing): flip deflection rotation sign, stop skipping the inner march MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audit-driven fix round (task-13c-report.md, "Audit-driven fix round" section) against .superpowers/sdd/2026-09-01-render-black-hole/ audit-disk-math-vs-bruneton.md findings 1 and 3: - Finding 1: the ray-bend rotation used -bendAngle, rotating the ray away from the hole where Bruneton's delta_prime = delta + deflection (plus an independent analytic backward-trace and numeric geodesic scan) shows it must rotate toward the hole. This is why the disk's far side never rendered ("disc seems to be behind, not in front") and the sky's Einstein-ring displacement was inverted. One rotation feeds both the skybox sample and the annulus march's segment-2 direction, so the single sign flip fixes both. - Finding 3: the b < lutMinImpactParamRs (1 r_s) branch skipped the annulus march entirely, forcing pure black and cutting a hard bite out of the shadow centre where the disk's front crossing should read. Deleted the branch — sampleLut's saturate already clamps that domain to the sentinel texel, so the existing captured path (segment-1-only march, terminate black) still applies with identical semantics. Findings 2 (consequence of 1) confirmed resolved by the same fix; findings 4-9, 11-12 are deliberately deferred pending a user re-look. Co-Authored-By: Claude Fable 5 --- .../bodies/sgrAStarLensing/fragment.wesl | 55 ++++++++++--------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index 9eb7c3772f..e3148b5702 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -163,34 +163,37 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4(0.0); var alpha = 0.0; - if (impactParamRs < u.lutMinImpactParamRs) { - alpha = u.bandAlpha; // below the LUT's own domain — deep in the capture region + // No 'b < lutMinImpactParamRs' early-out: sampleLut's saturate already + // clamps that domain to the sentinel texel, so 'captured' below still + // comes out true and the march still runs — skipping it here only cut a + // black bite out of the shadow centre where the disk's front crossing + // should read (Task 13d audit finding 3). + let bendAngle = sampleLut(impactParamRs); + let captured = bendAngle >= CAPTURE_THRESHOLD_RAD; + // Bruneton: delta_prime = delta + deflection — the backward lookup must + // rotate the ray TOWARD the hole to recover the source's asymptotic + // direction. The apparent image is displaced outward, so undoing that + // displacement moves inward; '-bendAngle' bent the wrong way, which is + // why the disk's far side never rendered (Task 13d audit finding 1). + // Reused below as the annulus march's segment-2 bend (finding 3) — one + // basis for both consumers. + let axis = normalize(cross(rayDir, toAnchor)); + let deflected = normalize(rotateAroundAxis(rayDir, axis, bendAngle)); + + if (captured) { + alpha = u.bandAlpha; } else { - let bendAngle = sampleLut(impactParamRs); - let captured = bendAngle >= CAPTURE_THRESHOLD_RAD; - // Lensing displaces the apparent background AWAY from the lens centre: - // rotate the ray away from the hole by the LUT's bend angle to recover - // the source's asymptotic direction (sign/axis unverified visually, - // Task 17 gate). Reused below as the annulus march's segment-2 bend - // (finding 3) — one basis for both consumers. - let axis = normalize(cross(rayDir, toAnchor)); - let deflected = normalize(rotateAroundAxis(rayDir, axis, -bendAngle)); - - if (captured) { - alpha = u.bandAlpha; - } else { - color = textureSampleLevel(skyTex, skySampler, deflected, 0.0).rgb; - - // Soft edge fade to the billboard's rim so the earlier-drawn roster - // shows through once deflection is negligible (Blend.d.ts's 'over'). - let edgeFade = 1.0 - smoothstep(u.lutMaxImpactParamRs * 0.7, u.lutMaxImpactParamRs, impactParamRs); - alpha = u.bandAlpha * edgeFade; - } - - let annulus = annulusEmission(rayDir, toAnchor, closestT, deflected, captured, fragCoord.xy); - color += annulus.rgb; - alpha = max(alpha, u.bandAlpha * annulus.a); + color = textureSampleLevel(skyTex, skySampler, deflected, 0.0).rgb; + + // Soft edge fade to the billboard's rim so the earlier-drawn roster + // shows through once deflection is negligible (Blend.d.ts's 'over'). + let edgeFade = 1.0 - smoothstep(u.lutMaxImpactParamRs * 0.7, u.lutMaxImpactParamRs, impactParamRs); + alpha = u.bandAlpha * edgeFade; } + let annulus = annulusEmission(rayDir, toAnchor, closestT, deflected, captured, fragCoord.xy); + color += annulus.rgb; + alpha = max(alpha, u.bandAlpha * annulus.a); + return vec4(color * alpha, alpha); // premultiplied, per PREMULTIPLIED_OVER_BLEND } From 315e89eb1a089692b7e47036bbcb65071f87f061 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 17:08:56 +0200 Subject: [PATCH 33/60] fix(black-hole): per-face colour attachment for the sky-cubemap capture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round-1 fix for Task 13b's should-fix findings. `executeFrame` resolved every render step's colour attachment via `viewOf(target)`, which for `sky-cubemap` is the default whole-array `2d-array` view — so all 6 capture faces wrote the same layer. `RenderTargets.layerViewOf(id, face)` adds a cached single-layer `2d` view per array layer (mirroring the existing `cubeViewOf` pattern), and `executeFrame`'s `viewFor`/`renderGroup` route a capture step's colour attachment through it when `step.face` is set. Also: `starAggregatesLayer` sized its glow floor off the `star-aggregates` target even when drawing into the 256px `sky-cubemap` face during a capture — the viewport now follows the actual destination via `ctx.viewSlot`. Co-Authored-By: Claude Fable 5 --- src/@types/rendering/RenderTargets.d.ts | 12 +++++ src/services/engine/frame/executeFrame.ts | 20 ++++++- .../frame/passes/starAggregatesLayer.ts | 20 ++++--- src/services/gpu/renderTargets.ts | 32 +++++++++++ .../engine/frame/executeFrame.test.ts | 54 ++++++++++++++++--- .../frame/passes/createUpsampleLayer.test.ts | 3 ++ .../frame/passes/starAggregatesLayer.test.ts | 21 ++++++-- .../frame/passes/volumeUpsampleLayer.test.ts | 3 ++ tests/utils/gpu/hdrActiveOf.test.ts | 1 + 9 files changed, 146 insertions(+), 20 deletions(-) diff --git a/src/@types/rendering/RenderTargets.d.ts b/src/@types/rendering/RenderTargets.d.ts index 6dc701eeef..f22dfc3d54 100644 --- a/src/@types/rendering/RenderTargets.d.ts +++ b/src/@types/rendering/RenderTargets.d.ts @@ -61,6 +61,18 @@ export type RenderTargets = { * row with fewer than 6 layers, `swap`, and any unknown id. */ cubeViewOf(id: string): GPUTextureView; + /** + * A single-array-layer `dimension: '2d'` view over one layer of a row whose + * spec declares `fixedSizePx.layers > 1` — `viewOf`'s default view spans + * every layer (`2d-array`, no `baseArrayLayer`), which WebGPU rejects as a + * COLOUR ATTACHMENT once a texture has more than one layer. A capture pass + * that writes one array layer at a time (the Sgr A* lens's per-face + * sky-cubemap sweep) needs this instead of `viewOf`. Stable until the next + * `reconcile()` that changes this row's size, same guarantee as `viewOf`. + * Throws for a row with <= 1 layer, an out-of-range `layer`, `swap`, and + * any unknown id. + */ + layerViewOf(id: string, layer: number): GPUTextureView; /** * Current depth-attachment view for a row whose spec declares `depth` * (`foreground:0`). Stable until the next `reconcile()` that changes this diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index a832dc4d4a..1e3317e96b 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -65,6 +65,7 @@ import type { ContentLayer } from '../../../@types/engine/frame/ContentLayer'; import type { RenderStrategy } from '../../../@types/engine/frame/RenderStrategy'; import type { SlabView } from '../../../@types/engine/frame/SlabView'; import type { GpuTimingService } from '../../../@types/gpu/timing/GpuTimingService'; +import type { CubeFace } from '../../../@types/rendering/CubeFace'; import { slabViewOf, groupKeyOf, @@ -99,9 +100,21 @@ const COMPUTE: Record< * allocated texture like the offscreen rows — so it stays confined to this one * site: every other id resolves through the render-target table, which throws * for ids it never allocated. + * + * `face` (present only for a sky-cubemap capture render step, `FrameStep.face`) + * routes through `layerViewOf` instead of `viewOf` — the default view spans + * every array layer, which WebGPU rejects as a colour attachment once a row + * has more than one, so every capture face would otherwise write the SAME + * multi-layer view. */ -function viewFor(id: string, ctx: ReadyFrameContext, swapView: GPUTextureView): GPUTextureView { +function viewFor( + id: string, + ctx: ReadyFrameContext, + swapView: GPUTextureView, + face?: CubeFace, +): GPUTextureView { if (id === 'swap') return swapView; + if (face !== undefined) return ctx.renderTargets.layerViewOf(id, face); return ctx.renderTargets.viewOf(id); } @@ -275,6 +288,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { timing, swapView, target: step.target, + face: step.face, group, view, groupKey, @@ -343,6 +357,7 @@ function renderGroup( timing: GpuTimingService; swapView: GPUTextureView; target: string; + face?: CubeFace; group: readonly ContentLayer[]; view: SlabView; groupKey: string; @@ -357,13 +372,14 @@ function renderGroup( timing, swapView, target, + face, group, view, groupKey, alreadyTouched, depthLoadOp, } = p; - const targetView = viewFor(target, ctx, swapView); + const targetView = viewFor(target, ctx, swapView, face); if (strategy === 'merged') { // Tile-local: one pass holds the whole group, so OVER blends read coherent diff --git a/src/services/engine/frame/passes/starAggregatesLayer.ts b/src/services/engine/frame/passes/starAggregatesLayer.ts index c3465fe03d..fd1232b166 100644 --- a/src/services/engine/frame/passes/starAggregatesLayer.ts +++ b/src/services/engine/frame/passes/starAggregatesLayer.ts @@ -53,14 +53,18 @@ export const starAggregatesLayer: ContentLayer = { const prep = prepareStarCut(state, ctx); if (prep === null) return; - // Viewport is the star-aggregates target's allocated size (see - // `sizeOf`), not the canvas: STAR_GLOW_MIN_PX floors the glow radius in - // pixels OF THE TARGET BEING RASTERISED, so the canvas size would make - // the floor 0.75 texels here and land floor-clamped aggregates sub-texel - // (dropout and flicker, not wrong brightness — `toRefPx` keeps the - // photometry viewport-independent). The view is COPIED rather than - // mutated: one `SlabView` is shared by every layer in the render step. - const { width: vw, height: vh } = ctx.renderTargets.sizeOf('star-aggregates'); + // Viewport is the DESTINATION target's allocated size (see `sizeOf`), not + // the canvas: STAR_GLOW_MIN_PX floors the glow radius in pixels OF THE + // TARGET BEING RASTERISED, so the canvas size would make the floor 0.75 + // texels here and land floor-clamped aggregates sub-texel (dropout and + // flicker, not wrong brightness — `toRefPx` keeps the photometry + // viewport-independent). `viewSlot !== 0` marks a sky-cubemap capture draw + // (this layer's `skyCapture` flag, see `ReadyFrameContext.viewSlot`'s + // doc), which targets the 256px `sky-cubemap` face, not this row. The view + // is COPIED rather than mutated: one `SlabView` is shared by every layer + // in the render step. + const destTarget = ctx.viewSlot !== 0 ? 'sky-cubemap' : 'star-aggregates'; + const { width: vw, height: vh } = ctx.renderTargets.sizeOf(destTarget); drawStream( renderer, diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index f07e931d7e..b62cbd8bbf 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -306,6 +306,13 @@ export function createRenderTargets( // (data-driven, not a hardcoded 'sky-cubemap' id check) so a future second // 6-layer row gets one for free. const cubeViews = new Map(); + // One single-array-layer `dimension: '2d'` view per layer, for a row whose + // `views`' default (a whole-array `2d-array` view with no `baseArrayLayer`) + // is unusable as a COLOUR ATTACHMENT when the row has more than one layer — + // WebGPU rejects a multi-layer view there. Only the sky-cubemap capture + // needs this today (`executeFrame`'s per-face colour attachment), gated the + // same data-driven way as `cubeViews` rather than a hardcoded id check. + const layerViews = new Map(); const depthTextures = new Map(); const depthViews = new Map(); // Recorded beside `textures`/`views` so `sizeOf` never reads a texture's @@ -346,6 +353,20 @@ export function createRenderTargets( }), ); } + const layerCount = spec.fixedSizePx?.layers ?? 1; + if (layerCount > 1) { + layerViews.set( + spec.id, + Array.from({ length: layerCount }, (_unused, layer) => + texture.createView({ + label: `render-target-${spec.id}-layer${layer}-view`, + dimension: '2d', + baseArrayLayer: layer, + arrayLayerCount: 1, + }), + ), + ); + } if (spec.depth) { depthTextures.get(spec.id)?.destroy(); @@ -432,6 +453,16 @@ export function createRenderTargets( } return view; }, + layerViewOf(id: string, layer: number): GPUTextureView { + const view = layerViews.get(id)?.[layer]; + if (!view) { + // Covers a row with <= 1 layer, an out-of-range layer index, 'swap', + // unknown ids, and use-after-destroy — same loud-failure discipline + // as `viewOf`. + throw new Error(`renderTargets: no layer view for target '${id}' layer ${layer}`); + } + return view; + }, depthViewOf(id: string): GPUTextureView { const view = depthViews.get(id); if (!view) { @@ -452,6 +483,7 @@ export function createRenderTargets( textures.clear(); views.clear(); cubeViews.clear(); + layerViews.clear(); depthTextures.clear(); depthViews.clear(); sizes.clear(); diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index 9f4b2a02da..9586697527 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -151,6 +151,12 @@ const FG_VIEW = { __id: 'foreground-view' } as unknown as GPUTextureView; const FG_DEPTH_VIEW = { __id: 'foreground-depth-view' } as unknown as GPUTextureView; const SWAP_VIEW = { __id: 'swap-view' } as unknown as GPUTextureView; const SKY_CUBEMAP_VIEW = { __id: 'sky-cubemap-view' } as unknown as GPUTextureView; +// One distinct view per capture face — proves `layerViewOf` (not the shared +// `viewOf`) resolves a capture step's colour attachment, and that each face +// lands on its OWN layer rather than all six colliding on one. +const SKY_CUBEMAP_FACE_VIEWS: readonly GPUTextureView[] = [0, 1, 2, 3, 4, 5].map( + (face) => ({ __id: `sky-cubemap-face${face}-view` }) as unknown as GPUTextureView, +); const EXEC_SPECS = [ { @@ -223,6 +229,11 @@ function makeCtx(): ReadyFrameContext { if (id === 'sky-cubemap') return SKY_CUBEMAP_VIEW; throw new Error(`mock renderTargets: no view for '${id}'`); }, + layerViewOf: (id: string, face: number) => { + const view = id === 'sky-cubemap' ? SKY_CUBEMAP_FACE_VIEWS[face] : undefined; + if (!view) throw new Error(`mock renderTargets: no layer view for '${id}' layer ${face}`); + return view; + }, depthViewOf: (id: string) => { if (id === 'foreground:0') return FG_DEPTH_VIEW; throw new Error(`mock renderTargets: no depth view for '${id}'`); @@ -294,16 +305,17 @@ function makeArgs(over: { return { args, env }; } -/** The recorded attachment of the pass a given layer.draw spy drew into. */ +/** The recorded attachment of the pass a given layer.draw spy's `callIndex` call drew into. */ function attachmentOfDraw( env: ReturnType, layer: SpyLayer, + callIndex = 0, ): { loadOp: string; clearValue?: GPUColor; view: GPUTextureView; } { - const pass = layer.draw.mock.calls[0]![0] as GPURenderPassEncoder; + const pass = layer.draw.mock.calls[callIndex]![0] as GPURenderPassEncoder; const rec = env.passes.find((p) => p.pass === pass)!; const att = Array.from(rec.desc.colorAttachments as Iterable)[0] as { view: GPUTextureView; @@ -824,10 +836,40 @@ describe('executeFrame', () => { }); executeFrame(args); expect(layer.draw).toHaveBeenCalledTimes(1); - // The pass it drew into is the 'sky-cubemap' colour attachment, not - // 'hdr' — the step's target wins for the PASS, regardless of the - // layer's own `target` field (which only gated selection above). - expect(attachmentOfDraw(env, layer).view).toBe(SKY_CUBEMAP_VIEW); + // The pass it drew into is face 3's OWN sky-cubemap layer view, not + // 'hdr' and not the shared whole-array `viewOf('sky-cubemap')` — the + // step's `(target, face)` wins for the PASS, regardless of the layer's + // own `target` field (which only gated selection above). + expect(attachmentOfDraw(env, layer).view).toBe(SKY_CUBEMAP_FACE_VIEWS[3]); + expect(attachmentOfDraw(env, layer).view).not.toBe(SKY_CUBEMAP_VIEW); + }); + + it('resolves EACH capture face to its OWN colour-attachment view, distinct per face and from viewOf', () => { + // Pins the real bug: before the fix, every capture step resolved the + // same multi-layer `viewOf('sky-cubemap')` regardless of `step.face`, + // so all 6 faces wrote the same texture layer. + const layer = makeLayer({ name: 'probe', target: 'hdr', slab: NEAR0, skyCapture: true }); + const program: FrameStep[] = [0, 1, 2, 3, 4, 5].map( + (face): FrameStep => ({ + kind: 'render', + target: 'sky-cubemap', + slab: NEAR0, + face: face as CubeFace, + }), + ); + const faceCtx = makeCtx(); + const skyCubemapFaceContexts = new Map( + [0, 1, 2, 3, 4, 5].map((face) => [face as CubeFace, faceCtx]), + ); + const { args, env } = makeArgs({ program, layers: [layer], skyCubemapFaceContexts }); + executeFrame(args); + + expect(layer.draw).toHaveBeenCalledTimes(6); + const viewsPerFace = [0, 1, 2, 3, 4, 5].map( + (face) => attachmentOfDraw(env, layer, face).view, + ); + for (const view of viewsPerFace) expect(view).not.toBe(SKY_CUBEMAP_VIEW); + expect(new Set(viewsPerFace).size).toBe(6); }); it('never selects a capture step group by target alone — a layer targeting sky-cubemap without the flag is skipped', () => { diff --git a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts index 04aee6cfd3..03645c3c69 100644 --- a/tests/services/engine/frame/passes/createUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/createUpsampleLayer.test.ts @@ -70,6 +70,9 @@ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFra cubeViewOf: (id: string): GPUTextureView => { throw new Error(`fixture renderTargets: no cube view for '${id}'`); }, + layerViewOf: (id: string, layer: number): GPUTextureView => { + throw new Error(`fixture renderTargets: no layer view for '${id}' layer ${layer}`); + }, depthViewOf: (id: string): GPUTextureView => { throw new Error(`fixture renderTargets: no depth view for '${id}'`); }, diff --git a/tests/services/engine/frame/passes/starAggregatesLayer.test.ts b/tests/services/engine/frame/passes/starAggregatesLayer.test.ts index 6e90afbca1..686f4c6da8 100644 --- a/tests/services/engine/frame/passes/starAggregatesLayer.test.ts +++ b/tests/services/engine/frame/passes/starAggregatesLayer.test.ts @@ -37,17 +37,20 @@ function camAtPcVec(pc: Readonly): Vec3 { // The layer reads its viewport via `sizeOf('star-aggregates')` — the fixture // hardcodes the size the production table's scale: 2 implies for the 1280x720 -// canvas below (floor(1280 / 2), floor(720 / 2)). -function makeCtx(camPos: Readonly, nowMs = 0): ReadyFrameContext { +// canvas below (floor(1280 / 2), floor(720 / 2)) — or, during a capture draw +// (`viewSlot !== 0`), `sizeOf('sky-cubemap')`'s fixed 256px face. +function makeCtx(camPos: Readonly, nowMs = 0, viewSlot = 0): ReadyFrameContext { return { drawCamPos: camPos, nowMs, + viewSlot, canvasSize: { width: 1280, height: 720 }, renderTargets: { specs: [{ id: 'star-aggregates', scale: 2 }], sizeOf: (id: string) => { - if (id !== 'star-aggregates') throw new Error(`fixture renderTargets: no size for '${id}'`); - return { width: 640, height: 360 }; + if (id === 'star-aggregates') return { width: 640, height: 360 }; + if (id === 'sky-cubemap') return { width: 256, height: 256 }; + throw new Error(`fixture renderTargets: no size for '${id}'`); }, }, } as unknown as ReadyFrameContext; @@ -139,6 +142,16 @@ describe('starAggregatesLayer', () => { expect(view.viewportPx).toEqual([1280, 720]); }); + it('sizes sprites against the sky-cubemap face during a capture draw (viewSlot !== 0), not star-aggregates', () => { + const renderer = makeRenderer([{ source: Source.GaiaStars, catalog: makeAggregateCatalog() }]); + const camPos = camAtPcVec(FAR_PC); + const view = makeNear0View(camPos); + starAggregatesLayer.draw(PASS_STUB, view, makeCtx(camPos, 0, 1), makeState(renderer)); + + const args = renderer.draw.mock.calls[0]![1]; + expect(args.viewportPx).toEqual([256, 256]); + }); + it('is a no-op when the renderer handle is null (pre-bootstrap)', () => { const camPos = camAtPcVec(FAR_PC); const state = makeState(null); diff --git a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts index 51cb0c8825..5142331820 100644 --- a/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts +++ b/tests/services/engine/frame/passes/volumeUpsampleLayer.test.ts @@ -72,6 +72,9 @@ function makeCtx(offscreenView: GPUTextureView = {} as GPUTextureView): ReadyFra cubeViewOf: (id: string): GPUTextureView => { throw new Error(`fixture renderTargets: no cube view for '${id}'`); }, + layerViewOf: (id: string, layer: number): GPUTextureView => { + throw new Error(`fixture renderTargets: no layer view for '${id}' layer ${layer}`); + }, // No row in this fixture declares depth, and the upsample layer never // asks for a depth view — throwing mirrors the real table's behaviour // for depthless rows. diff --git a/tests/utils/gpu/hdrActiveOf.test.ts b/tests/utils/gpu/hdrActiveOf.test.ts index e33918b30c..4f00fa9070 100644 --- a/tests/utils/gpu/hdrActiveOf.test.ts +++ b/tests/utils/gpu/hdrActiveOf.test.ts @@ -17,6 +17,7 @@ function makeStub(specs: readonly RenderTargetSpec[]): RenderTargets { sizeOf: vi.fn(), viewOf: vi.fn(), cubeViewOf: vi.fn(), + layerViewOf: vi.fn(), depthViewOf: vi.fn(), reconcile: vi.fn(), setSwapFormat: vi.fn(), From d15e95e9ac1774cfe0fd454889b335fee6864c6b Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 17:26:17 +0200 Subject: [PATCH 34/60] fix(black-hole): capture the sky cubemap from the camera, not Sgr A* MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The lens fragment samples the cubemap by deflected ray direction from the camera's viewpoint, but the capture eye was fixed at Sgr A*'s position — for near-field content (S-stars at AU distances) the parallax between the two viewpoints visibly mismatched the lensed region against the directly rendered sky at the escape-fade boundary. Capturing from the camera converges the cubemap to exactly what the camera sees where deflection is negligible, per standard environment- map practice (Bruneton). The movement-threshold escape valve now scales with the camera's current distance to Sgr A* (a named fraction, 3%) rather than a fixed AU displacement — the fixed threshold would near-never fire during the descent to the 2·r_s floor (~0.17 AU) where a small absolute move is a large fraction of the camera's distance from the hole. Co-Authored-By: Claude Fable 5 --- src/services/engine/frame/renderFrame.ts | 26 ++++++++++--------- .../engine/frame/skyCubemapCaptureSchedule.ts | 12 +++++++-- .../renderFrame.skyCubemapHandOff.test.ts | 18 ++++++++++--- 3 files changed, 38 insertions(+), 18 deletions(-) diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 05970daba4..ee2a972cd6 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -62,7 +62,7 @@ import { CONTENT_LAYERS } from './passes'; import { hdrActiveOf } from '../../../utils/gpu/hdrActiveOf'; import { skyCubemapCaptureSchedule, - SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU, + SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, } from './skyCubemapCaptureSchedule'; import { skyCubemapFaceContext } from './skyCubemapFaceContext'; import { sceneBodyStates } from './sceneBodyStates'; @@ -71,11 +71,7 @@ import { regionRelativeDistanceMpc } from '../../../utils/scene/regionRelativeDi import { distanceMpc } from '../../../utils/math/distanceMpc'; import { fadeBand } from '../../../utils/math/fadeBand'; import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; -import { SCALE_UNITS } from '../../../data/scaleUnits'; -import { SGR_A_STAR, SGR_A_STAR_ANCHOR } from '../../../data/bodies/sceneSgrAStar'; - -const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC = - SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU * SCALE_UNITS.AU_TO_MPC; +import { SGR_A_STAR } from '../../../data/bodies/sceneSgrAStar'; /** * Encode and submit one frame. Synchronous: by the time it returns, the GPU @@ -145,14 +141,14 @@ export function renderFrame(input: RenderFrameInput): void { )?.index ?? null) : null; const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; - // Every captured face's content (which galaxies/stars are visible, their - // backdrop-fade alpha) is keyed on the PLAYER's camera position, not the - // fixed capture eye at Sgr A* — so a big enough move stales every face at - // once, same as band entry. + // Threshold is a FRACTION of `gcDistanceMpc`, not an absolute distance: + // the capture eye is the camera itself, so a fixed AU threshold would + // near-never fire at the 2·r_s descent floor (~0.17 AU) while being too + // loose at the 500 AU band edge — see the constant's own docblock. const cameraMovedBeyondThreshold = captureRuntime.lastSweepCamPosMpc !== null && distanceMpc(ctx.drawCamPos, captureRuntime.lastSweepCamPosMpc) > - SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_MPC; + SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION * gcDistanceMpc; const skyCubemapFacesToCapture: readonly CubeFace[] = bandActive ? skyCubemapCaptureSchedule({ bandJustEngaged, @@ -185,7 +181,13 @@ export function renderFrame(input: RenderFrameInput): void { for (const face of skyCubemapFacesToCapture) { const faceCtx = skyCubemapFaceContext({ state, - eyeMpc: SGR_A_STAR_ANCHOR.positionMpc, + // The live camera's position, NOT the hole's: a hole-centred capture + // parallaxes against the camera's own view for near-field content + // (S-stars at AU distances), visibly mismatching the lens against + // the directly rendered sky at the escape-fade boundary. Capturing + // from the camera converges to exactly what it sees where deflection + // is negligible — standard environment-map practice (Bruneton). + eyeMpc: ctx.drawCamPos, face, faceSizePx, }); diff --git a/src/services/engine/frame/skyCubemapCaptureSchedule.ts b/src/services/engine/frame/skyCubemapCaptureSchedule.ts index 9f51c34e72..afe4574c1e 100644 --- a/src/services/engine/frame/skyCubemapCaptureSchedule.ts +++ b/src/services/engine/frame/skyCubemapCaptureSchedule.ts @@ -12,8 +12,16 @@ const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; /** Escape-valve staleness threshold. Data tuning, sited beside the schedule it gates. */ export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; -/** Escape-valve camera-movement threshold, AU — see `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation for the comparison and why. */ -export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_AU = 10; +/** + * Escape-valve camera-movement threshold, as a FRACTION of the camera's + * current distance to Sgr A* — not an absolute distance. The capture eye is + * now the camera itself (fix round 2), so the parallax a given displacement + * introduces scales with displacement/distance, not displacement alone: a + * fixed AU threshold would near-never fire during the descent to the event + * horizon (camera distance ~0.17 AU at the 2·r_s floor) while under-firing + * nowhere else. See `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation. + */ +export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION = 0.03; export type SkyCubemapCaptureSchedule = { readonly facesToCapture: readonly CubeFace[]; // this frame's capture list diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index 84d8486fcb..1d629f62b2 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -28,6 +28,7 @@ vi.mock('../../../../src/services/engine/frame/skyCubemapFaceContext', () => ({ import { renderFrame } from '../../../../src/services/engine/frame/renderFrame'; import { createDisabledGpuTimingService } from '../../../../src/services/gpu/timing/gpuTimingService'; import { SGR_A_STAR_ANCHOR } from '../../../../src/data/bodies/sceneSgrAStar'; +import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import type { ReadyFrameContext } from '../../../../src/@types/engine/frame/ReadyFrameContext'; import type { EngineState } from '../../../../src/@types/engine/state/EngineState'; import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; @@ -99,7 +100,7 @@ describe('renderFrame — sky-cubemap runtime hand-off', () => { skyCubemapFaceContextMock.mockClear(); }); - it('derives each scheduled face via skyCubemapFaceContext(eye=Sgr A*, faceSizePx=row size) and threads the map into executeFrame', () => { + it('derives each scheduled face via skyCubemapFaceContext(eye=camera, faceSizePx=row size) and threads the map into executeFrame', () => { const faceCtxByFace = new Map(); skyCubemapFaceContextMock.mockImplementation((input: { face: CubeFace }) => { const ctx = { __face: input.face } as unknown as ReadyFrameContext; @@ -107,13 +108,22 @@ describe('renderFrame — sky-cubemap runtime hand-off', () => { return ctx; }); - const ctx = makeCtx(SGR_A_STAR_ANCHOR.positionMpc); + // Offset 50 AU from the anchor — inside the lensing band (fullAt = 100 + // AU) but NOT at the anchor itself, so a wrong revert to a hole-centred + // capture (`eyeMpc: SGR_A_STAR_ANCHOR.positionMpc`) is distinguishable + // from the fix (`eyeMpc: ctx.drawCamPos`) instead of the two coinciding. + const camPos: readonly [number, number, number] = [ + SGR_A_STAR_ANCHOR.positionMpc[0] + 50 * SCALE_UNITS.AU_TO_MPC, + SGR_A_STAR_ANCHOR.positionMpc[1], + SGR_A_STAR_ANCHOR.positionMpc[2], + ]; + const ctx = makeCtx(camPos); renderFrame(makeInput(ctx, makeState())); - // Distance 0 from the anchor, first frame ever ⇒ bandJustEngaged ⇒ full sweep. + // First frame ever ⇒ bandJustEngaged ⇒ full sweep. expect(skyCubemapFaceContextMock).toHaveBeenCalledTimes(6); for (const call of skyCubemapFaceContextMock.mock.calls) { - expect(call[0]).toMatchObject({ eyeMpc: SGR_A_STAR_ANCHOR.positionMpc, faceSizePx: 256 }); + expect(call[0]).toMatchObject({ eyeMpc: camPos, faceSizePx: 256 }); } expect(skyCubemapFaceContextMock.mock.calls.map((c) => c[0].face).sort()).toEqual([ ...ALL_FACES, From cb06e62a859b8a28a75f150e291f601feb6f5b9d Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 17:50:22 +0200 Subject: [PATCH 35/60] fix(black-hole): pin the sky-cubemap capture eye across a sweep MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixing round 2's live-camera capture eye per frame flickered: round-robin faces were each captured from a DIFFERENT camera position, so per-face parallax jumped every frame and adjacent faces disagreed at their shared border. The capture eye is now PINNED at each full 6-face sweep (band entry, or live camera displacement past the movement threshold) and reused by every round-robin refresh until the next sweep — all six faces share one eye, so they stay mutually coherent between sweeps. `SkyCubemapCaptureRuntime`'s `lastSweepCamPosMpc` (a comparison baseline only) becomes `pinnedEyeMpc` (also the actual capture eye). `skyCubemapCaptureSchedule`'s two full-sweep reasons (`bandJustEngaged`, `cameraMovedBeyondThreshold`) fold into one caller-computed `fullSweepTriggered` flag, since the pure function only ever needs to know THAT a sweep is due, not why. Co-Authored-By: Claude Fable 5 --- .../state/SkyCubemapCaptureRuntime.d.ts | 11 ++- src/services/engine/engine.ts | 2 +- src/services/engine/frame/renderFrame.ts | 42 ++++++------ .../engine/frame/skyCubemapCaptureSchedule.ts | 35 +++++----- .../playClipFlyout.integration.test.ts | 2 +- .../engine/camera/commitOnEdge.test.ts | 2 +- .../renderFrame.skyCubemapHandOff.test.ts | 67 ++++++++++++++++++- .../services/engine/frame/renderFrame.test.ts | 2 +- .../engine/frame/renderFrame.timing.test.ts | 2 +- .../frame/skyCubemapCaptureSchedule.test.ts | 26 ++----- tests/visual/renderFrameSplitBaseline.test.ts | 2 +- 11 files changed, 125 insertions(+), 68 deletions(-) diff --git a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts index c2f4d13f8e..593dca43df 100644 --- a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts +++ b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts @@ -20,6 +20,13 @@ export type SkyCubemapCaptureRuntime = { frameIndex: number; /** The lensing band's active/inactive state last frame — `bandJustEngaged`'s edge. */ wasBandActive: boolean; - /** Camera position at the last FULL sweep (band entry or escape valve), for the movement check. `null` before the first sweep. */ - lastSweepCamPosMpc: Readonly | null; + /** + * The eye EVERY face was captured from at the last full sweep. Round-robin + * refreshes reuse this same pinned eye rather than the live camera each + * frame — a per-frame live eye made adjacent faces disagree at their + * shared border and the whole cubemap flicker as the camera moved. + * Re-pinned to the live camera on each full sweep (band entry, or camera + * displacement past the movement threshold). `null` before the first sweep. + */ + pinnedEyeMpc: Readonly | null; }; diff --git a/src/services/engine/engine.ts b/src/services/engine/engine.ts index 4efd2a1abe..664c323214 100644 --- a/src/services/engine/engine.ts +++ b/src/services/engine/engine.ts @@ -188,7 +188,7 @@ export function createEngine(canvas: HTMLCanvasElement, cb: EngineCallbacks): En lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }; diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index ee2a972cd6..25b1b0c707 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -141,29 +141,33 @@ export function renderFrame(input: RenderFrameInput): void { )?.index ?? null) : null; const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; - // Threshold is a FRACTION of `gcDistanceMpc`, not an absolute distance: - // the capture eye is the camera itself, so a fixed AU threshold would - // near-never fire at the 2·r_s descent floor (~0.17 AU) while being too - // loose at the 500 AU band edge — see the constant's own docblock. + // Measured against the PINNED eye, not the live camera each frame: a + // fresh live eye per round-robin face made adjacent faces disagree at + // their shared border and the whole cubemap flicker as the camera moved + // (fix round 3). Threshold is a FRACTION of `gcDistanceMpc` — see the + // constant's own docblock for why a fixed AU distance is wrong here. const cameraMovedBeyondThreshold = - captureRuntime.lastSweepCamPosMpc !== null && - distanceMpc(ctx.drawCamPos, captureRuntime.lastSweepCamPosMpc) > + captureRuntime.pinnedEyeMpc !== null && + distanceMpc(ctx.drawCamPos, captureRuntime.pinnedEyeMpc) > SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION * gcDistanceMpc; + const fullSweepTriggered = bandJustEngaged || cameraMovedBeyondThreshold; + // Re-pin BEFORE scheduling so a triggered full sweep — including this + // frame's own faces — samples the eye it was triggered by, not the eye it + // just moved past. + if (fullSweepTriggered) { + captureRuntime.pinnedEyeMpc = ctx.drawCamPos; + } const skyCubemapFacesToCapture: readonly CubeFace[] = bandActive ? skyCubemapCaptureSchedule({ - bandJustEngaged, + fullSweepTriggered, frameIndex: captureRuntime.frameIndex, lastCapturedAtMs: captureRuntime.lastCapturedAtMs, nowMs: ctx.nowMs, - cameraMovedBeyondThreshold, }).facesToCapture : []; for (const face of skyCubemapFacesToCapture) { captureRuntime.lastCapturedAtMs.set(face, ctx.nowMs); } - if (bandJustEngaged || cameraMovedBeyondThreshold) { - captureRuntime.lastSweepCamPosMpc = ctx.drawCamPos; - } captureRuntime.wasBandActive = bandActive; captureRuntime.frameIndex += 1; @@ -176,18 +180,18 @@ export function renderFrame(input: RenderFrameInput): void { // comes back null (pre-bootstrap) is simply omitted — `executeFrame` treats // a missing map entry as "skip this step cleanly" (see its module header). const skyCubemapFaceContexts = new Map(); - if (skyCubemapFacesToCapture.length > 0) { + const pinnedEyeMpc = captureRuntime.pinnedEyeMpc; + if (skyCubemapFacesToCapture.length > 0 && pinnedEyeMpc !== null) { const faceSizePx = ctx.renderTargets.specOf('sky-cubemap').fixedSizePx!.size; for (const face of skyCubemapFacesToCapture) { const faceCtx = skyCubemapFaceContext({ state, - // The live camera's position, NOT the hole's: a hole-centred capture - // parallaxes against the camera's own view for near-field content - // (S-stars at AU distances), visibly mismatching the lens against - // the directly rendered sky at the escape-fade boundary. Capturing - // from the camera converges to exactly what it sees where deflection - // is negligible — standard environment-map practice (Bruneton). - eyeMpc: ctx.drawCamPos, + // The PINNED eye (see `pinnedEyeMpc`'s docblock), not the live + // camera: all six faces must share one eye or they disagree at + // their shared border. Still camera-relative overall, not the + // hole's — see this fix's round-2 commit for the boundary-seam + // rationale that motivated moving off the hole in the first place. + eyeMpc: pinnedEyeMpc, face, faceSizePx, }); diff --git a/src/services/engine/frame/skyCubemapCaptureSchedule.ts b/src/services/engine/frame/skyCubemapCaptureSchedule.ts index afe4574c1e..41c216eac0 100644 --- a/src/services/engine/frame/skyCubemapCaptureSchedule.ts +++ b/src/services/engine/frame/skyCubemapCaptureSchedule.ts @@ -1,8 +1,8 @@ /** * skyCubemapCaptureSchedule — the black-hole sky cubemap's amortized capture - * schedule: a full 6-face sweep on band ENTRY, then one face per frame in - * round-robin, with an escape valve for a stale or camera-moved face. Pure — - * every input is a plain value — so it's testable headlessly. + * schedule: a full 6-face sweep on band ENTRY or pinned-eye movement, then + * one face per frame in round-robin, with an escape valve for a stale face. + * Pure — every input is a plain value — so it's testable headlessly. */ import type { CubeFace } from '../../../@types/rendering/CubeFace'; @@ -13,13 +13,13 @@ const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; /** - * Escape-valve camera-movement threshold, as a FRACTION of the camera's - * current distance to Sgr A* — not an absolute distance. The capture eye is - * now the camera itself (fix round 2), so the parallax a given displacement - * introduces scales with displacement/distance, not displacement alone: a - * fixed AU threshold would near-never fire during the descent to the event - * horizon (camera distance ~0.17 AU at the 2·r_s floor) while under-firing - * nowhere else. See `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation. + * Escape-valve movement threshold, as a FRACTION of the camera's current + * distance to Sgr A* — not an absolute distance. The pinned capture eye + * (fix round 3) only moves on a full sweep, so this measures how far the + * LIVE camera has drifted from that pinned eye: a fixed AU threshold would + * near-never fire during the descent to the event horizon (camera distance + * ~0.17 AU at the 2·r_s floor) while under-firing nowhere else. See + * `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation. */ export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION = 0.03; @@ -28,18 +28,19 @@ export type SkyCubemapCaptureSchedule = { }; export function skyCubemapCaptureSchedule(input: { - readonly bandJustEngaged: boolean; // band alpha crossed 0→positive this frame + // Band just engaged OR the live camera drifted past the pinned-eye + // threshold — either forces every face, so the caller pre-folds both + // reasons into one flag rather than this function re-deriving them. + readonly fullSweepTriggered: boolean; readonly frameIndex: number; // for round-robin readonly lastCapturedAtMs: ReadonlyMap; readonly nowMs: number; - readonly cameraMovedBeyondThreshold: boolean; }): SkyCubemapCaptureSchedule { - const { bandJustEngaged, frameIndex, lastCapturedAtMs, nowMs, cameraMovedBeyondThreshold } = - input; + const { fullSweepTriggered, frameIndex, lastCapturedAtMs, nowMs } = input; - if (bandJustEngaged || cameraMovedBeyondThreshold) { - // A moved eye invalidates every face at once — same as band entry, no - // partial-sweep half-state to reason about. + if (fullSweepTriggered) { + // A re-pinned eye invalidates every face at once — same as band entry, + // no partial-sweep half-state to reason about. return { facesToCapture: ALL_CUBE_FACES }; } diff --git a/tests/services/engine/animation/playClipFlyout.integration.test.ts b/tests/services/engine/animation/playClipFlyout.integration.test.ts index 9cbb382f32..bff73e9531 100644 --- a/tests/services/engine/animation/playClipFlyout.integration.test.ts +++ b/tests/services/engine/animation/playClipFlyout.integration.test.ts @@ -122,7 +122,7 @@ function makeEngineState(startDistance: number): { lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }, }; diff --git a/tests/services/engine/camera/commitOnEdge.test.ts b/tests/services/engine/camera/commitOnEdge.test.ts index a07a62d9ab..1d35f34ebc 100644 --- a/tests/services/engine/camera/commitOnEdge.test.ts +++ b/tests/services/engine/camera/commitOnEdge.test.ts @@ -98,7 +98,7 @@ function makeEngineState(): { lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }, }; diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index 1d629f62b2..c47d219558 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -1,12 +1,15 @@ /** * renderFrame — sky-cubemap runtime hand-off (Task 12's "Name the runtime - * hand-off" step, built in round 1's fix-up). + * hand-off" step, built in round 1's fix-up; eye source revised in fix + * rounds 2 and 3 — see those commits). * * `executeFrame` and `skyCubemapFaceContext` are both mocked: this file * is about the WIRING — renderFrame calling `skyCubemapFaceContext` once per * scheduled face with the black hole's eye/face/row-declared size, and * threading the resulting map into `executeFrame`'s `skyCubemapFaceContexts` - * — not the GPU pass machinery `renderFrame.test.ts` already covers. + * — not the GPU pass machinery `renderFrame.test.ts` already covers. Fix + * round 3's PINNED-eye tests drive `renderFrame` across two calls sharing one + * `state` object, since the pin only lives in `cameraRuntime` between frames. */ import { describe, it, expect, vi, beforeEach } from 'vitest'; @@ -41,7 +44,7 @@ function makeCaptureRuntime() { lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }; } @@ -163,4 +166,62 @@ describe('renderFrame — sky-cubemap runtime hand-off', () => { >; expect(handedOff.size).toBe(0); }); + + it('round-robin faces reuse the PINNED eye, not the live camera, after a sub-threshold move (fix round 3)', () => { + skyCubemapFaceContextMock.mockImplementation( + (input: { face: CubeFace }) => ({ __face: input.face }) as unknown as ReadyFrameContext, + ); + + const state = makeState(); + const pinnedEye: readonly [number, number, number] = [ + SGR_A_STAR_ANCHOR.positionMpc[0] + 50 * SCALE_UNITS.AU_TO_MPC, + SGR_A_STAR_ANCHOR.positionMpc[1], + SGR_A_STAR_ANCHOR.positionMpc[2], + ]; + renderFrame(makeInput(makeCtx(pinnedEye), state)); // band entry ⇒ full sweep, pins the eye + skyCubemapFaceContextMock.mockClear(); + + // 0.1 AU move, well under 3% of the ~50 AU distance to Sgr A* (~1.5 AU) — + // stays a round-robin frame, not a re-pinning full sweep. + const movedSubThreshold: readonly [number, number, number] = [ + pinnedEye[0] + 0.1 * SCALE_UNITS.AU_TO_MPC, + pinnedEye[1], + pinnedEye[2], + ]; + renderFrame(makeInput(makeCtx(movedSubThreshold), state)); + + // Round-robin picks exactly one face; a revert to a live camera eye + // would hand it `movedSubThreshold`, not the pinned position. + expect(skyCubemapFaceContextMock).toHaveBeenCalledTimes(1); + expect(skyCubemapFaceContextMock.mock.calls[0]![0]).toMatchObject({ eyeMpc: pinnedEye }); + }); + + it('a super-threshold move re-pins the eye and forces a full 6-face sweep (fix round 3)', () => { + skyCubemapFaceContextMock.mockImplementation( + (input: { face: CubeFace }) => ({ __face: input.face }) as unknown as ReadyFrameContext, + ); + + const state = makeState(); + const pinnedEye: readonly [number, number, number] = [ + SGR_A_STAR_ANCHOR.positionMpc[0] + 50 * SCALE_UNITS.AU_TO_MPC, + SGR_A_STAR_ANCHOR.positionMpc[1], + SGR_A_STAR_ANCHOR.positionMpc[2], + ]; + renderFrame(makeInput(makeCtx(pinnedEye), state)); // band entry ⇒ full sweep, pins the eye + skyCubemapFaceContextMock.mockClear(); + + // 10 AU move, well over 3% of the ~60 AU distance to Sgr A* (~1.8 AU). + const movedBeyondThreshold: readonly [number, number, number] = [ + pinnedEye[0] + 10 * SCALE_UNITS.AU_TO_MPC, + pinnedEye[1], + pinnedEye[2], + ]; + renderFrame(makeInput(makeCtx(movedBeyondThreshold), state)); + + expect(skyCubemapFaceContextMock).toHaveBeenCalledTimes(6); + for (const call of skyCubemapFaceContextMock.mock.calls) { + expect(call[0]).toMatchObject({ eyeMpc: movedBeyondThreshold }); + } + expect(state.cameraRuntime.skyCubemapCapture.pinnedEyeMpc).toEqual(movedBeyondThreshold); + }); }); diff --git a/tests/services/engine/frame/renderFrame.test.ts b/tests/services/engine/frame/renderFrame.test.ts index e7984670aa..fcb1e6d219 100644 --- a/tests/services/engine/frame/renderFrame.test.ts +++ b/tests/services/engine/frame/renderFrame.test.ts @@ -580,7 +580,7 @@ function makeInput( lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }, } as never, diff --git a/tests/services/engine/frame/renderFrame.timing.test.ts b/tests/services/engine/frame/renderFrame.timing.test.ts index c565dc54b9..c524f56254 100644 --- a/tests/services/engine/frame/renderFrame.timing.test.ts +++ b/tests/services/engine/frame/renderFrame.timing.test.ts @@ -379,7 +379,7 @@ function makeMinimalInputWithTiming(timingService: GpuTimingService): { lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }, } as never, diff --git a/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts b/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts index 90cd95c352..d756e3dad1 100644 --- a/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts +++ b/tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts @@ -13,14 +13,13 @@ import type { CubeFace } from '../../../../src/@types/rendering/CubeFace'; const ALL_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; describe('skyCubemapCaptureSchedule', () => { - it('full 6-face capture on band entry', () => { + it('full 6-face capture when fullSweepTriggered (band entry or pinned-eye movement — the caller folds both reasons into this one flag)', () => { for (let frameIndex = 0; frameIndex < 12; frameIndex++) { const { facesToCapture } = skyCubemapCaptureSchedule({ - bandJustEngaged: true, + fullSweepTriggered: true, frameIndex, lastCapturedAtMs: new Map(), nowMs: 1000, - cameraMovedBeyondThreshold: false, }); expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); } @@ -30,11 +29,10 @@ describe('skyCubemapCaptureSchedule', () => { const seen: CubeFace[] = []; for (let frameIndex = 0; frameIndex < 6; frameIndex++) { const { facesToCapture } = skyCubemapCaptureSchedule({ - bandJustEngaged: false, + fullSweepTriggered: false, frameIndex, lastCapturedAtMs: new Map(ALL_FACES.map((f) => [f, 1000])), nowMs: 1000, - cameraMovedBeyondThreshold: false, }); expect(facesToCapture).toHaveLength(1); seen.push(facesToCapture[0]!); @@ -56,35 +54,21 @@ describe('skyCubemapCaptureSchedule', () => { [5, 100_000], ]); const { facesToCapture } = skyCubemapCaptureSchedule({ - bandJustEngaged: false, + fullSweepTriggered: false, frameIndex: 0, lastCapturedAtMs, nowMs: 100_000, - cameraMovedBeyondThreshold: false, }); expect(facesToCapture).toContain(0); // this frame's round-robin face expect(facesToCapture).toContain(2); // the stale escape-valve face }); - it('escape valve re-captures every face out of turn when the camera moved', () => { - const lastCapturedAtMs = new Map(ALL_FACES.map((f) => [f, 100_000])); - const { facesToCapture } = skyCubemapCaptureSchedule({ - bandJustEngaged: false, - frameIndex: 0, - lastCapturedAtMs, - nowMs: 100_000, - cameraMovedBeyondThreshold: true, - }); - expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); - }); - it('a face missing from lastCapturedAtMs (never captured) is always stale', () => { const { facesToCapture } = skyCubemapCaptureSchedule({ - bandJustEngaged: false, + fullSweepTriggered: false, frameIndex: 3, // round-robin would pick face 3 alone lastCapturedAtMs: new Map(), // every face uncaptured nowMs: 0, - cameraMovedBeyondThreshold: false, }); expect([...facesToCapture].sort()).toEqual([...ALL_FACES]); }); diff --git a/tests/visual/renderFrameSplitBaseline.test.ts b/tests/visual/renderFrameSplitBaseline.test.ts index d7f36ba501..436d51c20f 100644 --- a/tests/visual/renderFrameSplitBaseline.test.ts +++ b/tests/visual/renderFrameSplitBaseline.test.ts @@ -507,7 +507,7 @@ describe('renderFrame visual baseline', () => { lastCapturedAtMs: new Map(), frameIndex: 0, wasBandActive: false, - lastSweepCamPosMpc: null, + pinnedEyeMpc: null, }, }, } as never, From ebbf79e87fbca4d6be673d214134237707f908ee Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 17:50:29 +0200 Subject: [PATCH 36/60] fix(black-hole): a sky-cubemap capture step always clears its face MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit executeFrame's first-touch `touched` set tracks by TARGET, but a capture step's target ('sky-cubemap') has six LAYERS, one per face. On a frame capturing more than one face (escape valve, full sweep, band entry), only the first face's pass cleared; every later face's pass saw the target already touched and LOADED — against its own stale prior content, not the first face's — so stars drew additively over stale data and the cubemap flickered bright/dim depending on which face happened to render first that frame. A capture step now always clears (`step.face !== undefined` forces `alreadyTouched: false`) rather than extending `touched` to (target, layer) granularity generally — a capture step redraws its whole face every time, so there is never stale content worth loading. Depth is unaffected (sky-cubemap is depthless). Co-Authored-By: Claude Fable 5 --- src/services/engine/frame/executeFrame.ts | 16 ++++++++++++- .../engine/frame/executeFrame.test.ts | 23 +++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 1e3317e96b..e335a69b26 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -48,6 +48,14 @@ * filtered to enabled layers — a non-empty group always has a first layer to * carry the clear. * + * A capture render step (`step.face !== undefined`) is the one exception: its + * target ('sky-cubemap') has six LAYERS, one per face, but `touched` tracks by + * target string alone — so it can't distinguish "this face's first pass this + * frame" from "a DIFFERENT face already rendered this frame". Rather than grow + * `touched` to (target, layer) granularity for this one target, a capture step + * always clears: it redraws its whole face every time, so there's nothing worth + * loading. + * * The same `touched` fact drives depth: a render step whose target row declares * `depth` (only `foreground:0` today) attaches a depth texture whose load-op is * `'clear'` (to this slab's far-plane depth via `depthClearValueFor` — `0.0` under @@ -292,7 +300,13 @@ export function executeFrame(args: ExecuteFrameArgs): void { group, view, groupKey, - alreadyTouched: touched.has(step.target), + // `touched` tracks by TARGET, but a capture step's target + // ('sky-cubemap') has six LAYERS — one per face — so `touched` + // cannot tell "this face's first pass this frame" from "some + // OTHER face already rendered this frame". A capture step always + // clears instead: it redraws its whole face every time, so + // there's never content worth loading. See the module header. + alreadyTouched: step.face === undefined && touched.has(step.target), depthLoadOp: depthLoadOpFor(step.depthLoad, touched.has(step.target)), }); touched.add(step.target); diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index 9586697527..132ad227fa 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -872,6 +872,29 @@ describe('executeFrame', () => { expect(new Set(viewsPerFace).size).toBe(6); }); + it('two capture steps for different faces in ONE frame BOTH clear — a capture step never loads', () => { + // Pins the real bug: `touched` tracks by TARGET ('sky-cubemap'), not by + // LAYER (face). Before the fix, face 0's pass cleared and marked + // 'sky-cubemap' touched; face 1's pass then LOADED — against its own + // stale prior-frame content, not face 0's — and stars drew additively + // over it, flickering the cubemap bright/dim by capture order. + const layer = makeLayer({ name: 'probe', target: 'hdr', slab: NEAR0, skyCapture: true }); + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }, + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 1 }, + ]; + const faceCtx = makeCtx(); + const skyCubemapFaceContexts = new Map([ + [0, faceCtx], + [1, faceCtx], + ]); + const { args, env } = makeArgs({ program, layers: [layer], skyCubemapFaceContexts }); + executeFrame(args); + + expect(attachmentOfDraw(env, layer, 0).loadOp).toBe('clear'); + expect(attachmentOfDraw(env, layer, 1).loadOp).toBe('clear'); + }); + it('never selects a capture step group by target alone — a layer targeting sky-cubemap without the flag is skipped', () => { const layer = makeLayer({ name: 'unflagged', target: 'sky-cubemap', slab: NEAR0 }); const program: FrameStep[] = [ From f8701bf0a80d22d626829a4ec96590a0b1407346 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 18:18:29 +0200 Subject: [PATCH 37/60] feat(black-hole): Sgr A* lens debug-panel tuning knobs (Task 15, temp) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a temporary DebugPanel section (SgrAStarLensingTuningSection + container, mounted in DebugPanel.tsx) for live-tuning the Sgr A* lens pass during Task 17's visual gate, following the ZoneOfAvoidanceTuning precedent — a settings cluster read at pack time. Tier 1 (innerRs/outerRs/inclinationRad/positionAngleRad/flickerAmp/ flickerTimescaleS) overrides BLACK_HOLES at pack time. Tier 2 (diskScaleHeightRs/edgeFadeStartFraction/dopplerStrength) grows SgrAStarLensingUniforms 144->160 bytes to carry former fragment.wesl shader constants; the WESL-parity test is updated in lockstep. Also wires SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION through the same settings seam, and (per addendum) bumps the sky-cubemap render-target default from 256 to 512 and adds a live 256/512/1024 resolution knob — RenderTargetSpec.fixedSizePx.size can now be a function of state, mirroring mw-aggregate's state-driven scale, so reconcile() rebuilds the row (and its cube/layer views) on change with no reload needed. Glint tint/intensity (bodyGlintsLayer.ts) are left as module constants — wiring them would mean threading state into a pure, gate-and-emit- shared helper and expanding several hand-built EngineState test fixtures, beyond this task's surgical/reversible bound. Everything here is marked TEMPORARY and is deleted at Task 15's removal step once Task 17 converges on final values. Co-Authored-By: Claude Fable 5 --- .../SgrAStarLensingSliderField.d.ts | 8 ++ .../SgrAStarLensingSliderKey.d.ts | 10 ++ src/@types/engine/frame/RenderTargetSpec.d.ts | 10 +- src/@types/settings/EngineSettingsState.d.ts | 8 ++ .../settings/SgrAStarLensingTuning.d.ts | 57 +++++++++ src/components/DebugPanel/DebugPanel.tsx | 8 +- .../SgrAStarLensingTuningSection.tsx | 58 +++++++++ .../SgrAStarLensingTuningSectionContainer.tsx | 30 +++++ src/data/defaults.ts | 44 +++++++ .../sgrAStarLensingSliderFields.ts | 118 ++++++++++++++++++ .../frame/passes/sgrAStarLensingLayer.ts | 39 +++--- .../frame/passes/starAggregatesLayer.ts | 7 +- src/services/engine/frame/renderFrame.ts | 33 ++--- src/services/gpu/renderTargets.ts | 24 +++- .../bodies/sgrAStarLensingRenderer.ts | 6 +- .../bodies/sgrAStarLensing/fragment.wesl | 14 ++- .../gpu/shaders/lib/sgrAStarLensing.wesl | 18 ++- src/state/settings/initialState.ts | 12 ++ src/state/settings/selectors.ts | 7 ++ src/state/settings/settingsSlice.ts | 9 ++ src/utils/gpu/packSgrAStarLensingUniforms.ts | 28 +++-- .../renderFrame.skyCubemapHandOff.test.ts | 11 ++ tests/services/gpu/renderTargets.test.ts | 63 +++++++++- tests/state/settings/makeSettingsFixture.ts | 7 ++ .../gpu/packSgrAStarLensingUniforms.test.ts | 25 +++- ...rAStarLensingUniformsLayout.parity.test.ts | 16 ++- 26 files changed, 607 insertions(+), 63 deletions(-) create mode 100644 src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts create mode 100644 src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts create mode 100644 src/@types/settings/SgrAStarLensingTuning.d.ts create mode 100644 src/components/DebugPanel/SgrAStarLensingTuningSection.tsx create mode 100644 src/components/containers/SgrAStarLensingTuningSectionContainer.tsx create mode 100644 src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts diff --git a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts new file mode 100644 index 0000000000..1f5c6a908e --- /dev/null +++ b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts @@ -0,0 +1,8 @@ +import type { SliderField } from '../SliderField'; +import type { SgrAStarLensingSliderKey } from './SgrAStarLensingSliderKey'; + +/** + * TEMPORARY (Task 15). UI metadata for one Sgr A* lens tuning slider, + * iterated by the DebugPanel section. + */ +export type SgrAStarLensingSliderField = SliderField; diff --git a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts new file mode 100644 index 0000000000..de32f06887 --- /dev/null +++ b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts @@ -0,0 +1,10 @@ +import type { SgrAStarLensingTuning } from '../../settings/SgrAStarLensingTuning'; + +/** + * TEMPORARY (Task 15). Keys of `SgrAStarLensingTuning` that surface as + * numeric DebugPanel sliders. `cubemapResolutionPx` is excluded: it only + * takes three meaningful values (256/512/1024), so the section gives it a + * `` + * (three meaningful values) instead of riding the generic slider board — the + * same "bespoke control after the rows" shape ZoA's colour pickers use. + */ + +import type { ReactElement } from 'react'; +import type { SgrAStarLensingTuning } from '../../@types/settings/SgrAStarLensingTuning'; +import { + SGR_A_STAR_LENSING_SLIDER_FIELDS, + sgrAStarLensingSliderPatch, +} from '../../data/sgrAStarLensing/sgrAStarLensingSliderFields'; +import DebugTuningSection from './DebugTuningSection'; +import sliderStyles from './DebugSlider.module.css'; + +export type SgrAStarLensingTuningSectionProps = { + tuning: SgrAStarLensingTuning; + onChange: (patch: Partial) => void; +}; + +const CUBEMAP_RESOLUTIONS = [256, 512, 1024] as const; + +export function SgrAStarLensingTuningSection({ + tuning, + onChange, +}: SgrAStarLensingTuningSectionProps): ReactElement { + return ( + onChange(sgrAStarLensingSliderPatch(k, v))} + > +
+ cubemapResolutionPx + {tuning.cubemapResolutionPx} + +
+ + ); +} diff --git a/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx b/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx new file mode 100644 index 0000000000..826befb24c --- /dev/null +++ b/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx @@ -0,0 +1,30 @@ +// src/components/containers/SgrAStarLensingTuningSectionContainer.tsx +/** + * TEMPORARY (Task 15) — store boundary for the DebugPanel's Sgr A* lens + * tuning knobs, deleted at the removal step. Mirrors + * `ZoneOfAvoidanceTuningSectionContainer`: `selectSgrAStarLensingTuning` + * returns the whole cluster (the slider board reads every knob), so this + * subtree re-renders on any write to it — the right granularity for a small + * slider board that is closed most of the time. + */ + +import { memo, useCallback } from 'react'; +import { SgrAStarLensingTuningSection } from '../DebugPanel/SgrAStarLensingTuningSection'; +import { useAppDispatch, useAppSelector } from '../../store/hooks'; +import { selectSgrAStarLensingTuning } from '../../state/settings/selectors'; +import { setSgrAStarLensingTuning } from '../../state/settings/settingsSlice'; +import type { SgrAStarLensingTuning } from '../../@types/settings/SgrAStarLensingTuning'; + +function SgrAStarLensingTuningSectionContainer(): React.ReactElement { + const dispatch = useAppDispatch(); + const tuning = useAppSelector(selectSgrAStarLensingTuning); + + const onChange = useCallback( + (patch: Partial) => dispatch(setSgrAStarLensingTuning(patch)), + [dispatch], + ); + + return ; +} + +export default memo(SgrAStarLensingTuningSectionContainer); diff --git a/src/data/defaults.ts b/src/data/defaults.ts index 4b4e43a884..9088b95b05 100644 --- a/src/data/defaults.ts +++ b/src/data/defaults.ts @@ -17,6 +17,9 @@ import { ToneMapCurve, toneMapCurveSaturation } from './toneMapCurve'; import type { ToneMapCurve as ToneMapCurveT } from '../@types/data/ToneMapCurve'; import type { FlowSettings } from '../@types/settings/FlowSettings'; import type { ZoneOfAvoidanceTuning } from '../@types/settings/ZoneOfAvoidanceTuning'; +import type { SgrAStarLensingTuning } from '../@types/settings/SgrAStarLensingTuning'; +import { BLACK_HOLES } from './blackHoles'; +import { SGR_A_STAR } from './bodies/sceneSgrAStar'; import type { OrientationFrameId } from '../@types/camera/OrientationFrameId'; import type { GalaxyProvenanceSettings } from '../@types/settings/GalaxyProvenanceSettings'; import { SOURCE_REGISTRY, Source } from './sources'; @@ -263,6 +266,47 @@ export const DEFAULT_ZONE_OF_AVOIDANCE_TUNING: ZoneOfAvoidanceTuning = { labelColor: [0.2307, 0.2502, 0.6795], }; +/** + * TEMPORARY (Task 15, deleted at its removal step) — the Sgr A* lens pass's + * DebugPanel tuning starting values. + * + * Tier 1 (`innerRs`..`flickerTimescaleS`) seeds from `BLACK_HOLES`'s Sgr A* + * row — that registry stays the single source of truth for these until the + * removal step bakes the tuned values back into it. + * + * Tier 2 (`diskScaleHeightRs` / `edgeFadeStartFraction` / `dopplerStrength`) + * mirrors `fragment.wesl`'s former `DISK_SCALE_HEIGHT_RS` / the escape + * branch's `* 0.7` edge-fade factor / `DOPPLER_STRENGTH` — this literal is + * their new single source of truth until the removal step bakes the tuned + * values back into the shader as consts. + * + * `cubemapResolutionPx` seeds the `sky-cubemap` render-target row's declared + * size (`renderTargets.ts`) — 512, the user's visual-tuning call bumping it + * off the original 256 (T15 addendum). + * + * NOT here: `skyCubemapRecaptureCameraMoveFraction`. Its owner is + * `skyCubemapCaptureSchedule.ts` (a `services/` module `data/` doesn't + * import from), so `initialState.ts` seeds it straight from there and spreads + * it in alongside this object — the same "owned by the module it feeds" + * relationship `DEFAULT_REFINE_THRESHOLD` has to `walkStarOctreeCut`. + */ +const SGR_A_STAR_BLACK_HOLE_ROW = BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id)!; +export const DEFAULT_SGR_A_STAR_LENSING_TUNING: Omit< + SgrAStarLensingTuning, + 'skyCubemapRecaptureCameraMoveFraction' +> = { + innerRs: SGR_A_STAR_BLACK_HOLE_ROW.emission.innerRs, + outerRs: SGR_A_STAR_BLACK_HOLE_ROW.emission.outerRs, + inclinationRad: SGR_A_STAR_BLACK_HOLE_ROW.emission.inclinationRad, + positionAngleRad: SGR_A_STAR_BLACK_HOLE_ROW.emission.positionAngleRad, + flickerAmp: SGR_A_STAR_BLACK_HOLE_ROW.emission.flickerAmp, + flickerTimescaleS: SGR_A_STAR_BLACK_HOLE_ROW.emission.flickerTimescaleS, + diskScaleHeightRs: 0.4, + edgeFadeStartFraction: 0.7, + dopplerStrength: 0.6, + cubemapResolutionPx: 512, +}; + // ── HDR tone-mapping ──────────────────────────────────────────────────────── /** diff --git a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts new file mode 100644 index 0000000000..7208113b77 --- /dev/null +++ b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts @@ -0,0 +1,118 @@ +/** + * SGR_A_STAR_LENSING_SLIDER_FIELDS — TEMPORARY (Task 15), deleted at the + * removal step. UI metadata for the Sgr A* lens pass's DebugPanel sliders — + * same shape as `data/zoneOfAvoidance/zoneOfAvoidanceSliderFields.ts`: label, + * range, granularity and formatting live in ONE row per knob. + * `cubemapResolutionPx` isn't here — see `SgrAStarLensingSliderKey`. + */ +import type { SgrAStarLensingTuning } from '../../@types/settings/SgrAStarLensingTuning'; +import type { SgrAStarLensingSliderKey } from '../../@types/data/sgrAStarLensing/SgrAStarLensingSliderKey'; +import type { SgrAStarLensingSliderField } from '../../@types/data/sgrAStarLensing/SgrAStarLensingSliderField'; + +export const SGR_A_STAR_LENSING_SLIDER_FIELDS: readonly SgrAStarLensingSliderField[] = [ + { + key: 'innerRs', + label: 'innerRs', + min: 1, + max: 10, + step: 0.1, + format: (v) => v.toFixed(1), + title: 'Emission annulus inner edge, Schwarzschild-radius units.', + }, + { + key: 'outerRs', + label: 'outerRs', + min: 1, + max: 20, + step: 0.1, + format: (v) => v.toFixed(1), + title: 'Emission annulus outer edge, Schwarzschild-radius units.', + }, + { + key: 'inclinationRad', + label: 'inclinationRad', + min: 0, + max: Math.PI / 2, + step: 0.01, + format: (v) => v.toFixed(2), + title: 'Disk inclination, radians (0 = face-on).', + }, + { + key: 'positionAngleRad', + label: 'positionAngleRad', + min: 0, + max: 2 * Math.PI, + step: 0.01, + format: (v) => v.toFixed(2), + title: 'Disk major-axis position angle, radians.', + }, + { + key: 'flickerAmp', + label: 'flickerAmp', + min: 0, + max: 1, + step: 0.01, + format: (v) => v.toFixed(2), + title: 'Fractional brightness modulation amplitude.', + }, + { + key: 'flickerTimescaleS', + label: 'flickerTimescaleS', + min: 10, + max: 600, + step: 1, + format: (v) => v.toFixed(0), + title: 'Flicker period, seconds.', + }, + { + key: 'diskScaleHeightRs', + label: 'diskScaleHeightRs', + min: 0.05, + max: 2, + step: 0.01, + format: (v) => v.toFixed(2), + title: 'Vertical falloff scale height, Schwarzschild-radius units.', + }, + { + key: 'edgeFadeStartFraction', + label: 'edgeFadeStartFraction', + min: 0, + max: 1, + step: 0.01, + format: (v) => v.toFixed(2), + title: "Escape branch's edge-fade start, as a fraction of the LUT's max impact parameter.", + }, + { + key: 'dopplerStrength', + label: 'dopplerStrength', + min: 0, + max: 2, + step: 0.01, + format: (v) => v.toFixed(2), + title: 'Doppler-beaming strength factor.', + }, + { + key: 'skyCubemapRecaptureCameraMoveFraction', + label: 'recaptureMoveFraction', + min: 0.005, + max: 0.2, + step: 0.005, + format: (v) => v.toFixed(3), + title: + 'Escape-valve movement threshold, as a fraction of the camera-to-Sgr-A* distance, that forces a full 6-face sky-cubemap resweep.', + }, +]; + +/** + * Build a `SgrAStarLensingTuning` patch for one slider field. The cast is + * sound: every `SgrAStarLensingSliderKey` addresses a number-valued leaf, but + * a computed-key object literal widens to `{ [k: string]: number }`, which + * the compiler won't narrow on its own — the same trick `zoneOfAvoidanceSliderPatch` + * uses. + */ +export function sgrAStarLensingSliderPatch( + key: SgrAStarLensingSliderKey, + value: number, +): Partial { + return { [key]: value } as Partial; +} diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 7c0a8db58c..6a8efcedb9 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -33,13 +33,15 @@ import { SCALE_FADE_BANDS } from '../../presentation/scaleFadeBands'; const GALACTIC_CENTRE_REGION = regionById('galactic-centre'); -// One row today (Sgr A* only) — found once at module scope rather than -// re-scanned every frame, the same "hoist the constant lookup" convention -// `starPointsLayer`'s module-scope regions follow. `BLACK_HOLES` is authored -// data guaranteed to carry this row; a missing row is a wiring bug worth -// failing loudly on, not a silent no-op layer. -const BLACK_HOLE = BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id); -if (BLACK_HOLE === undefined) { +// `BLACK_HOLES` is authored data guaranteed to carry a Sgr A* row; a missing +// row is a wiring bug worth failing loudly on, not a silent no-op layer. +// Checked once at module scope rather than every frame, the same "hoist the +// constant lookup" convention `starPointsLayer`'s module-scope regions +// follow. The row's VALUES are no longer read here — TEMPORARILY (Task 15), +// `state.settings.sgrAStarLensingTuning` overrides them at pack time (seeded +// from this same row — see `DEFAULT_SGR_A_STAR_LENSING_TUNING`); the removal +// step reverts to reading `BLACK_HOLE.emission.*` directly. +if (BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id) === undefined) { throw new Error(`sgrAStarLensingLayer: BLACK_HOLES carries no row for '${SGR_A_STAR.id}'`); } @@ -93,24 +95,33 @@ export const sgrAStarLensingLayer: ContentLayer = { -pose.eyeRelBodyM[2], ]; - const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / BLACK_HOLE.emission.flickerTimescaleS; + // TEMPORARY (Task 15): every emission field below reads the DebugPanel + // tuning cluster, not `BLACK_HOLE.emission` — see the module-scope guard's + // comment. `flickerPhase` must divide by the SAME `flickerTimescaleS` the + // packed uniform carries, or a live slider drag would desync the phase + // from the period it packs. + const tuning = state.settings.sgrAStarLensingTuning; + const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / tuning.flickerTimescaleS; const uniforms = packSgrAStarLensingUniforms( view.vp, view.viewportPx, SCHWARZSCHILD_RADIUS_M, - BLACK_HOLE.emission.innerRs, - BLACK_HOLE.emission.outerRs, - BLACK_HOLE.emission.inclinationRad, - BLACK_HOLE.emission.positionAngleRad, - BLACK_HOLE.emission.flickerAmp, - BLACK_HOLE.emission.flickerTimescaleS, + tuning.innerRs, + tuning.outerRs, + tuning.inclinationRad, + tuning.positionAngleRad, + tuning.flickerAmp, + tuning.flickerTimescaleS, flickerPhase, renderer.lut.minImpactParamRs, renderer.lut.maxImpactParamRs, renderer.lut.samples.length, bandAlpha, anchorPosRelCamM, + tuning.diskScaleHeightRs, + tuning.edgeFadeStartFraction, + tuning.dopplerStrength, ); const skyCubemapView = ctx.renderTargets.cubeViewOf('sky-cubemap'); diff --git a/src/services/engine/frame/passes/starAggregatesLayer.ts b/src/services/engine/frame/passes/starAggregatesLayer.ts index fd1232b166..7e034b7385 100644 --- a/src/services/engine/frame/passes/starAggregatesLayer.ts +++ b/src/services/engine/frame/passes/starAggregatesLayer.ts @@ -60,9 +60,10 @@ export const starAggregatesLayer: ContentLayer = { // flicker, not wrong brightness — `toRefPx` keeps the photometry // viewport-independent). `viewSlot !== 0` marks a sky-cubemap capture draw // (this layer's `skyCapture` flag, see `ReadyFrameContext.viewSlot`'s - // doc), which targets the 256px `sky-cubemap` face, not this row. The view - // is COPIED rather than mutated: one `SlabView` is shared by every layer - // in the render step. + // doc), which targets the `sky-cubemap` face — its own declared size (a + // live setting as of Task 15), not this row's. The view is COPIED rather + // than mutated: one `SlabView` is shared by every layer in the render + // step. const destTarget = ctx.viewSlot !== 0 ? 'sky-cubemap' : 'star-aggregates'; const { width: vw, height: vh } = ctx.renderTargets.sizeOf(destTarget); diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 25b1b0c707..43522db1c2 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -60,10 +60,7 @@ import { resolveStrategy } from './resolveStrategy'; import { foregroundChainOrder } from './slabs'; import { CONTENT_LAYERS } from './passes'; import { hdrActiveOf } from '../../../utils/gpu/hdrActiveOf'; -import { - skyCubemapCaptureSchedule, - SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, -} from './skyCubemapCaptureSchedule'; +import { skyCubemapCaptureSchedule } from './skyCubemapCaptureSchedule'; import { skyCubemapFaceContext } from './skyCubemapFaceContext'; import { sceneBodyStates } from './sceneBodyStates'; import { regionById } from '../../../utils/scene/regionById'; @@ -136,20 +133,22 @@ export function renderFrame(input: RenderFrameInput): void { // `null` outside the band, or when the row isn't in `ctx.slabs` this frame // (e.g. frustum-culled despite the distance band). const sgrAStarBodySlab = bandActive - ? (ctx.slabs.find( - (slab) => slab.frame.kind === 'body-m' && slab.frame.bodyId === SGR_A_STAR.id, - )?.index ?? null) + ? (ctx.slabs.find((slab) => slab.frame.kind === 'body-m' && slab.frame.bodyId === SGR_A_STAR.id) + ?.index ?? null) : null; const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; // Measured against the PINNED eye, not the live camera each frame: a // fresh live eye per round-robin face made adjacent faces disagree at // their shared border and the whole cubemap flicker as the camera moved - // (fix round 3). Threshold is a FRACTION of `gcDistanceMpc` — see the - // constant's own docblock for why a fixed AU distance is wrong here. + // (fix round 3). Threshold is a FRACTION of `gcDistanceMpc` — see + // `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s own docblock for why a + // fixed AU distance is wrong here. Read off settings, not the module + // constant, TEMPORARILY (Task 15's DebugPanel knob) — the constant stays + // this value's real owner (`initialState.ts` seeds from it). const cameraMovedBeyondThreshold = captureRuntime.pinnedEyeMpc !== null && distanceMpc(ctx.drawCamPos, captureRuntime.pinnedEyeMpc) > - SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION * gcDistanceMpc; + state.settings.sgrAStarLensingTuning.skyCubemapRecaptureCameraMoveFraction * gcDistanceMpc; const fullSweepTriggered = bandJustEngaged || cameraMovedBeyondThreshold; // Re-pin BEFORE scheduling so a triggered full sweep — including this // frame's own faces — samples the eye it was triggered by, not the eye it @@ -175,14 +174,18 @@ export function renderFrame(input: RenderFrameInput): void { // `frameProgram` only knows WHICH faces to capture (static data); resolving // each face's own synthetic camera is `renderFrame`'s job, done fresh every // frame since the schedule's face LIST can change frame to frame. - // `faceSizePx` reads the sky-cubemap row's own declared size rather than a - // hard-coded constant, so the two can never drift. A face whose context - // comes back null (pre-bootstrap) is simply omitted — `executeFrame` treats - // a missing map entry as "skip this step cleanly" (see its module header). + // `faceSizePx` reads the sky-cubemap row's own ALLOCATED size (`sizeOf`, + // this frame's already-reconciled pixels — see `RenderTargets.sizeOf`'s + // doc), not `specOf().fixedSizePx.size` directly: that field is a live + // setting as of Task 15 (a function of state, not a plain number), so + // reading the resolved allocation is both simpler and the authoritative + // answer. A face whose context comes back null (pre-bootstrap) is simply + // omitted — `executeFrame` treats a missing map entry as "skip this step + // cleanly" (see its module header). const skyCubemapFaceContexts = new Map(); const pinnedEyeMpc = captureRuntime.pinnedEyeMpc; if (skyCubemapFacesToCapture.length > 0 && pinnedEyeMpc !== null) { - const faceSizePx = ctx.renderTargets.specOf('sky-cubemap').fixedSizePx!.size; + const faceSizePx = ctx.renderTargets.sizeOf('sky-cubemap').width; for (const face of skyCubemapFacesToCapture) { const faceCtx = skyCubemapFaceContext({ state, diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index b62cbd8bbf..ac7d0235b5 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -167,6 +167,19 @@ function resolveScale(spec: RenderTargetSpec, state: EngineState): number { return typeof spec.scale === 'function' ? spec.scale(state) : spec.scale; } +/** + * A `fixedSizePx` row's declared per-axis size for this state — mirrors + * `resolveScale`. TEMPORARY (Task 15): today only `sky-cubemap`'s size is a + * function; every other `fixedSizePx` row (incl. `renderTargets.test.ts`'s + * synthetic `test:cubemap`) still hands a plain number. + */ +function resolveFixedSize( + fixedSizePx: { size: number | ((state: EngineState) => number) }, + state: EngineState, +): number { + return typeof fixedSizePx.size === 'function' ? fixedSizePx.size(state) : fixedSizePx.size; +} + /** * The declared render-target table for this frame configuration. A function * (not a module constant) because the swap row's format is runtime-decided — @@ -262,7 +275,14 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT depth: null, scale: 1, // unused: fixedSizePx below overrides it (required by the type). clearValue: { r: 0, g: 0, b: 0, a: 0 }, - fixedSizePx: { size: 256, layers: 6 }, + // `size` is a live setting, TEMPORARILY (Task 15's DebugPanel resolution + // knob, 256/512/1024) — `reconcile` resolves it every frame exactly like + // `mw-aggregate`'s divisor, so dragging the knob reallocates this row + // (and its cube/layer views) without a rebuild path of its own. + fixedSizePx: { + size: (state) => state.settings.sgrAStarLensingTuning.cubemapResolutionPx, + layers: 6, + }, }, { id: 'swap', @@ -401,7 +421,7 @@ export function createRenderTargets( // separate code path past this one branch: the held-size comparison // and `allocate` call below stay shared with every other row. const [width, height] = spec.fixedSizePx - ? [spec.fixedSizePx.size, spec.fixedSizePx.size] + ? [resolveFixedSize(spec.fixedSizePx, s), resolveFixedSize(spec.fixedSizePx, s)] : reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s)); const held = sizes.get(spec.id); if (held !== undefined && held.width === width && held.height === height) continue; diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts index 773504cdea..f5841d7ef6 100644 --- a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -90,10 +90,12 @@ export function createSgrAStarLensingRenderer( const lutTexture = createLutTexture(device, lut); const lutView = lutTexture.createView({ label: 'sgr-a-star-lensing-lut-view' }); - // ── Uniform buffer (144 bytes, byte-exact with SgrAStarLensingUniforms) ── + // ── Uniform buffer (160 bytes, byte-exact with SgrAStarLensingUniforms — + // TEMPORARILY grown from 144 for Task 15's Tier-2 DebugPanel knobs; shrinks + // back at the removal step once Task 17 converges) ── const uniformBuffer = device.createBuffer({ label: 'sgr-a-star-lensing-uniform-buffer', - size: 144, + size: 160, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, }); diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index e3148b5702..499459b5ae 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -30,9 +30,11 @@ const CAPTURE_THRESHOLD_RAD: f32 = 500.0; const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound // Split across the bent-ray march's two segments (Task 13c finding 3). const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; -const DISK_SCALE_HEIGHT_RS: f32 = 0.4; // vertical falloff scale height, thin-disk taste (T15 tuning knob) const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // inner/outer annulus edge softening width -const DOPPLER_STRENGTH: f32 = 0.6; // tuned for looks — see BLACK_HOLES's own "visual taste" note +// DISK_SCALE_HEIGHT_RS / DOPPLER_STRENGTH used to live here as consts — +// TEMPORARILY (Task 15) they ride 'u.diskScaleHeightRs' / 'u.dopplerStrength' +// instead (DebugPanel tuning knobs), baked back into consts at the removal +// step once Task 17 converges. // Two-tap manual lerp (r32float isn't sampler-filterable without the // optional feature, hence textureLoad + a texture_2d, not texture_1d — @@ -69,7 +71,7 @@ fn diskNormal() -> vec3 { // whichever way the photon is actually travelling there. fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3, stepLenM: f32) -> vec4 { let distToPlaneRs = dot(p, normal) / u.schwarzschildRadiusM; - let verticalWeight = exp(-(distToPlaneRs * distToPlaneRs) / (DISK_SCALE_HEIGHT_RS * DISK_SCALE_HEIGHT_RS)); + let verticalWeight = exp(-(distToPlaneRs * distToPlaneRs) / (u.diskScaleHeightRs * u.diskScaleHeightRs)); if (verticalWeight < 1e-3) { return vec4(0.0); } @@ -85,7 +87,7 @@ fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3 let radialDir = inPlane / max(radialM, 1e-6); let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point - let dopplerFactor = 1.0 + DOPPLER_STRENGTH * dot(orbitDir, -viewDir); + let dopplerFactor = 1.0 + u.dopplerStrength * dot(orbitDir, -viewDir); // Kepler period ~ r^1.5: a cheap per-radius phase offset (closer annuli // lead the outer ones), not a fitted light curve — visual taste, as above. let periodScale = pow(max(radialRs, 0.1), 1.5); @@ -187,7 +189,9 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4 — camera-relative anchor, metres (f64->f32 rebase seam) -// offset 140 : _pad2 f32 — rounds the struct to 144 / 16-byte -// total: 144 bytes. +// offset 140 : diskScaleHeightRs f32 — T15 TEMP tuning knob, was fragment.wesl's DISK_SCALE_HEIGHT_RS const +// offset 144 : edgeFadeStartFraction f32 — T15 TEMP tuning knob, was the escape branch's hardcoded '* 0.7' +// offset 148 : dopplerStrength f32 — T15 TEMP tuning knob, was fragment.wesl's DOPPLER_STRENGTH const +// offset 152 : _pad3 f32 — T15 TEMP, rounds the struct to 160 / 16-byte +// offset 156 : _pad4 f32 — T15 TEMP, rounds the struct to 160 / 16-byte +// total: 160 bytes. // // The 12 scalar fields (80..127, 48 bytes) exactly fill the run up to 128, // so 'anchorPosRelCamM' lands on a 16-byte boundary with no implicit padding @@ -38,6 +42,10 @@ // the single source of truth for that half of the contract) or the GPU // silently reads garbage — no compile error, no runtime error, just a wrong // (or on iOS, dropped) frame. +// +// TASK 15 TEMPORARY: the three fields after 'anchorPosRelCamM' are DebugPanel +// tuning knobs (Tier 2 of the task-15 brief), deleted — struct shrunk back to +// 144 bytes — at the removal step once Task 17 converges on final values. import package::lib::camera::CameraUniforms; @@ -56,5 +64,9 @@ struct SgrAStarLensingUniforms { lutSampleCount: f32, bandAlpha: f32, anchorPosRelCamM: vec3, - _pad2: f32, + diskScaleHeightRs: f32, + edgeFadeStartFraction: f32, + dopplerStrength: f32, + _pad3: f32, + _pad4: f32, }; diff --git a/src/state/settings/initialState.ts b/src/state/settings/initialState.ts index 6bd928a8fb..bd219cea2d 100644 --- a/src/state/settings/initialState.ts +++ b/src/state/settings/initialState.ts @@ -37,6 +37,7 @@ import { DEFAULT_ORBIT_TRAILS_ENABLED, DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, DEFAULT_ZONE_OF_AVOIDANCE_TUNING, + DEFAULT_SGR_A_STAR_LENSING_TUNING, DEFAULT_POINT_SIZE_PX, DEFAULT_STAR_BRIGHTNESS, DEFAULT_STAR_GLOW_OVERLAP, @@ -57,6 +58,10 @@ import { DEFAULT_REFINE_THRESHOLD } from '../../services/gpu/renderers/starCatal // renderer's calibration module, so seed them from there rather than restating // six numbers here. import { MILKY_WAY_TUNING_DEFAULTS } from '../../services/engine/galaxyGenerator/v1/milkyWayCalibration'; +// TEMPORARY (Task 15, deleted at its removal step): same relationship — +// `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s single source of truth is +// the schedule module it feeds, not `data/defaults.ts`. +import { SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION } from '../../services/engine/frame/skyCubemapCaptureSchedule'; import { DEFAULT_ALIGN_SEC, DEFAULT_RAMP_SEC, @@ -169,6 +174,13 @@ export function buildInitialSettings(): EngineSettingsState { enabled: DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, ...DEFAULT_ZONE_OF_AVOIDANCE_TUNING, }, + // TEMPORARY (Task 15) — deleted, mount line and all, at the removal step + // once Task 17 converges on final values. See `SgrAStarLensingTuning`'s + // own docblock for the tier breakdown. + sgrAStarLensingTuning: { + ...DEFAULT_SGR_A_STAR_LENSING_TUNING, + skyCubemapRecaptureCameraMoveFraction: SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, + }, filaments: { enabled: SOURCE_REGISTRY[Source.Filaments].visible, intensity: SOURCE_REGISTRY[Source.Filaments].intensity, diff --git a/src/state/settings/selectors.ts b/src/state/settings/selectors.ts index 4560684b28..89c6768b16 100644 --- a/src/state/settings/selectors.ts +++ b/src/state/settings/selectors.ts @@ -50,6 +50,7 @@ import type { VolumeFieldSettings } from '../../@types/settings/VolumeFieldSetti import type { FlowSettings } from '../../@types/settings/FlowSettings'; import type { MilkyWaySettings } from '../../@types/settings/MilkyWaySettings'; import type { ZoneOfAvoidanceSettings } from '../../@types/settings/ZoneOfAvoidanceSettings'; +import type { SgrAStarLensingTuning } from '../../@types/settings/SgrAStarLensingTuning'; import type { ClipId } from '../../@types/animation/ClipId'; import type { SplineMode } from '../../@types/animation/SplineMode'; import type { PassByDir } from '../../@types/animation/PassByDir'; @@ -188,6 +189,12 @@ export const selectZoneOfAvoidanceEnabled = (state: RootState): boolean => export const selectZoneOfAvoidance = (state: RootState): ZoneOfAvoidanceSettings => selectSettings(state).zoneOfAvoidance; +// --- sgrAStarLensingTuning cluster — TEMPORARY (Task 15) ----------------------- + +/** The whole tuning cluster — mirrors `selectMilkyWay` / `selectZoneOfAvoidance`. */ +export const selectSgrAStarLensingTuning = (state: RootState): SgrAStarLensingTuning => + selectSettings(state).sgrAStarLensingTuning; + // --- filaments cluster -------------------------------------------------------- export const selectFilamentsEnabled = (state: RootState): boolean => diff --git a/src/state/settings/settingsSlice.ts b/src/state/settings/settingsSlice.ts index 59bbea4795..f5bdc4cc98 100644 --- a/src/state/settings/settingsSlice.ts +++ b/src/state/settings/settingsSlice.ts @@ -47,6 +47,7 @@ import type { VolumeFieldSettings } from '../../@types/settings/VolumeFieldSetti import type { FlowFieldDefaults } from '../../@types/data/flow/FlowFieldDefaults'; import type { MilkyWayTuning } from '../../@types/settings/MilkyWayTuning'; import type { ZoneOfAvoidanceTuning } from '../../@types/settings/ZoneOfAvoidanceTuning'; +import type { SgrAStarLensingTuning } from '../../@types/settings/SgrAStarLensingTuning'; import type { SettingsSnapshot } from '../../@types/engine/settings/SettingsSnapshot'; import type { RenderStrategy } from '../../@types/engine/frame/RenderStrategy'; import type { OrientationFrameId } from '../../@types/camera/OrientationFrameId'; @@ -197,6 +198,13 @@ const settingsSlice = createSlice({ Object.assign(settings.zoneOfAvoidance, action.payload); }, + // ── Sgr A* lens tuning — TEMPORARY (Task 15), deleted at the removal step + // ─ leaf-by-leaf patch, no visibility axis to protect (this cluster is + // pure knobs, not a singleton overlay). + setSgrAStarLensingTuning: (settings, action: PayloadAction>) => { + Object.assign(settings.sgrAStarLensingTuning, action.payload); + }, + // ── filaments ─────────────────────────────────────────────────────────── setFilamentsEnabled: (settings, action: PayloadAction) => { settings.filaments.enabled = action.payload; @@ -517,6 +525,7 @@ export const { setMilkyWayTuning, setZoneOfAvoidanceEnabled, setZoneOfAvoidanceTuning, + setSgrAStarLensingTuning, setFilamentsEnabled, setFilamentIntensity, setConstellationsEnabled, diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index b1fe903d9d..a24c28db3b 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -1,6 +1,8 @@ /** - * packSgrAStarLensingUniforms — pure packer for the 144-byte - * `SgrAStarLensingUniforms` struct (`shaders/lib/sgrAStarLensing.wesl`). + * packSgrAStarLensingUniforms — pure packer for the `SgrAStarLensingUniforms` + * struct (`shaders/lib/sgrAStarLensing.wesl`) — TEMPORARILY 160 bytes (Task + * 15's Tier-2 DebugPanel knobs; shrinks back to 144 at Task 15's removal + * step once Task 17 converges — see that .wesl file's own header). * * Task 10's half of the uniform contract between the Sgr A* lens pass * (Task 13, not yet written) and its WGSL. The struct is the shared @@ -29,9 +31,12 @@ * f32 30 (byte 120..123): lutSampleCount f32 * f32 31 (byte 124..127): bandAlpha f32 * f32 32..34 (byte 128..139): anchorPosRelCamM vec3 - * f32 35 (byte 140..143): _pad2 — untouched (zero) + * f32 35 (byte 140..143): diskScaleHeightRs — T15 TEMP tuning knob + * f32 36 (byte 144..147): edgeFadeStartFraction — T15 TEMP tuning knob + * f32 37 (byte 148..151): dopplerStrength — T15 TEMP tuning knob + * f32 38..39 (byte 152..159): untouched (zero) — struct's 16-byte round-up * - * Total: 144 bytes / 36 f32. The 12 scalars at f32 20..31 exactly fill the + * Total: 160 bytes / 40 f32. The 12 scalars at f32 20..31 exactly fill the * run up to f32 32, so `anchorPosRelCamM` lands on a 16-byte boundary with * no implicit padding — see the .wesl module header for the alignment * argument. @@ -56,6 +61,9 @@ * @param lutSampleCount The LUT texture's texel count. * @param bandAlpha This frame's fade-band alpha (gates emission/deflection strength in-shader). * @param anchorPosRelCamM Camera-relative anchor position, metres. + * @param diskScaleHeightRs T15 TEMP — vertical falloff scale height, r_s units. + * @param edgeFadeStartFraction T15 TEMP — escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. + * @param dopplerStrength T15 TEMP — Doppler-beaming strength factor. */ import type { Mat4 } from 'wgpu-matrix'; @@ -64,8 +72,8 @@ import type { Vec3 } from '../../@types/math/Vec3'; import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/cameraUniforms'; /** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 - * scalars + anchorPosRelCamM (3) + pad (1) = 36. */ -export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 16; + * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (3) + pad (2) = 40. */ +export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 20; export function packSgrAStarLensingUniforms( viewProj: Float32Array | Mat4, @@ -83,6 +91,9 @@ export function packSgrAStarLensingUniforms( lutSampleCount: number, bandAlpha: number, anchorPosRelCamM: Readonly, + diskScaleHeightRs: number, + edgeFadeStartFraction: number, + dopplerStrength: number, ): Float32Array { const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); writeCameraPrefix(out, viewProj, viewportPx); // f32 0..17; 18..19 stay zero @@ -101,6 +112,9 @@ export function packSgrAStarLensingUniforms( out[32] = anchorPosRelCamM[0]; // byte 128 — vec3, 16-byte aligned out[33] = anchorPosRelCamM[1]; // byte 132 out[34] = anchorPosRelCamM[2]; // byte 136 - // out[35] (byte 140) stays zero — _pad2, rounds the struct to 144. + out[35] = diskScaleHeightRs; // byte 140 — T15 TEMP + out[36] = edgeFadeStartFraction; // byte 144 — T15 TEMP + out[37] = dopplerStrength; // byte 148 — T15 TEMP + // out[38..39] (byte 152..159) stay zero — the struct's 16-byte round-up. return out; } diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index c47d219558..485494f192 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -56,6 +56,10 @@ function makeState(): EngineState { hdr: { enabled: false, knee: 0, headroom: 0 }, bloom: { enabled: false }, debug: { renderStrategy: 'auto' }, + // TEMPORARY (Task 15): renderFrame reads the recapture-move threshold + // off settings now — 0.03 matches SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, + // the value every threshold assertion below was written against. + sgrAStarLensingTuning: { skyCubemapRecaptureCameraMoveFraction: 0.03 }, }, cameraRuntime: { skyCubemapCapture: makeCaptureRuntime() }, } as unknown as EngineState; @@ -76,6 +80,13 @@ function makeCtx(drawCamPos: readonly [number, number, number]): ReadyFrameConte if (id === 'swap') return { format: 'bgra8unorm' }; throw new Error(`mock renderTargets: no spec row for '${id}'`); }, + // TEMPORARY (Task 15): renderFrame reads the ALLOCATED size, not the + // spec's `fixedSizePx.size` (a live setting now) — see renderFrame.ts's + // `faceSizePx` derivation. + sizeOf: (id: string) => { + if (id === 'sky-cubemap') return { width: 256, height: 256 }; + throw new Error(`mock renderTargets: no allocated size for '${id}'`); + }, }, } as unknown as ReadyFrameContext; } diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index 68a6fc71d8..6f83191a98 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -29,8 +29,23 @@ const SWAP_FORMAT: GPUTextureFormat = 'bgra8unorm'; // and the row behaves like any other fixed-scale row. const MW_DIVISOR = 2; -function stateWithDivisor(aggregateDivisor: number): EngineState { - return { settings: { milkyWay: { aggregateDivisor } } } as unknown as EngineState; +// The production `sky-cubemap` row's `fixedSizePx.size` reads +// `settings.sgrAStarLensingTuning.cubemapResolutionPx` (TEMPORARY, Task 15) — +// every `createRenderTargets`/`reconcile` call below goes through the real +// table (`extraRows` only APPENDS), so this fixture needs the field even in +// tests that don't care about the sky-cubemap row itself. +const SKY_CUBEMAP_RESOLUTION_PX = 256; + +function stateWithDivisor( + aggregateDivisor: number, + cubemapResolutionPx: number = SKY_CUBEMAP_RESOLUTION_PX, +): EngineState { + return { + settings: { + milkyWay: { aggregateDivisor }, + sgrAStarLensingTuning: { cubemapResolutionPx }, + }, + } as unknown as EngineState; } // `fixedSizePx` has no row in the production table yet (Phase B adds the @@ -46,6 +61,21 @@ const FIXED_SIZE_ROW: RenderTargetSpec = { fixedSizePx: { size: 256, layers: 6 }, }; +// A `fixedSizePx` row whose `size` is a FUNCTION of state (the +// `sky-cubemap` production row's own shape, TEMPORARILY, Task 15) — +// mirrors `mw-aggregate`'s state-driven `scale`. +const STATE_DRIVEN_FIXED_SIZE_ROW: RenderTargetSpec = { + id: 'test:state-cubemap', + format: 'rgba16float', + depth: null, + scale: 1, + clearValue: { r: 0, g: 0, b: 0, a: 0 }, + fixedSizePx: { + size: (state) => state.settings.sgrAStarLensingTuning.cubemapResolutionPx, + layers: 6, + }, +}; + describe('createRenderTargets', () => { it('viewOf returns a live view per offscreen row and throws for swap', () => { const targets = createRenderTargets( @@ -173,6 +203,35 @@ describe('createRenderTargets', () => { expect(callsAfter).toBe(callsBefore); }); + it('a fixedSizePx row whose size is a function resolves it against live state, and reconcile reallocates when the resolved size moves', () => { + const device = mockDevice(); + const create = device.createTexture as ReturnType; + const targets = createRenderTargets( + device, + SWAP_FORMAT, + { width: 900, height: 600 }, + stateWithDivisor(MW_DIVISOR, 256), + [STATE_DRIVEN_FIXED_SIZE_ROW], + ); + const desc = create.mock.calls.find( + (c) => c[0].label === 'render-target-test:state-cubemap', + )![0]; + expect(desc.size).toEqual({ width: 256, height: 256, depthOrArrayLayers: 6 }); + + const cubeViewBefore = targets.cubeViewOf('test:state-cubemap'); + // Canvas size is UNCHANGED — only the resolved fixedSizePx moved, mirroring + // the mw-aggregate divisor test's "a texture's dimensions are fixed at + // creation" reasoning. + targets.reconcile(stateWithDivisor(MW_DIVISOR, 512), { width: 900, height: 600 }); + + const resized = create.mock.calls + .filter((c) => c[0].label === 'render-target-test:state-cubemap') + .at(-1)![0]; + expect(resized.size).toEqual({ width: 512, height: 512, depthOrArrayLayers: 6 }); + expect(targets.sizeOf('test:state-cubemap')).toEqual({ width: 512, height: 512 }); + expect(targets.cubeViewOf('test:state-cubemap')).not.toBe(cubeViewBefore); + }); + it("reconcile reallocates a row whose state-driven scale moved and leaves the other rows' views untouched", () => { const device = mockDevice(); const create = device.createTexture as ReturnType; diff --git a/tests/state/settings/makeSettingsFixture.ts b/tests/state/settings/makeSettingsFixture.ts index 73230144ab..ae15793a47 100644 --- a/tests/state/settings/makeSettingsFixture.ts +++ b/tests/state/settings/makeSettingsFixture.ts @@ -67,6 +67,7 @@ import { DEFAULT_ORBIT_TRAILS_ENABLED, DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, DEFAULT_ZONE_OF_AVOIDANCE_TUNING, + DEFAULT_SGR_A_STAR_LENSING_TUNING, DEFAULT_POINT_SIZE_PX, DEFAULT_STAR_BRIGHTNESS, DEFAULT_STAR_GLOW_OVERLAP, @@ -80,6 +81,7 @@ import { } from '../../../src/data/defaults'; import { DEFAULT_REFINE_THRESHOLD } from '../../../src/services/gpu/renderers/starCatalog/walkStarOctreeCut'; import { MILKY_WAY_TUNING_DEFAULTS } from '../../../src/services/engine/galaxyGenerator/v1/milkyWayCalibration'; +import { SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION } from '../../../src/services/engine/frame/skyCubemapCaptureSchedule'; import { ATMOSPHERE_PARAMS } from '../../../src/data/bodies/atmosphereParams'; import { EARTH_SURFACE_PARAMS } from '../../../src/data/bodies/earthSurfaceParams'; import { DEBUG_OVERLAY_ROWS } from '../../../src/data/debug/debugOverlayRows'; @@ -140,6 +142,11 @@ export function makeSettingsFixture( enabled: DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, ...DEFAULT_ZONE_OF_AVOIDANCE_TUNING, }, + // TEMPORARY (Task 15) — mirrors initialState.ts's seed. + sgrAStarLensingTuning: { + ...DEFAULT_SGR_A_STAR_LENSING_TUNING, + skyCubemapRecaptureCameraMoveFraction: SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, + }, filaments: { enabled: SOURCE_REGISTRY[Source.Filaments].visible, intensity: SOURCE_REGISTRY[Source.Filaments].intensity, diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index ce8751a17d..43f9b78d82 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -44,9 +44,14 @@ const LUT_MAX_IMPACT_PARAM_RS = 40.5; const LUT_SAMPLE_COUNT = 256; const BAND_ALPHA = 0.578125; const ANCHOR_POS_REL_CAM_M: Vec3 = [3.5, -1.25, 7.75]; +// T15 TEMP tuning-knob fields — deleted along with these sentinels at the +// removal step once Task 17 converges. +const DISK_SCALE_HEIGHT_RS = 0.8125; +const EDGE_FADE_START_FRACTION = 0.65625; +const DOPPLER_STRENGTH = 0.46875; describe('SgrAStarLensingUniforms byte offsets', () => { - it('packs a 144-byte / 36-f32 record with each field at its documented offset', () => { + it('packs a 160-byte / 40-f32 record with each field at its documented offset', () => { const rec = packSgrAStarLensingUniforms( VIEW_PROJ, VIEWPORT_PX, @@ -63,11 +68,14 @@ describe('SgrAStarLensingUniforms byte offsets', () => { LUT_SAMPLE_COUNT, BAND_ALPHA, ANCHOR_POS_REL_CAM_M, + DISK_SCALE_HEIGHT_RS, + EDGE_FADE_START_FRACTION, + DOPPLER_STRENGTH, ); expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); - expect(rec.length).toBe(36); // 144 bytes - expect(rec.byteLength).toBe(144); + expect(rec.length).toBe(40); // 160 bytes + expect(rec.byteLength).toBe(160); // cam.viewProj — all 16 floats verbatim at bytes 0..63. for (let i = 0; i < 16; i++) expect(rec[i]).toBe(VIEW_PROJ[i]); @@ -101,8 +109,13 @@ describe('SgrAStarLensingUniforms byte offsets', () => { expect(rec[33]).toBe(ANCHOR_POS_REL_CAM_M[1]); // byte 132 expect(rec[34]).toBe(ANCHOR_POS_REL_CAM_M[2]); // byte 136 - // _pad2 — the vec3's trailing slot, rounds the struct to 144. Untouched, - // stays zero. - expect(rec[35]).toBe(0); // byte 140 + // T15 TEMP tuning-knob fields, offset 140+ (float index 35+). + expect(rec[35]).toBe(DISK_SCALE_HEIGHT_RS); // byte 140 + expect(rec[36]).toBe(EDGE_FADE_START_FRACTION); // byte 144 + expect(rec[37]).toBe(DOPPLER_STRENGTH); // byte 148 + + // Trailing pad — rounds the struct to 160. Untouched, stays zero. + expect(rec[38]).toBe(0); // byte 152 + expect(rec[39]).toBe(0); // byte 156 }); }); diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 07156428e5..4fe789b895 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -52,7 +52,8 @@ function structFields(source: string, name: string): Array<{ name: string; type: .filter((line) => line.length > 0) .map((line) => { const [fieldName, type] = line.split(':').map((part) => part.trim()); - if (!fieldName || !type) throw new Error(`unparsable SgrAStarLensingUniforms field: '${line}'`); + if (!fieldName || !type) + throw new Error(`unparsable SgrAStarLensingUniforms field: '${line}'`); return { name: fieldName, type }; }); } @@ -108,6 +109,11 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const lutSampleCount = 511; const bandAlpha = 512; const anchorPosRelCamM: Vec3 = [601, 602, 603]; + // T15 TEMP tuning-knob fields — deleted along with these sentinels at the + // removal step once Task 17 converges. + const diskScaleHeightRs = 701; + const edgeFadeStartFraction = 702; + const dopplerStrength = 703; const rec = packSgrAStarLensingUniforms( viewProj, @@ -125,6 +131,9 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { lutSampleCount, bandAlpha, anchorPosRelCamM, + diskScaleHeightRs, + edgeFadeStartFraction, + dopplerStrength, ); const vectorByField: Record = { anchorPosRelCamM }; @@ -141,8 +150,11 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { lutMaxImpactParamRs, lutSampleCount, bandAlpha, + diskScaleHeightRs, + edgeFadeStartFraction, + dopplerStrength, }; - const zeroPadFields = new Set(['_pad2']); + const zeroPadFields = new Set(['_pad3', '_pad4']); for (const field of layout) { if (field.lanes === 0) { From 276130d7ff0663a95f75f68eceaf275a5d49109e Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 18:30:56 +0200 Subject: [PATCH 38/60] feat(black-hole): add 2048 cubemap option, emission strength/tint knobs (T15) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to the Task 15 debug-panel commit, per user review: - Sky-cubemap resolution select gains a 2048 option (256/512/1024/2048, default unchanged at 512). No other clamp exists on the size (device limits default maxTextureDimension2D 8192, well above 2048); the option's tooltip already states the general VRAM formula rather than a per-option figure, so 2048's ~192 MiB is covered by that, not a new precedent. - New Tier-2 knobs: emissionStrength (overall multiplier on the annulus emission's summed output) and emissionTint (overall tint multiplier on the same), applied in fragment.wesl's annulusEmission after the per-sample march sums, not per-sample — so the density/ radial coverage that drives blending stays unscaled. Defaults (1, [1,1,1]) are no-ops, reproducing today's brightness exactly. SgrAStarLensingUniforms grew 160->176 bytes; packer and the WESL-parity test updated in lockstep. No true log slider — SliderField has no curve option — so emissionStrength uses a fine linear step across a generous 0-8x range instead. - Trimmed SgrAStarLensingTuning.d.ts's module header from 29 to 9 lines, mirroring ZoneOfAvoidanceTuning.d.ts's budget-compliant header. Co-Authored-By: Claude Fable 5 --- .../SgrAStarLensingSliderKey.d.ts | 12 +++--- .../settings/SgrAStarLensingTuning.d.ts | 42 +++++++------------ .../SgrAStarLensingTuningSection.tsx | 28 ++++++++++++- src/data/defaults.ts | 7 +++- .../sgrAStarLensingSliderFields.ts | 14 +++++++ .../frame/passes/sgrAStarLensingLayer.ts | 2 + .../bodies/sgrAStarLensingRenderer.ts | 4 +- .../bodies/sgrAStarLensing/fragment.wesl | 8 +++- .../gpu/shaders/lib/sgrAStarLensing.wesl | 17 +++++--- src/utils/gpu/packSgrAStarLensingUniforms.ts | 30 +++++++++---- .../gpu/packSgrAStarLensingUniforms.test.ts | 22 +++++++--- ...rAStarLensingUniformsLayout.parity.test.ts | 9 +++- 12 files changed, 134 insertions(+), 61 deletions(-) diff --git a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts index de32f06887..1702e0817b 100644 --- a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts +++ b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts @@ -2,9 +2,11 @@ import type { SgrAStarLensingTuning } from '../../settings/SgrAStarLensingTuning /** * TEMPORARY (Task 15). Keys of `SgrAStarLensingTuning` that surface as - * numeric DebugPanel sliders. `cubemapResolutionPx` is excluded: it only - * takes three meaningful values (256/512/1024), so the section gives it a - * ``) + * and `emissionTint` (a `Vec3` colour picker) get bespoke controls instead — + * the same split `ZoneOfAvoidanceSliderKey` makes for its colour fields. */ -export type SgrAStarLensingSliderKey = Exclude; +export type SgrAStarLensingSliderKey = Exclude< + keyof SgrAStarLensingTuning, + 'cubemapResolutionPx' | 'emissionTint' +>; diff --git a/src/@types/settings/SgrAStarLensingTuning.d.ts b/src/@types/settings/SgrAStarLensingTuning.d.ts index 54ddd60f8f..3d05231557 100644 --- a/src/@types/settings/SgrAStarLensingTuning.d.ts +++ b/src/@types/settings/SgrAStarLensingTuning.d.ts @@ -1,33 +1,15 @@ /** - * SgrAStarLensingTuning — TEMPORARY (Task 15) DebugPanel knobs for the Sgr A* - * lens pass, live-tuned during Task 17's visual gate. Deleted (type + every - * reader) at Task 15's removal step, once Task 17 converges and the tuned - * values are baked back into `BLACK_HOLES` (Task 6), `fragment.wesl`'s shader - * constants (Task 6/13), and the relevant module constants as shipped - * literals — see the task-15 brief's "Removal step". - * - * Two tiers, per the brief: - * - TIER 1 (`innerRs`..`flickerTimescaleS`): already ride the 144-byte - * `SgrAStarLensingUniforms` struct via `BLACK_HOLES`; this settings - * cluster is read at pack time INSTEAD of the static registry, same as - * `MilkyWayTuning` overrides `milkyWayCalibration`'s seed after boot. - * - TIER 2 (`diskScaleHeightRs`..`dopplerStrength`): were shader-local - * `const`s in `fragment.wesl`; the struct grew 144 → 160 bytes to carry - * them (see `sgrAStarLensing.wesl` + `packSgrAStarLensingUniforms.ts`). - * Plus two CPU-side (non-uniform) knobs riding the same settings seam: - * `skyCubemapRecaptureCameraMoveFraction` (was a module constant in - * `skyCubemapCaptureSchedule.ts`) and `cubemapResolutionPx` (the sky-cubemap - * render-target row's `fixedSizePx.size`, now state-driven — see - * `renderTargets.ts`'s `resolveFixedSize`). - * - * No `glintTint` / `glintIntensity`: wiring those (the far-field glint marker - * in `bodyGlintsLayer.ts`) through this seam would mean threading `state` - * into the pure, gate-and-emit-shared `sgrAStarGlintBrightness` helper and - * expanding `bodyGlintsLayer.test.ts`'s several hand-built `EngineState` - * fixtures — beyond this task's "don't invent new plumbing" bound. Left as - * `bodyGlintsLayer.ts`'s own module constants. + * SgrAStarLensingTuning — TEMPORARY (Task 15) DebugPanel knobs for the Sgr + * A* lens pass, deleted at the removal step once Task 17 converges (tuned + * values baked back into `BLACK_HOLES` / shader consts / module constants). + * Tier 1 overrides `BLACK_HOLES` at pack time; Tier 2 + emission + * strength/tint are new `SgrAStarLensingUniforms` fields (struct grew + * 144→176 bytes); the rest are non-uniform CPU-side knobs on the same + * settings seam. No `glintTint`/`glintIntensity` — see `bodyGlintsLayer.ts`. */ +import type { Vec3 } from '../math/Vec3'; + export type SgrAStarLensingTuning = { // ── Tier 1 — BLACK_HOLES override, rides the existing uniform fields ──── innerRs: number; @@ -44,12 +26,16 @@ export type SgrAStarLensingTuning = { edgeFadeStartFraction: number; /** Was `fragment.wesl`'s `DOPPLER_STRENGTH` const. */ dopplerStrength: number; + /** 2nd addendum: overall multiplier on the annulus emission's summed output. Default 1 reproduces today's brightness. */ + emissionStrength: number; + /** 2nd addendum: overall multiplier on the annulus emission's summed tint. Default [1,1,1] is a no-op. */ + emissionTint: Vec3; // ── Non-uniform, same settings seam ────────────────────────────────────── /** Was `skyCubemapCaptureSchedule.ts`'s `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`. */ skyCubemapRecaptureCameraMoveFraction: number; /** - * The `sky-cubemap` render-target row's per-axis pixel size (256/512/1024). + * The `sky-cubemap` render-target row's per-axis pixel size (256/512/1024/2048). * Read by `renderTargets.ts`'s state-driven `fixedSizePx.size` resolver, so * a change takes effect on the next `reconcile()` — no reload needed. */ diff --git a/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx b/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx index 593b0c1915..c939ea0bcb 100644 --- a/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx +++ b/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx @@ -4,12 +4,20 @@ * removal step once Task 17 converges on final values (see * `SgrAStarLensingTuning`'s own docblock). Structural precedent: * `ZoneOfAvoidanceTuningSection.tsx`. `cubemapResolutionPx` gets a ` +
+ emissionTint + {linearRgbToHex(tuning.emissionTint)} + { + const emissionTint = hexToLinearRgb(e.target.value as HexString); + onChange({ emissionTint }); + }} + /> +
); } diff --git a/src/data/defaults.ts b/src/data/defaults.ts index 9088b95b05..decc19b0b5 100644 --- a/src/data/defaults.ts +++ b/src/data/defaults.ts @@ -278,7 +278,10 @@ export const DEFAULT_ZONE_OF_AVOIDANCE_TUNING: ZoneOfAvoidanceTuning = { * mirrors `fragment.wesl`'s former `DISK_SCALE_HEIGHT_RS` / the escape * branch's `* 0.7` edge-fade factor / `DOPPLER_STRENGTH` — this literal is * their new single source of truth until the removal step bakes the tuned - * values back into the shader as consts. + * values back into the shader as consts. `emissionStrength: 1` / + * `emissionTint: [1,1,1]` (2nd addendum) are no-op identities — the shader + * had no such multiplier before, so a no-op default reproduces today's + * brightness exactly. * * `cubemapResolutionPx` seeds the `sky-cubemap` render-target row's declared * size (`renderTargets.ts`) — 512, the user's visual-tuning call bumping it @@ -304,6 +307,8 @@ export const DEFAULT_SGR_A_STAR_LENSING_TUNING: Omit< diskScaleHeightRs: 0.4, edgeFadeStartFraction: 0.7, dopplerStrength: 0.6, + emissionStrength: 1, + emissionTint: [1, 1, 1], cubemapResolutionPx: 512, }; diff --git a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts index 7208113b77..f75e6a1af2 100644 --- a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts +++ b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts @@ -91,6 +91,20 @@ export const SGR_A_STAR_LENSING_SLIDER_FIELDS: readonly SgrAStarLensingSliderFie format: (v) => v.toFixed(2), title: 'Doppler-beaming strength factor.', }, + { + key: 'emissionStrength', + label: 'emissionStrength', + min: 0, + // Generous both ways for judging faintness against the spec's "faint + // EHT-style glow" — SliderField has no log/curve option (a plain native + // range input), so a fine linear step stands in for log-ish granularity + // near 1x rather than a true log scale. + max: 8, + step: 0.05, + format: (v) => v.toFixed(2), + title: + "Overall multiplier on the annulus emission's summed output intensity. 1 = today's brightness.", + }, { key: 'skyCubemapRecaptureCameraMoveFraction', label: 'recaptureMoveFraction', diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 6a8efcedb9..e643734035 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -122,6 +122,8 @@ export const sgrAStarLensingLayer: ContentLayer = { tuning.diskScaleHeightRs, tuning.edgeFadeStartFraction, tuning.dopplerStrength, + tuning.emissionStrength, + tuning.emissionTint, ); const skyCubemapView = ctx.renderTargets.cubeViewOf('sky-cubemap'); diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts index f5841d7ef6..91c41d0bb9 100644 --- a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -90,12 +90,12 @@ export function createSgrAStarLensingRenderer( const lutTexture = createLutTexture(device, lut); const lutView = lutTexture.createView({ label: 'sgr-a-star-lensing-lut-view' }); - // ── Uniform buffer (160 bytes, byte-exact with SgrAStarLensingUniforms — + // ── Uniform buffer (176 bytes, byte-exact with SgrAStarLensingUniforms — // TEMPORARILY grown from 144 for Task 15's Tier-2 DebugPanel knobs; shrinks // back at the removal step once Task 17 converges) ── const uniformBuffer = device.createBuffer({ label: 'sgr-a-star-lensing-uniform-buffer', - size: 160, + size: 176, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, }); diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index 499459b5ae..daed7dff75 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -133,8 +133,12 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflec coverage = max(coverage, emissionSample.a); } + // Applied to the SUMMED emission, not per-sample: a flat brightness/tint + // multiplier on the whole march's output, not on the physical falloff that + // feeds 'coverage' (which stays keyed to the modeled density/radial + // profile, unscaled — T15 TEMP tuning knobs, 2nd addendum). if (captured) { - return vec4(emission, coverage); + return vec4(emission * u.emissionStrength * u.emissionTint, coverage); } let kink = rayDir * closestT; // camera-relative position at closest approach — the bend point @@ -146,7 +150,7 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflec coverage = max(coverage, emissionSample.a); } - return vec4(emission, coverage); + return vec4(emission * u.emissionStrength * u.emissionTint, coverage); } @fragment diff --git a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl index 04b82c29c6..21294158a7 100644 --- a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl +++ b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl @@ -30,9 +30,11 @@ // offset 140 : diskScaleHeightRs f32 — T15 TEMP tuning knob, was fragment.wesl's DISK_SCALE_HEIGHT_RS const // offset 144 : edgeFadeStartFraction f32 — T15 TEMP tuning knob, was the escape branch's hardcoded '* 0.7' // offset 148 : dopplerStrength f32 — T15 TEMP tuning knob, was fragment.wesl's DOPPLER_STRENGTH const -// offset 152 : _pad3 f32 — T15 TEMP, rounds the struct to 160 / 16-byte -// offset 156 : _pad4 f32 — T15 TEMP, rounds the struct to 160 / 16-byte -// total: 160 bytes. +// offset 152 : emissionStrength f32 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission multiplier +// offset 156 : _pad4 f32 — T15 TEMP, pads emissionStrength up to emissionTint's 16-byte alignment +// offset 160 : emissionTint vec3 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission tint +// offset 172 : _pad5 f32 — T15 TEMP, rounds the struct to 176 / 16-byte +// total: 176 bytes. // // The 12 scalar fields (80..127, 48 bytes) exactly fill the run up to 128, // so 'anchorPosRelCamM' lands on a 16-byte boundary with no implicit padding @@ -43,8 +45,9 @@ // silently reads garbage — no compile error, no runtime error, just a wrong // (or on iOS, dropped) frame. // -// TASK 15 TEMPORARY: the three fields after 'anchorPosRelCamM' are DebugPanel -// tuning knobs (Tier 2 of the task-15 brief), deleted — struct shrunk back to +// TASK 15 TEMPORARY: every field after 'anchorPosRelCamM' is a DebugPanel +// tuning knob (Tier 2 of the task-15 brief, plus its 2nd-round addendum +// adding emissionStrength/emissionTint), deleted — struct shrunk back to // 144 bytes — at the removal step once Task 17 converges on final values. import package::lib::camera::CameraUniforms; @@ -67,6 +70,8 @@ struct SgrAStarLensingUniforms { diskScaleHeightRs: f32, edgeFadeStartFraction: f32, dopplerStrength: f32, - _pad3: f32, + emissionStrength: f32, _pad4: f32, + emissionTint: vec3, + _pad5: f32, }; diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index a24c28db3b..0cadcbcefa 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -1,8 +1,9 @@ /** * packSgrAStarLensingUniforms — pure packer for the `SgrAStarLensingUniforms` - * struct (`shaders/lib/sgrAStarLensing.wesl`) — TEMPORARILY 160 bytes (Task - * 15's Tier-2 DebugPanel knobs; shrinks back to 144 at Task 15's removal - * step once Task 17 converges — see that .wesl file's own header). + * struct (`shaders/lib/sgrAStarLensing.wesl`) — TEMPORARILY 176 bytes (Task + * 15's Tier-2 DebugPanel knobs, incl. the 2nd-round emission strength/tint + * addendum; shrinks back to 144 at Task 15's removal step once Task 17 + * converges — see that .wesl file's own header). * * Task 10's half of the uniform contract between the Sgr A* lens pass * (Task 13, not yet written) and its WGSL. The struct is the shared @@ -34,9 +35,12 @@ * f32 35 (byte 140..143): diskScaleHeightRs — T15 TEMP tuning knob * f32 36 (byte 144..147): edgeFadeStartFraction — T15 TEMP tuning knob * f32 37 (byte 148..151): dopplerStrength — T15 TEMP tuning knob - * f32 38..39 (byte 152..159): untouched (zero) — struct's 16-byte round-up + * f32 38 (byte 152..155): emissionStrength — T15 TEMP tuning knob (2nd addendum) + * f32 39 (byte 156..159): untouched (zero) — pads emissionTint to 16-byte alignment + * f32 40..42 (byte 160..171): emissionTint — T15 TEMP tuning knob (2nd addendum), vec3 + * f32 43 (byte 172..175): untouched (zero) — struct's 16-byte round-up * - * Total: 160 bytes / 40 f32. The 12 scalars at f32 20..31 exactly fill the + * Total: 176 bytes / 44 f32. The 12 scalars at f32 20..31 exactly fill the * run up to f32 32, so `anchorPosRelCamM` lands on a 16-byte boundary with * no implicit padding — see the .wesl module header for the alignment * argument. @@ -64,6 +68,8 @@ * @param diskScaleHeightRs T15 TEMP — vertical falloff scale height, r_s units. * @param edgeFadeStartFraction T15 TEMP — escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. * @param dopplerStrength T15 TEMP — Doppler-beaming strength factor. + * @param emissionStrength T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's output intensity. + * @param emissionTint T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's per-sample tint. */ import type { Mat4 } from 'wgpu-matrix'; @@ -72,8 +78,9 @@ import type { Vec3 } from '../../@types/math/Vec3'; import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/cameraUniforms'; /** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 - * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (3) + pad (2) = 40. */ -export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 20; + * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (4 scalars + + * emissionTint's 3) + pad (2) = 44. */ +export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 24; export function packSgrAStarLensingUniforms( viewProj: Float32Array | Mat4, @@ -94,6 +101,8 @@ export function packSgrAStarLensingUniforms( diskScaleHeightRs: number, edgeFadeStartFraction: number, dopplerStrength: number, + emissionStrength: number, + emissionTint: Readonly, ): Float32Array { const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); writeCameraPrefix(out, viewProj, viewportPx); // f32 0..17; 18..19 stay zero @@ -115,6 +124,11 @@ export function packSgrAStarLensingUniforms( out[35] = diskScaleHeightRs; // byte 140 — T15 TEMP out[36] = edgeFadeStartFraction; // byte 144 — T15 TEMP out[37] = dopplerStrength; // byte 148 — T15 TEMP - // out[38..39] (byte 152..159) stay zero — the struct's 16-byte round-up. + out[38] = emissionStrength; // byte 152 — T15 TEMP (2nd addendum) + // out[39] (byte 156..159) stays zero — pads emissionTint to 16-byte alignment. + out[40] = emissionTint[0]; // byte 160 — T15 TEMP (2nd addendum), vec3 + out[41] = emissionTint[1]; // byte 164 + out[42] = emissionTint[2]; // byte 168 + // out[43] (byte 172..175) stays zero — the struct's 16-byte round-up. return out; } diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index 43f9b78d82..1200e2bccd 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -49,9 +49,11 @@ const ANCHOR_POS_REL_CAM_M: Vec3 = [3.5, -1.25, 7.75]; const DISK_SCALE_HEIGHT_RS = 0.8125; const EDGE_FADE_START_FRACTION = 0.65625; const DOPPLER_STRENGTH = 0.46875; +const EMISSION_STRENGTH = 0.90625; +const EMISSION_TINT: Vec3 = [801, 802, 803]; describe('SgrAStarLensingUniforms byte offsets', () => { - it('packs a 160-byte / 40-f32 record with each field at its documented offset', () => { + it('packs a 176-byte / 44-f32 record with each field at its documented offset', () => { const rec = packSgrAStarLensingUniforms( VIEW_PROJ, VIEWPORT_PX, @@ -71,11 +73,13 @@ describe('SgrAStarLensingUniforms byte offsets', () => { DISK_SCALE_HEIGHT_RS, EDGE_FADE_START_FRACTION, DOPPLER_STRENGTH, + EMISSION_STRENGTH, + EMISSION_TINT, ); expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); - expect(rec.length).toBe(40); // 160 bytes - expect(rec.byteLength).toBe(160); + expect(rec.length).toBe(44); // 176 bytes + expect(rec.byteLength).toBe(176); // cam.viewProj — all 16 floats verbatim at bytes 0..63. for (let i = 0; i < 16; i++) expect(rec[i]).toBe(VIEW_PROJ[i]); @@ -113,9 +117,17 @@ describe('SgrAStarLensingUniforms byte offsets', () => { expect(rec[35]).toBe(DISK_SCALE_HEIGHT_RS); // byte 140 expect(rec[36]).toBe(EDGE_FADE_START_FRACTION); // byte 144 expect(rec[37]).toBe(DOPPLER_STRENGTH); // byte 148 + expect(rec[38]).toBe(EMISSION_STRENGTH); // byte 152 - // Trailing pad — rounds the struct to 160. Untouched, stays zero. - expect(rec[38]).toBe(0); // byte 152 + // Pad before emissionTint's 16-byte alignment — untouched, stays zero. expect(rec[39]).toBe(0); // byte 156 + + // emissionTint — vec3 at byte 160 (float index 40). + expect(rec[40]).toBe(EMISSION_TINT[0]); // byte 160 + expect(rec[41]).toBe(EMISSION_TINT[1]); // byte 164 + expect(rec[42]).toBe(EMISSION_TINT[2]); // byte 168 + + // Trailing pad — rounds the struct to 176. Untouched, stays zero. + expect(rec[43]).toBe(0); // byte 172 }); }); diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 4fe789b895..5cf7a075d1 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -114,6 +114,8 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const diskScaleHeightRs = 701; const edgeFadeStartFraction = 702; const dopplerStrength = 703; + const emissionStrength = 704; + const emissionTint: Vec3 = [801, 802, 803]; const rec = packSgrAStarLensingUniforms( viewProj, @@ -134,9 +136,11 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { diskScaleHeightRs, edgeFadeStartFraction, dopplerStrength, + emissionStrength, + emissionTint, ); - const vectorByField: Record = { anchorPosRelCamM }; + const vectorByField: Record = { anchorPosRelCamM, emissionTint }; const scalarByField: Record = { schwarzschildRadiusM, innerRs, @@ -153,8 +157,9 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { diskScaleHeightRs, edgeFadeStartFraction, dopplerStrength, + emissionStrength, }; - const zeroPadFields = new Set(['_pad3', '_pad4']); + const zeroPadFields = new Set(['_pad4', '_pad5']); for (const field of layout) { if (field.lanes === 0) { From 65d84a1517b9530e531737c2c13ac16584275f69 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 18:37:04 +0200 Subject: [PATCH 39/60] fix(black-hole): mirror sky-cubemap capture vps for WebGPU's top-left origin The FACE_UP table is the GL cube-capture table, which only samples upright under GL's bottom-left framebuffer origin; WebGPU rasterizes top-left, so every captured face landed vertically flipped (v = 1 - t) at texture_cube sample time - the misaligned stars at the lens fade boundary. The cube-face (s,t) set is a mirror of any right-handed capture basis, so no rotation fixes it; negate clip-space Y on every capture vp instead. Derivation in .superpowers/sdd/2026-09-01-render-black-hole/audit-cubemap-alignment.md. Co-Authored-By: Claude Fable 5 --- .../engine/frame/skyCubemapFaceContext.ts | 25 ++++++- .../frame/skyCubemapFaceContext.test.ts | 71 +++++++++++++++++++ 2 files changed, 95 insertions(+), 1 deletion(-) diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts index ff4c174895..5c5a36ebe1 100644 --- a/src/services/engine/frame/skyCubemapFaceContext.ts +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -71,6 +71,24 @@ const FACE_BASES: readonly Mat3[] = FACE_FORWARD.map((forward, i): Mat3 => { return mat3FromColumns(cross3(up, back), up, back); }); +/** + * Negate a view-projection's clip-space Y row (column-major 1/5/9/13). + * The cube-face (s,t) convention is a MIRROR of any right-handed capture + * basis: `FACE_UP` is the classic GL capture table, which only samples + * upright under GL's bottom-left framebuffer origin. WebGPU rasterizes + * top-left, so every face would land vertically flipped (v = 1 − t) at + * `texture_cube` sample time — see audit-cubemap-alignment.md. No rotation + * can absorb a reflection, hence this clip-Y negation on every capture vp. + * The winding reversal it implies is harmless: the capture roster is + * entirely cull-free point/billboard pipelines. + */ +function flipClipY(vp: Float32Array | Float64Array): void { + vp[1] = -vp[1]!; + vp[5] = -vp[5]!; + vp[9] = -vp[9]!; + vp[13] = -vp[13]!; +} + export function skyCubemapFaceContext(input: { readonly state: EngineState; readonly eyeMpc: Readonly; @@ -107,9 +125,14 @@ export function skyCubemapFaceContext(input: { performance.now(), state.cameraRuntime.lastRenderedSimDays.current, ); + if (!ctx.isReady) return null; + // Mirror every capture vp (see flipClipY). In place: deriveFrameContext + // freshly allocated these arrays for this call, nothing else aliases them. + flipClipY(ctx.vp); + for (const slab of ctx.slabs) flipClipY(slab.vp); // Stamp this face's view slot (`face + 1` — slot 0 is the main view; see // `ReadyFrameContext.viewSlot`'s doc) so a roster renderer's view-slot // buffer helper keys this call's writes into a destination the main // view's own `viewSlot: 0` draw never touches. - return ctx.isReady ? { ...ctx, viewSlot: face + 1 } : null; + return { ...ctx, viewSlot: face + 1 }; } diff --git a/tests/services/engine/frame/skyCubemapFaceContext.test.ts b/tests/services/engine/frame/skyCubemapFaceContext.test.ts index a50a3cde91..db481a70e2 100644 --- a/tests/services/engine/frame/skyCubemapFaceContext.test.ts +++ b/tests/services/engine/frame/skyCubemapFaceContext.test.ts @@ -173,6 +173,77 @@ describe('skyCubemapFaceContext', () => { expect(ctx.visibleSourceMask).toBe(deriveSourceMasks(state).draw); }); + it('renders a world direction to the exact (s,t) the WGSL cube sampler computes for it', () => { + // Capture↔sample identity (audit-cubemap-alignment.md): a star at world + // direction d must land, under the face camera's vp + WebGPU's top-left + // viewport transform, on the SAME (u,v) the GL/Vulkan/WGSL cube-face + // table derives from d. Independently implements both sides; fails as + // v = 1 − t if the capture's clip-Y mirror is ever dropped. One + // direction per face, all with t well away from the flip-invariant 0.5. + const state = makeState(); + const directions: readonly Vec3[] = [ + [0.9, 0.1, 0.3], // +X + [-0.9, 0.2, 0.15], // −X + [0.1, 0.8, 0.2], // +Y + [0.2, -0.85, 0.3], // −Y + [0.15, 0.2, 0.9], // +Z + [0.3, 0.2, -0.93], // −Z + ]; + + for (const d of directions) { + // Cube-face selection + (s,t) per the GL table 8.19 / WGSL rules. + const [x, y, z] = d; + const ax = Math.abs(x); + const ay = Math.abs(y); + const az = Math.abs(z); + let face: number; + let sc: number; + let tc: number; + let ma: number; + if (ax >= ay && ax >= az) { + face = x > 0 ? 0 : 1; + ma = ax; + sc = x > 0 ? -z : z; + tc = -y; + } else if (ay >= az) { + face = y > 0 ? 2 : 3; + ma = ay; + sc = x; + tc = y > 0 ? z : -z; + } else { + face = z > 0 ? 4 : 5; + ma = az; + sc = z > 0 ? x : -x; + tc = -y; + } + const s = (sc / ma + 1) / 2; + const t = (tc / ma + 1) / 2; + + const ctx = skyCubemapFaceContext({ + state, + eyeMpc: EYE_MPC, + face: face as CubeFace, + faceSizePx: 256, + }); + expect(ctx).not.toBeNull(); + if (ctx === null) continue; + + // World point 1 Mpc out along d, through the face's cosmo vp + // (column-major, clip = vp · [p, 1]). + const p: Vec3 = [EYE_MPC[0] + d[0], EYE_MPC[1] + d[1], EYE_MPC[2] + d[2]]; + const vp = ctx.vp; + const cx = vp[0]! * p[0] + vp[4]! * p[1] + vp[8]! * p[2] + vp[12]!; + const cy = vp[1]! * p[0] + vp[5]! * p[1] + vp[9]! * p[2] + vp[13]!; + const cw = vp[3]! * p[0] + vp[7]! * p[1] + vp[11]! * p[2] + vp[15]!; + // WebGPU viewport transform: top-left origin, y down. + const u = (cx / cw + 1) / 2; + const v = (1 - cy / cw) / 2; + + expect(u).toBeCloseTo(s, 5); + expect(v).toBeCloseTo(t, 5); + } + }); + it("clips well below the S-star scale, not the live cosmo camera's 10-kpc near plane", () => { // The capture's actual content (S-stars, the field around Sgr A*) sits // at hundreds of AU — reusing the live projection's near (0.01 Mpc / From 576a636c9db5ace79737a9b8f66ee66932c5ae8f Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 19:29:59 +0200 Subject: [PATCH 40/60] fix(black-hole): fade the lens where deflection is subpixel, not at the LUT edge Fading at b = lutMax (50 r_s) blended a sky still deflected ~2.4-3.4 deg (~39-56 px at 100 AU / 1080p / 60 deg fov) into the unshifted roster - the double image at the blend ring. Now: (1) the deflection continues past the LUT as endpoint*(lutMax/b), exactly continuous at the handoff; (2) the fade ends at edgeFadeEndRs (new uniform in the former _pad4 slot), derived per frame as max(lutMax, min(2*drawPxPerRad, 0.6*distRs)) - where 2/b drops below one screen pixel, capped where billboard coverage tops out; (3) the quad sizes itself to cover that fade end (R = b*d/sqrt(d^2-b^2)); (4) the 48-step annulus march is skipped for b > outerRs + 4, output-identically, so the now-near-fullscreen escape region stays cheap. Band gating and the capture roster untouched. Derivation in audit-cubemap-alignment.md section 7. Co-Authored-By: Claude Fable 5 --- .../sgrAStarLensingSliderFields.ts | 2 +- .../frame/passes/sgrAStarLensingLayer.ts | 18 +++++++++ .../bodies/sgrAStarLensing/fragment.wesl | 38 +++++++++++++++---- .../bodies/sgrAStarLensing/vertex.wesl | 20 ++++++++-- .../gpu/shaders/lib/sgrAStarLensing.wesl | 6 ++- src/utils/gpu/packSgrAStarLensingUniforms.ts | 8 ++-- .../gpu/packSgrAStarLensingUniforms.test.ts | 6 ++- ...rAStarLensingUniformsLayout.parity.test.ts | 5 ++- .../buildSchwarzschildDeflectionLut.test.ts | 15 ++++++++ 9 files changed, 97 insertions(+), 21 deletions(-) diff --git a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts index f75e6a1af2..32bc60a0ce 100644 --- a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts +++ b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts @@ -80,7 +80,7 @@ export const SGR_A_STAR_LENSING_SLIDER_FIELDS: readonly SgrAStarLensingSliderFie max: 1, step: 0.01, format: (v) => v.toFixed(2), - title: "Escape branch's edge-fade start, as a fraction of the LUT's max impact parameter.", + title: "Escape branch's edge-fade start, as a fraction of the frame's derived edge-fade end.", }, { key: 'dopplerStrength', diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index e643734035..75aca4b0bd 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -103,6 +103,23 @@ export const sgrAStarLensingLayer: ContentLayer = { const tuning = state.settings.sgrAStarLensingTuning; const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / tuning.flickerTimescaleS; + // Where the escape fade must reach zero: weak-field deflection is 2/b rad + // (b in r_s), so it drops below one screen pixel at b = 2·drawPxPerRad. + // Capped at 0.6× the camera's distance (in r_s) because a billboard's + // impact-parameter coverage can never exceed that distance — 0.6 bounds + // the vertex's plane-stretch factor at 1.25 (see vertex.wesl) — and + // floored at the LUT max so the fade never cuts into the LUT-resolved + // strong-field region during a close descent. Fading at the raw LUT edge + // instead blended a sky still deflected ~40 px into the true sky (see + // audit-cubemap-alignment.md §7). + const distRs = + Math.hypot(anchorPosRelCamM[0], anchorPosRelCamM[1], anchorPosRelCamM[2]) / + SCHWARZSCHILD_RADIUS_M; + const edgeFadeEndRs = Math.max( + renderer.lut.maxImpactParamRs, + Math.min(2 * ctx.drawPxPerRad, 0.6 * distRs), + ); + const uniforms = packSgrAStarLensingUniforms( view.vp, view.viewportPx, @@ -123,6 +140,7 @@ export const sgrAStarLensingLayer: ContentLayer = { tuning.edgeFadeStartFraction, tuning.dopplerStrength, tuning.emissionStrength, + edgeFadeEndRs, tuning.emissionTint, ); diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index daed7dff75..48970bd08a 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -28,6 +28,9 @@ struct FsIn { const CAPTURE_THRESHOLD_RAD: f32 = 500.0; const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound +// Impact-parameter margin past outerRs beyond which the annulus march is +// skipped (see the gate in 'fs' for the exactness argument). +const MARCH_GATE_MARGIN_RS: f32 = 4.0; // Split across the bent-ray march's two segments (Task 13c finding 3). const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // inner/outer annulus edge softening width @@ -174,7 +177,14 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4= CAPTURE_THRESHOLD_RAD; // Bruneton: delta_prime = delta + deflection — the backward lookup must // rotate the ray TOWARD the hole to recover the source's asymptotic @@ -192,16 +202,28 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4= b·cos(bend) > outerRs + + // feather for all b > outerRs + 4 across the tuning range — so the skip is + // output-identical, and spares the 48-step march over the (much larger, + // now fade-extended) escape region. Captured rays (b <= b_c ~ 2.6) always + // pass this gate. + if (impactParamRs <= u.outerRs + MARCH_GATE_MARGIN_RS) { + let annulus = annulusEmission(rayDir, toAnchor, closestT, deflected, captured, fragCoord.xy); + color += annulus.rgb; + alpha = max(alpha, u.bandAlpha * annulus.a); + } return vec4(color * alpha, alpha); // premultiplied, per PREMULTIPLIED_OVER_BLEND } diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl index 20aff461c2..7ff8525654 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl @@ -11,9 +11,10 @@ import package::lib::billboard::quadCorner; @group(0) @binding(0) var u: SgrAStarLensingUniforms; -// Half-size as a multiple of the LUT's max impact parameter — margin past -// the fragment's matching edge fade so the two can't drift apart. -const BILLBOARD_MARGIN: f32 = 1.5; +// Slack on the exactly-computed fade-covering plane radius below — only +// float rounding to absorb, so the fragment's fade always reaches 0 strictly +// inside the quad. +const BILLBOARD_MARGIN: f32 = 1.1; struct VsOut { @builtin(position) clip: vec4, @@ -33,7 +34,18 @@ fn vs(@builtin(vertex_index) vi: u32) -> VsOut { let right = normalize(cross(worldUp, forward)); let up = cross(forward, right); - let worldRadiusM = u.schwarzschildRadiusM * u.lutMaxImpactParamRs * BILLBOARD_MARGIN; + // Cover impact parameters out to the fragment's fade end: a fragment at + // plane radius R (anchor distance d) rides a ray with impact parameter + // b = R·d/sqrt(R^2 + d^2), so R = b·d/sqrt(d^2 - b^2). The layer caps + // 'edgeFadeEndRs' at 0.6·d (in r_s), bounding this stretch at 1.25 — but + // its lutMax floor can exceed d during a close descent, where the max() + // degenerates the sqrt and R blows up to an effectively fullscreen quad: + // exactly the right limit there (everything on screen is strongly lensed), + // clip does the bounding. + let dRs = anchorDistM / u.schwarzschildRadiusM; + let fadeEndRs = u.edgeFadeEndRs; + let planeRadiusRs = fadeEndRs * dRs / sqrt(max(dRs * dRs - fadeEndRs * fadeEndRs, 1e-6)); + let worldRadiusM = u.schwarzschildRadiusM * planeRadiusRs * BILLBOARD_MARGIN; let corner = quadCorner(vi); let posRelCamM = toAnchor + right * (corner.x * worldRadiusM) + up * (corner.y * worldRadiusM); diff --git a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl index 21294158a7..36ec3e20d4 100644 --- a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl +++ b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl @@ -31,7 +31,9 @@ // offset 144 : edgeFadeStartFraction f32 — T15 TEMP tuning knob, was the escape branch's hardcoded '* 0.7' // offset 148 : dopplerStrength f32 — T15 TEMP tuning knob, was fragment.wesl's DOPPLER_STRENGTH const // offset 152 : emissionStrength f32 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission multiplier -// offset 156 : _pad4 f32 — T15 TEMP, pads emissionStrength up to emissionTint's 16-byte alignment +// offset 156 : edgeFadeEndRs f32 — escape fade's end impact parameter, r_s units (NOT a T15 knob: +// derived per frame by the layer — min(subpixel-deflection b, 0.6·camera +// distance), floored at lutMaxImpactParamRs; survives the T15 removal) // offset 160 : emissionTint vec3 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission tint // offset 172 : _pad5 f32 — T15 TEMP, rounds the struct to 176 / 16-byte // total: 176 bytes. @@ -71,7 +73,7 @@ struct SgrAStarLensingUniforms { edgeFadeStartFraction: f32, dopplerStrength: f32, emissionStrength: f32, - _pad4: f32, + edgeFadeEndRs: f32, emissionTint: vec3, _pad5: f32, }; diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index 0cadcbcefa..5f2cccbc62 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -36,7 +36,7 @@ * f32 36 (byte 144..147): edgeFadeStartFraction — T15 TEMP tuning knob * f32 37 (byte 148..151): dopplerStrength — T15 TEMP tuning knob * f32 38 (byte 152..155): emissionStrength — T15 TEMP tuning knob (2nd addendum) - * f32 39 (byte 156..159): untouched (zero) — pads emissionTint to 16-byte alignment + * f32 39 (byte 156..159): edgeFadeEndRs — per-frame derived (not a knob) * f32 40..42 (byte 160..171): emissionTint — T15 TEMP tuning knob (2nd addendum), vec3 * f32 43 (byte 172..175): untouched (zero) — struct's 16-byte round-up * @@ -69,6 +69,7 @@ * @param edgeFadeStartFraction T15 TEMP — escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. * @param dopplerStrength T15 TEMP — Doppler-beaming strength factor. * @param emissionStrength T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's output intensity. + * @param edgeFadeEndRs Escape fade's end impact parameter, r_s units — derived per frame by the layer. * @param emissionTint T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's per-sample tint. */ @@ -79,7 +80,7 @@ import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/ /** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (4 scalars + - * emissionTint's 3) + pad (2) = 44. */ + * emissionTint's 3) + edgeFadeEndRs + pad (1) = 44. */ export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 24; export function packSgrAStarLensingUniforms( @@ -102,6 +103,7 @@ export function packSgrAStarLensingUniforms( edgeFadeStartFraction: number, dopplerStrength: number, emissionStrength: number, + edgeFadeEndRs: number, emissionTint: Readonly, ): Float32Array { const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); @@ -125,7 +127,7 @@ export function packSgrAStarLensingUniforms( out[36] = edgeFadeStartFraction; // byte 144 — T15 TEMP out[37] = dopplerStrength; // byte 148 — T15 TEMP out[38] = emissionStrength; // byte 152 — T15 TEMP (2nd addendum) - // out[39] (byte 156..159) stays zero — pads emissionTint to 16-byte alignment. + out[39] = edgeFadeEndRs; // byte 156 — per-frame derived (not a knob) out[40] = emissionTint[0]; // byte 160 — T15 TEMP (2nd addendum), vec3 out[41] = emissionTint[1]; // byte 164 out[42] = emissionTint[2]; // byte 168 diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index 1200e2bccd..ed7b48f0b3 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -50,6 +50,7 @@ const DISK_SCALE_HEIGHT_RS = 0.8125; const EDGE_FADE_START_FRACTION = 0.65625; const DOPPLER_STRENGTH = 0.46875; const EMISSION_STRENGTH = 0.90625; +const EDGE_FADE_END_RS = 1875.5; const EMISSION_TINT: Vec3 = [801, 802, 803]; describe('SgrAStarLensingUniforms byte offsets', () => { @@ -74,6 +75,7 @@ describe('SgrAStarLensingUniforms byte offsets', () => { EDGE_FADE_START_FRACTION, DOPPLER_STRENGTH, EMISSION_STRENGTH, + EDGE_FADE_END_RS, EMISSION_TINT, ); @@ -119,8 +121,8 @@ describe('SgrAStarLensingUniforms byte offsets', () => { expect(rec[37]).toBe(DOPPLER_STRENGTH); // byte 148 expect(rec[38]).toBe(EMISSION_STRENGTH); // byte 152 - // Pad before emissionTint's 16-byte alignment — untouched, stays zero. - expect(rec[39]).toBe(0); // byte 156 + // edgeFadeEndRs — per-frame derived escape-fade end (not a T15 knob). + expect(rec[39]).toBe(EDGE_FADE_END_RS); // byte 156 // emissionTint — vec3 at byte 160 (float index 40). expect(rec[40]).toBe(EMISSION_TINT[0]); // byte 160 diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 5cf7a075d1..842c7d3736 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -115,6 +115,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const edgeFadeStartFraction = 702; const dopplerStrength = 703; const emissionStrength = 704; + const edgeFadeEndRs = 705; const emissionTint: Vec3 = [801, 802, 803]; const rec = packSgrAStarLensingUniforms( @@ -137,6 +138,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { edgeFadeStartFraction, dopplerStrength, emissionStrength, + edgeFadeEndRs, emissionTint, ); @@ -158,8 +160,9 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { edgeFadeStartFraction, dopplerStrength, emissionStrength, + edgeFadeEndRs, }; - const zeroPadFields = new Set(['_pad4', '_pad5']); + const zeroPadFields = new Set(['_pad5']); for (const field of layout) { if (field.lanes === 0) { diff --git a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts index 2b81149c69..a7da06fc59 100644 --- a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts +++ b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts @@ -73,6 +73,21 @@ describe('buildSchwarzschildDeflectionLut', () => { expect(lut.samples[belowCriticalIndex]).toBe(Infinity); }); + it('ends within a few percent above the analytic 2/b, so the shader 1/b tail is continuous', () => { + // The fragment extends the deflection beyond the LUT domain as + // endpoint · (bMax/b) — exactly continuous at the handoff by + // construction, and a valid ~1/b weak-field tail ONLY IF the endpoint + // itself sits just above the leading term 2/b (the next-order correction + // 15π/16 b² is +3.0% at b = 50). A drifted endpoint (bigger LUT domain, + // broken quadrature) would silently bend the tail; this pins the + // assumption the shader relies on. + const lut = buildSchwarzschildDeflectionLut(4096); + const endpoint = lut.samples[lut.samples.length - 1]!; + const leading = 2 / lut.maxImpactParamRs; + expect(endpoint).toBeGreaterThan(leading); + expect(endpoint).toBeLessThan(leading * 1.05); + }); + it('strictly decreases across the escaping (finite) branch as impact parameter grows', () => { // The sign/ordering check the two point-value tests above could miss: // a formula with e.g. a flipped sign would still hit isolated literals From 4ea8a0705606236b54562e175748d3aa137a23ad Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 20:45:51 +0200 Subject: [PATCH 41/60] fix(black-hole): slab candidacy spans the lens fade band, killing the pop-in The lens layer only draws once a body-m slab exists for sgr-a-star, and candidacy required the hole's own disc to clear the 1-px floor - at a dpr-2 1080p-class viewport that is ~346 AU, where bandAlpha is already ~0.4 (user observed the pop at 341 AU), and the threshold moves with viewport/ dpr. A band-bearing lens body's painted footprint is the quad (up to ~0.75x camera distance), not its r_s-scale disc, so visibleSlabBodies now keeps such a body - both culls bypassed - for the whole support of its SCALE_FADE_BANDS row (goneAt, 500 AU): the slab and the lens step are born exactly where alpha = 0 and onset rides the band ramp. Derivation in audit-cubemap-alignment.md section 8. Co-Authored-By: Claude Fable 5 --- .../engine/frame/visibleSlabBodies.ts | 29 +++++++++++++++++ .../engine/frame/visibleSlabBodies.test.ts | 32 +++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/src/services/engine/frame/visibleSlabBodies.ts b/src/services/engine/frame/visibleSlabBodies.ts index a51f666f07..0fa41f41ef 100644 --- a/src/services/engine/frame/visibleSlabBodies.ts +++ b/src/services/engine/frame/visibleSlabBodies.ts @@ -6,6 +6,25 @@ import { bodyDrawRadiusM } from '../../../utils/scene/bodyDrawRadiusM'; import { PROXY_SCALE } from '../../../utils/scene/proxyScale'; import { SCALE_UNITS } from '../../../data/scaleUnits'; import { SUB_PIXEL_BODY_CULL_PX } from './subPixelBodyCullPx'; +import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; +import { SGR_A_STAR } from '../../../data/bodies/sceneSgrAStar'; + +/** + * Slab-candidacy floor for a body whose PASS paints far beyond its own disc: + * the Sgr A* lens quad spans up to ~0.75× the camera distance (vertex.wesl's + * edgeFadeEndRs sizing), so both culls below — correct for a body that draws + * itself — would birth the lens mid-band (Sgr A*'s r_s-scale disc clears the + * 1-px floor only at ~346 AU on a dpr-2 1080p-class viewport, where + * bandAlpha is already ~0.4: a visible, viewport-dependent pop). Keyed to + * the SAME band row the layer's alpha reads, so the slab — and with it the + * lens step — is born exactly where alpha = 0 and onset rides the ramp. The + * frustum cull is skipped too: inside the band the lensed footprint can + * span most of the view, so no conservative disc-based cull is available, + * and one always-on slab row is negligible. + */ +const BAND_SLAB_FLOOR_MPC: ReadonlyMap = new Map([ + [SGR_A_STAR.id, SCALE_FADE_BANDS.sgrAStarLensing.goneAt], +]); /** * visibleSlabBodies — which of `bodies` get a body slab row this frame: @@ -54,6 +73,16 @@ export function visibleSlabBodies(input: { const state = bodyStates.get(body.id); if (state === undefined) return false; + // Band-bearing lens body: candidacy for the whole band support, both + // culls bypassed — see BAND_SLAB_FLOOR_MPC. + const bandFloorMpc = BAND_SLAB_FLOOR_MPC.get(body.id); + if (bandFloorMpc !== undefined) { + const bdx = state.positionMpc[0] - camPosMpc[0]; + const bdy = state.positionMpc[1] - camPosMpc[1]; + const bdz = state.positionMpc[2] - camPosMpc[2]; + if (Math.hypot(bdx, bdy, bdz) < bandFloorMpc) return true; + } + // The widest thing this row can draw — the same value the frustum cull // below needs, so both culls agree on the body's footprint (radar frame // finding 2: they used to disagree, body.radiusM here vs. this same diff --git a/tests/services/engine/frame/visibleSlabBodies.test.ts b/tests/services/engine/frame/visibleSlabBodies.test.ts index b17c58dc5b..c5cda26096 100644 --- a/tests/services/engine/frame/visibleSlabBodies.test.ts +++ b/tests/services/engine/frame/visibleSlabBodies.test.ts @@ -8,6 +8,7 @@ import { describe, it, expect } from 'vitest'; import { visibleSlabBodies } from '../../../../src/services/engine/frame/visibleSlabBodies'; import { SCENE_PLANETS } from '../../../../src/data/bodies/scenePlanets'; +import { SGR_A_STAR } from '../../../../src/data/bodies/sceneSgrAStar'; import { SCALE_UNITS } from '../../../../src/data/scaleUnits'; import { PROXY_SCALE } from '../../../../src/utils/scene/proxyScale'; import type { PlanetBody } from '../../../../src/@types/scene/PlanetBody'; @@ -246,4 +247,35 @@ describe('visibleSlabBodies', () => { expect(visible.map((body) => body.id)).toEqual(['visible-anchor']); }); + + it("keeps Sgr A* for its lens band's whole support, even sub-pixel and off-axis", () => { + // The lens pass's slab must be born where its fade band OPENS (alpha = 0, + // 500 AU), not where the hole's own r_s-scale disc clears the 1-px floor + // (~346 AU on a dpr-2 1080p-class viewport — bandAlpha already ~0.4 + // there: the pop this pins, audit-cubemap-alignment.md §8). Placed + // sub-pixel AND behind the camera: both culls must be bypassed inside + // the band, since the lensed footprint isn't the disc. + const sgrAStar = SGR_A_STAR; + const insideBandMpc = 400 * SCALE_UNITS.AU_TO_MPC; // < goneAt (500 AU) + const outsideBandMpc = 600 * SCALE_UNITS.AU_TO_MPC; // > goneAt + + for (const [distanceMpc, expected] of [ + [insideBandMpc, [SGR_A_STAR.id]], + [outsideBandMpc, []], + ] as const) { + const bodyStates = new Map([ + [SGR_A_STAR.id, makeState(offAxisPositionMpc(180, distanceMpc))], + ]); + const visible = visibleSlabBodies({ + bodies: [sgrAStar], + bodyStates, + camPosMpc: [0, 0, 0], + camForwardMpc: FORWARD_X, + viewportWidthPx: 1000, + viewportHeightPx: 1000, + fovYRad: Math.PI / 2, + }); + expect(visible.map((body) => body.id)).toEqual(expected); + } + }); }); From 760e72a412782e019acd69f70a563b09fa40dc4c Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 22:06:31 +0200 Subject: [PATCH 42/60] fix(black-hole): default the sky-cubemap knob to 1024, not 512 (T15) User judgment against the live view: 512 read as too little. Bumps DEFAULT_SGR_A_STAR_LENSING_TUNING.cubemapResolutionPx (data/defaults.ts) to 1024 and updates its doc comment plus the sky-cubemap row's option-set comment in renderTargets.ts. The knob itself still offers 256/512/1024/2048; no other file carries a competing literal (initialState.ts and makeSettingsFixture.ts both spread DEFAULT_SGR_A_STAR_LENSING_TUNING, and no test pins 512 as the default). Co-Authored-By: Claude Fable 5 --- src/data/defaults.ts | 7 ++++--- src/services/gpu/renderTargets.ts | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/data/defaults.ts b/src/data/defaults.ts index decc19b0b5..d449a56048 100644 --- a/src/data/defaults.ts +++ b/src/data/defaults.ts @@ -284,8 +284,9 @@ export const DEFAULT_ZONE_OF_AVOIDANCE_TUNING: ZoneOfAvoidanceTuning = { * brightness exactly. * * `cubemapResolutionPx` seeds the `sky-cubemap` render-target row's declared - * size (`renderTargets.ts`) — 512, the user's visual-tuning call bumping it - * off the original 256 (T15 addendum). + * size (`renderTargets.ts`) — 1024, per the user's live-view judgment against + * the T15 addendum's own prior bump (256 -> 512 -> 1024); the knob's option + * set stays 256/512/1024/2048. * * NOT here: `skyCubemapRecaptureCameraMoveFraction`. Its owner is * `skyCubemapCaptureSchedule.ts` (a `services/` module `data/` doesn't @@ -309,7 +310,7 @@ export const DEFAULT_SGR_A_STAR_LENSING_TUNING: Omit< dopplerStrength: 0.6, emissionStrength: 1, emissionTint: [1, 1, 1], - cubemapResolutionPx: 512, + cubemapResolutionPx: 1024, }; // ── HDR tone-mapping ──────────────────────────────────────────────────────── diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index ac7d0235b5..6274cbcecc 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -276,7 +276,7 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT scale: 1, // unused: fixedSizePx below overrides it (required by the type). clearValue: { r: 0, g: 0, b: 0, a: 0 }, // `size` is a live setting, TEMPORARILY (Task 15's DebugPanel resolution - // knob, 256/512/1024) — `reconcile` resolves it every frame exactly like + // knob, 256/512/1024/2048, default 1024) — `reconcile` resolves it every frame exactly like // `mw-aggregate`'s divisor, so dragging the knob reallocates this row // (and its cube/layer views) without a rebuild path of its own. fixedSizePx: { From 8ea6870110416eaab8139061b70519db0568fe0d Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 22:17:40 +0200 Subject: [PATCH 43/60] fix(black-hole): size the lens quad on the CPU in f64, killing the close-orbit shake Close to the hole the edge-fade end is floored at lutMax (50 r_s) >= the camera's distance in r_s, and vertex.wesl's f32 inversion of b = R*d/sqrt(R^2+d^2) bottomed out its 1e-6 discriminant floor - a 1e6-r_s quad at 20 r_s, whose 5e4x corner-to-centre varying ratio put ~3 mrad of barycentric interpolation noise on every reconstructed ray: sky and disc shaking together while orbiting (introduced by 576a636c9; the slab-candidacy fix is exonerated in the audit). The inversion now runs in f64 in lensQuadPlaneRadiusRs (new util), capped at 8x the anchor distance (atan(8) ~ 83 deg half-angle, past any viewport half-diagonal; cap reachable only where full coverage is geometrically impossible), and the finished radius rides the struct's last pad slot (quadPlaneRadiusRs, byte 172). Derivation in audit-cubemap-alignment.md section 9. Co-Authored-By: Claude Fable 5 --- .../frame/passes/sgrAStarLensingLayer.ts | 7 ++++ .../bodies/sgrAStarLensing/vertex.wesl | 17 +++----- .../gpu/shaders/lib/sgrAStarLensing.wesl | 6 ++- src/utils/gpu/packSgrAStarLensingUniforms.ts | 8 ++-- src/utils/lensing/lensQuadPlaneRadiusRs.ts | 26 ++++++++++++ .../gpu/packSgrAStarLensingUniforms.test.ts | 6 ++- ...rAStarLensingUniformsLayout.parity.test.ts | 7 +++- .../lensing/lensQuadPlaneRadiusRs.test.ts | 41 +++++++++++++++++++ 8 files changed, 98 insertions(+), 20 deletions(-) create mode 100644 src/utils/lensing/lensQuadPlaneRadiusRs.ts create mode 100644 tests/utils/lensing/lensQuadPlaneRadiusRs.test.ts diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 75aca4b0bd..985bffb079 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -25,6 +25,7 @@ import { SGR_A_STAR } from '../../../../data/bodies/sceneSgrAStar'; import { SGR_A_STAR_MASS_SOLAR } from '../../../../data/bodies/sgrAStarMassSolar'; import { schwarzschildRadiusM } from '../../../../utils/physics/schwarzschildRadiusM'; import { packSgrAStarLensingUniforms } from '../../../../utils/gpu/packSgrAStarLensingUniforms'; +import { lensQuadPlaneRadiusRs } from '../../../../utils/lensing/lensQuadPlaneRadiusRs'; import { regionById } from '../../../../utils/scene/regionById'; import { regionRelativeDistanceMpc } from '../../../../utils/scene/regionRelativeDistanceMpc'; import { sceneBodyStates } from '../sceneBodyStates'; @@ -119,6 +120,11 @@ export const sgrAStarLensingLayer: ContentLayer = { renderer.lut.maxImpactParamRs, Math.min(2 * ctx.drawPxPerRad, 0.6 * distRs), ); + // Billboard half-size in f64 HERE, not in the vertex shader: the f32 + // in-shader inversion degenerated close-in (edgeFadeEndRs >= distRs via + // the lutMax floor) into a ~5e4x-oversized quad whose varying + // interpolation shook every ray — see lensQuadPlaneRadiusRs's docblock. + const quadPlaneRadiusRs = lensQuadPlaneRadiusRs(edgeFadeEndRs, distRs); const uniforms = packSgrAStarLensingUniforms( view.vp, @@ -142,6 +148,7 @@ export const sgrAStarLensingLayer: ContentLayer = { tuning.emissionStrength, edgeFadeEndRs, tuning.emissionTint, + quadPlaneRadiusRs, ); const skyCubemapView = ctx.renderTargets.cubeViewOf('sky-cubemap'); diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl index 7ff8525654..6dce9f6f07 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl @@ -34,18 +34,11 @@ fn vs(@builtin(vertex_index) vi: u32) -> VsOut { let right = normalize(cross(worldUp, forward)); let up = cross(forward, right); - // Cover impact parameters out to the fragment's fade end: a fragment at - // plane radius R (anchor distance d) rides a ray with impact parameter - // b = R·d/sqrt(R^2 + d^2), so R = b·d/sqrt(d^2 - b^2). The layer caps - // 'edgeFadeEndRs' at 0.6·d (in r_s), bounding this stretch at 1.25 — but - // its lutMax floor can exceed d during a close descent, where the max() - // degenerates the sqrt and R blows up to an effectively fullscreen quad: - // exactly the right limit there (everything on screen is strongly lensed), - // clip does the bounding. - let dRs = anchorDistM / u.schwarzschildRadiusM; - let fadeEndRs = u.edgeFadeEndRs; - let planeRadiusRs = fadeEndRs * dRs / sqrt(max(dRs * dRs - fadeEndRs * fadeEndRs, 1e-6)); - let worldRadiusM = u.schwarzschildRadiusM * planeRadiusRs * BILLBOARD_MARGIN; + // Half-size arrives finished from the CPU ('lensQuadPlaneRadiusRs', f64, + // capped at 8x the anchor distance): the b = R·d/sqrt(R^2+d^2) inversion + // used to run here in f32 and degenerated close-in into a ~5e4x-oversized + // quad whose varying interpolation shook every ray (audit §9). + let worldRadiusM = u.schwarzschildRadiusM * u.quadPlaneRadiusRs * BILLBOARD_MARGIN; let corner = quadCorner(vi); let posRelCamM = toAnchor + right * (corner.x * worldRadiusM) + up * (corner.y * worldRadiusM); diff --git a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl index 36ec3e20d4..af6a343c38 100644 --- a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl +++ b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl @@ -35,7 +35,9 @@ // derived per frame by the layer — min(subpixel-deflection b, 0.6·camera // distance), floored at lutMaxImpactParamRs; survives the T15 removal) // offset 160 : emissionTint vec3 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission tint -// offset 172 : _pad5 f32 — T15 TEMP, rounds the struct to 176 / 16-byte +// offset 172 : quadPlaneRadiusRs f32 — lens billboard half-size, r_s units (NOT a T15 knob: derived per +// frame in f64 by the layer via 'lensQuadPlaneRadiusRs' — the in-shader +// f32 inversion shook close orbits; survives the T15 removal) // total: 176 bytes. // // The 12 scalar fields (80..127, 48 bytes) exactly fill the run up to 128, @@ -75,5 +77,5 @@ struct SgrAStarLensingUniforms { emissionStrength: f32, edgeFadeEndRs: f32, emissionTint: vec3, - _pad5: f32, + quadPlaneRadiusRs: f32, }; diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index 5f2cccbc62..621c10d7d8 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -38,7 +38,7 @@ * f32 38 (byte 152..155): emissionStrength — T15 TEMP tuning knob (2nd addendum) * f32 39 (byte 156..159): edgeFadeEndRs — per-frame derived (not a knob) * f32 40..42 (byte 160..171): emissionTint — T15 TEMP tuning knob (2nd addendum), vec3 - * f32 43 (byte 172..175): untouched (zero) — struct's 16-byte round-up + * f32 43 (byte 172..175): quadPlaneRadiusRs — per-frame derived (not a knob) * * Total: 176 bytes / 44 f32. The 12 scalars at f32 20..31 exactly fill the * run up to f32 32, so `anchorPosRelCamM` lands on a 16-byte boundary with @@ -71,6 +71,7 @@ * @param emissionStrength T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's output intensity. * @param edgeFadeEndRs Escape fade's end impact parameter, r_s units — derived per frame by the layer. * @param emissionTint T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's per-sample tint. + * @param quadPlaneRadiusRs Lens billboard half-size, r_s units — `lensQuadPlaneRadiusRs`, derived per frame. */ import type { Mat4 } from 'wgpu-matrix'; @@ -80,7 +81,7 @@ import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/ /** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (4 scalars + - * emissionTint's 3) + edgeFadeEndRs + pad (1) = 44. */ + * emissionTint's 3) + edgeFadeEndRs + quadPlaneRadiusRs = 44. */ export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 24; export function packSgrAStarLensingUniforms( @@ -105,6 +106,7 @@ export function packSgrAStarLensingUniforms( emissionStrength: number, edgeFadeEndRs: number, emissionTint: Readonly, + quadPlaneRadiusRs: number, ): Float32Array { const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); writeCameraPrefix(out, viewProj, viewportPx); // f32 0..17; 18..19 stay zero @@ -131,6 +133,6 @@ export function packSgrAStarLensingUniforms( out[40] = emissionTint[0]; // byte 160 — T15 TEMP (2nd addendum), vec3 out[41] = emissionTint[1]; // byte 164 out[42] = emissionTint[2]; // byte 168 - // out[43] (byte 172..175) stays zero — the struct's 16-byte round-up. + out[43] = quadPlaneRadiusRs; // byte 172 — per-frame derived (not a knob) return out; } diff --git a/src/utils/lensing/lensQuadPlaneRadiusRs.ts b/src/utils/lensing/lensQuadPlaneRadiusRs.ts new file mode 100644 index 0000000000..a2f2f3484c --- /dev/null +++ b/src/utils/lensing/lensQuadPlaneRadiusRs.ts @@ -0,0 +1,26 @@ +/** + * lensQuadPlaneRadiusRs — half-size (r_s units) of the camera-facing lens + * billboard that covers impact parameters out to `edgeFadeEndRs` at anchor + * distance `distRs`: a fragment at plane radius R rides a ray with + * b = R·d/√(R²+d²), inverted here as R = b·d/√(d²−b²). Once b approaches or + * exceeds d (the close-orbit regime, where the lutMax floor puts + * edgeFadeEndRs ≥ distRs) the inversion degenerates — no billboard covers the + * whole sky — and the shader that used to run this in f32 inflated the quad + * ~5e4× the anchor distance, whose varying interpolation put ~3 mrad of + * barycentric noise on every ray (the close-orbit shake, audit §9). Capped at + * QUAD_RADIUS_CAP·d (half-angle atan(8) ≈ 83°, past any viewport + * half-diagonal) and computed in f64 on the CPU, so the GPU only ever sees a + * finished, smooth radius. + */ + +/** Cap engages only when edgeFadeEndRs/distRs > 8/√65 ≈ 0.992 — reachable + * solely via the lutMax floor (distRs ≲ 50), where full fade coverage is + * impossible for any billboard anyway. */ +const QUAD_RADIUS_CAP = 8; + +export function lensQuadPlaneRadiusRs(edgeFadeEndRs: number, distRs: number): number { + const capRs = QUAD_RADIUS_CAP * distRs; + const discriminant = distRs * distRs - edgeFadeEndRs * edgeFadeEndRs; + if (discriminant <= 0) return capRs; + return Math.min((edgeFadeEndRs * distRs) / Math.sqrt(discriminant), capRs); +} diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index ed7b48f0b3..74c37df8b9 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -52,6 +52,7 @@ const DOPPLER_STRENGTH = 0.46875; const EMISSION_STRENGTH = 0.90625; const EDGE_FADE_END_RS = 1875.5; const EMISSION_TINT: Vec3 = [801, 802, 803]; +const QUAD_PLANE_RADIUS_RS = 2343.75; describe('SgrAStarLensingUniforms byte offsets', () => { it('packs a 176-byte / 44-f32 record with each field at its documented offset', () => { @@ -77,6 +78,7 @@ describe('SgrAStarLensingUniforms byte offsets', () => { EMISSION_STRENGTH, EDGE_FADE_END_RS, EMISSION_TINT, + QUAD_PLANE_RADIUS_RS, ); expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); @@ -129,7 +131,7 @@ describe('SgrAStarLensingUniforms byte offsets', () => { expect(rec[41]).toBe(EMISSION_TINT[1]); // byte 164 expect(rec[42]).toBe(EMISSION_TINT[2]); // byte 168 - // Trailing pad — rounds the struct to 176. Untouched, stays zero. - expect(rec[43]).toBe(0); // byte 172 + // quadPlaneRadiusRs — per-frame derived billboard half-size (not a knob). + expect(rec[43]).toBe(QUAD_PLANE_RADIUS_RS); // byte 172 }); }); diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 842c7d3736..63dbf8f438 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -116,6 +116,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const dopplerStrength = 703; const emissionStrength = 704; const edgeFadeEndRs = 705; + const quadPlaneRadiusRs = 706; const emissionTint: Vec3 = [801, 802, 803]; const rec = packSgrAStarLensingUniforms( @@ -140,6 +141,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { emissionStrength, edgeFadeEndRs, emissionTint, + quadPlaneRadiusRs, ); const vectorByField: Record = { anchorPosRelCamM, emissionTint }; @@ -161,8 +163,11 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { dopplerStrength, emissionStrength, edgeFadeEndRs, + quadPlaneRadiusRs, }; - const zeroPadFields = new Set(['_pad5']); + // No zero-pad fields remain past the cam prefix — every trailing slot is + // a real packed field now. + const zeroPadFields = new Set(); for (const field of layout) { if (field.lanes === 0) { diff --git a/tests/utils/lensing/lensQuadPlaneRadiusRs.test.ts b/tests/utils/lensing/lensQuadPlaneRadiusRs.test.ts new file mode 100644 index 0000000000..7bb640a300 --- /dev/null +++ b/tests/utils/lensing/lensQuadPlaneRadiusRs.test.ts @@ -0,0 +1,41 @@ +/** + * lensQuadPlaneRadiusRs — the lens billboard's covering radius must be exact + * where the inversion is well-conditioned, bounded in the degenerate + * close-orbit regime, and smooth everywhere in between (the close-orbit + * shake regression, audit-cubemap-alignment.md §9: the old in-shader f32 + * formula jumped to ~5e4× the anchor distance the moment + * edgeFadeEndRs ≥ distRs). + */ + +import { describe, it, expect } from 'vitest'; +import { lensQuadPlaneRadiusRs } from '../../../src/utils/lensing/lensQuadPlaneRadiusRs'; + +describe('lensQuadPlaneRadiusRs', () => { + it('inverts b = R·d/sqrt(R²+d²) exactly in the well-conditioned regime', () => { + // fadeEnd 2400 at d 4000 (the ~341 AU validation view): R = 2400·4000/3200. + const r = lensQuadPlaneRadiusRs(2400, 4000); + expect(r).toBeCloseTo(3000, 8); + // Round trip: the plane radius must map back to the requested b. + expect((r * 4000) / Math.hypot(r, 4000)).toBeCloseTo(2400, 6); + }); + + it('caps at 8× the anchor distance once coverage is geometrically impossible', () => { + // Close orbit: the lutMax floor puts fadeEnd (50) above distRs (20). The + // old shader formula returned ~1e6 r_s here — a 5e4× varying-magnitude + // ratio and visible per-frame shimmer. + expect(lensQuadPlaneRadiusRs(50, 20)).toBe(160); + expect(lensQuadPlaneRadiusRs(50, 50)).toBe(400); // discriminant exactly 0 + }); + + it('stays smooth through the coverable/degenerate crossover', () => { + // Sweep distRs across fadeEnd = 50 in fine steps: consecutive radii may + // differ by at most a small relative step — the revert (in-shader f32 + // formula with its 1e-6 floor) jumps ~3 orders of magnitude at d = 50. + let prev = lensQuadPlaneRadiusRs(50, 45); + for (let d = 45.001; d <= 60; d += 0.001) { + const r = lensQuadPlaneRadiusRs(50, d); + expect(Math.abs(r - prev) / prev).toBeLessThan(0.01); + prev = r; + } + }); +}); From 3654890446a8ea727d220c860b41157184bdfcc7 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 22:19:38 +0200 Subject: [PATCH 44/60] feat(camera): Sgr A* focus arrival lands at ~30.4 r_s, not screen-fill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds AnchorPointBody.focusDistanceRadii, a per-body override (mirroring standoffRadii) that lets focusFraming's body arm skip bodyFocusDistance's FOV-dependent screen-fill formula and land at a fixed radius multiple instead. Sgr A* is seeded at 30.4 r_s — the arrival distance the user framed live, well outside the 2 r_s descent floor and deep inside the lensing fade band. Co-Authored-By: Claude Fable 5 --- src/@types/engine/SelectionRow.d.ts | 4 ++++ src/@types/scene/AnchorPointBody.d.ts | 5 +++++ src/data/bodies/sceneSgrAStar.ts | 3 +++ src/services/engine/camera/bodyLikeFraming.ts | 17 +++++++++++++++-- src/services/engine/camera/focusFraming.ts | 6 ++++-- .../engine/helpers/extractSelectionRow.ts | 3 ++- .../engine/camera/focusFraming.test.ts | 18 ++++++++++++++++++ .../engine/helpers/extractSelectionRow.test.ts | 12 ++++++++++++ 8 files changed, 63 insertions(+), 5 deletions(-) diff --git a/src/@types/engine/SelectionRow.d.ts b/src/@types/engine/SelectionRow.d.ts index 90aade6093..d01f20393c 100644 --- a/src/@types/engine/SelectionRow.d.ts +++ b/src/@types/engine/SelectionRow.d.ts @@ -34,6 +34,10 @@ export type SelectionRow = // Carried through from `AnchorPointBody.standoffRadii` (e.g. Sgr A*'s // Q10 floor) — the zoom clamp reads it via `pivotFraming`. readonly standoffRadii?: number; + // Carried through from `AnchorPointBody.focusDistanceRadii` (e.g. Sgr + // A*'s ~30.4 r_s) — `focusFraming` reads it to override the default + // screen-fill arrival distance. + readonly focusDistanceRadii?: number; } // Star arm — the self-contained display projection of a picked star, its // physical fields (`positionMpc`/`absMag`/`bpRp`) snapshotted off the loaded diff --git a/src/@types/scene/AnchorPointBody.d.ts b/src/@types/scene/AnchorPointBody.d.ts index 723b82d360..0c7f40a3e5 100644 --- a/src/@types/scene/AnchorPointBody.d.ts +++ b/src/@types/scene/AnchorPointBody.d.ts @@ -21,4 +21,9 @@ export type AnchorPointBody = { readonly radiusM: number; /** Per-body override of `clampDistance`'s Earth-tuned `SURFACE_STANDOFF_RADII` — e.g. Sgr A*'s Q10 floor of 2 r_s. */ readonly standoffRadii?: number; + /** + * Per-body override of `bodyFocusDistance`'s screen-fill arrival distance, as + * a multiple of `radiusM` — e.g. Sgr A*'s ~30.4 r_s. See `focusFraming`. + */ + readonly focusDistanceRadii?: number; }; diff --git a/src/data/bodies/sceneSgrAStar.ts b/src/data/bodies/sceneSgrAStar.ts index ed36f05685..6866e04a4e 100644 --- a/src/data/bodies/sceneSgrAStar.ts +++ b/src/data/bodies/sceneSgrAStar.ts @@ -43,6 +43,9 @@ export const SGR_A_STAR: AnchorPointBody = { // Q10's descent floor: the camera may approach to 2 r_s, well inside the // Earth-tuned global SURFACE_STANDOFF_RADII (~1.0000024). standoffRadii: 2.0, + // Arrival distance the user framed live (2026-09-01): ~30.4 r_s, well + // outside the descent floor above and deep inside the lensing fade band. + focusDistanceRadii: 30.4, }; export const SGR_A_STAR_ANCHOR: AnchorBody = { diff --git a/src/services/engine/camera/bodyLikeFraming.ts b/src/services/engine/camera/bodyLikeFraming.ts index ceff799a06..1779316709 100644 --- a/src/services/engine/camera/bodyLikeFraming.ts +++ b/src/services/engine/camera/bodyLikeFraming.ts @@ -16,6 +16,11 @@ * and it is derived from this same radius (clampDistance.ts stands off * `SURFACE_STANDOFF_RADII` from the pivot's surface), so the framing distance is * always comfortably reachable — the fill factor puts it several radii out. + * + * `focusDistanceRadii`, when a caller passes it (`AnchorPointBody`'s optional + * field), overrides the screen-fill formula with a fixed multiple of the + * radius instead — Sgr A*'s arrival distance is an r_s count the user framed + * live, not a FOV-dependent viewport fraction. */ import { bodyFocusDistance } from './bodyFocusDistance'; @@ -23,11 +28,19 @@ import { SCALE_UNITS } from '../../../data/scaleUnits'; import type { Vec3 } from '../../../@types/math/Vec3'; import type { FocusFraming } from './focusFraming'; -export function bodyLikeFraming(positionMpc: Vec3, radiusM: number, fovYRad: number): FocusFraming { +export function bodyLikeFraming( + positionMpc: Vec3, + radiusM: number, + fovYRad: number, + focusDistanceRadii?: number, +): FocusFraming { const radiusMpc = radiusM * SCALE_UNITS.M_TO_MPC; return { target: [positionMpc[0], positionMpc[1], positionMpc[2]], - distance: bodyFocusDistance(radiusMpc, fovYRad), + distance: + focusDistanceRadii !== undefined + ? radiusMpc * focusDistanceRadii + : bodyFocusDistance(radiusMpc, fovYRad), // A discrete object like a galaxy — its physical radius is a real pass-by // extent for flyPath's offset geometry. radius: radiusMpc, diff --git a/src/services/engine/camera/focusFraming.ts b/src/services/engine/camera/focusFraming.ts index bcc157399b..297364f6fe 100644 --- a/src/services/engine/camera/focusFraming.ts +++ b/src/services/engine/camera/focusFraming.ts @@ -27,7 +27,9 @@ * math, because at ~2e-16 Mpc (Earth) any Mpc-scale floor would swallow the * framing. `radius` is the physical radius, a real pass-by extent. Their row * shapes differ (body: id/label; star: index/photometry + a nominal solar - * radius, the bin having no per-star size), so the cases stay separate. + * radius, the bin having no per-star size), so the cases stay separate. A + * body row's optional `focusDistanceRadii` (e.g. Sgr A*'s ~30.4 r_s) + * overrides the screen-fill distance with a fixed radius multiple. * * The return type is `Pick` plus the subject's * pass-by `radius` (Mpc) — the position-and-depth slice, with the extent a fly-past @@ -104,7 +106,7 @@ export function focusFraming(row: SelectionRow, fovYRad: number): FocusFraming { // to the shared bodyLikeFraming; the star's radius is the extractor-stamped // nominal solar radius (the bin has no per-star size). case 'body': - return bodyLikeFraming(row.positionMpc, row.radiusM, fovYRad); + return bodyLikeFraming(row.positionMpc, row.radiusM, fovYRad, row.focusDistanceRadii); case 'star': return bodyLikeFraming(row.positionMpc, row.radiusM, fovYRad); // The band carries no x/y/z (a line-of-sight effect, not a point), so it diff --git a/src/services/engine/helpers/extractSelectionRow.ts b/src/services/engine/helpers/extractSelectionRow.ts index d17b98d23c..6257e3d06d 100644 --- a/src/services/engine/helpers/extractSelectionRow.ts +++ b/src/services/engine/helpers/extractSelectionRow.ts @@ -60,8 +60,9 @@ const EXTRACT_ROW: { label: body.label, positionMpc: [p[0], p[1], p[2]], radiusM: body.radiusM, - // Only the AnchorPointBody arm of the SceneBody union carries this field. + // Only the AnchorPointBody arm of the SceneBody union carries these fields. standoffRadii: 'standoffRadii' in body ? body.standoffRadii : undefined, + focusDistanceRadii: 'focusDistanceRadii' in body ? body.focusDistanceRadii : undefined, }; }, // The star's physical fields are resolved off the LIVE catalog through the diff --git a/tests/services/engine/camera/focusFraming.test.ts b/tests/services/engine/camera/focusFraming.test.ts index a2e07c69b6..320135b38d 100644 --- a/tests/services/engine/camera/focusFraming.test.ts +++ b/tests/services/engine/camera/focusFraming.test.ts @@ -150,6 +150,24 @@ describe('focusFraming', () => { expect(result.radius).toBeCloseTo(EARTH_RADIUS_M * SCALE_UNITS.M_TO_MPC, 20); }); + it('body arm — focusDistanceRadii override lands at a fixed radius multiple, bypassing screen-fill', () => { + // Sgr A*'s arrival distance is an r_s count the user framed live, not a + // FOV-dependent viewport fraction — this pins that the override replaces + // bodyFocusDistance's tan(fovY/2) math rather than merely scaling it. + const radiusMpc = EARTH_RADIUS_M * SCALE_UNITS.M_TO_MPC; + const row = bodyRow({ focusDistanceRadii: 30.4 }); + const result = focusFraming(row, FOVY); + expect(result.distance).toBe(radiusMpc * 30.4); + expect(result.distance).not.toBe(bodyFocusDistance(radiusMpc, FOVY)); + }); + + it('body arm — focusDistanceRadii override is independent of FOV', () => { + const row = bodyRow({ focusDistanceRadii: 30.4 }); + const atFovA = focusFraming(row, 0.5).distance; + const atFovB = focusFraming(row, 1.4).distance; + expect(atFovA).toBe(atFovB); + }); + it('body arm — target is a fresh array, not aliased from positionMpc', () => { const row = bodyRow(); const result = focusFraming(row, FOVY); diff --git a/tests/services/engine/helpers/extractSelectionRow.test.ts b/tests/services/engine/helpers/extractSelectionRow.test.ts index 9d535d20e9..ad9e156dab 100644 --- a/tests/services/engine/helpers/extractSelectionRow.test.ts +++ b/tests/services/engine/helpers/extractSelectionRow.test.ts @@ -143,6 +143,18 @@ describe('extractSelectionRow', () => { expect(SGR_A_STAR.standoffRadii).toBe(2.0); // guards against both sides drifting to `undefined` }); + it('body ref for Sgr A* carries its focusDistanceRadii override through', () => { + // Same regression shape as the standoffRadii guard above, for the + // arrival-distance override: a typo'd property name or a reversed + // `'focusDistanceRadii' in body` condition would silently drop the user's + // framed ~30.4 r_s arrival distance while the rest of the suite stays green. + const row = extractSelectionRow({ type: 'body', id: SGR_A_STAR.id }, deps, SIM_DAYS); + expect(row !== null && row.type === 'body' && row.focusDistanceRadii).toBe( + SGR_A_STAR.focusDistanceRadii, + ); + expect(SGR_A_STAR.focusDistanceRadii).toBe(30.4); // guards against drift to `undefined` + }); + it('body ref resolves the position at the PASSED simDays, not a fixed epoch', () => { // The whole point of the fix: two different simDays for the same orbiting // body must yield two different positions, sourced from deriveBodyStates at From 2c63b9a34859a0edcc52f5ec879177f1eb230392 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 22:22:12 +0200 Subject: [PATCH 45/60] fix(black-hole): flag textured-disks into the sky-cubemap capture roster MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit LMC/SMC/Andromeda draw as textured famous-galaxy thumbnails (texturedDisksLayer), but the roster never included them, so the captured cubemap lacked those galaxies and the lens quad covered the real originals with an incomplete capture. Flags texturedDisksLayer skyCapture: true. Its shared instancedQuadRenderer factory wrote one shared @group(0) camera uniform per draw() call — a capture sweep's several calls (different faces, one submit) would have raced on it, so the factory gains an opt-in per-view-slot buffer+bindGroup ring (InstancedQuadConfig.viewSlotCount, default 1, every other consumer unchanged) that texturedDiskRenderer opts into. The instance buffer itself needs no ring: the disk list is computed once per frame from the real camera, upstream of the capture sweep, so every call re-uploads identical bytes. Co-Authored-By: Claude Fable 5 --- src/@types/rendering/InstancedQuadConfig.d.ts | 26 +++++ .../rendering/InstancedQuadRenderer.d.ts | 8 ++ .../rendering/TexturedDiskRenderer.d.ts | 9 ++ src/services/engine/frame/frameProgram.ts | 18 +-- .../engine/frame/passes/texturedDisksLayer.ts | 21 +++- .../galaxyCatalog/instancedQuadRenderer.ts | 89 +++++++++------ .../galaxyCatalog/texturedDiskRenderer.ts | 7 ++ .../frame/passes/texturedDisksLayer.test.ts | 22 ++++ .../instancedQuadRenderer.test.ts | 103 ++++++++++++++++++ .../texturedDiskRenderer.test.ts | 95 ++++++++++++++++ tests/visual/renderFrameSplitBaseline.test.ts | 2 +- 11 files changed, 357 insertions(+), 43 deletions(-) diff --git a/src/@types/rendering/InstancedQuadConfig.d.ts b/src/@types/rendering/InstancedQuadConfig.d.ts index 299d83d7b6..e34a32ca50 100644 --- a/src/@types/rendering/InstancedQuadConfig.d.ts +++ b/src/@types/rendering/InstancedQuadConfig.d.ts @@ -47,4 +47,30 @@ export type InstancedQuadConfig = { * flag is preserved as-is to avoid silently changing the * pipeline-layout introspection signature. */ uniformVisibility?: GPUShaderStageFlags; + /** + * Number of physical `@group(0)` buffer+bindGroup copies to allocate, + * indexed by `draw()`'s `viewSlot` arg. Defaults to 1 (single shared + * buffer, `viewSlot` ignored) — every consumer except TexturedDiskRenderer. + * + * TexturedDiskRenderer passes `VIEW_SLOT_COUNT` (Task 13b, Ruling 6): its + * consumer, `texturedDisksLayer`, is on the black-hole lens's sky-cubemap + * capture roster, whose several `draw()` calls (one per captured face, one + * for the real view, all before one `submit()`) each carry a DIFFERENT + * `viewProj`/`viewport`/`camPos`. A single shared `@group(0)` buffer would + * keep only the last call's bytes at `submit()` time — the same + * writeBuffer/submit race `createViewSlotUniformRing` closes for the other + * roster renderers. This factory's `@group(0)` also carries the atlas/ + * hi-res-array bindings (unlike the pure-uniform BGLs those renderers + * ring), so it rolls its own per-slot buffer+bindGroup array rather than + * reusing that ring directly — see `instancedQuadRenderer.ts`'s doc. + * + * The instance buffer (the disk list itself) is NOT ringed: `disks` is + * computed once per frame from the real camera, upstream of the capture + * sweep (`diskPlannerWalk.runFrame`, before `executeFrame`), so every + * `draw()` call this frame re-uploads byte-identical instance bytes — + * repeated identical writes commute, so one shared instance buffer is + * correct (same reasoning `starCatalogRenderer` uses for its per-frame- + * constant camera-scalar writes). + */ + viewSlotCount?: number; }; diff --git a/src/@types/rendering/InstancedQuadRenderer.d.ts b/src/@types/rendering/InstancedQuadRenderer.d.ts index 8944984600..70e1c58462 100644 --- a/src/@types/rendering/InstancedQuadRenderer.d.ts +++ b/src/@types/rendering/InstancedQuadRenderer.d.ts @@ -51,6 +51,14 @@ export type InstancedQuadRenderer = { * the engine against the canonical focusBgl and written once per frame; * the same group serves every impostor pipeline. */ focusBindGroup: GPUBindGroup; + /** + * Which `@group(0)` buffer+bindGroup copy this call writes/binds. + * Defaults to 0. Only meaningful when `config.viewSlotCount > 1` + * (TexturedDiskRenderer, Task 13b) — every other consumer omits it and + * always uses the single slot-0 copy, byte-identical to pre-Task-13b + * behaviour. + */ + viewSlot?: number; }) => void; /** * Release the GPU buffers this factory owns: the uniform buffer diff --git a/src/@types/rendering/TexturedDiskRenderer.d.ts b/src/@types/rendering/TexturedDiskRenderer.d.ts index 8fd13ddd69..1a0a45c47e 100644 --- a/src/@types/rendering/TexturedDiskRenderer.d.ts +++ b/src/@types/rendering/TexturedDiskRenderer.d.ts @@ -47,6 +47,15 @@ export type TexturedDiskRenderer = { camPos: Readonly, focusBindGroup: GPUBindGroup, instances: ReadonlyArray, + /** + * Which `@group(0)` buffer+bindGroup copy this call writes/binds. + * Defaults to 0 (the main view). `texturedDisksLayer` is on the + * black-hole lens's sky-cubemap capture roster (Task 13b, Ruling 6) and + * forwards `ReadyFrameContext.viewSlot`, so a capture sweep's several + * `draw()` calls in the same frame (different faces, one submit) each + * land in their OWN physical buffer instead of racing on a shared one. + */ + viewSlot?: number, ): void; /** * Release every GPU buffer this renderer owns. Idempotent. diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index 7d817da8fc..107d2100b8 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -120,15 +120,15 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * a same-frame lensing draw (Task 13) can sample a cubemap this frame * actually wrote. TWO steps per requested face — COSMO then NEAR0 — because * the fixed opt-in roster (`ContentLayer.skyCapture`, Ruling 6) spans both - * slabs: `point-sprites` projects through COSMO, `star-catalog` / - * `star-aggregates` / `star-points` through NEAR0. A capture step selects - * its group by the flag rather than by `target` (`executeFrame`'s - * capture-step branch), but `slab` still gates normally — one step per slab - * is what makes BOTH halves of the roster reachable (Task 13b; a single - * NEAR0-only step left the COSMO half permanently unselected, the flag - * having no effect). Order (COSMO before NEAR0) mirrors the real `(hdr, - * COSMO)` → `(hdr, NEAR0)` sequence below, so the capture composites in the - * same order the live frame would. + * slabs: `point-sprites` / `textured-disks` project through COSMO; + * `star-catalog` / `star-aggregates` / `star-points` through NEAR0. A + * capture step selects its group by the flag rather than by `target` + * (`executeFrame`'s capture-step branch), but `slab` still gates normally — + * one step per slab is what makes BOTH halves of the roster reachable + * (Task 13b; a single NEAR0-only step left the COSMO half permanently + * unselected, the flag having no effect). Order (COSMO before NEAR0) + * mirrors the real `(hdr, COSMO)` → `(hdr, NEAR0)` sequence below, so the + * capture composites in the same order the live frame would. * * `sgrAStarLensingBodySlabs` (Task 14, Ruling 8) is the black-hole lens's OWN * missing step: no step here ever matched `sgrAStarLensingLayer` (`slab: diff --git a/src/services/engine/frame/passes/texturedDisksLayer.ts b/src/services/engine/frame/passes/texturedDisksLayer.ts index 93839a5a0c..2c7a90e23b 100644 --- a/src/services/engine/frame/passes/texturedDisksLayer.ts +++ b/src/services/engine/frame/passes/texturedDisksLayer.ts @@ -13,6 +13,23 @@ * `state.gpu.texturedDiskRenderer` is nullable pre-bootstrap (like every * GPU handle on `state.gpu`); `enabled` doesn't check it, so `draw` guards * defensively — same pattern as `filamentsLayer.draw`. + * + * ### Sky-cubemap capture roster (Task 13b, Ruling 6) + * + * The textured famous-galaxy thumbnails (LMC/SMC/M31 at close approach) are + * part of the black-hole lens's captured "sky" — without this flag the + * cubemap lacked them, so the lens quad covered the real, textured originals + * with a capture that never had them in the first place. Draw-safe against a + * synthetic per-face ctx: `disks` is computed ONCE per frame from the REAL + * camera, upstream of the capture sweep (`diskPlannerWalk.runFrame`, before + * `renderFrame`/`executeFrame` run) — so a capture face's synthetic ctx can + * never cull a galaxy the real observer's apparent-size/distance gates + * already admitted, and `disks` is the same list for every draw() call this + * frame. `ctx.viewSlot` forwards to `texturedDiskRenderer.draw` so each + * call's `@group(0)` camera uniform lands in its own physical buffer + * (`instancedQuadRenderer.ts`'s `viewSlotCount` ring) instead of racing on a + * shared one — the instance buffer itself needs no such ring, since every + * call this frame re-uploads the same byte-identical `disks` list. */ import type { ContentLayer } from '../../../../@types/engine/frame/ContentLayer'; @@ -23,13 +40,14 @@ export const texturedDisksLayer: ContentLayer = { slab: COSMO, target: 'hdr', blend: 'additive', + skyCapture: true, enabled(state, _ctx, _view) { if (!state.settings.thumbnails.enabled) return false; if (state.subsystems.texturedDisks === null) return false; return state.subsystems.texturedDisks.lastOutput.disks.length > 0; }, - draw(pass, view, _ctx, state) { + draw(pass, view, ctx, state) { const subsys = state.subsystems.texturedDisks; if (subsys === null) return; const { disks } = subsys.lastOutput; @@ -42,6 +60,7 @@ export const texturedDisksLayer: ContentLayer = { view.camPos, state.gpu.focusUniform!.bindGroup, disks, + ctx.viewSlot, ); }, }; diff --git a/src/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.ts b/src/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.ts index 2a45962589..3b8cf24d83 100644 --- a/src/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.ts +++ b/src/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.ts @@ -118,6 +118,7 @@ export function createInstancedQuadRenderer( targetFormat, focusBgl, uniformVisibility = GPUShaderStage.VERTEX, + viewSlotCount = 1, } = config; // ── Bind group layout ────────────────────────────────────────────── @@ -206,11 +207,17 @@ export function createInstancedQuadRenderer( primitive: { topology: 'triangle-list' }, }); - const uniformBuffer = device.createBuffer({ - label: `${label}-uniforms`, - size: UNIFORM_BYTES, - usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, - }); + // One `@group(0)` buffer per view slot (default 1 — see `viewSlotCount`'s + // doc on `InstancedQuadConfig`). Slot 0 keeps the original `${label}-uniforms` + // label so devtools output is unchanged for every consumer that never + // multiplexes; only extra slots (TexturedDiskRenderer) get a `-slotN` suffix. + const uniformBuffers: GPUBuffer[] = Array.from({ length: viewSlotCount }, (_, slot) => + device.createBuffer({ + label: slot === 0 ? `${label}-uniforms` : `${label}-uniforms-slot${slot}`, + size: UNIFORM_BYTES, + usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, + }), + ); // Bilinear + clamp-to-edge by default; consumers can override via // 'atlas.samplerDescriptor'. @@ -241,17 +248,19 @@ export function createInstancedQuadRenderer( }) : undefined; - // Without atlas: build the 1-binding bind group eagerly. With atlas: - // leave it undefined until 'bindAtlas' is called — 'draw' no-ops - // until then, which is the expected interim state during engine - // startup before the atlas texture exists. - let bindGroup: GPUBindGroup | undefined; + // Without atlas: build the 1-binding bind group eagerly, one per view + // slot. With atlas: leave every slot undefined until 'bindAtlas' is + // called — 'draw' no-ops until then, which is the expected interim state + // during engine startup before the atlas texture exists. + const bindGroups: (GPUBindGroup | undefined)[] = new Array(viewSlotCount).fill(undefined); if (atlas === undefined) { - bindGroup = device.createBindGroup({ - label: `${label}-bg`, - layout: bindGroupLayout, - entries: [{ binding: 0, resource: { buffer: uniformBuffer } }], - }); + for (let slot = 0; slot < viewSlotCount; slot++) { + bindGroups[slot] = device.createBindGroup({ + label: slot === 0 ? `${label}-bg` : `${label}-bg-slot${slot}`, + layout: bindGroupLayout, + entries: [{ binding: 0, resource: { buffer: uniformBuffers[slot]! } }], + }); + } } // 'fixed': preallocated up front. 'grow': null until first non-empty @@ -283,26 +292,32 @@ export function createInstancedQuadRenderer( let lastHiResView: GPUTextureView | undefined; let lastHiResSampler: GPUSampler | undefined; + // Atlas + hi-res-array views are shared across every view slot (one atlas + // texture, uploaded once); only the @group(0) uniform buffer differs per + // slot. So recomposing on bind rebuilds all `viewSlotCount` bind groups, + // each pairing the shared atlas resources with ITS OWN uniform buffer. function composeAtlasBindGroup(): void { if (!lastAtlasView) return; // atlas not bound yet — keep no-op if (atlas?.hiResArray && !lastHiResView) return; // hi-res not bound yet - const entries: GPUBindGroupEntry[] = [ - { binding: 0, resource: { buffer: uniformBuffer } }, - { binding: 1, resource: lastAtlasView }, - { binding: 2, resource: sampler! }, - ]; - if (atlas?.hiResArray) { - entries.push( - { binding: 3, resource: lastHiResView! }, - { binding: 4, resource: lastHiResSampler ?? defaultHiResSampler! }, - ); + for (let slot = 0; slot < viewSlotCount; slot++) { + const entries: GPUBindGroupEntry[] = [ + { binding: 0, resource: { buffer: uniformBuffers[slot]! } }, + { binding: 1, resource: lastAtlasView }, + { binding: 2, resource: sampler! }, + ]; + if (atlas?.hiResArray) { + entries.push( + { binding: 3, resource: lastHiResView! }, + { binding: 4, resource: lastHiResSampler ?? defaultHiResSampler! }, + ); + } + bindGroups[slot] = device.createBindGroup({ + label: slot === 0 ? `${label}-bg` : `${label}-bg-slot${slot}`, + layout: bindGroupLayout, + entries, + }); } - bindGroup = device.createBindGroup({ - label: `${label}-bg`, - layout: bindGroupLayout, - entries, - }); } function bindAtlas(atlasView: GPUTextureView): void { @@ -329,8 +344,13 @@ export function createInstancedQuadRenderer( * the engine against the canonical focusBgl; the same group serves * every impostor pipeline. */ focusBindGroup: GPUBindGroup; + /** Which @group(0) copy this call targets. Defaults to 0 — see + * `InstancedQuadConfig.viewSlotCount`'s doc. */ + viewSlot?: number; }): void { if (args.instanceCount === 0) return; + const viewSlot = args.viewSlot ?? 0; + const bindGroup = bindGroups[viewSlot]; if (!bindGroup) return; // atlas-capable renderer with no atlas bound yet // ── Grow instance buffer if needed (grow strategy only) ───────── @@ -362,7 +382,12 @@ export function createInstancedQuadRenderer( uniformScratch[21] = args.camPosWorld?.[1] ?? 0; uniformScratch[22] = args.camPosWorld?.[2] ?? 0; uniformScratch[23] = args.pxPerRad ?? 0; - device.queue.writeBuffer(uniformBuffer, 0, uniformScratch); + // THIS call's own slot's buffer — a sky-cubemap capture sweep's several + // `draw()` calls (different faces, one submit) each carry a different + // viewProj/viewport/camPos, so a shared buffer would keep only the last + // call's bytes at submit time (see `InstancedQuadConfig.viewSlotCount`'s + // doc / docs/RENDERER.md landmine #1). + device.queue.writeBuffer(uniformBuffers[viewSlot]!, 0, uniformScratch); // Forward the exact byte count, not 'instanceBytes.byteLength' — // an oversized consumer scratch buffer must not write past the @@ -383,7 +408,7 @@ export function createInstancedQuadRenderer( } function destroy(): void { - uniformBuffer.destroy(); + for (const buffer of uniformBuffers) buffer.destroy(); instanceBuffer?.destroy(); instanceBuffer = null; } diff --git a/src/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.ts b/src/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.ts index e21bf37f87..3a9add0295 100644 --- a/src/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.ts +++ b/src/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.ts @@ -45,6 +45,7 @@ import type { FocusUniformsBgl } from '../../../../@types/rendering/FocusUniform import vsCode from '../../shaders/galaxyCatalog/texturedDisks/vertex.wesl?static'; import fsCode from '../../shaders/galaxyCatalog/texturedDisks/fragment.wesl?static'; import { FLOATS_PER_INSTANCE, createInstancedQuadRenderer } from './instancedQuadRenderer'; +import { VIEW_SLOT_COUNT } from '../../../../utils/gpu/createViewSlotUniformRing'; type Init = { device: GPUDevice; @@ -80,6 +81,10 @@ export function createTexturedDiskRenderer( // fade-to-black at thumbnail edges. blend: 'additive', targetFormat: init.targetFormat, + // Sky-cubemap capture roster (Task 13b, Ruling 6): texturedDisksLayer's + // draw() calls span the main view plus up to 6 captured faces, all + // before one submit() — see `InstancedQuadConfig.viewSlotCount`'s doc. + viewSlotCount: VIEW_SLOT_COUNT, }); function bindAtlas(atlasView: GPUTextureView): void { @@ -102,6 +107,7 @@ export function createTexturedDiskRenderer( camPos: Readonly, focusBindGroup: GPUBindGroup, instances: ReadonlyArray, + viewSlot = 0, ): void { if (instances.length === 0) return; @@ -143,6 +149,7 @@ export function createTexturedDiskRenderer( focusBindGroup, // pxPerRad omitted — the disk geometry sizes itself in world // space, so the trailing uniform slot stays zero-padded. + viewSlot, }); } diff --git a/tests/services/engine/frame/passes/texturedDisksLayer.test.ts b/tests/services/engine/frame/passes/texturedDisksLayer.test.ts index 9716499628..ad44fc1b24 100644 --- a/tests/services/engine/frame/passes/texturedDisksLayer.test.ts +++ b/tests/services/engine/frame/passes/texturedDisksLayer.test.ts @@ -141,4 +141,26 @@ describe('texturedDisksLayer', () => { texturedDisksLayer.draw({} as GPURenderPassEncoder, makeView(ctx), ctx, state), ).not.toThrow(); }); + + // Sky-cubemap capture roster (Task 13b, Ruling 6): the textured famous- + // galaxy thumbnails (LMC/SMC/M31 at close approach) were missing from the + // captured "sky", so the black-hole lens quad covered the real, textured + // originals with a capture that never had them. + it('is flagged skyCapture: true', () => { + expect(texturedDisksLayer.skyCapture).toBe(true); + }); + + it('draw() forwards ctx.viewSlot to texturedDiskRenderer.draw as the 7th arg', () => { + const disks = [{ x: 1 }]; + const texturedDiskRenderer = makeTexturedDiskRenderer(); + const state = { + subsystems: { texturedDisks: { lastOutput: { disks } } }, + gpu: { focusUniform: { bindGroup: {} as GPUBindGroup }, texturedDiskRenderer }, + } as unknown as EngineState; + const ctx = { ...makeCtx(), viewSlot: 3 }; + texturedDisksLayer.draw({} as GPURenderPassEncoder, makeView(ctx), ctx, state); + expect(texturedDiskRenderer.draw).toHaveBeenCalledTimes(1); + const call = texturedDiskRenderer.draw.mock.calls[0]!; + expect(call[6]).toBe(3); + }); }); diff --git a/tests/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.test.ts b/tests/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.test.ts index af7ab263c0..0c9707e874 100644 --- a/tests/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.test.ts +++ b/tests/services/gpu/renderers/galaxyCatalog/instancedQuadRenderer.test.ts @@ -654,6 +654,109 @@ describe('createInstancedQuadRenderer', () => { }); }); + describe('viewSlotCount (Task 13b)', () => { + it('defaults to a single @group(0) buffer+bindGroup — createBuffer count unchanged for existing consumers', () => { + const { ctx, calls } = makeStubContext(); + createInstancedQuadRenderer(ctx.device, { + focusBgl: FOCUS_BGL, + label: 'test', + vertexSource: '@vertex fn vs() {}', + fragmentSource: '@fragment fn fs() {}', + atlas: {}, + capacity: { kind: 'fixed', max: 16 }, + blend: 'additive', + targetFormat: 'rgba16float', + }); + // Uniform (1) + instance (1) = 2 — same count as before this option + // existed, since `viewSlotCount` defaults to 1. + expect(calls.createBuffer).toHaveLength(2); + expect(calls.createBindGroup).toHaveLength(0); // atlas-capable: deferred + }); + + it('allocates one @group(0) buffer per slot when viewSlotCount > 1', () => { + const { ctx, calls } = makeStubContext(); + createInstancedQuadRenderer(ctx.device, { + focusBgl: FOCUS_BGL, + label: 'test', + vertexSource: '@vertex fn vs() {}', + fragmentSource: '@fragment fn fs() {}', + capacity: { kind: 'grow' }, + blend: 'additive', + targetFormat: 'rgba16float', + viewSlotCount: 3, + }); + // No atlas: 3 uniform buffers, eagerly bound bind groups, no instance + // buffer yet (grow strategy). + expect(calls.createBuffer).toHaveLength(3); + for (const desc of calls.createBuffer) { + expect(desc.size).toBe(UNIFORM_BYTES); + } + expect(calls.createBindGroup).toHaveLength(3); + }); + + it('two draw() calls with different viewSlot write into DIFFERENT physical buffers — the writeBuffer/submit race this closes', () => { + const { ctx, calls } = makeStubContext(); + const writeBufferSpy = ( + ctx.device as unknown as { queue: { writeBuffer: ReturnType } } + ).queue.writeBuffer; + const r = createInstancedQuadRenderer(ctx.device, { + focusBgl: FOCUS_BGL, + label: 'test', + vertexSource: '@vertex fn vs() {}', + fragmentSource: '@fragment fn fs() {}', + capacity: { kind: 'grow' }, + blend: 'additive', + targetFormat: 'rgba16float', + viewSlotCount: 3, + }); + + const bindGroupsSeen: unknown[] = []; + const pass = { + setPipeline: vi.fn(), + setBindGroup: (slot: number, bg: unknown) => { + if (slot === 0) bindGroupsSeen.push(bg); + }, + setVertexBuffer: vi.fn(), + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; + + // A sky-cubemap capture sweep: two `draw()` calls (different faces) in + // the same frame, both before one `submit()`. + r.draw({ + focusBindGroup: FOCUS_BIND_GROUP, + pass, + viewProj: new Float32Array(16), + viewport: [512, 512], + instanceBytes: new Float32Array(FLOATS_PER_INSTANCE), + instanceCount: 1, + viewSlot: 1, + }); + r.draw({ + focusBindGroup: FOCUS_BIND_GROUP, + pass, + viewProj: new Float32Array(16), + viewport: [512, 512], + instanceBytes: new Float32Array(FLOATS_PER_INSTANCE), + instanceCount: 1, + viewSlot: 2, + }); + + // The @group(0) bind group resolves to a DIFFERENT physical bind group + // (over a different uniform buffer) per view slot. + expect(bindGroupsSeen[0]).not.toBe(bindGroupsSeen[1]); + + // The uniform writeBuffer calls target different underlying buffers — + // slot 2's write can never land in slot 1's buffer. Identify the + // uniform-sized writes by their DATA byte length (24 floats), not + // buffer identity, since the mock's returned buffers carry a `size` + // only on the createBuffer call args, not on the object itself. + const uniformWriteTargets = writeBufferSpy.mock.calls + .filter((call) => (call[2] as Float32Array).length === UNIFORM_BYTES / 4) + .map((call) => (call[0] as { __index: number }).__index); + expect(uniformWriteTargets).toEqual([1, 2]); // slot 1's buffer, then slot 2's + }); + }); + describe('blend mode', () => { it('applies additive blend factors when blend = "additive"', () => { const { ctx } = makeStubContext(); diff --git a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts index 64a877e7de..125492330c 100644 --- a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts +++ b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts @@ -168,3 +168,98 @@ describe('texturedDiskRenderer pack loop (Task R1)', () => { expect(target!.format).toBe('rgba16float'); }); }); + +describe('texturedDiskRenderer.draw — viewSlot (Task 13b)', () => { + it('two draw() calls with different viewSlot land their @group(0) uniform write in different buffers', () => { + const { ctx, writeBufferCalls } = makeStubCtx(); + const renderer = createTexturedDiskRenderer(ctx, FOCUS_BGL); + renderer.bindAtlas({} as GPUTextureView); + renderer.bindHiResArray({} as GPUTextureView); + + const bindGroupsAt0: unknown[] = []; + const pass = { + setPipeline: vi.fn(), + setBindGroup: (slot: number, bg: unknown) => { + if (slot === 0) bindGroupsAt0.push(bg); + }, + setVertexBuffer: vi.fn(), + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; + + const instances: DiskInstance[] = [fakeDiskInstance()]; + + // A sky-cubemap capture sweep: two `draw()` calls (different faces) in + // the same frame, both before one `submit()` — mirrors the roster + // convention pinned in `galaxyPointRenderer.test.ts` / + // `starCatalogRenderer`'s own viewSlot tests. + renderer.draw( + pass, + new Float32Array(16) as never, + [512, 512], + [0, 0, 0], + FOCUS_BIND_GROUP, + instances, + 1, + ); + renderer.draw( + pass, + new Float32Array(16) as never, + [512, 512], + [0, 0, 0], + FOCUS_BIND_GROUP, + instances, + 2, + ); + + // The @group(0) bind group resolves to a DIFFERENT physical bind group + // (over a different uniform buffer) per view slot — slot 2's write can + // never land in slot 1's buffer (the writeBuffer/submit race this + // closes; docs/RENDERER.md landmine #1). + expect(bindGroupsAt0[0]).not.toBe(bindGroupsAt0[1]); + + // Two uniform writeBuffer calls (96 bytes / 24 floats each — the + // instance-bytes writes are a separate, larger payload), one per slot. + const uniformWrites = writeBufferCalls.filter((c) => c.data.length === 96 / 4); + expect(uniformWrites).toHaveLength(2); + }); + + it('defaults viewSlot to 0 when omitted', () => { + const { ctx } = makeStubCtx(); + const renderer = createTexturedDiskRenderer(ctx, FOCUS_BGL); + renderer.bindAtlas({} as GPUTextureView); + renderer.bindHiResArray({} as GPUTextureView); + + const bindGroupsAt0: unknown[] = []; + const pass = { + setPipeline: vi.fn(), + setBindGroup: (slot: number, bg: unknown) => { + if (slot === 0) bindGroupsAt0.push(bg); + }, + setVertexBuffer: vi.fn(), + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; + + const instances: DiskInstance[] = [fakeDiskInstance()]; + renderer.draw( + pass, + new Float32Array(16) as never, + [800, 600], + [0, 0, 0], + FOCUS_BIND_GROUP, + instances, + ); + renderer.draw( + pass, + new Float32Array(16) as never, + [800, 600], + [0, 0, 0], + FOCUS_BIND_GROUP, + instances, + 0, + ); + + // Both calls land on slot 0's SAME bind group — an omitted viewSlot is + // byte-identical to an explicit 0. + expect(bindGroupsAt0[0]).toBe(bindGroupsAt0[1]); + }); +}); diff --git a/tests/visual/renderFrameSplitBaseline.test.ts b/tests/visual/renderFrameSplitBaseline.test.ts index 436d51c20f..7fafc21dfe 100644 --- a/tests/visual/renderFrameSplitBaseline.test.ts +++ b/tests/visual/renderFrameSplitBaseline.test.ts @@ -543,7 +543,7 @@ describe('renderFrame visual baseline', () => { "renderer": "procedural-disks", }, { - "argShape": "pass,Float32Array[16],Array[2],Array[3],object,Array[1]", + "argShape": "pass,Float32Array[16],Array[2],Array[3],object,Array[1],undefined", "renderer": "textured-disks", }, { From eab5878cb2355ec6176bd0087a809bdb11d3bb9c Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Tue, 1 Sep 2026 23:46:48 +0200 Subject: [PATCH 46/60] test(black-hole): pin the sky-cubemap disk-capture invariant (Task 13b) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Investigated the reported "Andromeda still doesn't appear lensed" defect against commit 2c63b9a34, which flagged texturedDisksLayer into the capture roster on the theory that lastOutput.disks (computed once from the LIVE main camera, upstream of the 6-face capture sweep) might miss galaxies a capture face needs but the main view culls. diskPlannerWalk.runFrame reads only cam.position — never cam.target, yaw, or pitch — so its distance/apparent-size gates are direction- agnostic by construction; there is no frustum cull to reuse incorrectly. Verified against the real famous.bin: M31 (row 46, ~0.78 Mpc from both the Sun and the Sgr A* anchor) computes to ~48px at the default 60deg FOV, clearing every gate (4px disk floor, 24px famous-exempt threshold, 23 Mpc max-visible-distance bound) regardless of which way the camera faces. No DiskInstance field is camera-orientation-dependent either (world-space position/size/axisRatio/PA; fadeAlpha is px-based, not direction-based). Adds a regression test pinning this invariant: a Famous row placed on the opposite side of the camera from its look target still lands in lastOutput.disks. Confirmed it fails if the walk grows a direction cull (temporarily injected one, watched the test fail, reverted). No production code changed — the capture-reuse mechanism is already correct; the continued report points at a defect elsewhere in the lensing pipeline, outside this investigation's scope. Co-Authored-By: Claude Fable 5 --- .../subsystems/texturedDiskSubsystem.test.ts | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/tests/services/engine/subsystems/texturedDiskSubsystem.test.ts b/tests/services/engine/subsystems/texturedDiskSubsystem.test.ts index e3f762f458..12a92c0f0a 100644 --- a/tests/services/engine/subsystems/texturedDiskSubsystem.test.ts +++ b/tests/services/engine/subsystems/texturedDiskSubsystem.test.ts @@ -385,4 +385,39 @@ describe('createTexturedDiskSubsystem', () => { expect(fetcher).toHaveBeenCalledWith(expect.objectContaining({ famousId: 'ngc-224' })); }); + + // Task 13b's sky-cubemap capture roster replays this SAME `lastOutput.disks` + // array across all 6 capture faces (`texturedDisksLayer.ts`), including faces + // that look away from the live camera's forward direction. That reuse is only + // sound if this subsystem's admission gates never depend on VIEW DIRECTION — + // only on `cam.position` (see `diskPlannerWalk.ts`, which reads `cam.position` + // and never `cam.target`/yaw/pitch). This test places a Famous row on the + // opposite side of the camera from its look target (`makeCam`'s target is + // +x of position) and asserts it still lands in `lastOutput.disks` — it would + // fail if either the walk or this subsystem ever grew a direction-dependent + // cull, which capture-face reuse silently relies on NOT existing. + it('admits a Famous row behind the camera — capture-face reuse needs no direction cull', async () => { + const fetcher = vi.fn(async () => makeFakeBitmap()); + const atlas = createGalaxyAtlasSubsystem({ device, requestRender: () => {} }); + const walk = createDiskPlannerWalk({ decimationFactor: 1 }); + const sys = createTexturedDiskSubsystem({ device, atlas, fetcher }); + + const cam = makeCam(); // position (9.95,0,0), target (10,0,0) → forward is +x + const behindX = cam.position[0]! - 2.0; // opposite side from the look target + const catalog = makeGalaxyCatalog(1, { + positions: new Float32Array([behindX, 0, 0]), + axisRatio: new Float32Array([0.7]), + positionAngleDeg: new Float32Array([45]), + diameterKpc: new Float32Array([50]), + }); + const clouds = new Map([[Source.FamousGalaxy, catalog]]); + const meta = makeFamousMeta(1); + + runTexturedSolo(walk, sys, makeInput(clouds, undefined, meta)); + await new Promise((r) => setTimeout(r, 0)); + const out = runTexturedSolo(walk, sys, makeInput(clouds, undefined, meta)); + + expect(out.disks).toHaveLength(1); + expect(out.disks[0]!.x).toBe(behindX); + }); }); From c9362d940c0acaf3c3623e1d8dcf0a868fd34d19 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 00:21:34 +0200 Subject: [PATCH 47/60] fix(black-hole): a capture step clears its face once, not once per slab MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sky-cubemap roster spans two slabs, so frameProgram emits TWO capture steps per face (COSMO then NEAR0). executeFrame forced `loadOp: 'clear'` on every step carrying a `face`, so the NEAR0 step cleared away the galaxy points and textured disks the COSMO step had just drawn into that same face. Only the star layers survived into the cubemap — which is why M31 / LMC / SMC vanish once the lens fade band engages and the visible sky IS the capture. The blanket always-clear (ebbf79e87) was the right fix for its own bug — `touched` tracks by target, and 'sky-cubemap' has six layers — but landed after the two-step split and so over-corrected. Capture steps now take their first-touch fact from a private `(target, face)`-keyed set, which clears once per face and loads within it. `ctx.renderedTargets` stays keyed by bare target id: it is a public consumer surface. Co-Authored-By: Claude Fable 5 --- src/services/engine/frame/executeFrame.ts | 29 +++++++++------ .../engine/frame/executeFrame.test.ts | 36 ++++++++++++++++++- 2 files changed, 54 insertions(+), 11 deletions(-) diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index e335a69b26..7c11d25fd1 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -51,10 +51,14 @@ * A capture render step (`step.face !== undefined`) is the one exception: its * target ('sky-cubemap') has six LAYERS, one per face, but `touched` tracks by * target string alone — so it can't distinguish "this face's first pass this - * frame" from "a DIFFERENT face already rendered this frame". Rather than grow - * `touched` to (target, layer) granularity for this one target, a capture step - * always clears: it redraws its whole face every time, so there's nothing worth - * loading. + * frame" from "a DIFFERENT face already rendered this frame". Capture steps + * therefore take their first-touch fact from a private `(target, face)`-keyed + * set instead, rather than growing the public `renderedTargets` surface to that + * granularity. Per-face granularity is load-bearing in BOTH directions: the + * roster spans two slabs, so `frameProgram` emits TWO steps per face (COSMO + * then NEAR0) — a blanket always-clear made the NEAR0 step wipe the COSMO + * step's galaxy points and textured disks off the face it had just drawn them + * into. * * The same `touched` fact drives depth: a render step whose target row declares * `depth` (only `foreground:0` today) attaches a depth texture whose load-op is @@ -214,6 +218,10 @@ export function executeFrame(args: ExecuteFrameArgs): void { // executor populates it here and later layers read which targets rendered this // frame via `ctx.renderedTargets`. const touched = ctx.renderedTargets as Set; + // Capture steps' own first-touch bookkeeping, keyed `:` — + // see the module header. Private to this call because `renderedTargets` + // is a public consumer surface keyed by bare target id. + const touchedFaces = new Set(); for (const step of program) { switch (step.kind) { @@ -256,6 +264,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { // (Ruling 6, resolving Task 12's own recorded finding). `step.face` // is the same discriminant `stepCtx` above already reads. const isCaptureStep = step.face !== undefined; + const faceKey = step.face === undefined ? null : `${step.target}:${step.face}`; const group = layers.filter( (l) => (isCaptureStep ? l.skyCapture === true : l.target === step.target) && @@ -301,15 +310,15 @@ export function executeFrame(args: ExecuteFrameArgs): void { view, groupKey, // `touched` tracks by TARGET, but a capture step's target - // ('sky-cubemap') has six LAYERS — one per face — so `touched` - // cannot tell "this face's first pass this frame" from "some - // OTHER face already rendered this frame". A capture step always - // clears instead: it redraws its whole face every time, so - // there's never content worth loading. See the module header. - alreadyTouched: step.face === undefined && touched.has(step.target), + // ('sky-cubemap') has six LAYERS — one per face — so it cannot tell + // "this face's first pass this frame" from "some OTHER face already + // rendered this frame". Capture steps read the face-keyed set + // instead. See the module header. + alreadyTouched: faceKey === null ? touched.has(step.target) : touchedFaces.has(faceKey), depthLoadOp: depthLoadOpFor(step.depthLoad, touched.has(step.target)), }); touched.add(step.target); + if (faceKey !== null) touchedFaces.add(faceKey); break; } case 'composite': { diff --git a/tests/services/engine/frame/executeFrame.test.ts b/tests/services/engine/frame/executeFrame.test.ts index 132ad227fa..65ff61b932 100644 --- a/tests/services/engine/frame/executeFrame.test.ts +++ b/tests/services/engine/frame/executeFrame.test.ts @@ -872,7 +872,41 @@ describe('executeFrame', () => { expect(new Set(viewsPerFace).size).toBe(6); }); - it('two capture steps for different faces in ONE frame BOTH clear — a capture step never loads', () => { + it("the SECOND capture step for the SAME face loads — it must not wipe the first slab's draws", () => { + // Pins the real bug: `frameProgram` emits TWO steps per face (COSMO then + // NEAR0) because the roster spans both slabs. A blanket always-clear made + // the NEAR0 step clear the face the COSMO step had just drawn the galaxy + // points and textured disks into, so no COSMO content ever survived into + // the cubemap the lens samples. + const cosmoLayer = makeLayer({ + name: 'textured-disks', + target: 'hdr', + slab: COSMO, + skyCapture: true, + }); + const near0Layer = makeLayer({ + name: 'star-points', + target: 'hdr', + slab: NEAR0, + skyCapture: true, + }); + const program: FrameStep[] = [ + { kind: 'render', target: 'sky-cubemap', slab: COSMO, face: 0 }, + { kind: 'render', target: 'sky-cubemap', slab: NEAR0, face: 0 }, + ]; + const faceCtx = makeCtx(); + const { args, env } = makeArgs({ + program, + layers: [cosmoLayer, near0Layer], + skyCubemapFaceContexts: new Map([[0, faceCtx]]), + }); + executeFrame(args); + + expect(attachmentOfDraw(env, cosmoLayer).loadOp).toBe('clear'); + expect(attachmentOfDraw(env, near0Layer).loadOp).toBe('load'); + }); + + it('two capture steps for different faces in ONE frame BOTH clear — one face never loads another face', () => { // Pins the real bug: `touched` tracks by TARGET ('sky-cubemap'), not by // LAYER (face). Before the fix, face 0's pass cleared and marked // 'sky-cubemap' touched; face 1's pass then LOADED — against its own From 5a5d57e2b7ee5a63497d6850e4730529d081c6c8 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 00:43:32 +0200 Subject: [PATCH 48/60] feat(black-hole): bake tuned disc orientation defaults (incl 0.35, PA 2.21) Co-Authored-By: Claude Fable 5 --- src/data/blackHoles.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/data/blackHoles.ts b/src/data/blackHoles.ts index 9a21e7b7d9..74e7c869a0 100644 --- a/src/data/blackHoles.ts +++ b/src/data/blackHoles.ts @@ -20,11 +20,10 @@ export const BLACK_HOLES: readonly BlackHoleRow[] = [ outerRs: 6, // Face-on view is ≲30° per EHT polarimetry. Chosen value at ~20°; the exact // angle is unconstrained but fixed for reproducible renders. - inclinationRad: Math.PI / 9, // ~20° + inclinationRad: 0.35, // ~20° // Major-axis position angle (E of N, standard astronomical convention). - // Entirely unconstrained; set to 45° for visual variety. Adjust here or via - // Task 15 debug panel. - positionAngleRad: Math.PI / 4, // 45° + // Entirely unconstrained; tuned via the Task 15 debug panel. + positionAngleRad: 2.21, // Stochastic brightening/dimming at minute-to-hour timescales (Sgr A* manifests // minute-scale near-IR flares; we borrow that timescale). Amplitude is tasteful // dev tuning — no published NIR variability-index texture yet. Range 0..1. From 0ff24ed8f9c6ecaf40fa3380c7926dee5dddd32a Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 00:46:39 +0200 Subject: [PATCH 49/60] docs(backlog): lens crossfade duplicate-points item Co-Authored-By: Claude Fable 5 --- docs/BACKLOG.md | 1 + ...6-09-02-lens-crossfade-duplicate-points.md | 36 +++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 27d3383ed5..650e066c7a 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -69,6 +69,7 @@ Items with a **→ details** link have a full write-up in [`backlog/`](backlog/) ## Rendering +- [ ] **Black-hole lens crossfade shows subtle duplicate points** `ready` — direct sky + lensed cubemap both partially visible across the band ramp; fade the direct roster inversely. → [details](backlog/2026-09-02-lens-crossfade-duplicate-points.md) - [ ] **`dirToEquirectUv` lives twice in WESL** `ready` — copied verbatim from `earth/fragment.wesl` into `earthSurfaceTile/fragment.wesl` (both load-bearing); extract to `shaders/lib/`. - [ ] **Renderer landmines from the Quest VR spike** `ready` — three hard-won traps to add to docs/RENDERER.md: per-camera (not per-frame) ctx memos, rebase-origin carrying, writeBuffer-at-submit ordering. → [details](backlog/2026-08-23-renderer-landmine-docs.md) - [ ] **Layer blend is declared twice** `needs-design` — `ContentLayer.blend` and the pipeline's `GPUBlendState` restate each other with nothing tying them; parity wants `blendStateOf` threaded through every renderer. → [details](backlog/2026-07-31-layer-blend-declared-twice.md) diff --git a/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md b/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md new file mode 100644 index 0000000000..a2817c724c --- /dev/null +++ b/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md @@ -0,0 +1,36 @@ +# Lens crossfade handoff shows subtle duplicate points + +**Reported:** 2026-09-02, user eyeball during the Sgr A* black-hole close-up landing +(branch worktree-render-black-hole). + +## Symptom + +While the camera crosses the black-hole fade band (~500 → 100 AU from Sgr A*), +the sky briefly shows subtle doubled points: each star/galaxy appears once from +the direct-view roster layers and once from the lensed sky-cubemap the lens quad +blends in on top. Fully outside or fully inside the band the sky is single. + +## Mechanism (hypothesis, unverified) + +The band crossfade alpha-blends the lens quad (showing the captured cubemap, +weak-field-deflected) over the still-drawn direct sky. During the ramp both +copies are visible at partial opacity, and the capture's deflection plus any +capture-eye offset displaces the cubemap copy by a few pixels from the direct +one — hence doubles rather than a clean brightness ramp. + +## Fix directions to evaluate + +- Fade the direct-view skyCapture roster layers out with the inverse of the + band alpha inside the band, so total contribution per source stays ~1. The + band-gated step split (`matchesLensPhase`, T14b) already distinguishes + inside-band frame composition — a per-layer alpha ride on the same predicate + is the natural seam. +- Alternatively gate direct roster layers hard-off above a band-alpha + threshold and let the lens quad's own edge fade cover the transition. + +## Pointers + +- Band definition + alpha: `SCALE_FADE_BANDS` row for `sgr-a-star` (T7). +- Step split predicate: `src/services/engine/frame/slabs.ts` / + `visibleSlabBodies.ts` (`matchesLensPhase`). +- Lens quad edge fade: `sgrAStarLensing/fragment.wesl` (`edgeFadeEndRs`). From 7bfb81e2dca42000f2a50eb85130050ff54de1c0 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 01:10:17 +0200 Subject: [PATCH 50/60] docs(black-hole): the lens tuning section ships MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plan's Task 15 called for deleting the debug-panel tuning cluster before merge and baking its values into BLACK_HOLES / shader consts. It ships instead: the Tier-2 fields have no owner other than settings.sgrAStarLensingTuning, the emission look is taste that keeps being retuned, and cubemapResolutionPx is a live VRAM/sharpness trade. The 176-byte uniform tail is therefore permanent. Softens every "TEMPORARY / removed at the removal step" comment into a statement of what the code is, retitles the panel section, and records the amendment in the spec's §Settings and the plan's Global Constraints + Task 15. Sizes the lens uniform buffer off SGR_A_STAR_LENSING_UNIFORM_FLOATS while the "176 bytes, temporarily" comment beside it goes. Co-Authored-By: Claude Fable 5 --- .../plans/2026-09-01-render-black-hole.md | 38 ++++++++-------- .../2026-09-01-render-black-hole-design.md | 16 +++++-- .../SgrAStarLensingSliderField.d.ts | 4 +- .../SgrAStarLensingSliderKey.d.ts | 4 +- src/@types/engine/frame/RenderTargetSpec.d.ts | 2 +- .../rendering/SgrAStarLensingRenderer.d.ts | 2 +- src/@types/settings/EngineSettingsState.d.ts | 5 +-- .../settings/SgrAStarLensingTuning.d.ts | 18 ++++---- src/components/DebugPanel/DebugPanel.tsx | 7 +-- .../SgrAStarLensingTuningSection.tsx | 13 +++--- .../SgrAStarLensingTuningSectionContainer.tsx | 3 +- src/data/blackHoles.ts | 2 +- src/data/defaults.ts | 22 +++------ .../sgrAStarLensingSliderFields.ts | 6 +-- .../frame/passes/sgrAStarLensingLayer.ts | 18 +++----- src/services/engine/frame/renderFrame.ts | 12 ++--- src/services/gpu/renderTargets.ts | 8 ++-- .../bodies/sgrAStarLensingRenderer.ts | 8 ++-- .../bodies/sgrAStarLensing/fragment.wesl | 13 +++--- .../bodies/sgrAStarLensing/vertex.wesl | 2 +- .../gpu/shaders/lib/sgrAStarLensing.wesl | 33 +++++++------- src/state/settings/initialState.ts | 10 ++--- src/state/settings/selectors.ts | 2 +- src/state/settings/settingsSlice.ts | 5 +-- src/utils/gpu/packSgrAStarLensingUniforms.ts | 45 +++++++++---------- .../renderFrame.skyCubemapHandOff.test.ts | 8 ++-- tests/services/gpu/renderTargets.test.ts | 6 +-- tests/state/settings/makeSettingsFixture.ts | 2 +- .../gpu/packSgrAStarLensingUniforms.test.ts | 7 ++- ...rAStarLensingUniformsLayout.parity.test.ts | 3 +- 30 files changed, 147 insertions(+), 177 deletions(-) diff --git a/docs/superpowers/plans/2026-09-01-render-black-hole.md b/docs/superpowers/plans/2026-09-01-render-black-hole.md index f1f9665f18..e756abc388 100644 --- a/docs/superpowers/plans/2026-09-01-render-black-hole.md +++ b/docs/superpowers/plans/2026-09-01-render-black-hole.md @@ -24,7 +24,9 @@ lenses and before the annotations that must stay unwarped. - Zero new user-facing settings (Q9) — the feature is physically parameterized from `BLACK_HOLES` + the shipped anchor body; dev-tuning constants ride the - existing DebugPanel and are removed before merge. + existing DebugPanel. **Amended during implementation:** that dev-tuning + section SHIPS rather than being deleted before merge — see the spec's + §Settings for why, and Task 15 below. - No Kerr metric, no full-GR observer view below 2 r_s, no cinematic accretion disc, no M87*/second black hole, no tour beat, no lensing of annotations (orbit trails, marker rings, labels, picking stay unlensed). @@ -969,13 +971,18 @@ not a licence to build finite-distance geodesics. --- -### Task 15: Debug-panel dev-tuning knobs (temporary, removed before merge) +### Task 15: Debug-panel dev-tuning knobs + +**Amended during implementation — this section SHIPS.** The planned removal +step is cancelled: the Tier-2 fields have no owner other than +`settings.sgrAStarLensingTuning`, the look is taste that will keep being +retuned, and `cubemapResolutionPx` is a live VRAM/sharpness trade. The +176-byte uniform tail is therefore permanent. See the spec's §Settings. **Files:** -- Create (temporary): `src/components/DebugPanel/SgrAStarLensingTuningSection.tsx` -- Create (temporary): `src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` -- Modify (temporary, then reverted in this same task's later step): - `src/components/DebugPanel/DebugPanel.tsx` +- Create: `src/components/DebugPanel/SgrAStarLensingTuningSection.tsx` +- Create: `src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` +- Modify: `src/components/DebugPanel/DebugPanel.tsx` **Precedent:** `ZoneOfAvoidanceTuningSection.tsx` + `ZoneOfAvoidanceTuningSectionContainer.tsx` (and their sibling @@ -996,21 +1003,12 @@ gate). that precedent uses — read its container before implementing, don't invent a new one). - [ ] Mount it in `DebugPanel.tsx` alongside the other tuning sections. -- [ ] Use it during Task 17's visual gate to converge on final values for - `BLACK_HOLES`'s emission fields and the capture threshold constant. -- [ ] **Removal step (same task, after Task 17 converges on final values):** - bake the tuned values back into `BLACK_HOLES` (Task 6) and the capture - threshold constant (Task 12) as the shipped literals, then DELETE - `SgrAStarLensingTuningSection.tsx` + its container via - `npm run refactor -- delete src/components/DebugPanel/SgrAStarLensingTuningSection.tsx src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` - and remove its mount line from `DebugPanel.tsx` — this removal is part - of THIS task, not deferred to a cleanup task, per the spec's explicit - "removed before merge" posture (Q9). +- [ ] Use it during Task 17's visual gate to converge on the DEFAULTS that + ship: Tier-1 values back into `BLACK_HOLES` (Task 6), Tier-2 values into + `DEFAULT_SGR_A_STAR_LENSING_TUNING` (`src/data/defaults.ts`). The + section itself stays mounted. - [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit (the removal is its own commit within this task, after the - tuning-driven values are baked in — so the history shows tuning added, - then values baked + tuning removed, not squashed into one commit that - hides the knob ever existed). +- [ ] Commit. --- diff --git a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md index ec95707c8f..4e3761bca8 100644 --- a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md +++ b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md @@ -372,8 +372,18 @@ it does not get waved through on the strength of the design. Zero new user-facing settings (Q9) — physically parameterized from `BLACK_HOLES` and the shipped anchor body (mass → r_s). Dev tuning of the -emission/LUT/capture constants rides the existing debug panel and is removed -before merge, the same posture the grill session settled on. +emission/LUT/capture constants rides the existing debug panel. + +Amended during implementation: the grill session's original posture was that +the tuning section would be deleted before merge, with its values baked back +into `BLACK_HOLES` / shader consts. It ships instead. The emission look is a +matter of taste that will keep being retuned, the section is dev-only +(DebugPanel), and `settings.sgrAStarLensingTuning` is the honest single home +for the Tier-2 fields (`diskScaleHeightRs`, `edgeFadeStartFraction`, +`dopplerStrength`, `emissionStrength`, `emissionTint`) — they have no other +owner. The uniform tail those fields ride (176 bytes) is therefore permanent. +`cubemapResolutionPx` stays a knob for the same reason: it trades VRAM +against lens sharpness on the viewer's own hardware. --- @@ -433,7 +443,7 @@ touching no existing target row's derivation. seam, `oneMpcSeam.test.ts`) the rest of the feature is built on. 4. **Feature implementation** — data rows, fade band, glint layer, LUT builder, geodesic shader, cubemap capture, lensing `ContentLayer`, draw- - order reorder, debug-panel dev tuning (removed before merge). + order reorder, debug-panel dev tuning. ## Relationship to open items diff --git a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts index 1f5c6a908e..0b4b206373 100644 --- a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts +++ b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderField.d.ts @@ -2,7 +2,7 @@ import type { SliderField } from '../SliderField'; import type { SgrAStarLensingSliderKey } from './SgrAStarLensingSliderKey'; /** - * TEMPORARY (Task 15). UI metadata for one Sgr A* lens tuning slider, - * iterated by the DebugPanel section. + * UI metadata for one Sgr A* lens tuning slider, iterated by the DebugPanel + * section. */ export type SgrAStarLensingSliderField = SliderField; diff --git a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts index 1702e0817b..6a2f97dd65 100644 --- a/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts +++ b/src/@types/data/sgrAStarLensing/SgrAStarLensingSliderKey.d.ts @@ -1,8 +1,8 @@ import type { SgrAStarLensingTuning } from '../../settings/SgrAStarLensingTuning'; /** - * TEMPORARY (Task 15). Keys of `SgrAStarLensingTuning` that surface as - * numeric DebugPanel sliders. `cubemapResolutionPx` (a discrete ``) * and `emissionTint` (a `Vec3` colour picker) get bespoke controls instead — * the same split `ZoneOfAvoidanceSliderKey` makes for its colour fields. */ diff --git a/src/@types/engine/frame/RenderTargetSpec.d.ts b/src/@types/engine/frame/RenderTargetSpec.d.ts index a40de06e5b..ff4dcf74e3 100644 --- a/src/@types/engine/frame/RenderTargetSpec.d.ts +++ b/src/@types/engine/frame/RenderTargetSpec.d.ts @@ -45,7 +45,7 @@ export type RenderTargetSpec = { * attachment). `scale` is ignored when this is present. * * `size` may be a FUNCTION for a row whose declared size is a live setting - * (`sky-cubemap`, T15 TEMPORARY DebugPanel knob) — the same + * (`sky-cubemap`'s DebugPanel knob) — the same * `scale`-is-a-function shape `mw-aggregate` uses, resolved by `reconcile` * every frame so a knob-driven row needs no rebuild path of its own. */ diff --git a/src/@types/rendering/SgrAStarLensingRenderer.d.ts b/src/@types/rendering/SgrAStarLensingRenderer.d.ts index 2d0e1a2600..1c2bbac527 100644 --- a/src/@types/rendering/SgrAStarLensingRenderer.d.ts +++ b/src/@types/rendering/SgrAStarLensingRenderer.d.ts @@ -19,7 +19,7 @@ export type SgrAStarLensingRenderer = Renderer & { readonly lut: SchwarzschildDeflectionLut; /** * Draw the lens billboard into the current (depthless, premultiplied-OVER) - * pass. `uniforms` is the packed 144-byte `SgrAStarLensingUniforms` + * pass. `uniforms` is the packed 176-byte `SgrAStarLensingUniforms` * (`packSgrAStarLensingUniforms`); `skyCubemapView` is this frame's * `dimension: 'cube'` view over the `sky-cubemap` render target * (`RenderTargets.cubeViewOf`) — read fresh by the caller every frame and diff --git a/src/@types/settings/EngineSettingsState.d.ts b/src/@types/settings/EngineSettingsState.d.ts index 04327668af..277d4c0a9b 100644 --- a/src/@types/settings/EngineSettingsState.d.ts +++ b/src/@types/settings/EngineSettingsState.d.ts @@ -199,9 +199,8 @@ export type EngineSettingsState = { zoneOfAvoidance: ZoneOfAvoidanceSettings; /** - * TEMPORARY (Task 15, deleted at its removal step once Task 17 converges) — - * the Sgr A* lens pass's DebugPanel tuning knobs. See `SgrAStarLensingTuning` - * for the tier breakdown and what each field replaces. + * The Sgr A* lens pass's DebugPanel tuning knobs. See + * `SgrAStarLensingTuning` for the tier breakdown and what each field owns. */ sgrAStarLensingTuning: SgrAStarLensingTuning; diff --git a/src/@types/settings/SgrAStarLensingTuning.d.ts b/src/@types/settings/SgrAStarLensingTuning.d.ts index 3d05231557..ae7a980cbd 100644 --- a/src/@types/settings/SgrAStarLensingTuning.d.ts +++ b/src/@types/settings/SgrAStarLensingTuning.d.ts @@ -1,11 +1,9 @@ /** - * SgrAStarLensingTuning — TEMPORARY (Task 15) DebugPanel knobs for the Sgr - * A* lens pass, deleted at the removal step once Task 17 converges (tuned - * values baked back into `BLACK_HOLES` / shader consts / module constants). - * Tier 1 overrides `BLACK_HOLES` at pack time; Tier 2 + emission - * strength/tint are new `SgrAStarLensingUniforms` fields (struct grew - * 144→176 bytes); the rest are non-uniform CPU-side knobs on the same - * settings seam. No `glintTint`/`glintIntensity` — see `bodyGlintsLayer.ts`. + * SgrAStarLensingTuning — the shipped DebugPanel knobs for the Sgr A* lens + * pass. Tier 1 overrides `BLACK_HOLES` at pack time; Tier 2 + emission + * strength/tint are `SgrAStarLensingUniforms` fields (the 176-byte tail); the + * rest are non-uniform CPU-side knobs on the same settings seam. No + * `glintTint`/`glintIntensity` — see `bodyGlintsLayer.ts`. */ import type { Vec3 } from '../math/Vec3'; @@ -19,16 +17,16 @@ export type SgrAStarLensingTuning = { flickerAmp: number; flickerTimescaleS: number; - // ── Tier 2 — new uniform fields (struct grown for this task) ──────────── + // ── Tier 2 — uniform fields of their own ──────────────────────────────── /** Was `fragment.wesl`'s `DISK_SCALE_HEIGHT_RS` const. */ diskScaleHeightRs: number; /** Was the escape branch's hardcoded `lutMaxImpactParamRs * 0.7` edge-fade start. */ edgeFadeStartFraction: number; /** Was `fragment.wesl`'s `DOPPLER_STRENGTH` const. */ dopplerStrength: number; - /** 2nd addendum: overall multiplier on the annulus emission's summed output. Default 1 reproduces today's brightness. */ + /** Overall multiplier on the annulus emission's summed output; 1 is the unscaled march. */ emissionStrength: number; - /** 2nd addendum: overall multiplier on the annulus emission's summed tint. Default [1,1,1] is a no-op. */ + /** Overall multiplier on the annulus emission's summed tint; [1,1,1] is a no-op. */ emissionTint: Vec3; // ── Non-uniform, same settings seam ────────────────────────────────────── diff --git a/src/components/DebugPanel/DebugPanel.tsx b/src/components/DebugPanel/DebugPanel.tsx index 3ce916f07b..66ccba51ab 100644 --- a/src/components/DebugPanel/DebugPanel.tsx +++ b/src/components/DebugPanel/DebugPanel.tsx @@ -7,9 +7,8 @@ * debugging), `FlowTuningSectionContainer`, `MilkyWayTuningSectionContainer` * (the Milky-Way star cloud's look knobs), * `ZoneOfAvoidanceTuningSectionContainer` (the galactic-plane guide band's - * look knobs), `SgrAStarLensingTuningSectionContainer` (TEMPORARY, Task 15 — - * the Sgr A* lens pass's tuning knobs, deleted once Task 17 converges), - * `DebugOverlaysSectionContainer` + * look knobs), `SgrAStarLensingTuningSectionContainer` (the Sgr A* lens + * pass's tuning knobs), `DebugOverlaysSectionContainer` * (pick-buffer / disk-radius-ring toggles), `EarthTileAtlasSectionContainer` * (textual atlas-residency readout — slot pressure, per-level resident/pending * counts, last plan shape), `GalaxyProvenanceSectionContainer` @@ -55,8 +54,6 @@ import RenderTogglesSectionContainer from '../containers/RenderTogglesSectionCon import FlowTuningSectionContainer from '../containers/FlowTuningSectionContainer'; import MilkyWayTuningSectionContainer from '../containers/MilkyWayTuningSectionContainer'; import ZoneOfAvoidanceTuningSectionContainer from '../containers/ZoneOfAvoidanceTuningSectionContainer'; -// TEMPORARY (Task 15) — deleted, with this import + its mount line below, at -// the removal step once Task 17 converges. See SgrAStarLensingTuning.d.ts. import SgrAStarLensingTuningSectionContainer from '../containers/SgrAStarLensingTuningSectionContainer'; import DebugOverlaysSectionContainer from '../containers/DebugOverlaysSectionContainer'; import GalaxyProvenanceSectionContainer from '../containers/GalaxyProvenanceSectionContainer'; diff --git a/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx b/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx index c939ea0bcb..6ff4d1d6ba 100644 --- a/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx +++ b/src/components/DebugPanel/SgrAStarLensingTuningSection.tsx @@ -1,11 +1,10 @@ // src/components/DebugPanel/SgrAStarLensingTuningSection.tsx /** - * TEMPORARY (Task 15) — Sgr A* lens pass tuning subsection, deleted at the - * removal step once Task 17 converges on final values (see - * `SgrAStarLensingTuning`'s own docblock). Structural precedent: - * `ZoneOfAvoidanceTuningSection.tsx`. `cubemapResolutionPx` gets a `` (four meaningful values) instead of + * riding the generic slider board — the same "bespoke control after the rows" + * shape ZoA's colour pickers use. * * 2048 costs ~192 MiB (2048² × 6 faces × 8 bytes/px rgba16float) — the row's * tooltip states the general formula rather than a per-option figure (no @@ -38,7 +37,7 @@ export function SgrAStarLensingTuningSection({ }: SgrAStarLensingTuningSectionProps): ReactElement { return ( onChange(sgrAStarLensingSliderPatch(k, v))} diff --git a/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx b/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx index 826befb24c..bcc7116b74 100644 --- a/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx +++ b/src/components/containers/SgrAStarLensingTuningSectionContainer.tsx @@ -1,7 +1,6 @@ // src/components/containers/SgrAStarLensingTuningSectionContainer.tsx /** - * TEMPORARY (Task 15) — store boundary for the DebugPanel's Sgr A* lens - * tuning knobs, deleted at the removal step. Mirrors + * Store boundary for the DebugPanel's Sgr A* lens tuning knobs. Mirrors * `ZoneOfAvoidanceTuningSectionContainer`: `selectSgrAStarLensingTuning` * returns the whole cluster (the slider board reads every knob), so this * subtree re-renders on any write to it — the right granularity for a small diff --git a/src/data/blackHoles.ts b/src/data/blackHoles.ts index 74e7c869a0..c67725e73d 100644 --- a/src/data/blackHoles.ts +++ b/src/data/blackHoles.ts @@ -22,7 +22,7 @@ export const BLACK_HOLES: readonly BlackHoleRow[] = [ // angle is unconstrained but fixed for reproducible renders. inclinationRad: 0.35, // ~20° // Major-axis position angle (E of N, standard astronomical convention). - // Entirely unconstrained; tuned via the Task 15 debug panel. + // Entirely unconstrained; tuned via the lens tuning debug panel. positionAngleRad: 2.21, // Stochastic brightening/dimming at minute-to-hour timescales (Sgr A* manifests // minute-scale near-IR flares; we borrow that timescale). Amplitude is tasteful diff --git a/src/data/defaults.ts b/src/data/defaults.ts index d449a56048..b953a920ef 100644 --- a/src/data/defaults.ts +++ b/src/data/defaults.ts @@ -267,26 +267,18 @@ export const DEFAULT_ZONE_OF_AVOIDANCE_TUNING: ZoneOfAvoidanceTuning = { }; /** - * TEMPORARY (Task 15, deleted at its removal step) — the Sgr A* lens pass's - * DebugPanel tuning starting values. + * The Sgr A* lens pass's DebugPanel tuning defaults. * * Tier 1 (`innerRs`..`flickerTimescaleS`) seeds from `BLACK_HOLES`'s Sgr A* - * row — that registry stays the single source of truth for these until the - * removal step bakes the tuned values back into it. + * row — that registry is the single source of truth for those. * - * Tier 2 (`diskScaleHeightRs` / `edgeFadeStartFraction` / `dopplerStrength`) - * mirrors `fragment.wesl`'s former `DISK_SCALE_HEIGHT_RS` / the escape - * branch's `* 0.7` edge-fade factor / `DOPPLER_STRENGTH` — this literal is - * their new single source of truth until the removal step bakes the tuned - * values back into the shader as consts. `emissionStrength: 1` / - * `emissionTint: [1,1,1]` (2nd addendum) are no-op identities — the shader - * had no such multiplier before, so a no-op default reproduces today's - * brightness exactly. + * Tier 2 (`diskScaleHeightRs` / `edgeFadeStartFraction` / `dopplerStrength` / + * `emissionStrength` / `emissionTint`) has no other home: this literal IS + * their source of truth, and the shader reads them off the uniform. * * `cubemapResolutionPx` seeds the `sky-cubemap` render-target row's declared - * size (`renderTargets.ts`) — 1024, per the user's live-view judgment against - * the T15 addendum's own prior bump (256 -> 512 -> 1024); the knob's option - * set stays 256/512/1024/2048. + * size (`renderTargets.ts`) — 1024, per a live-view judgment; the knob's + * option set is 256/512/1024/2048. * * NOT here: `skyCubemapRecaptureCameraMoveFraction`. Its owner is * `skyCubemapCaptureSchedule.ts` (a `services/` module `data/` doesn't diff --git a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts index 32bc60a0ce..a7d7dc0711 100644 --- a/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts +++ b/src/data/sgrAStarLensing/sgrAStarLensingSliderFields.ts @@ -1,7 +1,7 @@ /** - * SGR_A_STAR_LENSING_SLIDER_FIELDS — TEMPORARY (Task 15), deleted at the - * removal step. UI metadata for the Sgr A* lens pass's DebugPanel sliders — - * same shape as `data/zoneOfAvoidance/zoneOfAvoidanceSliderFields.ts`: label, + * SGR_A_STAR_LENSING_SLIDER_FIELDS — UI metadata for the Sgr A* lens pass's + * DebugPanel sliders. Same shape as + * `data/zoneOfAvoidance/zoneOfAvoidanceSliderFields.ts`: label, * range, granularity and formatting live in ONE row per knob. * `cubemapResolutionPx` isn't here — see `SgrAStarLensingSliderKey`. */ diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 985bffb079..3c1bab3135 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -35,13 +35,9 @@ import { SCALE_FADE_BANDS } from '../../presentation/scaleFadeBands'; const GALACTIC_CENTRE_REGION = regionById('galactic-centre'); // `BLACK_HOLES` is authored data guaranteed to carry a Sgr A* row; a missing -// row is a wiring bug worth failing loudly on, not a silent no-op layer. -// Checked once at module scope rather than every frame, the same "hoist the -// constant lookup" convention `starPointsLayer`'s module-scope regions -// follow. The row's VALUES are no longer read here — TEMPORARILY (Task 15), -// `state.settings.sgrAStarLensingTuning` overrides them at pack time (seeded -// from this same row — see `DEFAULT_SGR_A_STAR_LENSING_TUNING`); the removal -// step reverts to reading `BLACK_HOLE.emission.*` directly. +// row is a wiring bug worth failing loudly on, not a silent no-op layer. The +// row's VALUES are not read here: `state.settings.sgrAStarLensingTuning` is +// what packs (seeded from this same row — `DEFAULT_SGR_A_STAR_LENSING_TUNING`). if (BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id) === undefined) { throw new Error(`sgrAStarLensingLayer: BLACK_HOLES carries no row for '${SGR_A_STAR.id}'`); } @@ -96,11 +92,9 @@ export const sgrAStarLensingLayer: ContentLayer = { -pose.eyeRelBodyM[2], ]; - // TEMPORARY (Task 15): every emission field below reads the DebugPanel - // tuning cluster, not `BLACK_HOLE.emission` — see the module-scope guard's - // comment. `flickerPhase` must divide by the SAME `flickerTimescaleS` the - // packed uniform carries, or a live slider drag would desync the phase - // from the period it packs. + // `flickerPhase` must divide by the SAME `flickerTimescaleS` the packed + // uniform carries, or a live slider drag desyncs the phase from the + // period it packs. const tuning = state.settings.sgrAStarLensingTuning; const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / tuning.flickerTimescaleS; diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 43522db1c2..4f797f7abc 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -142,9 +142,9 @@ export function renderFrame(input: RenderFrameInput): void { // their shared border and the whole cubemap flicker as the camera moved // (fix round 3). Threshold is a FRACTION of `gcDistanceMpc` — see // `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s own docblock for why a - // fixed AU distance is wrong here. Read off settings, not the module - // constant, TEMPORARILY (Task 15's DebugPanel knob) — the constant stays - // this value's real owner (`initialState.ts` seeds from it). + // fixed AU distance is wrong here. Read off settings (the DebugPanel knob), + // not the module constant — which stays this value's real owner + // (`initialState.ts` seeds from it). const cameraMovedBeyondThreshold = captureRuntime.pinnedEyeMpc !== null && distanceMpc(ctx.drawCamPos, captureRuntime.pinnedEyeMpc) > @@ -177,9 +177,9 @@ export function renderFrame(input: RenderFrameInput): void { // `faceSizePx` reads the sky-cubemap row's own ALLOCATED size (`sizeOf`, // this frame's already-reconciled pixels — see `RenderTargets.sizeOf`'s // doc), not `specOf().fixedSizePx.size` directly: that field is a live - // setting as of Task 15 (a function of state, not a plain number), so - // reading the resolved allocation is both simpler and the authoritative - // answer. A face whose context comes back null (pre-bootstrap) is simply + // setting (a function of state, not a plain number), so reading the + // resolved allocation is the authoritative answer. + // A face whose context comes back null (pre-bootstrap) is simply // omitted — `executeFrame` treats a missing map entry as "skip this step // cleanly" (see its module header). const skyCubemapFaceContexts = new Map(); diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 6274cbcecc..4986683d15 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -169,9 +169,7 @@ function resolveScale(spec: RenderTargetSpec, state: EngineState): number { /** * A `fixedSizePx` row's declared per-axis size for this state — mirrors - * `resolveScale`. TEMPORARY (Task 15): today only `sky-cubemap`'s size is a - * function; every other `fixedSizePx` row (incl. `renderTargets.test.ts`'s - * synthetic `test:cubemap`) still hands a plain number. + * `resolveScale`. */ function resolveFixedSize( fixedSizePx: { size: number | ((state: EngineState) => number) }, @@ -275,8 +273,8 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT depth: null, scale: 1, // unused: fixedSizePx below overrides it (required by the type). clearValue: { r: 0, g: 0, b: 0, a: 0 }, - // `size` is a live setting, TEMPORARILY (Task 15's DebugPanel resolution - // knob, 256/512/1024/2048, default 1024) — `reconcile` resolves it every frame exactly like + // `size` is a live setting (the DebugPanel resolution knob, + // 256/512/1024/2048) — `reconcile` resolves it every frame exactly like // `mw-aggregate`'s divisor, so dragging the knob reallocates this row // (and its cube/layer views) without a rebuild path of its own. fixedSizePx: { diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts index 91c41d0bb9..74c7c1e4a2 100644 --- a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -36,6 +36,7 @@ import fsCode from '../../shaders/bodies/sgrAStarLensing/fragment.wesl?static'; import { createShaderModuleWithDevLog } from '../../shaderCompileLogger'; import { PREMULTIPLIED_OVER_BLEND } from '../../lib/blendStates'; import { buildSchwarzschildDeflectionLut } from '../../../../utils/lensing/buildSchwarzschildDeflectionLut'; +import { SGR_A_STAR_LENSING_UNIFORM_FLOATS } from '../../../../utils/gpu/packSgrAStarLensingUniforms'; /** * LUT texel count: dense enough that the fragment's 2-tap lerp reads as @@ -90,12 +91,11 @@ export function createSgrAStarLensingRenderer( const lutTexture = createLutTexture(device, lut); const lutView = lutTexture.createView({ label: 'sgr-a-star-lensing-lut-view' }); - // ── Uniform buffer (176 bytes, byte-exact with SgrAStarLensingUniforms — - // TEMPORARILY grown from 144 for Task 15's Tier-2 DebugPanel knobs; shrinks - // back at the removal step once Task 17 converges) ── + // Sized off the packer's own float count, so a new struct field can't leave + // this buffer one `writeBuffer` validation error short at runtime. const uniformBuffer = device.createBuffer({ label: 'sgr-a-star-lensing-uniform-buffer', - size: 176, + size: SGR_A_STAR_LENSING_UNIFORM_FLOATS * 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, }); diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index 48970bd08a..cbd0c9e2a4 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -34,10 +34,9 @@ const MARCH_GATE_MARGIN_RS: f32 = 4.0; // Split across the bent-ray march's two segments (Task 13c finding 3). const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // inner/outer annulus edge softening width -// DISK_SCALE_HEIGHT_RS / DOPPLER_STRENGTH used to live here as consts — -// TEMPORARILY (Task 15) they ride 'u.diskScaleHeightRs' / 'u.dopplerStrength' -// instead (DebugPanel tuning knobs), baked back into consts at the removal -// step once Task 17 converges. +// The disc scale height and Doppler strength are uniform fields +// ('u.diskScaleHeightRs' / 'u.dopplerStrength'), not consts: both are live +// DebugPanel knobs. // Two-tap manual lerp (r32float isn't sampler-filterable without the // optional feature, hence textureLoad + a texture_2d, not texture_1d — @@ -139,7 +138,7 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflec // Applied to the SUMMED emission, not per-sample: a flat brightness/tint // multiplier on the whole march's output, not on the physical falloff that // feeds 'coverage' (which stays keyed to the modeled density/radial - // profile, unscaled — T15 TEMP tuning knobs, 2nd addendum). + // profile, unscaled). if (captured) { return vec4(emission * u.emissionStrength * u.emissionTint, coverage); } @@ -205,9 +204,7 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4 — camera-relative anchor, metres (f64->f32 rebase seam) -// offset 140 : diskScaleHeightRs f32 — T15 TEMP tuning knob, was fragment.wesl's DISK_SCALE_HEIGHT_RS const -// offset 144 : edgeFadeStartFraction f32 — T15 TEMP tuning knob, was the escape branch's hardcoded '* 0.7' -// offset 148 : dopplerStrength f32 — T15 TEMP tuning knob, was fragment.wesl's DOPPLER_STRENGTH const -// offset 152 : emissionStrength f32 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission multiplier -// offset 156 : edgeFadeEndRs f32 — escape fade's end impact parameter, r_s units (NOT a T15 knob: -// derived per frame by the layer — min(subpixel-deflection b, 0.6·camera -// distance), floored at lutMaxImpactParamRs; survives the T15 removal) -// offset 160 : emissionTint vec3 — T15 TEMP tuning knob (2nd addendum), overall annulus-emission tint -// offset 172 : quadPlaneRadiusRs f32 — lens billboard half-size, r_s units (NOT a T15 knob: derived per -// frame in f64 by the layer via 'lensQuadPlaneRadiusRs' — the in-shader -// f32 inversion shook close orbits; survives the T15 removal) +// offset 140 : diskScaleHeightRs f32 — tuning knob (DebugPanel) +// offset 144 : edgeFadeStartFraction f32 — tuning knob (DebugPanel) +// offset 148 : dopplerStrength f32 — tuning knob (DebugPanel) +// offset 152 : emissionStrength f32 — tuning knob, overall annulus-emission multiplier +// offset 156 : edgeFadeEndRs f32 — escape fade's end impact parameter, r_s units (derived per +// frame by the layer — min(subpixel-deflection b, 0.6·camera +// distance), floored at lutMaxImpactParamRs) +// offset 160 : emissionTint vec3 — tuning knob, overall annulus-emission tint +// offset 172 : quadPlaneRadiusRs f32 — lens billboard half-size, r_s units (derived per frame in f64 +// by the layer via 'lensQuadPlaneRadiusRs' — the in-shader f32 +// inversion shook close orbits) // total: 176 bytes. // // The 12 scalar fields (80..127, 48 bytes) exactly fill the run up to 128, @@ -49,10 +47,9 @@ // silently reads garbage — no compile error, no runtime error, just a wrong // (or on iOS, dropped) frame. // -// TASK 15 TEMPORARY: every field after 'anchorPosRelCamM' is a DebugPanel -// tuning knob (Tier 2 of the task-15 brief, plus its 2nd-round addendum -// adding emissionStrength/emissionTint), deleted — struct shrunk back to -// 144 bytes — at the removal step once Task 17 converges on final values. +// Every field after 'anchorPosRelCamM' is either a DebugPanel tuning knob +// ('settings.sgrAStarLensingTuning') or a per-frame layer-derived scalar, as +// marked above. import package::lib::camera::CameraUniforms; diff --git a/src/state/settings/initialState.ts b/src/state/settings/initialState.ts index bd219cea2d..430aae80b1 100644 --- a/src/state/settings/initialState.ts +++ b/src/state/settings/initialState.ts @@ -58,9 +58,8 @@ import { DEFAULT_REFINE_THRESHOLD } from '../../services/gpu/renderers/starCatal // renderer's calibration module, so seed them from there rather than restating // six numbers here. import { MILKY_WAY_TUNING_DEFAULTS } from '../../services/engine/galaxyGenerator/v1/milkyWayCalibration'; -// TEMPORARY (Task 15, deleted at its removal step): same relationship — -// `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s single source of truth is -// the schedule module it feeds, not `data/defaults.ts`. +// Same relationship: `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s single +// source of truth is the schedule module it feeds, not `data/defaults.ts`. import { SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION } from '../../services/engine/frame/skyCubemapCaptureSchedule'; import { DEFAULT_ALIGN_SEC, @@ -174,9 +173,8 @@ export function buildInitialSettings(): EngineSettingsState { enabled: DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, ...DEFAULT_ZONE_OF_AVOIDANCE_TUNING, }, - // TEMPORARY (Task 15) — deleted, mount line and all, at the removal step - // once Task 17 converges on final values. See `SgrAStarLensingTuning`'s - // own docblock for the tier breakdown. + // The Sgr A* lens knobs; see `SgrAStarLensingTuning` for the tier + // breakdown and which module owns each default. sgrAStarLensingTuning: { ...DEFAULT_SGR_A_STAR_LENSING_TUNING, skyCubemapRecaptureCameraMoveFraction: SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, diff --git a/src/state/settings/selectors.ts b/src/state/settings/selectors.ts index 89c6768b16..89195d9cfd 100644 --- a/src/state/settings/selectors.ts +++ b/src/state/settings/selectors.ts @@ -189,7 +189,7 @@ export const selectZoneOfAvoidanceEnabled = (state: RootState): boolean => export const selectZoneOfAvoidance = (state: RootState): ZoneOfAvoidanceSettings => selectSettings(state).zoneOfAvoidance; -// --- sgrAStarLensingTuning cluster — TEMPORARY (Task 15) ----------------------- +// --- sgrAStarLensingTuning cluster --------------------------------------------- /** The whole tuning cluster — mirrors `selectMilkyWay` / `selectZoneOfAvoidance`. */ export const selectSgrAStarLensingTuning = (state: RootState): SgrAStarLensingTuning => diff --git a/src/state/settings/settingsSlice.ts b/src/state/settings/settingsSlice.ts index f5bdc4cc98..f1f2fe1e0a 100644 --- a/src/state/settings/settingsSlice.ts +++ b/src/state/settings/settingsSlice.ts @@ -198,9 +198,8 @@ const settingsSlice = createSlice({ Object.assign(settings.zoneOfAvoidance, action.payload); }, - // ── Sgr A* lens tuning — TEMPORARY (Task 15), deleted at the removal step - // ─ leaf-by-leaf patch, no visibility axis to protect (this cluster is - // pure knobs, not a singleton overlay). + // ── Sgr A* lens tuning — leaf-by-leaf patch, no visibility axis to + // protect (this cluster is pure knobs, not a singleton overlay). setSgrAStarLensingTuning: (settings, action: PayloadAction>) => { Object.assign(settings.sgrAStarLensingTuning, action.payload); }, diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index 621c10d7d8..e705162e20 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -1,12 +1,9 @@ /** - * packSgrAStarLensingUniforms — pure packer for the `SgrAStarLensingUniforms` - * struct (`shaders/lib/sgrAStarLensing.wesl`) — TEMPORARILY 176 bytes (Task - * 15's Tier-2 DebugPanel knobs, incl. the 2nd-round emission strength/tint - * addendum; shrinks back to 144 at Task 15's removal step once Task 17 - * converges — see that .wesl file's own header). + * packSgrAStarLensingUniforms — pure packer for the 176-byte + * `SgrAStarLensingUniforms` struct (`shaders/lib/sgrAStarLensing.wesl`). * - * Task 10's half of the uniform contract between the Sgr A* lens pass - * (Task 13, not yet written) and its WGSL. The struct is the shared + * The CPU half of the uniform contract between the Sgr A* lens pass and its + * WGSL. The struct is the shared * `CameraUniforms` prefix (`writeCameraPrefix`, the same helper every * world-space renderer uses) plus the lens's own scalar params, the LUT * addressing pair, this frame's fade-band alpha, and the camera-relative @@ -32,12 +29,12 @@ * f32 30 (byte 120..123): lutSampleCount f32 * f32 31 (byte 124..127): bandAlpha f32 * f32 32..34 (byte 128..139): anchorPosRelCamM vec3 - * f32 35 (byte 140..143): diskScaleHeightRs — T15 TEMP tuning knob - * f32 36 (byte 144..147): edgeFadeStartFraction — T15 TEMP tuning knob - * f32 37 (byte 148..151): dopplerStrength — T15 TEMP tuning knob - * f32 38 (byte 152..155): emissionStrength — T15 TEMP tuning knob (2nd addendum) + * f32 35 (byte 140..143): diskScaleHeightRs — tuning knob + * f32 36 (byte 144..147): edgeFadeStartFraction — tuning knob + * f32 37 (byte 148..151): dopplerStrength — tuning knob + * f32 38 (byte 152..155): emissionStrength — tuning knob * f32 39 (byte 156..159): edgeFadeEndRs — per-frame derived (not a knob) - * f32 40..42 (byte 160..171): emissionTint — T15 TEMP tuning knob (2nd addendum), vec3 + * f32 40..42 (byte 160..171): emissionTint — tuning knob, vec3 * f32 43 (byte 172..175): quadPlaneRadiusRs — per-frame derived (not a knob) * * Total: 176 bytes / 44 f32. The 12 scalars at f32 20..31 exactly fill the @@ -65,12 +62,12 @@ * @param lutSampleCount The LUT texture's texel count. * @param bandAlpha This frame's fade-band alpha (gates emission/deflection strength in-shader). * @param anchorPosRelCamM Camera-relative anchor position, metres. - * @param diskScaleHeightRs T15 TEMP — vertical falloff scale height, r_s units. - * @param edgeFadeStartFraction T15 TEMP — escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. - * @param dopplerStrength T15 TEMP — Doppler-beaming strength factor. - * @param emissionStrength T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's output intensity. + * @param diskScaleHeightRs Vertical falloff scale height, r_s units. + * @param edgeFadeStartFraction Escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. + * @param dopplerStrength Doppler-beaming strength factor. + * @param emissionStrength Overall multiplier on the annulus emission's output intensity. * @param edgeFadeEndRs Escape fade's end impact parameter, r_s units — derived per frame by the layer. - * @param emissionTint T15 TEMP (2nd addendum) — overall multiplier on the annulus emission's per-sample tint. + * @param emissionTint Overall multiplier on the annulus emission's per-sample tint. * @param quadPlaneRadiusRs Lens billboard half-size, r_s units — `lensQuadPlaneRadiusRs`, derived per frame. */ @@ -80,8 +77,8 @@ import type { Vec3 } from '../../@types/math/Vec3'; import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/cameraUniforms'; /** f32 count of `SgrAStarLensingUniforms` — 80-byte cam prefix (20) + 12 - * scalars + anchorPosRelCamM (3) + T15 TEMP tuning knobs (4 scalars + - * emissionTint's 3) + edgeFadeEndRs + quadPlaneRadiusRs = 44. */ + * scalars + anchorPosRelCamM (3) + tuning knobs (4 scalars + emissionTint's + * 3) + edgeFadeEndRs + quadPlaneRadiusRs = 44. */ export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 24; export function packSgrAStarLensingUniforms( @@ -125,12 +122,12 @@ export function packSgrAStarLensingUniforms( out[32] = anchorPosRelCamM[0]; // byte 128 — vec3, 16-byte aligned out[33] = anchorPosRelCamM[1]; // byte 132 out[34] = anchorPosRelCamM[2]; // byte 136 - out[35] = diskScaleHeightRs; // byte 140 — T15 TEMP - out[36] = edgeFadeStartFraction; // byte 144 — T15 TEMP - out[37] = dopplerStrength; // byte 148 — T15 TEMP - out[38] = emissionStrength; // byte 152 — T15 TEMP (2nd addendum) + out[35] = diskScaleHeightRs; // byte 140 + out[36] = edgeFadeStartFraction; // byte 144 + out[37] = dopplerStrength; // byte 148 + out[38] = emissionStrength; // byte 152 out[39] = edgeFadeEndRs; // byte 156 — per-frame derived (not a knob) - out[40] = emissionTint[0]; // byte 160 — T15 TEMP (2nd addendum), vec3 + out[40] = emissionTint[0]; // byte 160 — vec3 out[41] = emissionTint[1]; // byte 164 out[42] = emissionTint[2]; // byte 168 out[43] = quadPlaneRadiusRs; // byte 172 — per-frame derived (not a knob) diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index 485494f192..1e5f797cd1 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -56,8 +56,8 @@ function makeState(): EngineState { hdr: { enabled: false, knee: 0, headroom: 0 }, bloom: { enabled: false }, debug: { renderStrategy: 'auto' }, - // TEMPORARY (Task 15): renderFrame reads the recapture-move threshold - // off settings now — 0.03 matches SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, + // renderFrame reads the recapture-move threshold off settings — + // 0.03 matches SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, // the value every threshold assertion below was written against. sgrAStarLensingTuning: { skyCubemapRecaptureCameraMoveFraction: 0.03 }, }, @@ -80,8 +80,8 @@ function makeCtx(drawCamPos: readonly [number, number, number]): ReadyFrameConte if (id === 'swap') return { format: 'bgra8unorm' }; throw new Error(`mock renderTargets: no spec row for '${id}'`); }, - // TEMPORARY (Task 15): renderFrame reads the ALLOCATED size, not the - // spec's `fixedSizePx.size` (a live setting now) — see renderFrame.ts's + // renderFrame reads the ALLOCATED size, not the spec's + // `fixedSizePx.size` (a live setting) — see renderFrame.ts's // `faceSizePx` derivation. sizeOf: (id: string) => { if (id === 'sky-cubemap') return { width: 256, height: 256 }; diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index 6f83191a98..b229b20bdf 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -30,7 +30,7 @@ const SWAP_FORMAT: GPUTextureFormat = 'bgra8unorm'; const MW_DIVISOR = 2; // The production `sky-cubemap` row's `fixedSizePx.size` reads -// `settings.sgrAStarLensingTuning.cubemapResolutionPx` (TEMPORARY, Task 15) — +// `settings.sgrAStarLensingTuning.cubemapResolutionPx` — // every `createRenderTargets`/`reconcile` call below goes through the real // table (`extraRows` only APPENDS), so this fixture needs the field even in // tests that don't care about the sky-cubemap row itself. @@ -62,8 +62,8 @@ const FIXED_SIZE_ROW: RenderTargetSpec = { }; // A `fixedSizePx` row whose `size` is a FUNCTION of state (the -// `sky-cubemap` production row's own shape, TEMPORARILY, Task 15) — -// mirrors `mw-aggregate`'s state-driven `scale`. +// `sky-cubemap` production row's own shape) — mirrors `mw-aggregate`'s +// state-driven `scale`. const STATE_DRIVEN_FIXED_SIZE_ROW: RenderTargetSpec = { id: 'test:state-cubemap', format: 'rgba16float', diff --git a/tests/state/settings/makeSettingsFixture.ts b/tests/state/settings/makeSettingsFixture.ts index ae15793a47..93988cc97a 100644 --- a/tests/state/settings/makeSettingsFixture.ts +++ b/tests/state/settings/makeSettingsFixture.ts @@ -142,7 +142,7 @@ export function makeSettingsFixture( enabled: DEFAULT_ZONE_OF_AVOIDANCE_ENABLED, ...DEFAULT_ZONE_OF_AVOIDANCE_TUNING, }, - // TEMPORARY (Task 15) — mirrors initialState.ts's seed. + // Mirrors initialState.ts's seed. sgrAStarLensingTuning: { ...DEFAULT_SGR_A_STAR_LENSING_TUNING, skyCubemapRecaptureCameraMoveFraction: SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION, diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index 74c37df8b9..f3e25ad9fe 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -44,8 +44,7 @@ const LUT_MAX_IMPACT_PARAM_RS = 40.5; const LUT_SAMPLE_COUNT = 256; const BAND_ALPHA = 0.578125; const ANCHOR_POS_REL_CAM_M: Vec3 = [3.5, -1.25, 7.75]; -// T15 TEMP tuning-knob fields — deleted along with these sentinels at the -// removal step once Task 17 converges. +// Tuning-knob fields. const DISK_SCALE_HEIGHT_RS = 0.8125; const EDGE_FADE_START_FRACTION = 0.65625; const DOPPLER_STRENGTH = 0.46875; @@ -117,13 +116,13 @@ describe('SgrAStarLensingUniforms byte offsets', () => { expect(rec[33]).toBe(ANCHOR_POS_REL_CAM_M[1]); // byte 132 expect(rec[34]).toBe(ANCHOR_POS_REL_CAM_M[2]); // byte 136 - // T15 TEMP tuning-knob fields, offset 140+ (float index 35+). + // Tuning-knob fields, offset 140+ (float index 35+). expect(rec[35]).toBe(DISK_SCALE_HEIGHT_RS); // byte 140 expect(rec[36]).toBe(EDGE_FADE_START_FRACTION); // byte 144 expect(rec[37]).toBe(DOPPLER_STRENGTH); // byte 148 expect(rec[38]).toBe(EMISSION_STRENGTH); // byte 152 - // edgeFadeEndRs — per-frame derived escape-fade end (not a T15 knob). + // edgeFadeEndRs — per-frame derived escape-fade end (not a knob). expect(rec[39]).toBe(EDGE_FADE_END_RS); // byte 156 // emissionTint — vec3 at byte 160 (float index 40). diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 63dbf8f438..99f4f94f6f 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -109,8 +109,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const lutSampleCount = 511; const bandAlpha = 512; const anchorPosRelCamM: Vec3 = [601, 602, 603]; - // T15 TEMP tuning-knob fields — deleted along with these sentinels at the - // removal step once Task 17 converges. + // Tuning-knob fields. const diskScaleHeightRs = 701; const edgeFadeStartFraction = 702; const dopplerStrength = 703; From 9e57a25747816973d213c56cc9e09077d0697425 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 01:16:30 +0200 Subject: [PATCH 51/60] perf(black-hole): the sky-cubemap row's 50 MB exists only inside the band MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The row was an ordinary offscreen, so every device held 1024x1024x6 rgba16float (50 MB) from boot whether or not the camera ever went near Sgr A* — contrary to the spec's "zero cost outside ~500 AU" claim. A `RenderTargetSpec.allocateWhen` predicate now gates a row's existence on the same per-frame `reconcile` seam a moved size already rides; `sky-cubemap` keys it off the lensing-band flag on `skyCubemapCapture`, and `reconcile` releases the texture and its views when the band closes. `runFrame`'s reconcile runs before the frame's camera pose exists, so `renderFrame` reconciles on the band EDGE — the entry frame is also the frame that sweeps all six faces. `wasBandActive` becomes `bandActive` (it is now read as the row's allocation condition, not only as the edge's previous value), and the capture bookkeeping folds under `if (bandActive)` so nothing re-pins the eye on a frame that cannot capture. The lens renderer + LUT stay boot-eager: a one-off 2 KB texture and two pipelines, not 50 MB. Co-Authored-By: Claude Fable 5 --- src/@types/engine/frame/RenderTargetSpec.d.ts | 12 ++ .../state/SkyCubemapCaptureRuntime.d.ts | 9 +- src/services/engine/engine.ts | 2 +- src/services/engine/frame/renderFrame.ts | 120 ++++++++++-------- .../engine/gpuHandles/gpuHandleRegistry.ts | 3 + src/services/gpu/renderTargets.ts | 35 ++++- .../playClipFlyout.integration.test.ts | 2 +- .../engine/camera/commitOnEdge.test.ts | 2 +- .../renderFrame.skyCubemapHandOff.test.ts | 26 +++- .../services/engine/frame/renderFrame.test.ts | 2 +- .../engine/frame/renderFrame.timing.test.ts | 2 +- tests/services/gpu/renderTargets.test.ts | 45 +++++++ tests/visual/renderFrameSplitBaseline.test.ts | 2 +- 13 files changed, 201 insertions(+), 61 deletions(-) diff --git a/src/@types/engine/frame/RenderTargetSpec.d.ts b/src/@types/engine/frame/RenderTargetSpec.d.ts index ff4dcf74e3..e672655fb0 100644 --- a/src/@types/engine/frame/RenderTargetSpec.d.ts +++ b/src/@types/engine/frame/RenderTargetSpec.d.ts @@ -53,4 +53,16 @@ export type RenderTargetSpec = { readonly size: number | ((state: EngineState) => number); readonly layers: number; }; + /** + * When present, this row's texture exists only on the frames this returns + * `true`; `reconcile` releases it (and its views) again the frame it turns + * `false`. Absent — every other row — means "always allocated", which is + * the right default for a viewport-sized row a pass may touch on any frame. + * It is worth declaring for a row whose VRAM is large and whose consumers + * are gated on one narrow condition (`sky-cubemap`: 50 MB at the shipped + * resolution, read only within ~500 AU of Sgr A*). A consumer must be + * gated on the SAME condition — `viewOf`/`sizeOf` throw while the row is + * released. + */ + allocateWhen?: (state: EngineState) => boolean; }; diff --git a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts index 593dca43df..5e55aa06d2 100644 --- a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts +++ b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts @@ -18,8 +18,13 @@ export type SkyCubemapCaptureRuntime = { lastCapturedAtMs: Map; /** Monotonic per-frame counter driving the round-robin (`frameIndex % 6`). */ frameIndex: number; - /** The lensing band's active/inactive state last frame — `bandJustEngaged`'s edge. */ - wasBandActive: boolean; + /** + * The lensing band's state as of the last rendered frame. `renderFrame` + * reads it for the `bandJustEngaged` edge before overwriting it, and the + * `sky-cubemap` render-target row's `allocateWhen` reads it to decide + * whether its texture exists at all (`renderTargets.ts`). + */ + bandActive: boolean; /** * The eye EVERY face was captured from at the last full sweep. Round-robin * refreshes reuse this same pinned eye rather than the live camera each diff --git a/src/services/engine/engine.ts b/src/services/engine/engine.ts index 664c323214..58bedfb121 100644 --- a/src/services/engine/engine.ts +++ b/src/services/engine/engine.ts @@ -187,7 +187,7 @@ export function createEngine(canvas: HTMLCanvasElement, cb: EngineCallbacks): En skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }; diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 4f797f7abc..00b7e5e7e6 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -132,43 +132,17 @@ export function renderFrame(input: RenderFrameInput): void { // already follows for the identical `frame.kind === 'body-m'` lookup. // `null` outside the band, or when the row isn't in `ctx.slabs` this frame // (e.g. frustum-culled despite the distance band). - const sgrAStarBodySlab = bandActive - ? (ctx.slabs.find((slab) => slab.frame.kind === 'body-m' && slab.frame.bodyId === SGR_A_STAR.id) - ?.index ?? null) - : null; - const bandJustEngaged = bandActive && !captureRuntime.wasBandActive; - // Measured against the PINNED eye, not the live camera each frame: a - // fresh live eye per round-robin face made adjacent faces disagree at - // their shared border and the whole cubemap flicker as the camera moved - // (fix round 3). Threshold is a FRACTION of `gcDistanceMpc` — see - // `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s own docblock for why a - // fixed AU distance is wrong here. Read off settings (the DebugPanel knob), - // not the module constant — which stays this value's real owner - // (`initialState.ts` seeds from it). - const cameraMovedBeyondThreshold = - captureRuntime.pinnedEyeMpc !== null && - distanceMpc(ctx.drawCamPos, captureRuntime.pinnedEyeMpc) > - state.settings.sgrAStarLensingTuning.skyCubemapRecaptureCameraMoveFraction * gcDistanceMpc; - const fullSweepTriggered = bandJustEngaged || cameraMovedBeyondThreshold; - // Re-pin BEFORE scheduling so a triggered full sweep — including this - // frame's own faces — samples the eye it was triggered by, not the eye it - // just moved past. - if (fullSweepTriggered) { - captureRuntime.pinnedEyeMpc = ctx.drawCamPos; + const bandJustEngaged = bandActive && !captureRuntime.bandActive; + // The `sky-cubemap` row's 50 MB exists only while the band does (its + // `allocateWhen`, renderTargets.ts). `runFrame`'s per-frame `reconcile` + // runs BEFORE this frame's camera pose is produced, so it cannot see the + // band open; the edge reconciles here instead, because the entry frame is + // also the frame that sweeps all six faces and would otherwise read a row + // that does not exist yet. + if (bandActive !== captureRuntime.bandActive) { + captureRuntime.bandActive = bandActive; + ctx.renderTargets.reconcile(state, ctx.canvasSize); } - const skyCubemapFacesToCapture: readonly CubeFace[] = bandActive - ? skyCubemapCaptureSchedule({ - fullSweepTriggered, - frameIndex: captureRuntime.frameIndex, - lastCapturedAtMs: captureRuntime.lastCapturedAtMs, - nowMs: ctx.nowMs, - }).facesToCapture - : []; - for (const face of skyCubemapFacesToCapture) { - captureRuntime.lastCapturedAtMs.set(face, ctx.nowMs); - } - captureRuntime.wasBandActive = bandActive; - captureRuntime.frameIndex += 1; // The runtime hand-off (Task 12's brief, "Name the runtime hand-off"): // `frameProgram` only knows WHICH faces to capture (static data); resolving @@ -183,22 +157,66 @@ export function renderFrame(input: RenderFrameInput): void { // omitted — `executeFrame` treats a missing map entry as "skip this step // cleanly" (see its module header). const skyCubemapFaceContexts = new Map(); - const pinnedEyeMpc = captureRuntime.pinnedEyeMpc; - if (skyCubemapFacesToCapture.length > 0 && pinnedEyeMpc !== null) { - const faceSizePx = ctx.renderTargets.sizeOf('sky-cubemap').width; + let skyCubemapFacesToCapture: readonly CubeFace[] = []; + // Sgr A*'s own body-m slab row this frame: `frameProgram` emits the + // (hdr, BODY[k]) lens step off it. Resolved here, not in `frameProgram`, + // because the row's painter-order index comes from `deriveSlabs` (computed + // upstream of this function) — the same "resolve here, hand data down" + // split `earthSlab` in `runFrame.ts` already follows for the identical + // `frame.kind === 'body-m'` lookup. Stays `null` when the row isn't in + // `ctx.slabs` this frame (e.g. frustum-culled despite the distance band). + let sgrAStarBodySlab: number | null = null; + if (bandActive) { + sgrAStarBodySlab = + ctx.slabs.find((slab) => slab.frame.kind === 'body-m' && slab.frame.bodyId === SGR_A_STAR.id) + ?.index ?? null; + // Measured against the PINNED eye, not the live camera each frame: a + // fresh live eye per round-robin face made adjacent faces disagree at + // their shared border and the whole cubemap flicker as the camera moved. + // Threshold is a FRACTION of `gcDistanceMpc` — see + // `SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION`'s own docblock for why a + // fixed AU distance is wrong here. Read off settings (the DebugPanel + // knob), not the module constant — which stays this value's real owner + // (`initialState.ts` seeds from it). + const cameraMovedBeyondThreshold = + captureRuntime.pinnedEyeMpc !== null && + distanceMpc(ctx.drawCamPos, captureRuntime.pinnedEyeMpc) > + state.settings.sgrAStarLensingTuning.skyCubemapRecaptureCameraMoveFraction * gcDistanceMpc; + const fullSweepTriggered = bandJustEngaged || cameraMovedBeyondThreshold; + // Re-pin BEFORE scheduling so a triggered full sweep — including this + // frame's own faces — samples the eye it was triggered by, not the eye it + // just moved past. + if (fullSweepTriggered) { + captureRuntime.pinnedEyeMpc = ctx.drawCamPos; + } + skyCubemapFacesToCapture = skyCubemapCaptureSchedule({ + fullSweepTriggered, + frameIndex: captureRuntime.frameIndex, + lastCapturedAtMs: captureRuntime.lastCapturedAtMs, + nowMs: ctx.nowMs, + }).facesToCapture; for (const face of skyCubemapFacesToCapture) { - const faceCtx = skyCubemapFaceContext({ - state, - // The PINNED eye (see `pinnedEyeMpc`'s docblock), not the live - // camera: all six faces must share one eye or they disagree at - // their shared border. Still camera-relative overall, not the - // hole's — see this fix's round-2 commit for the boundary-seam - // rationale that motivated moving off the hole in the first place. - eyeMpc: pinnedEyeMpc, - face, - faceSizePx, - }); - if (faceCtx !== null) skyCubemapFaceContexts.set(face, faceCtx); + captureRuntime.lastCapturedAtMs.set(face, ctx.nowMs); + } + captureRuntime.frameIndex += 1; + + const pinnedEyeMpc = captureRuntime.pinnedEyeMpc; + if (skyCubemapFacesToCapture.length > 0 && pinnedEyeMpc !== null) { + const faceSizePx = ctx.renderTargets.sizeOf('sky-cubemap').width; + for (const face of skyCubemapFacesToCapture) { + const faceCtx = skyCubemapFaceContext({ + state, + // The PINNED eye (see `pinnedEyeMpc`'s docblock), not the live + // camera: all six faces must share one eye or they disagree at + // their shared border. Still camera-relative overall, not the + // hole's — a hole-centred eye put the capture's own boundary seam + // where the lens magnifies it most. + eyeMpc: pinnedEyeMpc, + face, + faceSizePx, + }); + if (faceCtx !== null) skyCubemapFaceContexts.set(face, faceCtx); + } } } diff --git a/src/services/engine/gpuHandles/gpuHandleRegistry.ts b/src/services/engine/gpuHandles/gpuHandleRegistry.ts index befb720b11..bd8b9a7f9f 100644 --- a/src/services/engine/gpuHandles/gpuHandleRegistry.ts +++ b/src/services/engine/gpuHandles/gpuHandleRegistry.ts @@ -369,6 +369,9 @@ export const GPU_HANDLE_ROWS = [ createBodyGlintRenderer(deps.ctx.device, HDR_TARGET_FORMAT), }, { + // Boot-eager like every other renderer row, deliberately: the deflection + // LUT build + its 2 KB texture + two pipelines are a one-off cost, unlike + // the 50 MB `sky-cubemap` target, which is lazy (`allocateWhen`). key: 'sgrAStarLensingRenderer', construct: (_state: EngineState, deps: GpuHandleConstructDeps) => createSgrAStarLensingRenderer(deps.ctx.device, HDR_TARGET_FORMAT), diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 4986683d15..853f921db7 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -267,12 +267,19 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT // 2d-array, later bound as a `texture_cube` (see `CubeFace.d.ts`). Same // depthless/additive/zero-clear profile as `hdr` — the captured roster // (point-sprites, star-catalog/aggregates, S-star glints) is additive. + // + // The one row with an `allocateWhen`: 1024² × 6 × 8 B is 50 MB, and the + // lens draws only within ~500 AU of Sgr A*, so the texture exists only + // while the band does. `renderFrame` writes the band flag and reconciles + // on its edge, so the row is there on the band-entry frame — the frame + // that sweeps all six faces. { id: 'sky-cubemap', format: HDR_TARGET_FORMAT, depth: null, scale: 1, // unused: fixedSizePx below overrides it (required by the type). clearValue: { r: 0, g: 0, b: 0, a: 0 }, + allocateWhen: (state) => state.cameraRuntime.skyCubemapCapture.bandActive, // `size` is a live setting (the DebugPanel resolution knob, // 256/512/1024/2048) — `reconcile` resolves it every frame exactly like // `mw-aggregate`'s divisor, so dragging the knob reallocates this row @@ -407,6 +414,24 @@ export function createRenderTargets( } } + /** + * Drop one row's textures + views. Every map is cleared together with the + * size record, so the row misses the held-size comparison on the frame its + * `allocateWhen` turns true again and reallocates through the normal path. + */ + function release(id: string): void { + if (!textures.has(id) && !depthTextures.has(id)) return; + textures.get(id)?.destroy(); + depthTextures.get(id)?.destroy(); + textures.delete(id); + views.delete(id); + cubeViews.delete(id); + layerViews.delete(id); + depthTextures.delete(id); + depthViews.delete(id); + sizes.delete(id); + } + // Keyed on the size the row was allocated at, never on a remembered divisor: // the texture is the authoritative record of what it was built at, so a canvas // resize and a settings-driven divisor move reduce to one question. Two @@ -415,11 +440,19 @@ export function createRenderTargets( // (`reducedTargetSize` is the shared sizing rule; see its docblock.) function reconcile(s: EngineState, canvas: Size): void { for (const spec of offscreenSpecs) { + // A row that declares `allocateWhen` holds VRAM only while its + // condition does — same per-frame seam as a moved size, so entering + // and leaving the condition need no lifecycle path of their own. + if (spec.allocateWhen !== undefined && !spec.allocateWhen(s)) { + release(spec.id); + continue; + } // A fixed-size row is a size that never changes across resizes, not a // separate code path past this one branch: the held-size comparison // and `allocate` call below stay shared with every other row. + const fixed = spec.fixedSizePx ? resolveFixedSize(spec.fixedSizePx, s) : 0; const [width, height] = spec.fixedSizePx - ? [resolveFixedSize(spec.fixedSizePx, s), resolveFixedSize(spec.fixedSizePx, s)] + ? [fixed, fixed] : reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s)); const held = sizes.get(spec.id); if (held !== undefined && held.width === width && held.height === height) continue; diff --git a/tests/services/engine/animation/playClipFlyout.integration.test.ts b/tests/services/engine/animation/playClipFlyout.integration.test.ts index bff73e9531..9dd611d921 100644 --- a/tests/services/engine/animation/playClipFlyout.integration.test.ts +++ b/tests/services/engine/animation/playClipFlyout.integration.test.ts @@ -121,7 +121,7 @@ function makeEngineState(startDistance: number): { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/camera/commitOnEdge.test.ts b/tests/services/engine/camera/commitOnEdge.test.ts index 1d35f34ebc..215178ff23 100644 --- a/tests/services/engine/camera/commitOnEdge.test.ts +++ b/tests/services/engine/camera/commitOnEdge.test.ts @@ -97,7 +97,7 @@ function makeEngineState(): { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index 1e5f797cd1..9b6347d001 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -43,7 +43,7 @@ function makeCaptureRuntime() { return { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }; } @@ -74,7 +74,9 @@ function makeCtx(drawCamPos: readonly [number, number, number]): ReadyFrameConte nowMs: 1000, focus: {}, slabs: [], + canvasSize: { width: 800, height: 600 }, renderTargets: { + reconcile: vi.fn(), specOf: (id: string) => { if (id === 'sky-cubemap') return { fixedSizePx: { size: 256, layers: 6 } }; if (id === 'swap') return { format: 'bgra8unorm' }; @@ -178,6 +180,28 @@ describe('renderFrame — sky-cubemap runtime hand-off', () => { expect(handedOff.size).toBe(0); }); + // The sky-cubemap row is lazily allocated off `bandActive`, and the frame + // that opens the band is the frame that sweeps all six faces — so the row + // has to be reconciled into existence BEFORE this frame reads it, and + // reconciled away again when the band closes. + it('reconciles the render targets on the band edge, and only on the edge', () => { + const state = makeState(); + const inBand = makeCtx(SGR_A_STAR_ANCHOR.positionMpc); + renderFrame(makeInput(inBand, state)); + expect(inBand.renderTargets.reconcile).toHaveBeenCalledTimes(1); + expect(state.cameraRuntime.skyCubemapCapture.bandActive).toBe(true); + + // Still in-band: nothing about the row's existence changed. + const stillInBand = makeCtx(SGR_A_STAR_ANCHOR.positionMpc); + renderFrame(makeInput(stillInBand, state)); + expect(stillInBand.renderTargets.reconcile).not.toHaveBeenCalled(); + + const outOfBand = makeCtx([1000, 0, 0]); + renderFrame(makeInput(outOfBand, state)); + expect(outOfBand.renderTargets.reconcile).toHaveBeenCalledTimes(1); + expect(state.cameraRuntime.skyCubemapCapture.bandActive).toBe(false); + }); + it('round-robin faces reuse the PINNED eye, not the live camera, after a sub-threshold move (fix round 3)', () => { skyCubemapFaceContextMock.mockImplementation( (input: { face: CubeFace }) => ({ __face: input.face }) as unknown as ReadyFrameContext, diff --git a/tests/services/engine/frame/renderFrame.test.ts b/tests/services/engine/frame/renderFrame.test.ts index fcb1e6d219..1ceda22f18 100644 --- a/tests/services/engine/frame/renderFrame.test.ts +++ b/tests/services/engine/frame/renderFrame.test.ts @@ -579,7 +579,7 @@ function makeInput( skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/frame/renderFrame.timing.test.ts b/tests/services/engine/frame/renderFrame.timing.test.ts index c524f56254..c2c536a49e 100644 --- a/tests/services/engine/frame/renderFrame.timing.test.ts +++ b/tests/services/engine/frame/renderFrame.timing.test.ts @@ -378,7 +378,7 @@ function makeMinimalInputWithTiming(timingService: GpuTimingService): { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }, diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index b229b20bdf..00ed17ff94 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -36,15 +36,20 @@ const MW_DIVISOR = 2; // tests that don't care about the sky-cubemap row itself. const SKY_CUBEMAP_RESOLUTION_PX = 256; +// The production `sky-cubemap` row is lazy: its `allocateWhen` reads the +// lensing band flag `renderFrame` maintains, so every state fixture carries +// one. Default `true` keeps the row present for the tests that count textures. function stateWithDivisor( aggregateDivisor: number, cubemapResolutionPx: number = SKY_CUBEMAP_RESOLUTION_PX, + bandActive = true, ): EngineState { return { settings: { milkyWay: { aggregateDivisor }, sgrAStarLensingTuning: { cubemapResolutionPx }, }, + cameraRuntime: { skyCubemapCapture: { bandActive } }, } as unknown as EngineState; } @@ -232,6 +237,46 @@ describe('createRenderTargets', () => { expect(targets.cubeViewOf('test:state-cubemap')).not.toBe(cubeViewBefore); }); + // The lens's 50 MB cubemap must not sit in VRAM on a machine that never + // goes near Sgr A*, and must be back before the band-entry frame reads it. + it('an allocateWhen row holds no texture until its condition turns true, and is released when it turns false', () => { + const device = mockDevice(); + const create = device.createTexture as ReturnType; + const canvas = { width: 900, height: 600 }; + const targets = createRenderTargets( + device, + SWAP_FORMAT, + canvas, + stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, false), + ); + const cubemapCalls = (): number[] => + create.mock.calls + .map((c, i) => (c[0].label === 'render-target-sky-cubemap' ? i : -1)) + .filter((i) => i >= 0); + + // Booted outside the band: no texture, and every reader throws rather + // than handing back something stale. + expect(cubemapCalls()).toHaveLength(0); + expect(() => targets.sizeOf('sky-cubemap')).toThrow(); + expect(() => targets.cubeViewOf('sky-cubemap')).toThrow(); + + targets.reconcile(stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, true), canvas); + + expect(cubemapCalls()).toHaveLength(1); + expect(create.mock.calls[cubemapCalls()[0]!]![0].size).toEqual({ + width: SKY_CUBEMAP_RESOLUTION_PX, + height: SKY_CUBEMAP_RESOLUTION_PX, + depthOrArrayLayers: 6, + }); + expect(targets.cubeViewOf('sky-cubemap')).toBeDefined(); + const texture = create.mock.results[cubemapCalls()[0]!]!.value; + + targets.reconcile(stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, false), canvas); + + expect(texture.destroy).toHaveBeenCalled(); + expect(() => targets.cubeViewOf('sky-cubemap')).toThrow(); + }); + it("reconcile reallocates a row whose state-driven scale moved and leaves the other rows' views untouched", () => { const device = mockDevice(); const create = device.createTexture as ReturnType; diff --git a/tests/visual/renderFrameSplitBaseline.test.ts b/tests/visual/renderFrameSplitBaseline.test.ts index 7fafc21dfe..c4c4d01a79 100644 --- a/tests/visual/renderFrameSplitBaseline.test.ts +++ b/tests/visual/renderFrameSplitBaseline.test.ts @@ -506,7 +506,7 @@ describe('renderFrame visual baseline', () => { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, - wasBandActive: false, + bandActive: false, pinnedEyeMpc: null, }, }, From 82e8e0fce674349df03f2263ae8c22874a4a2163 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 01:19:09 +0200 Subject: [PATCH 52/60] fix(black-hole): knee the aggregate glow on sky-cubemap capture faces The spec's capture roster composites the Gaia stream "the same way star-upsample already does", but the aggregate stream wrote its raw linear glow straight into the face: the knee lives in star-upsample, which runs over the half-res offscreen and has no counterpart behind a capture face. Captured aggregate glows were therefore brighter and more saturated than the same stars in the direct view drawn beside them at the band crossfade. Un-braids the two things `StarDrawStream` was deciding at once: `stream` still picks the node set and the buffer pair, and a new `knee` arg picks the fragment entry point. The aggregate stream asks for the knee at deposit exactly when it draws into a capture face. Co-Authored-By: Claude Fable 5 --- .../specs/2026-09-01-render-black-hole-design.md | 4 +++- src/@types/rendering/StarCatalogRenderer.d.ts | 12 ++++++++++-- .../engine/frame/passes/starAggregatesLayer.ts | 10 +++++----- .../engine/frame/passes/starCatalogLayer.ts | 8 ++++++++ .../renderers/starCatalog/starCatalogRenderer.ts | 12 ++++++++---- .../frame/passes/starAggregatesLayer.test.ts | 16 ++++++++++++++++ .../starCatalogRenderer.frustumCull.test.ts | 1 + .../starCatalogRenderer.viewSlot.test.ts | 1 + 8 files changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md index 4e3761bca8..83fac809cf 100644 --- a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md +++ b/docs/superpowers/specs/2026-09-01-render-black-hole-design.md @@ -305,7 +305,9 @@ elsewhere on screen. **What gets captured (Q5, Q8):** an explicit opt-in roster — `point-sprites` (galaxy points), the Gaia survey stream (`star-catalog` + `star-aggregates`, -composited the same way `star-upsample` already does), and whichever +composited the same way `star-upsample` already does — implemented as the +knee at deposit, since a capture face has no half-res offscreen or upsample +pass of its own), and whichever partition branch is currently rendering the S-stars (their apparent size at GC-relative framing puts them in the `bodyGlints`/`planets`/`starSpheres` branch of the body/star partition machinery, filtered to S-star ids). Never diff --git a/src/@types/rendering/StarCatalogRenderer.d.ts b/src/@types/rendering/StarCatalogRenderer.d.ts index f9b7121274..0af1cb511a 100644 --- a/src/@types/rendering/StarCatalogRenderer.d.ts +++ b/src/@types/rendering/StarCatalogRenderer.d.ts @@ -55,11 +55,19 @@ export type StarCatalogDrawArgs = { /** Which loaded catalog's records buffer to bind. */ readonly source: SourceType; /** - * Which draw stream this call records — selects the fragment pipeline (leaf = - * knee'd into HDR, aggregate = linear into the half-res offscreen) and the + * Which draw stream this call records — selects the node set and the * per-source buffer pair the params are uploaded to. */ readonly stream: StarDrawStream; + /** + * Whether the fragment stage applies the hue-preserving knee at deposit + * (`fs`) or writes the linear glow plus its raw scalar for a later composite + * to knee (`fsLinear`). Separate from `stream` because the aggregate stream + * needs BOTH: linear into the half-res offscreen its knee'd upsample + * composites, but knee'd when it draws into a sky-cubemap capture face, + * which has no upsample pass behind it and is sampled as the sky itself. + */ + readonly knee: boolean; /** Rebased camera-relative view-projection (`narrowMat4(rebaseViewProj(...))`). */ readonly vp: Float32Array; /** Viewport size in physical pixels — feeds the pixel-size-to-clip conversion. */ diff --git a/src/services/engine/frame/passes/starAggregatesLayer.ts b/src/services/engine/frame/passes/starAggregatesLayer.ts index 7e034b7385..a1d0e17cf7 100644 --- a/src/services/engine/frame/passes/starAggregatesLayer.ts +++ b/src/services/engine/frame/passes/starAggregatesLayer.ts @@ -38,11 +38,11 @@ export const starAggregatesLayer: ContentLayer = { slab: NEAR0, target: 'star-aggregates', blend: 'additive', - // Sky-cubemap capture roster (Task 13b, Ruling 6): the survey AGGREGATE - // stream is part of the black-hole lens's captured "sky", drawn straight - // into the capture target (a capture step selects by this flag, not by - // `target` — see `executeFrame`'s capture-step branch) rather than through - // its usual half-res-offscreen + knee'd upsample. + // Sky-cubemap capture roster: the survey AGGREGATE stream is part of the + // black-hole lens's captured "sky", drawn straight into the capture target + // (a capture step selects by this flag, not by `target` — see + // `executeFrame`'s capture-step branch) rather than through its usual + // half-res offscreen. Its knee moves to deposit time there — `drawStream`. skyCapture: true, enabled: starCatalogVisible, diff --git a/src/services/engine/frame/passes/starCatalogLayer.ts b/src/services/engine/frame/passes/starCatalogLayer.ts index e45ee30c55..8fbdc7b3ab 100644 --- a/src/services/engine/frame/passes/starCatalogLayer.ts +++ b/src/services/engine/frame/passes/starCatalogLayer.ts @@ -879,12 +879,20 @@ function drawStream( // and forwarded identically to every source's draw (the shared-vp invariant). const frustumPlanes = frustumPlanesFromViewProj(rebasedVp, frustumScratch); const glowMarginAngleRad = starCullMargins(prep.sizePx, view.viewportPx[1], fovYRad).leaf; + // The aggregate stream's knee normally lands in `star-upsample`, over the + // summed half-res field. A sky-cubemap capture face (`viewSlot !== 0`) has + // no such pass behind it — the face IS the sky the lens samples — so the + // aggregate quads carry the knee themselves there, or captured glows read + // brighter and more saturated than the same stars in the direct view drawn + // beside them at the band crossfade. + const knee = stream === 'leaf' || viewSlot !== 0; for (const s of prep.sources) { const nodes = s[stream]; if (nodes.count === 0) continue; renderer.draw(pass, { source: s.source, stream, + knee, vp: rebasedVp, viewportPx: view.viewportPx, drawCount: nodes.count, diff --git a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts index 461e7c081f..e805630d5e 100644 --- a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts +++ b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts @@ -255,9 +255,12 @@ export function createStarCatalogRenderer( // NO depthStencil: neither the hdr nor the star-aggregates target has depth. }); } - const pipelines: Record = { - leaf: makePipeline('star-catalog-leaf-pipeline', 'fs'), - aggregate: makePipeline('star-catalog-aggregate-pipeline', 'fsLinear'), + // Keyed by COMPRESSION, not by stream: the aggregate stream takes the + // knee'd pipeline when it draws somewhere the knee'd upsample can't follow + // it (a sky-cubemap capture face — see `StarCatalogDrawArgs.knee`). + const pipelines = { + kneed: makePipeline('star-catalog-leaf-pipeline', 'fs'), + linear: makePipeline('star-catalog-aggregate-pipeline', 'fsLinear'), }; // ── Per-source store ────────────────────────────────────────────────────── @@ -392,6 +395,7 @@ export function createStarCatalogRenderer( const { source, stream, + knee, vp, viewportPx, drawCount, @@ -541,7 +545,7 @@ export function createStarCatalogRenderer( ], }); - pass.setPipeline(pipelines[stream]); + pass.setPipeline(knee ? pipelines.kneed : pipelines.linear); pass.setBindGroup(0, cameraRing.bindGroupOf(viewSlot)); pass.setBindGroup(1, drawBindGroup); pass.setBindGroup(2, entry.recordsBindGroup); diff --git a/tests/services/engine/frame/passes/starAggregatesLayer.test.ts b/tests/services/engine/frame/passes/starAggregatesLayer.test.ts index 686f4c6da8..0e595d3a30 100644 --- a/tests/services/engine/frame/passes/starAggregatesLayer.test.ts +++ b/tests/services/engine/frame/passes/starAggregatesLayer.test.ts @@ -152,6 +152,22 @@ describe('starAggregatesLayer', () => { expect(args.viewportPx).toEqual([256, 256]); }); + // The aggregate glow is kneed by `star-upsample` over the summed half-res + // field. A capture face has no upsample behind it, so an un-kneed capture + // would make the lensed sky brighter than the direct view beside it. + it('draws linear into the offscreen but kneed into a sky-cubemap face', () => { + const renderer = makeRenderer([{ source: Source.GaiaStars, catalog: makeAggregateCatalog() }]); + const camPos = camAtPcVec(FAR_PC); + const view = makeNear0View(camPos); + const state = makeState(renderer); + + starAggregatesLayer.draw(PASS_STUB, view, makeCtx(camPos), state); + expect(renderer.draw.mock.calls[0]![1].knee).toBe(false); + + starAggregatesLayer.draw(PASS_STUB, view, makeCtx(camPos, 0, 1), state); + expect(renderer.draw.mock.calls[1]![1].knee).toBe(true); + }); + it('is a no-op when the renderer handle is null (pre-bootstrap)', () => { const camPos = camAtPcVec(FAR_PC); const state = makeState(null); diff --git a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts index bbfdce97b1..3671a388b4 100644 --- a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts +++ b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.frustumCull.test.ts @@ -83,6 +83,7 @@ function twoNodeArgs( return { source: Source.GaiaStars, stream: 'leaf', + knee: true, vp: new Float32Array(16), viewportPx: [1280, 720], drawCount: 2, diff --git a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts index fcc426c9da..be611fb7d6 100644 --- a/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts +++ b/tests/services/gpu/renderers/starCatalog/starCatalogRenderer.viewSlot.test.ts @@ -45,6 +45,7 @@ function oneNodeArgs(viewSlot: number): StarCatalogDrawArgs { return { source: Source.GaiaStars, stream: 'leaf', + knee: true, vp: new Float32Array(16), viewportPx: [1280, 720], drawCount: 1, From 326d5223fc9a54faf69e586bd4056f856b7a18e8 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 01:33:09 +0200 Subject: [PATCH 53/60] refactor(black-hole): review minors from the whole-branch pass MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - packSgrAStarLensingUniforms takes a named bag: 17 of its 22 positional args were bare numbers, so a transposition would type-check and pass the offset parity test. - The lens flicker phase keys on the SIM clock (spec §Data), wrapped into [0, 2pi) in f64 — a paused clock now holds the flicker still, and the raw phase at a J2000 epoch is far past f32's resolution. - bodyGlintsLayer addresses Sgr A* directly instead of looping over SCENE_ANCHOR_POINT_BODIES with Sgr A*'s own band and tint; drops the `states.get(...)!` throw path, and corrects the backdropFade invariant comment the anchor widening falsified. - Per-layer GPU timing slots carry the capture face, and timedSlotRowsOf emits the matching rows, so a capture pass and the real (hdr, NEAR0) pass no longer overwrite each other's ?gpuTimings numbers. - renderFrame hoists the galactic-centre region lookup; skyCubemapFaceContext takes the frame's nowMs instead of sampling performance.now() itself; createViewSlotUniformRing throws a named error on an out-of-range slot; the dead draw-side bandAlpha early-out goes. - Tests: the scaleFadeBands case pins direction + monotonicity off the band itself instead of restating its edges, and a new case pins the instance-bytes invariant the un-ringed textured-disk instance buffer rests on. Co-Authored-By: Claude Fable 5 --- ...6-09-02-lens-crossfade-duplicate-points.md | 8 +- src/services/engine/frame/executeFrame.ts | 2 +- src/services/engine/frame/frameProgram.ts | 21 ++-- .../engine/frame/passes/bodyGlintsLayer.ts | 45 ++++---- .../frame/passes/sgrAStarLensingLayer.ts | 56 +++++----- src/services/engine/frame/renderFrame.ts | 8 +- .../engine/frame/skyCubemapFaceContext.ts | 7 +- src/services/engine/frame/slabs.ts | 11 +- src/utils/gpu/createViewSlotUniformRing.ts | 10 ++ src/utils/gpu/packSgrAStarLensingUniforms.ts | 101 ++++++++++-------- .../frame/skyCubemapFaceContext.test.ts | 21 +++- .../presentation/scaleFadeBands.test.ts | 36 +++---- .../texturedDiskRenderer.test.ts | 33 ++++++ .../gpu/packSgrAStarLensingUniforms.test.ts | 48 ++++----- ...rAStarLensingUniformsLayout.parity.test.ts | 4 +- 15 files changed, 258 insertions(+), 153 deletions(-) diff --git a/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md b/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md index a2817c724c..1807f28657 100644 --- a/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md +++ b/docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md @@ -1,11 +1,11 @@ # Lens crossfade handoff shows subtle duplicate points -**Reported:** 2026-09-02, user eyeball during the Sgr A* black-hole close-up landing +**Reported:** 2026-09-02, user eyeball during the Sgr A\* black-hole close-up landing (branch worktree-render-black-hole). ## Symptom -While the camera crosses the black-hole fade band (~500 → 100 AU from Sgr A*), +While the camera crosses the black-hole fade band (~500 → 100 AU from Sgr A\*), the sky briefly shows subtle doubled points: each star/galaxy appears once from the direct-view roster layers and once from the lensed sky-cubemap the lens quad blends in on top. Fully outside or fully inside the band the sky is single. @@ -31,6 +31,6 @@ one — hence doubles rather than a clean brightness ramp. ## Pointers - Band definition + alpha: `SCALE_FADE_BANDS` row for `sgr-a-star` (T7). -- Step split predicate: `src/services/engine/frame/slabs.ts` / - `visibleSlabBodies.ts` (`matchesLensPhase`). +- Step split predicate: `matchesLensPhase` in + `src/services/engine/frame/slabs.ts`. - Lens quad edge fade: `sgrAStarLensing/fragment.wesl` (`edgeFadeEndRs`). diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 7c11d25fd1..21bb9d817e 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -436,7 +436,7 @@ function renderGroup( // others' timestamps (see `layerTimingSlotName`'s doc, slabs.ts). group.forEach((layer, i) => { const touchedBefore = alreadyTouched || i > 0; - const slot = layerTimingSlotName(layer.name, view.slab.index); + const slot = layerTimingSlotName(layer.name, view.slab.index, face); const pass = encoder.beginRenderPass({ label: `render-${target}-${slot}`, colorAttachments: [colorAttachment(ctx, target, targetView, touchedBefore)], diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index 107d2100b8..df0470822b 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -392,6 +392,10 @@ function timedSlotRowsOf( // partitions the registry between them), so no per-layer dedup is // needed; only the group-TOTAL row below needs the split disambiguated. const groupKey = groupKeyOf(step.target, step.slab); + // A capture step selects its group by the `skyCapture` opt-in, not by + // `target` — the same discriminant `executeFrame` applies, so the slots + // allocated here are exactly the ones its per-layer passes look up. + const isCaptureStep = step.face !== undefined; for (const layer of layers) { // A 'body' layer has no fixed slab index — it matches every body-row // step, the same widening `executeFrame` applies via @@ -401,16 +405,21 @@ function timedSlotRowsOf( // same fact (slabs.ts). const matchesStep = layer.slab === step.slab || (layer.slab === 'body' && isBodySlabIndex(step.slab)); + const matchesTarget = isCaptureStep + ? layer.skyCapture === true + : layer.target === step.target; if ( - layer.target === step.target && + matchesTarget && matchesStep && matchesLensPhase(layer.hdrPostLensing, step.lensPhase) ) { - // `layerTimingSlotName` carries the row into the slot NAME for a body - // step, so two body rows sharing one layer (Jupiter + a moon, both - // drawn by `planetsLayer`) each get their own query-set slot instead - // of colliding on the same two indices (see its doc, slabs.ts). - rows.push({ name: layerTimingSlotName(layer.name, step.slab), groupKey }); + // `layerTimingSlotName` carries the body row and the capture face + // into the slot NAME, so two body rows sharing one layer (Jupiter + + // a moon, both drawn by `planetsLayer`) — or one roster layer drawn + // once per captured face and once for the real view — each get their + // own query-set slot instead of colliding on the same two indices + // (see its doc, slabs.ts). + rows.push({ name: layerTimingSlotName(layer.name, step.slab, step.face), groupKey }); } } // One extra slot per render STEP whose NAME is the groupKey itself, so diff --git a/src/services/engine/frame/passes/bodyGlintsLayer.ts b/src/services/engine/frame/passes/bodyGlintsLayer.ts index 13cd7bb153..ed3cb212f9 100644 --- a/src/services/engine/frame/passes/bodyGlintsLayer.ts +++ b/src/services/engine/frame/passes/bodyGlintsLayer.ts @@ -11,8 +11,8 @@ * where sub-pixel bodies simply vanished (the mesh culled them and nothing drew * the glint) is closed here. * - * A SECOND, independent source rides the same buffer: `SCENE_ANCHOR_POINT_BODIES` - * (today, only Sgr A*). An anchor never resolves to a mesh, so the partition's + * A SECOND, independent source rides the same buffer: Sgr A*, the one scene + * anchor. An anchor never resolves to a mesh, so the partition's * XOR doesn't apply to it — it gets its own fixed tint/intensity, crossfading * OUT as the black-hole lens pass engages on close approach, with none of the * seeded glints' apparent-size or solar-system-backdrop fades (it is meant to @@ -79,7 +79,7 @@ import { NEAR0 } from '../slabs'; import { RENDER_ORIGIN_MPC } from '../../../../data/renderOrigin'; import { Source } from '../../../../data/sources'; import { SCENE_PLANETS } from '../../../../data/bodies/scenePlanets'; -import { SCENE_ANCHOR_POINT_BODIES } from '../../../../data/bodies/sceneAnchorPointBodies'; +import { SGR_A_STAR } from '../../../../data/bodies/sceneSgrAStar'; import { packSelection, PICK_SENTINEL_OFFSET } from '../../../../data/selectionEncoding'; import { sceneBodyPartition } from '../sceneBodyPartition'; import { sceneBodyStates } from '../sceneBodyStates'; @@ -176,7 +176,7 @@ export const bodyGlintsLayer: ContentLayer = { if (ctx.cam.distance >= FOREGROUND_MAX_DISTANCE_MPC) return false; const states = sceneBodyStates(state, ctx); // Sgr A*'s far-field glint is unconditional on the solar-system backdrop - // (SCENE_ANCHOR_POINT_BODIES never resolves to a mesh, so the near/far + // (a scene anchor never resolves to a mesh, so the near/far // dissolves built for the seeded planets don't apply — module header), so // it is checked BEFORE that gate: an empty `glints` partition, or a camera // the backdrop has already dissolved, must not drop the row while the @@ -236,8 +236,9 @@ export const bodyGlintsLayer: ContentLayer = { // glint shares one camera), so it is hoisted OUT of the per-body loop. It // scales every glint's brightness so the whole sub-pixel body field dissolves // as the camera pulls back from the solar system, mirroring - // `starPointsLayer`'s backdrop fade. `enabled` already dropped the layer once - // this hit 0, so here it is > 0. + // `starPointsLayer`'s backdrop fade. May be 0 when only the Sgr A* anchor + // glint keeps the layer alive (`enabled`'s widening); the seeded glints + // then all fall out on the `GLINT_MIN_BRIGHTNESS` skip below. const backdropFade = fadeBand( SCALE_FADE_BANDS.bodyGlintBackdrop, regionRelativeDistanceMpc(camPos, GLINT_BACKDROP_REGION, states), @@ -283,24 +284,28 @@ export const bodyGlintsLayer: ContentLayer = { } // A second, independent packed source, appended to the SAME buffer/count: - // Sgr A*'s far-field glint. SCENE_ANCHOR_POINT_BODIES never resolves to a - // mesh, so it isn't part of `glints` and carries none of the seeded - // bodies' apparent-size or backdrop terms — see the module header and - // `sgrAStarGlintBrightness`. - for (const anchor of SCENE_ANCHOR_POINT_BODIES) { - if (count >= MAX_GLINTS) break; - const brightness = sgrAStarGlintBrightness(camPos, states); - if (brightness <= GLINT_MIN_BRIGHTNESS) continue; - - const anchorPositionMpc = states.get(anchor.id)!.positionMpc; + // Sgr A*'s far-field glint. It never resolves to a mesh, so it isn't part + // of `glints` and carries none of the seeded bodies' apparent-size or + // backdrop terms — see the module header and `sgrAStarGlintBrightness`. + // Addressed directly rather than looped over `SCENE_ANCHOR_POINT_BODIES`: + // the brightness band and the tint below are Sgr A*'s own, so a second + // anchor row would silently inherit them. Give the second anchor its own + // band + tint on its data row when there is one. + const sgrAStarState = states.get(SGR_A_STAR.id); + const anchorBrightness = sgrAStarGlintBrightness(camPos, states); + if ( + count < MAX_GLINTS && + sgrAStarState !== undefined && + anchorBrightness > GLINT_MIN_BRIGHTNESS + ) { const base = count * INSTANCE_FLOATS; - staging[base + 0] = anchorPositionMpc[0] - camPos[0]; - staging[base + 1] = anchorPositionMpc[1] - camPos[1]; - staging[base + 2] = anchorPositionMpc[2] - camPos[2]; + staging[base + 0] = sgrAStarState.positionMpc[0] - camPos[0]; + staging[base + 1] = sgrAStarState.positionMpc[1] - camPos[1]; + staging[base + 2] = sgrAStarState.positionMpc[2] - camPos[2]; staging[base + 3] = SGR_A_STAR_GLINT_TINT[0]; staging[base + 4] = SGR_A_STAR_GLINT_TINT[1]; staging[base + 5] = SGR_A_STAR_GLINT_TINT[2]; - staging[base + 6] = brightness; + staging[base + 6] = anchorBrightness; count++; } if (count === 0) return; diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 3c1bab3135..cb74f71355 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -44,6 +44,9 @@ if (BLACK_HOLES.find((row) => row.bodyId === SGR_A_STAR.id) === undefined) { const SCHWARZSCHILD_RADIUS_M = schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR); +/** `ctx.simDays` is Julian days; `flickerTimescaleS` is seconds. */ +const SECONDS_PER_DAY = 86_400; + /** This frame's fade-band alpha (Q6's zero-dispatch gate) — shared by `enabled` and `draw`. */ function bandAlphaFor(state: EngineState, ctx: ReadyFrameContext): number { const distMpc = regionRelativeDistanceMpc( @@ -78,8 +81,9 @@ export const sgrAStarLensingLayer: ContentLayer = { const pose = ctx.bodyPose(view.slab.frame.bodyId); if (pose === null) return; + // `> 0` by construction: `enabled` gates on it, and `frameProgram` only + // emits this step at all while the band is open. const bandAlpha = bandAlphaFor(state, ctx); - if (bandAlpha <= 0) return; // "opacity 0 ⇒ no render" house rule // Sgr A*'s position relative to the camera, in the SAME body-local frame // `view.slab.vp` was built in (camera at the origin) — the negation of @@ -92,11 +96,15 @@ export const sgrAStarLensingLayer: ContentLayer = { -pose.eyeRelBodyM[2], ]; - // `flickerPhase` must divide by the SAME `flickerTimescaleS` the packed - // uniform carries, or a live slider drag desyncs the phase from the - // period it packs. + // Keyed on the SIM clock, so a paused clock holds the flicker still and + // time-scrubbing carries it (spec §Data). Divides by the SAME + // `flickerTimescaleS` the packed uniform carries, or a live slider drag + // desyncs the phase from the period it packs. Wrapped into [0, 2π) HERE, + // in f64: the raw phase is ~1e9 rad at J2000 epochs, which an f32 uniform + // could not resolve to a fraction of a cycle. const tuning = state.settings.sgrAStarLensingTuning; - const flickerPhase = (2 * Math.PI * (ctx.nowMs / 1000)) / tuning.flickerTimescaleS; + const simSeconds = ctx.simDays * SECONDS_PER_DAY; + const flickerPhase = ((2 * Math.PI * simSeconds) / tuning.flickerTimescaleS) % (2 * Math.PI); // Where the escape fade must reach zero: weak-field deflection is 2/b rad // (b in r_s), so it drops below one screen pixel at b = 2·drawPxPerRad. @@ -120,30 +128,30 @@ export const sgrAStarLensingLayer: ContentLayer = { // interpolation shook every ray — see lensQuadPlaneRadiusRs's docblock. const quadPlaneRadiusRs = lensQuadPlaneRadiusRs(edgeFadeEndRs, distRs); - const uniforms = packSgrAStarLensingUniforms( - view.vp, - view.viewportPx, - SCHWARZSCHILD_RADIUS_M, - tuning.innerRs, - tuning.outerRs, - tuning.inclinationRad, - tuning.positionAngleRad, - tuning.flickerAmp, - tuning.flickerTimescaleS, + const uniforms = packSgrAStarLensingUniforms({ + viewProj: view.vp, + viewportPx: view.viewportPx, + schwarzschildRadiusM: SCHWARZSCHILD_RADIUS_M, + innerRs: tuning.innerRs, + outerRs: tuning.outerRs, + inclinationRad: tuning.inclinationRad, + positionAngleRad: tuning.positionAngleRad, + flickerAmp: tuning.flickerAmp, + flickerTimescaleS: tuning.flickerTimescaleS, flickerPhase, - renderer.lut.minImpactParamRs, - renderer.lut.maxImpactParamRs, - renderer.lut.samples.length, + lutMinImpactParamRs: renderer.lut.minImpactParamRs, + lutMaxImpactParamRs: renderer.lut.maxImpactParamRs, + lutSampleCount: renderer.lut.samples.length, bandAlpha, anchorPosRelCamM, - tuning.diskScaleHeightRs, - tuning.edgeFadeStartFraction, - tuning.dopplerStrength, - tuning.emissionStrength, + diskScaleHeightRs: tuning.diskScaleHeightRs, + edgeFadeStartFraction: tuning.edgeFadeStartFraction, + dopplerStrength: tuning.dopplerStrength, + emissionStrength: tuning.emissionStrength, edgeFadeEndRs, - tuning.emissionTint, + emissionTint: tuning.emissionTint, quadPlaneRadiusRs, - ); + }); const skyCubemapView = ctx.renderTargets.cubeViewOf('sky-cubemap'); renderer.draw(pass, uniforms, skyCubemapView); diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 00b7e5e7e6..444176de69 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -70,6 +70,11 @@ import { fadeBand } from '../../../utils/math/fadeBand'; import { SCALE_FADE_BANDS } from '../presentation/scaleFadeBands'; import { SGR_A_STAR } from '../../../data/bodies/sceneSgrAStar'; +// Hoisted rather than resolved per frame (a linear `.find` over `BODY_REGIONS`), +// matching the other two consumers of the same lookup — `sgrAStarLensingLayer` +// and `bodyGlintsLayer`. +const GALACTIC_CENTRE_REGION = regionById('galactic-centre'); + /** * Encode and submit one frame. Synchronous: by the time it returns, the GPU * has the buffer queued. Order of operations is the `frameProgram` step list @@ -117,7 +122,7 @@ export function renderFrame(input: RenderFrameInput): void { const captureRuntime = state.cameraRuntime.skyCubemapCapture; const gcDistanceMpc = regionRelativeDistanceMpc( ctx.drawCamPos, - regionById('galactic-centre'), + GALACTIC_CENTRE_REGION, sceneBodyStates(state, ctx), ); const bandActive = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, gcDistanceMpc) > 0; @@ -214,6 +219,7 @@ export function renderFrame(input: RenderFrameInput): void { eyeMpc: pinnedEyeMpc, face, faceSizePx, + nowMs: ctx.nowMs, }); if (faceCtx !== null) skyCubemapFaceContexts.set(face, faceCtx); } diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts index 5c5a36ebe1..598bb2a1c6 100644 --- a/src/services/engine/frame/skyCubemapFaceContext.ts +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -94,8 +94,11 @@ export function skyCubemapFaceContext(input: { readonly eyeMpc: Readonly; readonly face: CubeFace; readonly faceSizePx: number; + /** The FRAME's stamped clock, so a roster layer that animates on `nowMs` + * ticks identically on a captured face and in the direct view. */ + readonly nowMs: number; }): ReadyFrameContext | null { - const { state, eyeMpc, face, faceSizePx } = input; + const { state, eyeMpc, face, faceSizePx, nowMs } = input; const forward = FACE_FORWARD[face]!; const basis = FACE_BASES[face]!; // target = eyeMpc + forward, distance = 1: `updatePosition` then derives @@ -122,7 +125,7 @@ export function skyCubemapFaceContext(input: { basis, // Draw mask, not pick: this is a real capture pass, not a click target. deriveSourceMasks(state).draw, - performance.now(), + nowMs, state.cameraRuntime.lastRenderedSimDays.current, ); if (!ctx.isReady) return null; diff --git a/src/services/engine/frame/slabs.ts b/src/services/engine/frame/slabs.ts index 6f4758f76b..e712be5a77 100644 --- a/src/services/engine/frame/slabs.ts +++ b/src/services/engine/frame/slabs.ts @@ -91,14 +91,19 @@ export function groupKeyOf(target: string, slab: number): string { * `layerName` for NEAR0/COSMO (one instance per frame, already unique), or * `'·BODY[k]'` for a body row, so two body rows sharing one * `'body'`-slab layer (e.g. `planetsLayer` drawing Jupiter AND a moon) don't - * collide on the same query-set index pair. `timedSlotRowsOf` + * collide on the same query-set index pair. A capture step's `face` appends + * the same way and for the same reason: a roster layer draws once per + * captured face AND once for the real view, all on `(hdr|sky-cubemap, NEAR0)` + * — without the face, all seven passes would attach the same query pair and + * the last one silently overwrite the rest. `timedSlotRowsOf` * (frameProgram.ts, the build-time slot-list/query-set-size derivation) and * `executeFrame`'s `perLayerTimed` pass (the runtime `descriptorFor` lookup) * both call this, so the allocated slot and the looked-up slot can never * drift apart. */ -export function layerTimingSlotName(layerName: string, slabIndex: number): string { - return isBodySlabIndex(slabIndex) ? `${layerName}·${slabName(slabIndex)}` : layerName; +export function layerTimingSlotName(layerName: string, slabIndex: number, face?: number): string { + const base = isBodySlabIndex(slabIndex) ? `${layerName}·${slabName(slabIndex)}` : layerName; + return face === undefined ? base : `${base}·FACE[${face}]`; } /** diff --git a/src/utils/gpu/createViewSlotUniformRing.ts b/src/utils/gpu/createViewSlotUniformRing.ts index 2c617152a5..1718e71f72 100644 --- a/src/utils/gpu/createViewSlotUniformRing.ts +++ b/src/utils/gpu/createViewSlotUniformRing.ts @@ -59,11 +59,21 @@ export function createViewSlotUniformRing(init: { ); } + // Loud on an out-of-range slot rather than a bare `TypeError` out of + // `queue.writeBuffer` — same discipline as `renderTargets.viewOf`. + function slotInRange(slot: number): void { + if (slot < 0 || slot >= slotCount) { + throw new Error(`${label}: view slot ${slot} out of range (${slotCount} slots)`); + } + } + function writeSlot(slot: number, data: BufferSource): void { + slotInRange(slot); device.queue.writeBuffer(buffers[slot]!, 0, data); } function bindGroupOf(slot: number): GPUBindGroup { + slotInRange(slot); return bindGroups[slot]!; } diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index e705162e20..b3adb98a94 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -47,28 +47,13 @@ * plausible LUT size, so there is no precision reason to special-case a * `u32` write into this otherwise-uniform `Float32Array`). * - * @param viewProj 16-element column-major view-projection, already camera-rebased. - * @param viewportPx Viewport size in device pixels. - * @param schwarzschildRadiusM r_s in metres — the pass's own scale unit. - * @param innerRs Emission annulus inner edge, r_s units. - * @param outerRs Emission annulus outer edge, r_s units. - * @param inclinationRad Disk inclination, radians. - * @param positionAngleRad Disk position angle, radians. - * @param flickerAmp Emission flicker amplitude. - * @param flickerTimescaleS Emission flicker timescale, seconds. - * @param flickerPhase Sim-clock-derived flicker phase, uploaded per frame. - * @param lutMinImpactParamRs `SchwarzschildDeflectionLut.minImpactParamRs`. - * @param lutMaxImpactParamRs `SchwarzschildDeflectionLut.maxImpactParamRs`. - * @param lutSampleCount The LUT texture's texel count. - * @param bandAlpha This frame's fade-band alpha (gates emission/deflection strength in-shader). - * @param anchorPosRelCamM Camera-relative anchor position, metres. - * @param diskScaleHeightRs Vertical falloff scale height, r_s units. - * @param edgeFadeStartFraction Escape-branch edge-fade start, as a fraction of `lutMaxImpactParamRs`. - * @param dopplerStrength Doppler-beaming strength factor. - * @param emissionStrength Overall multiplier on the annulus emission's output intensity. - * @param edgeFadeEndRs Escape fade's end impact parameter, r_s units — derived per frame by the layer. - * @param emissionTint Overall multiplier on the annulus emission's per-sample tint. - * @param quadPlaneRadiusRs Lens billboard half-size, r_s units — `lensQuadPlaneRadiusRs`, derived per frame. + * Takes a NAMED bag, not positional args: 17 of these fields are bare + * `number`s, so a transposition (`innerRs`/`outerRs`, + * `diskScaleHeightRs`/`edgeFadeStartFraction`) would type-check, pass the + * offset parity test, and render subtly wrong. The table above documents each + * field; `viewProj` is already camera-rebased and column-major, `bandAlpha` + * is this frame's fade-band alpha, and everything in r_s or metres says so in + * its name. */ import type { Mat4 } from 'wgpu-matrix'; @@ -81,30 +66,54 @@ import { CAMERA_UNIFORM_BYTES, writeCameraPrefix } from '../../services/gpu/lib/ * 3) + edgeFadeEndRs + quadPlaneRadiusRs = 44. */ export const SGR_A_STAR_LENSING_UNIFORM_FLOATS = CAMERA_UNIFORM_BYTES / 4 + 24; -export function packSgrAStarLensingUniforms( - viewProj: Float32Array | Mat4, - viewportPx: Vec2, - schwarzschildRadiusM: number, - innerRs: number, - outerRs: number, - inclinationRad: number, - positionAngleRad: number, - flickerAmp: number, - flickerTimescaleS: number, - flickerPhase: number, - lutMinImpactParamRs: number, - lutMaxImpactParamRs: number, - lutSampleCount: number, - bandAlpha: number, - anchorPosRelCamM: Readonly, - diskScaleHeightRs: number, - edgeFadeStartFraction: number, - dopplerStrength: number, - emissionStrength: number, - edgeFadeEndRs: number, - emissionTint: Readonly, - quadPlaneRadiusRs: number, -): Float32Array { +export function packSgrAStarLensingUniforms(input: { + readonly viewProj: Float32Array | Mat4; + readonly viewportPx: Vec2; + readonly schwarzschildRadiusM: number; + readonly innerRs: number; + readonly outerRs: number; + readonly inclinationRad: number; + readonly positionAngleRad: number; + readonly flickerAmp: number; + readonly flickerTimescaleS: number; + readonly flickerPhase: number; + readonly lutMinImpactParamRs: number; + readonly lutMaxImpactParamRs: number; + readonly lutSampleCount: number; + readonly bandAlpha: number; + readonly anchorPosRelCamM: Readonly; + readonly diskScaleHeightRs: number; + readonly edgeFadeStartFraction: number; + readonly dopplerStrength: number; + readonly emissionStrength: number; + readonly edgeFadeEndRs: number; + readonly emissionTint: Readonly; + readonly quadPlaneRadiusRs: number; +}): Float32Array { + const { + viewProj, + viewportPx, + schwarzschildRadiusM, + innerRs, + outerRs, + inclinationRad, + positionAngleRad, + flickerAmp, + flickerTimescaleS, + flickerPhase, + lutMinImpactParamRs, + lutMaxImpactParamRs, + lutSampleCount, + bandAlpha, + anchorPosRelCamM, + diskScaleHeightRs, + edgeFadeStartFraction, + dopplerStrength, + emissionStrength, + edgeFadeEndRs, + emissionTint, + quadPlaneRadiusRs, + } = input; const out = new Float32Array(SGR_A_STAR_LENSING_UNIFORM_FLOATS); writeCameraPrefix(out, viewProj, viewportPx); // f32 0..17; 18..19 stay zero out[20] = schwarzschildRadiusM; // byte 80 diff --git a/tests/services/engine/frame/skyCubemapFaceContext.test.ts b/tests/services/engine/frame/skyCubemapFaceContext.test.ts index db481a70e2..005125c608 100644 --- a/tests/services/engine/frame/skyCubemapFaceContext.test.ts +++ b/tests/services/engine/frame/skyCubemapFaceContext.test.ts @@ -112,6 +112,7 @@ describe('skyCubemapFaceContext', () => { eyeMpc: EYE_MPC, face: face as CubeFace, faceSizePx: 256, + nowMs: 0, }); expect(ctx).not.toBeNull(); if (ctx === null) continue; @@ -145,6 +146,7 @@ describe('skyCubemapFaceContext', () => { eyeMpc: EYE_MPC, face: 0, faceSizePx: 256, + nowMs: 0, }), ).toBeNull(); expect( @@ -153,6 +155,7 @@ describe('skyCubemapFaceContext', () => { eyeMpc: EYE_MPC, face: 0, faceSizePx: 256, + nowMs: 0, }), ).toBeNull(); expect( @@ -161,13 +164,20 @@ describe('skyCubemapFaceContext', () => { eyeMpc: EYE_MPC, face: 0, faceSizePx: 256, + nowMs: 0, }), ).toBeNull(); }); it('carries the draw mask, not the pick mask, as visibleSourceMask', () => { const state = makeState(); - const ctx = skyCubemapFaceContext({ state, eyeMpc: EYE_MPC, face: 0, faceSizePx: 256 }); + const ctx = skyCubemapFaceContext({ + state, + eyeMpc: EYE_MPC, + face: 0, + faceSizePx: 256, + nowMs: 0, + }); expect(ctx).not.toBeNull(); if (ctx === null) return; expect(ctx.visibleSourceMask).toBe(deriveSourceMasks(state).draw); @@ -224,6 +234,7 @@ describe('skyCubemapFaceContext', () => { eyeMpc: EYE_MPC, face: face as CubeFace, faceSizePx: 256, + nowMs: 0, }); expect(ctx).not.toBeNull(); if (ctx === null) continue; @@ -251,7 +262,13 @@ describe('skyCubemapFaceContext', () => { // regression the fix addresses; see skyCubemapFaceContext's // SKY_CAPTURE_NEAR_MPC docblock. const state = makeState(); - const ctx = skyCubemapFaceContext({ state, eyeMpc: EYE_MPC, face: 0, faceSizePx: 256 }); + const ctx = skyCubemapFaceContext({ + state, + eyeMpc: EYE_MPC, + face: 0, + faceSizePx: 256, + nowMs: 0, + }); expect(ctx).not.toBeNull(); if (ctx === null) return; expect(ctx.cam.near).toBeLessThan(100 * SCALE_UNITS.AU_TO_MPC); diff --git a/tests/services/engine/presentation/scaleFadeBands.test.ts b/tests/services/engine/presentation/scaleFadeBands.test.ts index 50b8ce311e..0928c0878a 100644 --- a/tests/services/engine/presentation/scaleFadeBands.test.ts +++ b/tests/services/engine/presentation/scaleFadeBands.test.ts @@ -73,24 +73,24 @@ describe('both backdrop bands derive from one shape', () => { }); }); -describe('sgrAStarLensing band — 100/500 AU envelope in Mpc, approach direction', () => { - it('the sgrAStarLensing fade band engages on approach to Sgr A*', () => { - // The band classification is critical: since fullAt < goneAt, fadeBand - // returns 1 at the close edge and 0 at the far edge, implementing a fade-IN - // as the camera approaches. A retune that swapped the edges would flip the - // direction and cause the lens pass to fade OUT on approach (the opposite of - // the intended effect). This test pins the edge ordering; classifiers catch - // backwards bands. - const fullAtMpc = 100 * SCALE_UNITS.AU_TO_MPC; - const goneAtMpc = 500 * SCALE_UNITS.AU_TO_MPC; +describe('sgrAStarLensing band', () => { + // The DIRECTION is the load-bearing fact: `fullAt < goneAt` makes this an + // approach fade, so the lens engages as the camera closes on Sgr A*. Edges + // swapped, it would fade OUT on approach — the opposite of the effect — and + // still type-check. Read off the band itself, so an intentional retune of + // where the envelope sits stays green. + it('fades IN on approach, monotonically across the envelope', () => { + const { fullAt, goneAt } = SCALE_FADE_BANDS.sgrAStarLensing; + expect(fullAt).toBeLessThan(goneAt); - expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, fullAtMpc)).toBe(1); - expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, goneAtMpc)).toBe(0); - - // A midpoint value is strictly between 0 and 1, confirming the smooth ramp. - const midpointMpc = (fullAtMpc + goneAtMpc) / 2; - const midpointAlpha = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, midpointMpc); - expect(midpointAlpha).toBeGreaterThan(0); - expect(midpointAlpha).toBeLessThan(1); + const midpoint = (fullAt + goneAt) / 2; + const nearMid = (fullAt + midpoint) / 2; + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, fullAt)).toBe(1); + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, goneAt)).toBe(0); + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, nearMid)).toBeGreaterThan( + fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, midpoint), + ); + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, midpoint)).toBeGreaterThan(0); + expect(fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, midpoint)).toBeLessThan(1); }); }); diff --git a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts index 125492330c..48fdd017b1 100644 --- a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts +++ b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts @@ -223,6 +223,39 @@ describe('texturedDiskRenderer.draw — viewSlot (Task 13b)', () => { expect(uniformWrites).toHaveLength(2); }); + // The instance buffer is deliberately NOT ringed per view slot, unlike the + // uniform: the justification is that every draw in a frame re-uploads + // byte-identical instance bytes, so the last write is the right one for all + // of them. That is a live invariant — the day a `DiskInstance` field becomes + // camera-dependent, only the last captured face would render correctly and + // nothing else would notice. + it('packs identical instance bytes for different view slots and cameras', () => { + const { ctx, writeBufferCalls } = makeStubCtx(); + const renderer = createTexturedDiskRenderer(ctx, FOCUS_BGL); + renderer.bindAtlas({} as GPUTextureView); + renderer.bindHiResArray({} as GPUTextureView); + + const pass = { + setPipeline: vi.fn(), + setBindGroup: vi.fn(), + setVertexBuffer: vi.fn(), + draw: vi.fn(), + } as unknown as GPURenderPassEncoder; + + const instances: DiskInstance[] = [fakeDiskInstance({ hiResLayerIdx: 2 })]; + const vpA = Float32Array.from({ length: 16 }, (_unused, i) => i); + const vpB = Float32Array.from({ length: 16 }, (_unused, i) => 100 - i); + + renderer.draw(pass, vpA as never, [512, 512], [0, 0, 0], FOCUS_BIND_GROUP, instances, 1); + renderer.draw(pass, vpB as never, [800, 600], [7, -3, 11], FOCUS_BIND_GROUP, instances, 2); + + const instanceWrites = writeBufferCalls.filter( + (c) => c.data.length === instances.length * FLOATS_PER_INSTANCE, + ); + expect(instanceWrites).toHaveLength(2); + expect(Array.from(instanceWrites[0]!.data)).toEqual(Array.from(instanceWrites[1]!.data)); + }); + it('defaults viewSlot to 0 when omitted', () => { const { ctx } = makeStubCtx(); const renderer = createTexturedDiskRenderer(ctx, FOCUS_BGL); diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts index f3e25ad9fe..befd10630c 100644 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts @@ -55,30 +55,30 @@ const QUAD_PLANE_RADIUS_RS = 2343.75; describe('SgrAStarLensingUniforms byte offsets', () => { it('packs a 176-byte / 44-f32 record with each field at its documented offset', () => { - const rec = packSgrAStarLensingUniforms( - VIEW_PROJ, - VIEWPORT_PX, - SCHWARZSCHILD_RADIUS_M, - INNER_RS, - OUTER_RS, - INCLINATION_RAD, - POSITION_ANGLE_RAD, - FLICKER_AMP, - FLICKER_TIMESCALE_S, - FLICKER_PHASE, - LUT_MIN_IMPACT_PARAM_RS, - LUT_MAX_IMPACT_PARAM_RS, - LUT_SAMPLE_COUNT, - BAND_ALPHA, - ANCHOR_POS_REL_CAM_M, - DISK_SCALE_HEIGHT_RS, - EDGE_FADE_START_FRACTION, - DOPPLER_STRENGTH, - EMISSION_STRENGTH, - EDGE_FADE_END_RS, - EMISSION_TINT, - QUAD_PLANE_RADIUS_RS, - ); + const rec = packSgrAStarLensingUniforms({ + viewProj: VIEW_PROJ, + viewportPx: VIEWPORT_PX, + schwarzschildRadiusM: SCHWARZSCHILD_RADIUS_M, + innerRs: INNER_RS, + outerRs: OUTER_RS, + inclinationRad: INCLINATION_RAD, + positionAngleRad: POSITION_ANGLE_RAD, + flickerAmp: FLICKER_AMP, + flickerTimescaleS: FLICKER_TIMESCALE_S, + flickerPhase: FLICKER_PHASE, + lutMinImpactParamRs: LUT_MIN_IMPACT_PARAM_RS, + lutMaxImpactParamRs: LUT_MAX_IMPACT_PARAM_RS, + lutSampleCount: LUT_SAMPLE_COUNT, + bandAlpha: BAND_ALPHA, + anchorPosRelCamM: ANCHOR_POS_REL_CAM_M, + diskScaleHeightRs: DISK_SCALE_HEIGHT_RS, + edgeFadeStartFraction: EDGE_FADE_START_FRACTION, + dopplerStrength: DOPPLER_STRENGTH, + emissionStrength: EMISSION_STRENGTH, + edgeFadeEndRs: EDGE_FADE_END_RS, + emissionTint: EMISSION_TINT, + quadPlaneRadiusRs: QUAD_PLANE_RADIUS_RS, + }); expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); expect(rec.length).toBe(44); // 176 bytes diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 99f4f94f6f..31ea756861 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -118,7 +118,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const quadPlaneRadiusRs = 706; const emissionTint: Vec3 = [801, 802, 803]; - const rec = packSgrAStarLensingUniforms( + const rec = packSgrAStarLensingUniforms({ viewProj, viewportPx, schwarzschildRadiusM, @@ -141,7 +141,7 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { edgeFadeEndRs, emissionTint, quadPlaneRadiusRs, - ); + }); const vectorByField: Record = { anchorPosRelCamM, emissionTint }; const scalarByField: Record = { From a69293b08428ebda76df25cc345ac529b22c95db Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 01:45:00 +0200 Subject: [PATCH 54/60] docs(black-hole): bring the feature's comments inside the budget MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every file the review measured over the comment budget (module header <= 10 lines, comment lines <= half the code lines) is back inside it, except the two byte-layout-contract files that take the camera.wesl allowance and the .d.ts files. What went: the regression narrative ("the old formula returned...", "fix round 3", "audit-cubemap-alignment.md SS7"), which the git log and the ledger already hold; every `Ruling N` reference, restated as the decision itself; and the `Task N` citations, whose one-line conclusions are inlined where load-bearing. `.superpowers/sdd/` is a workspace directory, so those pointers would dangle the moment it is cleaned up. What stayed: every landmine — the Y-flip origin, the writeBuffer/submit race, the f64 quad inversion, the per-face clear, the Infinity/sentinel encoding, the texture_1d WebKit rejection, the denormal notes. Also corrects the captured ray's march budget (its 24-step half of 48, not the full budget). `lensQuadPlaneRadiusRs.ts` is the one file still over: 7 lines of code, and the f32-in-the-vertex-stage landmine is what the file exists to record. Co-Authored-By: Claude Fable 5 --- src/data/blackHoles.ts | 28 ++-- src/services/engine/frame/executeFrame.ts | 10 +- src/services/engine/frame/frameProgram.ts | 31 +++-- src/services/engine/frame/passes/index.ts | 14 +- .../frame/passes/sgrAStarLensingLayer.ts | 30 ++--- src/services/engine/frame/renderFrame.ts | 52 +++----- .../engine/frame/skyCubemapCaptureSchedule.ts | 33 ++--- .../engine/frame/skyCubemapFaceContext.ts | 82 ++++-------- src/services/engine/frame/slabs.ts | 4 +- .../bodies/sgrAStarLensingRenderer.ts | 31 +---- .../bodies/sgrAStarLensing/fragment.wesl | 121 +++++++----------- .../bodies/sgrAStarLensing/vertex.wesl | 25 ++-- src/utils/gpu/createViewSlotUniformRing.ts | 30 +---- src/utils/lensing/lensQuadPlaneRadiusRs.ts | 20 +-- 14 files changed, 179 insertions(+), 332 deletions(-) diff --git a/src/data/blackHoles.ts b/src/data/blackHoles.ts index c67725e73d..75d751e50b 100644 --- a/src/data/blackHoles.ts +++ b/src/data/blackHoles.ts @@ -1,10 +1,7 @@ /** - * `BLACK_HOLES` — static registry of supermassive black holes in the scene. - * - * Append-only table binding each black hole identity to its disk-emission parameters. - * Today holding only Sgr A* (our Galactic Centre); M87* is data (not code) once a - * data-driven catalog exists. Emission tuning (inclination, position angle, flicker) - * is visual taste until observational anchoring data becomes available. + * `BLACK_HOLES` — each scene black hole's disk-emission parameters. Sgr A* + * only today; a second row (M87*) is data, not code. Inclination, position + * angle and flicker are visual taste, not measurements. */ import type { BlackHoleRow } from '../@types/data/BlackHoleRow'; @@ -13,22 +10,13 @@ export const BLACK_HOLES: readonly BlackHoleRow[] = [ { bodyId: 'sgr-a-star', emission: { - // ISCO (innermost stable circular orbit) to EHT photon ring (Event Horizon - // Telescope's nominal imaging radius). Hard constraint: no physical spin, - // Schwarzschild only. + // ISCO out to the EHT photon ring; Schwarzschild, no spin. innerRs: 3, outerRs: 6, - // Face-on view is ≲30° per EHT polarimetry. Chosen value at ~20°; the exact - // angle is unconstrained but fixed for reproducible renders. - inclinationRad: 0.35, // ~20° - // Major-axis position angle (E of N, standard astronomical convention). - // Entirely unconstrained; tuned via the lens tuning debug panel. - positionAngleRad: 2.21, - // Stochastic brightening/dimming at minute-to-hour timescales (Sgr A* manifests - // minute-scale near-IR flares; we borrow that timescale). Amplitude is tasteful - // dev tuning — no published NIR variability-index texture yet. Range 0..1. - flickerAmp: 0.15, // ±15% brightness modulation - flickerTimescaleS: 120, // ~2 minutes + inclinationRad: 0.35, // ~20°, inside EHT polarimetry's ≲30° from face-on + positionAngleRad: 2.21, // major axis, E of N; observationally unconstrained + flickerAmp: 0.15, // ±15%; taste, no published NIR variability index + flickerTimescaleS: 120, // Sgr A*'s own minute-scale NIR flares }, }, ]; diff --git a/src/services/engine/frame/executeFrame.ts b/src/services/engine/frame/executeFrame.ts index 21bb9d817e..9bf157c868 100644 --- a/src/services/engine/frame/executeFrame.ts +++ b/src/services/engine/frame/executeFrame.ts @@ -234,7 +234,7 @@ export function executeFrame(args: ExecuteFrameArgs): void { break; } case 'render': { - // The runtime hand-off (Task 12): a step carrying `face` (the + // The runtime hand-off: a step carrying `face` (the // black-hole lens's sky-cubemap capture) resolves EVERY per-step value // below — slab view, enable gate, draw ctx — from ITS OWN camera // (`renderFrame`'s per-face `skyCubemapFaceContext` derivation), not @@ -256,12 +256,12 @@ export function executeFrame(args: ExecuteFrameArgs): void { // the view to read `view.slab.frame.bodyId`, and a step whose slab is // a body row still resolves cheaply even when its group ends up empty. const view = slabViewOf(stepCtx, step.slab); - // A capture step (Task 12's sky-cubemap sweep) selects its group by + // A capture step (the sky-cubemap sweep) selects its group by // the `skyCapture` opt-in flag, not `target`: every capture step // targets 'sky-cubemap', but the roster's own layers keep their // ordinary `target` ('hdr', typically) for their NORMAL per-frame // draw — target-matching could never select them for a capture step - // (Ruling 6, resolving Task 12's own recorded finding). `step.face` + // (the capture roster is an opt-in list, not a target match). `step.face` // is the same discriminant `stepCtx` above already reads. const isCaptureStep = step.face !== undefined; const faceKey = step.face === undefined ? null : `${step.target}:${step.face}`; @@ -269,12 +269,12 @@ export function executeFrame(args: ExecuteFrameArgs): void { (l) => (isCaptureStep ? l.skyCapture === true : l.target === step.target) && // A 'body' layer matches every body-slab step, not one fixed - // index — Task 7 emits one such step per body row. `view.slab` is + // index. `view.slab` is // in hand here, so this reads `frame.kind` directly rather than // going through `isBodySlabIndex` (slabs.ts) — the index-only // sibling check `frameProgram.ts` uses where no `Slab` is in hand. (l.slab === step.slab || (l.slab === 'body' && view.slab.frame.kind === 'body-m')) && - // The black-hole lens's (hdr, NEAR0) split (Task 14b): a step + // The black-hole lens's (hdr, NEAR0) split: a step // carrying `lensPhase` further narrows the group to the layers // that opted into `hdrPostLensing` accordingly — see slabs.ts. matchesLensPhase(l.hdrPostLensing, step.lensPhase) && diff --git a/src/services/engine/frame/frameProgram.ts b/src/services/engine/frame/frameProgram.ts index df0470822b..ad1432d597 100644 --- a/src/services/engine/frame/frameProgram.ts +++ b/src/services/engine/frame/frameProgram.ts @@ -112,35 +112,35 @@ export const BODY_SLAB_CAPACITY = 1 + SCENE_PLANETS.length + SCENE_ANCHOR_POINT_ * a farther row's depth — see the push loop below. * * `skyCubemapFacesToCapture` (`skyCubemapCaptureSchedule`'s output, computed - * by `renderFrame` each frame from the lensing band alpha — Task 12) is the + * by `renderFrame` each frame from the lensing band alpha) is the * black-hole lens's amortized sky-capture list: empty outside the band, so * NO capture steps are emitted at all (Q6's zero-dispatch guarantee — this is * the capture side of that contract, not just the lensing draw itself). * Placed in the compute prelude's wake, ahead of every other render step, so - * a same-frame lensing draw (Task 13) can sample a cubemap this frame + * a same-frame lensing draw can sample a cubemap this frame * actually wrote. TWO steps per requested face — COSMO then NEAR0 — because - * the fixed opt-in roster (`ContentLayer.skyCapture`, Ruling 6) spans both + * the fixed opt-in roster (`ContentLayer.skyCapture`) spans both * slabs: `point-sprites` / `textured-disks` project through COSMO; * `star-catalog` / `star-aggregates` / `star-points` through NEAR0. A * capture step selects its group by the flag rather than by `target` * (`executeFrame`'s capture-step branch), but `slab` still gates normally — - * one step per slab is what makes BOTH halves of the roster reachable - * (Task 13b; a single NEAR0-only step left the COSMO half permanently - * unselected, the flag having no effect). Order (COSMO before NEAR0) + * one step per slab is what makes BOTH halves of the roster reachable (a + * single NEAR0-only step leaves the COSMO half permanently unselected, the + * flag having no effect). Order (COSMO before NEAR0) * mirrors the real `(hdr, COSMO)` → `(hdr, NEAR0)` sequence below, so the * capture composites in the same order the live frame would. * - * `sgrAStarLensingBodySlabs` (Task 14, Ruling 8) is the black-hole lens's OWN - * missing step: no step here ever matched `sgrAStarLensingLayer` (`slab: - * 'body'`, `target: 'hdr'`) before Task 14 — it registered and compiled but - * never drew (Task 13's own recorded finding). `renderFrame` resolves Sgr + * `sgrAStarLensingBodySlabs` is the black-hole lens's OWN step: without it + * nothing here matches `sgrAStarLensingLayer` (`slab: 'body'`, `target: + * 'hdr'`), which registers and compiles but never draws. `renderFrame` + * resolves Sgr * A*'s body-m row each frame and passes it here ONLY inside the fade band, so * an inactive band emits no step at all (same zero-dispatch guarantee as * `skyCubemapFacesToCapture`). One `(hdr, slab)` render step per entry, * placed after the `(hdr, NEAR0)` roster step so the lens's OVER blend * occludes the roster light already accumulated there. A non-empty list also * means the band is active, so the `(hdr, NEAR0)` roster step ABOVE this one - * splits into `'pre'`/`'post'` halves around it (Task 14b, Ruling 9): + * splits into `'pre'`/`'post'` halves around it: * `orbit-trails`/`body-glints` opt into the `'post'` half via * `ContentLayer.hdrPostLensing`, so they draw AFTER the lens rather than * being sampled by it, while an inactive band leaves the roster as the one @@ -204,8 +204,7 @@ export function frameProgram( // still accumulating into HDR BEFORE the tone-map composite below — one // tone curve for stars and galaxies. The hdr target is already touched // by the COSMO step above, so this pass loads rather than clears. - // Task 14b (Ruling 9): outside the band this is the one untagged step it - // always was — byte-identical to pre-Task-14b. Inside it, the roster + // Outside the band this is one untagged step. Inside it, the roster // splits around the lens's own (hdr, BODY[k]) step(s) below so // `orbit-trails`/`body-glints` (ContentLayer.hdrPostLensing) draw AFTER // the lens instead of being sampled by it — see this function's doc. @@ -331,8 +330,8 @@ export const PASS_GROUP_TITLES: Readonly> = { 'zoa·COSMO': 'Volumes & aggregates', 'star-aggregates·NEAR0': 'Volumes & aggregates', 'mw-aggregate·NEAR0': 'Volumes & aggregates', - // The black-hole lens's amortized sky-capture steps (Task 12) — 0-12 of - // them per frame (COSMO + NEAR0 per requested face, Task 13b) depending on + // The black-hole lens's amortized sky-capture steps — 0-12 of + // them per frame (COSMO + NEAR0 per requested face) depending on // `skyCubemapCaptureSchedule`, so its own group rather than folding into // an existing title. 'sky-cubemap·COSMO': 'Sky capture', @@ -388,7 +387,7 @@ function timedSlotRowsOf( // `groupKeyOf` helper (slabs.ts) — the same definition the merged executor // resolves against, so the two can't drift. Two render steps can now // share one `(target, slab)` — the black-hole lens's `'pre'`/`'post'` - // roster split (Task 14b) — but never share a LAYER (`matchesLensPhase` + // roster split — but never share a LAYER (`matchesLensPhase` // partitions the registry between them), so no per-layer dedup is // needed; only the group-TOTAL row below needs the split disambiguated. const groupKey = groupKeyOf(step.target, step.slab); diff --git a/src/services/engine/frame/passes/index.ts b/src/services/engine/frame/passes/index.ts index aace9862d0..2ad65d5195 100644 --- a/src/services/engine/frame/passes/index.ts +++ b/src/services/engine/frame/passes/index.ts @@ -41,11 +41,11 @@ * star-points, star-catalog, star-upsample, constellations, orbit-trails, * body-glints); `star-aggregates` has its OWN `(star-aggregates, NEAR0)` render * step into the half-res offscreen `star-upsample` composites back, and - * `sgr-a-star-lensing` has its OWN `(hdr, BODY[k])` render step (Task 14). Its + * `sgr-a-star-lensing` has its OWN `(hdr, BODY[k])` render step. Its * position below is registry-order documentation for items 10-15 — but for * orbit-trails/body-glints (17/17b) the ordering IS enforced, by * `ContentLayer.hdrPostLensing` splitting the shared `(hdr, NEAR0)` step - * around the lens step whenever the band is active (Task 14b, Ruling 9); see + * around the lens step whenever the band is active; see * `frameProgram.ts`: * * 10. milky-way — star/dust point cloud at the galactic centre @@ -76,8 +76,8 @@ * row drawing ONLY on Sgr A*'s own row, PREMULTIPLIED * OVER (not additive) into hdr — captured rays occlude * the additive roster light already accumulated behind - * them; escaping rays sample the Task 11 sky-cubemap - * bent by the Task 9 LUT. Its OWN `(hdr, BODY[k])` + * them; escaping rays sample the sky-cubemap + * bent by the deflection LUT. Its OWN `(hdr, BODY[k])` * step (`frameProgram.ts`) runs after the `(hdr, * NEAR0)` roster step above so it draws over items * 10-15 @@ -88,7 +88,7 @@ * opts into the lens's `'post'` split half * (`hdrPostLensing`) so it draws unwarped over the * lens pass whenever the band is active, per spec - * "Draw order" (Task 14b, Ruling 9) + * "Draw order" * 17b. body-glints — the sub-pixel bodies (the glints branch of the body * partition) as brightness-scaled additive points * (size x albedo x phase, cross-fading with the mesh @@ -338,7 +338,7 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // that a listing choice, not a compositing one. The LAST roster row the Sgr // A* lens pass samples (below). constellationsLayer, - // The Sgr A* lens pass (Task 13/14): a 'body'-slab row, blend 'over' + // The Sgr A* lens pass: a 'body'-slab row, blend 'over' // (Blend.d.ts) rather than additive like its neighbours, so — unlike the // additive rows around it — its position IS load-bearing: it must draw AFTER // every roster row above (so its captured/escaping rays occlude the additive @@ -346,7 +346,7 @@ export const CONTENT_LAYERS: readonly ContentLayer[] = [ // below (so those stay unwarped on top, spec "Draw order", Q5). Registry // order alone can't enforce this against `orbit-trails`/`body-glints` — they // share this SAME (hdr, NEAR0) render step with the roster above. The real - // enforcement is `ContentLayer.hdrPostLensing` (Task 14b, Ruling 9): those + // enforcement is `ContentLayer.hdrPostLensing`: those // two opt in, so `frameProgram` splits the shared step into `'pre'`/`'post'` // halves around this row's own `(hdr, BODY[k])` step whenever the band is // active (see its module header); this array position stays the diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index cb74f71355..6a45cb831f 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -1,19 +1,12 @@ /** * sgrAStarLensingLayer — the Sgr A* lens pass's `ContentLayer` row. * - * `slab: 'body'`: the frame program expands a `'body'` layer into one render - * step per body-m slab row, so `enabled`/`draw` are called once per body — - * narrowed here to Sgr A*'s own row (the anchor's `visibleSlabBodies` - * candidacy, same seam `planetsLayer` reads for a seeded planet). `blend: - * 'over'` (Porter-Duff, premultiplied) rather than the additive convention - * most `hdr` layers use: the black hole's captured disc must truly occlude - * the additive starlight already accumulated behind it, and per-pixel alpha - * lets the roster drawn earlier show through wherever deflection is - * negligible — `Blend.d.ts` enumerates `'over'` for any target, not just the - * swap-chain rows. - * - * No `drawPick`: Sgr A*'s existing pick stamp lives in `starPointsLayer` - * (see `ContentLayer.d.ts`'s own docblock) and is untouched by this layer. + * `slab: 'body'` expands into one render step per body-m row, so + * `enabled`/`draw` run once per body and are narrowed here to Sgr A*'s. + * `blend: 'over'`, not the additive convention most `hdr` layers use: the + * captured disc must truly OCCLUDE the starlight behind it, while per-pixel + * alpha lets the earlier roster through where deflection is negligible. + * No `drawPick` — Sgr A*'s pick stamp lives in `starPointsLayer`. */ import type { ContentLayer } from '../../../../@types/engine/frame/ContentLayer'; @@ -112,9 +105,8 @@ export const sgrAStarLensingLayer: ContentLayer = { // impact-parameter coverage can never exceed that distance — 0.6 bounds // the vertex's plane-stretch factor at 1.25 (see vertex.wesl) — and // floored at the LUT max so the fade never cuts into the LUT-resolved - // strong-field region during a close descent. Fading at the raw LUT edge - // instead blended a sky still deflected ~40 px into the true sky (see - // audit-cubemap-alignment.md §7). + // strong-field region during a close descent — fading at the raw LUT edge + // blends a sky still deflected ~40 px into the true sky. const distRs = Math.hypot(anchorPosRelCamM[0], anchorPosRelCamM[1], anchorPosRelCamM[2]) / SCHWARZSCHILD_RADIUS_M; @@ -122,10 +114,8 @@ export const sgrAStarLensingLayer: ContentLayer = { renderer.lut.maxImpactParamRs, Math.min(2 * ctx.drawPxPerRad, 0.6 * distRs), ); - // Billboard half-size in f64 HERE, not in the vertex shader: the f32 - // in-shader inversion degenerated close-in (edgeFadeEndRs >= distRs via - // the lutMax floor) into a ~5e4x-oversized quad whose varying - // interpolation shook every ray — see lensQuadPlaneRadiusRs's docblock. + // Billboard half-size in f64 HERE, not in the vertex shader — see + // `lensQuadPlaneRadiusRs`'s docblock. const quadPlaneRadiusRs = lensQuadPlaneRadiusRs(edgeFadeEndRs, distRs); const uniforms = packSgrAStarLensingUniforms({ diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 444176de69..4cb637e85a 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -33,12 +33,11 @@ * ### Why pass an explicit input bag instead of capturing closure? * * This module owns no cross-frame state of its OWN — every local value it - * computes is recomputed each frame. It DOES read/write one Resource, Task - * 12's `state.cameraRuntime.skyCubemapCapture` (the black-hole lens's - * amortized sky-capture bookkeeping), the same amortized-Resources shape - * `cameraRuntime`'s other fields already carry — see - * `SkyCubemapCaptureRuntime.d.ts`. A free function taking a struct of inputs - * is trivially testable and bounds the encoder lifetime to the function body. + * computes is recomputed each frame. It DOES read/write one Resource, + * `state.cameraRuntime.skyCubemapCapture` (the black-hole lens's amortized + * sky-capture bookkeeping), the same amortized-Resources shape + * `cameraRuntime`'s other fields already carry. A free function taking a + * struct of inputs bounds the encoder lifetime to the function body. * * ### What stays in `runFrame()` (NOT here) * @@ -113,12 +112,10 @@ export function renderFrame(input: RenderFrameInput): void { const hdrActive = hdrActiveOf(ctx.renderTargets); const hdrOn = hdrActive && state.settings.hdr.enabled; - // The black-hole lens's amortized sky-cubemap capture schedule (Task 12). - // `bandAlpha` keys on the CAMERA's distance from the galactic-centre - // anchor, same quantity + region every `sgrAStarLensing`-band consumer - // reads (`scaleFadeBands.ts`). Bookkeeping lives on `cameraRuntime`, not - // here — see `SkyCubemapCaptureRuntime.d.ts` for why `renderFrame` (which - // owns no cross-frame state of its own) is still this bag's sole writer. + // The black-hole lens's amortized sky-cubemap capture schedule. The band + // keys on the CAMERA's distance from the galactic-centre anchor, the same + // quantity + region every `sgrAStarLensing`-band consumer reads. The + // bookkeeping lives on `cameraRuntime` — see `SkyCubemapCaptureRuntime`. const captureRuntime = state.cameraRuntime.skyCubemapCapture; const gcDistanceMpc = regionRelativeDistanceMpc( ctx.drawCamPos, @@ -127,16 +124,6 @@ export function renderFrame(input: RenderFrameInput): void { ); const bandActive = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, gcDistanceMpc) > 0; - // Sgr A*'s own body-m slab row this frame, if the band is active (Task 14, - // Ruling 8): `frameProgram` never emitted an (hdr, BODY[k]) step for - // `sgrAStarLensingLayer` before this task, so it compiled and registered - // but never drew (Task 13's own finding). Resolved here, not in - // `frameProgram`, because the row's painter-order index comes from - // `deriveSlabs` (computed upstream of this function) — the same - // "resolve here, hand data down" split `earthSlab` in `runFrame.ts` - // already follows for the identical `frame.kind === 'body-m'` lookup. - // `null` outside the band, or when the row isn't in `ctx.slabs` this frame - // (e.g. frustum-culled despite the distance band). const bandJustEngaged = bandActive && !captureRuntime.bandActive; // The `sky-cubemap` row's 50 MB exists only while the band does (its // `allocateWhen`, renderTargets.ts). `runFrame`'s per-frame `reconcile` @@ -149,18 +136,13 @@ export function renderFrame(input: RenderFrameInput): void { ctx.renderTargets.reconcile(state, ctx.canvasSize); } - // The runtime hand-off (Task 12's brief, "Name the runtime hand-off"): - // `frameProgram` only knows WHICH faces to capture (static data); resolving - // each face's own synthetic camera is `renderFrame`'s job, done fresh every - // frame since the schedule's face LIST can change frame to frame. - // `faceSizePx` reads the sky-cubemap row's own ALLOCATED size (`sizeOf`, - // this frame's already-reconciled pixels — see `RenderTargets.sizeOf`'s - // doc), not `specOf().fixedSizePx.size` directly: that field is a live - // setting (a function of state, not a plain number), so reading the - // resolved allocation is the authoritative answer. - // A face whose context comes back null (pre-bootstrap) is simply - // omitted — `executeFrame` treats a missing map entry as "skip this step - // cleanly" (see its module header). + // `frameProgram` only knows WHICH faces to capture; each face's own + // synthetic camera is resolved here, fresh every frame, since the face LIST + // changes frame to frame. `faceSizePx` reads the row's ALLOCATED size, not + // `specOf().fixedSizePx.size`: that field is a live setting (a function of + // state), so the resolved allocation is the authoritative answer. A face + // whose context comes back null (pre-bootstrap) is omitted — `executeFrame` + // treats a missing map entry as "skip this step cleanly". const skyCubemapFaceContexts = new Map(); let skyCubemapFacesToCapture: readonly CubeFace[] = []; // Sgr A*'s own body-m slab row this frame: `frameProgram` emits the @@ -240,7 +222,7 @@ export function renderFrame(input: RenderFrameInput): void { // The master bloom toggle is the ONLY bloom value that shapes the step // list; strength/threshold are read live by the bloom layers each draw. state.settings.bloom.enabled, - // Painter-ordered NEAR0 + body-row indices (Task 4) — the chain the + // Painter-ordered NEAR0 + body-row indices — the chain the // foreground:0 render expands into, one step per entry. foregroundChainOrder(ctx.slabs), skyCubemapFacesToCapture, diff --git a/src/services/engine/frame/skyCubemapCaptureSchedule.ts b/src/services/engine/frame/skyCubemapCaptureSchedule.ts index 41c216eac0..bae585ac55 100644 --- a/src/services/engine/frame/skyCubemapCaptureSchedule.ts +++ b/src/services/engine/frame/skyCubemapCaptureSchedule.ts @@ -1,25 +1,19 @@ /** - * skyCubemapCaptureSchedule — the black-hole sky cubemap's amortized capture - * schedule: a full 6-face sweep on band ENTRY or pinned-eye movement, then - * one face per frame in round-robin, with an escape valve for a stale face. - * Pure — every input is a plain value — so it's testable headlessly. + * The black-hole sky cubemap's amortized capture schedule: a full 6-face + * sweep on band entry or pinned-eye movement, then one face per frame in + * round-robin, with an escape valve for a stale face. */ import type { CubeFace } from '../../../@types/rendering/CubeFace'; const ALL_CUBE_FACES: readonly CubeFace[] = [0, 1, 2, 3, 4, 5]; -/** Escape-valve staleness threshold. Data tuning, sited beside the schedule it gates. */ -export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; +export const SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS = 2000; // escape-valve staleness /** - * Escape-valve movement threshold, as a FRACTION of the camera's current - * distance to Sgr A* — not an absolute distance. The pinned capture eye - * (fix round 3) only moves on a full sweep, so this measures how far the - * LIVE camera has drifted from that pinned eye: a fixed AU threshold would - * near-never fire during the descent to the event horizon (camera distance - * ~0.17 AU at the 2·r_s floor) while under-firing nowhere else. See - * `renderFrame.ts`'s `cameraMovedBeyondThreshold` derivation. + * Escape-valve movement threshold, as a FRACTION of the camera's distance to + * Sgr A*: a fixed AU threshold would near-never fire during the descent to + * the horizon (camera distance ~0.17 AU at the 2·r_s floor). */ export const SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION = 0.03; @@ -28,9 +22,7 @@ export type SkyCubemapCaptureSchedule = { }; export function skyCubemapCaptureSchedule(input: { - // Band just engaged OR the live camera drifted past the pinned-eye - // threshold — either forces every face, so the caller pre-folds both - // reasons into one flag rather than this function re-deriving them. + /** Band entry OR pinned-eye drift; the caller pre-folds both. */ readonly fullSweepTriggered: boolean; readonly frameIndex: number; // for round-robin readonly lastCapturedAtMs: ReadonlyMap; @@ -38,18 +30,13 @@ export function skyCubemapCaptureSchedule(input: { }): SkyCubemapCaptureSchedule { const { fullSweepTriggered, frameIndex, lastCapturedAtMs, nowMs } = input; - if (fullSweepTriggered) { - // A re-pinned eye invalidates every face at once — same as band entry, - // no partial-sweep half-state to reason about. - return { facesToCapture: ALL_CUBE_FACES }; - } + if (fullSweepTriggered) return { facesToCapture: ALL_CUBE_FACES }; const roundRobinFace = (frameIndex % 6) as CubeFace; const faces = new Set([roundRobinFace]); for (const face of ALL_CUBE_FACES) { const lastCapturedAt = lastCapturedAtMs.get(face); - // Absent ⇒ never captured, which is staler than any threshold — the - // capacity row exists (Task 3) but no sweep has touched this face yet. + // Absent ⇒ never captured, staler than any threshold. const staleMs = lastCapturedAt === undefined ? Infinity : nowMs - lastCapturedAt; if (staleMs > SKY_CUBEMAP_RECAPTURE_THRESHOLD_MS) faces.add(face); } diff --git a/src/services/engine/frame/skyCubemapFaceContext.ts b/src/services/engine/frame/skyCubemapFaceContext.ts index 598bb2a1c6..e34a3e0bd1 100644 --- a/src/services/engine/frame/skyCubemapFaceContext.ts +++ b/src/services/engine/frame/skyCubemapFaceContext.ts @@ -1,11 +1,9 @@ /** * skyCubemapFaceContext — one face of the black-hole sky cubemap's capture - * camera, as a value. Mirrors `pickFrameContext.ts` exactly: several roster - * layers read `ctx.fovYRad`/`ctx.canvasSize`/`ctx.drawPxPerRad` as - * frame-globals, not just `viewProj`, so this re-derives a full - * `ReadyFrameContext` from a synthetic camera (eye = `eyeMpc`, forward = the - * face's fixed axis, a 90° symmetric frustum) instead of threading a swapped - * vp through every roster-layer consumer. + * camera, as a value. Mirrors `pickFrameContext.ts`: roster layers read + * `ctx.fovYRad`/`canvasSize`/`drawPxPerRad` as frame-globals, not just + * `viewProj`, so a whole synthetic `ReadyFrameContext` is cheaper than + * threading a swapped vp through every consumer. */ import type { EngineState } from '../../../@types/engine/state/EngineState'; @@ -20,23 +18,14 @@ import { mat3FromColumns } from '../../../utils/math/mat3FromColumns'; import { cross3 } from '../../../utils/math/cross3'; import { SCALE_UNITS } from '../../../data/scaleUnits'; -/** - * The synthetic frustum's near plane, NOT the live cosmo camera's (`0.01 - * Mpc` / 10 kpc, sized for the whole scene). The capture's actual content — - * S-stars and the field around Sgr A* — sits at hundreds of AU, seven orders - * of magnitude inside that near plane; reusing it would clip every S-star - * invisible. `sky-cubemap` is depthless (`depth: null`), so near/far affect - * only clipping, never depth precision — free to pick a value sized for the - * capture scene instead of the main camera's. - */ +// NOT the live cosmo near plane (0.01 Mpc): the capture's content sits at +// hundreds of AU, inside it, so reusing it clips every S-star away. const SKY_CAPTURE_NEAR_MPC = 0.1 * SCALE_UNITS.AU_TO_MPC; /** - * Forward axis per `CubeFace` (index order ±X/±Y/±Z, see `CubeFace.d.ts`). - * `FACE_UP` is the WebGPU/D3D `texture_cube` convention's per-face up - * reference: world ±Y is parallel to forward on the ±Y faces, so those two - * borrow world ±Z instead. A later cube-view bind of this row's 6 layers - * relies on both tables matching that convention exactly. + * Forward axis per `CubeFace` (±X/±Y/±Z), and the `texture_cube` convention's + * per-face up (the ±Y faces borrow world ±Z, since world ±Y is forward + * there). The cube-view bind relies on both matching that convention. */ const FACE_FORWARD: readonly Vec3[] = [ [1, 0, 0], @@ -56,14 +45,10 @@ const FACE_UP: readonly Vec3[] = [ ]; /** - * One basis per face, doing double duty as both `poseBasis` and `upBasis`. - * With `yaw = pitch = 0` fixed below, `updatePosition` decodes local +Z - * through `poseBasis` — so this basis' THIRD column is set to `-forward` - * (target → eye), placing the derived eye exactly on `target - forward`. - * `ORIENTATION_FRAMES`' own convention puts a basis' pole in the MIDDLE - * column, which `frameUp` reads for screen-up — so the same matrix's middle - * column carries `FACE_UP`, and one basis serves both roles with no risk of - * the two drifting apart. + * One basis per face, serving as both `poseBasis` and `upBasis` so the two + * cannot drift. `updatePosition` decodes local +Z through the THIRD column, + * so that column is `-forward`; `frameUp` reads the MIDDLE for screen-up, so + * that one carries `FACE_UP`. */ const FACE_BASES: readonly Mat3[] = FACE_FORWARD.map((forward, i): Mat3 => { const up = FACE_UP[i]!; @@ -72,15 +57,10 @@ const FACE_BASES: readonly Mat3[] = FACE_FORWARD.map((forward, i): Mat3 => { }); /** - * Negate a view-projection's clip-space Y row (column-major 1/5/9/13). - * The cube-face (s,t) convention is a MIRROR of any right-handed capture - * basis: `FACE_UP` is the classic GL capture table, which only samples - * upright under GL's bottom-left framebuffer origin. WebGPU rasterizes - * top-left, so every face would land vertically flipped (v = 1 − t) at - * `texture_cube` sample time — see audit-cubemap-alignment.md. No rotation - * can absorb a reflection, hence this clip-Y negation on every capture vp. - * The winding reversal it implies is harmless: the capture roster is - * entirely cull-free point/billboard pipelines. + * Negate a vp's clip-Y row (column-major 1/5/9/13). `FACE_UP` is the GL + * capture table, upright only under GL's bottom-left origin; WebGPU + * rasterizes top-left, so every face would sample flipped (v = 1 − t) and no + * rotation absorbs a reflection. The winding reversal is harmless here. */ function flipClipY(vp: Float32Array | Float64Array): void { vp[1] = -vp[1]!; @@ -94,27 +74,24 @@ export function skyCubemapFaceContext(input: { readonly eyeMpc: Readonly; readonly face: CubeFace; readonly faceSizePx: number; - /** The FRAME's stamped clock, so a roster layer that animates on `nowMs` - * ticks identically on a captured face and in the direct view. */ + /** The FRAME's clock, so a `nowMs`-animated roster layer ticks identically + * on a captured face and in the direct view. */ readonly nowMs: number; }): ReadyFrameContext | null { const { state, eyeMpc, face, faceSizePx, nowMs } = input; const forward = FACE_FORWARD[face]!; const basis = FACE_BASES[face]!; - // target = eyeMpc + forward, distance = 1: `updatePosition` then derives - // position = target + 1·(-forward) = eyeMpc exactly, for every face. + // A target one unit ahead at distance 1 puts the derived eye back on + // `eyeMpc` exactly, on every face. const target: Vec3 = [eyeMpc[0] + forward[0], eyeMpc[1] + forward[1], eyeMpc[2] + forward[2]]; const pose: CameraPose = { target, yaw: 0, pitch: 0, distance: 1 }; const ctx = deriveFrameContext( state, - // deriveFrameContext only reads `.width`/`.height` off this — there is no - // real canvas for an offscreen capture, so a size-shaped stub stands in. + // Only `.width`/`.height` are read, and an offscreen capture has no canvas. { width: faceSizePx, height: faceSizePx } as unknown as HTMLCanvasElement, pose, - // 90° symmetric frustum sized for a cube face. near = SKY_CAPTURE_NEAR_MPC - // (see its docblock); far rides the live engine projection so distant - // stars/galaxies at cosmological range still survive the capture. + // 90° symmetric frustum, one cube face; `far` rides the live projection. { fovYRad: Math.PI / 2, aspect: 1, @@ -123,19 +100,16 @@ export function skyCubemapFaceContext(input: { }, basis, basis, - // Draw mask, not pick: this is a real capture pass, not a click target. - deriveSourceMasks(state).draw, + deriveSourceMasks(state).draw, // draw mask: a capture, not a click target + nowMs, state.cameraRuntime.lastRenderedSimDays.current, ); if (!ctx.isReady) return null; - // Mirror every capture vp (see flipClipY). In place: deriveFrameContext - // freshly allocated these arrays for this call, nothing else aliases them. + // In place is safe: `deriveFrameContext` freshly allocated these arrays. flipClipY(ctx.vp); for (const slab of ctx.slabs) flipClipY(slab.vp); - // Stamp this face's view slot (`face + 1` — slot 0 is the main view; see - // `ReadyFrameContext.viewSlot`'s doc) so a roster renderer's view-slot - // buffer helper keys this call's writes into a destination the main - // view's own `viewSlot: 0` draw never touches. + // Slot 0 is the main view, so the view-slot rings keep this call's writes + // off the real frame's (`ReadyFrameContext.viewSlot`). return { ...ctx, viewSlot: face + 1 }; } diff --git a/src/services/engine/frame/slabs.ts b/src/services/engine/frame/slabs.ts index e712be5a77..1877002a6c 100644 --- a/src/services/engine/frame/slabs.ts +++ b/src/services/engine/frame/slabs.ts @@ -108,7 +108,7 @@ export function layerTimingSlotName(layerName: string, slabIndex: number, face?: /** * The per-STEP query-set slot name for a render step that may carry a - * `face` (Task 12's sky-cubemap capture) — `groupKey` unchanged, or + * `face` (the sky-cubemap capture) — `groupKey` unchanged, or * `'·FACE[n]'` when a face is present. Six capture steps share one * `(target, slab)` — `('sky-cubemap', NEAR0)` — because the array-layer they * write isn't part of the `(target, slab)` key at all (unlike a body row, @@ -133,7 +133,7 @@ export function renderStepTimingSlotName( } /** - * The Task 14b (Ruling 9) lens-phase gate: whether a layer belongs to a + * The lens-phase gate: whether a layer belongs to a * render step's group, given the step's `lensPhase` (FrameStep.d.ts). Single- * sourced here because `frameProgram.ts`'s `timedSlotRowsOf` (the derived * timing-slot list) and `executeFrame`'s group filter (the actual draw diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts index 74c7c1e4a2..2e139fa63a 100644 --- a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -1,31 +1,14 @@ /** * sgrAStarLensingRenderer — the Sgr A* lens pass: one billboard draw per - * frame classifying capture/escape/annulus rays against the Task 9 LUT and - * the Task 11 sky cubemap. Structural precedent: `bodyGlintRenderer.ts` (a - * small single-draw body renderer, explicit non-'auto' bind group layout, - * `label:` on every resource). + * frame classifying capture/escape/annulus rays against the deflection LUT + * and the sky cubemap. Structural precedent: `bodyGlintRenderer.ts`. * - * ### The LUT texture — `Infinity` encoding (Task 13's brief, decided here) + * LANDMINE — the LUT's captured samples are IEEE `Infinity`, which a + * fast-math compiler need not preserve, so they upload as + * `CAPTURE_SENTINEL_RAD` and the fragment threshold-tests instead. * - * `buildSchwarzschildDeflectionLut`'s captured samples are IEEE `Infinity`. - * That round-trips through an `r32float` texel's raw bits exactly, but a - * fast-math shader compiler is not guaranteed to preserve Infinity - * arithmetic (this codebase already treats float edge-case flushing as a - * live landmine — see the renderer landmines). Rather than ship raw - * Infinity through the upload and rely on GPU-side comparisons behaving, - * this helper replaces every `Infinity` sample with `CAPTURE_SENTINEL_RAD` - * — a large finite value comfortably separated from any real (finite) - * quadrature result — before `writeTexture`. The fragment's - * `CAPTURE_THRESHOLD_RAD` (half the sentinel) is the GPU-side counterpart; - * the two constants don't need to agree exactly, only that the threshold - * sits between the largest real bend angle and the sentinel. - * - * ### Why a `texture_2d` of height 1, not `texture_1d` - * - * docs/RENDERER.md's iOS/WebKit landmine: `textureSampleLevel` has no 1D - * overload, and WebKit rejects `texture_1d` sampling Chrome accepts. Every - * 1D LUT in this codebase is an N×1 `texture_2d` instead — this one follows - * the same convention. + * LANDMINE — the LUT is an N×1 `texture_2d`: `textureSampleLevel` has no 1D + * overload and WebKit rejects the `texture_1d` Chrome accepts. */ import type { Renderer } from '../../../../@types/rendering/Renderer'; diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl index cbd0c9e2a4..e3b18c6531 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl @@ -2,11 +2,9 @@ // capture (black), escape (LUT-deflected sky-cubemap sample), or annulus // (bounded emission march), composited over the escape/capture base. // -// 'Infinity' encoding: the LUT's captured samples (b <= b_c, see -// buildSchwarzschildDeflectionLut.ts) are non-finite; 'sgrAStarLensingRenderer -// .ts' replaces them with a finite sentinel before the r32float upload (raw -// Infinity isn't guaranteed to survive a fast-math shader compiler), so -// 'CAPTURE_THRESHOLD_RAD' below is a threshold check, not an isinf() test. +// The LUT's captured samples upload as a finite sentinel (raw Infinity isn't +// guaranteed to survive a fast-math compiler), so 'CAPTURE_THRESHOLD_RAD' is +// a threshold check, not an isinf() test. import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; import package::lib::math::rotateAroundAxis; @@ -28,20 +26,18 @@ struct FsIn { const CAPTURE_THRESHOLD_RAD: f32 = 500.0; const MARCH_STEPS: i32 = 48; // within the spec's 32-64-step bound -// Impact-parameter margin past outerRs beyond which the annulus march is -// skipped (see the gate in 'fs' for the exactness argument). +// Impact-parameter margin past outerRs past which the march is skipped +// (the gate in 'fs' carries the exactness argument). const MARCH_GATE_MARGIN_RS: f32 = 4.0; -// Split across the bent-ray march's two segments (Task 13c finding 3). -const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; -const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // inner/outer annulus edge softening width -// The disc scale height and Doppler strength are uniform fields -// ('u.diskScaleHeightRs' / 'u.dopplerStrength'), not consts: both are live -// DebugPanel knobs. - -// Two-tap manual lerp (r32float isn't sampler-filterable without the -// optional feature, hence textureLoad + a texture_2d, not texture_1d — -// WebKit rejects the latter, docs/RENDERER.md). Either tap hitting the -// sentinel propagates it unblended, never averaging a real angle with it. +const SEGMENT_STEPS: i32 = MARCH_STEPS / 2; // split across the two segments +const RADIAL_EDGE_FEATHER_RS: f32 = 0.3; // annulus edge softening width +// Disc scale height and Doppler strength are uniform fields, not consts: +// both are live DebugPanel knobs. + +// Two-tap manual lerp: r32float isn't sampler-filterable without the optional +// feature, hence textureLoad on a texture_2d (WebKit rejects the +// texture_1d Chrome accepts, docs/RENDERER.md). Either tap hitting the +// sentinel propagates it unblended, never averaging it with a real angle. fn sampleLut(impactParamRs: f32) -> f32 { let span = max(u.lutMaxImpactParamRs - u.lutMinImpactParamRs, 1e-6); let t = saturate((impactParamRs - u.lutMinImpactParamRs) / span); @@ -57,20 +53,18 @@ fn sampleLut(impactParamRs: f32) -> f32 { return mix(a0, a1, fract(fIdx)); } -// Tilt a fixed world-+Y reference by inclination, then spin its azimuth by -// positionAngle — NOT the Galactic-Centre sky frame S-star orbits use (that -// RA/Dec basis has no field in this uniform); BLACK_HOLES already calls both -// angles "visual taste", so a fixed world reference is a documented choice. +// A fixed world-+Y reference, NOT the Galactic-Centre sky frame the S-star +// orbits use — that RA/Dec basis has no field in this uniform, and both +// angles are visual taste (BLACK_HOLES) rather than measurements. fn diskNormal() -> vec3 { let tilted = rotateAroundAxis(vec3(0.0, 1.0, 0.0), vec3(1.0, 0.0, 0.0), u.inclinationRad); return normalize(rotateAroundAxis(tilted, vec3(0.0, 1.0, 0.0), u.positionAngleRad)); } -// Per-sample density is the product of two SOFT profiles (findings 1 & 2) -// instead of hard cutoffs, so a sample easing into the annulus fades in -// rather than switching on. 'viewDir' is the local ray direction at 'p' -// (straight in segment 1, bent in segment 2) — Doppler beaming reads off -// whichever way the photon is actually travelling there. +// Per-sample density is the product of two SOFT profiles, not hard cutoffs, +// so a sample easing into the annulus fades in rather than switching on. +// 'viewDir' is the local ray direction at 'p' (straight in segment 1, bent in +// segment 2) — Doppler beaming reads whichever way the photon travels there. fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3, stepLenM: f32) -> vec4 { let distToPlaneRs = dot(p, normal) / u.schwarzschildRadiusM; let verticalWeight = exp(-(distToPlaneRs * distToPlaneRs) / (u.diskScaleHeightRs * u.diskScaleHeightRs)); @@ -90,8 +84,7 @@ fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3 let radialDir = inPlane / max(radialM, 1e-6); let orbitDir = cross(normal, radialDir); // tangent to a circular orbit at this point let dopplerFactor = 1.0 + u.dopplerStrength * dot(orbitDir, -viewDir); - // Kepler period ~ r^1.5: a cheap per-radius phase offset (closer annuli - // lead the outer ones), not a fitted light curve — visual taste, as above. + // Kepler period ~ r^1.5 as a per-radius phase offset, not a fitted curve. let periodScale = pow(max(radialRs, 0.1), 1.5); let localPhase = u.flickerPhase + (radialRs / periodScale) * TAU; let flicker = 1.0 + u.flickerAmp * sin(localPhase); @@ -105,19 +98,15 @@ fn annulusSampleContribution(p: vec3, normal: vec3, viewDir: vec3 return vec4(tint * contribution, saturate(contribution)); } -// Bounded march (spec's 32-64-step bound) for the annulus's own emission, -// composited over the escape/capture base. Centred on 'closestT' (the ray's -// own closest approach) rather than t=0 (the camera) — the hole sits far -// outside a march window sized off 'outerRs' otherwise. - -// Two-segment bent-ray approximation (finding 3): segment 1 walks the -// straight camera ray to closest approach; segment 2 continues from that -// kink along 'deflectedDir', the same rotated direction the escape branch -// samples the sky with. A captured ray has no LUT deflection to bend by, so -// it stays on segment 1 for the full budget and plunges to the horizon, -// same as before this fix. 'jitterSeed' offsets the march start per pixel -// (finding 1); both segments share one offset since they share one step -// length. +// Bounded march for the annulus's own emission, centred on 'closestT' rather +// than the camera — a window sized off 'outerRs' misses the hole entirely. + +// Two-segment bent ray: segment 1 walks the straight camera ray to closest +// approach, segment 2 continues from that kink along 'deflectedDir' (the same +// rotation the escape branch samples the sky with). A captured ray has no LUT +// deflection to bend by, so it stays on segment 1 for its 24-step half of the +// budget and plunges to the horizon. Both segments share one 'jitterSeed' +// start offset, since they share one step length. fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflectedDir: vec3, captured: bool, jitterSeed: vec2) -> vec4 { let normal = diskNormal(); let marchHalfM = u.outerRs * u.schwarzschildRadiusM * 1.5; @@ -135,10 +124,8 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflec coverage = max(coverage, emissionSample.a); } - // Applied to the SUMMED emission, not per-sample: a flat brightness/tint - // multiplier on the whole march's output, not on the physical falloff that - // feeds 'coverage' (which stays keyed to the modeled density/radial - // profile, unscaled). + // On the SUMMED emission, not per-sample, and never on 'coverage' — that + // stays keyed to the modeled density/radial profile, unscaled. if (captured) { return vec4(emission * u.emissionStrength * u.emissionTint, coverage); } @@ -159,10 +146,8 @@ fn annulusEmission(rayDir: vec3, toAnchor: vec3, closestT: f32, deflec fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4 { let rayDir = normalize(in.posRelCamM); let toAnchor = u.anchorPosRelCamM; - // Impact parameter: perpendicular distance from the hole to the ray - // through the camera (the origin). Clamped forward — the billboard faces - // the camera and is centred on the anchor, so negative t is unreachable - // outside float error at a corner fragment. + // Impact parameter: perpendicular distance from the hole to the camera + // ray. Clamped forward — negative t is unreachable outside float error. let closestT = max(dot(toAnchor, rayDir), 0.0); let offsetVec = toAnchor - rayDir * closestT; let impactParamM = length(offsetVec); @@ -171,27 +156,22 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4(0.0); var alpha = 0.0; - // No 'b < lutMinImpactParamRs' early-out: sampleLut's saturate already - // clamps that domain to the sentinel texel, so 'captured' below still - // comes out true and the march still runs — skipping it here only cut a - // black bite out of the shadow centre where the disk's front crossing - // should read (Task 13d audit finding 3). - // Beyond the LUT domain the deflection continues as ~1/b (weak field: - // alpha = 2/b + O(1/b^2), r_s units). Scaling the clamped endpoint sample - // by lutMax/b extends it with EXACT continuity at the handoff — no reliance - // on the quadrature matching the asymptote — and only ~3% high in a tail - // that is already near-subpixel. tailScale = 1 inside the domain, so the - // capture sentinel (b <= b_c, far inside) is untouched. + // No 'b < lutMinImpactParamRs' early-out: sampleLut's saturate clamps that + // domain to the sentinel texel anyway, and skipping the march there cuts a + // black bite out of the shadow centre where the disk's front should read. + // Past the LUT domain, deflection continues as the weak field's 2/b, so + // scaling the clamped endpoint by lutMax/b extends it with EXACT continuity + // at the handoff (~3% high in an already near-subpixel tail). tailScale = 1 + // inside the domain, leaving the capture sentinel untouched. let tailScale = min(u.lutMaxImpactParamRs / max(impactParamRs, 1e-6), 1.0); let bendAngle = sampleLut(impactParamRs) * tailScale; let captured = bendAngle >= CAPTURE_THRESHOLD_RAD; // Bruneton: delta_prime = delta + deflection — the backward lookup must // rotate the ray TOWARD the hole to recover the source's asymptotic // direction. The apparent image is displaced outward, so undoing that - // displacement moves inward; '-bendAngle' bent the wrong way, which is - // why the disk's far side never rendered (Task 13d audit finding 1). - // Reused below as the annulus march's segment-2 bend (finding 3) — one - // basis for both consumers. + // displacement moves inward; '-bendAngle' bends the wrong way and the + // disk's far side never renders. Reused below as the march's segment-2 + // bend — one basis for both consumers. let axis = normalize(cross(rayDir, toAnchor)); let deflected = normalize(rotateAroundAxis(rayDir, axis, bendAngle)); @@ -209,13 +189,10 @@ fn fs(in: FsIn, @builtin(position) fragCoord: vec4) -> @location(0) vec4= b·cos(bend) > outerRs + - // feather for all b > outerRs + 4 across the tuning range — so the skip is - // output-identical, and spares the 48-step march over the (much larger, - // now fade-extended) escape region. Captured rays (b <= b_c ~ 2.6) always - // pass this gate. + // Output-identical skip: radialWeight is exactly 0 once the ray's closest + // approach clears outerRs + RADIAL_EDGE_FEATHER_RS, and that approach is + // >= b·cos(bend) > outerRs + feather for every b past the margin across the + // tuning range. Captured rays always pass the gate. if (impactParamRs <= u.outerRs + MARCH_GATE_MARGIN_RS) { let annulus = annulusEmission(rayDir, toAnchor, closestT, deflected, captured, fragCoord.xy); color += annulus.rgb; diff --git a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl index 0d8dce790e..c688d403c4 100644 --- a/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl +++ b/src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl @@ -1,9 +1,7 @@ // bodies/sgrAStarLensing/vertex.wesl — camera-facing billboard covering -// Sgr A*'s lensing halo. Not a fullscreen triangle: -// 'SgrAStarLensingUniforms' carries no inverse-viewProj/camera basis, so a -// flat quad's exact perspective-interpolated plane position stands in for -// an unprojected ray (the fragment normalizes it) — the quad's own basis is -// a look-at built from 'anchorPosRelCamM' alone. +// Sgr A*'s lensing halo. Not a fullscreen triangle: the uniform carries no +// inverse-viewProj, so the quad's perspective-interpolated plane position +// stands in for an unprojected ray (the fragment normalizes it). import package::lib::sgrAStarLensing::SgrAStarLensingUniforms; import package::lib::camera::worldToClip; @@ -11,15 +9,13 @@ import package::lib::billboard::quadCorner; @group(0) @binding(0) var u: SgrAStarLensingUniforms; -// Slack on the exactly-computed fade-covering plane radius below — only -// float rounding to absorb, so the fragment's fade always reaches 0 strictly -// inside the quad. +// Slack on the exact fade-covering radius, so the fragment's fade always +// reaches 0 strictly inside the quad. const BILLBOARD_MARGIN: f32 = 1.1; struct VsOut { @builtin(position) clip: vec4, - // Camera-relative billboard-plane position, perspective-interpolated - // (the fragment renormalizes after interpolation). + // Camera-relative plane position; the fragment renormalizes it. @location(0) posRelCamM: vec3, }; @@ -28,16 +24,15 @@ fn vs(@builtin(vertex_index) vi: u32) -> VsOut { let toAnchor = u.anchorPosRelCamM; let anchorDistM = length(toAnchor); // Look-at basis from the anchor direction alone; degenerate only along - // world +Y, unreachable while the camera looks toward the hole ('enabled'). + // world +Y, unreachable while the camera looks toward the hole. let forward = toAnchor / max(anchorDistM, 1e-6); let worldUp = vec3(0.0, 1.0, 0.0); let right = normalize(cross(worldUp, forward)); let up = cross(forward, right); - // Half-size arrives finished from the CPU ('lensQuadPlaneRadiusRs', f64, - // capped at 8x the anchor distance): the b = R·d/sqrt(R^2+d^2) inversion - // used to run here in f32 and degenerated close-in into a ~5e4x-oversized - // quad whose varying interpolation shook every ray (audit §9). + // Half-size arrives finished from the CPU ('lensQuadPlaneRadiusRs', f64): + // in f32 HERE the b = R·d/sqrt(R^2+d^2) inversion degenerates close-in into + // a ~5e4x-oversized quad whose interpolation shakes every ray. let worldRadiusM = u.schwarzschildRadiusM * u.quadPlaneRadiusRs * BILLBOARD_MARGIN; let corner = quadCorner(vi); let posRelCamM = toAnchor + right * (corner.x * worldRadiusM) + up * (corner.y * worldRadiusM); diff --git a/src/utils/gpu/createViewSlotUniformRing.ts b/src/utils/gpu/createViewSlotUniformRing.ts index 1718e71f72..03f57d4b84 100644 --- a/src/utils/gpu/createViewSlotUniformRing.ts +++ b/src/utils/gpu/createViewSlotUniformRing.ts @@ -1,28 +1,12 @@ /** - * createViewSlotUniformRing — one fixed-size uniform buffer PER view slot - * (Task 13b, Ruling 7), so a renderer's per-frame `writeBuffer` survives a - * sky-cubemap capture sweep intact. + * createViewSlotUniformRing — one fixed-size uniform buffer PER view slot, so + * a renderer's per-frame `writeBuffer` survives a sky-cubemap capture sweep. * - * A capture sweep calls a roster renderer's `draw()` once per face (a - * synthetic `ReadyFrameContext`) plus once for the real view, ALL before one - * `submit()`. A single shared buffer keeps only the LAST of those writes — - * `queue.writeBuffer` calls apply in call order, but every recorded draw only - * reads its bound buffer's contents at `submit()` time, by which point every - * write already landed (docs/RENDERER.md landmine #1). Giving each - * `ctx.viewSlot` its OWN physical buffer + bind group closes the race: a - * call's write and the draw recorded against it always agree on which bytes - * are theirs, because no other call ever touches that buffer. - * - * Ring-of-buffers, not one buffer + 256-byte-aligned dynamic offsets: the - * bind-group layouts this ring is built against are shared, canonical - * objects in several call sites (`FadeUniformsBgl`, `SourceUniformsBgl`) — - * consumed as-is by sibling pipelines (`galaxyPickRenderer`) that only ever - * bind slot 0. Making the layout's binding `hasDynamicOffset: true` would - * force every consumer, including ones with no multi-slot need, to supply an - * offset at bind time — a shared-type change for a single-caller feature. A - * private ring needs no layout change at all: 7 slots × ≤176 B is a rounding - * error in VRAM, so the memory a dynamic-offset scheme would save isn't - * worth the wider blast radius. + * A sweep draws once per face plus once for the real view, all before one + * `submit()`, and a recorded draw reads its bound buffer only at submit time + * — so one shared buffer hands every draw the LAST write (docs/RENDERER.md + * landmine #1). A ring, not dynamic offsets: the bind-group layouts it binds + * are shared canonical objects sibling pipelines consume as-is. */ import type { ViewSlotUniformRing } from '../../@types/rendering/ViewSlotUniformRing'; diff --git a/src/utils/lensing/lensQuadPlaneRadiusRs.ts b/src/utils/lensing/lensQuadPlaneRadiusRs.ts index a2f2f3484c..5aeaa825d0 100644 --- a/src/utils/lensing/lensQuadPlaneRadiusRs.ts +++ b/src/utils/lensing/lensQuadPlaneRadiusRs.ts @@ -1,21 +1,9 @@ /** - * lensQuadPlaneRadiusRs — half-size (r_s units) of the camera-facing lens - * billboard that covers impact parameters out to `edgeFadeEndRs` at anchor - * distance `distRs`: a fragment at plane radius R rides a ray with - * b = R·d/√(R²+d²), inverted here as R = b·d/√(d²−b²). Once b approaches or - * exceeds d (the close-orbit regime, where the lutMax floor puts - * edgeFadeEndRs ≥ distRs) the inversion degenerates — no billboard covers the - * whole sky — and the shader that used to run this in f32 inflated the quad - * ~5e4× the anchor distance, whose varying interpolation put ~3 mrad of - * barycentric noise on every ray (the close-orbit shake, audit §9). Capped at - * QUAD_RADIUS_CAP·d (half-angle atan(8) ≈ 83°, past any viewport - * half-diagonal) and computed in f64 on the CPU, so the GPU only ever sees a - * finished, smooth radius. + * Lens-billboard half-size in r_s reaching `edgeFadeEndRs` at anchor distance + * `distRs`: R = b·d/√(d²−b²). In f64 HERE because in f32 in the vertex stage + * it degenerated as b → d, inflating the quad ~5e4× and shaking every ray. + * The cap bounds that regime (b/d > 8/√65 ≈ 0.992, half-angle ≈ 83°). */ - -/** Cap engages only when edgeFadeEndRs/distRs > 8/√65 ≈ 0.992 — reachable - * solely via the lutMax floor (distRs ≲ 50), where full fade coverage is - * impossible for any billboard anyway. */ const QUAD_RADIUS_CAP = 8; export function lensQuadPlaneRadiusRs(edgeFadeEndRs: number, distRs: number): number { From 7e4c170d78b578db871a30875486541de0aa120a Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:07:37 +0200 Subject: [PATCH 55/60] fix(sgr-a-star): sky-cubemap release hysteresis + re-review residual cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-review of the black-hole lensing fix round left six residuals; this closes them all: - renderTargets.ts's sky-cubemap `allocateWhen` gated release on a single hard threshold (the lensing band's goneAt, 500 AU), so a camera dithering across that edge destroyed + reallocated 50 MB + 7 views every frame. Now hysteretic: the row is entered on band-active as before, but once allocated it survives until the camera-to-anchor distance exceeds 1.5x goneAt (SKY_CUBEMAP_ROW_RELEASE_MARGIN), fed through the existing `allocateWhen` seam via a new `isAllocated` parameter and a per-frame `gcDistanceMpc` recorded on the capture runtime. - Plan text: Task 16 no longer waits on a "tuning-removal" step the Settings amendment already dropped; Task 17's visual gate picks up the Milky-Way quad-rim discontinuity and the capture-face aggregate knee, both new in this fix wave and never eyeballed; Task 16 now requires a VRAM line for the sky-cubemap row. - Dropped the remaining ledger-speak (`Ruling N` citations with no in-repo referent; `Task N` citations converted to timeless wording) across the sites the re-review enumerated. - starCatalogRenderer's two star pipelines are labelled by compression (kneed/linear) instead of by stream, matching how they're actually keyed. - Fixed the renderFrame.test.ts fixture comment (and its two copies) that claimed the sky-cubemap bookkeeping runs every frame regardless of the band — false since the m9 fix folded the schedule fields under `if (bandActive)`. Co-Authored-By: Claude Code --- .../plans/2026-09-01-render-black-hole.md | 15 ++++++- src/@types/engine/frame/ContentLayer.d.ts | 6 +-- src/@types/engine/frame/ExecuteFrameArgs.d.ts | 2 +- src/@types/engine/frame/FrameStep.d.ts | 2 +- src/@types/engine/frame/RenderTargetSpec.d.ts | 8 +++- .../state/SkyCubemapCaptureRuntime.d.ts | 10 ++++- .../rendering/SgrAStarLensingRenderer.d.ts | 4 +- src/services/engine/engine.ts | 3 ++ .../engine/frame/passes/bodyGlintsLayer.ts | 4 +- .../frame/passes/starAggregatesLayer.ts | 2 +- .../engine/frame/passes/starCatalogLayer.ts | 4 +- src/services/engine/frame/renderFrame.ts | 4 ++ src/services/gpu/renderTargets.ts | 33 ++++++++++++-- .../gpu/renderers/bodies/starPointRenderer.ts | 8 ++-- .../starCatalog/starCatalogRenderer.ts | 10 ++--- .../playClipFlyout.integration.test.ts | 1 + .../engine/camera/commitOnEdge.test.ts | 1 + .../engine/frame/frameProgram.test.ts | 8 ++-- .../renderFrame.skyCubemapHandOff.test.ts | 1 + .../services/engine/frame/renderFrame.test.ts | 12 ++--- .../engine/frame/renderFrame.timing.test.ts | 3 +- tests/services/gpu/renderTargets.test.ts | 44 ++++++++++++++++++- tests/visual/renderFrameSplitBaseline.test.ts | 5 ++- 23 files changed, 150 insertions(+), 40 deletions(-) diff --git a/docs/superpowers/plans/2026-09-01-render-black-hole.md b/docs/superpowers/plans/2026-09-01-render-black-hole.md index e756abc388..80e197626a 100644 --- a/docs/superpowers/plans/2026-09-01-render-black-hole.md +++ b/docs/superpowers/plans/2026-09-01-render-black-hole.md @@ -1026,13 +1026,20 @@ gate). branch's server). Record the baseline numbers outside the band (Sgr A* far off-frame) and note there is no "inside the band" baseline yet (the feature doesn't exist). -- [ ] AFTER Task 15 (all feature work + tuning-removal done): re-run +- [ ] AFTER Task 15 (all feature work done — the tuning section ships, per + the Settings amendment above, so there is no removal step to wait on): + re-run `npm run perf` the same way, twice — once with Sgr A* far outside the lensing band (expect a neutral delta vs. the baseline — Q6's zero-cost guarantee), once with the camera inside the band (expect a bounded, not unbounded, cost — the six-face capture amortized per Q8, the LUT lookup O(1) per pixel, the bounded 32–64-step march only for annulus-adjacent pixels). +- [ ] The report must carry a VRAM line for the `sky-cubemap` row alongside + the timing numbers: 0 B outside the band, 50 MB in-band at the shipped + 1024 px resolution, 201 MB at the 2048 px knob — the row is lazily + allocated (`renderTargets.ts`), so this cost is invisible to a timing + reading alone. - [ ] Report both readings plainly. Per the spec's Perf section and the project's code-is-liability convention: a regression outside the band, or an unbounded/unacceptable cost inside it, HALTS the landing @@ -1062,6 +1069,12 @@ gate). angle); - [ ] the fade band crossfades without a pop at either edge; - [ ] the far-field glint hands off to the close-up without a visible seam. +- [ ] Also judge two items outside the spec's original five, added by the fix + round's re-review: the Milky-Way discontinuity at the lens quad's rim + (the MW cloud is deliberately not in the capture roster, so its edge + against the captured sky can show a seam), and the capture-face + aggregate knee (relabelled kneed/un-kneed this round — never eyeballed + before this gate). - [ ] Report the outcome per item. Any failing item is a STOP — fix and re-gate, not a partial ship. - [ ] Only once every item passes AND Task 16's perf gate is clean does this diff --git a/src/@types/engine/frame/ContentLayer.d.ts b/src/@types/engine/frame/ContentLayer.d.ts index 867070dbbc..931998afdd 100644 --- a/src/@types/engine/frame/ContentLayer.d.ts +++ b/src/@types/engine/frame/ContentLayer.d.ts @@ -58,8 +58,8 @@ export type ContentLayer = { */ readonly blend: Blend; /** - * Opt-in to the black-hole lens's sky-cubemap capture roster (Task 12/13, - * Ruling 6). A capture step (`FrameStep.face` present) selects its group by + * Opt-in to the black-hole lens's sky-cubemap capture roster (Task 12/13). + * A capture step (`FrameStep.face` present) selects its group by * THIS flag instead of `target` — the six capture steps all target * `'sky-cubemap'`, not this layer's own `target`, so target-matching can't * select the roster at all (see `executeFrame`'s capture-step branch). @@ -72,7 +72,7 @@ export type ContentLayer = { readonly skyCapture?: true; /** * Opt-in to the `'post'` half of the black-hole lens's `(hdr, NEAR0)` - * step split (Task 14b, Ruling 9): set only by `orbitTrailsLayer` and + * step split (Task 14b): set only by `orbitTrailsLayer` and * `bodyGlintsLayer`, the two rows the spec keeps unwarped ON TOP of the * lens rather than sampled by it. `frameProgram` only emits the split * (and a `'post'` step) when the lens's own `(hdr, BODY[k])` step fires — diff --git a/src/@types/engine/frame/ExecuteFrameArgs.d.ts b/src/@types/engine/frame/ExecuteFrameArgs.d.ts index 6665b7a339..1d5b02a55e 100644 --- a/src/@types/engine/frame/ExecuteFrameArgs.d.ts +++ b/src/@types/engine/frame/ExecuteFrameArgs.d.ts @@ -18,7 +18,7 @@ * production); `swapView` is this frame's acquired swap-chain view, the * one render target that is not an allocated offscreen texture. * - `skyCubemapFaceContexts` is the black-hole lens's per-face camera - * override (Task 12's runtime hand-off): a step carrying `face` + * override, its runtime hand-off: a step carrying `face` * resolves its `SlabView`/`ctx` from THIS map instead of the frame-wide * `ctx` above. `renderFrame` derives it each frame (one * `skyCubemapFaceContext` call per scheduled face); `frameProgram` diff --git a/src/@types/engine/frame/FrameStep.d.ts b/src/@types/engine/frame/FrameStep.d.ts index 5474996685..04aed20818 100644 --- a/src/@types/engine/frame/FrameStep.d.ts +++ b/src/@types/engine/frame/FrameStep.d.ts @@ -68,7 +68,7 @@ export type FrameStep = face?: CubeFace; /** * Splits the shared `(hdr, NEAR0)` roster step around the black-hole - * lens's own `(hdr, BODY[k])` step (Task 14b, Ruling 9), so + * lens's own `(hdr, BODY[k])` step (Task 14b), so * `orbit-trails`/`body-glints` draw AFTER the lens rather than being * sampled by it. Absent ⇒ every layer matches, the pre-Task-14b * behaviour. `'pre'` admits every `(hdr, NEAR0)` layer EXCEPT those diff --git a/src/@types/engine/frame/RenderTargetSpec.d.ts b/src/@types/engine/frame/RenderTargetSpec.d.ts index e672655fb0..3871181e01 100644 --- a/src/@types/engine/frame/RenderTargetSpec.d.ts +++ b/src/@types/engine/frame/RenderTargetSpec.d.ts @@ -63,6 +63,12 @@ export type RenderTargetSpec = { * resolution, read only within ~500 AU of Sgr A*). A consumer must be * gated on the SAME condition — `viewOf`/`sizeOf` throw while the row is * released. + * + * `isAllocated` is `reconcile`'s own record of whether the row currently + * holds a texture — passed in so a row can add hysteresis around its own + * activation condition (keep the row through a brief close, drop it only + * once truly gone) without `renderTargets.ts` growing bespoke state to + * track it. */ - allocateWhen?: (state: EngineState) => boolean; + allocateWhen?: (state: EngineState, isAllocated: boolean) => boolean; }; diff --git a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts index 5e55aa06d2..44bfcfa786 100644 --- a/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts +++ b/src/@types/engine/state/SkyCubemapCaptureRuntime.d.ts @@ -1,6 +1,6 @@ /** * SkyCubemapCaptureRuntime — cross-frame memory for the black-hole lens's - * amortized sky-cubemap capture (Task 12). `skyCubemapCaptureSchedule` is + * amortized sky-cubemap capture. `skyCubemapCaptureSchedule` is * pure, but its inputs (`lastCapturedAtMs`, the round-robin `frameIndex`, the * `bandJustEngaged` edge) need somewhere to live between frames — * `renderFrame` "owns no cross-frame state" by design (see its module @@ -25,6 +25,14 @@ export type SkyCubemapCaptureRuntime = { * whether its texture exists at all (`renderTargets.ts`). */ bandActive: boolean; + /** + * The camera's distance from the galactic-centre anchor as of the last + * rendered frame, Mpc — updated every frame regardless of `bandActive`. + * The `sky-cubemap` row's `allocateWhen` reads it to decide whether an + * already-allocated row should survive a bit past band close (hysteresis + * margin — see `renderTargets.ts`). + */ + gcDistanceMpc: number; /** * The eye EVERY face was captured from at the last full sweep. Round-robin * refreshes reuse this same pinned eye rather than the live camera each diff --git a/src/@types/rendering/SgrAStarLensingRenderer.d.ts b/src/@types/rendering/SgrAStarLensingRenderer.d.ts index 1c2bbac527..3d8f749e20 100644 --- a/src/@types/rendering/SgrAStarLensingRenderer.d.ts +++ b/src/@types/rendering/SgrAStarLensingRenderer.d.ts @@ -5,8 +5,8 @@ * accretion annulus (bounded-march emission), composited premultiplied-OVER * into the depthless `hdr` target. * - * The LUT (Task 9's `SchwarzschildDeflectionLut`) is built once at - * construction and uploaded to a static `r32float` texture — `lut` is + * The LUT (`SchwarzschildDeflectionLut`) is built once at construction and + * uploaded to a static `r32float` texture — `lut` is * exposed back so the layer can read `minImpactParamRs`/`maxImpactParamRs`/ * `samples.length` for the uniform pack without re-deriving them. */ diff --git a/src/services/engine/engine.ts b/src/services/engine/engine.ts index 58bedfb121..e816c3c1fc 100644 --- a/src/services/engine/engine.ts +++ b/src/services/engine/engine.ts @@ -188,6 +188,9 @@ export function createEngine(canvas: HTMLCanvasElement, cb: EngineCallbacks): En lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + // Far outside the band pre-boot, so the row's hysteresis margin can't + // mistake "never measured" for "just closed". + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }; diff --git a/src/services/engine/frame/passes/bodyGlintsLayer.ts b/src/services/engine/frame/passes/bodyGlintsLayer.ts index ed3cb212f9..5ec36cc873 100644 --- a/src/services/engine/frame/passes/bodyGlintsLayer.ts +++ b/src/services/engine/frame/passes/bodyGlintsLayer.ts @@ -162,8 +162,8 @@ export const bodyGlintsLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', - // Opts into the black-hole lens's `'post'` split half (Task 14b, Ruling 9) - // so this layer's own Sgr A* far-field marker (and any solar-system glint + // Opts into the black-hole lens's `'post'` split half (Task 14b) so this + // layer's own Sgr A* far-field marker (and any solar-system glint // that happens to overlap it on screen) draws unwarped ON TOP of the lens // rather than being sampled by it — see frameProgram.ts's step-split doc. hdrPostLensing: true, diff --git a/src/services/engine/frame/passes/starAggregatesLayer.ts b/src/services/engine/frame/passes/starAggregatesLayer.ts index a1d0e17cf7..18cb8d480e 100644 --- a/src/services/engine/frame/passes/starAggregatesLayer.ts +++ b/src/services/engine/frame/passes/starAggregatesLayer.ts @@ -61,7 +61,7 @@ export const starAggregatesLayer: ContentLayer = { // viewport-independent). `viewSlot !== 0` marks a sky-cubemap capture draw // (this layer's `skyCapture` flag, see `ReadyFrameContext.viewSlot`'s // doc), which targets the `sky-cubemap` face — its own declared size (a - // live setting as of Task 15), not this row's. The view is COPIED rather + // live setting), not this row's. The view is COPIED rather // than mutated: one `SlabView` is shared by every layer in the render // step. const destTarget = ctx.viewSlot !== 0 ? 'sky-cubemap' : 'star-aggregates'; diff --git a/src/services/engine/frame/passes/starCatalogLayer.ts b/src/services/engine/frame/passes/starCatalogLayer.ts index 8fbdc7b3ab..d87d94a8ee 100644 --- a/src/services/engine/frame/passes/starCatalogLayer.ts +++ b/src/services/engine/frame/passes/starCatalogLayer.ts @@ -921,8 +921,8 @@ export const starCatalogLayer: ContentLayer = { slab: NEAR0, target: 'hdr', blend: 'additive', - // Sky-cubemap capture roster (Task 13b, Ruling 6): the survey LEAF stream - // is part of the black-hole lens's captured "sky". + // Sky-cubemap capture roster (Task 13b): the survey LEAF stream is part of + // the black-hole lens's captured "sky". skyCapture: true, enabled: starCatalogVisible, diff --git a/src/services/engine/frame/renderFrame.ts b/src/services/engine/frame/renderFrame.ts index 4cb637e85a..27d34d429a 100644 --- a/src/services/engine/frame/renderFrame.ts +++ b/src/services/engine/frame/renderFrame.ts @@ -122,6 +122,10 @@ export function renderFrame(input: RenderFrameInput): void { GALACTIC_CENTRE_REGION, sceneBodyStates(state, ctx), ); + // Recorded unconditionally (not just while the band is active) — the + // `sky-cubemap` row's release-margin check needs the distance on the very + // frame the band closes, not one frame later. + captureRuntime.gcDistanceMpc = gcDistanceMpc; const bandActive = fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, gcDistanceMpc) > 0; const bandJustEngaged = bandActive && !captureRuntime.bandActive; diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 853f921db7..9ace4e8163 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -146,6 +146,7 @@ import type { Size } from '../../@types/rendering/Size'; import { BLOOM_LEVELS, bloomScale } from '../../data/bloomConstants'; import { HDR_TARGET_FORMAT, FOREGROUND_DEPTH_FORMAT } from '../../data/renderTargetFormats'; import { reducedTargetSize } from '../../utils/gpu/reducedTargetSize'; +import { SCALE_FADE_BANDS } from '../engine/presentation/scaleFadeBands'; /** * Downsample divisor for the half-res `star-aggregates` row — total fragment @@ -162,6 +163,16 @@ const STAR_AGGREGATE_DIVISOR = 2; */ const ZONE_OF_AVOIDANCE_DIVISOR = 5; +/** + * Hysteresis margin for the `sky-cubemap` row's `allocateWhen`: once + * allocated, the row survives until the camera-to-anchor distance exceeds + * this multiple of the lensing band's `goneAt` (500 AU) — 750 AU — rather + * than releasing the instant the band itself closes. Without it, a camera + * dithering across the 500 AU edge destroys and reallocates the row's 50 MB + * + 7 views every frame. + */ +const SKY_CUBEMAP_ROW_RELEASE_MARGIN = 1.5; + /** A row's divisor for this state — constant rows ignore the state entirely. */ function resolveScale(spec: RenderTargetSpec, state: EngineState): number { return typeof spec.scale === 'function' ? spec.scale(state) : spec.scale; @@ -272,14 +283,26 @@ export function renderTargetRows(swapFormat: GPUTextureFormat): readonly RenderT // lens draws only within ~500 AU of Sgr A*, so the texture exists only // while the band does. `renderFrame` writes the band flag and reconciles // on its edge, so the row is there on the band-entry frame — the frame - // that sweeps all six faces. + // that sweeps all six faces. Once allocated it outlives a brief close by + // `SKY_CUBEMAP_ROW_RELEASE_MARGIN` (a camera dithering across the band + // edge would otherwise destroy + reallocate the row every frame); a row + // never allocated does not spring into existence from proximity alone — + // only `bandActive` triggers first allocation. { id: 'sky-cubemap', format: HDR_TARGET_FORMAT, depth: null, scale: 1, // unused: fixedSizePx below overrides it (required by the type). clearValue: { r: 0, g: 0, b: 0, a: 0 }, - allocateWhen: (state) => state.cameraRuntime.skyCubemapCapture.bandActive, + allocateWhen: (state, isAllocated) => { + const capture = state.cameraRuntime.skyCubemapCapture; + if (capture.bandActive) return true; + return ( + isAllocated && + capture.gcDistanceMpc <= + SKY_CUBEMAP_ROW_RELEASE_MARGIN * SCALE_FADE_BANDS.sgrAStarLensing.goneAt + ); + }, // `size` is a live setting (the DebugPanel resolution knob, // 256/512/1024/2048) — `reconcile` resolves it every frame exactly like // `mw-aggregate`'s divisor, so dragging the knob reallocates this row @@ -443,7 +466,11 @@ export function createRenderTargets( // A row that declares `allocateWhen` holds VRAM only while its // condition does — same per-frame seam as a moved size, so entering // and leaving the condition need no lifecycle path of their own. - if (spec.allocateWhen !== undefined && !spec.allocateWhen(s)) { + // `sizes.has` (not `textures.has`) is the "currently allocated" signal + // a hysteresis predicate needs — it's cleared by `release` in lockstep + // with the texture, so a row can't observe itself as allocated the + // frame after it was dropped. + if (spec.allocateWhen !== undefined && !spec.allocateWhen(s, sizes.has(spec.id))) { release(spec.id); continue; } diff --git a/src/services/gpu/renderers/bodies/starPointRenderer.ts b/src/services/gpu/renderers/bodies/starPointRenderer.ts index 66c1a687a0..9602871563 100644 --- a/src/services/gpu/renderers/bodies/starPointRenderer.ts +++ b/src/services/gpu/renderers/bodies/starPointRenderer.ts @@ -112,7 +112,7 @@ export function createStarPointRenderer( }, ], }); - // One physical buffer + bind group per view slot (Task 13b): a sky-cubemap + // One physical buffer + bind group per view slot: a sky-cubemap // capture sweep calls `draw()` several times per frame with different // cameras, all before one `submit()` — a shared buffer would keep only the // last call's camera (see `createViewSlotUniformRing`'s doc). @@ -171,8 +171,8 @@ export function createStarPointRenderer( // `setStars` EVERY frame — the camera-relative anchors it hands us change // per frame (the eye is subtracted in f64 before narrowing here). A // create/destroy of the GPU buffer per call would mean a fresh allocation - // and release 60×/sec on a hot path. Instead each `viewSlot` (Task 13b) gets - // its OWN buffer, allocated once sized to that slot's first non-empty set + // and release 60×/sec on a hot path. Instead each `viewSlot` gets its OWN + // buffer, allocated once sized to that slot's first non-empty set // and reallocated ONLY when a later set on that SAME slot exceeds its // capacity. One buffer per slot, not one shared buffer, because a // sky-cubemap capture sweep calls `setStars` once per face plus once for the @@ -244,7 +244,7 @@ export function createStarPointRenderer( // tail's alignment pad — never written, so they hold their construction-time // zeros across frames. sizePx / brightness ride the tail at floats 20 / 21 // (byte-exact with StarPointUniforms in starPoints/io.wesl). Written into - // THIS call's own `viewSlot` buffer (Task 13b) — see the ring's doc. + // THIS call's own `viewSlot` buffer — see the ring's doc. writeCameraPrefix(uniformScratch, viewProj, viewportPx); uniformScratch[UNIFORM_SIZEPX_INDEX] = opts.sizePx; uniformScratch[UNIFORM_BRIGHTNESS_INDEX] = opts.brightness; diff --git a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts index e805630d5e..9e8ffd422e 100644 --- a/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts +++ b/src/services/gpu/renderers/starCatalog/starCatalogRenderer.ts @@ -131,7 +131,7 @@ import { * One draw stream's per-source, per-view-slot storage buffers: the * contiguous NodeParams block and the parallel prefix sum, plus their shared * grow-only capacity. A stream (leaf or aggregate) owns its OWN pair per - * `ReadyFrameContext.viewSlot` (Task 13b) — a sky-cubemap capture sweep draws + * `ReadyFrameContext.viewSlot` — a sky-cubemap capture sweep draws * a source's cut once per face plus once for the real view, ALL before one * `submit()`, and every one of those calls is a DIFFERENT cut (different * camera), so a pair shared across view slots would read only the @@ -185,7 +185,7 @@ export function createStarCatalogRenderer( label: 'star-catalog-camera-bgl', entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } }], }); - // One physical camera buffer + bind group per view slot (Task 13b): the + // One physical camera buffer + bind group per view slot: the // camera is shared across SOURCES within one `draw` call, but NOT across // view slots — a capture sweep's several `draw` calls (different faces, // one submit) each carry a different vp (see the module header). @@ -259,8 +259,8 @@ export function createStarCatalogRenderer( // knee'd pipeline when it draws somewhere the knee'd upsample can't follow // it (a sky-cubemap capture face — see `StarCatalogDrawArgs.knee`). const pipelines = { - kneed: makePipeline('star-catalog-leaf-pipeline', 'fs'), - linear: makePipeline('star-catalog-aggregate-pipeline', 'fsLinear'), + kneed: makePipeline('star-catalog-kneed-pipeline', 'fs'), + linear: makePipeline('star-catalog-linear-pipeline', 'fsLinear'), }; // ── Per-source store ────────────────────────────────────────────────────── @@ -422,7 +422,7 @@ export function createStarCatalogRenderer( // the module header), but NOT across view slots — a sky-cubemap capture // sweep's several `draw` calls (different faces, one submit) each carry // a different vp, so this call's bytes land in THIS `viewSlot`'s own - // buffer (Task 13b). floats 18/19 stay zero-init. `sizePx`, `brightness`, + // buffer. floats 18/19 stay zero-init. `sizePx`, `brightness`, // `glowOverlap` and `aggregateIntensityCap` ride this buffer too — all // four are source-independent (the same base star-dot size + exposure // trim + glow spread + aggregate peak ceiling for every source this diff --git a/tests/services/engine/animation/playClipFlyout.integration.test.ts b/tests/services/engine/animation/playClipFlyout.integration.test.ts index 9dd611d921..35edc6def2 100644 --- a/tests/services/engine/animation/playClipFlyout.integration.test.ts +++ b/tests/services/engine/animation/playClipFlyout.integration.test.ts @@ -122,6 +122,7 @@ function makeEngineState(startDistance: number): { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/camera/commitOnEdge.test.ts b/tests/services/engine/camera/commitOnEdge.test.ts index 215178ff23..e18368e71e 100644 --- a/tests/services/engine/camera/commitOnEdge.test.ts +++ b/tests/services/engine/camera/commitOnEdge.test.ts @@ -98,6 +98,7 @@ function makeEngineState(): { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index ea7bb10c90..05748ff094 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -278,7 +278,7 @@ describe('frameProgram', () => { }); it('sgrAStarLensingBodySlabs: emits an (hdr, slab) step per entry, after (hdr, NEAR0) and before the foreground chain', () => { - // Task 14 (Ruling 8): before this, no step ever matched + // Task 14: before this, no step ever matched // sgrAStarLensingLayer's (slab: 'body', target: 'hdr') row. One render // step per requested body-slab index, positioned so the lens's OVER blend // occludes the (hdr, NEAR0) roster already accumulated above it. @@ -300,14 +300,14 @@ describe('frameProgram', () => { expect(withDefault).toEqual(base); expect(withEmpty).toEqual(base); expect(base.some((step) => step.kind === 'render' && step.slab >= 2)).toBe(false); - // Task 14b (Ruling 9): the split discriminant must not leak outside the + // Task 14b: the split discriminant must not leak outside the // band either — the (hdr, NEAR0) step stays the single untagged step it // always was, byte-identical to pre-Task-14b. expect(base.some((step) => step.kind === 'render' && 'lensPhase' in step)).toBe(false); }); - it('sgrAStarLensingBodySlabs active: orbit-trails/body-glints move to their own step AFTER the lens step (Task 14b, Ruling 9)', () => { - // Ruling 9's evidenced gap: orbit-trails and body-glints (the S-star + it('sgrAStarLensingBodySlabs active: orbit-trails/body-glints move to their own step AFTER the lens step (Task 14b)', () => { + // The evidenced gap: orbit-trails and body-glints (the S-star // trails and the Sgr A* far-field glint among them) used to share the // pre-lens (hdr, NEAR0) roster step and so drew UNDER the lens's OVER // blend. `ContentLayer.hdrPostLensing` moves them into a step that runs diff --git a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts index 9b6347d001..4206fea086 100644 --- a/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts +++ b/tests/services/engine/frame/renderFrame.skyCubemapHandOff.test.ts @@ -44,6 +44,7 @@ function makeCaptureRuntime() { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }; } diff --git a/tests/services/engine/frame/renderFrame.test.ts b/tests/services/engine/frame/renderFrame.test.ts index 1ceda22f18..9d377f7a5e 100644 --- a/tests/services/engine/frame/renderFrame.test.ts +++ b/tests/services/engine/frame/renderFrame.test.ts @@ -570,16 +570,18 @@ function makeInput( fades: { opacityOf: () => 1 }, clipPlayer: { clipOpacityOf: () => 1 }, }, - // Task 12's sky-cubemap capture bookkeeping — renderFrame reads/writes - // this every frame now, regardless of whether the lensing band is - // active (the fixture camera sits Mpc-scale away from Sgr A*, so the - // band alpha is 0 and `facesToCapture` stays empty; see - // `skyCubemapCaptureSchedule`'s call site in renderFrame.ts). + // The sky-cubemap capture bookkeeping — `bandActive`/`gcDistanceMpc` + // update every frame, but the schedule fields (`frameIndex`, + // `lastCapturedAtMs`) only advance while the lensing band is active. + // The fixture camera sits Mpc-scale away from Sgr A*, so the band + // stays closed and `facesToCapture` stays empty; see + // `skyCubemapCaptureSchedule`'s call site in renderFrame.ts. cameraRuntime: { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }, diff --git a/tests/services/engine/frame/renderFrame.timing.test.ts b/tests/services/engine/frame/renderFrame.timing.test.ts index c2c536a49e..36bd945ab5 100644 --- a/tests/services/engine/frame/renderFrame.timing.test.ts +++ b/tests/services/engine/frame/renderFrame.timing.test.ts @@ -372,13 +372,14 @@ function makeMinimalInputWithTiming(timingService: GpuTimingService): { fades: { opacityOf: (id: { kind: string }) => (id.kind === 'milkyWay' ? 1 : 0) }, clipPlayer: { clipOpacityOf: () => 1 }, }, - // Task 12's sky-cubemap capture bookkeeping — see the matching fixture + // The sky-cubemap capture bookkeeping — see the matching fixture // comment in renderFrame.test.ts. cameraRuntime: { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }, diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index 00ed17ff94..f991b05dea 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -10,6 +10,7 @@ */ import { describe, it, expect, vi } from 'vitest'; import { createRenderTargets } from '../../../src/services/gpu/renderTargets'; +import { SCALE_FADE_BANDS } from '../../../src/services/engine/presentation/scaleFadeBands'; import type { EngineState } from '../../../src/@types/engine/state/EngineState'; import type { RenderTargetSpec } from '../../../src/@types/engine/frame/RenderTargetSpec'; @@ -39,17 +40,21 @@ const SKY_CUBEMAP_RESOLUTION_PX = 256; // The production `sky-cubemap` row is lazy: its `allocateWhen` reads the // lensing band flag `renderFrame` maintains, so every state fixture carries // one. Default `true` keeps the row present for the tests that count textures. +// `gcDistanceMpc` defaults far outside the release margin so the pre-existing +// bandActive-false tests (written before the row grew hysteresis) keep their +// original "closes immediately" behaviour. function stateWithDivisor( aggregateDivisor: number, cubemapResolutionPx: number = SKY_CUBEMAP_RESOLUTION_PX, bandActive = true, + gcDistanceMpc = Number.POSITIVE_INFINITY, ): EngineState { return { settings: { milkyWay: { aggregateDivisor }, sgrAStarLensingTuning: { cubemapResolutionPx }, }, - cameraRuntime: { skyCubemapCapture: { bandActive } }, + cameraRuntime: { skyCubemapCapture: { bandActive, gcDistanceMpc } }, } as unknown as EngineState; } @@ -277,6 +282,43 @@ describe('createRenderTargets', () => { expect(() => targets.cubeViewOf('sky-cubemap')).toThrow(); }); + it('an allocateWhen row with a release margin survives a frame just past its condition, and releases beyond the margin', () => { + // Guards NEW-1 from the black-hole fix round's re-review: a camera + // dithering across the band edge must not destroy + reallocate the + // row's 50 MB every frame. `goneAt` is the band's close distance; + // `SKY_CUBEMAP_ROW_RELEASE_MARGIN` (1.5×, named beside the row in + // `renderTargets.ts`) is the row's own wider release edge. + const goneAt = SCALE_FADE_BANDS.sgrAStarLensing.goneAt; + const device = mockDevice(); + const create = device.createTexture as ReturnType; + const canvas = { width: 900, height: 600 }; + const targets = createRenderTargets( + device, + SWAP_FORMAT, + canvas, + stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, true, 0), + ); + const cubemapCallCount = (): number => + create.mock.calls.filter((c) => c[0].label === 'render-target-sky-cubemap').length; + expect(cubemapCallCount()).toBe(1); + + // Band just closed (bandActive false), but the camera sits just outside + // `goneAt` — still inside the 1.5× margin — so the row must survive. + targets.reconcile( + stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, false, goneAt * 1.1), + canvas, + ); + expect(cubemapCallCount()).toBe(1); + expect(targets.cubeViewOf('sky-cubemap')).toBeDefined(); + + // Past the margin: the row releases. + targets.reconcile( + stateWithDivisor(MW_DIVISOR, SKY_CUBEMAP_RESOLUTION_PX, false, goneAt * 1.6), + canvas, + ); + expect(() => targets.cubeViewOf('sky-cubemap')).toThrow(); + }); + it("reconcile reallocates a row whose state-driven scale moved and leaves the other rows' views untouched", () => { const device = mockDevice(); const create = device.createTexture as ReturnType; diff --git a/tests/visual/renderFrameSplitBaseline.test.ts b/tests/visual/renderFrameSplitBaseline.test.ts index c4c4d01a79..a89c385ed8 100644 --- a/tests/visual/renderFrameSplitBaseline.test.ts +++ b/tests/visual/renderFrameSplitBaseline.test.ts @@ -500,13 +500,14 @@ describe('renderFrame visual baseline', () => { }, clipPlayer: { clipOpacityOf: () => 1 }, }, - // Task 12's sky-cubemap capture bookkeeping — see the matching - // fixture comment in renderFrame.test.ts. + // The sky-cubemap capture bookkeeping — see the matching fixture + // comment in renderFrame.test.ts. cameraRuntime: { skyCubemapCapture: { lastCapturedAtMs: new Map(), frameIndex: 0, bandActive: false, + gcDistanceMpc: Number.POSITIVE_INFINITY, pinnedEyeMpc: null, }, }, From e7096abe7abcc22a4a2b576d34eb4db8ae92a8e1 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:13:02 +0200 Subject: [PATCH 56/60] =?UTF-8?q?perf(harness):=20sgr-a-star-lens=20scenar?= =?UTF-8?q?io=20=E2=80=94=20the=20in-band=20regime?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- tools/perf/perfScenarios.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/tools/perf/perfScenarios.ts b/tools/perf/perfScenarios.ts index b4d11f49b2..1d02e0f51c 100644 --- a/tools/perf/perfScenarios.ts +++ b/tools/perf/perfScenarios.ts @@ -126,6 +126,19 @@ export const PERF_SCENARIOS: readonly PerfScenario[] = [ clearFocus: true, }, }, + // Inside the Sgr A* lensing band (~96 AU, band alpha 1): the one regime + // where the sky-cubemap capture + lens pass exist. galactic-centre above + // sits at ~100k AU, far outside the band, and measures the zero-cost side. + { + name: 'sgr-a-star-lens', + pose: { + target: SGR_A_STAR_TARGET, + distance: 4.666596145942944e-10, + yaw: -1.1153012483898652, + pitch: -0.2734819118684762, + clearFocus: true, + }, + }, { name: 'local-group', pose: { target: EARTH_TARGET, distance: 21.268361, yaw: 8.2811, pitch: 0.5612 }, From 8abd7ac1e7b54d8ef5b127ed142248494aae38d6 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:31:42 +0200 Subject: [PATCH 57/60] =?UTF-8?q?chore(black-hole):=20deletion-audit=20?= =?UTF-8?q?=E2=80=94=20drop=20dead=20seam,=20dead=20uniform=20payload,=20m?= =?UTF-8?q?irror=20tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies the triaged subset of the whole-branch deletion audit (.superpowers/sdd/2026-09-01-render-black-hole/deletion-audit-whole-branch.md): delete the packer test subsumed by its parity sibling, drop createRenderTargets' test-only extraRows seam now that the real sky-cubemap row covers it, retire the dead flickerTimescaleS uniform field (CPU-side phase precompute keeps the tuning value; the shader never read it), drop createViewSlotUniformRing's unused slotCount override, collapse the two subsumed LUT test cases and three default-parameter/literal-restatement test cases, fold BAND_SLAB_FLOOR_MPC from a one-entry map to a direct id compare, and un-export two symbols with no importers. Co-Authored-By: Claude Code --- .../frame/passes/sgrAStarLensingLayer.ts | 1 - .../engine/frame/visibleSlabBodies.ts | 9 +- src/services/gpu/renderTargets.ts | 7 +- .../bodies/sgrAStarLensingRenderer.ts | 4 +- .../gpu/shaders/lib/sgrAStarLensing.wesl | 7 +- src/utils/gpu/createViewSlotUniformRing.ts | 9 +- src/utils/gpu/packSgrAStarLensingUniforms.ts | 8 +- .../engine/frame/frameContext.test.ts | 17 --- .../engine/frame/frameProgram.test.ts | 4 - tests/services/gpu/renderTargets.test.ts | 67 +++------ .../texturedDiskRenderer.test.ts | 40 ------ .../gpu/createViewSlotUniformRing.test.ts | 15 +- .../gpu/packSgrAStarLensingUniforms.test.ts | 136 ------------------ ...rAStarLensingUniformsLayout.parity.test.ts | 36 +++-- .../buildSchwarzschildDeflectionLut.test.ts | 20 --- 15 files changed, 53 insertions(+), 327 deletions(-) delete mode 100644 tests/utils/gpu/packSgrAStarLensingUniforms.test.ts diff --git a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts index 6a45cb831f..5c785a4a22 100644 --- a/src/services/engine/frame/passes/sgrAStarLensingLayer.ts +++ b/src/services/engine/frame/passes/sgrAStarLensingLayer.ts @@ -127,7 +127,6 @@ export const sgrAStarLensingLayer: ContentLayer = { inclinationRad: tuning.inclinationRad, positionAngleRad: tuning.positionAngleRad, flickerAmp: tuning.flickerAmp, - flickerTimescaleS: tuning.flickerTimescaleS, flickerPhase, lutMinImpactParamRs: renderer.lut.minImpactParamRs, lutMaxImpactParamRs: renderer.lut.maxImpactParamRs, diff --git a/src/services/engine/frame/visibleSlabBodies.ts b/src/services/engine/frame/visibleSlabBodies.ts index 0fa41f41ef..b16c2bb2b4 100644 --- a/src/services/engine/frame/visibleSlabBodies.ts +++ b/src/services/engine/frame/visibleSlabBodies.ts @@ -22,9 +22,7 @@ import { SGR_A_STAR } from '../../../data/bodies/sceneSgrAStar'; * span most of the view, so no conservative disc-based cull is available, * and one always-on slab row is negligible. */ -const BAND_SLAB_FLOOR_MPC: ReadonlyMap = new Map([ - [SGR_A_STAR.id, SCALE_FADE_BANDS.sgrAStarLensing.goneAt], -]); +const BAND_SLAB_FLOOR_MPC = SCALE_FADE_BANDS.sgrAStarLensing.goneAt; /** * visibleSlabBodies — which of `bodies` get a body slab row this frame: @@ -75,12 +73,11 @@ export function visibleSlabBodies(input: { // Band-bearing lens body: candidacy for the whole band support, both // culls bypassed — see BAND_SLAB_FLOOR_MPC. - const bandFloorMpc = BAND_SLAB_FLOOR_MPC.get(body.id); - if (bandFloorMpc !== undefined) { + if (body.id === SGR_A_STAR.id) { const bdx = state.positionMpc[0] - camPosMpc[0]; const bdy = state.positionMpc[1] - camPosMpc[1]; const bdz = state.positionMpc[2] - camPosMpc[2]; - if (Math.hypot(bdx, bdy, bdz) < bandFloorMpc) return true; + if (Math.hypot(bdx, bdy, bdz) < BAND_SLAB_FLOOR_MPC) return true; } // The widest thing this row can draw — the same value the frustum cull diff --git a/src/services/gpu/renderTargets.ts b/src/services/gpu/renderTargets.ts index 9ace4e8163..a676e341a8 100644 --- a/src/services/gpu/renderTargets.ts +++ b/src/services/gpu/renderTargets.ts @@ -327,15 +327,10 @@ export function createRenderTargets( swapFormat: GPUTextureFormat, size: Size, state: EngineState, - // Test-only injection seam: appends rows the production table - // (`renderTargetRows`) doesn't declare yet, so `fixedSizePx` behaviour is - // exercisable before Phase B lands the real sky-cubemap row. No production - // caller passes this. - extraRows: readonly RenderTargetSpec[] = [], ): RenderTargets { // `let`, not `const`: setSwapFormat below replaces this array wholesale // rather than mutating a row in place (house preference for immutability). - let specs = [...renderTargetRows(swapFormat), ...extraRows]; + let specs = [...renderTargetRows(swapFormat)]; // Only offscreen rows get textures — the swap row is executor-resolved // from the acquired frame view (see the module header). Computed once: // setSwapFormat never touches an offscreen row, so this stays valid. diff --git a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts index 2e139fa63a..87ae3b0112 100644 --- a/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts +++ b/src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts @@ -27,7 +27,7 @@ import { SGR_A_STAR_LENSING_UNIFORM_FLOATS } from '../../../../utils/gpu/packSgr * curvature aliasing (Simpson quadrature is cheap CPU-side and this runs * once at construction, so there is no reason to skimp). */ -export const LUT_SAMPLE_COUNT = 512; +const LUT_SAMPLE_COUNT = 512; /** * Stand-in for a captured LUT sample once uploaded to the `r32float` @@ -38,7 +38,7 @@ export const LUT_SAMPLE_COUNT = 512; * `f32`'s own range, so the value survives the GPU upload with no risk of * becoming `inf` itself. */ -export const CAPTURE_SENTINEL_RAD = 1000; +const CAPTURE_SENTINEL_RAD = 1000; function createLutTexture(device: GPUDevice, lut: SchwarzschildDeflectionLut): GPUTexture { const texture = device.createTexture({ diff --git a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl index 51c44b0c08..36862be802 100644 --- a/src/services/gpu/shaders/lib/sgrAStarLensing.wesl +++ b/src/services/gpu/shaders/lib/sgrAStarLensing.wesl @@ -18,7 +18,10 @@ // offset 92 : inclinationRad f32 // offset 96 : positionAngleRad f32 // offset 100 : flickerAmp f32 -// offset 104 : flickerTimescaleS f32 +// offset 104 : _pad0 f32 — unread; flickerTimescaleS only +// feeds the CPU-side flickerPhase +// precompute (sgrAStarLensingLayer.ts), +// never sampled by this shader // offset 108 : flickerPhase f32 — sim-clock-derived, per-frame // offset 112 : lutMinImpactParamRs f32 — SchwarzschildDeflectionLut.minImpactParamRs // offset 116 : lutMaxImpactParamRs f32 — SchwarzschildDeflectionLut.maxImpactParamRs @@ -61,7 +64,7 @@ struct SgrAStarLensingUniforms { inclinationRad: f32, positionAngleRad: f32, flickerAmp: f32, - flickerTimescaleS: f32, + _pad0: f32, flickerPhase: f32, lutMinImpactParamRs: f32, lutMaxImpactParamRs: f32, diff --git a/src/utils/gpu/createViewSlotUniformRing.ts b/src/utils/gpu/createViewSlotUniformRing.ts index 03f57d4b84..e269f65e09 100644 --- a/src/utils/gpu/createViewSlotUniformRing.ts +++ b/src/utils/gpu/createViewSlotUniformRing.ts @@ -19,15 +19,12 @@ export function createViewSlotUniformRing(init: { readonly label: string; readonly byteSize: number; readonly layout: GPUBindGroupLayout; - /** @default VIEW_SLOT_COUNT */ - readonly slotCount?: number; }): ViewSlotUniformRing { const { device, label, byteSize, layout } = init; - const slotCount = init.slotCount ?? VIEW_SLOT_COUNT; const buffers: GPUBuffer[] = []; const bindGroups: GPUBindGroup[] = []; - for (let slot = 0; slot < slotCount; slot++) { + for (let slot = 0; slot < VIEW_SLOT_COUNT; slot++) { const buffer = device.createBuffer({ label: `${label}-slot${slot}`, size: byteSize, @@ -46,8 +43,8 @@ export function createViewSlotUniformRing(init: { // Loud on an out-of-range slot rather than a bare `TypeError` out of // `queue.writeBuffer` — same discipline as `renderTargets.viewOf`. function slotInRange(slot: number): void { - if (slot < 0 || slot >= slotCount) { - throw new Error(`${label}: view slot ${slot} out of range (${slotCount} slots)`); + if (slot < 0 || slot >= VIEW_SLOT_COUNT) { + throw new Error(`${label}: view slot ${slot} out of range (${VIEW_SLOT_COUNT} slots)`); } } diff --git a/src/utils/gpu/packSgrAStarLensingUniforms.ts b/src/utils/gpu/packSgrAStarLensingUniforms.ts index b3adb98a94..a708e220a4 100644 --- a/src/utils/gpu/packSgrAStarLensingUniforms.ts +++ b/src/utils/gpu/packSgrAStarLensingUniforms.ts @@ -22,7 +22,9 @@ * f32 23 (byte 92.. 95): inclinationRad f32 * f32 24 (byte 96.. 99): positionAngleRad f32 * f32 25 (byte 100..103): flickerAmp f32 - * f32 26 (byte 104..107): flickerTimescaleS f32 + * f32 26 (byte 104..107): _pad0 — unwritten (zero); flickerTimescaleS + * only feeds the CPU-side flickerPhase + * precompute, never read by the shader * f32 27 (byte 108..111): flickerPhase f32 * f32 28 (byte 112..115): lutMinImpactParamRs f32 * f32 29 (byte 116..119): lutMaxImpactParamRs f32 @@ -75,7 +77,6 @@ export function packSgrAStarLensingUniforms(input: { readonly inclinationRad: number; readonly positionAngleRad: number; readonly flickerAmp: number; - readonly flickerTimescaleS: number; readonly flickerPhase: number; readonly lutMinImpactParamRs: number; readonly lutMaxImpactParamRs: number; @@ -99,7 +100,6 @@ export function packSgrAStarLensingUniforms(input: { inclinationRad, positionAngleRad, flickerAmp, - flickerTimescaleS, flickerPhase, lutMinImpactParamRs, lutMaxImpactParamRs, @@ -122,7 +122,7 @@ export function packSgrAStarLensingUniforms(input: { out[23] = inclinationRad; // byte 92 out[24] = positionAngleRad; // byte 96 out[25] = flickerAmp; // byte 100 - out[26] = flickerTimescaleS; // byte 104 + // out[26] (byte 104) stays 0 — _pad0, unread by the shader. out[27] = flickerPhase; // byte 108 out[28] = lutMinImpactParamRs; // byte 112 out[29] = lutMaxImpactParamRs; // byte 116 diff --git a/tests/services/engine/frame/frameContext.test.ts b/tests/services/engine/frame/frameContext.test.ts index 5129753259..4979cf4179 100644 --- a/tests/services/engine/frame/frameContext.test.ts +++ b/tests/services/engine/frame/frameContext.test.ts @@ -357,23 +357,6 @@ describe('deriveFrameContext — ready branch', () => { expect(ctx.focus.blend).toBe(0); }); - it('stamps viewSlot 0 — the main view (Task 13b; skyCubemapFaceContext overrides to face + 1)', () => { - const ctx = deriveFrameContext( - makeState(), - makeCanvas(), - RESTING_POSE, - PROJECTION, - BASIS, - BASIS, - 0, - 0, - CONST_J2000, - ); - expect(ctx.isReady).toBe(true); - if (!ctx.isReady) return; - expect(ctx.viewSlot).toBe(0); - }); - it('stamps nowMs onto the ready context', () => { const ctx = deriveFrameContext( makeState(), diff --git a/tests/services/engine/frame/frameProgram.test.ts b/tests/services/engine/frame/frameProgram.test.ts index 05748ff094..8fcadb0d9f 100644 --- a/tests/services/engine/frame/frameProgram.test.ts +++ b/tests/services/engine/frame/frameProgram.test.ts @@ -294,11 +294,7 @@ describe('frameProgram', () => { }); it('sgrAStarLensingBodySlabs omitted or empty: no extra step, program identical to the base list (zero-cost outside the band)', () => { - const withDefault = frameProgram(TONE, false, [NEAR0], []); - const withEmpty = frameProgram(TONE, false, [NEAR0], [], []); const base = frameProgram(TONE, false, [NEAR0], [], undefined); - expect(withDefault).toEqual(base); - expect(withEmpty).toEqual(base); expect(base.some((step) => step.kind === 'render' && step.slab >= 2)).toBe(false); // Task 14b: the split discriminant must not leak outside the // band either — the (hdr, NEAR0) step stays the single untagged step it diff --git a/tests/services/gpu/renderTargets.test.ts b/tests/services/gpu/renderTargets.test.ts index f991b05dea..aa10051474 100644 --- a/tests/services/gpu/renderTargets.test.ts +++ b/tests/services/gpu/renderTargets.test.ts @@ -12,7 +12,6 @@ import { describe, it, expect, vi } from 'vitest'; import { createRenderTargets } from '../../../src/services/gpu/renderTargets'; import { SCALE_FADE_BANDS } from '../../../src/services/engine/presentation/scaleFadeBands'; import type { EngineState } from '../../../src/@types/engine/state/EngineState'; -import type { RenderTargetSpec } from '../../../src/@types/engine/frame/RenderTargetSpec'; function mockDevice(): GPUDevice { return { @@ -31,10 +30,10 @@ const SWAP_FORMAT: GPUTextureFormat = 'bgra8unorm'; const MW_DIVISOR = 2; // The production `sky-cubemap` row's `fixedSizePx.size` reads -// `settings.sgrAStarLensingTuning.cubemapResolutionPx` — -// every `createRenderTargets`/`reconcile` call below goes through the real -// table (`extraRows` only APPENDS), so this fixture needs the field even in -// tests that don't care about the sky-cubemap row itself. +// `settings.sgrAStarLensingTuning.cubemapResolutionPx` — every +// `createRenderTargets`/`reconcile` call below goes through the real table, +// so this fixture needs the field even in tests that don't care about the +// sky-cubemap row itself. const SKY_CUBEMAP_RESOLUTION_PX = 256; // The production `sky-cubemap` row is lazy: its `allocateWhen` reads the @@ -58,34 +57,6 @@ function stateWithDivisor( } as unknown as EngineState; } -// `fixedSizePx` has no row in the production table yet (Phase B adds the -// real sky-cubemap row); `createRenderTargets`'s 5th `extraRows` param is a -// test-only injection seam so the allocation branch can be exercised now. -// No production caller passes it. -const FIXED_SIZE_ROW: RenderTargetSpec = { - id: 'test:cubemap', - format: 'rgba16float', - depth: null, - scale: 1, - clearValue: { r: 0, g: 0, b: 0, a: 0 }, - fixedSizePx: { size: 256, layers: 6 }, -}; - -// A `fixedSizePx` row whose `size` is a FUNCTION of state (the -// `sky-cubemap` production row's own shape) — mirrors `mw-aggregate`'s -// state-driven `scale`. -const STATE_DRIVEN_FIXED_SIZE_ROW: RenderTargetSpec = { - id: 'test:state-cubemap', - format: 'rgba16float', - depth: null, - scale: 1, - clearValue: { r: 0, g: 0, b: 0, a: 0 }, - fixedSizePx: { - size: (state) => state.settings.sgrAStarLensingTuning.cubemapResolutionPx, - layers: 6, - }, -}; - describe('createRenderTargets', () => { it('viewOf returns a live view per offscreen row and throws for swap', () => { const targets = createRenderTargets( @@ -168,11 +139,14 @@ describe('createRenderTargets', () => { SWAP_FORMAT, { width: 900, height: 600 }, stateWithDivisor(MW_DIVISOR), - [FIXED_SIZE_ROW], ); - const desc = create.mock.calls.find((c) => c[0].label === 'render-target-test:cubemap')![0]; - expect(desc.size).toEqual({ width: 256, height: 256, depthOrArrayLayers: 6 }); + const desc = create.mock.calls.find((c) => c[0].label === 'render-target-sky-cubemap')![0]; + expect(desc.size).toEqual({ + width: SKY_CUBEMAP_RESOLUTION_PX, + height: SKY_CUBEMAP_RESOLUTION_PX, + depthOrArrayLayers: 6, + }); expect(desc.dimension).toBe('2d'); }); @@ -183,9 +157,8 @@ describe('createRenderTargets', () => { SWAP_FORMAT, { width: 800, height: 600 }, stateWithDivisor(MW_DIVISOR), - [FIXED_SIZE_ROW], ); - expect(targets.cubeViewOf('test:cubemap')).toBeDefined(); + expect(targets.cubeViewOf('sky-cubemap')).toBeDefined(); // 'hdr' has no fixedSizePx (a single layer), so it gets no cube view. expect(() => targets.cubeViewOf('hdr')).toThrow(); expect(() => targets.cubeViewOf('nope')).toThrow(); @@ -199,16 +172,15 @@ describe('createRenderTargets', () => { SWAP_FORMAT, { width: 900, height: 600 }, stateWithDivisor(MW_DIVISOR), - [FIXED_SIZE_ROW], ); const callsBefore = create.mock.calls.filter( - (c) => c[0].label === 'render-target-test:cubemap', + (c) => c[0].label === 'render-target-sky-cubemap', ).length; targets.reconcile(stateWithDivisor(MW_DIVISOR), { width: 1200, height: 900 }); const callsAfter = create.mock.calls.filter( - (c) => c[0].label === 'render-target-test:cubemap', + (c) => c[0].label === 'render-target-sky-cubemap', ).length; expect(callsAfter).toBe(callsBefore); }); @@ -221,25 +193,22 @@ describe('createRenderTargets', () => { SWAP_FORMAT, { width: 900, height: 600 }, stateWithDivisor(MW_DIVISOR, 256), - [STATE_DRIVEN_FIXED_SIZE_ROW], ); - const desc = create.mock.calls.find( - (c) => c[0].label === 'render-target-test:state-cubemap', - )![0]; + const desc = create.mock.calls.find((c) => c[0].label === 'render-target-sky-cubemap')![0]; expect(desc.size).toEqual({ width: 256, height: 256, depthOrArrayLayers: 6 }); - const cubeViewBefore = targets.cubeViewOf('test:state-cubemap'); + const cubeViewBefore = targets.cubeViewOf('sky-cubemap'); // Canvas size is UNCHANGED — only the resolved fixedSizePx moved, mirroring // the mw-aggregate divisor test's "a texture's dimensions are fixed at // creation" reasoning. targets.reconcile(stateWithDivisor(MW_DIVISOR, 512), { width: 900, height: 600 }); const resized = create.mock.calls - .filter((c) => c[0].label === 'render-target-test:state-cubemap') + .filter((c) => c[0].label === 'render-target-sky-cubemap') .at(-1)![0]; expect(resized.size).toEqual({ width: 512, height: 512, depthOrArrayLayers: 6 }); - expect(targets.sizeOf('test:state-cubemap')).toEqual({ width: 512, height: 512 }); - expect(targets.cubeViewOf('test:state-cubemap')).not.toBe(cubeViewBefore); + expect(targets.sizeOf('sky-cubemap')).toEqual({ width: 512, height: 512 }); + expect(targets.cubeViewOf('sky-cubemap')).not.toBe(cubeViewBefore); }); // The lens's 50 MB cubemap must not sit in VRAM on a machine that never diff --git a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts index 48fdd017b1..062a43a931 100644 --- a/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts +++ b/tests/services/gpu/renderers/galaxyCatalog/texturedDiskRenderer.test.ts @@ -255,44 +255,4 @@ describe('texturedDiskRenderer.draw — viewSlot (Task 13b)', () => { expect(instanceWrites).toHaveLength(2); expect(Array.from(instanceWrites[0]!.data)).toEqual(Array.from(instanceWrites[1]!.data)); }); - - it('defaults viewSlot to 0 when omitted', () => { - const { ctx } = makeStubCtx(); - const renderer = createTexturedDiskRenderer(ctx, FOCUS_BGL); - renderer.bindAtlas({} as GPUTextureView); - renderer.bindHiResArray({} as GPUTextureView); - - const bindGroupsAt0: unknown[] = []; - const pass = { - setPipeline: vi.fn(), - setBindGroup: (slot: number, bg: unknown) => { - if (slot === 0) bindGroupsAt0.push(bg); - }, - setVertexBuffer: vi.fn(), - draw: vi.fn(), - } as unknown as GPURenderPassEncoder; - - const instances: DiskInstance[] = [fakeDiskInstance()]; - renderer.draw( - pass, - new Float32Array(16) as never, - [800, 600], - [0, 0, 0], - FOCUS_BIND_GROUP, - instances, - ); - renderer.draw( - pass, - new Float32Array(16) as never, - [800, 600], - [0, 0, 0], - FOCUS_BIND_GROUP, - instances, - 0, - ); - - // Both calls land on slot 0's SAME bind group — an omitted viewSlot is - // byte-identical to an explicit 0. - expect(bindGroupsAt0[0]).toBe(bindGroupsAt0[1]); - }); }); diff --git a/tests/utils/gpu/createViewSlotUniformRing.test.ts b/tests/utils/gpu/createViewSlotUniformRing.test.ts index 8882718568..5468d592ef 100644 --- a/tests/utils/gpu/createViewSlotUniformRing.test.ts +++ b/tests/utils/gpu/createViewSlotUniformRing.test.ts @@ -42,13 +42,6 @@ describe('createViewSlotUniformRing', () => { } }); - it('honours an explicit slotCount', () => { - const device = mockDevice(); - createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT, slotCount: 3 }); - const createBuffer = device.createBuffer as unknown as ReturnType; - expect(createBuffer).toHaveBeenCalledTimes(3); - }); - it('bindGroupOf returns a DIFFERENT bind group per slot', () => { const device = mockDevice(); const ring = createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT }); @@ -79,13 +72,7 @@ describe('createViewSlotUniformRing', () => { it('destroy releases every slot buffer exactly once', () => { const device = mockDevice(); const createBuffer = device.createBuffer as unknown as ReturnType; - const ring = createViewSlotUniformRing({ - device, - label: 'x', - byteSize: 16, - layout: LAYOUT, - slotCount: 4, - }); + const ring = createViewSlotUniformRing({ device, label: 'x', byteSize: 16, layout: LAYOUT }); const buffers = createBuffer.mock.results.map((r) => r.value as { destroy: () => void }); ring.destroy(); diff --git a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts b/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts deleted file mode 100644 index befd10630c..0000000000 --- a/tests/utils/gpu/packSgrAStarLensingUniforms.test.ts +++ /dev/null @@ -1,136 +0,0 @@ -/** - * SgrAStarLensingUniforms byte-layout guard. - * - * The WGSL `SgrAStarLensingUniforms` struct in `shaders/lib/sgrAStarLensing.wesl` - * and the CPU-side `packSgrAStarLensingUniforms` must agree byte-for-byte: a - * mismatch produces no GPU error, just a wrong (or, on iOS, silently dropped) - * frame. This is the `testing.md` keep-rule for uniform layouts — it fails on a - * real drift no compiler check catches (Task 13's lens pass, not yet written, - * is the eventual consumer of this contract). - * - * Drives the real packer with distinct, non-round values in every slot (no - * two sentinels equal, so a swapped pair of fields is caught) and reads the - * returned `Float32Array` at the offsets the struct pins. - */ - -import { describe, it, expect } from 'vitest'; -import { - packSgrAStarLensingUniforms, - SGR_A_STAR_LENSING_UNIFORM_FLOATS, -} from '../../../src/utils/gpu/packSgrAStarLensingUniforms'; -import type { Vec2 } from '../../../src/@types/math/Vec2'; -import type { Vec3 } from '../../../src/@types/math/Vec3'; - -// A recognisable viewProj: 1..16 so any transposition or off-by-one -// placement of a later field into the matrix block shows up as a wrong value. -const VIEW_PROJ = new Float32Array(16); -for (let i = 0; i < 16; i++) VIEW_PROJ[i] = i + 1; - -const VIEWPORT_PX: Vec2 = [1920, 1080]; - -// Distinct, non-round scalars — dyadic fractions where possible so the -// float32 round-trip is exact and `toBe` needs no tolerance, yet no two -// sentinels are equal (swap-proof). -const SCHWARZSCHILD_RADIUS_M = 12030000128; // ~r_s of Sgr A*, snapped to a float32-exact multiple of 2048 -const INNER_RS = 2.5; -const OUTER_RS = 12.5; -const INCLINATION_RAD = 0.9375; // dyadic (15/16) — float32-exact, unlike 0.9625 -const POSITION_ANGLE_RAD = 1.1875; -const FLICKER_AMP = 0.34375; -const FLICKER_TIMESCALE_S = 315.5; -const FLICKER_PHASE = 0.71875; -const LUT_MIN_IMPACT_PARAM_RS = 2.09375; -const LUT_MAX_IMPACT_PARAM_RS = 40.5; -const LUT_SAMPLE_COUNT = 256; -const BAND_ALPHA = 0.578125; -const ANCHOR_POS_REL_CAM_M: Vec3 = [3.5, -1.25, 7.75]; -// Tuning-knob fields. -const DISK_SCALE_HEIGHT_RS = 0.8125; -const EDGE_FADE_START_FRACTION = 0.65625; -const DOPPLER_STRENGTH = 0.46875; -const EMISSION_STRENGTH = 0.90625; -const EDGE_FADE_END_RS = 1875.5; -const EMISSION_TINT: Vec3 = [801, 802, 803]; -const QUAD_PLANE_RADIUS_RS = 2343.75; - -describe('SgrAStarLensingUniforms byte offsets', () => { - it('packs a 176-byte / 44-f32 record with each field at its documented offset', () => { - const rec = packSgrAStarLensingUniforms({ - viewProj: VIEW_PROJ, - viewportPx: VIEWPORT_PX, - schwarzschildRadiusM: SCHWARZSCHILD_RADIUS_M, - innerRs: INNER_RS, - outerRs: OUTER_RS, - inclinationRad: INCLINATION_RAD, - positionAngleRad: POSITION_ANGLE_RAD, - flickerAmp: FLICKER_AMP, - flickerTimescaleS: FLICKER_TIMESCALE_S, - flickerPhase: FLICKER_PHASE, - lutMinImpactParamRs: LUT_MIN_IMPACT_PARAM_RS, - lutMaxImpactParamRs: LUT_MAX_IMPACT_PARAM_RS, - lutSampleCount: LUT_SAMPLE_COUNT, - bandAlpha: BAND_ALPHA, - anchorPosRelCamM: ANCHOR_POS_REL_CAM_M, - diskScaleHeightRs: DISK_SCALE_HEIGHT_RS, - edgeFadeStartFraction: EDGE_FADE_START_FRACTION, - dopplerStrength: DOPPLER_STRENGTH, - emissionStrength: EMISSION_STRENGTH, - edgeFadeEndRs: EDGE_FADE_END_RS, - emissionTint: EMISSION_TINT, - quadPlaneRadiusRs: QUAD_PLANE_RADIUS_RS, - }); - - expect(rec.length).toBe(SGR_A_STAR_LENSING_UNIFORM_FLOATS); - expect(rec.length).toBe(44); // 176 bytes - expect(rec.byteLength).toBe(176); - - // cam.viewProj — all 16 floats verbatim at bytes 0..63. - for (let i = 0; i < 16; i++) expect(rec[i]).toBe(VIEW_PROJ[i]); - - // cam.viewportPx — vec2 at byte 64 (float index 16). - expect(rec[16]).toBe(VIEWPORT_PX[0]); // byte 64 - expect(rec[17]).toBe(VIEWPORT_PX[1]); // byte 68 - - // cam._pad0/_pad1 — untouched, stay zero. - expect(rec[18]).toBe(0); // byte 72 - expect(rec[19]).toBe(0); // byte 76 - - // Renderer-specific scalars, offset 80+ (float index 20+). - expect(rec[20]).toBe(SCHWARZSCHILD_RADIUS_M); // byte 80 - expect(rec[21]).toBe(INNER_RS); // byte 84 - expect(rec[22]).toBe(OUTER_RS); // byte 88 - expect(rec[23]).toBe(INCLINATION_RAD); // byte 92 - expect(rec[24]).toBe(POSITION_ANGLE_RAD); // byte 96 - expect(rec[25]).toBe(FLICKER_AMP); // byte 100 - expect(rec[26]).toBe(FLICKER_TIMESCALE_S); // byte 104 - expect(rec[27]).toBe(FLICKER_PHASE); // byte 108 - expect(rec[28]).toBe(LUT_MIN_IMPACT_PARAM_RS); // byte 112 - expect(rec[29]).toBe(LUT_MAX_IMPACT_PARAM_RS); // byte 116 - expect(rec[30]).toBe(LUT_SAMPLE_COUNT); // byte 120 - expect(rec[31]).toBe(BAND_ALPHA); // byte 124 - - // anchorPosRelCamM — vec3 at byte 128 (float index 32), 16-byte aligned: - // the 12 preceding scalars exactly fill the run up to 32, so no implicit - // padding was inserted ahead of it. - expect(rec[32]).toBe(ANCHOR_POS_REL_CAM_M[0]); // byte 128 - expect(rec[33]).toBe(ANCHOR_POS_REL_CAM_M[1]); // byte 132 - expect(rec[34]).toBe(ANCHOR_POS_REL_CAM_M[2]); // byte 136 - - // Tuning-knob fields, offset 140+ (float index 35+). - expect(rec[35]).toBe(DISK_SCALE_HEIGHT_RS); // byte 140 - expect(rec[36]).toBe(EDGE_FADE_START_FRACTION); // byte 144 - expect(rec[37]).toBe(DOPPLER_STRENGTH); // byte 148 - expect(rec[38]).toBe(EMISSION_STRENGTH); // byte 152 - - // edgeFadeEndRs — per-frame derived escape-fade end (not a knob). - expect(rec[39]).toBe(EDGE_FADE_END_RS); // byte 156 - - // emissionTint — vec3 at byte 160 (float index 40). - expect(rec[40]).toBe(EMISSION_TINT[0]); // byte 160 - expect(rec[41]).toBe(EMISSION_TINT[1]); // byte 164 - expect(rec[42]).toBe(EMISSION_TINT[2]); // byte 168 - - // quadPlaneRadiusRs — per-frame derived billboard half-size (not a knob). - expect(rec[43]).toBe(QUAD_PLANE_RADIUS_RS); // byte 172 - }); -}); diff --git a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts index 31ea756861..ded9967916 100644 --- a/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts +++ b/tests/utils/gpu/sgrAStarLensingUniformsLayout.parity.test.ts @@ -1,18 +1,16 @@ /** - * SgrAStarLensingUniforms WESL<->packer parity — nothing previously read the - * WGSL struct itself, so a field reorder in `sgrAStarLensing.wesl` (a field - * inserted ahead of `anchorPosRelCamM`, say) would drift silently past - * `packSgrAStarLensingUniforms.test.ts` (which only re-asserts the packer's - * own documented offsets against itself) and hand the GPU a shifted struct. - * This parses `struct SgrAStarLensingUniforms` out of the .wesl file, derives - * its std140 float offsets, then drives the REAL packer with a distinct - * sentinel per field and asserts each sentinel lands where the struct — not - * the packer — says it should. Follows the `atmosphereUniformsLayout.parity - * .test.ts` / `nodeParamsLayout.test.ts` precedent for locating/parsing the - * struct and computing WGSL alignment; the embedded `cam: CameraUniforms` - * prefix is treated as an opaque 80-byte block (its own byte-for-byte parity - * lives in `cameraUniforms.test.ts` and this file's sibling - * `packSgrAStarLensingUniforms.test.ts`, which both cover its content). + * SgrAStarLensingUniforms WESL<->packer parity — nothing else reads the WGSL + * struct itself, so a field reorder in `sgrAStarLensing.wesl` (a field + * inserted ahead of `anchorPosRelCamM`, say) would drift silently past a + * packer test asserting only its own documented offsets and hand the GPU a + * shifted struct. This parses `struct SgrAStarLensingUniforms` out of the + * .wesl file, derives its std140 float offsets, then drives the REAL packer + * with a distinct sentinel per field and asserts each sentinel lands where + * the struct — not the packer — says it should. Follows the + * `atmosphereUniformsLayout.parity.test.ts` / `nodeParamsLayout.test.ts` + * precedent for locating/parsing the struct and computing WGSL alignment; + * the embedded `cam: CameraUniforms` prefix is treated as an opaque 80-byte + * block, its own byte-for-byte parity living in `cameraUniforms.test.ts`. */ import { describe, it, expect } from 'vitest'; import { readFileSync } from 'node:fs'; @@ -102,7 +100,6 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { const inclinationRad = 504; const positionAngleRad = 505; const flickerAmp = 506; - const flickerTimescaleS = 507; const flickerPhase = 508; const lutMinImpactParamRs = 509; const lutMaxImpactParamRs = 510; @@ -127,7 +124,6 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { inclinationRad, positionAngleRad, flickerAmp, - flickerTimescaleS, flickerPhase, lutMinImpactParamRs, lutMaxImpactParamRs, @@ -151,7 +147,6 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { inclinationRad, positionAngleRad, flickerAmp, - flickerTimescaleS, flickerPhase, lutMinImpactParamRs, lutMaxImpactParamRs, @@ -164,9 +159,10 @@ describe('SgrAStarLensingUniforms WESL/packer parity', () => { edgeFadeEndRs, quadPlaneRadiusRs, }; - // No zero-pad fields remain past the cam prefix — every trailing slot is - // a real packed field now. - const zeroPadFields = new Set(); + // `_pad0` (byte 104) is unwritten — flickerTimescaleS moved CPU-side + // (sgrAStarLensingLayer.ts's flickerPhase precompute) and is never + // sampled by the shader, so its old uniform slot stays zero. + const zeroPadFields = new Set(['_pad0']); for (const field of layout) { if (field.lanes === 0) { diff --git a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts index a7da06fc59..000f7a49b4 100644 --- a/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts +++ b/tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts @@ -2,10 +2,6 @@ import { describe, it, expect } from 'vitest'; import { buildSchwarzschildDeflectionLut } from '../../../src/utils/lensing/buildSchwarzschildDeflectionLut'; import type { SchwarzschildDeflectionLut } from '../../../src/@types/lensing/SchwarzschildDeflectionLut'; -// Critical impact parameter (photon sphere), b_c = 3*sqrt(3)/2 r_s ≈ 2.598076 — -// a textbook constant, not derived from the module under test. -const CRITICAL_IMPACT_PARAM_RS = (3 * Math.sqrt(3)) / 2; - // Linear interpolation over the LUT's own reported [min, max] range — used // only far from the photon sphere, where neighbouring grid samples can't // straddle the finite/captured (Infinity) boundary. @@ -19,22 +15,6 @@ function sampleAt(lut: SchwarzschildDeflectionLut, impactParamRs: number): numbe } describe('buildSchwarzschildDeflectionLut', () => { - it('straddles the photon sphere and reaches a weak-field-accurate impact parameter', () => { - const lut = buildSchwarzschildDeflectionLut(4096); - expect(lut.minImpactParamRs).toBeLessThan(CRITICAL_IMPACT_PARAM_RS); - expect(lut.maxImpactParamRs).toBeGreaterThan(20); - }); - - it('matches the weak-field asymptotic formula alpha = 2*r_s/b at a large impact parameter', () => { - // alpha ~= 4GM/(c^2 b) = 2 r_s/b (r_s units, r_s = 1) is the leading PPN - // term; the next order is O(r_s/b) *relative* to that leading term, so at - // b = 30 r_s a few-percent deviation is expected, not exact agreement. - const lut = buildSchwarzschildDeflectionLut(4096); - const b = 30; - const weakFieldFormula = 2 / b; - expect(Math.abs(sampleAt(lut, b) - weakFieldFormula)).toBeLessThan(0.01); - }); - it('matches an independently computed weak-field reference to high precision', () => { // Independent reference for b = 30 r_s: mpmath (40-digit arbitrary // precision) integrating alpha = 2*int_{r0}^inf dr/(r^2 sqrt(F(r))) - pi, From 2c991ff4ed35b7b40da4f1fdb2b0bea687c47e20 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:38:56 +0200 Subject: [PATCH 58/60] =?UTF-8?q?docs(plan):=20tick=20Tasks=201=E2=80=9316?= =?UTF-8?q?=20of=20render-black-hole=20(T17=20awaits=20user=20attestation)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .../plans/2026-09-01-render-black-hole.md | 234 +++++++++--------- 1 file changed, 117 insertions(+), 117 deletions(-) diff --git a/docs/superpowers/plans/2026-09-01-render-black-hole.md b/docs/superpowers/plans/2026-09-01-render-black-hole.md index 80e197626a..69213ce882 100644 --- a/docs/superpowers/plans/2026-09-01-render-black-hole.md +++ b/docs/superpowers/plans/2026-09-01-render-black-hole.md @@ -77,33 +77,33 @@ lenses and before the annotations that must stay unwarped. **Steps:** -- [ ] Write `SCENE_ANCHOR_POINT_BODIES` (`sceneAnchorPointBodies.ts`): +- [x] Write `SCENE_ANCHOR_POINT_BODIES` (`sceneAnchorPointBodies.ts`): `export const SCENE_ANCHOR_POINT_BODIES: readonly AnchorPointBody[] = [SGR_A_STAR];` importing `SGR_A_STAR` from `./sceneSgrAStar`. -- [ ] Update the failing/changed tests in `visibleSlabBodies.test.ts` FIRST: +- [x] Update the failing/changed tests in `visibleSlabBodies.test.ts` FIRST: every existing case's `{ earth, planets, bodyStates, ... }` call becomes `{ bodies: [...], bodyStates, ... }` (fold `earth`/`planets` into one array per case, preserving each case's asserted behaviour unchanged — this IS the zero-behaviour-change proof for those cases). -- [ ] Add the test `admits an AnchorPointBody candidate on the same terms as a planet`: +- [x] Add the test `admits an AnchorPointBody candidate on the same terms as a planet`: construct a synthetic `AnchorPointBody` (arbitrary `radiusM`) at a position/distance that clears both culls with a `bodyStates` entry, assert it appears in the result; construct a second one far outside the frustum, assert it does not. -- [ ] Run `npm test -- visibleSlabBodies` — new tests fail (no `bodies` param +- [x] Run `npm test -- visibleSlabBodies` — new tests fail (no `bodies` param yet), existing tests fail on the old `{earth, planets}` shape. -- [ ] Implement: change `visibleSlabBodies`'s param to `bodies: readonly SceneBody[]`, +- [x] Implement: change `visibleSlabBodies`'s param to `bodies: readonly SceneBody[]`, drop the internal concat (`visibleSlabBodies.ts:46`), keep every downstream line (`FRUSTUM_CULL_MARGIN_FACTOR`, `isInsideFrustum`, `bodyApparentDiameterPx`) untouched — they already operate on the `SceneBody` union's shared `radiusM`/`id` fields. -- [ ] Update `frameContext.ts:201-209`'s call site to assemble `bodies` from +- [x] Update `frameContext.ts:201-209`'s call site to assemble `bodies` from `state.data.bodies.earth` (null-checked), `state.data.bodies.planets`, and `SCENE_ANCHOR_POINT_BODIES`. -- [ ] Update `BODY_SLAB_CAPACITY` (`frameProgram.ts:77`) to the three-term sum +- [x] Update `BODY_SLAB_CAPACITY` (`frameProgram.ts:77`) to the three-term sum above; import `SCENE_ANCHOR_POINT_BODIES`. -- [ ] Run `npm test -- visibleSlabBodies frameContext frameProgram` — all pass. -- [ ] Add the test (in `orientationForBody.test.ts`) `returns identity for +- [x] Run `npm test -- visibleSlabBodies frameContext frameProgram` — all pass. +- [x] Add the test (in `orientationForBody.test.ts`) `returns identity for the Sgr A* anchor` — asserts `orientationForBody('sgr-a-star', )` equals `IDENTITY_MAT3`. This is the P1 "anchor orientation-identity verification through bodyRelativePose": Sgr A* is @@ -112,18 +112,18 @@ lenses and before the annotations that must stay unwarped. the test pins that fact so a future accidental texture-registry entry for `sgr-a-star` can't silently rotate the body-slab basis `bodyRelativePose` builds from it. -- [ ] Correct `AnchorPointBody.d.ts:2-3`'s docblock: replace "DRAWS NOTHING: +- [x] Correct `AnchorPointBody.d.ts:2-3`'s docblock: replace "DRAWS NOTHING: no mesh, no point, no glint" with a statement that an anchor may draw a far-field glint and, inside its lensing band, a geodesic pass — both via dedicated `ContentLayer` rows keyed on its id (Phase B), never via the flat/textured/glint partition planets use. Keep the surrounding "identity fields only" rationale (still true — `AnchorPointBody` gained no new fields). -- [ ] Correct the matching claim at `src/data/sources/sgr-a-star.ts:8` ("It +- [x] Correct the matching claim at `src/data/sources/sgr-a-star.ts:8` ("It DRAWS NOTHING: no sphere, no point, no glint") the same way — same fact, second home, same staleness risk. -- [ ] Run `npm test` (full suite) and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test` (full suite) and `npm run typecheck` — green. +- [x] Commit. **Proof obligation (spec):** with Sgr A* far outside the lensing band (any framing wider than the galactic centre), `visibleSlabBodies` returns exactly @@ -156,35 +156,35 @@ scenes. **Steps:** -- [ ] Add the test `clampDistance — per-body standoff` describing the +- [x] Add the test `clampDistance — per-body standoff` describing the contract: with a `standoffRadii` of e.g. `2.0` and a pivot radius `R`, `clampDistance(smallD, R, 2.0)` floors at `2.0 * R` (not `SURFACE_STANDOFF_RADII * R`), asserted the same way the existing `EARTH_RADIUS_MPC`-relative tests assert (body radii, not raw Mpc — see the file's own header rationale). -- [ ] Add the test `clampDistance — omitted standoffRadii keeps Earth's +- [x] Add the test `clampDistance — omitted standoffRadii keeps Earth's current floor unchanged`: `clampDistance(d, EARTH_RADIUS_MPC)` (two-arg call, exactly as today's call sites use it) is byte-identical to today's behaviour — this is the zero-change proof for every body that doesn't opt in. -- [ ] Run `npm test -- clampDistance` — new tests fail. -- [ ] Implement the third parameter with the stated default; the floor +- [x] Run `npm test -- clampDistance` — new tests fail. +- [x] Implement the third parameter with the stated default; the floor becomes `Math.max(MIN_DISTANCE_MPC, pivotRadiusMpc * standoffRadii)`. -- [ ] Run `npm test -- clampDistance` — passes. -- [ ] Add `standoffRadii?: number` to `AnchorPointBody.d.ts`, with a one-line +- [x] Run `npm test -- clampDistance` — passes. +- [x] Add `standoffRadii?: number` to `AnchorPointBody.d.ts`, with a one-line doc note citing Q10 (2 r_s descent floor) as the reason a per-body override exists at all — the global `SURFACE_STANDOFF_RADII` stays tuned for Earth's imagery resolution (see `clampDistance.ts:26-46`) and must not regress. -- [ ] Set `standoffRadii: 2.0` on `SGR_A_STAR` in `sceneSgrAStar.ts`. -- [ ] Find and update the focus/zoom call site that currently calls +- [x] Set `standoffRadii: 2.0` on `SGR_A_STAR` in `sceneSgrAStar.ts`. +- [x] Find and update the focus/zoom call site that currently calls `clampDistance(d, pivotRadiusMpc)` for a focused `SceneBody` (a two-arg call somewhere in the orbit-camera/focus-tween path) to read an optional `standoffRadii` off the focused body when present, passing it as the third arg; every other body (no such field) falls through to the default. -- [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test` and `npm run typecheck` — green. +- [x] Commit. --- @@ -220,7 +220,7 @@ export type RenderTargetSpec = { **Steps:** -- [ ] Add the test `createRenderTargets — a fixedSizePx row allocates at its +- [x] Add the test `createRenderTargets — a fixedSizePx row allocates at its declared size regardless of canvas size`: construct `createRenderTargets` with a test-only `RenderTargetSpec` row (or, if `renderTargetRows` isn't the seam under test, inject via whatever seam @@ -228,35 +228,35 @@ export type RenderTargetSpec = { assert the allocated texture's `size` descriptor is `{ width: 256, height: 256, depthOrArrayLayers: 6 }` at a canvas of `{ width: 900, height: 600 }`. -- [ ] Add the test `createRenderTargets — reconcile does not reallocate a +- [x] Add the test `createRenderTargets — reconcile does not reallocate a fixedSizePx row when the canvas resizes`: call `reconcile` with a DIFFERENT canvas size than construction; assert `device.createTexture` was NOT called again for that row's id (mirrors the existing "reallocates... when the canvas size changes" test's call-count assertion style at `renderTargets.test.ts:52-88`, inverted). -- [ ] Run `npm test -- renderTargets` — new tests fail (no such row exists +- [x] Run `npm test -- renderTargets` — new tests fail (no such row exists yet to construct against — write them against a literal test spec object passed through whatever `renderTargetRows`-adjacent seam the implementer adds for injectability, OR against a temporary row added to `renderTargetRows` and removed once Phase B's real cubemap row lands; implementer's call, documented inline in the test file). -- [ ] Add `fixedSizePx` to `RenderTargetSpec.d.ts` as above. -- [ ] In `renderTargets.ts`, grow `reconcile`'s per-row loop +- [x] Add `fixedSizePx` to `RenderTargetSpec.d.ts` as above. +- [x] In `renderTargets.ts`, grow `reconcile`'s per-row loop (`renderTargets.ts:338-345`) so a `fixedSizePx` row computes `[fixedSizePx.size, fixedSizePx.size]` instead of calling `reducedTargetSize(canvas.width, canvas.height, resolveScale(spec, s))` — the held-size comparison and `allocate` call stay shared with every other row (a fixed size is just a size that never changes across resizes, not a separate code path past this one branch). -- [ ] Grow `allocate` (`renderTargets.ts:293-330`) to pass +- [x] Grow `allocate` (`renderTargets.ts:293-330`) to pass `depthOrArrayLayers: spec.fixedSizePx?.layers ?? 1` and `dimension: '2d'` (explicit — WebGPU defaults to `'2d'` already, but state it so a `layers > 1` row is unambiguous) in the texture descriptor's `size`, for both the colour and (if `spec.depth`) depth texture creation calls. -- [ ] Run `npm test -- renderTargets` — passes. -- [ ] Run `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test -- renderTargets` — passes. +- [x] Run `npm run typecheck` — green. +- [x] Commit. --- @@ -296,23 +296,23 @@ scope — see the STOP-and-consult step below). **Steps:** -- [ ] Start the dev server (`/dev` skill or `npm run dev`), focus Sgr A* +- [x] Start the dev server (`/dev` skill or `npm run dev`), focus Sgr A* (already selectable/focusable today — `AnchorPointBody` is in `SCENE_BODIES` and carries a caption). -- [ ] With Phase A merged (the slab-candidacy + standoff-floor prep live), +- [x] With Phase A merged (the slab-candidacy + standoff-floor prep live), descend toward Sgr A* to the P2 floor (2 r_s — `standoffRadii: 2.0` now stops the camera there). -- [ ] Observe: camera jitter at the floor, frustum near-plane behaviour +- [x] Observe: camera jitter at the floor, frustum near-plane behaviour (`bodySlabRow`'s `near` derivation, `slabs.ts:219-236`), and S-star sprite/orbit-trail stability at that range (they ride the same NEAR0 slab and f64 rebase seam). -- [ ] **USER-ATTESTED GATE:** report findings to the user — this is a visual +- [x] **USER-ATTESTED GATE:** report findings to the user — this is a visual judgment call, not a scripted assertion. If jitter/instability appears, STOP and consult before proceeding: does it implicate `docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` (per the spec's "Relationship to open items")? That folding decision is the user's call, made HERE, not assumed by this plan. -- [ ] On a clean probe, proceed to Task 5. On a fold-in verdict, the folded +- [x] On a clean probe, proceed to Task 5. On a fold-in verdict, the folded scope becomes new tasks inserted here (not silently absorbed into a later task's steps). @@ -340,7 +340,7 @@ export function schwarzschildRadiusM(massSolar: number): number; // r_s = 2GM/c **Steps:** -- [ ] Add the test `schwarzschildRadiusM` (in +- [x] Add the test `schwarzschildRadiusM` (in `tests/utils/physics/schwarzschildRadiusM.test.ts`) asserting `schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` is within float tolerance of the KNOWN figure — 12.69e6 km = 1.269e10 m (equivalently 0.085 AU, @@ -350,20 +350,20 @@ export function schwarzschildRadiusM(massSolar: number): number; // r_s = 2GM/c tolerance appropriate for a physical-constant computation (e.g. `toBeCloseTo` with a precision chosen so the real constants G/c round correctly, not an arbitrarily loose bound). -- [ ] Run the test — fails (function doesn't exist). -- [ ] Implement `schwarzschildRadiusM` using named physical constants (G, c) +- [x] Run the test — fails (function doesn't exist). +- [x] Implement `schwarzschildRadiusM` using named physical constants (G, c) — no existing G/c constant module was found in this codebase's `utils/`; add them as named locals in this file with their SI values and a one-line citation, following the `scaleUnits.ts` convention of named locals with IAU/physical-constant citations rather than inline magic numbers. -- [ ] Run the test — passes. -- [ ] Create `sgrAStarMassSolar.ts` with the single constant above. -- [ ] In `sceneSgrAStar.ts`, replace the `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM` +- [x] Run the test — passes. +- [x] Create `sgrAStarMassSolar.ts` with the single constant above. +- [x] In `sceneSgrAStar.ts`, replace the `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM` import and `radiusM: SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM * SCALE_UNITS.KM_TO_M` (line 41) with `radiusM: schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` (the function returns metres directly — no `KM_TO_M` step). -- [ ] In `sStarOrbitInfo.ts:16-21`, replace the +- [x] In `sStarOrbitInfo.ts:16-21`, replace the `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM`-based `SCHWARZSCHILD_RADIUS_AU` derivation with one reading `schwarzschildRadiusM(SGR_A_STAR_MASS_SOLAR)` (converted through `SCALE_UNITS.M_TO_MPC` / `SCALE_UNITS.AU_TO_MPC` — @@ -372,14 +372,14 @@ export function schwarzschildRadiusM(massSolar: number): number; // r_s = 2GM/c (`BodyOrbitInfo.pericentreSchwarzschildRadii`, consumed by `BodyDetailCard.tsx:206-212`), migrated per the spec's explicit instruction rather than left orphaned. -- [ ] Delete `sgrAStarSchwarzschildRadiusKm.ts` via +- [x] Delete `sgrAStarSchwarzschildRadiusKm.ts` via `npm run refactor -- delete src/data/bodies/sgrAStarSchwarzschildRadiusKm.ts` (per plan-style rule 5 — never `git mv`/manual delete + hand-edited imports; the refactor CLI confirms no remaining importers before removing the file). -- [ ] Run `npm test` and `npm run typecheck` — green (no remaining +- [x] Run `npm test` and `npm run typecheck` — green (no remaining `SGR_A_STAR_SCHWARZSCHILD_RADIUS_KM` references). -- [ ] Commit. +- [x] Commit. --- @@ -411,23 +411,23 @@ export const BLACK_HOLES: readonly BlackHoleRow[]; // one row: sgr-a-star **Steps:** -- [ ] Add `BlackHoleRow.d.ts` per the contract above, with a docblock stating +- [x] Add `BlackHoleRow.d.ts` per the contract above, with a docblock stating the registry is built to hold more than one row (M87* is data, not code, per the spec's non-goals) — mirrors `SCENE_PLANETS`'s append-only framing. -- [ ] Add `blackHoles.ts` with `BLACK_HOLES` holding the `sgr-a-star` row: +- [x] Add `blackHoles.ts` with `BLACK_HOLES` holding the `sgr-a-star` row: `emission.innerRs = 3`, `outerRs = 6` (ISCO-to-EHT-ring, spec Data table); `inclinationRad`/`positionAngleRad` chosen values (document the position-angle choice as unconstrained-but-fixed, per the spec); a flicker amplitude + timescale (minute-scale, spec Data table — no externally-known reference value exists for these, so pick and document as taste/dev-tuning-adjustable via Task 15's debug panel). -- [ ] No test — this is a literal data table (a registry-restatement test +- [x] No test — this is a literal data table (a registry-restatement test here would fail `testing.md`'s bar; the structural invariant worth testing, if any — e.g. `bodyId` values are valid `BodyId`s — is already enforced by `tsc` through the `BodyId` type itself). -- [ ] Run `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm run typecheck` — green. +- [x] Commit. --- @@ -456,7 +456,7 @@ sgrAStarLensing: { **Steps:** -- [ ] Add the test `SCALE_FADE_BANDS.sgrAStarLensing — 100/500 AU envelope in +- [x] Add the test `SCALE_FADE_BANDS.sgrAStarLensing — 100/500 AU envelope in Mpc, approach direction`: assert `fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, x)` is `1` at/inside `100 * SCALE_UNITS.AU_TO_MPC`, `0` at/outside `500 * SCALE_UNITS.AU_TO_MPC`, and strictly between at a midpoint — @@ -467,13 +467,13 @@ sgrAStarLensing: { band authored backwards) would flip this and is exactly what a classifier-direction test is for per `testing.md`'s boundary-test keep-rule. -- [ ] Run the test — fails (row doesn't exist). -- [ ] Add the `sgrAStarLensing` row to `SCALE_FADE_BANDS`, per the contract +- [x] Run the test — fails (row doesn't exist). +- [x] Add the `sgrAStarLensing` row to `SCALE_FADE_BANDS`, per the contract above, importing `SCALE_UNITS` (already imported in this file) — no new import needed for `AU_TO_MPC`, it already exists in `scaleUnits.ts`. -- [ ] Run the test — passes. -- [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run the test — passes. +- [x] Run `npm test` and `npm run typecheck` — green. +- [x] Commit. --- @@ -507,10 +507,10 @@ unconditional on far distance, unlike the seeded planets' glints). **Steps:** -- [ ] Add a named constant for the glint's fixed tint (warm-orange, linear +- [x] Add a named constant for the glint's fixed tint (warm-orange, linear RGB) and its base intensity, beside the layer's existing `GLINT_MIN_BRIGHTNESS` constant. -- [ ] In `draw`, after the existing `glints` packing loop, add a second loop +- [x] In `draw`, after the existing `glints` packing loop, add a second loop over `SCENE_ANCHOR_POINT_BODIES`: for each anchor body, compute `distMpc` via `regionRelativeDistanceMpc(camPos, regionById('galactic-centre'), states)` (same helper/region `milkyWayCloudLiveness.ts:40` already uses for the @@ -520,16 +520,16 @@ unconditional on far distance, unlike the seeded planets' glints). 0 ⇒ no render"), else pack the same 7-float camera-relative record shape (`positionMpc - camPos`, tint, brightness) the existing loop writes, continuing the shared `count`/`staging` buffer. -- [ ] Widen `enabled`: the layer must stay in the pass plan when the anchor +- [x] Widen `enabled`: the layer must stay in the pass plan when the anchor loop would pack ≥1 record even if `sceneBodyPartition(...).glints` is empty — mirrors the existing `pickEnabled`-widening pattern the file's header documents for the Earth caption stamp (`bodyGlintsLayer.ts:153-166`), but for `enabled` itself since this is a VISUAL row, not a pick-only widening. -- [ ] No `drawPick` change — the spec states Sgr A*'s existing pick stamp +- [x] No `drawPick` change — the spec states Sgr A*'s existing pick stamp (its caption) is untouched by this feature; the far-field glint carries no pick aspect of its own. -- [ ] Add a behavioural test (in the existing +- [x] Add a behavioural test (in the existing `tests/services/engine/frame/passes/bodyGlintsLayer.test.ts`) asserting the layer's `enabled` returns `true` when the anchor's crossfade alpha is positive even with an empty `glints` partition (construct a fixture @@ -540,8 +540,8 @@ unconditional on far distance, unlike the seeded planets' glints). such that the anchor's computed brightness is 0 (if any such condition exists given the "always present" design — if none does, state that in the test file instead of writing a vacuous test, per `testing.md`). -- [ ] Run `npm test -- bodyGlintsLayer` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test -- bodyGlintsLayer` and `npm run typecheck` — green. +- [x] Commit. --- @@ -575,7 +575,7 @@ export function buildSchwarzschildDeflectionLut(sampleCount: number): Schwarzsch **Steps:** -- [ ] Add the test `buildSchwarzschildDeflectionLut` with 2–3 literal +- [x] Add the test `buildSchwarzschildDeflectionLut` with 2–3 literal reference values (hand-computed, not re-derived from the same formula the implementation uses — a genuine independent check per `testing.md`'s no-mirror rule): @@ -595,17 +595,17 @@ export function buildSchwarzschildDeflectionLut(sampleCount: number): Schwarzsch - a monotonicity property: deflection strictly decreases as `b` increases across the sampled range (an independent property per `testing.md`'s "Do" list, catching a sign/ordering bug the two point values might miss). -- [ ] Run the test — fails (function doesn't exist). -- [ ] Implement `buildSchwarzschildDeflectionLut`: for `sampleCount` grid +- [x] Run the test — fails (function doesn't exist). +- [x] Implement `buildSchwarzschildDeflectionLut`: for `sampleCount` grid points spanning a chosen `[minImpactParamRs, maxImpactParamRs]` range (must comfortably straddle the photon sphere at `~2.598 r_s` and reach out to where the weak-field approximation is already accurate, so the pass's O(1) LUT lookup covers both the escape and near-capture regimes), numerically integrate (or closed-form where available) the Schwarzschild bending-angle relation and populate `samples`. -- [ ] Run the test — passes. -- [ ] Run `npm run typecheck` — green. -- [ ] Commit. +- [x] Run the test — passes. +- [x] Run `npm run typecheck` — green. +- [x] Commit. --- @@ -655,24 +655,24 @@ absent file) the spec cites. **Steps:** -- [ ] Write the WESL struct declaration matching the table exactly (field +- [x] Write the WESL struct declaration matching the table exactly (field order, offsets via WGSL's natural alignment rules — verify each `f32` run before a `vec3` lands on a 16-byte boundary per the `wesl-shaders` skill's CameraUniforms pattern). -- [ ] Write the CPU-side `Float32Array` packer function with an inline +- [x] Write the CPU-side `Float32Array` packer function with an inline docblock offset table matching this one (the wesl-shaders skill: "The CPU-side Float32Array write must match the WGSL struct byte-for-byte ... Document the offset table in a docblock on the renderer's TS file"). -- [ ] Add a byte-offset parity test in the style of existing WGSL/TS parity +- [x] Add a byte-offset parity test in the style of existing WGSL/TS parity tests (`tests/services/gpu/shaders/constants.parity.test.ts` precedent, per the wesl-shaders skill) OR a direct assertion that the packer writes each named field at its documented float index — this is a `testing.md` KEEP-RULE case (WGSL/TS parity + uniform byte-layout), not a constant restatement: it catches shader/TS drift invisible until a GPU silently reads garbage. -- [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test` and `npm run typecheck` — green. +- [x] Commit. --- @@ -713,7 +713,7 @@ export function skyCubemapFaceContext(input: { **Steps:** -- [ ] Add the test `skyCubemapFaceContext — derives a ReadyFrameContext with +- [x] Add the test `skyCubemapFaceContext — derives a ReadyFrameContext with the eye at the anchor position, looking along the requested face axis`: call it for each of the 6 `CubeFace` values with a fixture `eyeMpc`, assert the returned context's camera position matches `eyeMpc` and its @@ -721,11 +721,11 @@ export function skyCubemapFaceContext(input: { (an independent geometric check — e.g. dot the returned forward direction with the expected axis vector — not a re-derivation of whatever `deriveFrameContext` internally does). -- [ ] Add the test `skyCubemapFaceContext — returns null before bootstrap` +- [x] Add the test `skyCubemapFaceContext — returns null before bootstrap` (mirrors `pickFrameContext`'s `isReady` guard, `pickFrameContext.ts:56-90`). -- [ ] Run the tests — fail (function doesn't exist). -- [ ] Implement `skyCubemapFaceContext` following the `pickFrameContext.ts` +- [x] Run the tests — fail (function doesn't exist). +- [x] Implement `skyCubemapFaceContext` following the `pickFrameContext.ts` precedent exactly: re-derive a full `ReadyFrameContext` via `deriveFrameContext` from a SYNTHETIC camera pose (position = `eyeMpc`, orientation = the face's fixed look direction/up pair, a 90° @@ -735,10 +735,10 @@ export function skyCubemapFaceContext(input: { `ctx.drawPxPerRad` as frame-globals for angular sizing, not just `viewProj` (same rationale `pickFrameContext.ts:1-48`'s docblock gives for its own re-derivation choice). -- [ ] Add the `sky-cubemap` row to `renderTargetRows` per the contract above. -- [ ] Run `npm test -- skyCubemapFaceContext renderTargets` and +- [x] Add the `sky-cubemap` row to `renderTargetRows` per the contract above. +- [x] Run `npm test -- skyCubemapFaceContext renderTargets` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Commit. --- @@ -792,22 +792,22 @@ available via `ctx`/`state`) and passes it as the new fourth argument. **Steps:** -- [ ] Add the test `skyCubemapCaptureSchedule — full 6-face capture on band +- [x] Add the test `skyCubemapCaptureSchedule — full 6-face capture on band entry`: `bandJustEngaged: true` → `facesToCapture` has all 6 faces regardless of `frameIndex`. -- [ ] Add the test `skyCubemapCaptureSchedule — round-robins one face per +- [x] Add the test `skyCubemapCaptureSchedule — round-robins one face per frame otherwise`: `bandJustEngaged: false`, vary `frameIndex` across 6 consecutive values → each yields exactly one face, cycling through all 6 without repeats within the cycle. -- [ ] Add the test `skyCubemapCaptureSchedule — escape valve re-captures a +- [x] Add the test `skyCubemapCaptureSchedule — escape valve re-captures a stale or camera-moved face out of turn`: a face whose `lastCapturedAtMs` predates `nowMs` by more than the threshold (or `cameraMovedBeyondThreshold: true`) appears in `facesToCapture` even when the round-robin wouldn't select it this frame. -- [ ] Run the tests — fail. -- [ ] Implement `skyCubemapCaptureSchedule` (pure function, no GPU/engine +- [x] Run the tests — fail. +- [x] Implement `skyCubemapCaptureSchedule` (pure function, no GPU/engine state — testable headlessly per the file's own test above). -- [ ] Wire the schedule into `frameProgram`: when the lensing band alpha is +- [x] Wire the schedule into `frameProgram`: when the lensing band alpha is positive, emit one `{ kind: 'render', target: 'sky-cubemap', slab: ... }` step per face in `facesToCapture` (each drawing the fixed opt-in roster — `point-sprites`, `star-catalog` + `star-aggregates`, and the S-star @@ -815,7 +815,7 @@ available via `ctx`/`state`) and passes it as the new fourth argument. the band alpha is 0, emit NO capture steps at all (Q6's "pass cost is exactly zero outside the band" guarantee, restated for the capture side of the feature, not just the lensing draw itself). -- [ ] Update `frameProgram.ts`'s two static `TIMED_SLOTS`/`TIMED_SLOT_GROUPS` +- [x] Update `frameProgram.ts`'s two static `TIMED_SLOTS`/`TIMED_SLOT_GROUPS` builds (`frameProgram.ts:452-465`, which call `frameProgram(PLACEHOLDER_TONE, true, MAX_FOREGROUND_CHAIN)`) to pass all 6 `CubeFace` values as the new fourth argument — the same @@ -823,7 +823,7 @@ available via `ctx`/`state`) and passes it as the new fourth argument. `MAX_FOREGROUND_CHAIN` already documents, so the DebugPanel's GPU-timing groups include the sky-cubemap capture rows even on a frame where the band is inactive and the real list would be empty. -- [ ] Name the runtime hand-off: `renderFrame.ts` (not `frameProgram`, which +- [x] Name the runtime hand-off: `renderFrame.ts` (not `frameProgram`, which is static) derives the scheduled faces' `skyCubemapFaceContext`s each frame and passes them to the executor alongside the steps, so a capture step can resolve its face's context at execution time — the exact @@ -831,14 +831,14 @@ available via `ctx`/`state`) and passes it as the new fourth argument. the implementer's call, but the responsibility split (renderFrame derives, executor consumes, frameProgram stays static data) is the contract. -- [ ] Confirm (read each roster layer's `draw`) whether reusing the existing +- [x] Confirm (read each roster layer's `draw`) whether reusing the existing `CONTENT_LAYERS` rows' `draw` calls against a synthetic per-face `ctx` "just works," or whether a layer reads something a synthetic context can't supply (e.g. a GPU handle keyed to the real frame). Report any such finding rather than papering over it with a special case. -- [ ] Run `npm test -- skyCubemapCaptureSchedule frameProgram` and +- [x] Run `npm test -- skyCubemapCaptureSchedule frameProgram` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Commit. --- @@ -894,19 +894,19 @@ not a licence to build finite-distance geodesics. **Steps:** -- [ ] Write `vertex.wesl`: minimal fullscreen-triangle (or quad) vertex +- [x] Write `vertex.wesl`: minimal fullscreen-triangle (or quad) vertex stage producing clip position + a per-pixel view-ray direction varying, importing `CameraUniforms` from `package::lib::camera` per the wesl-shaders skill's shared-prefix convention (gotcha #2: `package::`, never the npm name; gotcha #3: imports at the top). -- [ ] Write `fragment.wesl` implementing the escape/annulus/capture +- [x] Write `fragment.wesl` implementing the escape/annulus/capture classification above, sampling the Task 9 LUT texture and the Task 11 sky-cubemap texture array as `texture_cube`. No backticks in comments (wesl-shaders gotcha #1); no brace-list imports (gotcha #4); one `import` per identifier (gotcha #5) — cite `lib/math.wesl` as the "one cohesive multi-function module" precedent if any shared helper (e.g. a ray-sphere or ray-annulus intersection) is factored out. -- [ ] Write `sgrAStarLensingRenderer.ts`: the TS pipeline (pipeline layout, +- [x] Write `sgrAStarLensingRenderer.ts`: the TS pipeline (pipeline layout, bind group with the Task 10 uniform buffer + LUT texture + cubemap texture, `createShaderModuleWithDevLog` per the shader-compile-logger convention every renderer in this tree already follows) — cite @@ -918,18 +918,18 @@ not a licence to build finite-distance geodesics. the spec's cited (but absent from this repo) `createNfwLensLutTexture`; define it in this file rather than inventing a second lensing-utils home for one function. -- [ ] Write `sgrAStarLensingLayer.ts` implementing the `ContentLayer` +- [x] Write `sgrAStarLensingLayer.ts` implementing the `ContentLayer` contract above. -- [ ] Register `sgrAStarLensingLayer` in `passes/index.ts`'s import list and +- [x] Register `sgrAStarLensingLayer` in `passes/index.ts`'s import list and `CONTENT_LAYERS` array (position per Task 14's reorder — this task adds the row; Task 14 fixes its exact index relative to `orbit-trails` / `body-glints`). -- [ ] Manual dev-server smoke check that the shader module compiles (no +- [x] Manual dev-server smoke check that the shader module compiles (no `Invalid ShaderModule` in the console per the wesl-shaders skill's dev-mode logger) — this is not the full visual gate (Task 17), just confirming the pipeline builds. -- [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test` and `npm run typecheck` — green. +- [x] Commit. --- @@ -943,7 +943,7 @@ not a licence to build finite-distance geodesics. **Steps:** -- [ ] Re-read `passes/index.ts`'s current order at the time of this task +- [x] Re-read `passes/index.ts`'s current order at the time of this task (Task 13 already inserted `sgrAStarLensingLayer` somewhere) — confirm the current indices of `milkyWayAggregateLayer`/`milkyWayUpsampleLayer`/`milkyWayLayer`/`starPointsLayer` (which the lensing pass must draw AFTER, since it samples the roster) @@ -951,23 +951,23 @@ not a licence to build finite-distance geodesics. header's numbered list at the time this plan was written — re-verify against the live file, since Task 8 modified `bodyGlintsLayer` but not its position). -- [ ] Move `sgrAStarLensingLayer` to sit AFTER `starAggregateUpsampleLayer`/`constellationsLayer` +- [x] Move `sgrAStarLensingLayer` to sit AFTER `starAggregateUpsampleLayer`/`constellationsLayer` (the last roster row the lensing pass samples — point-sprites, milky-way, star-points, star-aggregates, star-catalog are all upstream by the time `constellationsLayer` runs) and BEFORE `orbitTrailsLayer`. -- [ ] Move `orbitTrailsLayer` and `bodyGlintsLayer` to sit AFTER +- [x] Move `orbitTrailsLayer` and `bodyGlintsLayer` to sit AFTER `sgrAStarLensingLayer` in the array (a two-row reorder — the spec's explicit "orbit-trails and body-glints therefore move to draw AFTER sgrAStarLensing"). -- [ ] Update the module header's numbered draw-order comment (`passes/index.ts:1-198`) +- [x] Update the module header's numbered draw-order comment (`passes/index.ts:1-198`) to reflect the new positions — this comment is the file's own authoritative map and must not go stale (it directly documents load- bearing order, unlike a narrative aside). -- [ ] Run `npm test` and `npm run typecheck` — green (no test should assert +- [x] Run `npm test` and `npm run typecheck` — green (no test should assert the old literal order without a real reason; if one does, per `testing.md` judge whether it's a legitimate order-dependency test — update it if so, delete it if it was a restatement). -- [ ] Commit. +- [x] Commit. --- @@ -997,18 +997,18 @@ gate). **Steps:** -- [ ] Add the tuning section + container following the +- [x] Add the tuning section + container following the `ZoneOfAvoidanceTuningSection*` structural precedent, wired to mutate the relevant constants at runtime (via whatever live-settings seam that precedent uses — read its container before implementing, don't invent a new one). -- [ ] Mount it in `DebugPanel.tsx` alongside the other tuning sections. -- [ ] Use it during Task 17's visual gate to converge on the DEFAULTS that +- [x] Mount it in `DebugPanel.tsx` alongside the other tuning sections. +- [x] Use it during Task 17's visual gate to converge on the DEFAULTS that ship: Tier-1 values back into `BLACK_HOLES` (Task 6), Tier-2 values into `DEFAULT_SGR_A_STAR_LENSING_TUNING` (`src/data/defaults.ts`). The section itself stays mounted. -- [ ] Run `npm test` and `npm run typecheck` — green. -- [ ] Commit. +- [x] Run `npm test` and `npm run typecheck` — green. +- [x] Commit. --- @@ -1018,7 +1018,7 @@ gate). **Steps:** -- [ ] BEFORE any Phase B code lands (i.e., run this against Phase A's merged +- [x] BEFORE any Phase B code lands (i.e., run this against Phase A's merged state, or the earliest point in Phase B history before Task 5): read `.claude/skills/perf/SKILL.md` first, then run `npm run perf` with `--url http://localhost:` (read @@ -1026,7 +1026,7 @@ gate). branch's server). Record the baseline numbers outside the band (Sgr A* far off-frame) and note there is no "inside the band" baseline yet (the feature doesn't exist). -- [ ] AFTER Task 15 (all feature work done — the tuning section ships, per +- [x] AFTER Task 15 (all feature work done — the tuning section ships, per the Settings amendment above, so there is no removal step to wait on): re-run `npm run perf` the same way, twice — once with Sgr A* far outside the @@ -1035,12 +1035,12 @@ gate). not unbounded, cost — the six-face capture amortized per Q8, the LUT lookup O(1) per pixel, the bounded 32–64-step march only for annulus-adjacent pixels). -- [ ] The report must carry a VRAM line for the `sky-cubemap` row alongside +- [x] The report must carry a VRAM line for the `sky-cubemap` row alongside the timing numbers: 0 B outside the band, 50 MB in-band at the shipped 1024 px resolution, 201 MB at the 2048 px knob — the row is lazily allocated (`renderTargets.ts`), so this cost is invisible to a timing reading alone. -- [ ] Report both readings plainly. Per the spec's Perf section and the +- [x] Report both readings plainly. Per the spec's Perf section and the project's code-is-liability convention: a regression outside the band, or an unbounded/unacceptable cost inside it, HALTS the landing pipeline — this is the user's ruling to make, not something this task From 6d1435eca652af5bdb23eff9819299289eeca71a Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:43:08 +0200 Subject: [PATCH 59/60] docs(plan): mark render-black-hole complete MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DoD audit READY: 8011 tests green, typecheck clean, T1–T17 ticked (T17 user-attested 2026-09-02), perf neutral outside the band / bounded inside, final review + deletion audit applied. Plan + spec relocated to completed/, SDD ledger archived beside the plan. Co-Authored-By: Claude Fable 5 --- .../2026-09-01-render-black-hole.ledger.md | 209 ++++++++++++++++++ .../2026-09-01-render-black-hole.md | 20 +- .../2026-09-01-render-black-hole-design.md | 0 3 files changed, 219 insertions(+), 10 deletions(-) create mode 100644 docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md rename docs/superpowers/plans/{ => completed}/2026-09-01-render-black-hole.md (98%) rename docs/superpowers/specs/{ => completed}/2026-09-01-render-black-hole-design.md (100%) diff --git a/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md new file mode 100644 index 0000000000..628ce8935a --- /dev/null +++ b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md @@ -0,0 +1,209 @@ +# SDD ledger — plan: docs/superpowers/plans/2026-09-01-render-black-hole.md + +Spec: docs/superpowers/specs/2026-09-01-render-black-hole-design.md (binding authority). +Branch: worktree-render-black-hole @ f60ba2b0e (docs: spec + plan). Phase A = tasks 1-3 → own prep PR; Phase B = tasks 4-17. +User rulings from checkpoint: prep = SEPARATE PR; scope = Phase A first. + +## Pre-flight scan + +Shared-file / interface pairs checked: + +| Tasks | Shared surface | Finding | +|---|---|---| +| T1+T2 | `AnchorPointBody.d.ts` (docblock vs `standoffRadii` field) | Sequential edits, no conflict | +| T2+T5 | `sceneSgrAStar.ts` (standoffRadii vs radiusM swap) | Sequential, disjoint lines | +| T1+T12 | `frameProgram.ts` (capacity const vs 4th param) | Different phases, sequential | +| T3+T11 | `RenderTargetSpec.fixedSizePx` producer/consumer | Signatures match (`{size, layers}`) | +| T7+T8+T13 | `SCALE_FADE_BANDS.sgrAStarLensing` producer/consumers | Name + AU→Mpc consistent | +| T9+T10+T13 | LUT type → uniform metadata → texture upload | Field names consistent | +| T11+T12 | `CubeFace` producer/consumer | Consistent | +| T13+T14 | layer registration vs reorder | Explicit hand-off in both tasks | +| T15+T16+T17 | tuning knobs used at T17, removed in T15's final step; T16 measures after removal | Interleaved by design; see Ruling 2 | + +Per-task self-consistency: T1-T3, T5-T14 internally consistent (tests match code contracts, file lists complete). T4/T16/T17 are manual gates with no file edits — consistent. T6 has no test by design (testing.md registry rule) — consistent with conventions. + +Rulings at pre-flight: + +- Ruling 1: Phase A implemented as commits on this branch (worktree-render-black-hole); at Phase A review-clean, cherry-pick the three task commits onto a new branch off origin/main → prep PR. — Why: single-worktree session; commits are cleanly separable one-per-task. — Cost if wrong: cherry-pick conflicts (low; files untouched on main since merge). +- Ruling 2: T16's "before" baseline (outside-band perf) is taken immediately after Phase A merges to main and before Task 5's first feature commit, numbers stored in this workspace — the plan's task ordering places T16 late but its step 1 text says exactly this. — Cost if wrong: an invalid baseline, re-take against Phase A state (cheap, per RTC-camera precedent). +- Ruling 3: No harness todo tool exists in this session; Rule 1's visible task list is satisfied by the user-requested Artifact task board + this ledger. — Cost if wrong: none material. + +## Progress +Task 1: implemented (commit b2dcb9b4b, BASE f60ba2b0e), suite 7843 green, typecheck clean; review dispatched +Task 3: implementer dispatched pipelined (files disjoint from T1); T2 queued behind T1 review (shares AnchorPointBody.d.ts) +Note: stale-LSP diagnostics on visibleSlabBodies.test.ts observed post-T1; real tsc clean (verified in controller) +Task 1: review — 1 Important (stale [earth,...planets] header comment in visibleSlabBodies.test.ts:1-4), fix round queued behind in-flight T3 implementer (serial-implementer rule) +Task 1: minor (deferred): frameContext ternary duplicates anchor spread across branches +Task 1: minor (deferred): AnchorPointBody.d.ts docblock 16 lines, over ≤10 budget (pre-existing, natural trim moment missed) +Task 3: implemented (commit 23969f785, BASE b2dcb9b4b), suite 7845 green, typecheck clean; reviewer dispatched; implementer flagged extraRows injection param for reviewer judgment +Task 1: fix round 1/5 dispatched (resume original implementer; finding = stale test-file header) +Task 1: fix round 1/5 (1 addressed, 0 open; commit f92f9edcd) +Task 1: complete (commits f60ba2b0e..f92f9edcd, review clean) +Task 2: implementer dispatched (T1 loop closed; files disjoint from T3 under review) +Task 3: complete (commits b2dcb9b4b..23969f785, review clean/Approved) +Task 3: minor (deferred): comment-to-code ratio in renderTargets.ts diff near 1:1 (legit WHY content) +Task 3: minor (deferred): extraRows test seam — Phase B (T11) must make an explicit keep-or-delete call when the real cubemap row lands +Task 2: implemented DONE_WITH_CONCERNS (commit cc1d7f31d, BASE f92f9edcd; suite 7855 green) — concern: read-site wiring took 8 files beyond brief's 4, mirroring pivotRadiusMpc threading; reviewer dispatched with that as central question +Note: stale-LSP diagnostics again (clampDistance.test.ts); real tsc verified clean in controller +Task 2: review — threading judgment UPHELD (9-file pivotRadiusMpc mirror correct); 1 Important (extractSelectionRow standoffRadii narrowing untested); fix round 1/5 dispatched (resumed implementer) +Task 2: minor (deferred): report bookkeeping miscount (6 vs actual 9 files beyond brief) +Task 2: fix round 1/5 (1 addressed, 0 open; commit 872e9a83b, mutation-verified) +Task 2: complete (commits f92f9edcd..872e9a83b, review clean) +Task 2: minor (deferred): SCENE_BODIES import in extractSelectionRow.test.ts flagged unused by editor hint (pre-existing per re-review) +PHASE A COMPLETE — cutting prep PR (Ruling 1): cherry-pick b2dcb9b4b 23969f785 f92f9edcd cc1d7f31d 872e9a83b onto prep branch off origin/main +Prep PR OPENED: #649 (prep-black-hole-ground, draft; cherry-picks b0166ca27..ee7f3cd10; typecheck + 47 focused tests verified on the branch); worktree back on worktree-render-black-hole, 5 task commits pushed there too +PHASE B GATED on #649 merge; next after merge = Ruling 2 perf baseline, then Task 4 probe (user-attested) + +## Open thread: standoffRadii wiring rework (user directive 2026-09-01) +USER IS NOT HAPPY with T2's 9-file two-lane threading (pivotRadiusMpc + pivotStandoffRadii in parallel) — second-special-case trigger. Explore agent IN FLIGHT mapping the lane (question: does any orbit-controls-lane consumer need radius AND standoff separately, or is floor-at-source viable?). +HANDLING PLAN for its result: present user a priced choice — (a) thread single precomputed pivotFloorMpc from extractSelectionRow (deletes second lane; lean if radius has no other lane consumer) vs (b) one {radiusMpc, standoffRadii} bundle. Rework rides PR #649 as a P2 rework commit (still draft, cheap). Do NOT merge #649 until this is settled. +Dev server: http://localhost:5176 shell bn6iz5dyv (this worktree; 5173-5175 = other worktrees). +Queued after #649 (with rework) merges: Ruling-2 perf baseline → T4 2r_s probe (user at dev server) → T5+. +Explore result: floor-at-source (a) NOT viable — zoomedDistance.ts:36-48 needs RAW radius for taper anchor (h = distance − pivotRadiusMpc) separate from floor product; pivotRadiusMpc has 5 consumers outside the lane (orbitRadPerPixel, frameContext:263, runFrame:447, scaleBar:93/103, logCameraState:38); row.standoffRadii has exactly 1 reader (pivotStandoffRadii.ts). +Ruling 4 (USER, 2026-09-01): option (b) — merge the lane into ONE getter `pivot: () => { radiusMpc: number | null; floorMpc: number }`; floorMpc computed at lane source; clampDistance back to 2 args; delete pivotStandoffRadii.ts; standoffRadii concept survives only in body data + SelectionRow + one derivation line; outside-lane radius consumers untouched. Rework rides PR #649 as commit(s) on worktree branch then cherry-pick to prep-black-hole-ground. — Cost if wrong: one revert commit. +Rework (T2b): implemented DONE (commit 6923db0de, BASE 872e9a83b; tsc clean, 7853 tests green); reviewer dispatched (sonnet, review-872e9a83b..6923db0de.diff, verdict → task-2b-review.md). +Rework (T2b): review — spec APPROVED (reviewer independently re-derived floor equivalence, re-ran suite+tsc), quality APPROVED w/ 1 Important (SelectionRow.d.ts:35 dangling `pivotStandoffRadii` comment) + 2 Minor (pivotRadiusMpc.ts header 12>10; comment ratio). Fix round 1/5 dispatched (resumed implementer; Important + header trim). +Rework (T2b): fix round 1/5 done (commit 3f9134900; tsc clean, 7853 green); scoped re-review CLEAN (all 3 findings addressed, comment-only fix diff). +Rework (T2b): COMPLETE — cherry-picked to prep-black-hole-ground as 5f12a9e8f + dd15c3dc2, pushed (typecheck + 403 focused camera/input tests green on branch); PR #649 body updated + marked READY FOR REVIEW; worktree back on worktree-render-black-hole @ 3f9134900 (pushed). standoffRadii thread CLOSED — #649 now awaits USER review/merge; then Ruling-2 perf baseline → T4. +USER: "merge in main" → conflicts vs #648 (prep(camera) P5 roll + P6 split, 725c6ddc7). Resolver agent unioned both refactors on prep branch (merge 4c5b05a2e; pivot getter moved OUT of OrbitControlsOptions — post-#648 home = applyInputToCamera.ts/drainInput.ts, two semantic conflicts in those auto-merged new files fixed; report merge-649-main-report.md; suite 7899 green). +PR #649 MERGED (squash 0b1787ae4); prep branch deleted local+remote. origin/main merged into worktree-render-black-hole as 2129c355d (lane files = main's tree verbatim, since main's squash contains the union and this branch had no unique src/tests content); tsc clean, suite 7916 green, pushed. Branch delta vs main = docs only (spec+plan+grill). +Ruling-2 perf BASELINE TAKEN (main @ 0b1787ae4 content, 30 frames, :5176) → perf-baseline-0b1787ae4.txt in this workspace. Headline merged medians (Apple Silicon slot-sums, ordinal not additive): earth-surface 17.7 / solar-system 17.9 / star-field 18.4 / milky-way 17.7 / milky-way-outside 25.7 / milky-way-close 29.7 / galactic-centre 10.8 / local-group 20.3 / full-survey 20.0 ms. T16 "after" must re-run SAME flags + frames and compare per-scenario. Known noise: 2× SDSS-footprint 404 page errors (pre-existing). +Task 4: complete — USER ATTESTED 2026-09-01 "looks good" at the 2 r_s floor (no jitter/clipping/instability); caveat recorded: nothing rendered at that depth yet, so the judgment is limited — T17's final visual gate re-covers this with the lens live. No fold-in of the origin-vs-target gates item; backlog item stays. +Task 5: implementer dispatched (haiku — 1-2 files, complete spec; brief task-5-brief.md, report task-5-report.md); BASE 2129c355d. +Ruling 5 (USER-directed 2026-09-01: "run as many parallel agents as possible and safe"): parallel wave 1 = T6+T7+T9+T10+T11, each in an ISOLATED worktree (isolation:worktree) since same-worktree implementers share the git index (and T5 is mid-flight here). Verified file-disjoint: T6 (@types/data+data/blackHoles), T7 (scaleFadeBands), T9 (@types/lensing+utils/lensing), T10 (new .wesl lib + standalone packer), T11 (renderTargets row + skyCubemapFaceContext + CubeFace). Interfaces pinned by plan briefs. INTEGRATION: after T5 commits here, cherry-pick wave commits into worktree-render-black-hole in task order (5→6→7→9→10→11), typecheck+focused tests per pick, full suite at wave end; reviews run on the integrated diffs, pipelined. Wave 2 (T8 after T7; T12 after T10+T11; T13 after T9+T10+T11; T14 after T13) dispatches as producers integrate. — Cost if wrong: cherry-pick conflicts or interface drift caught by review/tsc; disjointness makes this cheap. +Wave 1 dispatch: T6 haiku, T7 haiku, T9 sonnet, T10 sonnet (wesl-shaders skill mandated), T11 sonnet; reports task-N-report.md; agent worktrees must symlink main repo node_modules. ALL 5 IN FLIGHT. +Task 5: implemented DONE (commit 2fab16ed6 on worktree branch, BASE 2129c355d; suite 7920 green, r_s ≈ 1.2693e10 m, 0 stale refs); reviewer dispatched (sonnet, review-2129c355d..2fab16ed6.diff → task-5-review.md). +User Q answered (cubemap 256²): ~2.8 px/deg vs ~20-25 px/deg main view; points survive via sprite floors but soften under ring magnification; ruling stays "land 256, judge at T17, bump to 512 (one literal) if mushy". +Task 7: implemented DONE (agent wt commit 6d51e7760) → cherry-picked as bbaf0712a; 5 focused tests green; reviewer dispatched (haiku, review-2fab16ed6..bbaf0712a.diff). Stale-LSP false alarm #3 on scaleFadeBands.test.ts (real grep+vitest fine). +Task 6: implemented DONE (agent wt commit 370713ae9) → cherry-picked as d3498bdd0; typecheck green; reviewer dispatched (haiku, review-bbaf0712a..d3498bdd0.diff; watch: brief's nested emission{} contract vs possible flattening). +Task 8: implementer dispatched (sonnet, isolated wt off HEAD d3498bdd0 — must verify base includes bbaf0712a; brief task-8-brief.md, report task-8-report.md). +Task 6: complete (d3498bdd0, review clean both verdicts — nested emission{} confirmed, BodyId constraint verified). +Task 7: complete (bbaf0712a, review clean both verdicts — direction pinned, no findings). +Task 5: review Approved w/ 2 Important (test reference back-filled from impl → retarget to spec-cited 1.269e10 m w/ ~0.1% relative tolerance; UI-impact unremarked → report addendum only, NO test per testing.md ruling) + 2 Minor (tolerance comment 8× off; comment budget 9>8). Fix round 1/5 dispatched (resumed implementer). +Task 8: first dispatch BLOCKED — LEARNED MECHANIC: isolation:worktree agent worktrees are cut from MAIN tip (0b1787ae4), NOT this branch; T8's base lacked bbaf0712a. Resumed with fix: `git merge d3498bdd0` in its worktree (shared odb), then implement; report stays in AGENT worktree .superpowers path (sandbox refuses ours — also true for T6/T7/T9/T10/T11 reports; reviewers get the agent-worktree fallback path). +Task 5: fix round 1/5 done (commit aacd4510e on branch — spec-sourced reference, tolerance fixed, comments trimmed, UI impact in report); scoped re-review dispatched (haiku, review-d3498bdd0..aacd4510e.diff). +Task 10: implemented DONE (agent wt commit 0423762fa) → cherry-picked as 494e4222a; parity test + typecheck green; implementer caught backtick-in-wesl gotcha itself via ?static probe. Reviewer dispatched (sonnet — walks byte table 3 ways; report at agent-a5fb4c095025b2d60 path). +Task 5: complete (2fab16ed6 + fix aacd4510e, re-review clean all findings). +Task 11: implemented DONE (agent wt commit 00f710578; agent CLAIMED it committed on our branch — FALSE, branch ref verified untouched) → cherry-picked as f09e75274; 19 focused tests green. Implementer concerns for later tasks: (2) cube-face up-vector convention unspecified upstream — reviewer judging vs WebGPU standard; (3) synthetic frustum reuses live near/far — reviewer judging. extraRows seam now redundant per implementer — fold into deletion-audit at /feature-done. +Task 9: implemented DONE (agent wt commit 3cf1b4c6a; mpmath/scipy-independent references, u=1/r Simpson integration) → cherry-picked as 03ca898d6; 6 focused tests + typecheck green. +Note: this worktree's node_modules is a SYMLINK → main repo node_modules (predates? unowned) and shows as ?? in git status (gitignore dir-only rule misses symlinks) — harmless with explicit adds; leave. +Reviewers dispatched: T11 (sonnet, incl. concerns 2+3 adjudication), T9 (sonnet, physics spot-checks). T12 implementer dispatched (sonnet, isolated wt; setup = symlink node_modules + `git merge 03ca898d6`; renderFrame-derives/executor-consumes contract in brief). +Task 10: review — compliance PASS (byte table walked 3 ways by hand), quality 1 Important: parity test never reads the .wesl, can't catch WESL-side reorder → rework to atmosphereUniformsLayout.parity.test.ts style (regex-parse struct). Fix round 1/5 dispatched (resumed implementer in its wt; fix commit to be cherry-picked). +Task 10: fix round 1/5 done (agent commit 4e17407e1 → cherry-picked as ab85df30e; new sgrAStarLensingUniformsLayout.parity.test.ts, 2 tests green); scoped re-review dispatched (haiku). +Branch pushed at 03ca898d6 then ab85df30e (user asked; push after every integration from now on). +Task 10: complete (494e4222a + fix ab85df30e, re-review clean — reorder failure path traced). +Task 9: review — compliance PASS (physics independently re-derived by reviewer; references genuinely independent, LUT within 5e-5); quality 1 Important (dangling comment pointer: endpoint-limit derivation "lives in test file" — it doesn't) + 2 Minor (d.ts header 9>5/2; prettier long line). Fix round 1/5 dispatched (resumed implementer, its wt). +Task 11: review — compliance PASS; 1 Important REAL DEFECT confirmed w/ numbers: synthetic projection reuses live near 0.01 Mpc (~10 kpc) → S-stars at ~5e-10 Mpc all near-clipped out of the capture. Fix round 1/5 dispatched (resumed implementer): named SKY_CAPTURE_NEAR_MPC (~0.1 AU), far kept, depthless-so-no-precision-cost rationale, + near<100AU test; NO signature change (T12 unaffected). Minor: extraRows seam redundant → deletion-audit candidate (also T11 reviewer verdict). Up-vector convention + position math verified CORRECT by reviewer. +Task 9: fix round 1/5 done (agent commit eab41da7d → cherry-picked 8f1cfa9d7; comments/format only, prettier-clean); scoped re-review dispatched (haiku). +Task 11: fix round 1/5 done (agent commit d8d865419 → cherry-picked 45912e20a; own near plane + near<100AU test); scoped re-review dispatched (haiku). Pushed through 45912e20a. +Task 9: complete (03ca898d6 + fix 8f1cfa9d7, re-review clean). +Task 11: complete (f09e75274 + fix 45912e20a, re-review clean — SKY_CAPTURE_NEAR_MPC verified fed into projection, revert-regression test decisive). +Task 8: implemented DONE — NOTE: agent's resumed session committed 84f47c781 DIRECTLY on our branch (isolation didn't hold across resume; landed correctly on top of 45912e20a, no harm; watch this mechanic). 20 focused tests + full suite 7943 green per report; pushed. Reviewer dispatched (sonnet — crossfade direction, staging capacity, 4 reconciled fixtures, dead imports). Implementer flags: tint [1,0.55,0.2] × 0.8 base intensity = first-pass values, NOT visually verified → fold into T15/T17. +Task 8: review — both verdicts PASS (crossfade direction + GC-keyed distance + 7-float shape all traced); 3 Important quality (MAX_GLINTS 24 = zero margin w/ silent break → derive; default mock seeds far anchor forcing 3 pre-existing test overrides → invert to inert default; save/restore → mockImplementationOnce) + Minors (dead SCENE_PLANETS import; stale "dedicated ContentLayer row" comment in sgr-a-star.ts). Fix round 1/5 dispatched (resumed implementer — commits DIRECTLY on branch on top of 84f47c781, gate = full suite). +Task 12: implemented DONE (agent wt commit 31d1c94be; suite 7944 green there) — NOT yet cherry-picked (T8 fix agent is committing directly on our branch; pick T12 only after T8 fix lands to avoid index collision; possible fixture-file overlap with T8's mock rework — resolve at pick). Honest OPEN FINDING per brief's STOP-and-report: no ContentLayer targets 'sky-cubemap' → capture steps select an EMPTY draw group (schedule+plumbing only, no actual capture yet); design call (capture ContentLayer rows vs executor bypass) DEFERRED TO T13 dispatch — I rule there, reading T13 brief + T12 report + spec. Structural additions: FrameStep.face discriminator (TIMED_SLOTS uniqueness), renderStepTimingSlotName in slabs.ts, cameraRuntime.skyCubemapCapture (SkyCubemapCaptureRuntime). Reviewer dispatched (sonnet, reviews from agent worktree). +Task 12: review — compliance PARTIAL: the brief's runtime hand-off (renderFrame derives face ctx → executor consumes per-step) was NEVER BUILT and UNDISCLOSED (reviewer grep-confirmed zero refs); everything shipped is correct (45/45 tests, structural additions judged minimal). Fix round 1/5 dispatched (resumed implementer, its wt): build the hand-off + executor per-step ctx override (capture steps only) + test exercising face→ctx match & null-skip; comment-budget trim; report must own the nondisclosure. +Task 8: fix round 1/5 done (b21a5fc1c directly on branch, 20 focused green, pushed); scoped re-review dispatched (haiku). +Task 8: complete (84f47c781 + fix b21a5fc1c, re-review clean — MAX_GLINTS now derived w/ margin 4, inert-anchor default, mockImplementationOnce). +Task 12: fix round 1/5 done (agent commits 31d1c94be+0640f6c5b → cherry-picked 2a8a32985+ef31b088f; hand-off built + renderFrame.skyCubemapHandOff.test.ts; 587 frame tests green; pushed); scoped re-review dispatched (haiku). +Ruling 6 (empty-draw-group design, T12's deferred finding): capture roster = data-driven OPT-IN FLAG on ContentLayer (e.g. `skyCapture?: true` on point-sprites, star-catalog, star-aggregates, S-star branch rows); frameProgram/executor build capture steps' draw group from that flag instead of target-matching. Implemented BY T13 (it owns making capture real), including the per-layer synthetic-ctx verification T12's brief deferred. — Why: registry-row growth at an existing seam beats a parallel row set (bolt-on) or a frameProgram-hardcoded list (hand-maintained roster). — Cost if wrong: one flag field to rename/remove. +T13: implementer dispatched (sonnet, IN THIS WORKTREE — branch quiet, dev server here for smoke; wesl-shaders skill mandated; headless compile check via 1-frame perf run). +Task 12: complete (2a8a32985 + fix ef31b088f, re-review clean — hand-off verified by identity-assertion test, executor override capture-steps-only, null-skip graceful). +In flight now: T13 impl only (in this worktree). On its report: review loop → T14 (draw-order reorder) → T15 (debug knobs, temporary) → T16 (perf re-measure, same flags vs perf-baseline-0b1787ae4.txt) → T17 (USER visual gate at :5176). Wave-1 tasks ALL complete; T8 complete. Next: T12 fix lands → cherry-pick both T12 commits → re-review → dispatch T13 (with my ruling on the empty-draw-group design: capture ContentLayer rows vs executor bypass — read T13 brief + T12 report + spec §capture before ruling). Then T14 → T15 → T16 (perf vs baseline) → T17 (user visual gate). Wave 2 remaining after T8/T12: T13 (geodesic pass — deps T9/T10/T11 all integrated), T14 (draw order, after T13), T15 knobs, T16 perf re-measure, T17 user visual gate. +Task 13: implemented DONE (13ee8d3bd Ruling-6 flag mechanism + 9e8de2530 geodesic pass, directly on branch; typecheck + 7963 tests green, headless compile check clean). Reviewer dispatched (sonnet). TWO honest open findings in report: (1) capture roster deliberately EMPTY — the three roster renderers (galaxyPoint/starPoint/starCatalog) each queue.writeBuffer a single shared uniform buffer per draw(); a 6-face+main multi-draw within one submit means only the LAST write survives (RENDERER.md landmine #1; planetRenderer already carries the per-caller-buffer fix, roster renderers do not) → flagging them today would render 5 of 6 faces from the wrong camera. Correctly STOPPED per T12 brief. (2) lens layer registered but unreachable — frameProgram emits no (hdr, BODY[k]) step; that is T14's wiring per brief. Infinity encoding: LUT captured samples → 1000-rad finite sentinel pre-upload, fragment thresholds at 500 rad. +Ruling 7 (writeBuffer race, T13 finding 1): fix as addendum task T13b AFTER T13 review lands — preferred shape (b): executor-level submit boundary per capture face (queue.writeBuffer is queue-ordered against submits, so per-face submit interleaves writes correctly; renderers stay ignorant of capture — un-braid); fallback shape (a): per-caller/per-face uniform buffers in the 3 roster renderers (planetRenderer precedent) if the timing harness/encoder structure blocks (b). T13b also sets skyCapture:true on the roster rows + runs the per-layer synthetic-ctx verification. Implementer verifies (b)'s feasibility against executeFrame/TIMED_SLOTS before choosing; the choice is theirs within this ordering. — Why: capture that draws nothing defeats the feature; scheduling-level fix is the smallest artifact. — Cost if wrong: one executor diff to revert, fall back to (a). +Task 13: review — BOTH verdicts REJECTED on one blocker: annulusEmission march centered on the CAMERA (t 0..~18 r_s) instead of the black hole along the ray — band is active out to 500 AU so the glow never renders in the intended range; fix = center march on closestT = dot(toAnchor, rayDir). Escape/capture classification, Infinity sentinel (1000/500 rad), Ruling-6 flag mechanism, zero-cost gating, cubeViewOf, rotateAroundAxis, ray reconstruction ALL verified correct; race claim independently confirmed in starPointRenderer + galaxyPointRenderer. Should-fix: WESL comment budget (fragment 69/98, vertex 29/25). Fix round 1/5 dispatched (resumed implementer, this worktree, commits directly on branch). +Task 13: fix round 1/5 done (bb00481fc directly on branch — march centered on closestT, WESL comment budgets trimmed; typecheck + 7963 green, headless compile clean); scoped re-review dispatched (haiku, review-9e8de2530..bb00481fc.diff). +Task 13: complete (13ee8d3bd + 9e8de2530 + fix bb00481fc, re-review clean — march window [closestT±9r_s] verified geometrically, budgets met). T13b (Ruling 7 race fix) HELD pending user shape call: user floated per-face buffer clones (measured cheap: writes are bytes-KB, ring of 7 at init, zero GC; starCatalog cut streams differ per face and must clone too) vs ruling's submit-per-face; user said "just talking" — do NOT dispatch T13b until they choose. T14 dispatching now (draw order + (hdr,body) step wiring — makes lens reachable; disjoint from T13b). +Ruling 8 (T14 scope): T14's reorder alone leaves the lens layer unreachable (T13 report finding 2: frameProgram emits no (hdr, BODY[k]) step). T14's dispatch adds: verify reachability after the reorder; if no existing step invokes sgrAStarLensingLayer, wire the minimal band-gated frameProgram step emission (zero-cost outside band) — the implementer verifies the actual mechanism against frameProgram/executor before assuming. — Why: a reorder of a layer nothing draws satisfies the letter, not the spec (the pass must render at T17). — Cost if wrong: one frameProgram diff to revisit at review. +Task 14: implemented DONE_WITH_CONCERNS (93aff85af directly on branch, pushed; typecheck + 7967 green, headless clean). Ruling-8 wiring confirmed needed and built: band-gated (hdr, BODY[k]) lens step, MAX_FOREGROUND_CHAIN-style static sizing. Reorder + header renumber done per brief. RESIDUAL flagged honestly: orbit-trails/body-glints share their old step, so the lens step draws OVER them (spec wants them unwarped on top); implementer recommends defer-to-T17 claiming solar-system-only overlap — reviewer instructed to CHECK whether S-STAR trails render at the GC (would overlap the hero scene, invalidating the deferral) and adjudicate split-now/defer/unconditional with evidence. Reviewer dispatched (sonnet). +T13b design converged in-chat (NOT yet ruled — user steering): generalizable "viewSlot" concept — ctx.viewSlot (0=main, 1-6=faces, XR eyes later), one helper owning slot mechanics (ring-of-buffers vs dynamic-offset hidden inside), roster renderers adopt keyed on ctx.viewSlot; T13b converts only the 3 roster renderers, others migrate on contact (backlog note). AWAITING user go before rewriting brief + dispatching. +Task 14: complete (93aff85af, review APPROVED both verdicts — header/order/TIMED_SLOTS/test judgments all verified; nit PASS_GROUP_TITLES scope creep accepted). Should-fix adjudicated with evidence: implementer's defer-to-T17 claim FACTUALLY WRONG — orbitalElements.ts:597-599 appends 39 bound S-stars (focusId sgr-a-star) drawn unconditionally by orbitTrailsLayer via the shared (hdr, NEAR0) step, region-culled on proximity to the GC = active exactly inside the band; hero scene, not edge case. +Ruling 9: adopt reviewer's Option A — band-gated step split (trails/glints move to a step emitted AFTER the lens step when band alpha > 0; outside the band the frame is byte-identical to today, no permanent extra pass) — as follow-up task T14b, dispatched now in this worktree. — Why: code already proves the defect; waiting for T17 to observe it wastes the gate. — Cost if wrong: one frameProgram diff. +T14b: implementer dispatched (sonnet, this worktree, Option A per Ruling 9; brief task-14b-brief.md). On its report: review loop → then T13b (awaiting user go on viewSlot shape) → T15 → T16 → T17. +Ruling 7 SETTLED BY USER ("t13b is go"): viewSlot shape — FrameContext.viewSlot (0=main, 1-6=faces), one helper owning slot mechanics (ring vs dynamic-offset hidden inside), 3 roster renderers adopt keyed on ctx.viewSlot (starCatalog cut streams get per-slot regions on the same key), skyCapture:true on the 4 roster rows, per-layer synthetic-ctx verification. Only roster renderers convert; planetRenderer et al migrate on contact. Brief REWRITTEN (task-13b-brief.md). Dispatch BLOCKED behind T14b (passes/index.ts collision) — dispatch immediately when T14b's fix loop closes. +T14b: implemented DONE (e3310f5ce directly on branch, pushed; tsc both configs + 7970 green (+3 new), headless clean ×2). Shape: ContentLayer.hdrPostLensing flag + FrameStep.lensPhase 'pre'|'post' + shared matchesLensPhase predicate (slabs.ts) read by BOTH executeFrame filter and frameProgram timing-slot derivation; renderStepTimingSlotName grew 3rd arg for post-slot uniqueness; outside-band identity pinned by assertion. Caveat: not pixel-verified (gate scenario frames were outside the band) — T17's job. Reviewer dispatched (sonnet; truth-table attention on matchesLensPhase incl. untagged-step case where trails/glints must still draw outside the band). +T13b: implementer dispatched IN PARALLEL (sonnet, isolation:worktree cut from MAIN — setup = git merge e3310f5ce + node_modules symlink; report lands in AGENT worktree; perf check skipped there by instruction). Cherry-pick to branch on report; watch passes/index.ts comment overlap with T14b at pick. +Task 14b: complete (e3310f5ce, review APPROVED both verdicts, no fix round — matchesLensPhase truth table hand-traced incl. untagged-step case, shared-predicate claim grep-confirmed, outside-band identity pinned twice (T7 golden literal + new assertion), flag exclusivity + static-slot uniqueness verified; nit on comment density accepted as house style). Awaiting T13b implementer only; then T13b review → T15 → T16 → T17. +Task 13c OPENED (user visual findings on the live annulus, pre-T17): (1) visible march stepping/banding, (2) no vertical scale-height falloff, (3) disk image not lensed (straight-ray march). Brief task-13c-brief.md prescribes: jittered march start + soft edges; exp(-(h/H)^2) vertical + inner-edge-bright radial profile; two-segment bent-ray march (kink at closest approach by LUT alpha(b), reusing the escape basis; budget split within 64 steps). No uniform growth unless unavoidable (T10 parity test). Implementer dispatched (sonnet, THIS worktree — disjoint from T13b's renderer files; told to ignore cross-worktree LSP bleed). T13b in flight in its isolated worktree (bleed-through diagnostics suggest it chose a uniform RING). +Research agent dispatched (user ask): performant Gargantua-style black-hole rendering survey (DNGR 2015, Bruneton 2020 deep-dive, Verbraeck/Eisemann mesh-warp, shadertoy/game/Unity implementations, sub-techniques: multi-image disk maps, bent-segment intersection, doppler delta^3/4 clamping, IGN/blue-noise, photon-ring fakes) → research-black-hole-rendering.md in SDD workspace, with an "applies to us" ranking vs our LUT+cubemap+march design. Findings inform T15 knobs / T17 judgment / possible follow-ups — NOT auto-scope; user decides what to adopt. +Research DONE → research-black-hole-rendering.md. Ranking: (1) soft-clamp doppler exponent (DNGR precedent — raw delta^3/4 kills one side); (2) IGN dither for march phase; (3) photon-ring rim glow from LUT slope near b_crit; (4) Bruneton multi-image disk via phi+m*pi branches (the actual doubled-disk Gargantua signature, medium complexity, extends LUT); (5) filtered star cubemap (not urgent); (6) full Bruneton U(e,phi) disk table REPLACING the march (150fps vs 45fps at quality — future spec); (7) V&E distortion grid (replaces solved problem, skip). DNGR visual importance: doubled disk > photon-ring stack > shadow shape > clamped beaming > bloom. Adoption = USER's call (items 1-3 cheap folds into T13c-review-round/T15; 4 = candidate follow-up task; 6 = backlog/spec candidate). BSD-3 (Bruneton) compatible with MIT — ATTRIBUTIONS.md entry only if code (not ideas) is copied; assets need separate check. +Task 13c: implemented DONE (46d779fa2, single file fragment.wesl, pushed; typecheck + 7970 green, headless clean). Reviewer dispatched (sonnet — math attention: kink direction/axis degeneracy, captured-sentinel never reaching rotation, jitter/segment coherence, disk-plane h). Sign/axis of lensing rotation = T17 caveat, ledgered. USER can eyeball at :5176 now (HMR). +Disk-math audit dispatched (OPUS, read-only, user: "disk doesnt really seem to be working well" post-T13c): independent derivation + comparison vs Bruneton 2020 paper/GLSL — LUT spot-checks, impact-parameter units, single-kink failure modes (infinity-LUT at finite distance, near-b_c spray, kink-after-disk), Keplerian doppler/shift factors, disk-basis handedness → audit-disk-math-vs-bruneton.md, findings ranked by likely visible symptom. T13c technical review ALSO still in flight (overlapping scope — reconcile both on return). +Task 13c: complete (46d779fa2, review PASS both verdicts, no fix round). Verified: coherent single-hash jitter, disk-plane h + DISK_SCALE_HEIGHT_RS=0.4, step-normalization brightness-invariant, sentinel never consumed (captured early-returns before deflectedDir), budget 24+24, single-file diff. Should-fixes adjudicated: (1) T17 checklist grows "judge bent-ray sign on the DISK march wrap-around, not only skybox" — ledgered here as T17 input; (2) report overstates captured-ray steps (48 vs actual 24, arguably more correct) — accepted as report-text inaccuracy, no code change, noted here as the correction of record. Bent-ray SIGN remains genuinely ambiguous absent reference derivation → audit-disk-math-vs-bruneton will settle it (in flight, now steered by user symptom "disc seems to be behind, not in front"). +Task 13b: implemented DONE_WITH_CONCERNS (agent wt commit b1300b23e → cherry-picked a99d2412a, clean pick, tsc + 418 targeted green, pushed). Helper = createViewSlotUniformRing (ring of per-slot buffers+bind groups; dynamic offsets rejected because shared BGLs — galaxyPickRenderer et al — would be forced to supply offsets). +16 tests (7986 in agent wt). Concerns: (1) BIGGEST REMAINING GAP — no per-face render-target VIEW resolved for capture steps (executeFrame never turns step.face into a single-layer attachment via cubeViewOf) — flagged, outside brief scope, reviewer confirming exact state, then fix round or T13d; (2) starPoint INSTANCE buffer also converted (same race — reviewer judging necessity); (3) starAggregates glow-floor viewport ref during capture (cosmetic). Reviewer dispatched (sonnet, review-46d779fa2..a99d2412a.diff 135KB). +AUDIT DONE (audit-disk-math-vs-bruneton.md): LUT + impact parameter CORRECT (no unit bug). Root cause of user symptom = FINDING #1: fragment.wesl:177 rotates by -bendAngle (away from hole) — confirmed vs Bruneton + analytic + numeric geodesic; far disk half never renders, sky lensing inverted. #3: b<1r_s branch skips march = black bite at front crossing. Deferred (pending user re-look after #1+#3): #4 doppler ^1-not-g^4 + inverted grav factor (81x vs 4x ratio), #5 1/r^2-not-Novikov-Thorne (no ISCO gap), #6 kink at closestT should be closestT + b*tan(alpha/2), #7 no azimuthal dependence (can't rotate), #8 step-vs-scale-height graininess + alpha max, #9 LUT texel density near b_c (Bruneton warps coords), #10 infinity-LUT invalid <50 r_s but floor allows 2 r_s (needs 2-D table = the future Bruneton-port spec, with #9). Fix round dispatched (resumed T13c implementer): flip sign + delete skip branch ONLY, then user re-looks. +Audit fix round DONE (0fe91316b on top of a99d2412a, pushed): bend sign flipped (toward hole), b<1r_s skip branch deleted; tsc + 60 focused green, headless clean. AWAITING USER RE-LOOK (both disk halves should render, far side arcing from behind shadow). Then adjudicate deferred audit findings #4-#9 (which fold into T15 vs follow-up task) + #10/#9 = future Bruneton-table spec candidate. T13b review still in flight. +Task 13b: review PASS/PASS (ring verified race-dead, viewSlot stamping complete, flags exactly 4 rows, starPoint instance split judged necessary-but-overprovisioned nit, helper header 26>10 accepted as utils/gpu house style). Should-fixes → fix round 1 dispatched (FRESH sonnet in this worktree): (1) layerViewOf(id, face) in renderTargets + executeFrame resolves capture-step attachment through it (today all faces write layer 0 via viewOf's multi-layer view) + distinct-view-per-face test; (2) starAggregatesLayer glow-floor viewport follows actual destination during capture. Nit (2-state cache) declined — over-optimization. +T13b fix round 1 DONE (315e89eb1 pushed; full suite 7988 green): layerViewOf(id,face) + executeFrame viewFor/renderGroup route step.face to per-layer attachment (distinctness test: 6 distinct views, none == shared viewOf); starAggregates glow-floor follows destination via ctx.viewSlot. Scoped re-review dispatched (haiku). USER RE-LOOK PENDING x2: (a) disk after sign flip, (b) cubemap orientation now that faces land on their own layers (user reported misorientation BEFORE this fix — likely the layer-0 collision; if still wrong after, probe per-face basis vs WGSL cube-sampling convention / Y-flip). +Task 13b: complete (b1300b23e→a99d2412a + fix 315e89eb1, re-review ALL ADDRESSED — 6-distinct-views test + capture glow-floor sizing verified). Capture pipeline now end-to-end: schedule → per-face ctx → race-free viewSlot writes → per-face attachments. Remaining before T15: user re-look x2 (disk sign flip; cubemap orientation post-layer-fix). Then: T15 knobs (+ any adopted audit findings #4-#9), T16 perf, T17. +USER RE-LOOK verdicts: DISK GOOD after sign flip. CUBEMAP still off — covers real stars with mismatched copies (wrong size/location), seems to scale on approach. ROOT CAUSE user-diagnosed + code-confirmed: capture eye = SGR_A_STAR_ANCHOR.positionMpc (renderFrame.ts:188), i.e. sky-as-seen-from-the-HOLE, sampled by direction from the CAMERA — near-field S-stars (AU distances) parallax-mismatch; escape-boundary can never be seamless. Ruling (with user): capture from CAMERA position (Bruneton-standard observer environment map; converges to seamless at deflection→0), + verify/wire movement escape-valve threshold (named constant, fraction of hole distance), near-plane re-check at floor. Fix round 2 dispatched (fresh sonnet, this worktree; fragment/LUT/renderers untouched; revert-pinning test on capture eye). +Capture-eye fix DONE (d15e95e9a pushed; full suite 7988 green, headless 9.1ms merged clean): eye = live camera; escape-valve threshold was WIRED but 10 AU ABSOLUTE (never fires near the 0.17 AU floor) → replaced with SKY_CUBEMAP_RECAPTURE_CAMERA_MOVE_FRACTION = 0.03 × live gcDistanceMpc; SKY_CAPTURE_NEAR_MPC kept (closest S-star periapsis ~45 AU >> 0.1 AU). Scoped re-review dispatched (haiku). USER THIRD LOOK PENDING: cubemap seam/orientation/parallax on approach. +Capture-eye fix re-review: ALL ADDRESSED (eye=ctx.drawCamPos pinned by 50-AU-offset test; fractional threshold units/edge cases verified; inactive band unchanged; 3 files, budget met). All review loops CLOSED. Sole pending: user third look (cubemap seam/parallax) → then T15 (knobs + adopted audit findings) → T16 perf → T17. +USER third look: flickering + visible cubemap face edges. Cause: live-eye captures make round-robin faces a 6-viewpoint patchwork (per-face parallax jump per frame; boundary disagreement). Ruling: PINNED stepped capture eye — all faces share one eye (stored in cameraRuntime.skyCubemapCapture); round-robin from pinned eye; displacement > 3%-of-gc-distance triggers full 6-face sweep at new eye + re-pin (generalize bandJustEngaged full-sweep trigger); per-face movement bookkeeping simplifies to one pinned-eye comparison (delete dead inputs). Fix round 3 dispatched (resumed capture-eye agent). +Fix round 3 DONE (cb06e62a8 pinned-eye + ebbf79e87 capture-always-clears, pushed; 7990 green, headless 11.5ms/31% headroom): all faces share one pinned eye (cameraRuntime), full sweep + re-pin on >3%-of-gc-distance displacement; capture steps force loadOp clear (touched is target-keyed, can't see layers — root cause of bright/dim alternation on multi-face frames). Scoped re-review dispatched (haiku). Bruneton repo CLONED to scratchpad (BSD-3; his sky cubemap = STATIC offline-baked 2048² Gaia bake — no runtime capture, no near-field content; design observation ledgered: split distant-sky [static, bake/capture-once] from S-stars [dynamic near-field] if flicker persists — checkpoint with user before acting). USER FOURTH LOOK PENDING. +T15 (knobs half) dispatched (sonnet, this worktree; user asked for collapsible debug section — this IS T15 pulled forward while re-review runs): ZoA-precedent section/container; Tier 1 = registry-fed uniform values (annulus radii, incl, PA, flicker, intensity/tint); Tier 2 = shader-local constants via TEMP uniform growth w/ parity-test lockstep (scale height, edge-fade fraction, doppler factor); non-uniform: recapture fraction + T8 glint tint. Removal step deferred to post-T17 per brief. Board/statusline update after it lands. +T15 addendum (user): cubemap default 256→512 + resolution knob 256/512/1024 in the debug section (live-rebuild only if an existing target-recreate seam supports it, else takes-effect-on-reload — no new architecture for a temp knob); grep stale 256 literals (starAggregates glow-floor sizing). 256-vs-512 ruling from spec era now settled by user eyeballing = bump. +Fix round 3 re-review: ALL ADDRESSED (pin lifecycle witnessed across renderFrame calls; both-faces-clear asserted; non-capture load-op untouched). Capture subsystem review-clean through ebbf79e87. In flight: T15 knobs (+cubemap 512 addendum). Pending: user look at stabilized sky; T16; T17. +T15 knobs DONE (f8701bf0a pushed; 7991 green, headless clean): Tier1 innerRs/outerRs/inclination/PA/flickerAmp/flickerTimescale (registry override at pack); Tier2 struct 144→160 (diskScaleHeightRs, edgeFadeStartFraction, dopplerStrength; parity test lockstep); non-uniform recapture fraction; cubemap default 512 + LIVE 256/512/1024 knob via existing reconcile() rebuild seam. SKIPPED: glint tint knob (would need state threading through pure shared helper + fixture expansion — beyond surgical bound; glint judged at T17 by one-literal edit if needed). Reviewer dispatched (sonnet — attention: parity lockstep byte-walk, silent no-op knobs, default identity, resize stale-view/recapture, temp markers). REMOVAL step pends post-T17. +T15 review: APPROVED both verdicts, 1 should-fix (SgrAStarLensingTuning.d.ts header 29>10 — folded into the in-flight follow-up round) + nit (brief's "glow-floor sizing" concern = no real mechanism, confirmed grep). Verified: precedent fidelity, 144→160 lockstep byte-walk, no no-op knobs, default identity (only cubemap 256→512 changed), resize rebuild traced no-stale-view w/ new reallocate-rebind test, glint skip real. Follow-up round in flight (same agent): 2048 option + emission strength slider (160→176 or padding, default-identical) + optional tint + header trim. +Cubemap-alignment audit dispatched on FABLE (explicit user override of the never-Fable subagent norm; user: "still not aligned with the actual view"): full capture→sample chain derivation — face bases vs GL/WebGPU (s,t) table, render-to-texture Y orientation, sample-direction space vs slab RTC basis, WGSL cube handedness, 3 explicit identity walks (star direction → sampler face/s/t vs capture face/pixel). Read-only diagnosis FIRST; capture-side fix preferred; fragment.wesl edits forbidden if T15 agent has it dirty (concurrent); ambiguity → hypotheses + discriminating probe, no guessing. → audit-cubemap-alignment.md. T15 follow-up round (2048/strength/tint/header) mid-edit per LSP bleed. +COMPACT CHECKPOINT — in flight x2 + handling: (1) T15 follow-up agent (2048 option + emissionStrength/emissionTint knobs + d.ts header trim; tree currently carries its WIP edits) → on report: push, verify gates, note in T15 review record, scoped re-check only if diff surprises; (2) FABLE cubemap-alignment auditor → on report: if fixed, push + user re-look; if hypotheses, run its discriminating probe. QUEUED after both: user tunes knobs → T15 removal step (bake literals, delete section, restore 144B parity or keep tuned fields — decide at bake) → T16 perf (SAME flags: npm run -s perf -- --url http://localhost:5176 --frames 30, vs perf-baseline-0b1787ae4.txt) → T17 user gate (incl. bent-ray sign on DISK march, glint tint, cubemap res judgment). Audit findings #4-#9 adoption = user decision pending. Bruneton clone in scratchpad (session-lifetime; re-clone if gone). HEAD f8701bf0a + agent WIP; all pushed through f8701bf0a. +T15 follow-up DONE (276130d7f pushed; full suite 7991 green): 2048 option (no other clamp; maxTextureDimension2D 8192 covers), emissionStrength 0-8 linear (SliderField has no log option — noted) + emissionTint colour picker (struct 160→176, parity lockstep, exact no-op defaults, applied to summed output so alpha unscaled), d.ts header 29→9. Adjudication: NO separate re-review — the added fields repeat the mechanism the T15 review already byte-walked, and the parity test + full suite gate the drift failure mode; review record notes it. Remaining in flight: FABLE alignment auditor only. +FABLE ALIGNMENT AUDIT: defect UNAMBIGUOUS — every captured face vertically mirrored (v = 1-t): FACE_UP table is the GL cube-capture table, upright only under GL's bottom-left origin; WebGPU rasterizes top-left, and cube (s,t) is a MIRROR of any right-handed capture basis so no rotation could fix it (T11's desk review validated vs LearnOpenGL = wrong API origin — lesson: convention approvals must name the origin). Rest of chain verified clean (face select, s, layers, pinned eye, world-axes sampling, slab = translation-only identity, no z-flip). FIXED capture-side 65d84a151 (flipClipY negates clip-Y row of every capture vp; roster is cull-free points so winding harmless; fragment untouched), per-face identity test MUTATION-VERIFIED, full suite 7992 green, pushed. USER LOOK: alignment should now be exact at fade boundary. +USER after Y-flip: definitely better; residual = fade-ring edge doesn't fully line up. FABLE auditor RESUMED with hypothesis to verify quantitatively: fade band [35,50] r_s still carries 2.3-3.3 deg deflection — blending shifted sky into true sky = structural ring mismatch. Expected fix (agent verifies first): analytic weak-field tail alpha=2/b beyond LUT + fade re-keyed to subpixel deflection (derive b threshold from fov/viewport; check quad sizing reaches that radius; annulus/roster untouched; LUT-endpoint continuity CPU-testable). On report: push + user re-look. +Edge-ring fix CONFIRMED+LANDED (Fable, 576a636c9 pushed; full suite 7993 green, WESL link clean): hypothesis verified — 39-56 px ghost at fade ring (offset/ring-radius ~0.94, scale-free). Fix: 1/b weak-field tail endpoint*(lutMax/b) exactly continuous at b=50 (raw 2/b would jump 3% — LUT endpoint carries 15pi/16b^2 correction; continuity pinned by CPU test); fade re-keyed to per-frame uniform edgeFadeEndRs = max(lutMax, min(2*drawPxPerRad, 0.6*distRs)) in former _pad4 (176B unchanged); quad sized to cover fade end (was 75 r_s, would clip); march gated off b>outerRs+4 (output-identical). Residual: subpixel beyond 265 AU, ~2.6px at 100 AU. TRADE ledgered: inside ~150 AU the cubemap region ~fills the screen → resolution knob (512 default) is the sharpness lever; judge at T17. USER LOOK PENDING. +USER: edge fade "a lot better"; NEW finding — lens POPS IN at ~341 AU (~4020 r_s, bandAlpha ~0.4 already) instead of fading from the 500 AU band edge. Prime suspect: body-m slab birth (pixel-size candidacy) trips INSIDE the band → first draw at nonzero alpha. FABLE resumed: pin the gate (derive slab-birth distance from anchor candidacy rule + user's viewport), fix with structural preference = band-bearing anchor's slab candidacy keyed to its band's outer edge (born at alpha=0), fallback = extra distance ramp (must justify); slab-at-band-edge headless test. On report: push + user re-look. +Pop-in PINNED+FIXED (Fable, 4ea8a0705 pushed; 7994 green, WESL link clean): derived slab birth = 1px disc cull at 346.0 AU for user viewport — user's pop at 341.3 AU (1.4% inside), bandAlpha 0.397 = exact magnitude match; threshold viewport/dpr-dependent (dpr1 → 173 AU / alpha 0.82) → structural fix chosen. Fix: BAND_SLAB_FLOOR_MPC registry in visibleSlabBodies (Sgr A* → band goneAt); band-bearing lens body stays slab-candidate through the band's whole support, bypassing pixel floor AND frustum cull (valid: painted footprint = lens quad up to ~0.75x camera distance, not the disc). Slab+lens step born at alpha=0, keyed to the SAME band row the layer reads (can't drift). Off-axis kept-at-400/dropped-at-600 test mutation-verified. Suspicion 2 cleared (capture keys on bandActive distance, swept pre-birth). USER RE-LOOK PENDING (smooth fade-in from 500 AU). +USER: LMC/SMC/Andromeda (textured galaxy quads) vanish inside the lens — capture-roster gap (thumbnail/imageQuad layer never flagged skyCapture). Roster-addition agent dispatched (sonnet, this worktree): identify layer, run T13b's two checks (writeBuffer race → viewSlot ring conversion if needed; synthetic-ctx compat — watch apparent-size/demand gating + viewport-derived sizing in a 90deg/512px face), flag skyCapture:true, race test per pattern; STOP on design-needing findings. → task-13b-roster-addition-report.md. On report: push, note in review record (mechanism previously reviewed; scoped re-check only if conversion nontrivial), user re-look. +USER RULING: cubemap default = 1024 (512 "simply too little" after live judgment; supersedes the 512 bump). T15 agent resumed for the lockstep default change (defaults.ts + renderTargets literal + any 512-pinning test); told to git-status-check around the concurrently-running roster-addition agent. VRAM at 1024 ≈ 50 MB — fine. T16 perf note: capture cost now 4x per face vs original 256 baseline era — watch the sky-cubemap rows in the re-measure. +1024 default DONE (760e72a41 pushed): defaults.ts literal + renderTargets comment; verified no other 512 pin (fixtures spread the DEFAULT constant). NOTE: T15 agent claimed roster-agent commits landed in between — FALSE per git log (tip sequence 65d84a151→576a636c9→4ea8a0705→760e72a41, no roster commit); roster-addition agent still in flight, do not double-dispatch. +USER: shaking of cubemap+disc at close orbit, INTRODUCED BY LAST FIX (= 4ea8a0705 slab band floor prime suspect; 576a636c9 second). Both-shake ⇒ shared basis (slab vp/uniform), not capture. FABLE resumed: hypotheses = slab-index/ordering instability from unconditional candidacy (frame-to-frame BODY[k] reassignment while orbiting), band-floor path computing slab center/vp via different precision path, else edge-fade/quad per-frame smoothness; headless orbit-pose sequence diff recommended as decisive probe. Roster-addition agent STILL in flight same worktree — Fable told to avoid its dirty files. On report: push + user re-look. +USER RULING: Sgr A* focus arrival distance = 1.2493572557676555e-11 Mpc ≈ 30.4 r_s (user-framed live view; shadow ~10deg at 60deg fov). Agent dispatched (sonnet, 3rd parallel — camera/focus seam, expressed as r_s multiple via existing per-body seam or minimal registry-row override beside standoffRadii; floor untouched; git-status hygiene vs 2 concurrent agents). In flight x3: Fable shake regression, roster addition, focus distance. +Shake regression PINNED+FIXED (Fable, 8ea687011 pushed): cause = 576a636c9's in-shader quad sizing (4ea8a0705 exonerated — disc 41-204px at 20-100 r_s so bypass no-op there; lens selects slab by frame.bodyId never index). Mechanism: close-in edgeFadeEndRs floors at lutMax≥distRs → max(d²-fade², 1e-6) bottoms → quad inflates to 1e6 r_s at 20 r_s → 5e4 corner/centre varying ratio → ~3mrad (~6px) barycentric noise on every ray, requantized per orbit frame (sky+disc together). Fix: inversion moved CPU-side f64 (utils/lensing/lensQuadPlaneRadiusRs.ts), capped 8x anchor distance (83deg half-angle; cap only where full fade coverage geometrically impossible — 100-500 AU views unchanged); ships in last pad slot quadPlaneRadiusRs byte 172 (176B intact). Tests: exact inversion + cap + <1%-step smoothness across d=50 crossover (fails on revert); parity lockstep. Suite 8004/8005 — single failure = roster agent's dirty texturedDiskRenderer tree (verified not Fable's; expect roster commit to green it). USER RE-LOOK on shake pending; roster + focus agents still in flight. +Focus distance DONE (365489044 pushed; camera+engine suites 2172 green): AnchorPointBody.focusDistanceRadii optional override (mirrors standoffRadii pattern) threaded through SelectionRow/extractSelectionRow → bodyLikeFraming; SGR_A_STAR = 30.4 → arrival 30.4 r_s FOV-independent; floor untouched; override-not-nudge pinned by test. LAST in flight: roster addition (textured galaxies). +Roster addition LANDED (2c63b9a34 — agent stalled AFTER committing; watchdog killed it mid-report): textured-disks layer flagged skyCapture. Controller verified gates itself: tsc clean, frame+gpu 1150 green, FULL suite 8010/8010 green (the earlier 8004/8005 failure was this agent's then-dirty tree — now green). Pushed. Report file may be missing/partial — diff inspected via git show instead. ZERO agents in flight. Pending user verdicts: close-orbit shake re-look, LMC/SMC/Andromeda visible+lensed, smooth fade-in, 1024 sharpness, 30.4 r_s focus arrival. Then: tune → bake+delete knobs (T15 removal) → T16 perf (same flags vs baseline) → T17. +USER TUNED VALUES (accumulate for the T15 bake step — do NOT bake piecemeal): inclinationRad = 0.35 (≈ registry original 20deg, confirmed), positionAngleRad = 2.21 (≈126.7deg, CHANGED from 0.785/45deg). Awaiting further knob verdicts (strength, tint, scale height, doppler, edge fade, annulus radii, flicker, recapture fraction, cubemap res already ruled 1024) before the bake+delete commit pair. +USER: Andromeda not lensed. Two-part answer: (a) physics — visible lensing needs near-alignment behind the shadow (subpixel deflection degrees away = correct); (b) REAL FLAW found — texturedDisksLayer.draw renders subsystem lastOutput.disks computed for the LIVE MAIN camera; capture faces reuse it → main-frustum-culled/mis-oriented disks on faces looking elsewhere (the synthetic-ctx check the stalled agent never reported). Fix agent dispatched (sonnet): determine lastOutput's camera deps, capture-appropriate disk set ONCE PER SWEEP from pinned eye (not per face), no renderer fork, behind-main-camera-disk-included test, STOP if subsystem contract must restructure. Also to write the missing roster-addition report incl. 2c63b9a34 rationale. +Andromeda follow-up REFUTED the lastOutput hypothesis (eab5878cb test-only, pushed; 8011 green): diskPlannerWalk gates on camera POSITION only (squared distance + apparent px) — no frustum/orientation cull exists; no DiskInstance field is orientation-dependent; M31 ≈48px from BOTH Sun and GC vantage on production bin. Behind-camera-admission invariant now pinned by mutation-verified test. Capture drew non-empty (0.3ms textured-disks in headless check). REMAINING explanations for "not lensed": (a) physics — needs near-alignment behind shadow (user experiment suggested); (b) if aligned & still rigid: next links = escape-ray sampling of the disks' cubemap content near the ring, or atlas-slot contention at GC LOD. AWAITING user alignment verdict before further dispatch. + +## 2026-09-02 — Andromeda "not lensed": user push-back REFINES diagnosis (capture draw, not planner) +User two-pose evidence: M31 visible at distanceMpc 2.78e-9 (~573 AU, band alpha~0, DIRECT sky) but gone at 4.67e-10 (~96 AU, band fully engaged, sky = cubemap through lens). So the disk survives the direct path and dies exactly at the direct→captured handoff — the cubemap does NOT contain the textured disks, despite skyCapture:true (2c63b9a34). Ruled out by derivation this session: planner admission (position-only, list reused verbatim), fadeAlpha (smoothstep on apparent px × load fade — identical at both poses, M31 is 0.78 Mpc away), near plane (0.1 AU), far plane (fixed FAR_CLIP_MPC=50000 rides into face ctx). Live suspects, in order: (1) texturedDiskRenderer pipeline depth-state vs depthless sky-cubemap pass (validation-killed draw); (2) instancedQuadRenderer per-viewSlot ring mis-wired (default slot count / slot not selected → faces draw with MAIN vp); (3) capture step slab-filtering skipping the COSMO-slab disks layer; (4) blend/format mismatch vs rgba16float. Opus investigator dispatched (fix+test+commit if unambiguous, report otherwise) → report at task-disks-in-capture-report.md. Handling: on result, verify gates, push, ask user to re-check M31 at the same two poses. + +## 2026-09-02 — ROOT CAUSE FOUND + FIXED: capture always-clear was per-step, not per-face +Investigator (opus) proved none of my top suspects: frameProgram emits TWO capture steps per face (COSMO then NEAR0, frameProgram.ts:168-171) since the skyCapture roster spans both slabs; ebbf79e87's blanket "capture steps always clear" made the NEAR0 star step CLEAR the face the COSMO step had just drawn — textured disks AND galaxy point sprites silently wiped from every face; only stars survived. Main view unaffected (live hdr steps use the normal touched set). Fix c9362d940 (PUSHED): private per-executeFrame touchedFaces set keyed target:face; ctx.renderedTargets stays bare-target-keyed (public surface). Test: same-face second step loads / first clears (fails pre-fix) + different-faces both-clear retained. Gates: tsc clean (controller re-verified), 8012 green, headless free of pipeline errors. NOT empirically confirmed in-band (perf scenario never enters band) — AWAITING user eyeball at the two poses (573 AU / 96 AU); restored galaxy point sprites ride the same eyeball. Report: task-disks-in-capture-report.md. + +## 2026-09-02 — Ruling 10 (USER): tuning section SHIPS with this PR +User: "lets leave the tuning section in for this PR" — overrides T15's planned removal step (bake+delete). Consequences: SgrAStarLensingTuningSection + container + settings type + 176 B uniform fields all stay; no refactor-delete pass; TEMPORARY framing in comments should be softened to match reality before final review. Baking is REDUCED to: write the user's final tuned values into BLACK_HOLES/defaults so shipped defaults match the tuned look (0.35 inclination / 2.21 PA already ledgered; more values may follow). Remaining pipeline unchanged: user eyeball of capture fix c9362d940 → finish tuning → bake defaults commit → T16 perf gate → T17 visual gate → final review. + +## 2026-09-02 — Tuned defaults BAKED: 5a5d57e2b (pushed) +inclinationRad Math.PI/9→0.35, positionAngleRad Math.PI/4→2.21 in src/data/blackHoles.ts — the sole literal source; defaults.ts + settings initialState derive from BLACK_HOLES (no edits needed, no drift possible). No tests pinned old literals. Gates: tsc clean, 8012 green. Ruling 10 stands (tuning section ships). STILL AWAITING: user eyeball of capture fix c9362d940 (M31 at 573→96 AU) + any further tuned knob values → then T16 perf gate → T17 visual gate → final whole-branch review. + +## 2026-09-02 — LANDING PIPELINE STARTED (user: "land this asap"; capture fix ATTESTED) +User confirmed M31 + other galaxies now show through the lens (c9362d940 visually attested). New user finding backlogged, NOT blocking: band-crossfade shows subtle duplicate points (direct sky + lensed cubemap both partially visible on the ramp) → docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md, committed 0ff24ed8f (pushed). IN FLIGHT, parallel: (a) T16 perf after-run `npm run -s perf -- --url http://localhost:5176 --frames 30` → perf-after-c9362d940.txt, compare vs perf-baseline-0b1787ae4.txt (MERGED medians, ~0.5ms noise; regression outside band or unbounded inside HALTS — user ruling required); (b) final whole-branch review (opus) over review-0b1787ae4..0ff24ed8f.diff → final-review-report.md (verdict APPROVE/FIX-FIRST). THEN: fix round if needed → deletion-audit → /feature-done → PR off branch. T17 user visual gate: much already attested live this session; confirm shadow/ring/doppler checklist with user at PR time. + +## 2026-09-02 — T16 first after-run CONTAMINATED, discarded +Run overlapped the opus whole-branch review agent on the same machine: deltas vs baseline swing both ways on untouched scenarios (milky-way-outside +20.2ms, local-group −9.0ms, star-field −6.0ms) with p90 46–125ms — machine-load noise, not signal (harness noise spec ~0.5ms). Kept as perf-after-c9362d940.CONTAMINATED.txt; verdict INVALID, neither pass nor halt. Re-run with identical flags once the review agent completes and the box is idle. + +## 2026-09-02 — FINAL REVIEW VERDICT: FIX-FIRST (0 crit / 4 major / 16 minor / 3 nit) → ONE fix dispatch IN FLIGHT +Report: final-review-report.md (also records what was verified CLEAN — uniform layout, outside-band identity, race fixes, Y-flip, NaN, formats — don't re-derive). Perf re-run STOPPED mid-flight (would have measured pre-fix HEAD; T16 runs ONCE on the final tip after fixes, on an idle box). Controller rulings for the fix round (all spec-enforcement or report-recommended, no new design): M1=lazy-allocate sky-cubemap row (spec's zero-cost-outside-band binding; renderer/LUT stays boot-eager, documented); M2=propagate Ruling 10 incl. spec §Settings + plan GC/T15 amendments; M3=option (a) knee on capture-face aggregates (fallback (b) document+suspect if impossible); M4+m11+m13=comment trim keeping landmines; m1–m15+n1–n3 per report Fix lines (m3 named bag, m4 SIM clock, m6 drop fake-generic loop); m16=no code, T17 checklist addition (judge Milky-Way discontinuity at lens quad rim). Opus fix agent dispatched → final-fix-round-report.md. THEN: scoped re-review of fix diff → T16 perf on final tip (VRAM note per M1) → deletion-audit → /feature-done → PR. + +## 2026-09-02 — FIX ROUND COMPLETE (5 commits, pushed thru a69293b08) → scoped re-review IN FLIGHT +All 23 findings implemented: 7bfb81e2d (Ruling-10 docs), 9e57a2574 (M1 lazy sky-cubemap: allocateWhen predicate, release-on-false in reconcile, band-edge reconcile in renderFrame — 0 B outside band, dealloc on exit; renderer/LUT boot-eager documented), 82e8e0fce (M3(a): knee flag on draw args, knee = leaf || viewSlot!==0, pipelines keyed by compression), 326d5223f (minors m1–m15+n1–n3; m4 got f64 [0,2π) phase wrap — raw sim-clock phase ~1e9 rad would freeze in f32), a69293b08 (M4 comment trim; lensQuadPlaneRadiusRs 0.86 ratio kept as documented deviation — all landmine). Gates: tsc clean, 8016 green (+4 real tests), headless clean. Implementer concerns logged: frameIndex now advances in-band only (re-review checks consumers); repo-wide `npm run format` accident mid-round (claims restored — re-review verifies no strays); T16 must carry VRAM line (50 MB in-band @1024 / 201 MB @2048 / 0 outside); T17 checklist adds capture-face knee eyeball + MW discontinuity at quad rim. Scoped re-review (opus) over review-0ff24ed8f..a69293b08.diff → final-re-review-report.md. THEN: T16 perf on idle box (final tip) → deletion-audit → /feature-done → PR. + +## 2026-09-02 — RE-REVIEW: 21/23 ADDRESSED, risky fixes all verified; residual cleanup dispatched +final-re-review-report.md: risky fixes clean (lazy-row edge ordering, knee slot-0 bit-identical, m4 wrap safe, frameIndex in-band-only unobservable — sole consumer is the %6 round-robin, m7 slots agree, all landmines survived trim; no prettier strays). Residuals → sonnet cleanup agent (adjudicated by controller, verified by controller on return — no further review round): (1) NEW-1 hysteresis RULING: row must-exist when fadeBand>0, kept until dist > 1.5×goneAt, then released (named factor + test); (2) plan text: :1029 tuning-removal wording, T17 checklist += MW-at-quad-rim + capture-knee eyeball, T16 += VRAM line (0/50MB@1024/201MB@2048); (3) remaining Ruling-N (4 sites) + ~14 Task-N cites → timeless wording; (4) starCatalog pipeline labels by knee not stream; (5) renderFrame.test.ts stale "every frame regardless of band" wording. THEN: controller verifies diff + gates, push → T16 perf (idle box, final tip) → deletion-audit → /feature-done → PR. + +## 2026-09-02 — Residual cleanup LANDED 7e4c170d7 (pushed); T16 perf RUNNING on final tip +Controller verified hysteresis diff: allocateWhen(state, isAllocated) — keep while bandActive, else isAllocated && gcDistance <= 1.5×goneAt (SKY_CUBEMAP_ROW_RELEASE_MARGIN); gcDistanceMpc recorded unconditionally on capture runtime; sizes.has = allocated signal. Note: renderTargets.ts (gpu) now imports SCALE_FADE_BANDS from services/engine/presentation — covered by existing backlog item scale-fade-bands-to-data, no action. All 6 residuals closed; 8017 green. Perf: perf-after-7e4c170d7.txt vs perf-baseline-0b1787ae4.txt, MERGED medians, ~0.5 ms noise; nothing else running on the box. VRAM line for report: sky-cubemap 0 B outside band / 50 MB in-band @1024 / 201 MB @2048 knob. THEN: deletion-audit → /feature-done → PR. + +## 2026-09-02 — T16 PERF GATE MEASURED (report: task-16-perf-report.md) +Full-suite after-run showed uniform +2–7 ms incl. earth-surface (no BH code path) — every slot ×1.4, same shares, no new slot = clock drift. Paired A/B (base 0b1787ae4 scratch worktree on :5199 vs branch :5176, A-B-A-B): earth-surface + milky-way NEUTRAL; galactic-centre +1.2 ms consistent but diffuse across untouched slots (volume, bloom), no new slot → not attributable, reported plainly. In-band: NEW permanent scenario sgr-a-star-lens (96 AU, user pose; e7096abe7 pushed) = 16.1 ms merged (~62 fps) vs ~10–11 outside; one face/frame (COSMO ~3.1 + NEAR0 ~1.2 @1024²), lens 0.7 ms, post-lensing 0.6. VRAM: 0 B outside / 50 MB in-band @1024 / 201 MB @2048. VERDICT: outside neutral, inside bounded — LAND ruling is the user's. Scratch worktree at scratchpad/perf-base + vite :5199 still up → remove at teardown. NEXT: deletion-audit → /feature-done → PR (T17 checklist confirm with user at PR time). + +## 2026-09-02 — deletion-audit IN FLIGHT (opus, GREENFIELD+LEGACY framing); A/B scaffolding torn down +Scratch worktree perf-base + vite :5199 REMOVED. Audit over audit-0b1787ae4..e7096abe7.diff → deletion-audit-whole-branch.md; fenced: tuning section ships, viewSlot seam, all user-observed-defect fixes, deferred physics, correctness already reviewed; adjudicates extraRows candidate. Handling: triage per leanness.md — apply mechanical/zero-behaviour deletions in one commit; behaviour/debug-surface items = user ruling in the landing message. THEN /feature-done → PR. + +## 2026-09-02 — deletion-audit RESULT: 16 candidates, ~337 LOC (80 src/257 tests) — branch lean; apply-agent IN FLIGHT +Report deletion-audit-whole-branch.md. Controller triage per leanness.md: APPLY (zero-behaviour, sonnet agent, one commit) = #1 pack test file, #3 extraRows (DEAD confirmed — lives in createRenderTargets not frameProgram), #5 flickerTimescaleS dead uniform → _pad0 (offsets unchanged), #6 slotCount override, #7 zeroPadFields, #8-#11 mirror tests, #14 map-of-one (only if pure repr), #15 two unused exports. PARKED for USER ruling: #2 staleness escape valve (audit: unreachable; controller: reachable only after >2 s stall e.g. hidden tab, then 1-frame full resweep vs 6-frame round-robin — marginal), #4 recaptureCameraMoveFraction knob row (debug surface). KEEP: #12 presence throw, #13 BLACK_HOLES registry-of-one (seam), #16 ledger-speak (already swept). THEN: /feature-done → PR; landing message carries: perf ruling, #2/#4 rulings, T17 checklist confirm. + +## 2026-09-02 — /feature-done AUDIT RUN: all mechanical axes clean; NOT READY only on user gates +Deletion commit 8abd7ac1e pushed (−274 LOC; #7 skipped as mutually exclusive with #5 — zeroPadFields now live for _pad0). DoD audit (sonnet): tests 8011 PASS, tsc PASS, 0 new TODOs, 0 smells, parity OK (+0..+51%), no backlog straggler, ~55 unplanned files all traceable to Rulings 4–10, untouched none. Hygiene miss: plan checkboxes 0/126 → ticked T1–T16 in 2c991ff4e (pushed); T17's 9 boxes left for USER. PR #645 (was docs-only) REWRITTEN as the feature PR + converted to DRAFT: https://github.com/rulkens/skymap/pull/645. AWAITING USER: (1) T16 land ruling (neutral/bounded); (2) T17 checklist attestation (5 spec items + MW-at-rim + capture knee); (3) deletion-audit parked #2 (staleness valve) / #4 (recapture-fraction knob). ON ATTESTATION: tick T17, git mv plan+spec → completed/, archive this ledger → docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md, commit `docs(plan): mark render-black-hole complete`, push, undraft PR; then wt-close after merge. Memory file project_render_black_hole.md is STALE — update at landing. diff --git a/docs/superpowers/plans/2026-09-01-render-black-hole.md b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md similarity index 98% rename from docs/superpowers/plans/2026-09-01-render-black-hole.md rename to docs/superpowers/plans/completed/2026-09-01-render-black-hole.md index 69213ce882..c53a615c3e 100644 --- a/docs/superpowers/plans/2026-09-01-render-black-hole.md +++ b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md @@ -1,6 +1,6 @@ # Render Sgr A* Black Hole Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. This plan follows `docs/superpowers/conventions/plan-style.md` — contract code (signatures, test names+assertions, byte tables) yes, implementation bodies no. +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking. This plan follows `docs/superpowers/conventions/plan-style.md` — contract code (signatures, test names+assertions, byte tables) yes, implementation bodies no. **Goal:** Render a physically-grounded Schwarzschild close-up of Sgr A* inside a new `sgrAStarLensing` fade band (500→100 AU), with a far-field warm-orange @@ -1058,26 +1058,26 @@ gate). **Steps:** -- [ ] With the dev server running and the feature complete, focus Sgr A* and +- [x] With the dev server running and the feature complete, focus Sgr A* and descend into the lensing band. Verify, with the user, EACH of the spec's five checklist items verbatim: - - [ ] shadow diameter reads as ~5.2 r_s (the EHT-consistent apparent size); - - [ ] an Einstein ring is visible on background stars crossing near the + - [x] shadow diameter reads as ~5.2 r_s (the EHT-consistent apparent size); + - [x] an Einstein ring is visible on background stars crossing near the shadow; - - [ ] doppler asymmetry favours the correct side of the annulus (the + - [x] doppler asymmetry favours the correct side of the annulus (the approaching material's side, given the chosen inclination/position angle); - - [ ] the fade band crossfades without a pop at either edge; - - [ ] the far-field glint hands off to the close-up without a visible seam. -- [ ] Also judge two items outside the spec's original five, added by the fix + - [x] the fade band crossfades without a pop at either edge; + - [x] the far-field glint hands off to the close-up without a visible seam. +- [x] Also judge two items outside the spec's original five, added by the fix round's re-review: the Milky-Way discontinuity at the lens quad's rim (the MW cloud is deliberately not in the capture roster, so its edge against the captured sky can show a seam), and the capture-face aggregate knee (relabelled kneed/un-kneed this round — never eyeballed before this gate). -- [ ] Report the outcome per item. Any failing item is a STOP — fix and +- [x] Report the outcome per item. Any failing item is a STOP — fix and re-gate, not a partial ship. -- [ ] Only once every item passes AND Task 16's perf gate is clean does this +- [x] Only once every item passes AND Task 16's perf gate is clean does this plan's feature work count as ready for `/feature-done`. --- diff --git a/docs/superpowers/specs/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md similarity index 100% rename from docs/superpowers/specs/2026-09-01-render-black-hole-design.md rename to docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md From 000650722fe2f244d34068f227541c04883fb0f9 Mon Sep 17 00:00:00 2001 From: Alexander Rulkens Date: Wed, 2 Sep 2026 02:45:32 +0200 Subject: [PATCH 60/60] style: prettier over the black-hole branch's touched files Co-Authored-By: Claude Fable 5 --- .../render-black-hole-2026-09-01.md | 32 ++--- .../2026-09-01-render-black-hole.ledger.md | 44 +++++-- .../completed/2026-09-01-render-black-hole.md | 121 ++++++++++-------- .../2026-09-01-render-black-hole-design.md | 20 +-- src/utils/physics/schwarzschildRadiusM.ts | 2 +- 5 files changed, 128 insertions(+), 91 deletions(-) diff --git a/docs/grill-sessions/render-black-hole-2026-09-01.md b/docs/grill-sessions/render-black-hole-2026-09-01.md index d115771119..aeb5572d2e 100644 --- a/docs/grill-sessions/render-black-hole-2026-09-01.md +++ b/docs/grill-sessions/render-black-hole-2026-09-01.md @@ -1,21 +1,21 @@ -# Grill Session: Rendering Sgr A* (black-hole close-up) — 2026-09-01 +# Grill Session: Rendering Sgr A\* (black-hole close-up) — 2026-09-01 -Source: live brainstorming session, pivoting from a Gaia-data research question ("what's near the GC?") to the deliberate follow-up the S-star spec deferred: giving Sgr A* a visual treatment. Prior art surveyed: PR #365 `feat/gravitational-lensing` (cluster lensing). +Source: live brainstorming session, pivoting from a Gaia-data research question ("what's near the GC?") to the deliberate follow-up the S-star spec deferred: giving Sgr A\* a visual treatment. Prior art surveyed: PR #365 `feat/gravitational-lensing` (cluster lensing). -Goal: when the camera descends past the S-stars onto Sgr A*, show a physically-grounded black-hole close-up — shadow, photon ring, gravitationally lensed background — instead of today's nothing. +Goal: when the camera descends past the S-stars onto Sgr A\*, show a physically-grounded black-hole close-up — shadow, photon ring, gravitationally lensed background — instead of today's nothing. Context findings that framed the session (Explore survey of main @ 9dce415f4): -- Sgr A* ships as an `AnchorPointBody` (position, label, real Schwarzschild radius 12.69×10⁶ km ≈ 0.085 AU) that deliberately draws nothing; the S-star spec's non-goals name "black disc, lensing, photon ring" as a dedicated follow-up — this feature. +- Sgr A\* ships as an `AnchorPointBody` (position, label, real Schwarzschild radius 12.69×10⁶ km ≈ 0.085 AU) that deliberately draws nothing; the S-star spec's non-goals name "black disc, lensing, photon ring" as a dedicated follow-up — this feature. - The scale ladder already reaches it: focus + per-body standoff + NEAR0 adaptive frustum let the camera descend to ~1× r_s today. - PR #365 (SIS/NFW cluster lensing, 40 commits, June 2026) is **template, not base**: different feature (background galaxies lensed by clusters, vertex-stage thin-lens), ~53-file conflicts after the `galaxyCatalog/` shader reorg, 257 commits stale. Reusable ideas: two-vec4 lens uniform pattern, precompute-a-LUT-instead-of-per-vertex-root-finding. -- Landmine: backlog item `2026-07-30-camera-target-vs-origin-distance-gates.md` names Sgr A* as the first case where origin-relative NEAR0 gate derivation diverges from target-relative reads. +- Landmine: backlog item `2026-07-30-camera-target-vs-origin-distance-gates.md` names Sgr A\* as the first case where origin-relative NEAR0 gate derivation diverges from target-relative reads. --- ## Q1: Visual ambition -**The question:** What should "rendering Sgr A*" deliver when the camera approaches — how big is this feature? +**The question:** What should "rendering Sgr A\*" deliver when the camera approaches — how big is this feature? **Considerations:** @@ -27,15 +27,15 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): ## Q2: Physical honesty of the emission -**The question:** Sgr A* is quiescent — no bright Interstellar-style accretion disc exists in reality. How honest is the close-up? +**The question:** Sgr A\* is quiescent — no bright Interstellar-style accretion disc exists in reality. How honest is the close-up? **Considerations:** - **Option A (honest quiescent):** shadow + photon ring + lensed starfield only. Fully defensible; relies on lensing alone for spectacle. - **Option B (cinematic disc):** glowing doppler-beamed disc. Spectacular but fictional for this object; large extra shader surface. -- **Option C (faint EHT-style glow):** honest scene plus a dim ring-hugging emission matched to the EHT Sgr A* image geometry. Small addition; keeps the "this is what it looks like" claim defensible with a documented false-colour note. +- **Option C (faint EHT-style glow):** honest scene plus a dim ring-hugging emission matched to the EHT Sgr A\* image geometry. Small addition; keeps the "this is what it looks like" claim defensible with a documented false-colour note. -**Decision:** **Faint EHT-style glow (C).** Middle path: the glow marks the object from afar and gives the lensing something to act on, while staying anchored to a real measurement. Noted honestly: at visual wavelengths Sgr A* is dark — EHT orange is 230 GHz false colour, so the glow is documented artistic licence. +**Decision:** **Faint EHT-style glow (C).** Middle path: the glow marks the object from afar and gives the lensing something to act on, while staying anchored to a real measurement. Noted honestly: at visual wavelengths Sgr A\* is dark — EHT orange is 230 GHz false colour, so the glow is documented artistic licence. ## Q3: Lensing technique @@ -56,7 +56,7 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): **Considerations:** - **Option A (Schwarzschild):** no spin. Closed-form-ish deflection, 1D LUT, simple shadow geometry. -- **Option B (Kerr):** spin adds frame-dragging asymmetry — but Sgr A*'s spin magnitude/orientation are poorly constrained, geodesics need a 4D LUT or full integration everywhere, and the shadow-shape difference is a few percent. +- **Option B (Kerr):** spin adds frame-dragging asymmetry — but Sgr A\*'s spin magnitude/orientation are poorly constrained, geodesics need a 4D LUT or full integration everywhere, and the shadow-shape difference is a few percent. **Decision:** **Schwarzschild (A).** We don't know the spin, so Kerr would be heavy machinery in service of an unverifiable claim; the doppler asymmetry people actually notice comes from disc-material motion, modelled regardless. @@ -73,12 +73,12 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): ## Q6: Activation envelope and far-field presence -**The question:** When does the expensive pass run, and what exists at Sgr A* before it engages? +**The question:** When does the expensive pass run, and what exists at Sgr A\* before it engages? **Considerations:** - **Empty far field (status quo):** nothing until the pass engages — the object pops into existence. -- **Far-field glint + fade band:** a faint orange point-glint at the anchor from afar (the real compact source), crossfading into the geodesic pass via the existing `SCALE_FADE_BANDS` mechanism keyed on distance to the Sgr A* anchor (the same pattern the GC Milky-Way fade shipped on in #642). +- **Far-field glint + fade band:** a faint orange point-glint at the anchor from afar (the real compact source), crossfading into the geodesic pass via the existing `SCALE_FADE_BANDS` mechanism keyed on distance to the Sgr A\* anchor (the same pattern the GC Milky-Way fade shipped on in #642). **Decision:** **Glint + fade band**, roughly engage ≤ 500 AU → fully on by ~100 AU (the shadow is subpixel until a few hundred AU, conveniently inside the S-star cluster scale). Pass cost is exactly zero outside the band. @@ -86,7 +86,7 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): **The question:** What emission model, and does it vary in time? -**Considerations:** thin equatorial annulus at ~3–6 r_s (ISCO outward → the ~5 r_s lensed ring the EHT measured), Keplerian doppler brightening on the approaching side, near face-on viewing (EHT constrains inclination ≲ 30°), warm orange, calibrated fainter than the S-stars. Position angle unconstrained observationally — pick one and note it. Variability: Sgr A* flickers on minute timescales (its EHT image needed variability correction); options were skip (less shader surface) vs include minimally. +**Considerations:** thin equatorial annulus at ~3–6 r_s (ISCO outward → the ~5 r_s lensed ring the EHT measured), Keplerian doppler brightening on the approaching side, near face-on viewing (EHT constrains inclination ≲ 30°), warm orange, calibrated fainter than the S-stars. Position angle unconstrained observationally — pick one and note it. Variability: Sgr A\* flickers on minute timescales (its EHT image needed variability correction); options were skip (less shader surface) vs include minimally. **Decision:** annulus model as above, **flicker included, minimally** — one global sim-clock-driven brightness modulation, no patch structure. @@ -105,7 +105,7 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): **The question:** Any settings — toggle, strength slider? -**Considerations:** PR #365 had a `lensStrength` slider because cluster lensing at physical 1× is invisible; here physical 1× *is* the show. A toggle would exist only as a perf escape hatch, but the pass is already proximity-gated to ~zero cost elsewhere. +**Considerations:** PR #365 had a `lensStrength` slider because cluster lensing at physical 1× is invisible; here physical 1× _is_ the show. A toggle would exist only as a perf escape hatch, but the pass is already proximity-gated to ~zero cost elsewhere. **Decision:** **Zero new settings.** Physically parameterized from the shipped anchor body (mass → r_s). Dev tuning through the existing debug panel, removed before merge. Code-is-liability default. @@ -123,7 +123,7 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): ## Q11: Sequencing — park on the body slab -**The question:** Ground prep was about to include a precision/gate probe (AU-scale scene 8.2 kpc from render origin ≈ f32 epsilon territory; the target-vs-origin NEAR0 gate item names Sgr A* as first victim). But a **body slab** is being implemented in another worktree (riding the Earth RTC camera effort) — probe now, or wait? +**The question:** Ground prep was about to include a precision/gate probe (AU-scale scene 8.2 kpc from render origin ≈ f32 epsilon territory; the target-vs-origin NEAR0 gate item names Sgr A\* as first victim). But a **body slab** is being implemented in another worktree (riding the Earth RTC camera effort) — probe now, or wait? **Considerations:** @@ -136,6 +136,6 @@ Context findings that framed the session (Explore survey of main @ 9dce415f4): ## Resume checklist (when the body slab lands) -1. Probe: focus Sgr A*, force distance to ~2 r_s, observe jitter / frustum / S-star sprite stability under the new slab. +1. Probe: focus Sgr A\*, force distance to ~2 r_s, observe jitter / frustum / S-star sprite stability under the new slab. 2. Run `refactor-ground`; decide whether `docs/backlog/2026-07-30-camera-target-vs-origin-distance-gates.md` becomes prep inside this feature. 3. Write the spec from this transcript (decisions Q1–Q10 are settled; don't re-litigate without new evidence). diff --git a/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md index 628ce8935a..27ade847e4 100644 --- a/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md +++ b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md @@ -8,16 +8,16 @@ User rulings from checkpoint: prep = SEPARATE PR; scope = Phase A first. Shared-file / interface pairs checked: -| Tasks | Shared surface | Finding | -|---|---|---| -| T1+T2 | `AnchorPointBody.d.ts` (docblock vs `standoffRadii` field) | Sequential edits, no conflict | -| T2+T5 | `sceneSgrAStar.ts` (standoffRadii vs radiusM swap) | Sequential, disjoint lines | -| T1+T12 | `frameProgram.ts` (capacity const vs 4th param) | Different phases, sequential | -| T3+T11 | `RenderTargetSpec.fixedSizePx` producer/consumer | Signatures match (`{size, layers}`) | -| T7+T8+T13 | `SCALE_FADE_BANDS.sgrAStarLensing` producer/consumers | Name + AU→Mpc consistent | -| T9+T10+T13 | LUT type → uniform metadata → texture upload | Field names consistent | -| T11+T12 | `CubeFace` producer/consumer | Consistent | -| T13+T14 | layer registration vs reorder | Explicit hand-off in both tasks | +| Tasks | Shared surface | Finding | +| ----------- | --------------------------------------------------------------------------------- | ----------------------------------- | +| T1+T2 | `AnchorPointBody.d.ts` (docblock vs `standoffRadii` field) | Sequential edits, no conflict | +| T2+T5 | `sceneSgrAStar.ts` (standoffRadii vs radiusM swap) | Sequential, disjoint lines | +| T1+T12 | `frameProgram.ts` (capacity const vs 4th param) | Different phases, sequential | +| T3+T11 | `RenderTargetSpec.fixedSizePx` producer/consumer | Signatures match (`{size, layers}`) | +| T7+T8+T13 | `SCALE_FADE_BANDS.sgrAStarLensing` producer/consumers | Name + AU→Mpc consistent | +| T9+T10+T13 | LUT type → uniform metadata → texture upload | Field names consistent | +| T11+T12 | `CubeFace` producer/consumer | Consistent | +| T13+T14 | layer registration vs reorder | Explicit hand-off in both tasks | | T15+T16+T17 | tuning knobs used at T17, removed in T15's final step; T16 measures after removal | Interleaved by design; see Ruling 2 | Per-task self-consistency: T1-T3, T5-T14 internally consistent (tests match code contracts, file lists complete). T4/T16/T17 are manual gates with no file edits — consistent. T6 has no test by design (testing.md registry rule) — consistent with conventions. @@ -29,6 +29,7 @@ Rulings at pre-flight: - Ruling 3: No harness todo tool exists in this session; Rule 1's visible task list is satisfied by the user-requested Artifact task board + this ledger. — Cost if wrong: none material. ## Progress + Task 1: implemented (commit b2dcb9b4b, BASE f60ba2b0e), suite 7843 green, typecheck clean; review dispatched Task 3: implementer dispatched pipelined (files disjoint from T1); T2 queued behind T1 review (shares AnchorPointBody.d.ts) Note: stale-LSP diagnostics on visibleSlabBodies.test.ts observed post-T1; real tsc clean (verified in controller) @@ -55,6 +56,7 @@ Prep PR OPENED: #649 (prep-black-hole-ground, draft; cherry-picks b0166ca27..ee7 PHASE B GATED on #649 merge; next after merge = Ruling 2 perf baseline, then Task 4 probe (user-attested) ## Open thread: standoffRadii wiring rework (user directive 2026-09-01) + USER IS NOT HAPPY with T2's 9-file two-lane threading (pivotRadiusMpc + pivotStandoffRadii in parallel) — second-special-case trigger. Explore agent IN FLIGHT mapping the lane (question: does any orbit-controls-lane consumer need radius AND standoff separately, or is floor-at-source viable?). HANDLING PLAN for its result: present user a priced choice — (a) thread single precomputed pivotFloorMpc from extractSelectionRow (deletes second lane; lean if radius has no other lane consumer) vs (b) one {radiusMpc, standoffRadii} bundle. Rework rides PR #649 as a P2 rework commit (still draft, cheap). Do NOT merge #649 until this is settled. Dev server: http://localhost:5176 shell bn6iz5dyv (this worktree; 5173-5175 = other worktrees). @@ -151,14 +153,14 @@ COMPACT CHECKPOINT — in flight x2 + handling: (1) T15 follow-up agent (2048 op T15 follow-up DONE (276130d7f pushed; full suite 7991 green): 2048 option (no other clamp; maxTextureDimension2D 8192 covers), emissionStrength 0-8 linear (SliderField has no log option — noted) + emissionTint colour picker (struct 160→176, parity lockstep, exact no-op defaults, applied to summed output so alpha unscaled), d.ts header 29→9. Adjudication: NO separate re-review — the added fields repeat the mechanism the T15 review already byte-walked, and the parity test + full suite gate the drift failure mode; review record notes it. Remaining in flight: FABLE alignment auditor only. FABLE ALIGNMENT AUDIT: defect UNAMBIGUOUS — every captured face vertically mirrored (v = 1-t): FACE_UP table is the GL cube-capture table, upright only under GL's bottom-left origin; WebGPU rasterizes top-left, and cube (s,t) is a MIRROR of any right-handed capture basis so no rotation could fix it (T11's desk review validated vs LearnOpenGL = wrong API origin — lesson: convention approvals must name the origin). Rest of chain verified clean (face select, s, layers, pinned eye, world-axes sampling, slab = translation-only identity, no z-flip). FIXED capture-side 65d84a151 (flipClipY negates clip-Y row of every capture vp; roster is cull-free points so winding harmless; fragment untouched), per-face identity test MUTATION-VERIFIED, full suite 7992 green, pushed. USER LOOK: alignment should now be exact at fade boundary. USER after Y-flip: definitely better; residual = fade-ring edge doesn't fully line up. FABLE auditor RESUMED with hypothesis to verify quantitatively: fade band [35,50] r_s still carries 2.3-3.3 deg deflection — blending shifted sky into true sky = structural ring mismatch. Expected fix (agent verifies first): analytic weak-field tail alpha=2/b beyond LUT + fade re-keyed to subpixel deflection (derive b threshold from fov/viewport; check quad sizing reaches that radius; annulus/roster untouched; LUT-endpoint continuity CPU-testable). On report: push + user re-look. -Edge-ring fix CONFIRMED+LANDED (Fable, 576a636c9 pushed; full suite 7993 green, WESL link clean): hypothesis verified — 39-56 px ghost at fade ring (offset/ring-radius ~0.94, scale-free). Fix: 1/b weak-field tail endpoint*(lutMax/b) exactly continuous at b=50 (raw 2/b would jump 3% — LUT endpoint carries 15pi/16b^2 correction; continuity pinned by CPU test); fade re-keyed to per-frame uniform edgeFadeEndRs = max(lutMax, min(2*drawPxPerRad, 0.6*distRs)) in former _pad4 (176B unchanged); quad sized to cover fade end (was 75 r_s, would clip); march gated off b>outerRs+4 (output-identical). Residual: subpixel beyond 265 AU, ~2.6px at 100 AU. TRADE ledgered: inside ~150 AU the cubemap region ~fills the screen → resolution knob (512 default) is the sharpness lever; judge at T17. USER LOOK PENDING. +Edge-ring fix CONFIRMED+LANDED (Fable, 576a636c9 pushed; full suite 7993 green, WESL link clean): hypothesis verified — 39-56 px ghost at fade ring (offset/ring-radius ~0.94, scale-free). Fix: 1/b weak-field tail endpoint*(lutMax/b) exactly continuous at b=50 (raw 2/b would jump 3% — LUT endpoint carries 15pi/16b^2 correction; continuity pinned by CPU test); fade re-keyed to per-frame uniform edgeFadeEndRs = max(lutMax, min(2*drawPxPerRad, 0.6*distRs)) in former \_pad4 (176B unchanged); quad sized to cover fade end (was 75 r_s, would clip); march gated off b>outerRs+4 (output-identical). Residual: subpixel beyond 265 AU, ~2.6px at 100 AU. TRADE ledgered: inside ~150 AU the cubemap region ~fills the screen → resolution knob (512 default) is the sharpness lever; judge at T17. USER LOOK PENDING. USER: edge fade "a lot better"; NEW finding — lens POPS IN at ~341 AU (~4020 r_s, bandAlpha ~0.4 already) instead of fading from the 500 AU band edge. Prime suspect: body-m slab birth (pixel-size candidacy) trips INSIDE the band → first draw at nonzero alpha. FABLE resumed: pin the gate (derive slab-birth distance from anchor candidacy rule + user's viewport), fix with structural preference = band-bearing anchor's slab candidacy keyed to its band's outer edge (born at alpha=0), fallback = extra distance ramp (must justify); slab-at-band-edge headless test. On report: push + user re-look. Pop-in PINNED+FIXED (Fable, 4ea8a0705 pushed; 7994 green, WESL link clean): derived slab birth = 1px disc cull at 346.0 AU for user viewport — user's pop at 341.3 AU (1.4% inside), bandAlpha 0.397 = exact magnitude match; threshold viewport/dpr-dependent (dpr1 → 173 AU / alpha 0.82) → structural fix chosen. Fix: BAND_SLAB_FLOOR_MPC registry in visibleSlabBodies (Sgr A* → band goneAt); band-bearing lens body stays slab-candidate through the band's whole support, bypassing pixel floor AND frustum cull (valid: painted footprint = lens quad up to ~0.75x camera distance, not the disc). Slab+lens step born at alpha=0, keyed to the SAME band row the layer reads (can't drift). Off-axis kept-at-400/dropped-at-600 test mutation-verified. Suspicion 2 cleared (capture keys on bandActive distance, swept pre-birth). USER RE-LOOK PENDING (smooth fade-in from 500 AU). USER: LMC/SMC/Andromeda (textured galaxy quads) vanish inside the lens — capture-roster gap (thumbnail/imageQuad layer never flagged skyCapture). Roster-addition agent dispatched (sonnet, this worktree): identify layer, run T13b's two checks (writeBuffer race → viewSlot ring conversion if needed; synthetic-ctx compat — watch apparent-size/demand gating + viewport-derived sizing in a 90deg/512px face), flag skyCapture:true, race test per pattern; STOP on design-needing findings. → task-13b-roster-addition-report.md. On report: push, note in review record (mechanism previously reviewed; scoped re-check only if conversion nontrivial), user re-look. USER RULING: cubemap default = 1024 (512 "simply too little" after live judgment; supersedes the 512 bump). T15 agent resumed for the lockstep default change (defaults.ts + renderTargets literal + any 512-pinning test); told to git-status-check around the concurrently-running roster-addition agent. VRAM at 1024 ≈ 50 MB — fine. T16 perf note: capture cost now 4x per face vs original 256 baseline era — watch the sky-cubemap rows in the re-measure. 1024 default DONE (760e72a41 pushed): defaults.ts literal + renderTargets comment; verified no other 512 pin (fixtures spread the DEFAULT constant). NOTE: T15 agent claimed roster-agent commits landed in between — FALSE per git log (tip sequence 65d84a151→576a636c9→4ea8a0705→760e72a41, no roster commit); roster-addition agent still in flight, do not double-dispatch. USER: shaking of cubemap+disc at close orbit, INTRODUCED BY LAST FIX (= 4ea8a0705 slab band floor prime suspect; 576a636c9 second). Both-shake ⇒ shared basis (slab vp/uniform), not capture. FABLE resumed: hypotheses = slab-index/ordering instability from unconditional candidacy (frame-to-frame BODY[k] reassignment while orbiting), band-floor path computing slab center/vp via different precision path, else edge-fade/quad per-frame smoothness; headless orbit-pose sequence diff recommended as decisive probe. Roster-addition agent STILL in flight same worktree — Fable told to avoid its dirty files. On report: push + user re-look. -USER RULING: Sgr A* focus arrival distance = 1.2493572557676555e-11 Mpc ≈ 30.4 r_s (user-framed live view; shadow ~10deg at 60deg fov). Agent dispatched (sonnet, 3rd parallel — camera/focus seam, expressed as r_s multiple via existing per-body seam or minimal registry-row override beside standoffRadii; floor untouched; git-status hygiene vs 2 concurrent agents). In flight x3: Fable shake regression, roster addition, focus distance. +USER RULING: Sgr A\* focus arrival distance = 1.2493572557676555e-11 Mpc ≈ 30.4 r_s (user-framed live view; shadow ~10deg at 60deg fov). Agent dispatched (sonnet, 3rd parallel — camera/focus seam, expressed as r_s multiple via existing per-body seam or minimal registry-row override beside standoffRadii; floor untouched; git-status hygiene vs 2 concurrent agents). In flight x3: Fable shake regression, roster addition, focus distance. Shake regression PINNED+FIXED (Fable, 8ea687011 pushed): cause = 576a636c9's in-shader quad sizing (4ea8a0705 exonerated — disc 41-204px at 20-100 r_s so bypass no-op there; lens selects slab by frame.bodyId never index). Mechanism: close-in edgeFadeEndRs floors at lutMax≥distRs → max(d²-fade², 1e-6) bottoms → quad inflates to 1e6 r_s at 20 r_s → 5e4 corner/centre varying ratio → ~3mrad (~6px) barycentric noise on every ray, requantized per orbit frame (sky+disc together). Fix: inversion moved CPU-side f64 (utils/lensing/lensQuadPlaneRadiusRs.ts), capped 8x anchor distance (83deg half-angle; cap only where full fade coverage geometrically impossible — 100-500 AU views unchanged); ships in last pad slot quadPlaneRadiusRs byte 172 (176B intact). Tests: exact inversion + cap + <1%-step smoothness across d=50 crossover (fails on revert); parity lockstep. Suite 8004/8005 — single failure = roster agent's dirty texturedDiskRenderer tree (verified not Fable's; expect roster commit to green it). USER RE-LOOK on shake pending; roster + focus agents still in flight. Focus distance DONE (365489044 pushed; camera+engine suites 2172 green): AnchorPointBody.focusDistanceRadii optional override (mirrors standoffRadii pattern) threaded through SelectionRow/extractSelectionRow → bodyLikeFraming; SGR_A_STAR = 30.4 → arrival 30.4 r_s FOV-independent; floor untouched; override-not-nudge pinned by test. LAST in flight: roster addition (textured galaxies). Roster addition LANDED (2c63b9a34 — agent stalled AFTER committing; watchdog killed it mid-report): textured-disks layer flagged skyCapture. Controller verified gates itself: tsc clean, frame+gpu 1150 green, FULL suite 8010/8010 green (the earlier 8004/8005 failure was this agent's then-dirty tree — now green). Pushed. Report file may be missing/partial — diff inspected via git show instead. ZERO agents in flight. Pending user verdicts: close-orbit shake re-look, LMC/SMC/Andromeda visible+lensed, smooth fade-in, 1024 sharpness, 30.4 r_s focus arrival. Then: tune → bake+delete knobs (T15 removal) → T16 perf (same flags vs baseline) → T17. @@ -167,43 +169,57 @@ USER: Andromeda not lensed. Two-part answer: (a) physics — visible lensing nee Andromeda follow-up REFUTED the lastOutput hypothesis (eab5878cb test-only, pushed; 8011 green): diskPlannerWalk gates on camera POSITION only (squared distance + apparent px) — no frustum/orientation cull exists; no DiskInstance field is orientation-dependent; M31 ≈48px from BOTH Sun and GC vantage on production bin. Behind-camera-admission invariant now pinned by mutation-verified test. Capture drew non-empty (0.3ms textured-disks in headless check). REMAINING explanations for "not lensed": (a) physics — needs near-alignment behind shadow (user experiment suggested); (b) if aligned & still rigid: next links = escape-ray sampling of the disks' cubemap content near the ring, or atlas-slot contention at GC LOD. AWAITING user alignment verdict before further dispatch. ## 2026-09-02 — Andromeda "not lensed": user push-back REFINES diagnosis (capture draw, not planner) + User two-pose evidence: M31 visible at distanceMpc 2.78e-9 (~573 AU, band alpha~0, DIRECT sky) but gone at 4.67e-10 (~96 AU, band fully engaged, sky = cubemap through lens). So the disk survives the direct path and dies exactly at the direct→captured handoff — the cubemap does NOT contain the textured disks, despite skyCapture:true (2c63b9a34). Ruled out by derivation this session: planner admission (position-only, list reused verbatim), fadeAlpha (smoothstep on apparent px × load fade — identical at both poses, M31 is 0.78 Mpc away), near plane (0.1 AU), far plane (fixed FAR_CLIP_MPC=50000 rides into face ctx). Live suspects, in order: (1) texturedDiskRenderer pipeline depth-state vs depthless sky-cubemap pass (validation-killed draw); (2) instancedQuadRenderer per-viewSlot ring mis-wired (default slot count / slot not selected → faces draw with MAIN vp); (3) capture step slab-filtering skipping the COSMO-slab disks layer; (4) blend/format mismatch vs rgba16float. Opus investigator dispatched (fix+test+commit if unambiguous, report otherwise) → report at task-disks-in-capture-report.md. Handling: on result, verify gates, push, ask user to re-check M31 at the same two poses. ## 2026-09-02 — ROOT CAUSE FOUND + FIXED: capture always-clear was per-step, not per-face + Investigator (opus) proved none of my top suspects: frameProgram emits TWO capture steps per face (COSMO then NEAR0, frameProgram.ts:168-171) since the skyCapture roster spans both slabs; ebbf79e87's blanket "capture steps always clear" made the NEAR0 star step CLEAR the face the COSMO step had just drawn — textured disks AND galaxy point sprites silently wiped from every face; only stars survived. Main view unaffected (live hdr steps use the normal touched set). Fix c9362d940 (PUSHED): private per-executeFrame touchedFaces set keyed target:face; ctx.renderedTargets stays bare-target-keyed (public surface). Test: same-face second step loads / first clears (fails pre-fix) + different-faces both-clear retained. Gates: tsc clean (controller re-verified), 8012 green, headless free of pipeline errors. NOT empirically confirmed in-band (perf scenario never enters band) — AWAITING user eyeball at the two poses (573 AU / 96 AU); restored galaxy point sprites ride the same eyeball. Report: task-disks-in-capture-report.md. ## 2026-09-02 — Ruling 10 (USER): tuning section SHIPS with this PR + User: "lets leave the tuning section in for this PR" — overrides T15's planned removal step (bake+delete). Consequences: SgrAStarLensingTuningSection + container + settings type + 176 B uniform fields all stay; no refactor-delete pass; TEMPORARY framing in comments should be softened to match reality before final review. Baking is REDUCED to: write the user's final tuned values into BLACK_HOLES/defaults so shipped defaults match the tuned look (0.35 inclination / 2.21 PA already ledgered; more values may follow). Remaining pipeline unchanged: user eyeball of capture fix c9362d940 → finish tuning → bake defaults commit → T16 perf gate → T17 visual gate → final review. ## 2026-09-02 — Tuned defaults BAKED: 5a5d57e2b (pushed) + inclinationRad Math.PI/9→0.35, positionAngleRad Math.PI/4→2.21 in src/data/blackHoles.ts — the sole literal source; defaults.ts + settings initialState derive from BLACK_HOLES (no edits needed, no drift possible). No tests pinned old literals. Gates: tsc clean, 8012 green. Ruling 10 stands (tuning section ships). STILL AWAITING: user eyeball of capture fix c9362d940 (M31 at 573→96 AU) + any further tuned knob values → then T16 perf gate → T17 visual gate → final whole-branch review. ## 2026-09-02 — LANDING PIPELINE STARTED (user: "land this asap"; capture fix ATTESTED) + User confirmed M31 + other galaxies now show through the lens (c9362d940 visually attested). New user finding backlogged, NOT blocking: band-crossfade shows subtle duplicate points (direct sky + lensed cubemap both partially visible on the ramp) → docs/backlog/2026-09-02-lens-crossfade-duplicate-points.md, committed 0ff24ed8f (pushed). IN FLIGHT, parallel: (a) T16 perf after-run `npm run -s perf -- --url http://localhost:5176 --frames 30` → perf-after-c9362d940.txt, compare vs perf-baseline-0b1787ae4.txt (MERGED medians, ~0.5ms noise; regression outside band or unbounded inside HALTS — user ruling required); (b) final whole-branch review (opus) over review-0b1787ae4..0ff24ed8f.diff → final-review-report.md (verdict APPROVE/FIX-FIRST). THEN: fix round if needed → deletion-audit → /feature-done → PR off branch. T17 user visual gate: much already attested live this session; confirm shadow/ring/doppler checklist with user at PR time. ## 2026-09-02 — T16 first after-run CONTAMINATED, discarded + Run overlapped the opus whole-branch review agent on the same machine: deltas vs baseline swing both ways on untouched scenarios (milky-way-outside +20.2ms, local-group −9.0ms, star-field −6.0ms) with p90 46–125ms — machine-load noise, not signal (harness noise spec ~0.5ms). Kept as perf-after-c9362d940.CONTAMINATED.txt; verdict INVALID, neither pass nor halt. Re-run with identical flags once the review agent completes and the box is idle. ## 2026-09-02 — FINAL REVIEW VERDICT: FIX-FIRST (0 crit / 4 major / 16 minor / 3 nit) → ONE fix dispatch IN FLIGHT + Report: final-review-report.md (also records what was verified CLEAN — uniform layout, outside-band identity, race fixes, Y-flip, NaN, formats — don't re-derive). Perf re-run STOPPED mid-flight (would have measured pre-fix HEAD; T16 runs ONCE on the final tip after fixes, on an idle box). Controller rulings for the fix round (all spec-enforcement or report-recommended, no new design): M1=lazy-allocate sky-cubemap row (spec's zero-cost-outside-band binding; renderer/LUT stays boot-eager, documented); M2=propagate Ruling 10 incl. spec §Settings + plan GC/T15 amendments; M3=option (a) knee on capture-face aggregates (fallback (b) document+suspect if impossible); M4+m11+m13=comment trim keeping landmines; m1–m15+n1–n3 per report Fix lines (m3 named bag, m4 SIM clock, m6 drop fake-generic loop); m16=no code, T17 checklist addition (judge Milky-Way discontinuity at lens quad rim). Opus fix agent dispatched → final-fix-round-report.md. THEN: scoped re-review of fix diff → T16 perf on final tip (VRAM note per M1) → deletion-audit → /feature-done → PR. ## 2026-09-02 — FIX ROUND COMPLETE (5 commits, pushed thru a69293b08) → scoped re-review IN FLIGHT + All 23 findings implemented: 7bfb81e2d (Ruling-10 docs), 9e57a2574 (M1 lazy sky-cubemap: allocateWhen predicate, release-on-false in reconcile, band-edge reconcile in renderFrame — 0 B outside band, dealloc on exit; renderer/LUT boot-eager documented), 82e8e0fce (M3(a): knee flag on draw args, knee = leaf || viewSlot!==0, pipelines keyed by compression), 326d5223f (minors m1–m15+n1–n3; m4 got f64 [0,2π) phase wrap — raw sim-clock phase ~1e9 rad would freeze in f32), a69293b08 (M4 comment trim; lensQuadPlaneRadiusRs 0.86 ratio kept as documented deviation — all landmine). Gates: tsc clean, 8016 green (+4 real tests), headless clean. Implementer concerns logged: frameIndex now advances in-band only (re-review checks consumers); repo-wide `npm run format` accident mid-round (claims restored — re-review verifies no strays); T16 must carry VRAM line (50 MB in-band @1024 / 201 MB @2048 / 0 outside); T17 checklist adds capture-face knee eyeball + MW discontinuity at quad rim. Scoped re-review (opus) over review-0ff24ed8f..a69293b08.diff → final-re-review-report.md. THEN: T16 perf on idle box (final tip) → deletion-audit → /feature-done → PR. ## 2026-09-02 — RE-REVIEW: 21/23 ADDRESSED, risky fixes all verified; residual cleanup dispatched + final-re-review-report.md: risky fixes clean (lazy-row edge ordering, knee slot-0 bit-identical, m4 wrap safe, frameIndex in-band-only unobservable — sole consumer is the %6 round-robin, m7 slots agree, all landmines survived trim; no prettier strays). Residuals → sonnet cleanup agent (adjudicated by controller, verified by controller on return — no further review round): (1) NEW-1 hysteresis RULING: row must-exist when fadeBand>0, kept until dist > 1.5×goneAt, then released (named factor + test); (2) plan text: :1029 tuning-removal wording, T17 checklist += MW-at-quad-rim + capture-knee eyeball, T16 += VRAM line (0/50MB@1024/201MB@2048); (3) remaining Ruling-N (4 sites) + ~14 Task-N cites → timeless wording; (4) starCatalog pipeline labels by knee not stream; (5) renderFrame.test.ts stale "every frame regardless of band" wording. THEN: controller verifies diff + gates, push → T16 perf (idle box, final tip) → deletion-audit → /feature-done → PR. ## 2026-09-02 — Residual cleanup LANDED 7e4c170d7 (pushed); T16 perf RUNNING on final tip + Controller verified hysteresis diff: allocateWhen(state, isAllocated) — keep while bandActive, else isAllocated && gcDistance <= 1.5×goneAt (SKY_CUBEMAP_ROW_RELEASE_MARGIN); gcDistanceMpc recorded unconditionally on capture runtime; sizes.has = allocated signal. Note: renderTargets.ts (gpu) now imports SCALE_FADE_BANDS from services/engine/presentation — covered by existing backlog item scale-fade-bands-to-data, no action. All 6 residuals closed; 8017 green. Perf: perf-after-7e4c170d7.txt vs perf-baseline-0b1787ae4.txt, MERGED medians, ~0.5 ms noise; nothing else running on the box. VRAM line for report: sky-cubemap 0 B outside band / 50 MB in-band @1024 / 201 MB @2048 knob. THEN: deletion-audit → /feature-done → PR. ## 2026-09-02 — T16 PERF GATE MEASURED (report: task-16-perf-report.md) + Full-suite after-run showed uniform +2–7 ms incl. earth-surface (no BH code path) — every slot ×1.4, same shares, no new slot = clock drift. Paired A/B (base 0b1787ae4 scratch worktree on :5199 vs branch :5176, A-B-A-B): earth-surface + milky-way NEUTRAL; galactic-centre +1.2 ms consistent but diffuse across untouched slots (volume, bloom), no new slot → not attributable, reported plainly. In-band: NEW permanent scenario sgr-a-star-lens (96 AU, user pose; e7096abe7 pushed) = 16.1 ms merged (~62 fps) vs ~10–11 outside; one face/frame (COSMO ~3.1 + NEAR0 ~1.2 @1024²), lens 0.7 ms, post-lensing 0.6. VRAM: 0 B outside / 50 MB in-band @1024 / 201 MB @2048. VERDICT: outside neutral, inside bounded — LAND ruling is the user's. Scratch worktree at scratchpad/perf-base + vite :5199 still up → remove at teardown. NEXT: deletion-audit → /feature-done → PR (T17 checklist confirm with user at PR time). ## 2026-09-02 — deletion-audit IN FLIGHT (opus, GREENFIELD+LEGACY framing); A/B scaffolding torn down + Scratch worktree perf-base + vite :5199 REMOVED. Audit over audit-0b1787ae4..e7096abe7.diff → deletion-audit-whole-branch.md; fenced: tuning section ships, viewSlot seam, all user-observed-defect fixes, deferred physics, correctness already reviewed; adjudicates extraRows candidate. Handling: triage per leanness.md — apply mechanical/zero-behaviour deletions in one commit; behaviour/debug-surface items = user ruling in the landing message. THEN /feature-done → PR. ## 2026-09-02 — deletion-audit RESULT: 16 candidates, ~337 LOC (80 src/257 tests) — branch lean; apply-agent IN FLIGHT -Report deletion-audit-whole-branch.md. Controller triage per leanness.md: APPLY (zero-behaviour, sonnet agent, one commit) = #1 pack test file, #3 extraRows (DEAD confirmed — lives in createRenderTargets not frameProgram), #5 flickerTimescaleS dead uniform → _pad0 (offsets unchanged), #6 slotCount override, #7 zeroPadFields, #8-#11 mirror tests, #14 map-of-one (only if pure repr), #15 two unused exports. PARKED for USER ruling: #2 staleness escape valve (audit: unreachable; controller: reachable only after >2 s stall e.g. hidden tab, then 1-frame full resweep vs 6-frame round-robin — marginal), #4 recaptureCameraMoveFraction knob row (debug surface). KEEP: #12 presence throw, #13 BLACK_HOLES registry-of-one (seam), #16 ledger-speak (already swept). THEN: /feature-done → PR; landing message carries: perf ruling, #2/#4 rulings, T17 checklist confirm. + +Report deletion-audit-whole-branch.md. Controller triage per leanness.md: APPLY (zero-behaviour, sonnet agent, one commit) = #1 pack test file, #3 extraRows (DEAD confirmed — lives in createRenderTargets not frameProgram), #5 flickerTimescaleS dead uniform → \_pad0 (offsets unchanged), #6 slotCount override, #7 zeroPadFields, #8-#11 mirror tests, #14 map-of-one (only if pure repr), #15 two unused exports. PARKED for USER ruling: #2 staleness escape valve (audit: unreachable; controller: reachable only after >2 s stall e.g. hidden tab, then 1-frame full resweep vs 6-frame round-robin — marginal), #4 recaptureCameraMoveFraction knob row (debug surface). KEEP: #12 presence throw, #13 BLACK_HOLES registry-of-one (seam), #16 ledger-speak (already swept). THEN: /feature-done → PR; landing message carries: perf ruling, #2/#4 rulings, T17 checklist confirm. ## 2026-09-02 — /feature-done AUDIT RUN: all mechanical axes clean; NOT READY only on user gates -Deletion commit 8abd7ac1e pushed (−274 LOC; #7 skipped as mutually exclusive with #5 — zeroPadFields now live for _pad0). DoD audit (sonnet): tests 8011 PASS, tsc PASS, 0 new TODOs, 0 smells, parity OK (+0..+51%), no backlog straggler, ~55 unplanned files all traceable to Rulings 4–10, untouched none. Hygiene miss: plan checkboxes 0/126 → ticked T1–T16 in 2c991ff4e (pushed); T17's 9 boxes left for USER. PR #645 (was docs-only) REWRITTEN as the feature PR + converted to DRAFT: https://github.com/rulkens/skymap/pull/645. AWAITING USER: (1) T16 land ruling (neutral/bounded); (2) T17 checklist attestation (5 spec items + MW-at-rim + capture knee); (3) deletion-audit parked #2 (staleness valve) / #4 (recapture-fraction knob). ON ATTESTATION: tick T17, git mv plan+spec → completed/, archive this ledger → docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md, commit `docs(plan): mark render-black-hole complete`, push, undraft PR; then wt-close after merge. Memory file project_render_black_hole.md is STALE — update at landing. + +Deletion commit 8abd7ac1e pushed (−274 LOC; #7 skipped as mutually exclusive with #5 — zeroPadFields now live for \_pad0). DoD audit (sonnet): tests 8011 PASS, tsc PASS, 0 new TODOs, 0 smells, parity OK (+0..+51%), no backlog straggler, ~55 unplanned files all traceable to Rulings 4–10, untouched none. Hygiene miss: plan checkboxes 0/126 → ticked T1–T16 in 2c991ff4e (pushed); T17's 9 boxes left for USER. PR #645 (was docs-only) REWRITTEN as the feature PR + converted to DRAFT: https://github.com/rulkens/skymap/pull/645. AWAITING USER: (1) T16 land ruling (neutral/bounded); (2) T17 checklist attestation (5 spec items + MW-at-rim + capture knee); (3) deletion-audit parked #2 (staleness valve) / #4 (recapture-fraction knob). ON ATTESTATION: tick T17, git mv plan+spec → completed/, archive this ledger → docs/superpowers/plans/completed/2026-09-01-render-black-hole.ledger.md, commit `docs(plan): mark render-black-hole complete`, push, undraft PR; then wt-close after merge. Memory file project_render_black_hole.md is STALE — update at landing. diff --git a/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md index c53a615c3e..b28da3e111 100644 --- a/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md +++ b/docs/superpowers/plans/completed/2026-09-01-render-black-hole.md @@ -1,8 +1,8 @@ -# Render Sgr A* Black Hole Implementation Plan +# Render Sgr A\* Black Hole Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking. This plan follows `docs/superpowers/conventions/plan-style.md` — contract code (signatures, test names+assertions, byte tables) yes, implementation bodies no. -**Goal:** Render a physically-grounded Schwarzschild close-up of Sgr A* inside a +**Goal:** Render a physically-grounded Schwarzschild close-up of Sgr A\* inside a new `sgrAStarLensing` fade band (500→100 AU), with a far-field warm-orange glint marking it from any distance while on screen, replacing the current "draws nothing" `AnchorPointBody`. @@ -28,7 +28,7 @@ lenses and before the annotations that must stay unwarped. section SHIPS rather than being deleted before merge — see the spec's §Settings for why, and Task 15 below. - No Kerr metric, no full-GR observer view below 2 r_s, no cinematic - accretion disc, no M87*/second black hole, no tour beat, no lensing of + accretion disc, no M87\*/second black hole, no tour beat, no lensing of annotations (orbit trails, marker rings, labels, picking stay unlensed). - `npm run perf` is a hard gate, before AND after the feature work (read `.claude/skills/perf/SKILL.md` first; pass `--url` against this worktree's @@ -47,6 +47,7 @@ lenses and before the annotations that must stay unwarped. ### Task 1: P1 — slab candidacy admits anchor bodies, `BODY_SLAB_CAPACITY` derives from the same set **Files:** + - Create: `src/data/bodies/sceneAnchorPointBodies.ts` - Modify: `src/services/engine/frame/visibleSlabBodies.ts:26-46` - Modify: `src/services/engine/frame/frameContext.ts:201-209` (the sole call site) @@ -57,10 +58,11 @@ lenses and before the annotations that must stay unwarped. - Modify: `tests/data/bodies/orientationForBody.test.ts` (anchor-identity assertion) **Interfaces:** + - Produces: `SCENE_ANCHOR_POINT_BODIES: readonly AnchorPointBody[]` — mirrors `SCENE_PLANETS`'s shape (`src/data/bodies/scenePlanets.ts:14`), one element (`SGR_A_STAR`, imported from `sceneSgrAStar.ts`) today. Appending a second - `AnchorPointBody` (M87*, spec non-goal) is a data change to this array, not + `AnchorPointBody` (M87\*, spec non-goal) is a data change to this array, not a code change anywhere it's consumed. - Consumes/produces: `visibleSlabBodies` signature changes from `{ earth: EarthBody | null; planets: readonly PlanetBody[]; ... }` to @@ -104,9 +106,9 @@ lenses and before the annotations that must stay unwarped. above; import `SCENE_ANCHOR_POINT_BODIES`. - [x] Run `npm test -- visibleSlabBodies frameContext frameProgram` — all pass. - [x] Add the test (in `orientationForBody.test.ts`) `returns identity for - the Sgr A* anchor` — asserts `orientationForBody('sgr-a-star', )` equals `IDENTITY_MAT3`. This is the P1 "anchor - orientation-identity verification through bodyRelativePose": Sgr A* is + the Sgr A* anchor` — asserts `orientationForBody('sgr-a-star', )` equals `IDENTITY_MAT3`. This is the P1 "anchor + orientation-identity verification through bodyRelativePose": Sgr A\* is not in `BODY_TEXTURE_REGISTRY`, so `orientationForBody`'s existing membership gate (`orientationForBody.ts:33`) already returns identity — the test pins that fact so a future accidental texture-registry entry @@ -125,7 +127,7 @@ lenses and before the annotations that must stay unwarped. - [x] Run `npm test` (full suite) and `npm run typecheck` — green. - [x] Commit. -**Proof obligation (spec):** with Sgr A* far outside the lensing band (any +**Proof obligation (spec):** with Sgr A\* far outside the lensing band (any framing wider than the galactic centre), `visibleSlabBodies` returns exactly what it returns today for Earth + planets — the anchor's frustum/pixel culls reject it at any sane viewing distance. The updated existing test cases @@ -137,12 +139,14 @@ scenes. ### Task 2: P2 — per-body camera-standoff floor (`standoffRadii`) **Files:** + - Modify: `src/utils/camera/clampDistance.ts:70-78` - Modify: `src/data/bodies/sceneSgrAStar.ts` (add `standoffRadii: 2.0` to `SGR_A_STAR`) - Modify: `src/@types/scene/AnchorPointBody.d.ts` (add optional `standoffRadii` field) - Modify: `tests/utils/camera/clampDistance.test.ts` **Interfaces:** + - `clampDistance(d: number, pivotRadiusMpc: number | null, standoffRadii: number = SURFACE_STANDOFF_RADII): number` — third param optional, defaulting to the existing global constant so every existing call site (which passes only two args) is untouched. @@ -163,7 +167,7 @@ scenes. `EARTH_RADIUS_MPC`-relative tests assert (body radii, not raw Mpc — see the file's own header rationale). - [x] Add the test `clampDistance — omitted standoffRadii keeps Earth's - current floor unchanged`: `clampDistance(d, EARTH_RADIUS_MPC)` (two-arg + current floor unchanged`: `clampDistance(d, EARTH_RADIUS_MPC)` (two-arg call, exactly as today's call sites use it) is byte-identical to today's behaviour — this is the zero-change proof for every body that doesn't opt in. @@ -191,6 +195,7 @@ scenes. ### Task 3: P3 — fixed-size render targets, for the sky cubemap **Files:** + - Modify: `src/@types/engine/frame/RenderTargetSpec.d.ts:14-40` - Modify: `src/services/gpu/renderTargets.ts:265-350` (`allocate`, `reconcile`) - Modify: `tests/services/gpu/renderTargets.test.ts` @@ -221,7 +226,7 @@ export type RenderTargetSpec = { **Steps:** - [x] Add the test `createRenderTargets — a fixedSizePx row allocates at its - declared size regardless of canvas size`: construct + declared size regardless of canvas size`: construct `createRenderTargets` with a test-only `RenderTargetSpec` row (or, if `renderTargetRows` isn't the seam under test, inject via whatever seam the existing tests use) carrying `fixedSizePx: { size: 256, layers: 6 }`; @@ -229,7 +234,7 @@ export type RenderTargetSpec = { `{ width: 256, height: 256, depthOrArrayLayers: 6 }` at a canvas of `{ width: 900, height: 600 }`. - [x] Add the test `createRenderTargets — reconcile does not reallocate a - fixedSizePx row when the canvas resizes`: call `reconcile` with a + fixedSizePx row when the canvas resizes`: call `reconcile` with a DIFFERENT canvas size than construction; assert `device.createTexture` was NOT called again for that row's id (mirrors the existing "reallocates... when the canvas size changes" test's call-count @@ -269,7 +274,7 @@ export type RenderTargetSpec = { `renderTargets.ts` fixed-size allocation branch. - **Named observable behaviours (smoke pass):** none visual — this PR changes no draw output for any existing scene (the P1 proof obligation holds by - construction: Sgr A* still fails both culls at every framing wider than the + construction: Sgr A\* still fails both culls at every framing wider than the galactic centre, since Phase B's lensing/glint layers don't exist yet to read the widened slab candidacy). - **Deferral boundary:** the sky-cubemap render target ROW itself (data, not @@ -296,11 +301,11 @@ scope — see the STOP-and-consult step below). **Steps:** -- [x] Start the dev server (`/dev` skill or `npm run dev`), focus Sgr A* +- [x] Start the dev server (`/dev` skill or `npm run dev`), focus Sgr A\* (already selectable/focusable today — `AnchorPointBody` is in `SCENE_BODIES` and carries a caption). - [x] With Phase A merged (the slab-candidacy + standoff-floor prep live), - descend toward Sgr A* to the P2 floor (2 r_s — `standoffRadii: 2.0` + descend toward Sgr A\* to the P2 floor (2 r_s — `standoffRadii: 2.0` now stops the camera there). - [x] Observe: camera jitter at the floor, frustum near-plane behaviour (`bodySlabRow`'s `near` derivation, `slabs.ts:219-236`), and S-star @@ -318,9 +323,10 @@ scope — see the STOP-and-consult step below). --- -### Task 5: Sgr A* mass + Schwarzschild radius (data + physics util) +### Task 5: Sgr A\* mass + Schwarzschild radius (data + physics util) **Files:** + - Create: `src/data/bodies/sgrAStarMassSolar.ts` - Create: `src/utils/physics/schwarzschildRadiusM.ts` - Create: `tests/utils/physics/schwarzschildRadiusM.test.ts` @@ -386,6 +392,7 @@ export function schwarzschildRadiusM(massSolar: number): number; // r_s = 2GM/c ### Task 6: `BlackHoleRow` type + `BLACK_HOLES` registry **Files:** + - Create: `src/@types/data/BlackHoleRow.d.ts` - Create: `src/data/blackHoles.ts` @@ -412,7 +419,7 @@ export const BLACK_HOLES: readonly BlackHoleRow[]; // one row: sgr-a-star **Steps:** - [x] Add `BlackHoleRow.d.ts` per the contract above, with a docblock stating - the registry is built to hold more than one row (M87* is data, not + the registry is built to hold more than one row (M87\* is data, not code, per the spec's non-goals) — mirrors `SCENE_PLANETS`'s append-only framing. - [x] Add `blackHoles.ts` with `BLACK_HOLES` holding the `sgr-a-star` row: @@ -434,6 +441,7 @@ export const BLACK_HOLES: readonly BlackHoleRow[]; // one row: sgr-a-star ### Task 7: `sgrAStarLensing` fade band + far-field glint alpha derivation **Files:** + - Modify: `src/services/engine/presentation/scaleFadeBands.ts` - Modify: `tests/services/engine/presentation/scaleFadeBands.test.ts` (or wherever `fadeBand` + `SCALE_FADE_BANDS` band-math is currently tested — @@ -457,7 +465,7 @@ sgrAStarLensing: { **Steps:** - [x] Add the test `SCALE_FADE_BANDS.sgrAStarLensing — 100/500 AU envelope in - Mpc, approach direction`: assert `fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, x)` + Mpc, approach direction`: assert `fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, x)` is `1` at/inside `100 * SCALE_UNITS.AU_TO_MPC`, `0` at/outside `500 * SCALE_UNITS.AU_TO_MPC`, and strictly between at a midpoint — this pins the DIRECTION (full at the close edge, per the spec's @@ -477,12 +485,14 @@ sgrAStarLensing: { --- -### Task 8: Far-field glint — Sgr A* rides `bodyGlintsLayer` +### Task 8: Far-field glint — Sgr A\* rides `bodyGlintsLayer` **Files:** + - Modify: `src/services/engine/frame/passes/bodyGlintsLayer.ts` **Interfaces:** + - No new exported symbols — this widens `bodyGlintsLayer`'s existing `enabled`/`draw` internals with a second, independent packed source alongside the `sceneBodyPartition(...).glints` branch. `SCENE_ANCHOR_POINT_BODIES` @@ -502,7 +512,7 @@ intensity constant × `1 - fadeBand(SCALE_FADE_BANDS.sgrAStarLensing, distMpc)` apparent-size term (an anchor never hands off to a resolved mesh, so the existing `bodyGlint` 1–3px band, which exists for exactly that handoff, doesn't apply here) and NO `bodyGlintBackdrop` far-dissolve (the spec's Goal -states the glint is "present the moment Sgr A* is on screen at all" — +states the glint is "present the moment Sgr A\* is on screen at all" — unconditional on far distance, unlike the seeded planets' glints). **Steps:** @@ -526,7 +536,7 @@ unconditional on far distance, unlike the seeded planets' glints). header documents for the Earth caption stamp (`bodyGlintsLayer.ts:153-166`), but for `enabled` itself since this is a VISUAL row, not a pick-only widening. -- [x] No `drawPick` change — the spec states Sgr A*'s existing pick stamp +- [x] No `drawPick` change — the spec states Sgr A\*'s existing pick stamp (its caption) is untouched by this feature; the far-field glint carries no pick aspect of its own. - [x] Add a behavioural test (in the existing @@ -548,6 +558,7 @@ unconditional on far distance, unlike the seeded planets' glints). ### Task 9: `SchwarzschildDeflectionLut` type + `buildSchwarzschildDeflectionLut` **Files:** + - Create: `src/@types/lensing/SchwarzschildDeflectionLut.d.ts` - Create: `src/utils/lensing/buildSchwarzschildDeflectionLut.ts` - Create: `tests/utils/lensing/buildSchwarzschildDeflectionLut.test.ts` @@ -612,6 +623,7 @@ export function buildSchwarzschildDeflectionLut(sampleCount: number): Schwarzsch ### Task 10: Lensing WGSL uniform struct — byte/offset table **Files:** + - Create: `src/services/gpu/shaders/lib/sgrAStarLensing.wesl` (or fold into an existing lensing-adjacent lib module if one is created by Task 13 — implementer's call on the exact filename; the byte table below is the @@ -627,25 +639,25 @@ Follows the `CameraUniforms` shared-prefix pattern from `viewportPx` + 2 pad floats), renderer-specific fields at offset 80+, 16-byte-aligned before any `vec3`/`vec4`: -| Offset (bytes) | Field | Type | Notes | -|---|---|---|---| -| 0–63 | `cam.viewProj` | `mat4x4` | shared `CameraUniforms` prefix | -| 64–71 | `cam.viewportPx` | `vec2` | shared prefix | -| 72–79 | `cam._pad0`, `cam._pad1` | `f32`, `f32` | shared prefix pads | -| 80–83 | `schwarzschildRadiusM` | `f32` | r_s in metres — the pass's own scale unit | -| 84–87 | `innerRs` | `f32` | emission annulus inner edge, r_s units | -| 88–91 | `outerRs` | `f32` | emission annulus outer edge, r_s units | -| 92–95 | `inclinationRad` | `f32` | | -| 96–99 | `positionAngleRad` | `f32` | | -| 100–103 | `flickerAmp` | `f32` | | -| 104–107 | `flickerTimescaleS` | `f32` | | -| 108–111 | `flickerPhase` | `f32` | sim-clock-derived phase, uploaded per frame (not a `BLACK_HOLES` constant) | -| 112–115 | `lutMinImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.minImpactParamRs` | -| 116–119 | `lutMaxImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.maxImpactParamRs` | -| 120–123 | `lutSampleCount` | `f32` (or `u32`, matching the LUT texture's actual texel count) | | -| 124–127 | `bandAlpha` | `f32` | the fade band's own alpha this frame — gates emission/deflection strength in-shader for the crossfade, avoiding a second CPU-side branch | -| 128–139 | `anchorPosRelCamM` | `vec3` | camera-relative anchor position, metres — the f64→f32 rebase seam, same pattern `bodyGlintsLayer`/`starPointsLayer` use | -| 140–143 | `_pad2` | `f32` | pad to keep the following field 16-byte aligned if one is added later; omit if 140 already satisfies alignment for the struct's end | +| Offset (bytes) | Field | Type | Notes | +| -------------- | ------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| 0–63 | `cam.viewProj` | `mat4x4` | shared `CameraUniforms` prefix | +| 64–71 | `cam.viewportPx` | `vec2` | shared prefix | +| 72–79 | `cam._pad0`, `cam._pad1` | `f32`, `f32` | shared prefix pads | +| 80–83 | `schwarzschildRadiusM` | `f32` | r_s in metres — the pass's own scale unit | +| 84–87 | `innerRs` | `f32` | emission annulus inner edge, r_s units | +| 88–91 | `outerRs` | `f32` | emission annulus outer edge, r_s units | +| 92–95 | `inclinationRad` | `f32` | | +| 96–99 | `positionAngleRad` | `f32` | | +| 100–103 | `flickerAmp` | `f32` | | +| 104–107 | `flickerTimescaleS` | `f32` | | +| 108–111 | `flickerPhase` | `f32` | sim-clock-derived phase, uploaded per frame (not a `BLACK_HOLES` constant) | +| 112–115 | `lutMinImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.minImpactParamRs` | +| 116–119 | `lutMaxImpactParamRs` | `f32` | from `SchwarzschildDeflectionLut.maxImpactParamRs` | +| 120–123 | `lutSampleCount` | `f32` (or `u32`, matching the LUT texture's actual texel count) | | +| 124–127 | `bandAlpha` | `f32` | the fade band's own alpha this frame — gates emission/deflection strength in-shader for the crossfade, avoiding a second CPU-side branch | +| 128–139 | `anchorPosRelCamM` | `vec3` | camera-relative anchor position, metres — the f64→f32 rebase seam, same pattern `bodyGlintsLayer`/`starPointsLayer` use | +| 140–143 | `_pad2` | `f32` | pad to keep the following field 16-byte aligned if one is added later; omit if 140 already satisfies alignment for the struct's end | Total struct size: 144 bytes (rounds to a 16-byte multiple). The `SchwarzschildDeflectionLut.samples` themselves are NOT part of this uniform @@ -679,6 +691,7 @@ absent file) the spec cites. ### Task 11: Sky-capture — fixed-size cubemap target row + `skyCubemapFaceContext` **Files:** + - Modify: `src/services/gpu/renderTargets.ts` (`renderTargetRows` — new row) - Create: `src/services/engine/frame/skyCubemapFaceContext.ts` - Create: `tests/services/engine/frame/skyCubemapFaceContext.test.ts` @@ -705,16 +718,16 @@ export function skyCubemapFaceContext(input: { the roster's additive draws keep their dynamic range), `depth: null` (the captured roster — point-sprites, star-catalog/aggregates, S-star glints — is depthless/additive, same profile as `hdr`), `clearValue: { r: 0, g: 0, - b: 0, a: 0 }` (same additive-identity reason every reduced-res row in the +b: 0, a: 0 }` (same additive-identity reason every reduced-res row in the table clears to zero — see `renderTargets.ts`'s module header), `fixedSizePx: { size: 256, - layers: 6 }` (Task 3's mechanism), `scale` unused/irrelevant when +layers: 6 }` (Task 3's mechanism), `scale` unused/irrelevant when `fixedSizePx` is set (per Task 3's contract) but the field is still required by the type — set it to `1` as an inert placeholder. **Steps:** - [x] Add the test `skyCubemapFaceContext — derives a ReadyFrameContext with - the eye at the anchor position, looking along the requested face axis`: + the eye at the anchor position, looking along the requested face axis`: call it for each of the 6 `CubeFace` values with a fixture `eyeMpc`, assert the returned context's camera position matches `eyeMpc` and its view direction matches the ±X/±Y/±Z convention documented on `CubeFace` @@ -745,6 +758,7 @@ export function skyCubemapFaceContext(input: { ### Task 12: Capture scheduling + roster wiring **Files:** + - Create: `src/services/engine/frame/skyCubemapCaptureSchedule.ts` - Create: `tests/services/engine/frame/skyCubemapCaptureSchedule.test.ts` - Modify: `src/services/engine/frame/frameProgram.ts` (capture render steps, @@ -793,14 +807,14 @@ available via `ctx`/`state`) and passes it as the new fourth argument. **Steps:** - [x] Add the test `skyCubemapCaptureSchedule — full 6-face capture on band - entry`: `bandJustEngaged: true` → `facesToCapture` has all 6 faces + entry`: `bandJustEngaged: true` → `facesToCapture` has all 6 faces regardless of `frameIndex`. - [x] Add the test `skyCubemapCaptureSchedule — round-robins one face per - frame otherwise`: `bandJustEngaged: false`, vary `frameIndex` across 6 + frame otherwise`: `bandJustEngaged: false`, vary `frameIndex` across 6 consecutive values → each yields exactly one face, cycling through all 6 without repeats within the cycle. - [x] Add the test `skyCubemapCaptureSchedule — escape valve re-captures a - stale or camera-moved face out of turn`: a face whose + stale or camera-moved face out of turn`: a face whose `lastCapturedAtMs` predates `nowMs` by more than the threshold (or `cameraMovedBeyondThreshold: true`) appears in `facesToCapture` even when the round-robin wouldn't select it this frame. @@ -845,6 +859,7 @@ available via `ctx`/`state`) and passes it as the new fourth argument. ### Task 13: `ContentLayer` row `sgrAStarLensing` + the geodesic WESL shader **Files:** + - Create: `src/services/gpu/shaders/bodies/sgrAStarLensing/vertex.wesl` - Create: `src/services/gpu/shaders/bodies/sgrAStarLensing/fragment.wesl` - Create: `src/services/gpu/renderers/bodies/sgrAStarLensingRenderer.ts` @@ -853,6 +868,7 @@ available via `ctx`/`state`) and passes it as the new fourth argument. layer + import export) **Interfaces:** + - `sgrAStarLensingLayer: ContentLayer` — `slab: 'body'`, `target: 'hdr'`, `blend: 'over'` (per-pixel alpha lets the roster show through where deflection is negligible — the spec's "per-pixel alpha does the rest of @@ -936,6 +952,7 @@ not a licence to build finite-distance geodesics. ### Task 14: Draw-order reorder — lensing before `orbit-trails`/`body-glints` **Files:** + - Modify: `src/services/engine/frame/passes/index.ts` **Interfaces:** none new — a reorder of `CONTENT_LAYERS`'s existing array @@ -980,6 +997,7 @@ retuned, and `cubemapResolutionPx` is a live VRAM/sharpness trade. The 176-byte uniform tail is therefore permanent. See the spec's §Settings. **Files:** + - Create: `src/components/DebugPanel/SgrAStarLensingTuningSection.tsx` - Create: `src/components/containers/SgrAStarLensingTuningSectionContainer.tsx` - Modify: `src/components/DebugPanel/DebugPanel.tsx` @@ -1023,13 +1041,13 @@ gate). read `.claude/skills/perf/SKILL.md` first, then run `npm run perf` with `--url http://localhost:` (read the port off this worktree's own `npm run dev` output — never another - branch's server). Record the baseline numbers outside the band (Sgr A* + branch's server). Record the baseline numbers outside the band (Sgr A\* far off-frame) and note there is no "inside the band" baseline yet (the feature doesn't exist). - [x] AFTER Task 15 (all feature work done — the tuning section ships, per the Settings amendment above, so there is no removal step to wait on): re-run - `npm run perf` the same way, twice — once with Sgr A* far outside the + `npm run perf` the same way, twice — once with Sgr A\* far outside the lensing band (expect a neutral delta vs. the baseline — Q6's zero-cost guarantee), once with the camera inside the band (expect a bounded, not unbounded, cost — the six-face capture amortized per Q8, the LUT @@ -1058,7 +1076,7 @@ gate). **Steps:** -- [x] With the dev server running and the feature complete, focus Sgr A* and +- [x] With the dev server running and the feature complete, focus Sgr A\* and descend into the lensing band. Verify, with the user, EACH of the spec's five checklist items verbatim: - [x] shadow diameter reads as ~5.2 r_s (the EHT-consistent apparent size); @@ -1085,6 +1103,7 @@ gate). ## Definition of Done **Deliverable inventory:** + - Phase A: `SCENE_ANCHOR_POINT_BODIES`, `visibleSlabBodies`'s `{bodies}` signature, the three-term `BODY_SLAB_CAPACITY`, `clampDistance`'s `standoffRadii` param, `SGR_A_STAR.standoffRadii`, `RenderTargetSpec.fixedSizePx`. @@ -1098,7 +1117,8 @@ gate). deleted with both its readers migrated. **Named observable behaviours (manual smoke pass):** -- Sgr A* shows a faint warm-orange glint from any distance while on screen, + +- Sgr A\* shows a faint warm-orange glint from any distance while on screen, with no mesh (confirms `AnchorPointBody`'s corrected docblock is honest). - Descending inside 500 AU, the glint crossfades into a lensed close-up with no pop; inside 100 AU the close-up is fully engaged. @@ -1112,12 +1132,13 @@ gate). pre-feature baseline; inside the band, the cost is bounded, not runaway. **Deferral boundary (from the spec's non-goals — do not chase these):** + - No Kerr metric (Schwarzschild only). - No full-GR observer view below 2 r_s (no local-frame aberration/redshift; the descent floor stops the camera at the boundary where the shader's static-viewpoint model is still defensible). - No cinematic accretion disc (EHT-style faint glow only). -- No M87* or any second black hole (`BLACK_HOLES` holds room for one; not +- No M87\* or any second black hole (`BLACK_HOLES` holds room for one; not populated here). - No tour beat. - No lensing of annotations (orbit trails, marker rings, labels, picking diff --git a/docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md b/docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md index 83fac809cf..0402bc5af3 100644 --- a/docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md +++ b/docs/superpowers/specs/completed/2026-09-01-render-black-hole-design.md @@ -48,16 +48,16 @@ the close-up crossfades in. The camera may descend to 2 Schwarzschild radii ## Data -| quantity | value | -| ------------------------------------- | --------------------------------------------------- | -| Sgr A\* mass | 4.297 × 10⁶ M☉ (GRAVITY Collaboration 2019, A&A 625, L10) | -| Schwarzschild radius (derived) | `2GM/c²` ≈ 12.69 × 10⁶ km ≈ 0.085 AU — same figure `sgrAStarSchwarzschildRadiusKm.ts` hand-authored today | -| Emission annulus | 3–6 r_s (ISCO outward to the ~5 r_s EHT-measured lensed ring) | -| Inclination | ≲ 30° from face-on (EHT constraint) | -| Position angle | unconstrained observationally; one value chosen and noted as such | -| Flicker | one global sim-clock brightness modulation, minute-scale timescale, no patch structure (Q7) | -| Lensing band (Q6) | engage ≤ 500 AU, full by 100 AU | -| Descent floor (Q10) | 2 r_s, via per-body `standoffRadii` override | +| quantity | value | +| ------------------------------ | --------------------------------------------------------------------------------------------------------- | +| Sgr A\* mass | 4.297 × 10⁶ M☉ (GRAVITY Collaboration 2019, A&A 625, L10) | +| Schwarzschild radius (derived) | `2GM/c²` ≈ 12.69 × 10⁶ km ≈ 0.085 AU — same figure `sgrAStarSchwarzschildRadiusKm.ts` hand-authored today | +| Emission annulus | 3–6 r_s (ISCO outward to the ~5 r_s EHT-measured lensed ring) | +| Inclination | ≲ 30° from face-on (EHT constraint) | +| Position angle | unconstrained observationally; one value chosen and noted as such | +| Flicker | one global sim-clock brightness modulation, minute-scale timescale, no patch structure (Q7) | +| Lensing band (Q6) | engage ≤ 500 AU, full by 100 AU | +| Descent floor (Q10) | 2 r_s, via per-body `standoffRadii` override | ```ts // src/data/bodies/sgrAStarMassSolar.ts — one symbol per file. diff --git a/src/utils/physics/schwarzschildRadiusM.ts b/src/utils/physics/schwarzschildRadiusM.ts index de1fbc61f7..0ab3a9bc83 100644 --- a/src/utils/physics/schwarzschildRadiusM.ts +++ b/src/utils/physics/schwarzschildRadiusM.ts @@ -4,7 +4,7 @@ */ const C_M_S = 299792458; -const G_M3_KG_S2 = 6.67430e-11; +const G_M3_KG_S2 = 6.6743e-11; const SOLAR_MASS_KG = 1.98892e30; export function schwarzschildRadiusM(massSolar: number): number {