@forgeax/engine-render 0.1.31 → 0.1.33

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,16 @@
 
 ## Public frame contract
 
+`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`.
+
 ## 灯光最短入口
 
 三条最短入口：
@@ -101,6 +117,14 @@ plan. Register it at construction with
 `createRenderer(canvas, { features: [feature] })`. A feature never receives a
 device, queue, encoder, staging builder, or submit callback.
 
+After a frame reaches queue submission, the optional `onFrameSubmitted` callback
+receives a bounded `RenderFeatureSubmission` projection. Its `passes` contain
+only work admitted after prepared-resource resolution, so producer diagnostics
+can distinguish submitted compute dispatches and graphics draws from a plan
+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.
+
 ## RenderFeature: the producer seam (first-read index)
 
 The public route is one `RenderFeature<FrameData>` through the active RenderGraph
@@ -157,6 +181,13 @@ surface receiver position along its world-space normal before projection (defaul
 Normal offset and depth bias are independent: increasing the CSM depth span must
 not magnify the world-space normal offset. Both PCF and PCSS project the offset
 receiver; volumetric samples have no surface normal and use only depth bias.
+Surface receivers also get a per-cascade depth correction derived from the
+world size of a shadow texel, the filter footprint, and the receiver's depth
+slope along the light's two image axes. The existing normal offset counts
+toward this coverage; only the missing amount is added to `depthBias`, after
+conversion through that cascade's light-space depth span. PCSS derives its
+blocker-search and comparison coverage separately from their actual radii.
+This does not change either author field's units or add shadow texture taps.
 Cascade projections include their incoming blend band, and PCSS depth spans
 match the actual projection, including toward-light caster reach. The normal
 position offset follows the approach in
@@ -192,6 +223,8 @@ index path, not a second schema.
 import {
   ANTIALIAS_TAA,
   Atmosphere,
+  BLOOM_DISABLED,
+  CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   Fog,
   type FramePlan,
@@ -214,6 +247,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
@@ -225,6 +269,42 @@ 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.
 
+### 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
@@ -259,6 +339,8 @@ 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({
@@ -332,6 +414,168 @@ 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 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;
+  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. This route covers authored density and time projection only; it does
+not add a procedural cloud API or a Voxel integration.
+
 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
@@ -368,6 +612,8 @@ 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({
@@ -896,20 +1142,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.
@@ -947,7 +1304,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],
@@ -1089,10 +1446,14 @@ renderer.instances.update(collection.collectionId, {
   transforms: patch,
 });
 
-// Replacement keeps the logical identity and publishes a new revision.
+// 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);
 ```
 
@@ -1101,7 +1462,9 @@ storage, `replace` publishes a complete new revision (and grows capacity when
 needed), `update` validates a bounded matrix interval and records its dirty
 range, `inspect` returns identity/count/capacity/revision, `snapshot` returns a
 detached matrix copy plus dirty ranges for extraction, and `release` makes the
-collection id terminal. A caller never provides a GPU buffer or maintains
+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.
 
@@ -1393,8 +1756,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);
@@ -1908,10 +2271,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:
@@ -2290,16 +2653,66 @@ 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. The volume
+integrator samples that tile in 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
+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
+
+`DepthOfField` is the built-in Standard camera effect for ordinary meshes. Add it
+only to the active perspective camera; component removal or
+`maxRadiusPixels: 0` declares the exact zero-work path. The side and quality
+fields use the closed numeric values exported by this package:
+
+```ts
+import {
+  DepthOfField,
+  DepthOfFieldQualityValue,
+  DepthOfFieldSideValue,
+} from '@forgeax/engine-render';
+
+world.addComponent(camera, {
+  component: DepthOfField,
+  data: {
+    focusDistance: 8,
+    fStop: 1.4,
+    sensorHeight: 0.024,
+    maxRadiusPixels: 16,
+    quality: DepthOfFieldQualityValue.medium,
+    blurSide: DepthOfFieldSideValue.both,
+  },
+});
+```
+
+The near, far and both presets share one signed thin-lens CoC. `quality` changes
+sampling density only, so it does not change the optical radius. The graph uses
+the Standard `RenderExtent`: full-resolution CoC/composite targets follow the
+current internal or output domain, and half-resolution targets use
+`max(1, ceil(axis / 2))`. Current temporal-v1 depth validity and the resolved
+multisampled depth binding remain the source of truth.
+
+After a real `draw()` submission, read `renderer.inspect().depthOfField` for the
+requested component values, effective submitted values, graph/device
+generations, extents, pass count and descriptor-derived bytes. `lastKnownGood`
+and `effective` stay bound to the accepted submission; a failed candidate keeps
+the prior accepted projection and reports its failure reason for recovery.
+When the active camera has no `DepthOfField` component, the inspection remains
+available with `status: 'off'` and zero DoF graph facts. Invalid fields and an
+orthographic camera stay on the normal camera snapshot path with structured
+`error.code`, `error.expected`, `error.hint`, and `error.detail`; they report
+`status: 'invalid'` or `status: 'unsupported'` without admitting a DoF graph.
+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.

package/dist/assembly/analytic-fog-registration.d.ts

@@ -0,0 +1,3 @@
+import type { RenderSystem } from '../render-system';
+export declare function registerAnalyticFogPostProcess(renderSystem: Pick<RenderSystem, 'registerBuiltinPostProcess'>, source: string, candidate: boolean): void;
+//# sourceMappingURL=analytic-fog-registration.d.ts.map

package/dist/assembly/analytic-fog-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytic-fog-registration.d.ts","sourceRoot":"","sources":["../../src/assembly/analytic-fog-registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,4BAA4B,CAAC,EAC9D,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,GACjB,IAAI,CAON"}

package/dist/assembly/fxaa-registration.d.ts

@@ -0,0 +1,4 @@
+import type { RenderSystem } from '../render-system';
+/** Register the built-in FXAA post-process once for the active generation. */
+export declare function registerFxaaPostProcess(renderSystem: Pick<RenderSystem, 'registerBuiltinPostProcess'>, source: string, registered: boolean): boolean;
+//# sourceMappingURL=fxaa-registration.d.ts.map

package/dist/assembly/fxaa-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fxaa-registration.d.ts","sourceRoot":"","sources":["../../src/assembly/fxaa-registration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,4BAA4B,CAAC,EAC9D,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,OAAO,GAClB,OAAO,CAQT"}

package/dist/assembly/lod-observation.d.ts

@@ -0,0 +1,4 @@
+import type { FrameReceipt } from '../render-contract';
+import type { RenderSystem } from '../render-system';
+export declare function observeLodOcclusionForReceipt(renderSystem: Pick<RenderSystem, 'observeLodOcclusion'>, receipt: Pick<FrameReceipt, 'frameId' | 'deviceGeneration'>): Promise<void>;
+//# sourceMappingURL=lod-observation.d.ts.map

package/dist/assembly/lod-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lod-observation.d.ts","sourceRoot":"","sources":["../../src/assembly/lod-observation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,qBAAqB,CAAC,EACvD,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,kBAAkB,CAAC,GAC1D,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/assembly/motion-blur-registration.d.ts

@@ -0,0 +1,3 @@
+import type { RenderSystem } from '../render-system';
+export declare function registerMotionBlurPostProcess(renderSystem: Pick<RenderSystem, 'registerBuiltinPostProcess'>, source: string): void;
+//# sourceMappingURL=motion-blur-registration.d.ts.map

package/dist/assembly/motion-blur-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-blur-registration.d.ts","sourceRoot":"","sources":["../../src/assembly/motion-blur-registration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,4BAA4B,CAAC,EAC9D,MAAM,EAAE,MAAM,GACb,IAAI,CASN"}

package/dist/assembly/renderer-facade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer-facade.d.ts","sourceRoot":"","sources":["../../src/assembly/renderer-facade.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,sBAAsB,EAE5B,MAAM,kBAAkB,CAAC;AAM1B,OAAO,KAAK,EAEV,QAAQ,EAKR,aAAa,EAEd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGlE,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,0BAA0B,GAAG,QAAQ,CA6M7E;AAMD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7C;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,sBAAsB,CA0BjG;AA2DD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CA6ChF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAMzE"}
+{"version":3,"file":"renderer-facade.d.ts","sourceRoot":"","sources":["../../src/assembly/renderer-facade.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,sBAAsB,EAE5B,MAAM,kBAAkB,CAAC;AAO1B,OAAO,KAAK,EAEV,QAAQ,EAKR,aAAa,EAEd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGlE,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,0BAA0B,GAAG,QAAQ,CA8M7E;AAMD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7C;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,sBAAsB,CA0BjG;AA2DD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CA6ChF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAMzE"}

package/dist/assembly/temporal-post-process-prewarm.d.ts

@@ -0,0 +1,13 @@
+import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+export type AsyncShaderModuleFactory = ((device: RhiDevice, desc: {
+    readonly code: string;
+    readonly label?: string;
+}) => Promise<Result<ShaderModule, RhiError>>) | undefined;
+/** Create the shared readiness prewarmer for temporal/fullscreen shader entries. */
+export declare function createTemporalShaderPrewarmer(input: {
+    readonly device: RhiDevice;
+    readonly asyncCreateShaderModule: AsyncShaderModuleFactory;
+    readonly seedShaderModule: (label: string, module: ShaderModule) => void;
+}): (entry: ManifestEntry | undefined, id: string) => Promise<void>;
+//# sourceMappingURL=temporal-post-process-prewarm.d.ts.map