@forgeax/engine-render 0.1.19 → 0.1.21

package/README.md

@@ -30,6 +30,62 @@ The current-source manifest and schema identify `source`, `build`, `backend`,
 readback or PNG evidence, and historical oracle data are separate evidence
 classes. An unavailable backend is reported as unavailable.
 
+### 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 {
   ANTIALIAS_TAA,
@@ -55,6 +111,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
 
@@ -84,6 +236,23 @@ PBR, IBL, SSAO, bloom, tone, antialiasing, sky, material, VFX, and debug feature
 the same graph and submit boundary. CPU and WebGL2 fallback are capability lanes of that pipeline,
 not second renderer identities.
 
+## 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.
+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
 
 Progressive disclosure is intentional: read Camera configuration first, then
@@ -255,6 +424,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 +530,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.