@forgeax/engine-render 0.1.28 → 0.1.30

package/README.md

@@ -33,7 +33,7 @@ GPU, Browser, and Dawn evidence that cannot execute is `not-run` or
 `unavailable`, never a verified structural substitute.
 
 The public frame vocabulary is intentionally small. `Camera` is the authoring
-owner for tone, antialiasing, bloom, and `historyVersion`; `Atmosphere` and
+owner for tone, exposure, color grading, antialiasing, bloom, and `historyVersion`; `Atmosphere` and
 `Fog` are independent ECS components. The renderer extracts these facts into
 an immutable `FramePlan`, records one frame, and returns a `FrameReceipt`.
 `FrameReceipt` is the only successful synchronous proof that the host submit
@@ -47,8 +47,16 @@ An AI consumer can start with the public sequence `state -> inspect -> recover
 `alive` admits a frame; `device-lost` permits one explicit recovery flight;
 `recovering` shares that flight; `faulted` requires a new Renderer; and
 `disposed` is terminal. `inspect()` is detached POD evidence for the current
-state and recovery attempt. After `recover()` succeeds, submit the unchanged
+state, recovery attempt, and named output contract. After `recover()` succeeds, submit the current
 draw input and use the new `FrameReceipt` as the proof for that generation.
+An active device loss includes native `destroyed` notifications; only retired
+or unpublished candidate generations are isolated from active health. Pending
+dynamic geometry must be prepared again for the replacement generation before
+admission. Explicit preparation between recovery and draw may upload its new
+payload; the first-draw guard still rejects lazy cold uploads or pipeline builds
+inside rendering. Preparation does not make an old-generation receipt current.
+Recovery prepares the last successfully submitted workset; the next draw still
+consumes current World edits and admits new resources through normal residency.
 
 `inspect().recovery` is always present. Its `phase` is `null` outside an active
 attempt and otherwise follows `quiesce`, `acquire-adapter`, `acquire-device`,
@@ -142,9 +150,20 @@ The remaining CSM fields keep these public units and defaults: `cascadeCount`
 is an integer in `[1, 4]` (default `4`), `splitLambda` is `[0, 1]` (default
 `0.75`), `cascadeBlend` is `[0, 0.5]` (default `0.2`), `mapSize` is a positive
 map resolution (default `2048`), `depthBias` is a depth value (default
-`0.005`), `normalBias` is a world-space offset (default `0.05`), and
+`0.00001`, subtracted from normalized receiver depth), `normalBias` offsets the
+surface receiver position along its world-space normal before projection (default `0.05`), and
 `shadowDistance` is a positive world-unit distance in meters (default `200`).
 
+Normal offset and depth bias are independent: increasing the CSM depth span must
+not magnify the world-space normal offset. Both PCF and PCSS project the offset
+receiver; volumetric samples have no surface normal and use only depth bias.
+Cascade projections include their incoming blend band, and PCSS depth spans
+match the actual projection, including toward-light caster reach. The normal
+position offset follows the approach in
+[Three.js shadowmap_vertex](https://github.com/mrdoob/three.js/blob/e45cbf7ff66df079cfa39d9699ccb42729934be1/src/renderers/shaders/ShaderChunk/shadowmap_vertex.glsl.js).
+The real-render regression is
+[`shadow-contact.browser.test.ts`](../runtime/src/__tests__/shadow-contact.browser.test.ts).
+
 After `draw`, read the single `renderer.inspect().directionalShadow` projection.
 It is JSON-safe and bounded: `requested` is author intent, `effective` is the
 admitted profile, `status` is `accepted | fallback | rejected`, and
@@ -194,8 +213,42 @@ environment owners or multiple fog owners return structured errors with a
 code-specific `detail`; they do not create a second registry or silently pick
 the first entity. Frame facts contain IDs, revisions, and POD values only, not
 textures, buffers, devices, or other live GPU objects.
+
+The Standard graph renders an Atmosphere source as a 128-by-128, six-face
+`rgba16float` sky cube and a background pass before scene geometry. The selected
+DirectionalLight supplies the sun direction, color, and illuminance; the sun
+angle is in radians, and zero radius disables the visible disc. Geometry covers
+the background through ordinary scene rendering, including transparent blending.
+The cube excludes the disc. An explicit `Skylight` without an equirect asset
+uses diffuse irradiance and roughness-prefiltered radiance from this same cube.
+Its color and intensity remain the lighting controls; no Skylight means no
+global ambient contribution. An explicit equirect keeps its image source.
+Use a neutral Skylight tint when comparing local captures against the sky.
+
+The cube has 786,432 texture payload bytes. Its 16-square irradiance cube and
+64-square, five-mip prefilter add 274,176 bytes; parameters and vertices total
+1,560 bytes, before backend allocation alignment. DeviceScope owns one cached
+set, imported into each graph. Resize and probe topology changes reuse it;
+disabling Atmosphere retains it until device-scope retirement. Device recovery
+allocates a fresh set. Its six faces and lighting products update together only
+when the selected environment signature changes, and become current only after
+successful frame submission. An unchanged source runs only the background pass.
+GPU pass observations
+name `atmosphere-prepare`, `atmosphere-cube-0` through `atmosphere-cube-5`, and
+`atmosphere-background`, `atmosphere-irradiance-*` and `atmosphere-prefilter-*`;
+unavailable timestamps remain explicitly unavailable.
+The source lifecycle inspection and graph resource accounting describe different
+owners: a source revision is not a claim that its GPU cube was submitted.
+
+The reusable [Wave 1 recipe](../../scripts/dev-verify/wave1-rendering/README.md)
+shows the public scene inputs and associated acceptance gates.
+
 ## GPU pass timing: opt in, draw, observe, branch on status
 
+When App owns the draw loop, `renderer.subscribe` delivers the exact `receipt`
+in each `frame-submitted` event. Pass that receipt to `observe`; do not construct
+one from the frame number. Start observation promptly because retention is bounded.
+
 GPU pass timing is disabled by default. Opt in once on `createRenderer`, keep the
 returned `FrameReceipt`, and request facts only for that receipt. The pass
 duration is a bounded GPU fact; it is not frame latency.
@@ -291,6 +344,18 @@ over-budget requests. A World with no `PointLightShadow` remains `inactive`;
 there is no pseudo-disabled shadow mode. Directional CSM remains a separate
 shadow owner; PointLightShadow is not a second directional-light path.
 
+The cube atlas uses negated world axes: cube lookup is `lightPos - worldPos`,
+and each face camera looks opposite its cube axis with the corresponding face-up
+vector. This matches WebGPU framebuffer V without reflecting clip-space Y or
+changing authored front-face/culling state. Raster matrices and sampling must
+change together; a standalone Z flip is not a valid conversion.
+
+Camera-culled scene meshes remain shadow candidates when their bounds intersect
+an admitted light frustum. Their projected dispatch contains only `ShadowCaster`,
+never Forward/Deferred work. Persistent composition uses the merged light frame,
+including lights from another World. `frustumStats.culled` continues to count
+camera rejection even when the retained object casts a shadow.
+
 ## Render happy path
 
 `RenderScene -> Standard Pipeline -> DeviceScope -> FrameReceipt` is the only frame
@@ -319,20 +384,50 @@ and keeps shadow, PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX,
 ownership inside the same graph and submit boundary. CPU and WebGL2 remain capability lanes for the
 Cluster membership producer or for mesh/instance storage fallback; they do not reintroduce a
 PointLight/SpotLight buffer or a fixed four-light ABI.
-## SSR M0 admission: inspect owners, then decide
+## SSR admission and bounded inspection
+
+Coverage counters are `null` until GPU measurements are supplied; missing
+measurements must not be interpreted as zero hits. The hello-ssr Browser smoke
+captures a v7 RHI tape, reads trace/temporal/compose outputs at their producing
+work indices, and requires positive confidence plus a measurable composition
+delta. It also verifies that the composed resource reaches a later draw and
+retains its pixels through that draw. Ordinary `hello-ssr` startup enables SSR.
+
+The Standard G-buffer stores the visible material's response once:
+
+| Target | RGB | Alpha |
+|:--|:--|:--|
+| Normal/roughness | Encoded world normal | Roughness |
+| Albedo/metallic | Linear albedo | Metallic |
+| Specular response/AO | Unit-radiance specular BRDF response, including occlusion | AO |
+
+Forward lighting still owns direct light and emissive contributions. SSR uses
+one fullscreen additive draw, not a geometry redraw: its RGB delta is
+`confidence * (filteredRadiance * specularResponse - fallback)`. This prevents
+equal-depth overlapping geometry from subtracting the fallback more than once.
+Resolved radiance has a confidence-weighted mip chain; composition samples
+`roughness² * (mipCount - 1)` with trilinear reconstruction. Receiver admission
+uses the current lighting coverage, compatible half-resolution normals, and
+the shared View's enable/roughness cutoff. It does not clip the rough lobe to
+the central mirror ray's hit confidence. Material roughness changes the
+reflection's filter footprint, not just its opacity; confidence remains bounded
+by the current receiver's roughness fade. Coarse mips are spatial approximations,
+not separate roughness-dependent ray traces.
 
 > [!IMPORTANT]
 > SSR M0 is a consumer-only admission boundary. It reads detached producer,
-> r32float format, and temporal receipts with one four-field integration
-> identity. Any missing, stale, structural-only, or mismatched receipt stays
-> `fallback-only` and emits zero SSR work; this section does not describe SSR
-> capture, ray tracing, Hi-Z, temporal resolve, composition, or history.
+> r32float format, and optional prior temporal receipts with one four-field
+> integration identity. Missing required, stale, structural-only, or mismatched receipts stay
+> `fallback-only` and emits zero SSR work. An admitted Standard frame then
+> projects the renderer-owned M1 spatial chain and M2 history through
+> `renderer.inspect().ssr`; paired Browser/Dawn pixel evidence is still the
+> gate for calling the result SSR v1.
 
 ```mermaid
 flowchart LR
   P["producer detached receipt"] --> A["admitSsrM0"]
   F["format stage receipt"] --> A
