@forgeax/engine-render 0.1.33 → 0.1.34

package/README.md

@@ -14,6 +14,32 @@
 
 ## 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
@@ -24,6 +50,41 @@ matching depth resolve is available. Translucent surfaces that do not write dept
 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.
+
 ## 灯光最短入口
 
 三条最短入口：
@@ -73,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`,
@@ -92,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)
 
@@ -108,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,
@@ -125,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
@@ -269,6 +954,16 @@ 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
@@ -339,8 +1034,6 @@ import { createRenderer } from '@forgeax/engine-runtime';
 const created = await createRenderer(canvas, { gpuPassTiming: {} });
 if (!created.ok) throw created.error;
 const renderer = created.value;
-const ready = await renderer.initialization;
-if (!ready.ok) throw ready.error;
 const attached = renderer.attach(world);
 if (!attached.ok) throw attached.error;
 const drawn = renderer.draw({
@@ -536,8 +1229,6 @@ 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 ready = await renderer.initialization;
-  if (!ready.ok) throw ready.error;
   const attached = renderer.attach(world);
   if (!attached.ok) throw attached.error;
   const lease = attached.value;
@@ -573,8 +1264,157 @@ browser check; homogeneous transmittance alone cannot detect light-band artifact
 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. This route covers authored density and time projection only; it does
-not add a procedural cloud API or a Voxel integration.
+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
@@ -612,8 +1452,6 @@ rebuild or cold-cook its source, then retry the same request.
 const created = await createRenderer(canvas);
 if (!created.ok) throw created.error;
 const renderer = created.value;
-const ready = await renderer.initialization;
-if (!ready.ok) throw ready.error;
 const attached = renderer.attach(world);
 if (!attached.ok) throw attached.error;
 const frame = renderer.draw({
@@ -727,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
@@ -980,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
@@ -1407,115 +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 publishes a new revision. Pass prior generation tokens in their
-// new order when compaction/reorder preserves logical instance identity;
-// omitted tokens intentionally seed replacement rows.
-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:
 
@@ -1533,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
 ```
 
@@ -1694,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
@@ -1779,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
@@ -1846,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';
 
@@ -2247,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
@@ -2293,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.
@@ -2393,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
@@ -2653,16 +3478,19 @@ existing observable state; resource disposal is distinct from JavaScript GC.
 
 ### Volumetric density coordinates
 
-`VolumetricFog.density` is a producer-owned linear 3D source tile. The volume
-integrator samples that tile in repeated world-space coordinates, combines the
+`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.
 
-Density integration uses fixed midpoints over 96 base ray intervals, including
-the clipped final segment. Segments near a selected PointLight or SpotLight
+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
@@ -2716,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.