@forgeax/engine-render 0.1.20 → 0.1.23

package/README.md

@@ -8,6 +8,30 @@
 
 ## Public frame contract
 
+## 灯光最短入口
+
+三条最短入口：
+
+1. `RectAreaLight`：在现有 `Transform` 上声明单面矩形发光体，尺寸由 `width` 与 `height` 持有。
+2. `SpotLight`：用 `iesProfile` 和 `cookie` 绑定现有资产，用 `rollDeg` 共享方位角；缺席 handle 是乘法单位元。
+3. `LightProbe`：声明 27 个 `irradiance` 值和唯一的 `radius`，位置与朝向仍来自 `Transform`。
+
+这些是 authored/render 输入，不是 GPU slot、LTC、probe asset 或第二个 Renderer API。尺寸、半径和 `rollDeg` 在场景序列化中保留；资产 GUID 通过 Pack/Catalog 的 `refs` 往返，不能从 URL 或数组位置推断身份。
+
+### Extended-lighting consumer route
+
+The three smallest public examples are `RectAreaLight(width, height)`,
+`SpotLight(iesProfile, cookie, rollDeg)`, and `LightProbe(irradiance, radius)`.
+Probe diffuse uses `A={admitted && d<r}`, `c=1-(d/r)^2`, scaled finite `qhat`,
+`alpha=q/Q`, `C=1-prod(1-c)`, and `S=1-C`; Sky is only
+`S*E_sky(N)`. It never enters probe admission, `Q`, `alpha`, specular, or
+`DirectLightSlot`. `recordByteLength=160` is the per-object ABI receipt.
+
+Recovery is inspected as data: read `code`, `expected`, `hint`, and typed
+`detail`; keep the current LKG until the replacement generation is accepted.
+GPU, Browser, and Dawn evidence that cannot execute is `not-run` or
+`unavailable`, never a verified structural substitute.
+
 The public frame vocabulary is intentionally small. `Camera` is the authoring
 owner for tone, antialiasing, bloom, and `historyVersion`; `Atmosphere` and
 `Fog` are independent ECS components. The renderer extracts these facts into
@@ -25,10 +49,86 @@ typed `detail`, repair that owner, and submit the same request again. Public
 consumers do not parse `message` and 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.
