@forgeax/engine-render 0.1.32 → 0.1.34

package/README.md

@@ -1,5 +1,11 @@
 # `@forgeax/engine-render`
 
+> [!NOTE]
+> This package-owner README contains physical `@forgeax/engine-render` imports
+> in internal ownership examples. Game-facing code should use the public
+> facade `@forgeax/engine/render`; the Bloom consumer route is documented in
+> [hello-bloom](../../apps/hello/bloom/README.md).
+
 > [!IMPORTANT]
 > The Standard pipeline keeps dark-gradient color in `rgba16float` until one
 > `outputTransform` reaches the `surface.storage.raw` endpoint; `inspect()` and
@@ -8,6 +14,77 @@
 
 ## Public frame contract
 
+Every accepted `FrameReceipt` with a submitted camera context carries an
+immutable `barrelDistortion` mapping, including the exact identity mapping when
+the camera has no active distortion. The optional property is a transport and
+pre-first-frame shape: `undefined` means that no accepted submitted display
+context exists. It is fail-closed, never an identity guess; display consumers
+must wait for a new submitted frame.
+The mapping is tied to the submitted output extent, camera matrices, device
+generation, graph generation, and frame identity. Consumers must keep those
+facts together; a mapping from a newer World edit cannot be applied to an older
+picture. The renderer publishes the mapping only after queue submission, and a
+candidate that fails validation keeps the previous accepted picture and
+mapping. The public projection is deeply frozen and contains no device, graph,
+texture, or mutable resource handle.
+
+`renderer.inspect().barrelDistortion` projects the same accepted context as
+`effectiveMapping`, `extent`, `frameId`, `deviceGeneration`,
+`graphGeneration`, and `lastKnownGood`. Before the first accepted frame, after
+surface retirement, or during device loss, `effectiveMapping` is unavailable;
+display consumers must wait for a new submitted frame. An invalid authoring
+value returns `barrel-distortion-invalid-parameter` with its field and bound.
+Unsupported float attachment capability is reported only for an active plan;
+an empty or zero-strength plan stays zero-work. A pending or failed disable
+keeps the old nonzero mapping with its picture, while a successful disable
+publishes identity and retires the old feature resources through the normal
+in-flight fence.
+
+`Fog` provides distance fog with exponential height density through one
+finite-depth fullscreen pass before temporal resolve, Bloom and tone mapping.
+`density`, `heightFalloff`, linear `color` and `maxOpacity` are selected from
+the frame's resource owner. Disabled or zero-density fog allocates no fog target;
+there is no 3D texture, froxel grid or temporal history. The authored sky remains
+unchanged. FXAA, TAA and no-AA use single-sample depth; MSAA is rejected until a
+matching depth resolve is available. Translucent surfaces that do not write depth
+use the opaque background depth. Use `VolumetricFog` for spatial density and
+lighting/scattering effects; the meadow-style distance haze needs only `Fog`.
+
+### Local volumetric fog
+
+Spawn one `VolumetricFog` per local medium in the rendered environment World.
+Each owner selects its own light, 3D density texture, world-space bounds, and
+optical coefficients. Up to `MAX_VOLUMETRIC_FOG_OWNERS` (8) owners share the
+renderer-owned inject, integrate, temporal, and composite passes. Overlapping
+media add coefficients before integration; removing one owner keeps the others.
+Removing the last owner retires the volume graph resources.
+
+| Author field | Contract |
+|:--|:--|
+| `density` | Shared linear `TextureAsset`, `viewDimension: '3d'` |
+| `sampling` | ECS enum: `VolumetricFogSamplingValue.noise` (default animated atmospheric grain), or `.density` (local normalized bounds sample) |
+| `boundsMin`, `boundsMax` | Finite world coordinates, strictly increasing on each axis; not transformed by `Transform` |
+| `extinction`, `albedo`, `emission` | Nonnegative RGB; albedo additionally at most 1 |
+| `anisotropy`, `maxDistance` | Finite, respectively `(-1, 1)` and positive world units |
+| `light`, `spotLight` | Same-World selected light and optional Point/Spot pair, as in the existing single-volume contract |
+
+Pure `VolumetricFogAuthoring` validation uses the string sampling labels, not
+the ECS numeric values. `extractVolumetricFog()` returns an available `fogs`
+collection and validates every member atomically. Overflow returns
+`volume-owner-conflict` with `detail.ownerCount`; invalid author parameters
+retain the existing structured error contract.
+
+Read `renderer.inspect().volumetricFog.ownerCount` after a completed frame for
+the accepted collection, alongside status, pass count, memory, and generation.
+It is not an echo of a rejected candidate. Light projectors retain the shared
+renderer-selected projector contract; only its selected light samples the map.
+
+> [!IMPORTANT]
+> This is local-medium integration against scene depth, not a claim of
+> depth-aware fogging of every transparent or VFX feature. Those consumers
+> require their own rendered integration evidence. Software GPU readback is
+> correctness evidence, not hardware performance evidence.
+
 ## 灯光最短入口
 
 三条最短入口：
@@ -57,6 +134,10 @@ 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.
+Fullscreen recovery warms only active declared post-process identities; graph-local
+resource aliases are resolved by the prepared feature and are not separate pipelines.
+Ordinary graph replacement retains the previous graph until submission settles,
+using the same retirement boundary for resize and post-process changes.
 
 `inspect().recovery` is always present. Its `phase` is `null` outside an active
 attempt and otherwise follows `quiesce`, `acquire-adapter`, `acquire-device`,
@@ -76,10 +157,39 @@ uninitialized until a successful receipt; a neutral target or last-known-good
 fallback is not proof of real recovery. Public consumers never receive graph
 nodes, devices, history textures, or prepared handles.
 
- The current-source manifest and schema identify `source`, `build`, `backend`,
- `runner`, and `frameIdentity`. Structural graph receipts, Browser/Dawn
- readback or PNG evidence, and historical oracle data are separate evidence
- classes. An unavailable backend is reported as unavailable.
+The current-source manifest and schema identify `source`, `build`, `backend`,
+`runner`, and `frameIdentity`. Structural graph receipts, Browser/Dawn
+readback or PNG evidence, and historical oracle data are separate evidence
+classes. An unavailable backend is reported as unavailable.
+
+### Renderer-wide graph allocation inspection
+
+`renderer.inspect().renderGraphGenerationAllocation` is the renderer-owned
+logical allocation receipt across active, volumetric candidate, retiring, and
+detached recovery graph generations:
+
+```ts
+const allocation = renderer.inspect().renderGraphGenerationAllocation;
+if (allocation?.availability === 'complete') {
+  console.log(allocation.liveBytes, allocation.pendingRetirementBytes, allocation.peakBytes);
+  for (const entry of allocation.entries) {
+    console.log(entry.generation, entry.roles, entry.retirement, entry.allocation);
+  }
+}
+```
+
+`roles` identifies `active`, `candidate`, and `retiring` ownership; `retirement`
+is `active`, `pending`, or `failed`. `liveBytes` and
+`pendingRetirementBytes` are current logical bytes, while `peakBytes` is the
+simultaneous logical high-water mark captured at compile, replacement, and
+retirement events. `failedRetirementCount` and `failedRetirementBytes` keep a
+destroy refusal, throw, or fence failure visible until its owner is repaired.
+`availability` is `complete`, `partial`, or `unavailable`, with
+`unavailableGenerationCount` explaining omitted graph facts. `unit` is
+`engine-allocation-bytes` and `physicalResidency` is always `unknown`: imported
+resources remain with their importing owner and logical byte size is not a VRAM
+measurement. After a device-loss recovery, inspect the replacement generation
+and retry the frame; a retained failed or pending row is recovery evidence.
 
 ## RenderFeature: the producer seam (first-read index)
 