-  T["temporal submit receipt"] --> A
+  T["optional prior temporal receipt"] -.-> A
   A -->|"all identity and verdict checks pass"| E["admitted: parent M1 may unlock"]
   A -->|"missing, stale, unavailable, or mismatched"| B["fallback-only: zero work"]
 ```
@@ -355,16 +450,64 @@ if (admission.status === 'fallback-only') {
 }
 ```
 
+After the ordinary frame, read the detached spatial projection without opening
+the graph or a GPU handle:
+
+```ts
+const spatial = renderer.inspect().ssr;
+switch (spatial.status) {
+  case 'not-requested':
+  case 'requested':
+  case 'fallback-only':
+    // Base probe / Skylight / neutral reflection remains visible.
+    break;
+  case 'structural-only':
+    // The graph is admitted, but this run has no executable shader carrier.
+    break;
+  case 'admitted':
+    // Inspect history, passRoster, fallbackSource, and coverage before evidence.
+    break;
+}
+```
+
+| `renderer.inspect().ssr.status` | Meaning | SSR work |
+|:--|:--|:--|
+| `not-requested` | Active camera has no `ScreenSpaceReflection` | Exact zero |
+| `requested` | Authoring is present; M0/spatial facts are not yet complete | Exact zero |
+| `fallback-only` | A closed config, lane, input, capability, or owner receipt failed | Exact zero |
+| `structural-only` | Spatial admission and graph topology exist, but no executable shader source is bound | Topology only |
+| `admitted` | Standard spatial path and shader manifest are bound | Inspect `history`, `passRoster`, `fallbackSource`, and coverage |
+
+`history.state`, `history.bytes`, `history.resetCount`, `passRoster`, and
+`fallbackSource` are bounded POD facts. They are evidence about the current
+owner state, not an acceptance claim: M1/M2 remain an implementation checkpoint
+until the paired Browser/Dawn 300-frame carrier, readback, falsifiers, and
+performance gates are present.
+
+SSR temporal feedback and presentation use distinct coordinates without another
+allocation. The persistent color/depth and normal/confidence slots use fixed,
+unjittered half-resolution centers (`2*p + 0.5` in full-resolution pixels).
+Current trace samples are reconstructed onto that grid once; history reprojection
+uses unjittered motion and validates depth/normal before interpolation. The
+separate resolved output stays on the current jittered raster grid for composition
+and reflection mip generation. Never feed that presentation reconstruction back
+into history: repeated jitter filtering loses reflected texture contrast.
+
 Use `inspect -> owner recovery -> matching submit -> reinspect` as the complete
 AI route. No returned field is a device, graph node, texture, buffer, encoder,
 or other live handle. A stable generation keeps `resetCount`, `rebuildCount`,
 and additional format probe work at zero; a changed generation must be
 reinspected before admission can be considered again.
 
