@forgeax/engine-runtime 0.1.27 → 0.1.29

package/README.md

@@ -12,6 +12,14 @@ returned `FrameReceipt`:
 const result = await createRenderer(canvas);
 if (!result.ok) throw result.error;
 const renderer = result.value;
+const ready = await renderer.initialization;
+if (!ready.ok) {
+  // Inspect ready.error.code / .expected / .hint and its typed detail before
+  // repairing the named producer or backend. Initialization failures are not
+  // draw-time retries; dispose and recreate after the repair.
+  renderer.dispose();
+  throw ready.error;
+}
 const lease = renderer.attach(world);
 if (!lease.ok) throw lease.error;
 const frame = renderer.draw({
@@ -22,10 +30,20 @@ const frame = renderer.draw({
 if (!frame.ok) throw frame.error;
 const facts = renderer.inspect();
 const observation = await renderer.observe(frame.value, { include: ['timings'] });
+const output = facts.output;
+// output.autoExposure / output.standardLut are receipt-bound detached facts.
+// Read output.error before choosing a retry or producer recovery path.
 void facts;
+void output;
 void observation;
 ```
 
+`Renderer.inspect().output` is the single public subtree for the Standard
+output transform: it contains display encoding, surface formats, the auto
+exposure receipt, the ordinary shared-texture 3D LUT receipt, and structured
+availability errors. Camera exposure and color grading remain authored on the
+Camera; runtime only assembles the renderer and forwards the detached facts.
+
 ## Progressive recovery index
 
 Start with the public recovery route: `state() -> inspect() -> recover() ->
@@ -44,6 +62,14 @@ uninitialized until a successful new-generation receipt; fallback output is
 not Browser/Dawn proof. Structural inspection, real Browser/Dawn readback,
 and PNG evidence remain separate evidence classes.
 
+Before the first `attach` or `draw`, always await `renderer.initialization` and
+branch on its `Result`. A failed initialization exposes a structured
+`webgpu-runtime-error`; for pipeline failures inspect
+`error.detail.error.detail.cause` to reach the backend `RhiError`, repair that
+producer or capability, dispose the failed renderer, and call `createRenderer`
+again. `renderer.recover()` is for an admitted renderer whose later resource or
+device state needs recovery; it does not replace the initialization barrier.
+
 Carrier manifests and schemas expose current source/build provenance, backend,
 runner, and frame identity. Structural graph checks are distinct from real
 Browser/Dawn readback and PNG evidence; a historical oracle is reference data,
@@ -54,6 +80,24 @@ 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.
 
+## GPU-driven PBR / shadow / skin navigation
+
+Runtime is the host-side entry for the prepared Standard PBR frame. Follow the
+owner links when a frame is rejected:
+
+| Entry | Owner | Next action |
+|:--|:--|:--|
+| [`shader`](../shader/README.md#gpu-driven-pbr--shadow--skin-navigation) | WGSL, schema, reflection, cooked receipt | repair source or recook |
+| [`render`](../render/README.md#gpu-driven-pbr--shadow--skin-navigation) | scene index, topology, shadow views, indirect record | inspect lane and retry |
+| [`hello-skin`](../../apps/hello/skin/README.md#gpu-driven-skin-carrier) / [`hello-fbx-skin`](../../apps/hello/fbx-skin/README.md#gpu-driven-fbx-carrier) | imported skin carrier and smoke | rerun the declared smoke |
+
+The offline exercise is deterministic: read `renderer.inspect().renderScene.gpuDriven`,
+branch on the closed `lane`/`reason`, and for a blocked channel use
+`failure.detail.owner` plus `failure.detail.recovery` to repair the named
+producer before retrying the unchanged frame request. `failure.hint` is
+human-readable only. `blocked/resource-not-ready` means promotion stopped; it
+is not permission to route the same candidate through CPU semantics.
+
 ## Directional shadow authoring and recovery index
 
 The cold-AI entry is `DirectionalLight.shadowFilter`, followed by one read of
@@ -106,6 +150,27 @@ 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.
 
+## Spot shadow inspection route
+
+Author `SpotLight` beside its `Transform`, then use the renderer-owned channel
+projection after `draw`; Runtime does not create a second light or shadow
+registry. The render package has the complete authoring table and source
+anchors in [Point and Spot shadow authoring → view inspection](../render/README.md#point-and-spot-shadow-authoring--view-inspection).
+
+```ts
+const channels = renderer.inspect().renderScene.gpuDriven.channels;
+const spot = channels.filter((channel) => channel.viewPass === 'spot-shadow');
+const point = channels.filter((channel) => channel.viewPass === 'point-shadow');
+void spot; // viewIndex, lane, reason, and drawCount are bounded facts.
+void point; // point views additionally expose face for cube-array inspection.
+```
+
+If a channel is `blocked`, follow its structured `failure.detail.owner` and
+`failure.detail.recovery`; do not retry the candidate through CPU semantics or
+infer ownership from an array position. Static `TextureAsset` cookies and
+projectors follow the existing Catalog/resource route, while video and render
+target sources remain dynamic semantic inputs.
+
 ## Render happy path
 
 `createRenderer -> attach -> draw -> inspect/observe/recover` assembles one
@@ -117,6 +182,34 @@ 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.
 
+## Large instance lifecycle and recovery
+
+Large instance matrices stay behind the Render owner even when the renderer is
+assembled by Runtime. After `attach`, create one logical collection through
+`renderer.instances`, associate its returned `collectionId` with the Render
+`Instances` component, and use that same owner for `replace`, bounded `update`,
+`inspect`, detached `snapshot`, and terminal `release`. Runtime does not expose
+RHI buffers or require a game-side chunk manager.
+
+Read `renderer.inspect().instanceCollections` for detached
+`collectionId`/`count`/`capacity`/`revision`, resident generation and lane,
+dirty/upload ranges and bytes, backend/owner, and any structured error. The
+error's `code`, `expected`, `hint`, and typed facts
+(`requestedBytes`, `supportedBytes`, `backend`, `owner`, `cause`, and
+`recovery`) are the recovery API; do not parse the message or stack. An
+authoring error is repaired at `renderer.instances`; a capability or record
+error is repaired at the named producer/backend and then the identical frame
+request is retried.
+
+If the renderer enters `device-lost`, `await renderer.recover()` and redraw.
+The canonical CPU matrices survive the generation change, while every new GPU
+resident is initialized from the complete canonical collection before draw;
+partial dirty ranges are never mistaken for initialization after recovery.
+The initial matrices should be identity-filled (with any desired translation),
+not all-zero mat4 values, so the first frame has a valid homogeneous transform
+and visible geometry. The complete authoring and inspection recipe is in
+[`@forgeax/engine-render`](../render/README.md#renderer-owned-instances-and-cpu-bounds).
+
 ## Standard profile recovery
 
 The host exposes one `forgeax::standard` profile. `lightCount` is one of
@@ -237,6 +330,11 @@ import { createRenderer } from '@forgeax/engine-runtime';
 const created = await createRenderer(canvas);
 if (!created.ok) return created.error;
 const renderer = created.value;
+const ready = await renderer.initialization;
+if (!ready.ok) {
+  renderer.dispose();
+  return ready.error;
+}
 const attached = renderer.attach(world);
 if (!attached.ok) return attached.error;
 return renderer.draw({

package/dist/collect-scene-asset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collect-scene-asset.d.ts","sourceRoot":"","sources":["../src/collect-scene-asset.ts"],"names":[],"mappings":"AA8CA,OAAO,EAGL,oCAAoC,EACpC,sCAAsC,EACvC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAEL,KAAK,SAAS,IAAI,YAAY,EAC9B,KAAK,YAAY,EACjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAQ3D,OAAO,KAAK,EACV,KAAK,EAIL,UAAU,EAGX,MAAM,uBAAuB,CAAC;AAG/B,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;CAC1C;AAqID,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7C,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,oCAAoC,CAAC,CA2BvE;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EAAE,GACpB,MAAM,CACP,UAAU,EACV,sCAAsC,GAAG,oCAAoC,CAC9E,CAgbA"}
+{"version":3,"file":"collect-scene-asset.d.ts","sourceRoot":"","sources":["../src/collect-scene-asset.ts"],"names":[],"mappings":"AA8CA,OAAO,EAGL,oCAAoC,EACpC,sCAAsC,EACvC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAEL,KAAK,SAAS,IAAI,YAAY,EAC9B,KAAK,YAAY,EACjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAS3D,OAAO,KAAK,EAAE,KAAK,EAAyB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGtF,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;CAC1C;AAirBD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7C,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,oCAAoC,CAAC,CA2BvE;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EAAE,GACpB,MAAM,CACP,UAAU,EACV,sCAAsC,GAAG,oCAAoC,CAC9E,CAqfA"}

package/dist/index.d.ts

@@ -61,7 +61,7 @@ export { EngineEnvironmentError } from './errors/environment';
  *     }
  *   });
  */
-export { type LimitExceededDetail, type RhiAssetNotRegisteredDetail, RhiError, type RhiErrorCode, type RhiErrorDetail, type RhiShaderCompileDetail, type RhiWebgpuRuntimeDetail, } from '@forgeax/engine-rhi';
+export { type LimitExceededDetail, type RhiAssetNotRegisteredDetail, RhiError, type RhiErrorCode, type RhiErrorDetail, type RhiShaderCompileDetail, type RhiWebgpuRuntimeCause, type RhiWebgpuRuntimeDetail, } from '@forgeax/engine-rhi';
 /**
  * Asset system SSOT re-exports (feat-20260511-asset-system-v1 / w30 / D-P7 +
  * plan-strategy §7.4 discoverability dual-entry).

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAgBlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAW9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;GASG;AACH;;;;;;;;;GASG;AAKH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAQlE;;;;;;GAMG;AACH;;;;;;;;;;;;;;GAcG;AACH;GACG;AAQH;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAiB5E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAiB5C,OAAO,EACL,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AA+B/B;;;;;;;;;;GAUG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAgBlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAW9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;GASG;AACH;;;;;;;;;GASG;AAKH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAQlE;;;;;;GAMG;AACH;;;;;;;;;;;;;;GAcG;AACH;GACG;AAQH;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAiB5E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAiB5C,OAAO,EACL,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AA+B/B;;;;;;;;;;GAUG"}