@forgeax/engine-runtime 0.1.20 → 0.1.21

package/README.md

@@ -45,6 +45,58 @@ stale receipt is a structured failure rather than an implicit read of the
 current frame. Repair the owner named by `error.detail`, then retry the same
 request.
 
+## Directional shadow authoring and recovery index
+
+The cold-AI entry is `DirectionalLight.shadowFilter`, followed by one read of
+`renderer.inspect().directionalShadow` read. The closed labels are
+`pcf1`, `pcf3`, `pcf5`, `pcssMedium`, and `pcssHigh`; the default is `pcf3`.
+`shadowAngularRadius` is measured in radians, defaults to `0.00465`, and must
+be in `[0.0001, 0.05]`. `maxPenumbraTexels` is a finite integer measured in
+texels, defaults to `32`, and must be in `[1, 64]`. These are Directional
+author facts; Point/Spot `pcfKernelSize` remains a separate contract.
+
+The detached `directionalShadow` projection explains the next action without
+reading renderer private state:
+
+| Inspection field | AI interpretation |
+|:--|:--|
+| `requested` / `effective` | Author request and admitted profile |
+| `status` | `accepted`, explicit `fallback`, or `rejected` |
+| `fallbackReason` | `webgl2-unsupported`, `rhi-null-structural`, or `candidate-failed` |
+| `lastKnownGood` | Whether the previous admitted profile was retained |
+| `pixelEvidence` | `available` or `not-available`; structural evidence is not pixel proof |
+| `deviceGeneration` / `graphGeneration` | 当前 inspection result 的 generation identity |
+| `cascadeCount`, `mapSize`, `atlasBytes`, `writerPasses`, `blockerTaps`, `filterTapUpperBound`, `seamTapUpperBound` | Bounded CSM and tap-budget facts |
+
+For `error.code === 'shadow-invalid-config'`, use the structured properties
+`error.expected`, `error.hint`, and `error.detail.field`, `actual`, `bound`, and
+`reason`. Set the named field to the bound described by `detail`, then retry;
+the prose `error.message` is not an API. For a failed capable candidate, keep
+the `lastKnownGood` projection, repair or rebuild its producer, call
+`renderer.recover()`, and retry the identical draw. WebGL2 may expose only its
+explicit PCF fallback, while RhiNull is structural (`pixelEvidence:
+not-available`); neither state may be rewritten as PCSS support. A
+`not-run` Browser/Dawn/PNG/timing receipt stays `not-run`.
+
+The complete author → inspect → recover path is:
+
+```ts
+const renderer = (await createRenderer(canvas)).unwrap();
+// Spawn DirectionalLight with a legal shadowFilter and PCSS units first.
+const frame = renderer.draw(request);
+if (!frame.ok) {
+  // Read frame.error.code, .expected, .hint, and typed .detail.
+  throw frame.error;
+}
+const shadow = renderer.inspect().directionalShadow;
+// Repair the named owner, renderer.recover(), then retry request when needed.
+void shadow;
+```
+
+The labels, units, defaults, structured error shape, and fallback vocabulary
+are shared with [`@forgeax/engine-render`](../render/README.md); runtime owns
+host assembly and recovery invocation, not a second Directional schema.
+
 ## Render happy path
 
 `createRenderer -> attach -> draw -> inspect/observe/recover` assembles one
@@ -56,6 +108,41 @@ named by `error.detail`, rebuild or cold-cook its source, and retry.
 > [!IMPORTANT]
 > Runtime is the sole public host-assembly entry for `createRenderer`. It selects browser/backend services, invokes render's internal construction seam, and cleans up partial construction. It does not own scene, skinning, animation, or render-domain APIs.
 
+## Standard profile recovery
+
+The host exposes one `forgeax::standard` profile. `lightCount` is one of
+`1 | 32 | 256`, `renderPath` is `forward | deferred`, and local finite lights
+are always prepared for the shared Cluster transport. Invalid profile input
+returns `standard-profile-invalid` with `expected`, `hint`, and `detail`; the
+failed transaction keeps the last-known-good profile and device generation.
+
+## Point-shadow creation recipe
+
+Point shadows stay discoverable through the App recipe while the renderer
+remains the sole owner of atlas admission and frame facts. Install
+`pointShadowPlugin()` beside the existing renderer provider, then preflight a
+caster count and read the detached inspection after a successful frame:
+
+```ts
+import { pointShadowPlugin } from '@forgeax/engine-app';
+
+// Include this in the same App/Worker plugin list as rendererPlugin(renderer).
+const pointShadow = app.pluginContext.pointShadow;
+const result = pointShadow?.admit(1);
+if (result !== undefined && !result.ok) throw result.error;
+const facts = pointShadow?.inspect();
+void facts?.shadowed;
+```
+
+`admit()` returns a structured `PointShadowRecipeError` for missing
+`storageBuffer`, an invalid request, or a count above the renderer's shared
+`ShadowAtlas` capacity. A World without `PointLightShadow` is the real inactive
+case; there is no pseudo-disabled mode. `inspect()` reports `requested`,
+`admitted`, `shadowed`, occupancy, and capacity from the last submitted frame;
+it is not a second shadow registry. Directional CSM remains the renderer's
+separate global path, and Runtime does not create another provider or submit
+path.
+
 ## Assemble producer features
 
 The host receives a heterogeneous list of producer-owned
@@ -155,6 +242,21 @@ its structured construction error. After construction, `attach`, `draw`,
 `inspect`, `observe`, and `recover` remain receipt-bound and `dispose()` is
 idempotent.
 
+## GPU pass timing forwarding
+
+`CreateRendererOptions.gpuPassTiming` is forwarded unchanged through the
+existing renderer-options projection. Runtime does not request timestamp
+features, create a timing session, retain RHI handles, inspect a pass catalog,
+or change `ProfileCapture`. Use the Render-owned public route: opt in, keep the
+`draw()` `FrameReceipt`, call `observe(receipt, { include: ['timings'] })`, and
+branch on the four statuses and structured `code`/`hint`. The accepted bounded
+contract and recovery path are documented in
+[`packages/render/README.md`](../render/README.md).
+
+Membership timing is a separate producer-specific capability. Its records are
+not generic accepted GPU pass evidence and must not become a second runtime
+owner or controller.
+
 ### Browser backend selection and diagnosis
 
 The default browser path prefers native WebGPU and can retry through the