-`inspect()` is a synchronous snapshot. The first snapshot after binding may show
-an absent format or temporal receipt while the owner probe and first submit are
-still in flight; it is not a `pending` verdict. Run the ordinary owner frame,
-await `FrameReceipt.completed`, then inspect again before routing recovery.
+`inspect()` is a synchronous snapshot. Explicit `RendererOptions.ssrIdentity`
+opts into one real format probe during initialization of each device generation;
+initialization and recovery await it before the first synchronous draw. A renderer
+without that option does not probe. Camera demand still controls all per-frame
+SSR attachments, passes, history and uploads. An unavailable format stays
+fallback-only; an absent previous temporal receipt does not block fresh spatial
+SSR. Current-frame motion/coverage comes from the Standard graph. History is
+read only after its normal successful-submit validation, never fabricated to
+admit the first frame.
 
 There are two action projections. `admission.failure.detail.action` is the coarse
 M0 gate instruction (`retry` for demand/readiness and `rebuild` for a missing or
@@ -377,12 +520,56 @@ API; use the existing owner operation shown here, then submit and inspect again:
 | `reflectionFallbackInspection.recoveryAction = use-LKG` | Keep the compatible probe row and draw the next frame | Read the committed row and matching temporal receipt |
 | `reflectionFallbackInspection.recoveryAction = use-Skylight` / `use-neutral` | Change the World-owned probe/`Skylight` source, then draw | Confirm selected source and committed generation |
 | `reflectionFallbackInspection.recoveryAction = recapture` / `rebuild` / `retry` | Draw again so the producer/RHI owner retries pending work | Await completion and inspect the owner receipt/failure |
-| `admission.failure.detail.action = retry` / `rebuild` | Retry the consumer frame, or rebuild the named owner receipt | Reinspect admission and all three receipt generations |
-| device-loss recovery | `await renderer.recover()` before the next draw | Confirm the replacement `deviceGeneration`, then re-probe |
+| `admission.failure.detail.action = retry` / `rebuild` | Retry the consumer frame, or rebuild the named owner receipt | Reinspect required receipts and any supplied temporal receipt |
+| device-loss recovery | `await renderer.recover()` before the next draw | Confirm the replacement `deviceGeneration` and its completed format probe |
 
 SSR never invokes these operations or mutates producer/device state; this table
 maps the typed action to the existing public World and Renderer seams.
 
+## Screen-space ambient occlusion
+
+Enable AO through the same public Standard profile used at creation or by
+`renderer.setProfile()`. It requires `renderPath: 'deferred'` for current-frame
+depth and world normals; an incompatible profile returns a structured error.
+
+The GLES fallback does not support the required raw-depth shader reads. It boots normally with AO disabled; requesting AO reports `feature-not-enabled` and requires WebGPU.
+
+The default Vite shader producer includes SSAO, so `StandardProfile.ssao` needs no build-time opt-in. A deliberately stripped manifest reports `post-process-not-found` when AO is requested; it must not silently render white AO.
+
+```ts
+const configured = renderer.setProfile({
+  ...renderer.inspect().profile,
+  renderPath: 'deferred',
+  ssao: { quality: 'medium', radius: 0.5, bias: 0.025, intensity: 1 },
+});
+if (!configured.ok) throw configured.error;
+// Remove both AO passes and their per-frame upload work:
+const disabled = renderer.setProfile({ ...renderer.inspect().profile, ssao: false });
+if (!disabled.ok) throw disabled.error;
+```
+
+| Parameter | Contract |
+|:--|:--|
+| `quality` | `low` / `medium` / `high`: 16 / 32 / 64 hemisphere samples; default `high` |
+| `radius` | Positive finite view-space distance; default `0.5` |
+| `bias` | Non-negative finite view-space depth bias; default `0.025` |
+| `intensity` | Non-negative finite strength; default `1`; zero preserves the unoccluded image |
+| `ssao: true` | Enables the same default parameter set |
+
+AO runs at half resolution with a symmetric depth/normal-aware blur. Sampling
+uses the raster projection, including camera jitter. Static, skinned, and
+custom Standard surfaces multiply ambient illumination and the corresponding
+SSR fallback by the same AO factor; direct lights remain unchanged. Material
+occlusion is applied once. AO is reconstructed every frame and owns no temporal
+history, so moved geometry cannot leave a retained AO image.
+
+> [!NOTE]
+> AO is a local screen-space approximation. Offscreen occluders are absent,
+> and silhouettes can retain small half-resolution sampling artifacts. Use
+> the plane-plus-cube example at `apps/learn-render/5.advanced-lighting/9.ssao`
+> to compare contact, lift, quality, radius, and disabled behavior. GPU timings
+> are opt-in via `gpuPassTiming` and receipt-bound `observe(..., { include: ['timings'] })`.
+
 ## Target and probe lifecycle index
 
 The public target route is one Renderer owner: create a typed `RenderTarget`, create a
@@ -406,22 +593,144 @@ must match the committed row's frame and device generation before it is used as
 The exact public names and stable consumer IDs are machine-readable in
 `src/__tests__/render-target-public-schema.json`.
 
+### Dynamic reflection probes
+
+```ts
+const probe = world.spawn(
+  { component: Transform, data: { pos: [0, 1, 0] } },
+  { component: ReflectionProbe, data: {
+    halfExtents: [5, 3, 5], resolution: 128,
+    updateIntent: REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  } },
+).unwrap();
+// Explicit invalidation also works for a once probe.
+const current = world.get(probe, ReflectionProbe).unwrap();
+world.set(probe, ReflectionProbe, {
+  invalidationVersion: current.invalidationVersion + 1,
+}).unwrap();
+```
+
+| Update intent | Trigger |
+|:--|:--|
+| `REFLECTION_PROBE_UPDATE_ONCE` | Initial capture, explicit invalidation, or probe movement |
+| `REFLECTION_PROBE_UPDATE_ON_CHANGE` | Above, plus retained scene/material/geometry or light/environment changes |
+| `REFLECTION_PROBE_UPDATE_CONTINUOUS` | Start another capture after the previous candidate completes |
+
+The renderer shares **one capture face or PMREM face/mip step per submitted
+frame across all probes**, round-robin. One probe needs six raw faces plus 30
+filter steps: 36 completed submissions after pipeline readiness. Multiple probes
+share that budget. This is amortized realtime updating, with visible latency;
+it does not provide a fresh six-face snapshot every display frame. Changes
+arriving during a cycle coalesce into the next cycle rather than starving
+publication. Video and time-driven shader changes require continuous mode or
+explicit invalidation when their producer does not update scene change evidence.
+
+A complete candidate swaps atomically after successful GPU completion. Failed
+submissions retry the same step, and stale device-generation completions cannot
+publish. A moving probe uses Skylight fallback until a capture at its new center
+is ready. Each face sees the retained authored scene, including objects outside
+the display camera; authored hidden objects stay excluded. Probe specular keeps
+the global Skylight diffuse color, intensity, and rotation. Shared materials
+still select probes independently for each object.
+
+Raw faces sample the selected Atmosphere sky cube, otherwise the authored
+`SkyboxBackground`, or the Skylight environment when no skybox is present,
+in the same HDR geometry pass. Atmosphere capture declares a sampled-read of
+the existing graph-owned cube; it does not evaluate another sky or allocate
+another sky texture. Its sun disc remains in the display background only,
+while directional lighting supplies the specular sun response. Changes to
+Atmosphere parameters invalidate `on-change` probes through the existing
+selected-environment signature. Camera-only changes do not invalidate them.
+Environment asset readiness precedes capture. Camera-cube orientation is normalized during PMREM
+production; runtime probe sampling does not apply the image-IBL Y conversion.
+Place capture centers in empty space, away from the interior of opaque objects.
+
+Fallback source receipts publish only after the actual graph output completes
+on the GPU. Normal rendering performs no fallback pixel readback or hashing.
+Set `captureReflectionFallbackReadback: true` on `createApp` / `createRenderer`
+only for diagnostics that need `reflectionFallbackReadback`: this copies,
+maps, validates and hashes the full HDR attachment each submitted frame.
+Source receipts contain selection facts; the optional readback receipt contains
+actual sampled pixel evidence. Submission failure preserves compatible LKG,
+and stale device or source completions cannot publish either kind of receipt.
+
+The selected probe is admitted per object, but its influence is evaluated per
+shaded pixel. Pixels outside `halfExtents` use the global Skylight specular map;
+the outer 10% of the box blends into that source. The global texture stays
+resident alongside the local cube, including GPU-driven and custom Surface
+materials. Changing either resource invalidates material binding reuse.
+
+`boxProjection` defaults to `false`, as a general captured cubemap has no known
+wall geometry. Set it to `true` only when `halfExtents` also describes a room's
+reflection proxy. A small influence box around an outdoor object is not a room
+proxy: forcing that correction can reflect the wrong surface even for an
+otherwise valid ray. The SSR demo exposes independent SSR/probe controls and a
+**Plane + cube** fixture; the Objects fixture keeps every object resting on its
+floor and contains the probe receiver within the influence box.
+
+Resolution is an actual power of two from 16 through 256. The 64 MiB admission
+budget counts the raw cube, two filtered cubes, and depth attachments, with at
+most 16 probes; at 256 pixels the byte budget admits five. Start at 64 or 128 for
+frequent updates. `inspect().reflectionProbes.updates` reports intent, requested
+and captured revision, active generation, pending work, and completion latency.
+The SSR fallback source identity includes the active probe generation, so a
+new environment invalidates stale SSR history. Probe capture, SSR ray tracing,
+and SSR composition remain separate observable work.
+
 ## Stable inspection and dark-gradient evidence
 
 Progressive disclosure is intentional: read Camera configuration first, then
 the graph facts, backend facts, and finally the stable observation identity.
-The JSON-safe `RenderInspection` projection names the output contract directly:
+The JSON-safe `RenderInspection` projection keeps renderer lifecycle facts and
+the output contract in separate named subtrees. Read `renderer.inspect().output`
+for output facts; do not infer output state from renderer-level fields:
 
 | Field | Meaning | Owner |
 |:--|:--|:--|
-| `outputTransform` | `forgeax::standard::output-transform` | Standard post chain |
-| `displayEncoded` | final output is display encoded | Output Transform |
-| `intermediateFormat` | linear intermediate format (`rgba16float`) | Standard target owner |
-| `surfaceStorage` / `surfaceDisplay` | raw storage and display surface formats | surface adapter |
-| `endpoint` | `surface.storage.raw` | backend adapter |
-| `capability` / `error` | structured availability and recovery facts | RHI/render surface |
+| `output.outputTransform` | `forgeax::standard::output-transform` | Standard post chain |
+| `output.displayEncoded` | final output is display encoded | Output Transform |
+| `output.intermediateFormat` | linear intermediate format (`rgba16float`) | Standard target owner |
+| `output.surfaceStorage` / `output.surfaceDisplay` | raw storage and display surface formats | surface adapter |
+| `output.endpoint` | `surface.storage.raw` | backend adapter |
+| `output.capability` / `output.error` | structured availability and recovery facts | RHI/render surface |
 | `observation.observationId` / `frameId` | stable correlation refs | renderer observation owner |
 
+### Auto exposure and 3D LUT authoring
+
+Exposure is a Camera-owned closed union. Manual exposure is a positive
+multiplier; auto exposure carries a fallback, EV compensation, bounded EV
+range, and non-negative adaptation rates. The renderer owns the GPU receipt,
+but the author owns the Camera input:
+
+```ts
+world.set(camera, Camera, {
+  exposure: { kind: 'auto', fallback: 1, compensationEv: 0,
+    rangeEv: [-4, 4], rates: [2, 1] },
+}).unwrap();
+
+const output = renderer.inspect().output;
+if (output.autoExposure?.receipt.committed !== true) {
+  throw new Error(output.error?.hint ?? 'auto exposure is not committed');
+}
+```
+
+Color grading uses the ordinary shared `TextureAsset` route. Import/cook the
+3D LUT through Pack/Catalog, load the shared handle by its GUID/source key, and
+bind it to the Camera; there is no second LUT registry or URL-derived identity:
+
+```ts
+world.set(camera, Camera, {
+  colorLut: world.allocSharedRef('TextureAsset', lutHandle),
+  colorLutStrength: 0.75,
+}).unwrap();
+const lut = renderer.inspect().output.standardLut;
+// Match lut.sourceKey and lut.receipt.frameId to the submitted FrameReceipt.
+```
+
+`output.autoExposure`, `output.standardLut`, and `output.error` are detached
+facts. A fallback or last-known-good row is a recovery observation, not proof
+that a physical Browser/Dawn workload or timing gate completed.
+
 `renderer.inspect()` and `renderer.observe()` never carry ROI pixels, scanlines,
 brightness or level metrics. The hello-fxaa `hello-fxaa/dark-gradient/v1`
 fixture report owns those fields and records the fixed camera, low-light scene,
@@ -508,6 +817,83 @@ gate exercises the browser delivery path. Runtime inspection uses the public
 belongs in `packages/render/bench` and its dev-verify producer. Render does
 not expose a timing controller or a second membership-specific API.
 
+## TAA accumulation and private stability
+
+TAA reconstructs unjittered current color, validates reprojected depth, and
+accumulates HDR using luminance-preserving compressed-domain weights. History
+depth validation recognizes mixed current-depth coverage, following Three's
+TRAA edge exception: background/geometry and depth-discontinuous 3x3 edges
+may retain clipped history instead of alternating between accumulated and
+raw current color. Uniform-depth disocclusion, absent current geometry,
+out-of-bounds reprojection, invalid global history, motion and reactivity
+retain their rejection or weighting behavior. The GPU coverage regression
+executes the complete resolve, including the non-edge negative cases.
+History clipping uses YCoCg bounds. After eight accepted stationary frames, its bounds
+cover the texels supporting the reconstructed neighborhood; motion, rejection,
+or reactivity resets that private age. The history still updates every frame:
+this is not a frozen screenshot or an appearance acceptance claim.
+
+The private age continues to 128 accepted stationary frames without another
+surface. History weight stays at 0.95 through frame 64, then smoothly rises to
+0.99 by frame 128 to reduce residual phase response. The eight-frame clipping
+footprint remains unchanged. Clipping relaxation runs earlier, from accepted
+frame 8 through frame 64, while the 0.95 history weight still permits responsive
+accumulation. Releasing it only after increasing history weight preserves a
+biased clipped mean and causes prolonged static drift. Once settled, a single phase's unsupported
+color does not erase accumulated subpixel coverage: clipping resumes only
+after eight consecutive unsupported samples in the same signed dominant RGB
+direction. Finding support or reversing direction breaks that streak.
+Persistent unmarked color changes therefore restore color clipping within one
+complete jitter cycle. This color correction preserves the accepted stationary
+age and its reconstruction footprint; it must not collapse the next frame's
+neighborhood from 5x5 to 3x3. Motion,
+reactivity or rejection immediately reset
+the age and restore fast recovery; this delay is necessary because zero
+velocity alone does not establish settled radiance.
+
+An optional secondary-source reactivity texture joins the scene reactive lane
+before history weighting and stability counting. Standard forwards SSR's
+existing hit-source mask through a typed sampled read; TAA takes a conservative
+7x7 maximum at that texture's resolution. This covers the measured vacated
+reflection edge missed by the former radius-one footprint; it is a bounded
+dilation, not an arbitrary-speed reflected-motion guarantee. Reflected source motion can therefore
+reset a stationary receiver without changing the receiver's velocity or depth.
+The disabled path binds existing temporal data but does not sample it as a mask;
+no extra texture or pass is allocated. The 658-frame Browser and Dawn feedback
+variant checks secondary-motion reset and recovery; Dawn additionally verifies
+a failing control that ignores the mask. Each cyclic input step checks the
+Karis recurrence from the actual stored history against its adjacent FP16
+values; an independent infinite-precision tail detects accumulated bias.
+The premature high-weight counterexample must also fail. This does not establish visual
+convergence or ghost-free SSR.
+
+Color writeback stochastically selects adjacent representable FP16 values before
+attachment conversion. This prevents consistently downward conversion from
+accumulating a dark history bias without widening the history textures. Its
+deterministic pixel/frame hash shares one RGB threshold, leaves alpha and
+temporal metadata unchanged, and does not freeze the jitter sequence. Browser
+and Dawn run the same 528-frame raster-feedback regression against an analytic
+compressed-HDR recurrence; this precision gate is not visual acceptance.
+
+| Ping-pong history | Format | Consumer |
+|:--|:--|:--|
+| Color | `rgba16float` | TAA and downstream HDR processing |
+| Motion, depth, reactivity | `rgba16float` | Unchanged `temporal-v1` metadata, including Motion Blur |
+| Stationary age and settled clipping streak | `r8unorm` | TAA only; never stored in the reactive lane |
+
+The private byte uses codes 0–128 for stationary age and 129–170 for one
+through seven unsupported samples in six signed RGB directions. The eighth
+matching sample restores clipping and resets age. This is one encoded state,
+not an additional attachment or a change to downstream temporal metadata.
+Browser and Dawn raster-feedback tests cover phase-local coverage, unmarked
+color steps, and a falsifier that permanently disables clipping.
+
+These six surfaces share the existing successful-submit, abort, replacement,
+and retirement lifecycle. Texture accounting is 34 bytes per output pixel;
+`inspect().temporal.resources` includes active, candidate, and retiring states.
+Fullscreen pipeline targets come from the declared attachment format list,
+not from inspecting shader source text for a particular output structure.
+
 ## Motion Blur temporal consumer
 
 The Standard camera may carry the presence-enabled `MotionBlur` component. Its
@@ -664,69 +1050,135 @@ infer state from URLs, or repair a producer failure. Aggregate counts are
 derived from the observations, so an AI can inspect first, repair or recook the
 producer, and retry without guessing at hidden renderer state.
 
-### Large Instances ownership
+### Renderer-owned Instances and CPU bounds
 
-> [!IMPORTANT]
-> World owns `Instances.transforms`. Create, replace and read instance matrices
-> through ECS without constructing a Renderer. A scene remains usable by another
-> Renderer after the first is disposed; glTF SceneAssets retain their matrices.
+`Instances` is a lightweight ECS association containing only a
+renderer-owned `collectionId`. Create and mutate the canonical packed matrices
+through the same `renderer.instances` owner; it validates mat4 stride, keeps
+revision/capacity/dirty ranges, and returns detached inspection snapshots.
+
+```ts
+function identityMatrices(count: number): Float32Array {
+  const matrices = new Float32Array(count * 16);
+  for (let index = 0; index < count; index += 1) {
+    const offset = index * 16;
+    // Column-major identity, with a deterministic layout so the instances are visible.
+    matrices[offset] = 1;
+    matrices[offset + 5] = 1;
+    matrices[offset + 10] = 1;
+    matrices[offset + 15] = 1;
+    matrices[offset + 12] = (index % 100) * 2;
+    matrices[offset + 14] = Math.floor(index / 100) * 2;
+  }
+  return matrices;
+}
+
+const collection = renderer.instances.create({
+  transforms: identityMatrices(instanceCount),
+}).unwrap();
+world.spawn(
+  { component: MeshFilter, data: { assetHandle: cube } },
+  { component: MeshRenderer, data: {} },
+  { component: Instances, data: { collectionId: collection.collectionId } },
+);
+
+const patch = identityMatrices(1);
+patch[12] = 4;
+renderer.instances.update(collection.collectionId, {
+  start: 0,
+  transforms: patch,
+});
+
+// Replacement keeps the logical identity and publishes a new revision.
+renderer.instances.replace(collection.collectionId, identityMatrices(instanceCount + 1));
+const current = renderer.instances.inspect(collection.collectionId).unwrap();
+const detached = renderer.instances.snapshot(collection.collectionId).unwrap();
+renderer.instances.release(collection.collectionId);
+```
 
-| Data | Owner |
+The lifecycle is deliberately one owner: `create` allocates canonical CPU
+storage, `replace` publishes a complete new revision (and grows capacity when
+needed), `update` validates a bounded matrix interval and records its dirty
+range, `inspect` returns identity/count/capacity/revision, `snapshot` returns a
+detached matrix copy plus dirty ranges for extraction, and `release` makes the
+collection id terminal. A caller never provides a GPU buffer or maintains
+backend-specific chunks. `detached.transforms` is an observation, not mutable
+renderer state.
+
+Render snapshots one collection per frame and derives CPU union bounds from the
+mesh AABB, entity world matrix, and detached matrices. Direct, GPU-driven, and
+backend fallback lanes consume that same projection; internal GPU chunks never
+become ECS or game-side state. Missing, malformed, or empty collections fail
+closed or remain a conservative no-cull result without manufacturing an
+identity instance. The initial payload must contain valid matrices: an
+all-zero mat4 has a zero homogeneous `w` and can produce a blank frame. Do not
+add matrix bytes, bounds, or chunk fields to the public `Instances` component or
+duplicate this renderer fact in Pack/asset state.
+
+#### Instance inspection and recovery
+
+`renderer.inspect().instanceCollections` is detached, bounded evidence for
+every live collection. Each row contains:
+
+| Field | Meaning |
 |:--|:--|
-| Instance matrices and entity lifecycle | World component storage |
-| Detached instance snapshot and content revision | Per-renderer projection |
-| GPU allocation, binding-sized chunks and uploaded revision | Existing renderer device generation |
-
-Small managed arrays keep the existing BufferPool size classes. Arrays larger
-than the largest pooled class use dedicated allocations and are released instead
-of retained in a large free bucket. The same authoring path supports 1,500,
-10,000 and 20,000 instances without application chunking.
-
-Each renderer compares complete extracted matrices against its own prior
-projection. Identical input retains the projection revision; a changed input
-publishes a complete new snapshot. Upload completion belongs to each GPU
-resident, not to a shared authoring dirty-range or a snapshot read. Stable
-residents skip upload; changed or new residents upload the complete applicable
-binding chunk. A renderer that skips frames still receives every latest value.
-
-`renderer.inspect().instanceCollections` reports derived projection identity,
-count, revision and upload/residency facts. These IDs never appear in components
-or SceneAssets and cannot be used to author a scene. Residency here describes
-the direct/chunked instance buffers; GPU-driven primary rendering is reported
-by `inspect().renderScene` and does not retain those unused buffers.
-
-Device loss uses the existing `renderer.recover()` candidate-generation protocol.
-The World stays authoritative; candidate preparation initializes replacement
-instance buffers from the complete snapshot before publication. Main and shadow
-passes share these residents, so the first recovered frame performs no cold
-instance upload for the prepared visible workset. Instances
-introduce no additional recovery API or lifecycle.
-
-Shader preparation, layouts and uploads all consume `RhiDevice.caps.storageBuffer`.
-Material boot variants include only axes declared by the material manifest.
-The Dawn gate restricts the advertised capability on a real WebGPU device and
-verifies uniform bindings below and above 128 instances with material pixels,
-GPU validation and stable-upload receipts.
-
-Population checks use the same World component route:
+| `collectionId`, `count`, `capacity`, `revision` | Logical identity and canonical authoring revision. |
+| `residentGeneration`, `lane` | Device generation and the selected `direct-storage`, `chunked-storage`, `direct-uniform`, `chunked-uniform`, `unresident`, or `unavailable` lane. |
+| `dirtyRanges`, `uploadRanges` | Canonical pending edits and the ranges uploaded by the current resident. |
+| `uploadedBytes`, `requestedBytes`, `supportedBytes` | Measured upload and admission byte facts; unsupported limits remain explicit. |
+| `backend`, `owner` | Backend identity and the fixed owner `renderer.instances`. |
+| `error` | A structured record-stage failure with `code`, `expected`, `hint`, and typed `detail` facts. |
+
+Authoring failures use the same closed `InstanceCollectionError` contract.
+For example, an invalid stride is rejected before publication and carries
+typed facts instead of requiring message parsing:
+
+```ts
+const result = renderer.instances.create({ transforms: new Float32Array(17) });
+if (!result.ok) {
+  const { code, expected, hint, detail, facts } = result.error;
+  // facts expose requestedBytes, supportedBytes, backend, owner, cause, and
+  // recovery; detail retains operation metadata. Repair the payload and retry.
+  void code;
+  void expected;
+  void hint;
+  void detail;
+  void facts;
+}
+```
+
+After a `device-lost` transition, call `await renderer.recover()` and retry the
+same draw request. The renderer drops generation-owned residents, keeps the
+canonical collection, and uploads every matrix into the new resident before
+recording; it does not reuse an old partial dirty range for uninitialized GPU
+memory. If inspection reports `unavailable`, follow its `error.detail.recovery`
+and repair the named capability/producer before retrying.
+
+The large-instance smoke exercises the real Dawn path for all admitted sizes:
 
 ```bash
-pnpm exec vitest run --config vitest.browser.config.ts --project=browser apps/parity/instancing-static/src/__tests__/instances.browser.test.ts
-INSTANCE_COUNT=20000 SMOKE_MIN_FRAMES=600 SMOKE_DURATION_MS=0 pnpm --filter @forgeax/parity-instancing-static smoke
+for count in 1500 10000 20000; do
+  INSTANCE_COUNT=$count SMOKE_MIN_FRAMES=600 SMOKE_DURATION_MS=0 \
+    pnpm --filter @forgeax/parity-instancing-static smoke
+done
 ```
 
-### Instances CPU bounds contract
+Each run must retain one logical collection, submit real work, upload on its
+first resident frame, and report zero transform-upload bytes on unchanged
+frames. Browser WebGPU acceptance additionally uses the browser/dev-server
+transport through the same production fixture and parameterizes the same three
+populations:
 
-`Instances` remains author data containing only packed local transforms. The
-renderer derives a CPU union bound from each mesh AABB, entity world matrix,
-and every instance matrix. The union cache is scoped by World/entity and
-invalidated by mesh, entity-transform, instance-array, slot removal, and
-generation changes. Missing, malformed, or empty instance data is a
-conservative no-cull result; it never creates a synthetic identity instance.
-The GPU path keeps the mesh-local AABB and performs per-instance visibility,
-while the CPU path uses the derived union only to avoid dropping an entity
-whose origin is outside the view. Do not add `bounds` to the public
-`Instances` component or duplicate this renderer fact in Pack/asset state.
+```bash
+pnpm exec vitest run --config vitest.browser.config.ts --project=browser \
+  apps/parity/instancing-static/src/__tests__/instances.browser.test.ts
+```
+
+The Browser test submits 600 frames for each population, asserts a real
+`webgpu` backend, captures the first and stable `instanceCollections` upload
+witnesses, reads the presented canvas through the browser compositor, and
+requires visible spread at three or more grid samples with zero renderer/RHI
+error events. Dawn structural evidence alone is not a browser validation.
 
 ## Points and Lines authoring (M1)
 
@@ -865,6 +1317,10 @@ the custom parameters on the returned root MaterialAsset. Compiler and loader
 project that published contract without adding fields based on a Pass module.
 Physical layer declarations remain sparse. A custom full-shader material does
 not acquire Standard semantics by adding a shadow Pass or a `surface` slot.
+When a producer also publishes `vs_main` and `vs_scene_index` for a controlled
+full-custom program, the same prepared material can use the GPU-driven indirect
+lane; ordinary custom WGSL without that ABI remains on its direct/specialized
+lane.
 
 The custom WGSL implements only `evaluate_surface`; it does not declare
 stages, bindings, lighting, or output code. The Engine composes the result
@@ -886,7 +1342,7 @@ consumer never re-infers physical layers from `SurfaceData`.
 |:--|:--|:--|
 | base-only Standard | no second physical layer | Deferred plus Forward and ShadowCaster |
 | Standard with a physical layer | physical layer present | Forward plus ShadowCaster |
-| full-custom escape hatch | no Standard plan | authored custom pass contract |
+| full-custom escape hatch | no Standard plan | authored custom pass contract; GPU-driven only with a published direct/scene-index ABI |
 
 ## Points and Lines runtime contract
 
@@ -959,18 +1415,32 @@ state published by `World.update()`.
 
 ## Persistent render scene
 
-The ordinary single-World path bootstraps one renderer-owned CPU projection,
-then drains the World's bounded change journal. A no-change frame reuses the
-last visible snapshot without traversing renderable archetypes; transform
-changes update only their stable projection slots. Unrelated gameplay
-component writes do not invalidate render state.
+Every attached World composition bootstraps one renderer-owned CPU projection,
+then consumes each World's component and shared-reference change versions. One identity-based update
+publication merges content, root transforms, and instance changes, including
+when all occur in the same frame. Its GPU projection compares affected matrix
+and metadata rows before uploading them. An unchanged frame retains its existing
+snapshot; unrelated gameplay component writes do not invalidate render state.
+There is no exclusive transform/instance scene admission followed by a separate
+rebuild implementation. Missing producer evidence causes conservative source
+extraction into the same retained projection. World reordering and catalog
+reconciliation preserve surviving slots and their submitted temporal history.
 
 Mutable shared payloads use the same explicit-dirty rule: mutate the resolved
 payload, then call `world.sharedRefs.markChanged(handle)`. The renderer compares
-one monotonic shared-ref epoch on the no-change path, drains the bounded exact
-mutation journal when it advances, and refreshes only projection slots indexed
-by the changed material handle. Journal overflow and topology-changing material
-edits remain explicit full-reconcile reasons rather than silent partial state.
+one monotonic shared-ref epoch on the no-change path, reads changed handles
+when it advances, and refreshes the projection slots indexed by changed
+material or mesh handles. Missing source evidence requests conservative
+source reconciliation. Camera, light, and environment facts refresh independently
+of geometry publication; their edits do not discard retained geometry.
+
+Instance collection revisions refresh only their consumers. Visibility and
+parent changes refresh the affected subtree, and joint changes refresh the
+retained skin consumers. Shadow pass facts belong to each retained renderable;
+frame ownership is derived before camera culling so offscreen casters remain
+available. CPU visibility, occlusion, and LOD consume this same projection on
+every frame, including frames submitted through GPU-driven raster. No scene
+classification enables a second extraction or visibility implementation.
 
 When `RhiCaps.storageBuffer` is available, the same projection owns persistent
 Primitive, Instance, Transform, DrawTemplate, and Material GPU tables. The
@@ -998,11 +1468,143 @@ reason. The nested `gpu` status is one of `inactive`, `unsupported`, `resident`,
 `rebuild-pending`, or `error`; resident state additionally reports capacity,
 upload ranges and bytes, grows, clears, rebuilds, and no-change frames. The
 `gpuDriven` inspection reports whether stable frames materialized or validated
-GPU-owned rows and whether candidate or batch topology bytes were uploaded.
+GPU-owned rows and whether candidate or batch topology bytes were uploaded. Its
+lifetime `residencyValidationScans` and `residencyValidationCacheHits` counters
+make the CPU residency boundary auditable: an unchanged persistent frame should
+reuse the producer rows, while mesh, device, pipeline, or catalog generations
+force a new validation.
 GPU and renderer contract errors arrive through the single `renderer.subscribe`
 event stream (`event.kind === 'error'`); the renderer does not expose a second
 error listener registry.
 
+## GPU-driven PBR / shadow / skin navigation
+
+The shortest public declaration uses the same `Materials.standard` producer as
+the runtime and imported-skin carriers. `alphaCutoff` is the Alpha Mask
+contract; `castShadow` publishes the matching ShadowCaster pass.
+
+```ts
+import { Materials } from '@forgeax/engine/render';
+
+const material = Materials.standard({
+  baseColor: [1, 1, 1, 1],
+  alphaCutoff: 0.5,
+  castShadow: true,
+});
+const materialHandle = world.allocSharedRef('MaterialAsset', material);
+void materialHandle;
+```
+
+| Candidate | Main GPU lane | Shadow GPU lane | Closed result |
+|:--|:--:|:--:|:--|
+| Standard opaque or Alpha Mask, finite resources | supported | supported | `gpu` |
+| Standard skin with imported or explicitly authored finite animated bounds | supported | supported | `gpu` |
+| Skin bounds missing or non-finite | refused | refused | `cpu-deformation` |
+| Capable resource/pipeline not ready | refused | refused | `blocked` (`resource-not-ready`) |
+| Blend, transmission, morph, custom without a published ABI, or unsupported topology | refused | refused | `cpu-semantic` |
+| ABI-backed custom Surface/full-custom row within the producer page | supported | supported when a ShadowCaster ABI is published | `gpu` |
+
+The custom row is deliberately about the published producer contract, not a
+shader-name allowlist. A custom program is eligible only when its cooked receipt
+contains matching direct/scene-index entries, reflected resources, vertex inputs,
+and a schema-derived row no larger than the 512-byte GPU Scene page. Custom
+storage-buffer resources, renderer-local/video sources, and pass attachments that
+have no corresponding prepared owner remain on their specialized lane until that
+owner publishes the missing binding and recovery contract. The legacy
+[`custom-shader` demo](../../apps/hello/custom-shader) is direct-only by design;
+it does not publish `vs_scene_index`, so it is not evidence for the indirect lane.
+
+Clustered local lights and SSAO use the same group-2 lighting bindings in direct
+and scene-index programs, including custom Surface programs. These switches do
+not disable GPU-driven admission. SSAO requires `renderPath: 'deferred'` to
+produce depth and normals. SSR's fallback MRT selects the corresponding
+scene-index fragment variant; background probe capture preserves the display
+view's GPU submission. Each pass selects its own material slots and color
+attachments. Shared materials at different local probes retain separate binding
+classes so deduplication cannot substitute one object's reflection environment.
+
+
+### Static TextureAsset admission
+
+Static PBR and Alpha Mask resources are admitted only from registered shared
+`TextureAsset` and `SamplerAsset` payloads. The resource-class identity is the
+sorted handle-pair projection used by the prepared material; it is not an
+array-position guess. Dynamic `RenderTargetTextureSource` and video sources
+remain their own CPU semantic boundary and are never coerced into a static
+GPU texture candidate.
+
+The focused topology fixture allocates and resolves real static shared refs for
+resource classes `1`, `16`, and `256`, then builds `100,000` candidates for each
+class. It is structural admission evidence, not a physical-GPU benchmark:
+
+```sh
+FORGEAX_SKIP_HARNESS_SYNC=1 pnpm exec vitest run --project=@forgeax/engine-render \
+  packages/render/src/__tests__/gpu-driven-batch-topology-pbr.unit.test.ts \
+  --no-file-parallelism --reporter=dot
+```
+
+### Point and Spot shadow authoring → view inspection
+
+`PointLight` and `SpotLight` shadow views are public light facts, not a hidden
+GPU slot API. A Spot author declares a companion `Transform`, outgoing
+`direction`, cone angles in degrees, and the embedded shadow policy:
+
+```ts
+import { SpotLight } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+
+world.spawn(
+  { component: Transform, data: { pos: [0, 5, 0] } },
+  {
+    component: SpotLight,
+    data: {
+      direction: [0, -1, 0],
+      range: 20,
+      innerConeDeg: 15,
+      outerConeDeg: 35,
+      castShadow: true,
+      mapSize: 1024,
+      pcfKernelSize: 3,
+    },
+  },
+);
+```
+
+| Author fact | Contract |
+|:--|:--|
+| `direction` / `Transform` | Outgoing direction plus the light position; both are required for a useful view |
+| `range` | Meters; default `10` |
+| `innerConeDeg` / `outerConeDeg` | Degrees; `0 ≤ inner < outer ≤ 90`, defaults `0` / `45` |
+| `castShadow` | Defaults `true`; set `false` for the explicit no-shadow case |
+| `mapSize`, `pcfKernelSize` | Shadow map resolution and odd PCF width; defaults `2048` / `3` |
+| `cookie` / `projector` | Optional GUID-backed static texture facts; dynamic target/video sources stay outside GPU admission |
+
+After a successful `draw`, inspect the same renderer projection:
+
+```ts
+const channels = renderer.inspect().renderScene.gpuDriven.channels;
+const spotViews = channels.filter((channel) => channel.viewPass === 'spot-shadow');
+const pointFaces = channels.filter((channel) => channel.viewPass === 'point-shadow');
+void spotViews; // lane, reason, drawCount, and viewIndex are bounded facts.
+void pointFaces; // point views additionally expose the cube `face`.
+```
+
+The per-view cache is keyed by light identity and view parameters. A cache hit
+does not dispatch or record a duplicate shadow view. The inspection labels and
+identity helpers are anchored in
+[`spot-light.ts`](src/components/spot-light.ts),
+[`shadow-views.ts`](src/gpu-driven/shadow-views.ts), and
+[`frame.ts`](src/record/frame.ts); repair the producer named by a structured
+`failure.detail` before retrying the unchanged frame.
+
+For offline recovery, read `renderer.inspect().renderScene.gpuDriven.channels`.
+A blocked channel carries one bounded `failure` projection with the same
+closed `code`, `detail.owner`, `detail.reason`, and `detail.recovery` that the
+renderer error stream emits. Repair that owner, recook or republish its
+producer artifact, and retry the identical frame; `hint` is explanatory text,
+not a value to parse. A blocked capable candidate is not permission to issue a
+duplicate CPU draw.
+
 ## GPU-driven view kernel
 
 `BatchTopology` groups eligible rigid draw items by immutable geometry,
@@ -1012,41 +1614,56 @@ non-indexed five-word indirect command. A per-view typed graph records
 `reset -> frustum/compact -> finalize` over persistent candidate and batch
 buffers. The compute path validates generation and active flags, composes the
 primitive world transform with each ordinary instance-local transform, writes a
-compact `(instanceIndex, materialIndex)` stream, sets explicit overflow flags,
-and emits indirect arguments with `firstInstance = 0`.
-
-The Standard frame activates the production raster lane when compute, storage
-buffers, and indirect drawing are available. The current lane accepts opaque,
-rigid default-unlit triangle-list passes with batch-stable render state,
-ordinary instances, indexed or non-indexed geometry, multiple submeshes and
-material slots, and the canonical `12F` vertex layout. It also accepts persistent rigid multi-World
-composition. Candidates come from the complete persistent projection rather
-than the CPU-visible snapshot. The same typed graph imports the scene and mesh
-buffers, runs the three compute passes, and consumes generated arguments with
-`drawIndexedIndirect` or `drawIndirect`. Entities accepted by that lane are not
-also validated, uploaded, or recorded by the CPU forward loop on a stable
-frame.
-
-clustered, PBR and custom shader variants, texture/sampler/video resource bindings,
-transparent meshes, skinning, morphing, non-canonical layouts, and shadow views
-keep explicit CPU or specialized lanes. WebGL2 selects capability fallback from
-the same persistent projection; it does not emulate compute. Visibility and
-hierarchy changes, non-rigid multi-World composition, and some prepared-resource
-changes still require bounded reconcile work. The implemented lane proves a
-zero-upload stable data path and broad rigid geometry coverage, but hardware
-100k timing, schema-derived material variants, stable world identities, and
-GPU-driven shadows remain required before declaring P3 complete.
-
-The bounded inspection reports topology revision, candidates, batches, visible
-capacity, buffer capacities, update count, upload bytes, rebuild count, and CPU
-fallback rows. RhiNull verifies graph dependency order and stable-frame zero
-work; Dawn and Chromium verification consume indexed, non-indexed,
-multi-submesh, and instanced arguments, read persistent scene tables in the
-vertex path, and compare the resulting pixel. The renderer-level RhiNull
-integration also proves that the built-in Standard graph contains the compute chain
-before `main`, including rigid multi-World composition, without GPU plus CPU
-duplicate draws. The renderer retains one graph, one compile owner, one
-encoder, and one submit route.
+compact `(meshProjectionRow, materialOrPaletteRow)` stream, sets explicit
+overflow flags, and emits indirect arguments with `firstInstance = 0`. The low
+bit of the candidate admission word controls submission; its upper bits carry
+the batch-local projected mesh row. Rigid rows address the generated material
+table, while skin rows address the persistent palette through
+`Instance.customDataStart`.
+
+The Standard frame activates the production raster lane only when compute,
+storage buffers, indirect drawing, and producer-owned Standard PBR artifacts
+are all ready. It covers opaque and Alpha Mask rigid/skin candidates whose
+geometry, resource class, reflection, palette address, and (for skin) finite
+producer-authored bounds satisfy the prepared contract. Main and directional,
+spot, or point shadow views consume the same scene and topology, but keep
+view-local visibility and projection bindings. Ownership is per draw item and
+view pass, so one draw can be GPU-owned in the main/shadow channels while an
+unrelated semantic pass remains CPU-owned.
+
+Transparent/blend, transmission, morph, unsupported prepared variants, and
+skin without a producer-authored conservative bound stay on an explicit CPU
+semantic or CPU deformation lane. A producer-published custom Surface or
+full-custom ABI follows the same GPU lane when its selected Pass passes the
+prepared contract; an ordinary custom WGSL artifact without that ABI remains
+CPU/specialized. WebGL2 selects capability
+fallback from the same persistent projection; it does not emulate compute.
+Missing capable-path artifacts and failed resource publication are structured
+errors that block graph promotion rather than silently drawing the same item a
+second time through CPU semantics.
+
+> [!WARNING]
+> A GPU selector overflow is fail-closed: `finalize` emits zero indirect
+> instances for the affected batch and inspection reports `overflow=true`.
+> The last-known-good resource generation remains authoritative until the
+> producer can rebuild with sufficient capacity. Missing skin bounds are also
+> intentionally conservative: they remain CPU deformation work; bind-pose
+> bounds are never invented as animation bounds.
+
+The bounded `gpuDriven.channels` inspection reports the selected lane and
+closed reason for each view pass. Blocked promotion additionally exposes the
+producer-owned `failure` (`code`, `expected`, `hint`, and typed `detail`) so an
+AI caller can branch on owner/recovery without decoding an error string. The
+same `GpuDrivenPreparationError` is delivered through the renderer error
+stream. The inspection also reports topology revision, candidates,
+batches, visible capacity, buffer capacities, update count, upload bytes,
+rebuild count, overflow, retry count, and last-known-good generation. RhiNull
+verifies graph dependency order and stable-frame zero work; local Dawn verifies
+the command, binding, palette, shadow-view, and readback contracts. The
+renderer-level integration also proves that the built-in Standard graph
+contains the compute chain before `main`, with no GPU plus CPU duplicate draws.
+The renderer retains one graph, one compile owner, one encoder, and one submit
+route.
 
 > [!NOTE]
 > Non-rigid multi-World composition, skinned lanes, visibility/hierarchy
@@ -1056,6 +1673,28 @@ encoder, and one submit route.
 > semantics; later coverage can make those changes entity-local without adding
 > another scene authority.
 
+### Offline inspect → repair owner → retry
+
+Use the detached channel to identify the next owner without opening a browser
+or reading live GPU objects:
+
+```mermaid
+flowchart LR
+  A["inspect gpuDriven.channels"] --> B{"lane / reason"}
+  B -->|"gpu / none"| C["record the same graph"]
+  B -->|"blocked / resource-not-ready"| D["repair failure.detail.owner"]
+  D --> E["recook or publish the receipt"]
+  E --> F["retry the identical frame request"]
+```
+
+The three public navigation entries are [`shader`](../shader/README.md#gpu-driven-pbr--shadow--skin-navigation),
+[`runtime`](../runtime/README.md#gpu-driven-pbr--shadow--skin-navigation), and
+this render owner. The two executable carriers are
+[`hello-skin`](../../apps/hello/skin/README.md#gpu-driven-skin-carrier) and
+[`hello-fbx-skin`](../../apps/hello/fbx-skin/README.md#gpu-driven-fbx-carrier).
+Their Dawn smoke commands remain independent evidence; RhiNull proves graph
+ownership and deterministic lane facts only.
+
 Features are supplied through the construction options (`features: [...]`) and
 enter the same host-owned extract → plan → graph projection path. The public
 `Renderer` intentionally has no install/uninstall methods: optional capability
@@ -1163,6 +1802,34 @@ targets, and draw/dispatch commands. Graph buffer and texture access is derived
 from those roles; producers never author a second `reads`/`writes` ledger and
 never receive an encoder or submit authority.
 
+Prepared material-input layouts accept `particleInputLanes` from 1 through 4
+(omission selects the canonical one-lane layout). The count is valid only for a
+material-input vertex layout. Render derives its instance stride and attributes
+from the base layout and uses the same complete multi-stream descriptor in the
+PipelineSpec cache identity. Invalid counts fail during resource preparation.
+
+A prepared pipeline with empty `colorFormats` uses the depth-only route and
+preserves its declared `depthFormat`, depth state and complete vertex streams.
+A vertex-only shader needs no fragment entry. For a vertex-index-generated draw,
+declare `vertexLayout: 'none'` on the draw and supply the prepared empty group
+when the shader has no resources. This is depth-target rendering, not automatic
+registration as a Standard light-view shadow caster.
+
+For light-view participation, declare a `shadow-caster` plan pass with the same
+draw vocabulary and a depth32float, zero-color graphics program. Standard owns
+the light-view binding, atlas, viewport and pass replication; the feature owns
+only geometry and instance inputs. It reuses the normal prepared draw encoder
+and the same graph buffer imports. Active GPU casters disable static directional
+atlas reuse because ECS mesh epochs do not describe GPU buffer contents.
+
+The graph projects a feature's leading compute prefix before shadow views until
+the first scene-target dependency or ordinary raster. Remaining work stays at
+the normal scene contribution boundary. A caster whose projection is late reads
+the prior submitted instance data (initially empty); it must not be described as
+current-frame simulation. Owner-local pipeline implementations use
+`contributeShadowFeatures` with `addTypedShadowPasses`; graph construction and
+these helpers are not added to the public Render root.
+
 ### Five render terms
 
 | Term | Meaning | Owner |
@@ -1355,9 +2022,20 @@ sibling-loop report or an authored manifest. Read identity, generation, evidence
 level, and closed failure fields before following the named owner recovery action.
 Submit the same consumer request and reinspect after recovery. The route returns
 detached facts only: no live GPU handle, second owner, or second ledger is exposed.
-Missing or mismatched receipts remain
-`fallback-only` with zero SSR work; SSR v1, Hi-Z, ray marching, temporal resolve,
-compose, and history are out of scope.
+Missing or mismatched receipts remain `fallback-only` with zero SSR work. The
+current renderer may expose admitted structural Hi-Z, trace, temporal, compose,
+and history facts, but no single backend snapshot or non-black canvas is an SSR
+v1 acceptance result; use paired Browser/Dawn readback and the closed-loop gates
+before promoting that status.
+
+The canonical paired carrier is `apps/hello/ssr`. It runs the same fixture at
+`http://127.0.0.1:4173/?forgeax-evidence=ssr` and
+`dawn://hello/ssr?forgeax-evidence=ssr`, records 300-frame identity-bound
+readbacks, and keeps visual rows in the form `observed` / `verdict` /
+`confidence`. Its performance lane derives the 1920x1080 descriptor and checks
+it against `estimateSsrSpatialMemory`; timestamp or paired-lane absence remains
+blocked.
+
 ## Standard dynamic MeshAsset candidates
 
 The Renderer owns one bounded candidate lifecycle for geometry produced by an
@@ -1474,6 +2152,28 @@ physics.admitDerivedShapeCandidate(physicsCandidate, () => {
 // After World.update succeeds, inspect Physics publication/failure and draw.
 ```
 
+For a group of physical bodies, pair `physics.admitDerivedShapeCandidates`
+with `renderer.acceptDynamicGeometryCandidates`. The latter accepts one prepared
+candidate per distinct render entity, all in the same attached World and fixed
+step, using the existing candidate budget. It retains previous unpublished
+credentials and GPU leases until every MeshFilter swap succeeds. A later-member
+refusal restores earlier bindings; if restoration cannot be proven it throws so
+the paired physics owner requires reconstruction. Topology history is invalidated
+once after the whole successful group. Retain every returned accepted credential
+and inspect its normal FrameReceipt; callback success alone is not a draw receipt.
+
+```ts
+physics.admitDerivedShapeCandidates(physicsCandidates, () => {
+  const admitted = renderer.acceptDynamicGeometryCandidates(geometryCandidates, {
+    world,
+    fixedStep: world.getResource(FixedTime).tick,
+  });
+  if (!admitted.ok) return err(admitted.error);
+  acceptedGeometries = admitted.value;
+  return ok(undefined);
+}).unwrap();
+```
+
 The commit must return immediately after its complete binding change, without
 additional fallible work. On physical preparation/native failure it is not called;
 cancel the still-prepared geometry using its normal owner. On a refused commit,
@@ -1573,3 +2273,33 @@ example; Renderer never registers or mints an asset. Provider/Catalog/GUID cold
 loading therefore continues through the existing route; a producer that needs
 a custom voxel artifact owns that schema and loader outside the Engine, while
 its projected standard mesh enters this candidate path.
+
+### Residency resource retirement
+
+Scope-owned `GpuBuffer` and `GpuTexture` registrations end when their explicit
+`destroy()` succeeds. Failed destruction keeps scope ownership for cleanup;
+scope termination still cleans remaining resources in reverse adoption order.
+Mesh retirement waits for outstanding submission and candidate leases before
+releasing that registration, so repeated mesh replacement does not retain all
+destroyed handles in the renderer generation. Caller-held handles retain their
+existing observable state; resource disposal is distinct from JavaScript GC.
+
+### Targeted spatial inspection
+
+`renderer.bounds(world, entity)` returns a detached world-space AABB from the last extracted composition, including the existing instance-bound projection. It returns `undefined` for an absent World/entity or unknown/invalid producer bounds. This is renderer geometry evidence, not collision geometry or a synchronous update of authored World changes. A subsequent draw refreshes the projection; callers must not substitute an origin for an unavailable mesh bound. The query reuses culling ownership and retains no additional bounds cache.
+
+### Volumetric density coordinates
+
+`VolumetricFog.density` is a linear scalar field over `boundsMin` to `boundsMax`.
+World positions map to `(position - boundsMin) / (boundsMax - boundsMin)` and
+sample with clamp-to-edge addressing. The renderer clamps negative density at
+the optical-depth boundary, but adds no bias, octave synthesis, repetition or
+animation. White density means one; zero density contributes no extinction or
+scattering. Noise synthesis belongs to the asset producer. The existing volume
+passes integrate this field against scene depth before output tonemapping.
+
+Density integration uses fixed segment midpoints and the profile's logical
+froxel depth, including the clipped final segment. It does not rotate density
+samples with frame number: static authored air must not create temporal noise.
+Shadow visibility uses matching froxel centers without per-frame XY jitter or
+stochastic byte dithering. Shared PCF shadow filtering remains in effect.