@forgeax/engine-render 0.1.2

package/README.md

@@ -0,0 +1,1019 @@
+# `@forgeax/engine-render`
+
+## MaterialAsset 唯一成功路径
+
+Render 只消费 `paramSchema -> derive -> compile/reflect -> cook/load -> extract/record`
+主线的 extract/record 阶段：从已验证的 material artifact 取得 slot 数据，按
+`coordinateSet`、transform 与 `physicalUvScale` 写入 record，并以
+`layoutIdentity` 选择匹配的 bind-group layout。发现 identity 或坐标不一致时，
+回到 producer inspect/repair/recook，不在 game-side 添加 padding 或 fallback。
+
+| 阶段 | 唯一 owner | 结果 |
+|---|---|---|
+| schema / derive | material producer | 派生参数与纹理字段 |
+| compile / reflect | shader compiler | 与 WGSL 一致的 artifact 输入 |
+| cook / load | pack 与 assets-runtime | 带 receipt 的 GUID payload |
+| extract / record | render | 与 identity 对齐的 draw bindings |
+
+> [!IMPORTANT]
+> Render 错误通过结构化 `code`、`detail`、`hint` 恢复；不要把非结构化文本、
+> app 侧安装或替代材质当作 contract。
+
+## Direct-light parity contract
+
+The direct-light proposition is: one public `DirectionalLight`/`PointLight`/
+`SpotLight` semantic snapshot must produce the same analytic result in URP and
+HDRP. The M4 authority is the revision-pinned
+[`three-r184-finite-range-authority.json`](../../apps/parity/color-lighting/cases/direct-light/calibration/three-r184-finite-range-authority.json).
+It is `ready` only when its Three revision, source hash, config, and expected
+samples are present. Missing authority or paired GPU captures is `blocked`; do
+not repair that state with a multiplier, a backend profile, or a demo asset.
+
+Run the focused contract checks with:
+
+```sh
+pnpm exec vitest run apps/parity/color-lighting/src/analytic/__tests__/three-r184-finite-range.test.ts
+pnpm exec vitest run apps/parity/color-lighting/src/integration/__tests__/light-snapshot.test.ts
+```
+
+The public mapping is deliberately small:
+
+| Fact | Contract | Owner or evidence |
+|:--|:--|:--|
+| World scale | `1` world unit is `1` meter | Light components and glTF bridge |
+| Exposure | `1` by default; applied after lighting at tone/output | Camera tone contract and paired capture |
+| Intensity | Directional uses lux; point and spot use candela | `DirectionalLight`, `PointLight`, `SpotLight` |
+| Color | Linear RGB; no hidden global multiplier | Light snapshot and buffer layout |
+| Range and decay | Positive range is meters; `Infinity` means no cutoff; runtime uses `e=2` | Three r184 authority |
+| Cone | KHR radians import to component degrees; snapshot stores `cosInner` and `cosOuter` | glTF bridge and extract |
+| Direction | KHR local `-Z` after world rotation; extract normalizes once; downstream shaders consume the result | Extract snapshot and URP/HDRP shaders |
+
+The runtime finite-range factor is the Three r184 squared window:
+`clamp(1 - (d / c)^4, 0, 1)^2`. The KHR
+[`three-r184-khr-calibration.json`](../../apps/parity/color-lighting/cases/direct-light/calibration/three-r184-khr-calibration.json)
+curve is an explicit unsquared import/reference curve only; it is not a
+substitute for the runtime authority. The squared and unsquared samples are
+kept separate so a replacement remains a visible falsification.
+
+For a blocked case, inspect the authority fixture first, then the normalized
+light snapshot and the independent Forge/Three captures. The parity report
+must retain `provenance`, `captures`, `raw hash`, `analyticMax`, `roiMax`, and
+`verdict` for each backend x pipeline x case. A same-canvas self-comparison or
+analytic-only green result is not direct-light parity evidence.
+
+## Fog: authoring, inspection, and recovery
+
+> [!IMPORTANT]
+> Fog is the one public scene-radiance component. Spawn it in the World that
+> is passed as resourceOwner; the renderer selects zero or one Fog entity,
+> validates the fields, publishes a candidate, and commits it only after a
+> successful frame submission. Applications do not register a post effect,
+> pack a Fog buffer, import Fog WGSL, or maintain Fog history.
+
+The shortest authoring route is one public import plus the existing draw owner:
+The minimum form is world.spawn({ component: Fog, data: {} }) when defaults are sufficient.
+
+```ts
+ import { Fog } from '@forgeax/engine-render';
+ import type { RenderError } from '@forgeax/engine-render';
+
+const fogEntity = world.spawn({
+  component: Fog,
+  data: {
+    color: [0.45, 0.52, 0.6],
+    density: 0.018,
+    heightFalloff: 0.15,
+    maxOpacity: 0.85,
+  },
+}).unwrap();
+
+const drawn = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+if (!drawn.ok) reportRenderError(drawn.error as RenderError);
+const fogInspection = renderer.renderScene.fog;
+void fogEntity;
+void fogInspection;
+```
+
+### Authoring domain
+
+| Field | Valid domain | Default | Meaning |
+|:--|:--|--:|:--|
+| color | three finite non-negative numbers | [0.5, 0.5, 0.5] | Linear Fog radiance color; HDR values are valid |
+| density | finite number >= 0 | 0.01 | Base optical density |
+| heightFalloff | finite number >= 0 | 0 | Exponential density falloff along world y |
+| maxOpacity | finite number in [0, 1] | 1 | Upper bound for the Fog mix; surface alpha is preserved |
+
+The component has no mode, profile, baseHeight, start, or end field.
+heightFalloff = 0 is the uniform-density lane. A missing Fog entity means
+disabled scene Fog and adds no Fog-owned graph resource, pass, texture, bind
+group, or history. A second Fog entity in the same resourceOwner is a
+structured conflict, not a winner-selection policy.
+
+resourceOwner is an existing numeric World owner, not a string resource:
+
+| Fog cardinality in the selected owner | Renderer fact | Recovery |
+|:--:|:--|:--|
+| 0 | enabled=false; no accepted Fog snapshot | Continue without scene Fog |
+| 1 | Candidate is validated and becomes last-known-good after submit | Read renderer.renderScene.fog |
+| N | fog-owner-conflict; no new candidate is published | Remove every extra Fog entity, then retry draw |
+
+### Bounded inspection
+
+Read the accepted facts after draw:
+
+```ts
+const fog = renderer.renderScene.fog;
+const accepted = {
+  enabled: fog.enabled,
+  resourceOwner: fog.resourceOwner,
+  entity: fog.entity,
+  revision: fog.revision,
+  reactive: fog.reactive,
+  failure: fog.failure,
+};
+```
+
+The inspection is bounded and read-only. revision changes when a successful
+Fog authoring candidate changes; reactive is true on the current frame when
+the accepted revision changed. A failed candidate does not replace the
+last-known-good snapshot. failure is either fog-owner-conflict,
+fog-parameters-invalid, or undefined; it is not a free-form diagnostic
+registry.
+
+### Structured errors and exhaustive recovery
+
+Fog failures are members of the closed RenderError union:
+FogOwnerConflictError has code fog-owner-conflict, while
+FogParametersInvalidError has code fog-parameters-invalid. Both errors expose
+code, detail, expected, and hint; detail carries the bounded values needed for
+a retry.
+
+```ts
+function recoverFog(error: RenderError): 'retry' | 'forward' {
+  switch (error.code) {
+    case 'fog-owner-conflict':
+      // Remove all but one Fog entity in error.detail.resourceOwner.
+      return 'retry';
+    case 'fog-parameters-invalid':
+      // Set error.detail.field to a value satisfying error.expected.
+      return 'retry';
+    default:
+      return 'forward';
+  }
+}
+```
+
+For fog-owner-conflict, inspect error.detail.entities and
+error.detail.omitted; remove every extra entity from that resourceOwner, then
+retry draw. For fog-parameters-invalid, inspect error.detail.entity,
+error.detail.field, error.detail.actual, and the structured expected domain;
+repair the ECS field and retry. Do not parse the error message, create a
+fallback material, or silently disable Fog.
+
+### Height-aware scene-radiance formula
+
+The shared forgeax_view::fog module integrates optical depth along a
+producer-supplied world-space ray. Let y0 be the ray origin height, dy its
+world-space vertical direction, d its linear distance, h the height falloff,
+and rho the authored density:
+
+$$
+\rho_0 = \rho e^{-h y_0},\qquad
+q = h\,dy,\qquad
+\tau =
+\begin{cases}
+\rho_0 d & |q| < \epsilon,\\
+\rho_0 \dfrac{1-e^{-qd}}{q} & |q| \geq \epsilon.
+\end{cases}
+$$
+
+$$
+T = e^{-\tau},\qquad
+\alpha_f = \operatorname{clamp}(m(1-T), 0, 1),\qquad
+C' = \operatorname{mix}(C, C_f, \alpha_f),
+$$
+
+where m is maxOpacity, C is the producer color, and Cf is the authored
+linear Fog color. The output keeps the producer alpha unchanged. CPU
+extraction and WGSL share the same field order and ray contract; near/far
+values and non-linear depth are not Fog inputs.
+
+### Producer and pipeline responsibility
+
+Fog is applied exactly once to linear scene radiance before the
+renderer-owned temporal resolve. URP and HDRP keep their existing pipeline
+order; opaque, masked, unlit, Standard PBR, transparent, Sprite, Text,
+Skybox, and the five VFX render paths supply their own ray facts and call the
+shared module. G-buffer facts, shadow maps, and overlay/debug output are not
+Fog inputs. Alpha is preserved for transparent and VFX output.
+
+```mermaid
+flowchart TD
+  Author["World spawns one Fog entity"] --> Extract["extract selects resourceOwner"]
+  Extract --> Candidate["validate and stage candidate"]
+  Candidate --> Submit{"successful frame submit"}
+  Submit -->|yes| Accepted["publish revision and bounded inspection"]
+  Submit -->|no| Lkg["retain last-known-good snapshot"]
+  Accepted --> Scene["linear scene-radiance Fog exactly once"]
+  Scene --> Temporal["existing temporal resolve"]
+```
+
+No Fog-specific pass, texture, bind group, upload, history, registry, or
+fullscreen fallback is part of this route. TAA remains the sole history owner;
+Fog revision changes use its existing current-frame reactive lane.
+
+### Real evidence commands
+
+Run the focused contracts first, then the two independent feature carriers:
+
+```sh
+pnpm exec vitest run --project='@forgeax/engine-render' packages/render/src/__tests__/fog-public-surface.integration.test.ts packages/render/src/__tests__/fog-source-absence.integration.test.ts packages/render/src/__tests__/fog-custom-render-feature.integration.test.ts
+pnpm --filter @forgeax/bevy-fog smoke
+pnpm --filter @forgeax/bevy-fog smoke:browser
+```
+
+Each carrier must write case-wise expected, observed, delta, verdict, and
+confidence fields plus revision/reactive/recovery facts. The Dawn artifact is
+evidence/dawn-fog-trace.json; the Browser artifact is
+evidence/browser-fog-trace.json. PNG is auxiliary evidence: it never replaces
+linear readback or the case-wise verdict.
+
+> [!CAUTION]
+> The current M4 Dawn and Browser 300-frame artifacts are real executions but
+> remain verdict: fail because their RGB deltas exceed 0.02. This README
+> records the failure rather than promoting it to green. Preserve the
+> artifacts and repair the Engine owner before claiming visual parity.
+
+### Custom RenderFeature responsibility
+
+A custom RenderFeature can consume the renderer-owned scene-color target and
+contribute an overlay through the existing graph seam. It must not become a
+second Fog owner or create fog-texture, fog-history, fog-bind-group,
+Fog-specific upload state, or a parallel formula. The executable fixture is
+src/__tests__/fog-custom-render-feature.fixture.ts; its compile/import/overlay
+evidence is evidence/custom-render-feature-compile.json and contains the
+fixture path, compiler command, exitCode, moduleImport, and overlay verdict.
+
+<details>
+<summary>Custom feature boundary checklist</summary>
+
+- [x] Consume existing graph targets instead of allocating a Fog resource.
+- [x] Keep engine-render as the Fog owner.
+- [x] Use the public RenderFeature lifecycle and opaque staging references.
+- [ ] Add a new public capability only through a separate design and owner review.
+
+</details>
+
+### Out of scope for this Fog contract
+
+| Deferred capability | Boundary |
+|:--|:--|
+| Linear start/end, Exp2, baseHeight, public mode/profile, or a second Fog component | Reopen design only if a real scene proves the single density field insufficient |
+| Froxel/raymarch volume, 3D density, phase/scattering, light/shadow injection, or temporal volume denoise | Separate volume and lighting owner |
+| Local Fog volumes, overlap/blend, or directional phase | Separate volume composition authority |
+| Atmosphere, Sun, analytic sky, clouds, weather, or cloud shadow | Separate sky/weather/environment owner |
+| OIT, layered media, volume compositing, or automatic exposure | Separate transparency and color-management owners |
+| Fog-specific pass, texture, bind group, upload, history, or coverage registry | Explicitly forbidden because they duplicate RenderGraph/View/TAA SSOT |
+| Frozen GPU epsilon, exponent, or full diagnostic UI | Keep implementation details behind ABI and bounded evidence |
+
+M5 closure remains explicit:
+
+- [x] Public Fog schema and bounded inspection are documented.
+- [x] One-cut app source absence and two closed recovery errors are indexed.
+- [x] Real Dawn/Browser evidence paths and their current failed verdicts are linked.
+- [ ] RGB tolerance repair and full smoke-fleet gates remain required.
+
+## Particle feature boundary
+
+Particle rendering is provided by
+[`@forgeax/engine-vfx-render`](../vfx-render/README.md). This package owns the
+generic RenderFeature host, prepared graphics resolver, pipeline readiness
+contract, and structured renderer errors; it does not own VFX simulation or
+particle asset authoring.
+
+## Deferred membership timing
+
+Render owns the opt-in `membershipTiming` contract for the real
+`hdrp-cluster-membership` compute pass. App and Runtime only forward the option;
+they do not define a second profiler or reason vocabulary.
+
+| Mode | Work | Result |
+|:--|:--|:--|
+| omitted | No query set, resolve buffer, map, or queue wait | No timing record |
+| `cpu-control` | Existing CPU binner remains the control path | Accepted control record with `gpu: null` |
+| `gpu` | Bounded timestamp query, resolve, async queue completion, and map | GPU ticks plus backend period, or a terminal refusal/error |
+
+> [!IMPORTANT]
+> A GPU request is refused when the backend does not advertise timestamp
+> queries or a positive timestamp period. RhiNull and the wgpu WebGL2 path are
+> intentionally non-timing backends. They never synthesize GPU duration.
+
+The controller timestamps immediately around the existing membership dispatch,
+keeps GPU ticks separate from CPU encode/submit and async readback, and
+terminalizes captures on timeout, submit failure, queue completion failure,
+readback failure, device recovery, or disposal. The closed
+`MembershipTimingReasonCode` union and its exhaustive mapping live in
+[`src/record/membership-timing.ts`](src/record/membership-timing.ts).
+
+Timestamp-capable backends must execute both raw timestamp writes. A missing or
+throwing write is a structured `timestamp-write-unavailable` refusal; Render
+never publishes a zero, reversed, or non-finite GPU interval as a report.
+
+## Deferred membership evidence closure
+
+> [!IMPORTANT]
+> The close condition is `acceptedGpu=16`, with five accepted Dawn GPU
+> records at each of 32, 64, and 128 lights, one 256-light record, positive
+> tick intervals, per-light-count variance, and the 256-light overflow
+> fingerprint. `acceptedGpu=0` is a blocker. CPU control, WebKit refusal,
+> RhiNull refusal, PNG screenshots, and capability bits never count as GPU
+> evidence.
+
+The producer and validator are deliberately separate from the public Render
+API. Generate the exact manifest, run the full producer matrix, and inspect
+the machine-readable report in this order:
+
+```sh
+node scripts/dev-verify/generate-deferred-membership-manifest.mjs --output=report/deferred-membership-timing/full-matrix-manifest.json
+node scripts/dev-verify/capture-deferred-membership-corpus.mjs --manifest=report/deferred-membership-timing/full-matrix-manifest.json --output-root=report/deferred-membership-timing --webkit-download=webkit-evidence --report=report/deferred-membership-timing
+```
+
+The manifest contract is [`full-matrix-contract.json`](../../scripts/dev-verify/membership-timing/full-matrix-contract.json); the WebKit subset is validated by [`webkit-subset.schema.json`](../../scripts/dev-verify/membership-timing/webkit-subset.schema.json). The stable identity is `sourceHead`, `carrier`, `workload`, `profile`, and `artifactHashes`. The exact target is 20 top-level records and 32 nested references, with `record`, `profile`, `membership`, and `pixel` SHA-256 descriptors.
+
+The report exposes `valid`, `truthfulnessReady`, `completeMatrixReady`,
+`optimizationReleaseReady`, `counts`, `errors`, and `blocker`. A blocker uses
+`code`, `expected`, `hint`, and the observed `acceptedGpu` count so an AI user
+can recover by inspecting per-attempt refusal, profile, identity, and artifact
+hash records. The owner reason union remains closed; for example,
+`timestamp-query-unsupported` is a refusal, while `timestamp-write-unavailable`
+is a terminal producer failure. Neither is a successful GPU sample.
+
+## RenderFeature: the producer seam (first-read index)
+
+The public route remains `RenderFeature` through `RenderPipeline` and the
+active RenderGraph pass. This is the RenderGraph pass for a `type FrameData`
+producer, which uses
+`createRenderer(canvas, { features: [feature] })`,
+`context.staging.addPass('named-pass'`, `execute: ({ pass })`, and the
+`Material pass` boundary. This is the graph-only Wave 1 feature route.
+
+> [!IMPORTANT]
+> Render consumes the effective MaterialAsset snapshot produced by extract. Each texture slot carries its own coordinate set and transform into the built-in PBR binding layout; render records do not reinterpret authoring fields or manufacture shader artifacts. The effective `passes` are already validated.
+
+## MaterialAsset render contract
+
+Render owns this consumption route:
+
+| Input | Render responsibility |
+|:--|:--|
+| `passes` and `values` | Consume the effective snapshot; do not reinterpret authoring data. |
+| `parent` | Consume the already-resolved inheritance result. |
+| texture `coordinates` | Bind the selected coordinate set and transform. |
+| `cook` output | Record only validated shader artifacts. |
+| `recovery` | Preserve the structured failure so the source contract or cooked module can be repaired. |
+
+### Mesh material binding resolution
+
+Render resolves one effective material table per logical mesh slot before
+recording submesh draws. `MeshRenderer.materials[]` is a sparse per-instance
+override vector: a missing entry or `0` inherits the corresponding
+`MeshAsset.materialSlots[]` default. A slot without a declared mesh default
+uses the neutral engine material.
+
+> [!IMPORTANT]
+> A declared mesh default is a required asset dependency. If it is unavailable,
+> extract fails closed with the mesh GUID, slot index, and material GUID instead
+> of silently painting the mesh gray. Invalid instance overrides fall back with
+> a structured diagnostic; entries beyond the slot table are ignored and
+> diagnosed.
+
+The render path is `MaterialAsset` -> extract snapshot -> prepare resources -> record the per-slot `coordinates` and values. The effective `parent` is already resolved before extract. If a material contract or reflection binding fails, preserve the structured error and repair the source contract or cooked module before drawing again; that is the recovery route. The render package owns consumption, not material import or cook policy.
+
+> [!IMPORTANT]
+> Owner: render vocabulary and the extract → prepare → record frame boundary. Runtime selects concrete services and calls this package; it does not re-own these tokens.
+
+```ts
+import {
+  Camera,
+  materialTextureValue,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render';
+import { createRenderer } from '@forgeax/engine-runtime';
+
+const renderer = await createRenderer(canvas);
+const ready = await renderer.ready;
+const attached = renderer.attachWorld(world);
+if (ready.ok && attached.ok) {
+  world.update(1 / 60).unwrap();
+  renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+}
+
+// A numeric texture handle is normalized into the structured material slot.
+const values = { baseColorTexture: materialTextureValue(textureHandle) };
+```
+
+For the full slot contract, read [`MaterialTextureValue`](../types/src/material/asset.ts)
+and keep `baseColorTexture` on the same `paramSchema -> derive -> cook/load ->
+extract/record` path.
+
+`attachWorld` installs renderer-required derived-state systems once. Hosts built
+with `createApp` get this wiring automatically. A custom loop attaches each
+World before its first update, then keeps `draw` as a read-only consumer of the
+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. Each attached World generation
+receives one renderer-local `WorldRenderId`; draw-array reordering cannot change
+that identity, while detach retires it before the same World object can
+reattach. 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.
+
+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.
+
+When `RhiCaps.storageBuffer` is available, the same projection owns persistent
+Primitive, Instance, Transform, DrawTemplate, and Material GPU tables. The
+tables use independent stable ranges: one primitive can reference ordinary
+instance-local transforms, multiple draw items, and multiple prepared material
+records. The schema in `src/gpu-scene-schema.ts` derives byte offsets, signed
+and unsigned scalar forms, strides, and WGSL declarations; dirty ranges become
+coalesced `queue.writeBuffer` writes and no-change frames upload zero scene
+bytes. Device recovery discards only device-owned tables and rebuilds them from
+the retained CPU projection.
+
+The typed render-graph evidence path imports those persistent tables without
+transferring ownership, runs compute cull → compact → indirect args, and consumes
+the result through a graph-owned raster pass. Companion Dawn and Chromium gates
+also cover storage-buffer ping-pong, compute-generated indirect dispatch and draw
+arguments, storage-texture sampling in raster, and per-mip HZB reduction. These
+are real driver/pixel proofs for the GPU-driven boundary; they do not make
+RhiNull a pixel backend or make the CPU projection cease to be the scene
+authority.
+
+Inspect the current path through `renderer.renderScene`. Its CPU counters expose
+full rebuilds, no-change and delta frames, transform/material/instance updates,
+removals, the journal cursor, projection cardinality, and the last resync
+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 errors also use the existing `renderer.onError` channel.
+
+## GPU-driven view kernel
+
+`BatchTopology` groups eligible rigid draw items by immutable geometry,
+material, render-state, and command compatibility. One primitive can contribute
+multiple submesh draw items, and each draw item uses a closed indexed or
+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 URP frame activates the production raster lane when compute, storage
+buffers, and indirect drawing are available. The current lane accepts opaque,
+rigid default-unlit 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 keyed by stable renderer-local World identity instead of the
+current `draw(worlds)` order. 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.
+
+HDRP, 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, visibility/hierarchy-local
+routing, 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 URP 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.
+
+> [!NOTE]
+> Non-rigid multi-World composition, skinned lanes, visibility/hierarchy
+> changes, and unsupported render-relevant structural changes currently take
+> an explicit reconcile path. The projection and GPU tables already define
+> stable slot, generation, create, update, remove, grow, clear, and rebuild
+> semantics; later coverage can make those changes entity-local without adding
+> another scene authority.
+
+When a host constructs a feature only after its World or asset catalogue is
+ready, use `await renderer.installRenderFeature(feature)`. The late path inserts into
+the same lifecycle host and RenderGraph ordering as boot-time features; it is
+not a second renderer. Installing the same object twice is idempotent, while a
+different object with the same identity returns the structured registration
+conflict. Awaiting also completes the feature's declared material-shader
+prewarm, so its first prepared draw observes the same ready barrier as a
+boot-time feature.
+
+This is the graph-only Wave 1 feature route; prepared graphics and late shader
+prewarm extend the same lifecycle for production asset features.
+
+When a late-installed feature remains registered through device loss, its declared material
+shaders remain part of the renderer's live prewarm set. `await renderer.recover()` therefore
+rebuilds those modules before the next prepared draw rather than relying on a one-frame retry.
+
+For capability composition, `rendererPlugin(renderer)` provides the Host-owned
+renderer and `renderFeaturePlugin(feature)` binds installation to a Cordis
+Fiber. Fiber disposal calls `uninstallRenderFeature`, waits for submitted GPU
+work, releases prepared batches/resources, and removes the feature's shader
+prewarm declarations before the disposer resolves. The Fiber is never queried
+inside extract, prepare, record, RenderGraph execution, or an RHI command loop.
+
+When an App or Engine Worker owns the host-created Renderer itself, it installs
+`ownedRendererPlugin(renderer)`. The same Provider publishes the renderer
+Service and calls `Renderer.dispose()` after dependent capability Fibers have
+unwound. Assemble-form Apps use borrowed `rendererPlugin(renderer)` instead.
+
+```ts
+const fiber = await app.pluginContext.plugin(renderFeaturePlugin(feature));
+await fiber.dispose();
+```
+
+Boot-time `features: [...]` remains the direct renderer-construction path. Use
+the plugin helper when the feature belongs to an optional or reloadable
+capability whose lifetime must be reversible.
+
+### Built-in pipeline identity and cleanup
+
+The built-in Universal Render Pipeline is registered under the stable public
+identifier `URP_PIPELINE_ID` (`'forgeax::urp'`). Import the identifier from the
+public `@forgeax/engine-render` entry when constructing a
+`RenderPipelineAsset`; the `urpPipeline` implementation remains engine-owned.
+
+```ts
+import { URP_PIPELINE_ID } from '@forgeax/engine-render';
+
+const asset = {
+  kind: 'render-pipeline',
+  pipelineId: URP_PIPELINE_ID,
+  config: {},
+};
+const cleanup = renderer.installPipeline(asset);
+if (cleanup.ok) {
+  // Keep this disposer with the Renderer / Fiber that installed the asset.
+  cleanup.value();
+}
+```
+
+> [!IMPORTANT]
+> Pipeline, post-process, and RenderFeature registrations belong to a
+> Renderer instance and must be disposed with that instance or its owning
+> Fiber. Do not add a module-level `installed` set or reach through
+> `renderer.store`; those are lifecycle and allocation internals, not public
+> extension state.
+
+| This package owns | Excluded concepts |
+|:--|:--|
+| Camera/light/mesh vocabulary, `Renderer`, render errors, documented pipeline operations | Backend selection, asset import, ECS scheduling, animation playback, optional text/tile/sprite authoring |
+
+The stable surface is [`src/index.ts`](src/index.ts). `RenderError` is closed and carries actionable detail. Runtime alone owns host assembly and its `EngineEnvironmentError` rejection contract; render's construction seam is internal to that dependency path.
+
+## Tone mapping output contract
+
+The public mode names are the same names used by the Three r184 oracle:
+
+| Mode | Public constant | Output behavior |
+|:--|:--|:--|
+| `linear` | `TONEMAP_LINEAR` | Exposure, then clamp to LDR |
+| `reinhard` | `TONEMAP_REINHARD` | Per-channel Reinhard |
+| `cineon` | `TONEMAP_CINEON` | Cineon filmic curve |
+| `aces-filmic` | `TONEMAP_ACES_FILMIC` | ACES filmic curve |
+| `agx` | `TONEMAP_AGX` | AgX curve |
+| `neutral` | `TONEMAP_NEUTRAL` | Khronos neutral curve |
+
+`TONEMAP_REINHARD_EXTENDED` is the existing ForgeaX luminance-domain curve. Its
+separate `reinhard-extended` name is intentional: it is not a second formula
+hidden behind the Three `reinhard` name.
+
+Tone-enabled cameras use one output contract:
+
+```text
+linearHdr -- exposure + named tone curve --> linearLdr --> displayEncoded
+```
+
+The final capture is the encoded surface result. A linear capture, when a
+parity adapter exposes one, remains a separate `linearHdr` or `linearLdr`
+sample and must not be compared as if it were the final display capture. The
+contract is available as `resolveToneOutputContract(camera.tonemap)` from the
+render package. The camera remains the runtime entry point:
+
+```ts
+import { Camera, TONEMAP_AGX, perspective } from '@forgeax/engine-render';
+
+world.spawn({
+  component: Camera,
+  data: {
+    ...perspective({ fov: Math.PI / 4, aspect: 1 }),
+    tonemap: TONEMAP_AGX,
+    exposure: 1,
+  },
+}).unwrap();
+```
+
+The built-in pass samples the HDR target and writes the LDR result through the
+registered `forgeax::tonemap` fullscreen shader. Shader source authority is
+[`packages/shader/src/tonemap.wgsl`](../shader/src/tonemap.wgsl); the render
+package does not duplicate those formulas.
+
+## Optional CPU profiling
+
+Render accepts the host-owned `Profiler` capability through App assembly. It writes bounded CPU
+phase evidence only while a capture is active; it does not add GPU timestamps, ECS spans, a UI, or
+a remote method. The artifact and its owner-declared catalog are documented by
+[`@forgeax/engine-profiler`](../profiler/README.md).
+
+```ts
+import { createProfiler, type Profiler } from '@forgeax/engine-profiler';
+import { createRenderer } from '@forgeax/engine-runtime';
+
+const profiler: Profiler = createProfiler();
+const renderer = await createRenderer(canvas, { profiler });
+```
+
+Use the package's `validateProfileCapture` and `buildProfileModel` entries for offline analysis.
+The render package remains the owner of render vocabulary and extract/prepare/record execution.
+
+## RenderFeature: the producer seam
+
+Register one producer-owned feature at the renderer assembly boundary. The
+same `FrameData` type flows through `extract`, `prepare`, and `contribute`;
+the host supplies ordering, capability projection, graph composition, and
+lifecycle isolation.
+Both paths execute inside the active RenderGraph and the frame's single
+execute/submit boundary.
+
+The smallest graph-only feature can still use `addResource` plus `addPass` for
+CPU callbacks. GPU work uses the typed methods on the same staging object:
+
+```ts
+contribute: (_frame, context) => {
+  context.staging.addComputePass('compact', computeDescriptor).unwrap();
+  context.staging.addGraphicsPass('draw', graphicsDescriptor).unwrap();
+  return ok(undefined);
+}
+```
+
+`computeDescriptor` contains only prepared program/binding references and
+dispatches. `graphicsDescriptor` contains logical feature targets, prepared
+pipeline/binding/data references, and draw or indirect-draw commands. The host
+projects both into one typed `RenderGraph`; neither descriptor owns an encoder.
+
+### Five render terms
+
+| Term | Meaning | Owner |
+|:--|:--|:--|
+| `RenderFeature` | Producer-owned extract/prepare/contribute callbacks and frame data | Feature producer |
+| `RenderPipeline` | Full frame policy selected or switched by the host | Render host |
+| RenderGraph pass | One declared graph execution node contributed to the active pipeline | Graph host |
+| Material pass | One shader-facing pass in a `MaterialAsset` | Material asset |
+| Prepared graphics | Opaque pipeline, binding, vertex/index, and attachment references prepared by the host | Render host |
+| Prepared GPU work | Opaque persistent compute program, binding, buffer, dispatch, and indirect-draw references | Render host |
+
+### Prepared compute resources
+
+`RenderFeature` producers prepare cooked compute pipelines, reflected name-based bindings,
+uniform/storage buffers, and dispatches. The renderer joins reflection with prepared binding
+entries, imports the persistent buffers into the render graph, and derives `uniform-read`,
+`storage-read`, or `storage-read-write` access. Producers do not repeat a string `reads/writes`
+ledger and do not receive an encoder.
+
+Compute and graphics passes use the same contribution graph and submission boundary. The graph
+owns `beginComputePass` / `end`; prepared GPU work records only pipeline, bind group, and dispatch
+commands into the lent pass encoder. Persistent buffers retain device identity across frames,
+rebuild with the feature-host generation, and retire only after queue completion. A storage buffer
+may also be consumed as renderer-declared vertex data.
+
+Feature contexts never expose raw GPU graphics state, a complete pipeline
+context, submit authority, or a command encoder. They expose an immutable
+`Readonly<RhiCaps>` capability snapshot for capability-gated preparation. The
+graph-only `addPass`
+surface still exposes only named pass and frame identity; use the prepared
+graphics surface below when a feature needs pipelines, bindings, vertex/index
+data, attachments, and draw records. Both paths execute inside the active
+RenderGraph and the frame's single execute/submit boundary. The active RenderGraph
+owns that frame boundary. Do not cast either context to a raw device or encoder. See
+[`features/graph-contribution.ts`](src/features/graph-contribution.ts) for the
+staging shape.
+
+The copyable recipe above is therefore a graph-only Wave 1 feature; it stops at
+the graph seam and does not provide a production particle draw path.
+
+### Prepared graphics recipe
+
+Prepared graphics extends the existing graph-owned staging seam with five
+opaque reference kinds. A producer requests preparation during `prepare`,
+retains only the returned references, and contributes declarative records. The
+render host owns generation checks, graph composition, recording, and submit.
+
+Persistent GPU work follows the same ownership rule. A feature may retain opaque bindings for an
+active producer; bindings retain their transitive program and buffers. Untouched resources are
+detached after a successful feature frame and destroyed after queue completion, never while an
+in-flight command can still reference them.
+
+Prepare opaque references through `context.graphics` and, when compute is
+available, `context.gpu`; retain those references in producer-owned frame data
+and consume them only through `addComputePass` and `addGraphicsPass` during
+`contribute`. The executable contract examples live in
+[`render-feature-graph.integration.test.ts`](src/__tests__/render-feature-graph.integration.test.ts)
+and
+[`render-feature-gpu-work.integration.test.ts`](src/__tests__/render-feature-gpu-work.integration.test.ts).
+
+### Failure and recovery
+
+`RenderError` is a closed union. Switch on `error.code`, then read
+`error.expected`, `error.hint`, and the code-specific `error.detail`.
+
+Feature capability checks are based on `Readonly<RhiCaps>`, and recovery actions
+consume the structured `error.detail` context.
+
+| Diagnostic state or code | Recovery action |
+|:--|:--|
+| `active` | Continue the next frame |
+| `failed` / `render-feature-stage-failed` | Correct producer data and retry on the next frame |
+| `disabled` / `render-feature-capability-missing` | Provide the capability on a replacement device; after device-loss recovery call `await renderer.recover()`. On a live renderer, `recover()` returns `recover-not-needed`, so rebuild on a capable device instead. |
+| `render-feature-registration-conflict` | Fix identity/order at registration |
+| `render-feature-pass-order-conflict` | Reorder the declared dependency and retry contribution |
+| `render-feature-preparation-failed` | Repair the named prepared resource and retry on the action in `error.detail.recovery`; after device loss, verify that the feature's declared shader was included in the recovery prewarm set |
+| `render-feature-prepared-state-mismatch` | Read the discriminated `error.detail.reason`, repair the generation/layout/format mismatch, and retry |
+| `render-feature-draw-recording-failed` | Read `error.detail.backendReason`, then retry after the host reports renderer recovery |
+| `disposed` | Terminal; create a new renderer/feature registration |
+
+Use `renderer.renderFeatureDiagnostics()` for a read-only snapshot. Call
+`renderer.dispose()` once or repeatedly; disposal is idempotent. A pipeline
+switch keeps the feature registration list and rebuilds the active graph.
+The host still uses `renderer.registerPipeline(id, pipeline)` for a full
+pipeline change.
+
+For a temporary presentation-owner handoff, call `renderer.releaseSurface()`.
+It unconfigures the canvas and makes `draw()` fail closed without disposing the
+Renderer, AssetRegistry, or GPU declarations. After the temporary owner is
+gone, `renderer.restoreSurface()` re-enables lazy surface configuration on the
+next draw. Both calls are idempotent; `dispose()` remains the terminal path.
+
+For the complete declaration shape, read
+[`features/types.ts`](src/features/types.ts) and
+[`features/prepared-graphics.ts`](src/features/prepared-graphics.ts). For graph
+contribution details, read [`features/graph-contribution.ts`](src/features/graph-contribution.ts);
+for pipeline switching, read [`renderer.ts`](src/renderer.ts). The producer
+asset contract is [`@forgeax/engine-vfx`](../vfx/README.md), while graph
+ownership is [`@forgeax/engine-render-graph`](../render-graph/README.md).
+
+> [!WARNING]
+> Wave 2 delivered this generic prepared public seam. A downstream Wave 3 VFX
+> integration owns visible particle draws; render must not gain a
+> particle-kind switch or VFX production dependency. See the
+> [VFX Wave 3 handoff](https://github.com/ForgeaXGame/forgeax-engine-harness/blob/main/docs/vfx-particle-runtime-design.md).
+
+Dynamic consumers use the same boundary explicitly:
+
+```ts
+const { Camera, MeshFilter, MeshRenderer } = await import('@forgeax/engine-render');
+```
+
+`@forgeax/engine-runtime` remains the host assembly entry for `createRenderer` and backend policy. Import `Materials` from this package. Runtime is not a compatibility barrel for render components.
+
+Optional text, tilemap, and sprite authoring is intentionally isolated from the
+base vocabulary:
+
+```ts
+import {
+  GlyphText,
+  SpriteAnimation,
+  Tilemap,
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+} from '@forgeax/engine-render/authoring';
+```
+
+`authoring` also owns the public transparent-bucket configuration helpers and
+their four named modes. A consumer that composes sprites with an existing 3D
+game may set the world-level mode here; it should not reach into `/internal`.
+
+The root barrel does not expose frame stores or extract/prepare/record owners.
+Custom pipelines use `RenderPipeline.build`, typed targets, and typed graph
+primitives; the renderer owns graph compilation and submission.
+
+`@forgeax/engine-render/internal` is an engine-owned assembly seam, not an
+application API or a compatibility route. Imports from `/internal` under the
+private `apps/` tree are engine dogfood for assembly coverage, not application
+recipes. First-party packages may use it while the engine is assembled;
+application code should not copy those imports. Its
+surface can change without a consumer migration promise. If a custom renderer
+needs a capability absent from the supported root operations, treat that as a
+request for an explicit public design rather than importing `/internal`.
+
+For a custom `RenderPipeline` with `Camera.antialias = ANTIALIAS_MSAA`, create
+count-4 scene colour/depth targets plus a single-sample resolve target, then pass
+the typed resolve target to `addTypedScenePass`. Downstream passes read that
+resolved handle; single-sample pipelines omit it.
+
+## Temporal antialiasing contract
+
+`Camera.antialias = ANTIALIAS_TAA` selects the renderer-owned temporal path. The fixed v1 order is linear scene color -> temporal raster -> one TAA resolve -> bloom -> tone/output/debug/UI. `Camera.historyVersion` is the explicit reset authority; increment it after a camera cut or other discontinuity.
+
+> [!IMPORTANT]
+> Read `renderer.renderScene.temporal` after `draw()`. It is the bounded inspection SSOT for history bytes, reset reason, coverage, failure, and recovery. Applications must not retain graph textures or create a parallel history registry.
+
+The none, FXAA, and MSAA lanes allocate zero TAA history and record neither `scene-temporal-clear` nor `taa-resolve`. The permanent real-backend oracle is [`apps/hello/taa`](../../apps/hello/taa/README.md).
+
+The main scene raster is the only jittered domain. Temporal replay uses unjittered current and previous view projection matrices plus its own cleared depth attachment; reusing main depth would compare unjittered fragments against jittered visibility. The packed `rgba16float` payload is `(currentUv - previousUv, log2(1 + viewDepth), reactive)`. Clip payloads use linear interpolation so previous projection remains a geometric authority rather than a perspective-correct material varying.
+
+Resolve and both history textures live in the unjittered output domain. Current scene color is therefore sampled at `uv + currentJitterUv`, while history is sampled at `uv - velocity`. This is the same coordinate transform as the jittered-domain form `uvJittered - velocity + (previousJitter - currentJitter)`: storing the previous resolve unjittered removes the previous-jitter term instead of dropping jitter correction. The v1 preset keeps hard UV/depth rejection, 3 x 3 current-neighborhood clipping, alpha preservation, and a fixed luminance-adaptive feedback range of 0.88 through 0.97 further reduced by reactive, velocity, depth, and startup factors.
+
+### AI-user recipe: TAA, reset, and recovery
+
+Enable TAA on the existing `Camera` and treat `historyVersion` as an explicit discontinuity counter. Do not increment it for ordinary camera motion.
+
+```ts
+import { ANTIALIAS_TAA, Camera } from '@forgeax/engine-render';
+
+const camera = world.spawn({
+  component: Camera,
+  data: {
+    fov: Math.PI / 4,
+    aspect: 16 / 9,
+    near: 0.1,
+    far: 100,
+    antialias: ANTIALIAS_TAA,
+    historyVersion: 0,
+  },
+}).unwrap();
+
+let historyVersion = 0;
+function resetHistoryAfterCameraCut(): void {
+  historyVersion += 1;
+  world.set(camera, Camera, { historyVersion }).unwrap();
+}
+```
+
+Register `onError` before the first draw, handle the returned `Result`, then read the bounded inspection after the draw. The inspection is the recovery authority; the error listener preserves the exact structured failure that caused it.
+
+```ts
+const stopErrors = renderer.onError((error) => reportRenderError(error));
+const drawn = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+if (!drawn.ok) reportRenderError(drawn.error);
+
+const temporal = renderer.renderScene.temporal;
+if (temporal.recovery !== 'none') {
+  reportTemporalRecovery(temporal.recovery, temporal.failure, temporal.coverage);
+}
+
+stopErrors();
+```
+
+| `temporal.recovery` | Owner action |
+|:--|:--|
+| `none` | Continue; a stable submitted frame owns valid history. |
+| `seed-history` | Submit the next continuous frame; increment `historyVersion` only for a real discontinuity. |
+| `enable-temporal-capabilities` | Recreate the renderer on a device with `rgba16float` rendering and at least two color attachments. |
+| `fix-temporal-pipeline-topology` | Repair the custom pipeline's target domain, attachment, or resolve count. |
+| `complete-temporal-coverage` | Find `coverage.missingContributorIds`; make each producer exact or reactive. |
+| `retry-frame` | Retry after the submit failure; aborted frames never advance history. |
+| `rebuild-renderer` | Call `await renderer.recover()` after device loss and handle its `Result`. |
+
+### Custom pipeline temporal seam
+
+A custom pipeline uses the same graph owner and follows one narrow order: scene color -> unjittered temporal raster -> feature contributions -> exactly one `context.resolveTemporal(...)` -> bloom/tone/output. For a TAA topology, allocate `scene-color` and `scene-temporal` as single-sample `rgba16float`; allocate a separate single-sample temporal depth target; clear temporal color to `(0, 0, -1, 1)` before replay; and call the public resolve seam exactly once. A non-TAA topology allocates and records none of those temporal resources or passes; calling the seam without `sceneTemporal` is optional and returns `undefined`.
+
+```ts
+const features = context.contributeFeatures([
+  sceneColorTarget,
+  sceneDepthTarget,
+  sceneTemporalTarget,
+]);
+if (!features.ok) return features;
+
+const resolved = context.resolveTemporal({
+  sceneColor: sceneColorTarget,
+  sceneDepth: sceneDepthTarget,
+  sceneTemporal: sceneTemporalTarget,
+});
+if (!resolved.ok) return resolved;
+
+const postInput = resolved.value?.resolvedColor ?? sceneColorTarget;
+```
+
+The snippet assumes the pipeline has already recorded its scene and temporal raster passes. `exact` feature coverage must write the provided `scene-temporal` target from current/previous producer state. `reactive` is conservative but complete coverage: declaring `temporalCoverage: 'reactive'` permits current-frame fallback, while writing `w = 1` to the target gives pixel-local rejection. A visible graphics producer that declares neither is `missing`; the renderer rejects that frame's history instead of guessing.
+
+```mermaid
+flowchart LR
+  World["World data"] --> Extract["extract"]
+  Extract --> Prepare["prepare"]
+  Prepare --> Record["record"]
+Record --> Rhi["RHI submission"]
+```
+
+## Visibility contract
+
+Quick start:
+
+```ts
+import { Visibility, VisibilityStateValue, resolveVisibility } from '@forgeax/engine-render';
+
+world.spawn({
+  component: Visibility,
+  data: { state: VisibilityStateValue.hidden },
+}).unwrap();
+const snapshot = resolveVisibility(world);
+```
+
+| Stage | Truth | Diagnostic |
+|:--|:--|:--|
+| Author intent | `Visibility.state` is `inherited`, `hidden`, or `visible` | Read the ECS field or reflected `labels` |
+| Effective state | `resolveVisibility(world).effective(entity)` applies valid scene parents | Inspect `snapshot.diagnostics` and `VisibilityResolution.source` |
+| Render result | Render producers skip hidden candidates before material work | Read `renderer.visibilityStats`; it is not a frustum or picking metric |
+
+If the state write returns an error, preserve `code`, `expected`, `hint`, and
+`detail`, correct the enum value, and retry through `world.set`. If hierarchy
+diagnostics are present, repair the scene relation and resolve again. Do not
+hide the issue with a custom mesh, camera workaround, or material substitute.
+
+Out of scope: camera frustum policy, picking, app lifecycle, asset import, and
+VFX shadow behavior. `@forgeax/engine-vfx-render` remains the producer-owned
+particle bridge and consumes the same effective visibility boundary.
+
+## Analytic atmosphere: one source, one submitted generation
+
+The analytic environment route has one authoring source and one renderer-owned
+submission transaction. `Atmosphere` contains exactly five medium fields; the
+resource-owner selector enforces one Atmosphere source per World (the ECS schema
+does not carry cardinality policy);
+Sun direction, colour and illuminance belong to the co-located
+`DirectionalLight` entity. The app never selects an atmosphere Skybox mode and
+never owns an evaluator, cache, lifecycle ledger, encoder or queue submit.
+
+```ts
+const sunEntity = world.spawn(
+  { component: Atmosphere, data: {
+    turbidity: 2.4,
+    rayleigh: 1.1,
+    mieCoefficient: 0.006,
+    mieDirectionalG: 0.78,
+    sunAngularRadius: 0.004675,
+  } },
+  { component: DirectionalLight, data: {
+    direction: [0.35, -0.88, -0.2],
+    color: [1, 0.93, 0.82],
+    intensity: 2.2,
+  } },
+).unwrap();
+
+world.update(1 / 60).unwrap();
+const frame = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+if (!frame.ok) reportRenderError(frame.error);
+const submitted = renderer.renderScene.environment;
+```
+
+The final line is a bounded projection of the existing Renderer generation
+transaction. It reports state, source World/entity, desired/active signature,
+device generation, bytes, rebuild facts, failure/LKG and temporal publish/reset
+facts. It does not expose GPU handles or mutable caches.
+
+| Failure observation | Exhaustive recovery action |
+|:--|:--|
+| `environment-source-conflict` | Keep exactly one image or Atmosphere source and retry extract. |
+| `atmosphere-sun-missing` | Add the co-located `DirectionalLight`; do not invent a second Sun store. |
+| `atmosphere-capability-insufficient` | Admit only the M0 capability matrix result or fail closed. |
+| `atmosphere-producer-failed` | Read the stage, preserve LKG, repair the producer and retry the same Renderer owner. |
+| `render-feature-*` / `webgpu-runtime-error` | Read the discriminated `code`/`detail`, abort the frame transaction and follow its explicit recovery. |
+
+> [!WARNING]
+> `Fog`, day/night automation, clouds, aerial perspective, astronomy, auto
+> exposure and a high-frequency time-of-day system are not implemented by this
+> route. A compatibility alias, conceptual wrapper, second evaluator/cache or
+> second submit/lifecycle owner would fail the one-cut audit.
+
+<details>
+<summary>U-12 comparative-only boundary</summary>
+
+Three r184 and PMREM references may appear in comparative calibration evidence,
+but they are not an implementation dependency, runtime import, evaluator, or
+public API owner. Comparative observations cannot turn an unavailable
+Browser/Dawn readback into a ForgeaX pixel verdict.
+</details>