@@ -92,6 +202,589 @@ fallback material. The projection preserves `layoutIdentity`,
 `programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
 stale draw can be traced to the first producer divergence.
 
+### Single-layer medium Surface
+
+`MaterialAsset.surface` selects the Engine template and one imported Surface
+implementation. A Standard Surface imports
+`forgeax_material::surface_v1::{SurfaceInput, SurfaceData}` and exports
+`evaluate_surface(SurfaceInput) -> SurfaceData`. A
+`model: 'single-layer-medium'` Surface instead imports
+`forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput,
+SingleLayerMediumSurfaceData}` and exports that separate input/data ABI. The
+Surface returns normal, roughness, coverage, foam, absorption, scattering, IOR,
+and phase facts; Render performs the finite Beer-Lambert/single-scatter
+integral, one Fresnel allocation, and consumes renderer-owned paired
+color/depth frame facts. `maxDistanceMeters` is a finite authored upper bound
+in metres for the sky-miss case. A valid value is carried through the Surface
+ABI and Cook output, while invalid or absent input uses the conservative Engine
+bound; it never turns an unavailable depth producer into a synthetic sample.
+The Surface does not declare a stage, binding, attachment, BRDF, or vertex
+displacement.
+
+```ts
+import { definePack, definePackageId } from '@forgeax/engine/pack/source';
+import { ok, type MaterialAsset } from '@forgeax/engine/types';
+
+const packageId = definePackageId('01900000-0000-7000-8000-000000000001');
+
+const material = {
+  kind: 'material',
+  surface: {
+    model: 'single-layer-medium',
+    module: 'game::water_surface_a',
+    dynamicInput: {
+      name: 'waterEvents',
+      fields: [
+        { name: 'position', type: 'vec3<f32>' },
+        { name: 'time', type: 'f32' },
+        { name: 'eventId', type: 'u32' },
+      ],
+      maxRecords: 64,
+      maxDomains: 8,
+      maxPageBytes: 2048,
+      maxBindings: 1,
+      maxEventsPerSample: 8,
+    },
+  },
+  passes: [{ name: 'color', program: { module: 'forgeax::single-layer-medium' } }],
+  parameters: [
+    { name: 'coverage', type: 'f32' },
+    { name: 'absorption', type: 'vec3' },
+  ],
+  values: { coverage: 0.85, absorption: [0.22, 0.07, 0.025] },
+} satisfies MaterialAsset;
+
+export default definePack({
+  schemaVersion: '2.0.0',
+  packageId,
+  name: 'Water',
+  build: () => ok({ 'material/water': material }),
+});
+```
+
+The authored module reads that schema through the compiler-generated accessor;
+parameter names are fields on `material`, not free uniforms or string lookups:
+
+```wgsl
+#define_import_path game::water_surface_a
+#import forgeax_material::parameters::{material}
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+
+fn evaluate_surface(input: SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  return SingleLayerMediumSurfaceData(
+    normalize(input.geometricNormalWS),
+    0.16,
+    material.coverage,
+    0.0,
+    material.absorption,
+    vec3<f32>(0.018, 0.04, 0.085),
+    1.333,
+    0.24,
+    900.0,
+  );
+}
+```
+
+Cook validates this accessor against `parameters`, the Pack transport writes
+the cooked material through JSON while preserving its GUID, and runtime loads
+that GUID before allocating the `MaterialAsset` handle used by `MeshRenderer`.
+The executable [LightProbe to ProbeBlend to Surface example](#lightprobe-to-probeblend-to-surface-example)
+shows the `loadByGuid<MaterialAsset>` → World → `MeshRenderer` → `draw` half of
+the same route.
+
+The generated dynamic page is a bounded, read-only storage record. Create one
+`ReadonlyDynamicInputPage`, write only changed records, then reserve an explicit
+`{ domain, recordStart, recordCount, instanceIndex, member }` range for each draw.
+`member` is the stable public address
+`{ worldIdentity: world.identity, entityKey, drawItemIndex, instanceOrdinal }`.
+Its
+`contentRevision`, `bufferGeneration`, and `deviceGeneration` are separate
+facts; stale ranges and consumption before an upload return a structured error.
+The page uses the existing instance bind group's free binding and never uses
+skinning's `customDataStart`. Publish the page to the existing Renderer owner
+before drawing:
+`renderer.setSurfaceDynamicInput({ page, ranges, projectionRevision, frameTime })`.
+Advance `projectionRevision` only when range membership or addresses change;
+record values and World time keep the current revision so stable frames reuse
+the retained validation and consumption projection.
+Range order is irrelevant: Render joins each range to the admitted candidate by
+`member` and rejects missing, duplicate, or non-admitted identities.
+
+#### Linear HDR optical oracle
+
+The physical oracle observes the real Pack → GUID → World → medium nearest/color
+path before exposure, tone mapping, and anti-aliasing. Arm the next successful
+submit with `renderer.requestObservation(['linear-hdr'])`, keep its `FrameReceipt`,
+then call `renderer.observe(receipt, { include: ['linear-hdr'] })`. The returned
+bytes are padded-row `rgba16float`; `frameId`, device and graph generations,
+texture identity, and readback identity bind them to that exact completed frame.
+When no observation is requested, the renderer does not copy, map, or synchronously
+read this attachment.
+
+> [!IMPORTANT]
+> Compare optical math in this linear attachment. A canvas screenshot is an
+> exposed, tone-mapped, anti-aliased presentation artifact and cannot prove the
+> Beer-Lambert, scatter, or Fresnel contract.
+
+The permanent fixture loads authored water through the Preview Pack, freezes the
+camera, medium parameters, paired background, light, event time, and fixed ROI,
+then compares the observed half-floats with an independent double-precision
+screen-space reference. Its evidence also carries the actual nearest/color
+program and resource generations plus the completed submission receipt.
+
+Author 4x coverage through the Camera component. ECS fields retain their numeric
+schema representation; `ANTIALIAS_MSAA` extracts to the public closed
+`antialias: 'msaa'` render fact:
+
+```ts
+import { ANTIALIAS_MSAA, Camera, orthographic } from '@forgeax/engine/render';
+
+world.spawn({
+  component: Camera,
+  data: {
+    ...orthographic({ left: -3, right: 3, bottom: -2, top: 2 }),
+    antialias: ANTIALIAS_MSAA,
+  },
+});
+```
+
+The edge oracle independently projects the authored rod, wall, shoreline, and
+rough-water rectangles onto the canonical four sample positions. Fully covered
+control regions calibrate each authored linear-HDR endpoint. For opaque edges,
+the nearest depth sample selects its matching color before the full-coverage
+water pass. For partial water coverage, the final hardware resolve averages the
+independently predicted covered samples. The oracle rejects the opposite policy,
+checks a small moving-camera interval, repeats after an 800-by-450 backing resize,
+and keeps the physical maximum per-channel error at `0.05`. Its pure four-sample
+counterexample separately proves why averaging color and then choosing the
+nearest depth loses the color/depth pair.
+
+```sh
+FORGEAX_SURFACE_LANE_PARITY=1 pnpm exec vitest run --project=dawn --retry=0 \
+  --maxWorkers=1 --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.dawn.test.ts
+
+FORGEAX_SURFACE_LANE_PARITY=1 pnpm exec vitest run \
+  --config vitest.browser.config.ts --project=browser --retry=0 \
+  --maxWorkers=1 --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.browser.test.ts
+
+FORGEAX_SURFACE_MSAA4X=1 FORGEAX_SURFACE_LANE_PARITY=1 \
+  pnpm exec vitest run --project=dawn --retry=0 --maxWorkers=1 \
+  --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.dawn.test.ts
+
+VITE_FORGEAX_SURFACE_MSAA4X=1 FORGEAX_SURFACE_LANE_PARITY=1 \
+  pnpm exec vitest run --project=browser --retry=0 --maxWorkers=1 \
+  --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.browser.test.ts
+
+# Public App lifecycle: World-time water events plus a cooked GPU splash.
+FORGEAX_SURFACE_APP_LIFECYCLE_ONLY=1 pnpm exec vitest run --project=dawn \
+  --retry=0 --maxWorkers=1 --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.dawn.test.ts
+
+VITE_FORGEAX_SURFACE_APP_LIFECYCLE_ONLY=1 pnpm exec vitest run --project=browser \
+  --retry=0 --maxWorkers=1 --no-file-parallelism \
+  packages/runtime/src/__tests__/surface-standard-pipeline.browser.test.ts
+```
+
+The lifecycle gate enqueues two deduplicated impacts into one attached World.
+Its Update system takes one `Time.elapsed` snapshot, stamps both Surface records,
+and starts the matching `ParticleEffectPlayer` edges. The splash is the authored
+`surface-water-splash.pack.json` asset: the Pack transport resolves its GUID,
+`loadVfxGpuEffect` loads its cooked program, and `createVfxRuntimeHost` contributes
+the production renderer feature. The gate rejects an effect without a renderer;
+an intent-only program is not visible evidence.
+
+Before each target submit, the gate arms the existing `linear-hdr` observation.
+It reads pre-frozen 16-by-16 water-A, water-B, and above-water splash ROIs from
+that completed receipt, and compares every pixel. The mask never depends on
+brightness, medians, or observed error. Evidence carries the frame, device,
+graph, texture, and readback identities. The active splash ROI must change and
+return to its baseline after the effect expires; the VFX host must also retire
+both players. `rgba16float` samples remain unclamped linear values, including
+values above 1, and use the same maximum per-channel error of `0.05` at every
+lifecycle stage. The oracle does not round them through an 8-bit domain.
+
+A real wait while paused preserves World time, committed VFX state, receipt
+count, and the exact active completed image: `paused` reuses the active receipt
+and does not submit a zero-delta frame. `resume()` continues from retained World
+time without adding the paused host interval or replaying either splash. The
+later `stepFrame(0.05)` calls are explicit deterministic simulation steps used
+to reach camera coverage and expiry; they advance World time and therefore are
+not evidence that a paused App remains frozen. In Dawn only, a timer supplies
+the missing host scheduling primitive; the same App remains the sole owner of
+World update and Renderer draw.
+
+### LightProbe to ProbeBlend to Surface example
+
+The following scene uses one authored water material for two entities. Each
+entity selects a different local `LightProbe` domain, while both consume the
+same bounded dynamic-input page. The renderer derives `ProbeBlendRecord`, slot,
+generation, and the direct or scene-index consumer lane from the attached
+World; application code does not build a second probe table.
+
+`drawProbeLitWater` receives an already-constructed Runtime `Renderer`.
+Construct it at the Runtime boundary with `await createRenderer(canvas)`, check
+the returned `Result` (`if (!result.ok) throw result.error`), and pass
+`result.value` to this helper. Runtime completes renderer initialization before
+returning that value, so the render helper does not own a second initialization
+promise.
+
+```ts
+import { Time, World } from '@forgeax/engine-ecs';
+import { createPlaneGeometry } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  DirectionalLight,
+  LightProbe,
+  MeshFilter,
+  MeshRenderer,
+  ReadonlyDynamicInputPage,
+  type Renderer,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { type AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { AssetGuid, MaterialAsset } from '@forgeax/engine-types';
+
+export async function drawProbeLitWater(
+  renderer: Renderer,
+  assets: AssetRegistry,
+  waterGuid: AssetGuid,
+) {
+  // The Pack producer cooks the authored MaterialAsset and its Surface module;
+  // runtime consumers load only the GUID-addressed publication.
+  const loaded = await assets.loadByGuid<MaterialAsset>(waterGuid);
+  if (!loaded.ok) throw loaded.error;
+  const water = loaded.value;
+  const dynamicInput = water.surface?.dynamicInput;
+  if (water.surface?.model !== 'single-layer-medium' || dynamicInput === undefined) {
+    throw new Error('expected an authored single-layer-medium Surface');
+  }
+
+  const world = new World();
+  const plane = createPlaneGeometry(1.8, 1.8).unwrap();
+  const mesh = world.allocSharedRef('MeshAsset', plane);
+  const material = world.allocSharedRef('MaterialAsset', water);
+  const waterEntities = [-1.2, 1.2].map((x) =>
+    world
+      .spawn(
+        { component: Transform, data: { pos: [x, 0, 0] } },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [material] } },
+      )
+      .unwrap(),
+  );
+
+  const red = new Float32Array(27);
+  red[0] = 1.8;
+  const blue = new Float32Array(27);
+  blue[2] = 1.8;
+  world.spawn(
+    { component: Transform, data: { pos: [-1.2, 0, 0] } },
+    { component: LightProbe, data: { irradiance: red, radius: 1 } },
+  );
+  world.spawn(
+    { component: Transform, data: { pos: [1.2, 0, 0] } },
+    { component: LightProbe, data: { irradiance: blue, radius: 1 } },
+  );
+  world.spawn(
+    { component: Transform, data: { pos: [0, 0, 6] } },
+    {
+      component: Camera,
+      data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 20 },
+    },
+  );
+  world.spawn({
+    component: DirectionalLight,
+    data: { direction: [0, 0, -1], color: [1, 1, 1], intensity: 1 },
+  });
+
+  const page = ReadonlyDynamicInputPage.create({
+    sourceId: 'water-events',
+    pageId: 1,
+    schema: dynamicInput,
+  }).unwrap();
+  const eventLifetimeSeconds = 0.45;
+  const events = [
+    { position: [-1.2, 0, 0] as const, time: 0, eventId: 1 },
+    { position: [1.2, 0, 0] as const, time: 0, eventId: 2 },
+  ] as const;
+  let publishedEventCount = 0;
+  let projectionRevision = 1;
+  let publishedDeviceGeneration = renderer.inspect().frame.deviceGeneration;
+  page.reconfigureDevice(publishedDeviceGeneration).unwrap();
+
+  const reserveFreshRanges = () =>
+    waterEntities.map((entityKey, index) =>
+      page
+        .reserveRange({
+          domain: index === 0 ? 'water-left' : 'water-right',
+          recordStart: index,
+          recordCount: 1,
+          instanceIndex: index,
+          member: {
+            worldIdentity: world.identity,
+            entityKey,
+            drawItemIndex: 0,
+            instanceOrdinal: 0,
+          },
+        })
+        .unwrap(),
+    );
+  let ranges = reserveFreshRanges();
+  let deviceLost = renderer.state() === 'device-lost';
+
+  const publishDynamicInput = (now: number): void => {
+    const activeEvents = events.filter(
+      (event) => now >= event.time && now - event.time < eventLifetimeSeconds,
+    );
+    const recordsToRewrite = Math.max(publishedEventCount, activeEvents.length);
+    for (let index = 0; index < recordsToRewrite; index += 1) {
+      page
+        .writeRecord(
+          index,
+          activeEvents[index] ?? { position: [0, 0, 0], time: -1_000, eventId: 0 },
+        )
+        .unwrap();
+    }
+    publishedEventCount = activeEvents.length;
+    renderer.setSurfaceDynamicInput({ page, ranges, projectionRevision, frameTime: now });
+  };
+
+  const recoverAndRepublish = async (): Promise<number> => {
+    if (renderer.state() !== 'device-lost') {
+      throw new Error('water recovery requires the Renderer device-lost state');
+    }
+    const recovered = await renderer.recover();
+    if (!recovered.ok) throw recovered.error;
+    const nextDeviceGeneration = renderer.inspect().frame.deviceGeneration;
+    if (nextDeviceGeneration <= publishedDeviceGeneration) {
+      throw new Error('water recovery did not publish a new device generation');
+    }
+    const previousRanges = ranges;
+    page.reconfigureDevice(nextDeviceGeneration).unwrap();
+    ranges = reserveFreshRanges();
+    if (
+      ranges.some(
+        (range, index) =>
+          range === previousRanges[index] ||
+          range.deviceGeneration !== nextDeviceGeneration ||
+          range.bufferGeneration === previousRanges[index]?.bufferGeneration,
+      )
+    ) {
+      throw new Error('water recovery reused a pre-recovery dynamic range');
+    }
+    publishedDeviceGeneration = nextDeviceGeneration;
+    projectionRevision += 1;
+    publishDynamicInput(world.getResource(Time).elapsed);
+    deviceLost = false;
+    return nextDeviceGeneration;
+  };
+
+  const unsubscribe = renderer.subscribe((event) => {
+    if (event.kind === 'state-changed' && event.current === 'device-lost') {
+      deviceLost = true;
+    }
+  });
+  try {
+    const attachment = renderer.attach(world);
+    if (!attachment.ok) throw attachment.error;
+    const attached = attachment.value;
+    publishDynamicInput(world.getResource(Time).elapsed);
+    world.update(1 / 60).unwrap();
+    const submitAndObserve = async () => {
+      // The Renderer keeps this logical World lease valid across recovery;
+      // retry the same lease after the page and ranges are revalidated.
+      const submitted = renderer.draw({
+        leases: [attached],
+        camera: { lease: attached },
+        environment: { lease: attached },
+      });
+      if (!submitted.ok) throw submitted.error;
+      const completed = await submitted.value.completed;
+      if (!completed.ok) throw completed.error;
+      const observed = await renderer.observe(submitted.value, { include: ['draws'] });
+      if (!observed.ok) throw observed.error;
+      return submitted.value;
+    };
+
+    let submitted: Awaited<ReturnType<typeof submitAndObserve>>;
+    try {
+      submitted = await submitAndObserve();
+    } catch (cause) {
+      // A first frame can fail before it yields a receipt. Recover only when
+      // the public lifecycle reports the actual device-lost state.
+      if (renderer.state() !== 'device-lost') throw cause;
+      await recoverAndRepublish();
+      submitted = await submitAndObserve();
+    }
+    if (deviceLost || renderer.state() === 'device-lost') {
+      await recoverAndRepublish();
+      submitted = await submitAndObserve();
+    }
+    const inspection = renderer.inspect();
+    if (submitted.deviceGeneration !== publishedDeviceGeneration) {
+      throw new Error('water draw receipt does not match the published device generation');
+    }
+    return {
+      world,
+      attached,
+      page,
+      receipt: submitted,
+      submission: inspection.renderScene.submission,
+      deviceGeneration: inspection.frame.deviceGeneration,
+    };
+  } finally {
+    unsubscribe();
+  }
+}
+```
+
+The repository exercises this route through real Pack/GUID publication and a
+physical texture or compositor readback:
+
+```bash
+pnpm exec vitest run --project=dawn \
+  packages/runtime/src/__tests__/surface-standard-pipeline.dawn.test.ts --retry=0
+pnpm exec vitest run --config vitest.browser.config.ts --project=browser \
+  packages/runtime/src/__tests__/surface-standard-pipeline.browser.test.ts --retry=0
+
+# Same material, scene, time, events, ProbeBlend domains, exposure, and ROI;
+# cold direct -> GPU -> direct. The original 0.05 RGB oracle remains active.
+FORGEAX_SURFACE_LANE_PARITY=1 FORGEAX_DAWN_LIGHTWEIGHT=1 \
+  pnpm exec vitest run --project=dawn \
+  packages/runtime/src/__tests__/surface-standard-pipeline.dawn.test.ts --retry=0
+```
+
+Direct medium draws use a dedicated group(3): ordinary instance transforms,
+the retained ProbeBlend record, dynamic page, per-member frame rows, shared
+frame time, and a producer-owned per-draw frame-base uniform. The vertex shader
+addresses `frameBase + instance_index`; neither GUID order nor a scene-index
+visible slot is used to infer that address. Missing member identity, page,
+generation, or frame-base publication fails the draw through the structured
+Render error path.
+
+After a successful submission, `renderer.inspect().renderScene.gpuDriven.surfaceArtifact`
+exposes the selected direct/scene-index entries and artifact/resource
+generation. `renderer.inspect().renderScene.submission` separates
+`requestedLane` from the command-derived `actualLane` and publishes only
+nearest/color passes that encoded a real `draw*` or `draw*Indirect` command.
+When the current Standard frame carries the reflection fallback MRT, the same
+submission projection reports `actualLane: 'direct'` with
+`actualLaneReason: 'reflection-fallback-mrt'`. This is a pass-ownership
+constraint, not a device-capability result; the reason is absent again when a
+later frame resumes the ordinary GPU-driven lane.
+Direct rows contain the actual command range (`firstInstance` remains `0`),
+the producer's separate `surfaceFrameBase`, and the member identities bound by
+that command. Every command reports the exact selected artifact's
+`receiptIdentity`/`receiptGeneration`; `programEvidence: 'missing'` means the
+recorder could not prove that producer identity. Indirect rows contain the
+actual indirect buffer identity and byte offset. `status: 'completed'` is published only after the existing queue
+completion fence resolves for the same device generation.
+
+GPU member identity is opt-in because it requires readback. Call
+`await renderer.observe(frameReceipt, { include: ['draws'] })` before reading
+the inspection row. Until that call, an indirect pass reports
+`memberEvidence: 'indirect-readback-required'` and omits members. The observe
+path reuses the selector telemetry copy, reads its actual visible rows, and
+then reports `indirect-visible-readback`. The readback carries its recording
+sequence, frame/device/resource/view identity, and per-pass indirect ranges;
+an older or reordered shared-buffer result is rejected even within one device
+generation. Nearest and color share the same
+visible member set because both consume the same submitted selector/indirect
+projection; each pass still has its own encoded command receipt. CPU candidate
+lists are never substituted for this GPU readback. The lane-parity gates pair
+these command facts with completed fixed-ROI pixels at the unchanged `0.05`
+RGB epsilon.
+
+The public consumer sequence is `draw` -> `observe` -> `inspect`:
+
+```ts
+import type { SurfaceGpuIndirectParameters } from '@forgeax/engine/render';
+
+const receipt = renderer.draw(frameInput);
+if (!receipt.ok) throw receipt.error;
+const observed = await renderer.observe(receipt.value, { include: ['draws'] });
+if (!observed.ok) throw observed.error;
+const inspection = renderer.inspect();
+const completePasses = (inspection.renderScene.submission?.passes ?? []).filter(
+  (pass) => pass.memberEvidence === 'indirect-visible-readback',
+);
+const indirectParameters: readonly SurfaceGpuIndirectParameters[] = completePasses.flatMap(
+  (pass) => {
+    if (pass.indirectParameters === undefined) throw new Error('complete GPU readback is missing');
+    return pass.indirectParameters;
+  },
+);
+void indirectParameters;
+```
+
+`pass.indirectParameters` appears only after the requested observation resolves
+and the renderer accepts a complete matching GPU readback. A pass before
+readback, with no complete identity match, reports
+`memberEvidence: 'indirect-readback-required'` and has no parameters. A valid
+readback whose bounded command sample is truncated reports
+`memberEvidence: 'indirect-visible-readback-truncated'` and also has no
+parameters; its saved and dropped counts remain diagnostic facts. GPU-byte
+truncation, a stale/reordered copy, or an identity mismatch is rejected and
+leaves the pass in `indirect-readback-required`. Only a complete valid copy
+reports `memberEvidence: 'indirect-visible-readback'` with parameters. These
+states are diagnostic facts and never proof when the required evidence is
+absent. Each record is bound to the same
+`sequence`, `frameId`, `deviceGeneration`, `resourceGeneration`, `viewIdentity`,
+and Surface `pass` as the published submission, plus the exact indirect
+`indirectBufferIdentity` and `indirectOffset`. For indexed commands, `count`,
+`first`, `instanceCount`, signed `baseVertex`, and `firstInstance` decode the
+five WebGPU indirect words. For non-indexed commands, `count`, `first`,
+`instanceCount`, and `firstInstance` decode the four words and `baseVertex` is
+zero by definition.
+
+Each pass exposes `totalCommandCount`, bounded `savedCommandCount`,
+`droppedCommandCount`, and `truncated`. A truncated indirect row is diagnostic
+evidence, never a complete member set; a valid readback labels it
+`indirect-visible-readback-truncated` and omits `indirectParameters`. A direct
+row uses `direct-command-members-truncated` for the same bounded-sample limit.
+
+The Render owner validates the cooked layout, source/page identity, generation,
+range bounds, and device storage limit. It begins a detached upload and commits
+the page revision only after every queue write succeeds; graph submission then
+consumes the validated ranges. The same input is carried through GPU
+preparation and the recovery candidate. In the scene-index lane, the renderer
+maps each GPU-written visible member's stable candidate row to a frame row and
+keeps each producer `instanceIndex` in the row; the atomic compact draw slot is
+never used as a dynamic-input address.
+
+On a device with compute, storage-buffer, and indirect-drawing capabilities,
+GPU-driven preparation records the published Surface submission and binds the
+Surface page and frame records through the existing GPU-driven instance owner.
+The Standard Forward and Deferred graph owners allocate the two
+`nearest-layer`/`color` targets and share the transmission backdrop producer.
+The backdrop is the paired opaque color input. At 1x, both Standard paths copy
+the completed depth into an `r32float` sampled target. At 4x MSAA, Render does
+not use the hardware-averaged color resolve as the medium backdrop. A typed
+fullscreen producer examines all four depth samples, selects the nearest
+sample, and publishes both that depth and the color at the same sample index.
+The nearest-water pass uses 4x color and depth attachments and the identical
+paired rule before the color pass consumes it. Both resolved depth facts are
+`r32float` with an unfilterable-float/non-filtering binding, so the color pass
+never samples a depth attachment while writing scene depth. Inputs other than
+the admitted 1x or paired 4x forms fail with `resource-descriptor-invalid`;
+`addSingleLayerMediumPasses` never creates a synthetic depth value. This policy
+is a nearest-sample coverage resolve, not an average of already-resolved color.
+The color pass binds the copied depth, the preceding nearest-layer color/depth
+pair, and the shared backdrop through the existing material bind-group owner.
+GPU-driven recording reuses the existing Standard raster
+dispatch with a Surface-family filter; devices without the required
+capability use the existing CPU record lane and its structured admission
+reason. These tests prove the owner boundary and fail-closed behavior;
+Browser, Dawn, and physical GPU frame evidence remain separate gates. A
+missing Surface ABI, pass, resource, or prepared generation is a
+producer/preparation error. The public paired math and two example Surface
+modules live in
+[`src/examples/single-layer-medium-surface.ts`](src/examples/single-layer-medium-surface.ts).
+
 The public route is one `RenderFeature<FrameData>` through the Standard
 Pipeline and the active RenderGraph pass. In the examples below, `type FrameData`
 is the producer-owned extracted value. A feature extracts one frame value,
@@ -109,6 +802,14 @@ that was still pending. This is a receipt of admitted commands, not a GPU
 readback or proof that an indirect draw produced non-zero instances; producers
 that need those facts must use their existing readback or tape evidence.
 
+`BarrelDistortion` is supplied by the ordinary ordered RenderFeature host. A
+missing or zero-strength component produces no allocation, upload, or pass;
+the feature still declares its shader for production validation. A positive
+component adds one fullscreen pass after linear-LDR LUT output and before FXAA
+and final encoding. There is no separate built-in registration path, so feature
+ordering and retirement use the same graph and in-flight lifetime rules as
+other post-process features.
+
 ## RenderFeature: the producer seam (first-read index)
 
 The public route is one `RenderFeature<FrameData>` through the active RenderGraph
@@ -207,6 +908,8 @@ index path, not a second schema.
 import {
   ANTIALIAS_TAA,
   Atmosphere,
+  BLOOM_DISABLED,
+  CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   Fog,
   type FramePlan,
@@ -229,6 +932,17 @@ 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.
 
+An Atmosphere also requires exactly one `DirectionalLight` sun. A direct render
+extraction with no sun routes `SunCardinalityError` through the World-owned
+error boundary (`console.error` with the structured error) before extraction
+throws; that internal route is deliberately separate from `app.onError`.
+`app.onError` receives errors returned by the App frame loop and renderer event
+stream. Inspect `error.code` and `error.detail.value`, repair the owning World,
+then retry the same extraction or the next frame. For zero suns, spawn one
+`DirectionalLight`; for multiple suns, remove the extras so the Atmosphere has
+one owner. The renderer does not manufacture a fallback sun or retain a
+partially selected environment.
+
 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
@@ -240,6 +954,52 @@ 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 uses one bounded analytic Rayleigh/Mie daylight evaluator. Rayleigh
+and Mie controls affect their spectral scattering and extinction, while solar
+radiance scales linearly with the selected light. A 1.5 exponent shapes the
+Rayleigh color response before solar scaling; the Mie lobe remains additive.
+A smooth effective air-mass
+bound (four zenith columns) avoids a saturated neutral horizon. This is an
+explicit game-oriented clear-sky approximation, not the retired Perez fit or a
+full spherical multiple-scattering solution. The existing cache owns all work;
+background pixels still sample the cube, and the separate sun disc is unchanged.
+
+### Atmosphere controls and fixed-exposure comparisons
+
+`Atmosphere` keeps the visible disc and the analytic sky response as separate
+controls. `circumsolarStrength` and `circumsolarWidth` affect only the Mie
+forward lobe used while producing the cached sky cube. The defaults preserve the
+baseline response; `sunAngularRadius` still controls the separate disc in the
+background pass and does not grow a halo.
+
+| Field | Default | Valid range | Meaning |
+|:--|:--:|:--|:--|
+| `circumsolarStrength` | `1` | `[0, 4]` | Multiplier for the circumsolar Mie lobe |
+| `circumsolarWidth` | `1` | `[0.25, 4]` | Relative lobe width; larger values broaden it, smaller values narrow it |
+| `sunAngularRadius` | `0.004675` rad | `[0, +∞)` | Radius of the separate visible sun disc; `0` disables the disc |
+
+For an angular or sunset sweep, hold the camera exposure in manual mode and
+disable Bloom so the measurement belongs to the Atmosphere response. Vary the
+two circumsolar fields while leaving `sunAngularRadius` unchanged:
+
+```ts
+world.set(atmosphere, Atmosphere, {
+  circumsolarStrength: 1.5,
+  circumsolarWidth: 2,
+  sunAngularRadius: 0.004675,
+}).unwrap();
+world.set(camera, Camera, {
+  exposureMode: CAMERA_EXPOSURE_MODE_MANUAL,
+  exposure: 1,
+  bloom: BLOOM_DISABLED,
+}).unwrap();
+```
+
+The fixed exposure and Bloom setting are comparison setup, not additional
+Atmosphere state. Use the renderer's submitted frame or a real Browser/Dawn
+readback for visual claims; source values and a sky-cube upload do not prove a
+pixel response.
+
 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
@@ -347,6 +1107,315 @@ before publication; an invalid update keeps the renderer's last-known-good
 fog frame and exposes the structured failure through the existing inspection
 path. There is no app-local fog state.
 
+### VolumetricFog authoring, World time, and recovery
+
+`VolumetricFog` is an authored, one-owner component backed by a linear 3D
+`TextureAsset`. The selected light must be a live same-World
+`DirectionalLight`, `PointLight`, or `SpotLight`; Point/Spot selection also
+requires the corresponding `Transform`. Validate the authoring POD before
+spawning the component, then let the existing RenderSystem extract it. The
+World `Time` resource is the only simulation clock: `world.update(delta)`
+advances it, and the volume parameter block receives that elapsed value.
+
+```ts
+import { Time, World } from '@forgeax/engine-ecs';
+import {
+  Atmosphere,
+  BLOOM_DISABLED,
+  CAMERA_EXPOSURE_MODE_MANUAL,
+  Camera,
+  DirectionalLight,
+  VolumetricFog,
+  extractVolumetricFog,
+  perspective,
+  resolveSelectedVolumetricLight,
+  validateVolumetricFog,
+  type VolumetricFogAuthoring,
+  type Renderer,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type { TextureAsset } from '@forgeax/engine-types';
+
+const world = new World();
+const densityAsset: TextureAsset = {
+  kind: 'texture',
+  shape: { viewDimension: '3d', extent: { width: 4, height: 4, depth: 4 } },
+  format: 'r8unorm',
+  colorSpace: 'linear',
+  mips: { kind: 'none' },
+  data: new Uint8Array(4 * 4 * 4).fill(32),
+};
+const density = world.allocSharedRef('TextureAsset', densityAsset);
+// A production project normally obtains this TextureAsset from its existing
+// Pack/Catalog load path, then allocates the same shared handle in this World.
+// The inline payload keeps this authoring example executable and deterministic.
+const camera = world.spawn(
+  { component: Transform, data: { pos: [0, 0, 3] } },
+  { component: Camera, data: {
+    ...perspective({ fov: Math.PI / 4, aspect: 16 / 9 }),
+    exposureMode: CAMERA_EXPOSURE_MODE_MANUAL,
+    exposure: 1,
+    bloom: BLOOM_DISABLED,
+  } },
+).unwrap();
+const sun = world.spawn({
+  component: DirectionalLight,
+  data: { direction: [-0.4, -0.8, -0.3], castShadow: true },
+}).unwrap();
+const atmosphere = world.spawn({
+  component: Atmosphere,
+  data: { circumsolarStrength: 1, circumsolarWidth: 1, sunAngularRadius: 0.004675 },
+}).unwrap();
+
+const authored: VolumetricFogAuthoring = {
+  light: sun,
+  density: {
+    guid: 'density-demo',
+    generation: 1,
+    shape: { viewDimension: '3d', extent: { width: 4, height: 4, depth: 4 } },
+    format: 'r8unorm',
+    colorSpace: 'linear',
+  },
+  bounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+  extinction: [0.2, 0.2, 0.2],
+  albedo: [0.8, 0.8, 0.8],
+  emission: [0, 0, 0],
+  anisotropy: 0,
+  maxDistance: 50,
+};
+const checked = validateVolumetricFog(authored);
+if (!checked.ok) throw checked.error;
+const extracted = extractVolumetricFog([checked.value]);
+if (!extracted.ok) throw extracted.error;
+const selected = resolveSelectedVolumetricLight(world, sun);
+if (selected.status === 'unresolved') {
+  throw new Error(`${selected.reason}: ${selected.hint}`);
+}
+world.spawn({
+  component: VolumetricFog,
+  data: {
+    light: sun,
+    density,
+    boundsMin: authored.bounds.min,
+    boundsMax: authored.bounds.max,
+    extinction: authored.extinction,
+    albedo: authored.albedo,
+    emission: authored.emission,
+    anisotropy: authored.anisotropy,
+    maxDistance: authored.maxDistance,
+  },
+}).unwrap();
+
+world.update(1 / 60).unwrap();
+const elapsed = world.getResource(Time).elapsed; // the projected volume time
+void camera;
+void atmosphere;
+void elapsed;
+```
+
+If validation fails, read its structured `code`, `expected`, `hint`, and typed
+`detail`. If light resolution is unresolved, read its `reason`, `expected`,
+`actual`, and `hint`; repair the owning authoring field, and extract again.
+Do not manufacture a light or a density fallback. After a submitted frame,
+`renderer.inspect().volumetricFog` reports `status`, `resourceStage`, the
+selected-light facts, and candidate/LKG generations. For a renderer device
+loss, wait for the host recovery boundary, call `await renderer.recover()`,
+then submit the same World again and inspect the replacement generation:
+
+```ts
+import type { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+
+// After the existing createRenderer(canvas) happy path returns a Renderer,
+// call `await recoverAndDraw(renderer, world)` with the World above.
+async function recoverAndDraw(renderer: Renderer, world: World): Promise<void> {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  const lease = attached.value;
+  if (renderer.state() === 'device-lost') {
+    const recovered = await renderer.recover();
+    if (!recovered.ok) throw recovered.error;
+  }
+  const retry = renderer.draw({
+    leases: [lease],
+    camera: { lease },
+    environment: { lease },
+  });
+  if (!retry.ok) throw retry.error;
+  const completed = await retry.value.completed;
+  if (!completed.ok) throw completed.error;
+  const volume = renderer.inspect().volumetricFog;
+  console.log(volume?.status, volume?.resourceStage, volume?.generation);
+}
+```
+
+The recovery call rebuilds renderer-owned resources; it is not a second volume
+clock or registry. Pausing the simulation means withholding `world.update`.
+Equal time and normal monotonic World ticks up to 100 ms retain eligible
+volume history. Clock rollback, a larger jump, or changed time availability
+invalidates it. Camera, light, medium, size and resource changes still invalidate
+history. Integration and shadow visibility use stable cell centers, so a reset
+does not expose render-frame random noise. The ray uses 96 base intervals;
+segments within four interval lengths of a selected punctual source use four
+midpoints to resolve its inverse-square peak and spot cone. This local refinement
+keeps the density expression and packed shadow resolution unchanged. A real GPU
+punctual-scattering oracle protects spatial accuracy alongside the continuous-frame
+browser check; homogeneous transmittance alone cannot detect light-band artifacts.
+History is clipped to the current
+neighborhood and its weight decays with elapsed World time (at most 0.875 per
+frame, about 87 ms half-life at 60 Hz or slower), limiting trails from animated
+density. `CloudLayer` is the renderer-owned procedural cloud route described
+below; it does not change the volumetric fog component or add a second clock.
+
+### CloudLayer authoring and derived transport
+
+`CloudLayer` is a single World-authored component. Its schema keeps the seed,
+layer bounds, noise scale, coverage, density, wind and quality as serializable
+source facts. `renderComponentsPlugin()` registers it with the normal ECS
+component lease. Cache bytes, light-space shadow projections, per-view history
+and GPU handles remain Render-derived state and can be reconstructed from the
+validated source key.
+
+Coverage is monotonic: zero clears the layer and increasing it admits more of
+its weather-shaped body. Detail erodes this body after altitude shaping; it
+cannot create detached density outside the body. Formation cache version 5
+uses the same integer hash and density composition as both analytic WGSL
+paths, with center-aligned periodic interpolation. Layer thickness controls
+the physical height of two vertical body cells; scale controls four horizontal
+cells per world-space period. Choose comparable body dimensions for cumulus
+rather than compressing a broad cloud into a thin layer. The broad field owns
+85% of body shaping; attenuated high-frequency octaves and bounded subtractive
+erosion preserve connected masses instead of dense detached fragments.
+
+Install the producer through the existing RenderFeature seam when a scene uses
+clouds:
+
+```ts
+import { World } from '@forgeax/engine-ecs';
+import { createRenderer } from '@forgeax/engine-runtime';
+import {
+  Camera,
+  CloudLayer,
+  CloudQualityValue,
+  DirectionalLight,
+  createCloudLayerFeature,
+  perspective,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+
+const canvas = document.querySelector('canvas');
+if (!(canvas instanceof HTMLCanvasElement)) throw new Error('canvas is required');
+const world = new World();
+const camera = world.spawn(
+  { component: Transform, data: { pos: [0, 140, 240] } },
+  { component: Camera, data: { ...perspective({ fov: Math.PI / 4, aspect: 16 / 9 }) } },
+).unwrap();
+const sun = world.spawn({
+  component: DirectionalLight,
+  data: { direction: [-0.4, -0.8, -0.3], color: [1, 0.95, 0.9], intensity: 2 },
+}).unwrap();
+const cloud = world.spawn({
+  component: CloudLayer,
+  data: {
+    seed: 1337,
+    baseHeight: 120,
+    thickness: 80,
+    scale: 0.004,
+    coverage: 0.48,
+    density: 1,
+    wind: [8, 0, 2],
+    quality: CloudQualityValue.medium,
+    shadowRange: 512,
+  },
+}).unwrap();
+const created = await createRenderer(canvas, { features: [createCloudLayerFeature()] });
+if (!created.ok) throw created.error;
+const renderer = created.value;
+const attached = renderer.attach(world);
+if (!attached.ok) throw attached.error;
+world.update(1 / 60).unwrap();
+const drawn = renderer.draw({
+  leases: [attached.value],
+  camera: { lease: attached.value },
+  environment: { lease: attached.value },
+});
+if (!drawn.ok) throw drawn.error;
+console.log(camera, sun, cloud, renderer.inspect().cloudLayer);
+
+world.set(cloud, CloudLayer, { wind: [10, 0, 2] }).unwrap();
+const changed = renderer.draw({
+  leases: [attached.value],
+  camera: { lease: attached.value },
+  environment: { lease: attached.value },
+});
+if (!changed.ok) {
+  console.error(renderer.state(), renderer.inspect().cloudLayer, changed.error);
+  throw changed.error;
+}
+```
+
+If the capability report does not admit the cloud lane, disable that feature at
+assembly time and keep the rest of the renderer running:
+
+```ts
+const created = await createRenderer(canvas, {
+  features: [createCloudLayerFeature({ enabled: false })],
+});
+```
+
+The runtime `createRenderer()` result is returned after the renderer's internal
+initialization barrier has completed, so the public `Renderer` can attach and
+draw immediately after the `Result` check above. The `initialization` Promise
+belongs to the lower-level internal construction seam.
+
+The feature extracts the authored component, World `Time`, and the selected
+directional sun through the normal frame owner. It declares a bounded packed
+`u32` 3D formation cache with three contiguous R8 planes (`weather`, `body`,
+`erosion`; `ceil(3 * R8 texels / 4)` elements and `elements * 4` storage
+bytes), then composites scene-linear HDR color with inverse-view-projection
+rays, scene depth termination, bounded Beer extinction, solar-column
+transmittance, and cloud-interior phase scattering. The same formation and
+coverage contract is used by the CPU reference and the production WGSL path;
+coverage, density and wind are evaluation inputs and do not rebuild the
+reusable planes. The erosion plane repeats three times across the body period,
+adding smaller boundary structure without increasing cache bytes or density
+reads. Direct and approximate multiple scattering use the same light/phase unit
+convention as the volume path and CPU optical reference; view and solar
+sample limits are unchanged. The exported CPU helpers (`buildCloudDensityCache`,
+`integrateCloudCameraPath`,
+`integrateCloudSolarColumn`, `integrateCloudInterior`, and
+`sampleCloudShadow`) remain deterministic reconstruction and recovery tools.
+
+The cloud shadow target is a square, quality-derived `rgba16float` map whose
+world-space projection is texel-snapped around the selected sun anchor. The
+cloud view, shadow and interior consumers share that projection and attenuate
+direct solar transport once. A cloud-enabled view opts into six additional
+`rgba16float` temporal surfaces: radiance, transmittance and representative
+cloud depth, each with current/previous ping-pong slots at `ceil(surface / 2)`
+resolution. One half-resolution transport raster writes the three surfaces as
+an MRT from the same camera integral. A full-resolution resolve upsamples those
+fields, rejects history by world depth, clamps radiance and transmittance to a
+four-neighbour history envelope, and performs the one HDR composite. The
+transport samples the world-space cloud-shadow cache for remaining solar
+optical depth; invalid projection or out-of-range samples use the bounded
+analytic column fallback. There is no second full-resolution raymarch solely
+for cloud depth.
+
+Temporal slots are created only when a view demands them; submit advances the
+transaction from the resolve pass, while abort, resize, recovery and unload
+retire the old generation through the normal queue-fence owner.
+
+Transparent geometry remains depth-read-only unless its authored render state
+explicitly enables `depthWriteEnabled`; this keeps ordinary alpha smoke from
+truncating later volume/cloud segments while allowing an intentional cutout or
+water surface to publish its own depth. Use `inspectCloudLayer()` and the
+renderer's normal feature inspection to read capability, generation,
+temporal-reset and resource facts. Inspection distinguishes CPU cache bytes,
+declared GPU target bytes, and measured GPU bytes; physical adapter timing and
+residency are reported as unavailable until a prepared adapter submits those
+receipts. Unavailable compute or storage support is data rather than a hidden
+fallback texture.
+
 Point shadows use one renderer-owned cube-array `ShadowAtlas`. The public
 `SHADOW_ATLAS_DEFAULT_FACE_SIZE` and `SHADOW_ATLAS_DEFAULT_LAYERS` constants
 are the only capacity owner; extract assigns `shadowAtlasLayer: -1` to
@@ -496,7 +1565,7 @@ switch (spatial.status) {
 `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
+until the paired Browser/Dawn 60-frame carrier, readback, falsifiers, and
 performance gates are present.
 
 SSR temporal feedback and presentation use distinct coordinates without another
@@ -749,7 +1818,7 @@ 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,
-800x600 resolution, 300-frame schedule, ROI, scanline, backend/lane, surface
+800x600 resolution, 60-frame schedule, ROI, scanline, backend/lane, surface
 formats, pixel hash, validation errors and mutation falsifiers.
 
 The report gates are explicit: unique-color ratio $r_U \ge 0.75$, level ratio
@@ -911,20 +1980,131 @@ 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
-validated parameters are `shutterAngle` in `[0, 360]`, `maxRadiusPixels` in
-`[0, 64]`, and integer `sampleCount` in `[4, 16]`. Zero shutter is an explicit
-zero-work case. The feature reads the shared `scene-data-temporal` sampled token
-and contributes one raster pass after optional TAA and before Bloom. It does
-not own a previous frame, write TAA history, allocate storage/compute state, or
-cache an RHI handle.
-
-`renderer.inspect()` exposes only detached Motion Blur POD facts when the
-component is active: status, bounded parameters, demand, pass identity, and
-the invariant `historyWrites: 0`. Invalid parameters and unavailable temporal
-data are structured failures with owner-specific recovery; callers should fix
-the component or capability and retry the same frame. The hello-taa carrier
-contains the four-lane smoke and falsifier evidence.
+The Standard camera enables Motion Blur by carrying the presence-enabled
+component. Authoring stays bounded and validated at the component boundary:
+
+```ts
+import { MotionBlur } from '@forgeax/engine-render';
+
+const result = world.addComponent(cameraEntity, {
+  component: MotionBlur,
+  data: { shutterAngle: 180, maxRadiusPixels: 32, sampleCount: 8, targetFps: 60 },
+});
+if (!result.ok) throw result.error;
+```
+
+| Input / state | Contract |
+|:--|:--|
+| Parameters | `shutterAngle ∈ [0, 360]`, `maxRadiusPixels ∈ [0, 64]`, integer `sampleCount ∈ [4, 16]`, integer `targetFps ∈ [0, 240]`; zero shutter/radius is zero work. |
+| Temporal source | One renderer-owned `scene-data-temporal` sampled target. Motion validity and color reactivity are separate fields. |
+| Post order | TAA resolve → Motion Blur → auto exposure/Bloom/tone output. Motion Blur never writes TAA history. |
+| WebGPU/native lane | One 16×16 tile summary dispatch plus one fused reconstruction dispatch. Long vectors use an even-pixel half-resolution source lattice with depth guidance. |
+| Bounded work | Effective color tiers are exactly `0|4|8|16`; metadata probes are fixed and color work is linear in the tier. There is no radius-squared neighborhood, per-pixel scatter, or atomic accumulation. |
+| WebGL2 fallback | One directional raster gather, explicitly reported as `raster-limited`; it does not claim compute quality or timing parity. |
+
+The authored integer sample count maps to one of the four execution tiers:
+`4..7 → 4`, `8..15 → 8`, and `16 → 16`; a zero-work bypass is `0`. The
+selected tier is the total color budget for every direction, including a
+bounded fallback when all candidates are rejected. There is no implicit
+center tap added to the budget.
+
+For an uncovered moving support, accepted foreground coverage reconstructs a
+bounded portion of an opaque silhouette edge rather than averaging rejected
+support as black. The matching empty-background trail is attenuated by the
+same fixed factor, so the correction redistributes energy and does not add
+another sample. If no source is accepted, the receiver's center color remains
+the conservative fallback. A recovered midpoint anchor is still only partial
+evidence. Compute and raster-limited lanes share the rule without an extra
+pass or radius-sized neighborhood.
+
+Reset and recovery remain observable through the existing temporal owner:
+
+```ts
+const inspection = renderer.inspect();
+if (
+  inspection.motionBlur?.status === 'reset' &&
+  inspection.motionBlur.resetReason === 'time-discontinuity' &&
+  inspection.temporal.resetReason === 'time-discontinuity'
+) {
+  // The next successful draw commits the new baseline; retry the same renderer.
+  renderer.draw(frameInput());
+}
+```
+
+After a rejected graph or queue submit, `motionBlur.lastFailure` is
+`'submit-failure'` while the previous successful temporal view remains the
+baseline. A `'scene-data-unavailable'` failure means the shared
+`standard-scene-data` producer or its `rgba16float` capability was not
+admitted; repair that producer/capability and retry the same frame. It never
+creates a private Motion Blur history target.
+
+The renderer carries the raw host render sample timestamp through App/Worker
+and accepts it only after a successful submit. A gap greater than `100 ms`
+creates a `time-discontinuity` reset; a normal `30 Hz` interval remains valid,
+and a failed submit cannot advance the accepted temporal clock. Pause/resume
+also marks the next frame as a new baseline. Instance pose updates preserve
+the last submitted transform. Collection replacement mints new identity
+generations by default; a producer that keeps an instance through compaction
+or reorder can pass its prior generation tokens in the new order, allowing the
+record stage to pair each current transform with the real prior transform.
+
+`renderer.inspect().motionBlur` exposes detached POD facts: status (`off`,
+`active`, `reset`, `limited`, or `invalid`), selected lane, effective tier,
+pass count, reset reason, last failure, and `historyWrites: 0`. Invalid public
+parameters return `MotionBlurValidationError` with code
+`motion-blur-invalid-params`; repair the named component field or capability
+and retry the same frame. The typed cause is preserved by the public draw
+result, so a caller can repair the named field without parsing `Error.message`:
+
+```ts
+const result = renderer.draw(frameInput);
+if (!result.ok && result.error.code === 'motion-blur-invalid-params') {
+  console.error(result.error.detail.field, result.error.detail.value);
+  // Repair the component field, then retry the same frame.
+}
+```
+
+The hello-taa carrier contains the Dawn, Browser, WebGL2, RhiNull, performance,
+and source-level falsifier paths.
+
+## Multiscale HDR Bloom
+
+Bloom is a Camera-owned Standard post feature. `bloom` selects the enabled
+path, while `bloomIntensity` is bounded to `[0, 8]`, `bloomThreshold` to
+`[0, 65504]`, `bloomSoftKnee` to `[0, 1]`, and `bloomScatter` to `[0, 0.95]`.
+The defaults are intensity `1`, threshold `1`, soft knee `0.5`, and scatter
+`0.7`; the disabled value and intensity `0` are exact zero-work cases.
+
+Game authors import this contract through the public umbrella facade:
+
+```ts
+import {
+  BLOOM_ENABLED,
+  Camera,
+  TONEMAP_REINHARD_EXTENDED,
+} from '@forgeax/engine/render';
+```
+
+The physical `@forgeax/engine-render` package remains the repository ownership
+unit; it is not the recommended consumer import path.
+
+An enabled frame stays in the linear HDR domain and uses one typed graph:
+five ceil-halved downsample levels `D0..D4`, four tent upsample levels
+`U3..U0`, then one HDR composite before tone mapping. `D0` applies the soft
+threshold per source texel and weights each texel by its exact source/target
+rectangle overlap, including odd extents. `D1..D4` use the shared 13-tap
+reduction; each upsample blends the current level with the next coarser level
+using the authored scatter. Composite adds only RGB bloom and preserves the
+scene alpha.
+
+`renderer.inspect().bloom` is detached POD evidence from the compiled graph.
+Its level dimensions, `targetBytes`, pass topology, and
+`residentChildBytes` come from validated descriptors and active resource
+ownership, not from an expected-size calculation. A missing, forged, or
+invalid descriptor graph reports `invalid`; an off camera reports `empty` and
+zero target/resident bytes. Candidate generations remain behind the existing
+LKG fence and are released only after the submit fence; device recovery
+rehydrates the same Bloom bundle before a new receipt is accepted.
 
 > [!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.
@@ -962,7 +2142,7 @@ base-only root keeps `forward + deferred + shadow`, while declaring any
 second-stage layer or physical texture selects `forward + shadow`.
 
 ```ts
-import { Materials } from '@forgeax/engine-render';
+import { Materials } from '@forgeax/engine/render';
 
 const material = Materials.standard({
   baseColor: [0.72, 0.48, 0.22, 1],
@@ -1065,113 +2245,75 @@ 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.
 
-### Renderer-owned Instances and CPU bounds
+### World-owned Instances and CPU bounds
 
-`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.
+`Instances.transforms` holds packed column-major mat4 values in World-managed
+storage. Author the same field in keyed Scene assets, glTF imports, or ECS;
+neither creation nor saving requires a Renderer.
 
 ```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 transforms = new Float32Array(20_000 * 16);
+for (let index = 0; index < 20_000; index++) {
+  const offset = index * 16;
+  transforms[offset] = transforms[offset + 5] =
+    transforms[offset + 10] = transforms[offset + 15] = 1;
+  transforms[offset + 12] = (index % 100) * 2;
+  transforms[offset + 14] = Math.floor(index / 100) * 2;
 }
-
-const collection = renderer.instances.create({
-  transforms: identityMatrices(instanceCount),
-}).unwrap();
-world.spawn(
+const entity = world.spawn(
+  { component: Transform, data: {} },
   { 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,
-});
+  { component: Instances, data: { transforms } },
+).unwrap();
 
-// 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();
-// A read-only observation does not advance the renderer upload cursor.
-const observed = renderer.instances.peek(collection.collectionId).unwrap();
-renderer.instances.release(collection.collectionId);
+transforms[12] = 4;
+world.set(entity, Instances, { transforms }).unwrap();
 ```
 
-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. `peek` returns the same detached matrices without
-advancing the renderer upload cursor, so read-only inspection cannot hide a
-later dirty range. 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.
+World copies external input and publishes changes through its normal component
+write path. Mutating the input array after spawn/set does not edit the World.
+Use `world.set` or a declared writable query; do not mutate inspection snapshots.
+
+| Boundary | Owner and invariant |
+|:--|:--|
+| Authoring and Scene save | World/Scene retains matrices, not renderer-local IDs. Saving and reopening preserves the layout. |
+| Renderer projection | Current World change evidence drives the existing persistent RenderScene. Independent Renderers accept independently; stable matrices reuse the detached snapshot and revision. |
+| CPU bounds and drawing | Mesh bounds, holder world transform and instance-local matrices feed one projection shared by direct, GPU-driven and capability fallback lanes. |
+| Temporal identity | Ordinals retain identity across pose edits. Count changes seed new identities; previous matrices come from the last successful submission. |
+| GPU lifetime | Record owns buffer capacity, upload revisions, internal chunks and device generation. No game-side collection manager is required. |
+
+Render derives CPU union bounds from the mesh AABB and instance-local matrices,
+then applies the holder's world transform. Bounds are not a second authored
+field. A missing or invalid mesh AABB yields a conservative no-cull result;
+repair the mesh producer and reload the same asset instead of inventing a
+game-side bounds override.
+
+An empty array means zero instances. Invalid stride reports
+`instance-transforms-stride-mismatch`; non-finite values report
+`instance-transforms-invalid` before rendering that entity. Repair the World or
+source Scene data and retry. All-zero matrices are finite but have zero
+homogeneous `w`; initialize valid transforms for visible geometry.
 
 #### Instance inspection and recovery
 
-`renderer.inspect().instanceCollections` is detached, bounded evidence for
-every live collection. Each row contains:
+`renderer.inspect().instanceCollections` reports detached runtime evidence.
+Its `collectionId` is a private projection identity, not a Scene field or an
+authoring handle. There is no public `renderer.instances` mutation API.
 
 | Field | Meaning |
 |:--|:--|
-| `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.
+| `collectionId`, `count`, `revision` | Renderer-local projection identity, matrix count and accepted content revision. |
+| `residentGeneration`, `lane` | Device generation and direct/chunked storage/uniform residency, or unresident/unavailable state. |
+| `uploadRanges`, `uploadedBytes` | Upload work observed in the latest rendered frame; stable frames report zero. |
+| `requestedBytes`, `supportedBytes`, `backend`, `owner` | Admission facts. The diagnostic owner label `renderer.instances` names internal residency, not a public API. |
+| `error` | Structured record failure with `code`, `expected`, `hint` and `detail`. |
+
+After `device-lost`, call `await renderer.recover()` and retry the same draw.
+Recovery prepares new device resources from the retained CPU projection, without
+rescanning World or reusing old GPU handles. Failed candidates release their
+instance buffers. Writes made while the device is lost remain World-owned and
+are observed on the next draw. Disposing the Renderer never deletes author data.
 
 The large-instance smoke exercises the real Dawn path for all admitted sizes:
 
@@ -1189,7 +2331,7 @@ transport through the same production fixture and parameterizes the same three
 populations:
 
 ```bash
-pnpm exec vitest run --config vitest.browser.config.ts --project=browser \
+pnpm exec vitest run --config config/vitest.browser.config.ts --project=browser \
   apps/parity/instancing-static/src/__tests__/instances.browser.test.ts
 ```
 
@@ -1350,7 +2492,9 @@ same forward-only policy. This section is about the Standard lane, not the
 separate Points/Lines admission rule above. See the
 [`shader Surface contract`](../shader/README.md#standard-surface-contract) and
 the [`game-3d` import example](../../templates/game-3d/README.md#import-first-surface-material-example)
-for the source and Pack route.
+for the source and Pack route. Water and other participating media use the
+separate [Single-layer medium Surface](#single-layer-medium-surface) ABI and
+runtime route.
 
 The compiler and renderer share one pure `StandardLayerPlan`:
 `deriveStandardLayerPlan(effectiveParameters)`. It is the only derivation used
@@ -1412,8 +2556,8 @@ separate cache/recovery authority.
 > 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, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
-import { createRenderer } from '@forgeax/engine-runtime';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine/render';
+import { createRenderer } from '@forgeax/engine/runtime';
 
 const renderer = await createRenderer(canvas);
 const attached = renderer.attach(world);
@@ -1435,23 +2579,31 @@ state published by `World.update()`.
 ## Persistent render scene
 
 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
+then consumes each World's current membership and component block revisions. 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
+and metadata rows before uploading them. Shared material rows are packed once per
+GPU synchronization; Primitive, DrawTemplate, and Material rows upload only when
+their packed bytes change. Failed uploads retain their dirty rows for retry. 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, 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.
+Shared runtime material parameters and mesh buffers are authored through
+`RuntimeMaterialValue` and `RuntimeMeshVertices` from `assets-runtime`, using
+ordinary managed `world.set` writes. The shared handle remains identity-only.
+Renderer reverse dependencies wake all users of both the old and new handle
+when content is rebound or removed. Each Renderer independently accepts its
+source candidate; one consumer cannot drain another's updates. See the
+[content contract](../assets-runtime/README.md#runtime-content).
+
+Camera, light, and environment facts refresh independently of geometry.
+Initial attachment and updates use the same block candidate discovery and direct
+entity lookup. GPU dirty row addresses use fixed-width radix ordering before
+adjacent ranges are coalesced. A failed GPU upload retires that resident; source
+acceptance and submitted temporal history remain separate boundaries.
 
 Instance collection revisions refresh only their consumers. Visibility and
 parent changes refresh the affected subtree, and joint changes refresh the
@@ -1502,6 +2654,13 @@ 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.
 
+Frame preparation and device recovery share the material-artifact collector.
+It indexes ShadowCaster dispatch once by renderable index and material handle;
+the selected last matching dispatch owns both the program identity and its
+vertex/fragment entries. Per-draw lookup does not rescan the dispatch roster,
+and the index is rebuilt for each collection so replacement publications are
+observed without a persistent cache.
+
 ```ts
 import { Materials } from '@forgeax/engine/render';
 
@@ -1903,6 +3062,10 @@ consume the structured `error.detail` context.
 Use `renderer.inspect()` for a read-only snapshot. Call `renderer.dispose()`
 once or repeatedly; disposal is idempotent. Feature plans are assembled once
 and the Standard host owns graph replacement and last-known-good recovery.
+Repeated recoverable preparation errors are reported at most once per 60 frames.
+A changed stage exception name/message is reported immediately, retaining one
+report record per feature/error owner. Normal asynchronous resource warm-up
+remains silent.
 
 For a temporary presentation-owner handoff, call `renderer.releaseSurface()`.
 It unconfigures the canvas and makes `draw()` fail closed without disposing the
@@ -1927,10 +3090,10 @@ ownership is [`@forgeax/engine-render-graph`](../render-graph/README.md).
 Dynamic consumers use the same boundary explicitly:
 
 ```ts
-const { Camera, MeshFilter, MeshRenderer } = await import('@forgeax/engine-render');
+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.
+`@forgeax/engine/runtime` remains the host assembly entry for `createRenderer` and backend policy. Import `Materials` from `@forgeax/engine/render`. Runtime is not a compatibility barrel for render components.
 
 Optional text, tilemap, and sprite authoring is intentionally isolated from the
 base vocabulary:
@@ -1949,6 +3112,12 @@ consumer that composes sprites with an existing 3D game can call
 `TransparentSort.configure(world, { mode: TransparentSort.layerY, yzAlpha: 1 })`;
 it should not reach into `/internal`.
 
+Eligible sprite buckets share one fold instance buffer across the typed transparent
+geometry pass and the legacy sprite pass. Both consume the same head/skip plan;
+10,000 equal-depth sprites remain one instanced draw rather than 10,000 submissions.
+The sprite-atlas Dawn smoke checks this for 60 frames, and its browser probe
+checks the instance count, typed upload payload and WebGPU validation.
+
 The root barrel does not expose frame stores or extract/plan/record owners.
 Applications contribute work through `RenderFeature` plans; the Standard
 renderer owns graph compilation and submission.
@@ -2049,7 +3218,7 @@ 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
+`dawn://hello/ssr?forgeax-evidence=ssr`, records 60-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
@@ -2309,19 +3478,24 @@ existing observable state; resource disposal is distinct from JavaScript GC.
 
 ### 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.
+`VolumetricFog.density` is a producer-owned linear 3D source tile. In the default
+`noise` mode the integrator samples repeated world-space coordinates, combines the
+same three scales used by the approved fog fixture, and uses World time for the
+continuous advection term. The renderer keeps the source texture resident; it
+does not rebuild noise data for each frame. Its source expression is mapped to a
+signed density and clamped only at the optical-depth boundary so Beer-Lambert
+extinction remains non-negative.
+
+The local `density` mode samples normalized owner bounds directly. Each owner
+retains its own texture and optics; overlap sums coefficients before integration.
+Density integration partitions at owner entry/exit boundaries and uses 96
+fixed midpoint steps per interval, including the clipped final segment.
+Segments near a selected PointLight or SpotLight
+receive four local midpoints to resolve the inverse-square peak without making
+the whole ray uniformly expensive. Frame identity does not rotate density
+samples. Shadow visibility uses matching froxel centers without per-frame XY
+jitter or stochastic byte dithering; shared PCF shadow filtering remains in
+effect.
 
 ## Camera Depth of Field
 
@@ -2370,3 +3544,61 @@ orthographic camera stay on the normal camera snapshot path with structured
 The Engine Preview/game capability lab uses this same component on its ordinary
 mesh camera, and its settings control toggles component presence through the
 normal World path.
+
+## Standard camera barrel distortion
+
+`BarrelDistortion` is the bounded output-space camera companion. Its
+`strength` is finite in `[0, 0.35]`; `centerX` and `centerY` are finite fractions
+in `[0, 1]` with a top-left origin. The Standard stage samples linear-LDR color
+after LUT and before FXAA and the single output encoding. Positive strength uses
+the automatic crop rule, so the fixed-FOV camera sees a narrower region. Missing
+or zero strength preserves the exact zero-work path.
+
+If a DOM or `OffscreenCanvas` drawing buffer is temporarily zero-sized (for
+example while hidden or detached), `renderer.draw()` stops before configuring
+or submitting a zero-sized swapchain texture. The public result is a structured
+`device-operation-failed` whose nested cause is `rhi-not-available`; the last
+accepted `FrameReceipt` remains the LKG and a later positive-size draw resumes
+the same camera mapping without a GPU validation cascade.
+
+```ts
+import { BarrelDistortion } from '@forgeax/engine-render';
+
+world.addComponent(camera, {
+  component: BarrelDistortion,
+  data: { strength: 0.2, centerX: 0.5, centerY: 0.5 },
+});
+```
+
+Invalid authoring is a closed error-code path. Narrow on `error.code` and read
+the structured fields; do not parse `error.message`:
+
+```ts
+import { createBarrelDistortionMapping } from '@forgeax/engine-render';
+
+const mapping = createBarrelDistortionMapping(1920, 1080, { strength: 0.4 });
+if (!mapping.ok && mapping.error.code === 'barrel-distortion-invalid-parameter') {
+  const error = mapping.error;
+  const field = error.detail.field;
+  const value = error.detail.value;
+  const detailExpected = error.detail.expected;
+  const expected = error.expected;
+  const hint = error.hint;
+  console.error({ field, value, detailExpected, expected, hint });
+}
+```
+
+In the design language, `actual` and `bound` map to the public Barrel members
+`error.detail.value` and `error.detail.expected`. Barrel errors do not expose
+`error.detail.actual` or `error.detail.bound`; those member names remain owned by
+`shadow-invalid-config` only.
+
+`createBarrelDistortionMapping(outputWidth, outputHeight, data)` derives the
+immutable effective mapping. Reuse the mapping attached to the submitted
+`FrameReceipt` or the serialized worker frame signal. `mapDisplayToScene` and
+`mapSceneToDisplay` write continuous output-viewport physical pixels through
+out-parameters; inverse points cropped outside the display rectangle return
+`false`. The public `@forgeax/engine-picking` display entrypoints use this
+mapping once, while legacy picking continues to accept unwarped viewport
+coordinates. DOM/ShadowRoot HUD layout remains unchanged; world labels and
+vertex radius sorting must use the inverse mapping in display pixels.