+
+## RenderFeature: the producer seam (first-read index)
+
+### Material contract projection
+
+Render consumes only the Pack-owned material publication projection. Its
+inputs are runtime bool/value data, composed module slots, and the closed
+compiler context; render never authors, cooks, writes DDC, or selects a
+fallback material. The projection preserves `layoutIdentity`,
+`programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
+stale draw can be traced to the first producer divergence.
+
+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,
+then its mandatory `plan(data, context)` declares named resources and passes;
+the host derives graph access, preparation, recording, and recovery from that
+plan. Register it at construction with
+`createRenderer(canvas, { features: [feature] })`. A feature never receives a
+device, queue, encoder, staging builder, or submit callback.
+
+### Directional shadow quality: author → inspect → recover
+
+`DirectionalLight` is the only authoring entry for directional shadow quality.
+Set `shadowFilter` with the numeric constant for one of the five closed labels
+below; it is an ECS enum field, not a label string. Do not invent a numeric
+label or a compatibility alias. The default is `pcf3`. The two PCSS fields
+are read only when `shadowFilter` is `pcssMedium` or `pcssHigh`:
+
+```ts
+import { DirectionalLight, DirectionalShadowFilterValue } from '@forgeax/engine-render';
+
+world.spawn({ component: DirectionalLight, data: {
+  direction: [0.2, -0.98, 0],
+  shadowFilter: DirectionalShadowFilterValue.pcssHigh,
+  shadowAngularRadius: 0.00465,
+  maxPenumbraTexels: 32,
+} });
+```
+
+| Author field | Valid values / units | Default | Effective meaning |
+|:--|:--|:--|:--|
+| `shadowFilter` | `pcf1`, `pcf3`, `pcf5`, `pcssMedium`, `pcssHigh` | `pcf3` | Requested directional filter profile |
+| `shadowAngularRadius` | Radians, finite range `[0.0001, 0.05]` | `0.00465` | PCSS light angular radius |
+| `maxPenumbraTexels` | Texels, finite integer range `[1, 64]` | `32` | PCSS penumbra ceiling |
+
+The remaining CSM fields keep these public units and defaults: `cascadeCount`
+is an integer in `[1, 4]` (default `4`), `splitLambda` is `[0, 1]` (default
+`0.75`), `cascadeBlend` is `[0, 0.5]` (default `0.2`), `mapSize` is a positive
+map resolution (default `2048`), `depthBias` is a depth value (default
+`0.005`), `normalBias` is a world-space offset (default `0.05`), and
+`shadowDistance` is a positive world-unit distance in meters (default `200`).
+
+After `draw`, read the single `renderer.inspect().directionalShadow` projection.
+It is JSON-safe and bounded: `requested` is author intent, `effective` is the
+admitted profile, `status` is `accepted | fallback | rejected`, and
+`fallbackReason` explains `webgl2-unsupported`, `rhi-null-structural`, or
+`candidate-failed`. `lastKnownGood` identifies retained output and
+`pixelEvidence` distinguishes real pixel evidence from `not-available`.
+`cascadeCount`, `mapSize`, `atlasBytes`, `writerPasses`, `blockerTaps`,
+`filterTapUpperBound`, `seamTapUpperBound`, `deviceGeneration`, and
+`graphGeneration` are inspection facts, not additional author controls.
+
+If author validation returns `error.code === 'shadow-invalid-config'`, do not
+parse `error.message`. Read `error.expected`, `error.hint`,
+`error.detail.field`, `error.detail.actual`, `error.detail.bound`, and
+`error.detail.reason`; repair the named `DirectionalLight` field and retry the
+same request. For a rejected candidate, retain `lastKnownGood` from inspection,
+repair or rebuild the named producer, then call the existing `renderer.recover()`
+boundary and retry. WebGL2 reports its explicit PCF lane; RhiNull reports
+`rhi-null-structural` only, so neither is PCSS pixel evidence.
+Missing or `not-run` Browser/Dawn/PNG/timing evidence remains missing or
+`not-run`, never a pass. The authoritative labels and validation remain in
+[`directional-light.ts`](src/components/directional-light.ts) and
+[`light-helpers.ts`](src/components/light-helpers.ts); this section is an AI
+index path, not a second schema.
 
 ```ts
 import {
@@ -55,6 +155,102 @@ environment owners or multiple fog owners return structured errors with a
 code-specific `detail`; they do not create a second registry or silently pick
 the first entity. Frame facts contain IDs, revisions, and POD values only, not
 textures, buffers, devices, or other live GPU objects.
+## GPU pass timing: opt in, draw, observe, branch on status
+
+GPU pass timing is disabled by default. Opt in once on `createRenderer`, keep the
+returned `FrameReceipt`, and request facts only for that receipt. The pass
+duration is a bounded GPU fact; it is not frame latency.
+
+```ts
+import { createRenderer } from '@forgeax/engine-runtime';
+
+const created = await createRenderer(canvas, { gpuPassTiming: {} });
+if (!created.ok) throw created.error;
+const renderer = created.value;
+const attached = renderer.attach(world);
+if (!attached.ok) throw attached.error;
+const drawn = renderer.draw({
+  leases: [attached.value],
+  camera: { lease: attached.value },
+  environment: { lease: attached.value },
+});
+if (!drawn.ok) throw drawn.error;
+
+const observed = await renderer.observe(drawn.value, { include: ['timings'] });
+if (!observed.ok) throw observed.error;
+const timings = observed.value.timings;
+if (timings === undefined) throw new Error('timings were not requested');
+switch (timings.status) {
+  case 'complete':
+    console.log(timings.frame.passes);
+    break;
+  case 'partial':
+    console.log(timings.reason.code, timings.frame.passes);
+    break;
+  case 'unavailable':
+    console.log(timings.reason.code, timings.capability);
+    break;
+  case 'failed':
+    console.log(timings.error.code, timings.latestKnownGood);
+    break;
+}
+```
+
+The [bounded fact contract](src/record/gpu-pass-timing/contract.ts),
+[recovery errors](src/record/gpu-pass-timing/errors.ts), and
+[validator](bench/gpu-pass-timing/validator.ts) are the source-linked
+references for the four status branches and the fail-closed benchmark verdict.
+A timing error exposes the closed `code` union plus `expected`, `hint`, and
+`detail`; follow the producer-owned recovery action in the error before
+observing a later receipt. `latestKnownGood` is a separate reference and never
+changes the current status or completeness. Omitting `timings` from `include`
+returns receipt metadata without materializing timing facts.
+
+Run the paired real-GPU benchmark with the Dawn host:
+
+```sh
+FORGEAX_GPU_PASS_TIMING_HOST_MODULE="$PWD/packages/render/bench/gpu-pass-timing/dawn-host.ts" \
+  pnpm gpu-pass-timing:bench -- --output=/tmp/forgeax-gpu-pass-timing.json
+```
+
+The command exits `0` only for a complete accepted report and exits `2` for a
+blocked report. When an observation is `partial`, branch on
+`timings.reason.code === 'timestamp-write-unavailable'`, retain the
+unmeasured pass and its structured `detail.cause`, then observe the next
+receipt after the producer-owned recovery action. Do not turn that pass into a
+zero-duration sample or accept the benchmark until all paired windows are
+complete.
+
+An accepted report retains `frameFacts`: one complete on-path frame fact per paired
+group, including the frame identity, raw decimal ticks, each measured pass duration,
+and `measuredPassNanoseconds`. If a real run is blocked by partial observations, the
+blocked JSON keeps the observed representative facts under `evidence.frameFacts` so
+the measured values remain inspectable without weakening the verdict. If complete
+windows fail the paired overhead gate, `evidence.windows` retains the raw samples and
+`evidence.pairedOverhead` retains each group p95, group overhead, and reported median.
+
+Measured entries expose `measurementSource`: raster and compute entries use
+`pass-boundary`; copy entries use `copy-boundary-envelope`, the interval between
+timing-only marker passes, and must not be read as exact copy duration.
+
+## Fog and point-shadow observations
+
+`Fog` is a one-per-World environment input. Extract validates its parameters
+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.
+
+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
+requests beyond that capacity while retaining them for inspection. After a
+successful frame, `renderer.inspect().pointShadow` reports `requested`,
+`admitted`, `shadowed`, `shadowAtlasOccupancy`, and `shadowAtlasCapacity`.
+The App `pointShadowPlugin()` consumes that renderer capability and provides
+structured preflight failures for missing-storage-buffer, invalid, or
+over-budget requests. A World with no `PointLightShadow` remains `inactive`;
+there is no pseudo-disabled shadow mode. Directional CSM remains a separate
+shadow owner; PointLightShadow is not a second directional-light path.
 
 ## Render happy path
 
@@ -79,10 +275,97 @@ if (!frame.ok) throw frame.error;
 const observation = await renderer.observe(frame.value, { include: ['timings'] });
 ```
 
-The Standard pipeline selects direct or clustered lighting from capabilities and keeps shadow,
-PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature ownership inside
-the same graph and submit boundary. CPU and WebGL2 fallback are capability lanes of that pipeline,
-not second renderer identities.
+The Standard pipeline uses one Cluster transport for every local light on storage-capable devices
+and keeps shadow, PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature
+ownership inside the same graph and submit boundary. CPU and WebGL2 remain capability lanes for the
+Cluster membership producer or for mesh/instance storage fallback; they do not reintroduce a
+PointLight/SpotLight buffer or a fixed four-light ABI.
+## SSR M0 admission: inspect owners, then decide
+
+> [!IMPORTANT]
+> SSR M0 is a consumer-only admission boundary. It reads detached producer,
+> r32float format, and temporal receipts with one four-field integration
+> identity. Any missing, stale, structural-only, or mismatched receipt stays
+> `fallback-only` and emits zero SSR work; this section does not describe SSR
+> capture, ray tracing, Hi-Z, temporal resolve, composition, or history.
+
+```mermaid
+flowchart LR
+  P["producer detached receipt"] --> A["admitSsrM0"]
+  F["format stage receipt"] --> A
+  T["temporal submit receipt"] --> A
+  A -->|"all identity and verdict checks pass"| E["admitted: parent M1 may unlock"]
+  A -->|"missing, stale, unavailable, or mismatched"| B["fallback-only: zero work"]
+```
+
+The inspection route is deliberately progressive:
+
+| Layer | Read first | Owner action on failure |
+|:--|:--|:--|
+| Status | `status`, `failure.code`, `failure.expected` | branch on the closed failure code |
+| Identity | `sourceHead`, `sourceTree`, `lockSha256`, `buildSha256` | rebuild the owner receipt for the current identity |
+| Generation | producer `generation`, format `deviceGeneration`, temporal `generation` | discard stale completion and reinspect |
+| Recovery | `failure.hint`, typed `detail.owner`, `detail.action` | use LKG/Skylight/neutral, recapture, rebuild, or retry through that owner |
+| Work | attachment/pass/binding/resource/history/temporal counters | require exact zero on every blocked path |
+
+```ts
+const admission = admitSsrM0({ requested, identity, reflectionFallback, format, temporal });
+if (admission.status === 'fallback-only') {
+  // Read admission.failure.code and route recovery to its owner.
+  console.log(admission.work); // every SSR counter is zero
+}
+```
+
+Use `inspect -> owner recovery -> matching submit -> reinspect` as the complete
+AI route. No returned field is a device, graph node, texture, buffer, encoder,
+or other live handle. A stable generation keeps `resetCount`, `rebuildCount`,
+and additional format probe work at zero; a changed generation must be
+reinspected before admission can be considered again.
+
+`inspect()` is a synchronous snapshot. The first snapshot after binding may show
+an absent format or temporal receipt while the owner probe and first submit are
+still in flight; it is not a `pending` verdict. Run the ordinary owner frame,
+await `FrameReceipt.completed`, then inspect again before routing recovery.
+
+There are two action projections. `admission.failure.detail.action` is the coarse
+M0 gate instruction (`retry` for demand/readiness and `rebuild` for a missing or
+mismatched receipt). `reflectionFallbackInspection.recoveryAction` is the
+producer's more specific source/recapture instruction. Neither is a second SSR
+API; use the existing owner operation shown here, then submit and inspect again:
+
+| Action field | Owner operation | Next observation |
+|:--|:--|:--|
+| `reflectionFallbackInspection.recoveryAction = use-LKG` | Keep the compatible probe row and draw the next frame | Read the committed row and matching temporal receipt |
+| `reflectionFallbackInspection.recoveryAction = use-Skylight` / `use-neutral` | Change the World-owned probe/`Skylight` source, then draw | Confirm selected source and committed generation |
+| `reflectionFallbackInspection.recoveryAction = recapture` / `rebuild` / `retry` | Draw again so the producer/RHI owner retries pending work | Await completion and inspect the owner receipt/failure |
+| `admission.failure.detail.action = retry` / `rebuild` | Retry the consumer frame, or rebuild the named owner receipt | Reinspect admission and all three receipt generations |
+| device-loss recovery | `await renderer.recover()` before the next draw | Confirm the replacement `deviceGeneration`, then re-probe |
+
+SSR never invokes these operations or mutates producer/device state; this table
+maps the typed action to the existing public World and Renderer seams.
+
+## Target and probe lifecycle index
+
+The public target route is one Renderer owner: create a typed `RenderTarget`, create a
+`RenderTargetTextureSource` for the material slot, request a readback ticket, draw once, await
+`FrameReceipt.completed`, then call `observe(receipt, ...)`. `CubeCamera` contributes six real
+face views to the existing frame graph; a candidate becomes active only after its completed
+receipt. `ReflectionProbe` adds bounded PMREM face/mip work, local box projection, and Skylight
+irradiance fallback through the same Standard material binding path.
+
+Use `inspect()` for bounded target/probe counts, pending work, and the last structured failure.
+`inspection.reflectionProbes.selection` identifies the selected probe by `worldId` and `entityKey`,
+or reports `{ kind: 'skylight' }` for the explicit fallback. `recover()` is meaningful only from `device-lost`; on a healthy renderer its structured
+`renderer-state-invalid` result is a guard. Device recovery invalidates old generations and
+rebuilds producer-owned physical resources, so old tickets and sources must not be reused.
+For the SSR dependency producer, `inspection.reflectionProbes.reflectionFallbackInspection`
+is the bounded recovery projection: its `receipt` is the committed source row selected for
+the current lighting selection, while `failureStage`, `failureCode`, `expected`, and
+`recoveryAction` describe the latest closed failure without exposing a texture, graph, or
+device handle. `reflectionFallbackReadback` is the separate completed attachment fact; it
+must match the committed row's frame and device generation before it is used as evidence.
+The exact public names and stable consumer IDs are machine-readable in
+`src/__tests__/render-target-public-schema.json`.
 
 ## Stable inspection and dark-gradient evidence
 
@@ -186,26 +469,6 @@ gate exercises the browser delivery path. Runtime inspection uses the public
 belongs in `packages/render/bench` and its dev-verify producer. Render does
 not expose a timing controller or a second membership-specific API.
 
-## RenderFeature: the producer seam (first-read index)
-
-### Material contract projection
-
-Render consumes only the Pack-owned material publication projection. Its
-inputs are runtime bool/value data, composed module slots, and the closed
-compiler context; render never authors, cooks, writes DDC, or selects a
-fallback material. The projection preserves `layoutIdentity`,
-`programIdentity`, `cookIdentity`, and `materialPublicationIdentity` so a
-stale draw can be traced to the first producer divergence.
-
-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,
-then its mandatory `plan(data, context)` declares named resources and passes;
-the host derives graph access, preparation, recording, and recovery from that
-plan. Register it at construction with
-`createRenderer(canvas, { features: [feature] })`. A feature never receives a
-device, queue, encoder, staging builder, or submit callback.
-
 ## Motion Blur temporal consumer
 
 The Standard camera may carry the presence-enabled `MotionBlur` component. Its
@@ -255,6 +518,31 @@ uses the neutral engine material.
 
 The render path is `MaterialAsset` -> extract snapshot -> prepare resources -> record the per-slot `coordinates` and values. The effective `parent` is already resolved before extract. If a material contract or reflection binding fails, preserve the structured error and repair the source contract or cooked module before drawing again; that is the recovery route. The render package owns consumption, not material import or cook policy.
 
+### Resident material observation
+
+`renderer.inspect().meshMaterialBindings[]` is the detached observation of the
+binding that the renderer actually consumed. Its `residency` projection records
+`ready`, `pending`, `failed`, or `last-known-good`, plus the resolved sampler
+handles, texture handles, mip counts, and the nearest structured preparation
+failure when one exists. The observation is recomputed from the asset/runtime
+owner during preparation; render does not keep a second readiness ledger,
+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.
+
+### Instances CPU bounds contract
+
+`Instances` remains author data containing only packed local transforms. The
+renderer derives a CPU union bound from each mesh AABB, entity world matrix,
+and every instance matrix. The union cache is scoped by World/entity and
+invalidated by mesh, entity-transform, instance-array, slot removal, and
+generation changes. Missing, malformed, or empty instance data is a
+conservative no-cull result; it never creates a synthetic identity instance.
+The GPU path keeps the mesh-local AABB and performs per-instance visibility,
+while the CPU path uses the derived union only to avoid dropping an entity
+whose origin is outside the view. Do not add `bounds` to the public
+`Instances` component or duplicate this renderer fact in Pack/asset state.
+
 ## Points and Lines authoring (M1)
 
 Points and Lines are first-class render components. Their geometry remains a
@@ -336,6 +624,27 @@ if (!result.ok) {
 }
 ```
 
+## Standard lighting contract
+
+`forgeax::standard` is the only built-in lighting identity. Every finite point
+and spot light enters the shared Cluster membership path; `DirectionalLight`
+remains global and does not consume local-light membership. `renderPath` only
+selects Forward or Deferred graph topology. The derivation chain is
+`LightFrame -> PreparedStandardLighting -> StandardClusterTransportPlan`, with
+`packages/render/src/pipeline/standard-lighting/layout.ts` as the storage-size
+and light-index budget SSOT.
+
+Transport capability is explicit: compute/storage or CPU/storage. Cluster has
+no uniform-backed downlevel ABI; when `storageBuffer` is absent, admission
+returns the structured `standard-cluster-transport-unavailable` result with
+`requested` and `admitted`. Never invent a four-light fallback. Read
+`expected`, `hint`, and `detail` before repairing the device capability or the
+producer input. Both lanes consume the same complete CPU canonical corpus;
+the compute lane materializes the GPU index list, while the CPU lane uploads
+that list. A Dawn readback that compares the GPU list with the canonical
+corpus is the proof of GPU membership; until that readback runs, evidence is
+`not-proven`, never a synthetic completion state.
+
 M1 intentionally refuses strip expansion, joins, caps, dashes, picking, and
 visible point/line draw preparation. Those are later implementation lanes, not
 implicit fallbacks in authoring code.
@@ -445,7 +754,7 @@ authority.
 
 Inspect the current path through `renderer.inspect()`. Its detached CPU snapshot exposes
 full rebuilds, no-change and delta frames, transform/material/instance updates,
-removals, the journal cursor, projection cardinality, and the last resync
+removals, the consumer-owned read version, projection cardinality, and the last resync
 reason. The nested `gpu` status is one of `inactive`, `unsupported`, `resident`,
 `rebuild-pending`, or `error`; resident state additionally reports capacity,
 upload ranges and bytes, grows, clears, rebuilds, and no-change frames. The
@@ -783,3 +1092,30 @@ const temporal = catalog.require('forgeax::scene-data::temporal-v1');
 available, `SceneDataUnavailableError` exposes the closed `reason`, missing
 producer IDs (at most 32 plus an omission count), and explicit `recovery`.
 Repair capability or producer coverage at its owner, then retry the next frame.
+
+## AI-readable SSR fallback route
+
+For the reflection fallback dependency evidence, call `renderer.inspect()` first
+and run the paired fixture. The fixture writes the current Browser/Dawn manifests;
+the collector then seals a fresh joint M0 guard for the current checkout:
+
+```bash
+pnpm --filter @forgeax/app-learn-render-6-pbr-4-render-target-reflection smoke:ssr-fallback
+pnpm --filter @forgeax/app-learn-render-6-pbr-4-render-target-reflection smoke:browser
+node scripts/forgeax/collect-ssr-dependency-report.mjs \
+  --input artifacts/ssr-fallback/dawn/ssr-dependencies-input.json \
+  --build-summary packages/render/dist/index.mjs \
+  --output artifacts/ssr-fallback/ssr-dependency-report.json
+```
+
+Each smoke writes its own detached `ssr-dependencies-input.json` beside the lane
+manifest; the command above uses the just-completed Dawn input (use the Browser
+path when inspecting that lane separately). The collector signs the output with
+the current source/tree/lock/build identity; it never promotes a stale
+sibling-loop report or an authored manifest. Read identity, generation, evidence
+level, and closed failure fields before following the named owner recovery action.
+Submit the same consumer request and reinspect after recovery. The route returns
+detached facts only: no live GPU handle, second owner, or second ledger is exposed.
+Missing or mismatched receipts remain
+`fallback-only` with zero SSR work; SSR v1, Hi-Z, ray marching, temporal resolve,
+compose, and history are out of scope.

package/dist/assembly/backend-contract.d.ts

@@ -2,6 +2,19 @@ import type { Result, RhiCanvasContext, RhiDevice, RhiError, RhiInstance, Shader
 /** Optional host hooks for recorder and device-lifecycle capabilities. */
 export interface RhiBackendInstrumentation {
     readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+    /**
+     * Optional deterministic submit fault seam for backend-owned integration
+     * fixtures. The callback runs after `finish()` and before the queue submit;
+     * returning an error aborts the frame transaction without changing the
+     * production queue contract.
+     */
+    readonly beforeSubmit?: (device: RhiDevice) => RhiError | undefined;
+    /**
+     * Optional device-loss projection for deterministic recovery fixtures. A
+     * backend may compose this promise with its native `device.lost` promise;
+     * normal production packs leave it undefined and use the native signal.
+     */
+    readonly deviceLost?: (device: RhiDevice) => RhiDevice['lost'];
     readonly onFrameBoundary?: () => void;
     readonly onDeviceLost?: () => void;
 }

package/dist/assembly/backend-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend-contract.d.ts","sourceRoot":"","sources":["../../src/assembly/backend-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,MAAM,EAAE,iBAAiB,GAAG,eAAe,KACxC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CACrC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAC3D,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;KAC1B,CAAC;IACF,gBAAgB;IAChB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,SAAS,CAAC;IAC7E,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,yBAAyB,CAAC;CACtD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD;AAiCD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,4BAAiC;CAWtE"}
+{"version":3,"file":"backend-contract.d.ts","sourceRoot":"","sources":["../../src/assembly/backend-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnF;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,QAAQ,GAAG,SAAS,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,MAAM,EAAE,iBAAiB,GAAG,eAAe,KACxC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CACrC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAC/C,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAC3D,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;KAC1B,CAAC;IACF,gBAAgB;IAChB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,SAAS,CAAC;IAC7E,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,yBAAyB,CAAC;CACtD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD;AAiCD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,4BAAiC;CAWtE"}

package/dist/assembly/device-feature-admission.d.ts

@@ -0,0 +1,18 @@
+import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
+export declare const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export interface DeviceFeatureAdmissionOptions {
+    readonly gpuPassTiming?: object | undefined;
+    readonly captureGpuTimings?: boolean | undefined;
+}
+export interface DeviceFeatureAdmission {
+    readonly requiredFeatures: GPUFeatureName[];
+    readonly requiredLimits?: {
+        readonly maxSampledTexturesPerShaderStage: number;
+    };
+}
+type AdapterFeatureProbe = Pick<RhiAdapter, 'features'> & Partial<Pick<RhiAdapter, 'limits'>>;
+export declare function deriveDeviceFeatureAdmission(adapter: AdapterFeatureProbe, options?: DeviceFeatureAdmissionOptions): DeviceFeatureAdmission;
+export declare function deviceOptionsForAdapter(adapter: AdapterFeatureProbe, options?: DeviceFeatureAdmissionOptions): DeviceFeatureAdmission | undefined;
+export declare function isTimestampQueryAdmitted(caps: Pick<RhiDevice['caps'], 'timestampQuery' | 'timestampPeriodNanoseconds'>): boolean;
+export {};
+//# sourceMappingURL=device-feature-admission.d.ts.map

package/dist/assembly/device-feature-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-feature-admission.d.ts","sourceRoot":"","sources":["../../src/assembly/device-feature-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAejE,eAAO,MAAM,sCAAsC,KAAK,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,gBAAgB,EAAE,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,gCAAgC,EAAE,MAAM,CAAC;KACnD,CAAC;CACH;AAED,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9F,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,CAwBxB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,6BAA6B,GACtC,sBAAsB,GAAG,SAAS,CAKpC;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,4BAA4B,CAAC,GAC7E,OAAO,CAOT"}

package/dist/assembly/directional-shadow-inspection.d.ts

@@ -0,0 +1,38 @@
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
+import type { DirectionalShadowInspection, DirectionalShadowInspectionError, DirectionalShadowProfile } from '../inspection-types';
+import type { DirectionalShadowBackendAdmission } from '../render-pipeline';
+export interface DirectionalShadowInspectionSource {
+    readonly requested: DirectionalShadowProfile;
+    readonly candidate: 'accepted' | 'failed';
+    readonly lastKnownGood?: DirectionalShadowProfile | undefined;
+    readonly cascadeCount: number;
+    readonly mapSize: number;
+    readonly atlasBytes: number;
+    readonly writerPasses: number;
+    readonly shadowAngularRadius?: number | undefined;
+    readonly maxPenumbraTexels?: number | undefined;
+    readonly deviceGeneration: number;
+    readonly graphGeneration: number;
+    readonly shadowReady: boolean;
+    readonly error?: DirectionalShadowInspectionError | undefined;
+}
+export interface DirectionalShadowInspectionInput {
+    readonly admission: DirectionalShadowBackendAdmission;
+    readonly cascadeCount: number;
+    readonly mapSize: number;
+    readonly atlasBytes: number;
+    readonly writerPasses: number;
+    readonly blockerTaps: number;
+    readonly filterTapUpperBound: number;
+    readonly seamTapUpperBound: number;
+    readonly shadowAngularRadius?: number | undefined;
+    readonly maxPenumbraTexels?: number | undefined;
+    readonly deviceGeneration: number;
+    readonly graphGeneration: number;
+    readonly error?: DirectionalShadowInspectionError | undefined;
+}
+/** Project the single bounded Directional inspection POD; no live handles leak. */
+export declare function projectDirectionalShadowInspection(input: DirectionalShadowInspectionInput): DirectionalShadowInspection;
+export declare function directionalShadowProfileFromQuality(quality: DirectionalShadowQuality | undefined): DirectionalShadowProfile;
+export declare function projectDirectionalShadowInspectionSource(input: DirectionalShadowInspectionSource): DirectionalShadowInspection;
+//# sourceMappingURL=directional-shadow-inspection.d.ts.map

package/dist/assembly/directional-shadow-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directional-shadow-inspection.d.ts","sourceRoot":"","sources":["../../src/assembly/directional-shadow-inspection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACxF,OAAO,KAAK,EACV,2BAA2B,EAC3B,gCAAgC,EAChC,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAE5E,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,gCAAgC,GAAG,SAAS,CAAC;CAC/D;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,SAAS,EAAE,iCAAiC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,gCAAgC,GAAG,SAAS,CAAC;CAC/D;AAWD,mFAAmF;AACnF,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,gCAAgC,GACtC,2BAA2B,CAwB7B;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,wBAAwB,CAI1B;AAED,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,iCAAiC,GACvC,2BAA2B,CAiC7B"}