@forgeax/engine-runtime 0.1.6 → 0.1.19

package/README.md

@@ -1,5 +1,50 @@
 # `@forgeax/engine-runtime`
 
+## Host entry and frame evidence
+
+`createRenderer` is the host assembly entry. It selects the backend services
+and returns the render package's single `Renderer` contract; game code does
+not construct a device, graph, or second submit path. Pass the attached lease,
+camera, and environment facts to `draw`, then bind diagnostics to the
+returned `FrameReceipt`:
+
+```ts
+const result = await createRenderer(canvas);
+if (!result.ok) throw result.error;
+const renderer = result.value;
+const lease = renderer.attach(world);
+if (!lease.ok) throw lease.error;
+const frame = renderer.draw({
+  leases: [lease.value],
+  camera: { lease: lease.value },
+  environment: { lease: lease.value },
+});
+if (!frame.ok) throw frame.error;
+const facts = renderer.inspect();
+const observation = await renderer.observe(frame.value, { include: ['timings'] });
+void facts;
+void observation;
+```
+
+## Progressive recovery index
+
+Start with the public host route: `createRenderer`, `attach`, and `draw`. Then
+use `inspect()` for detached state and `observe(receipt, request)` for evidence
+bound to the successful receipt. If `draw` returns an error, use its closed
+`code` and typed `detail` to repair the named producer or capability, and retry
+the identical request. Do not parse text or reach into graph, device, or
+history state.
+
+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,
+not a runtime pass. `unavailable` remains an explicit result.
+
+`inspect()` is detached and bounded. `observe()` is receipt-bound, so a
+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.
+
 ## Render happy path
 
 `createRenderer -> attach -> draw -> inspect/observe/recover` assembles one
@@ -110,6 +155,22 @@ its structured construction error. After construction, `attach`, `draw`,
 `inspect`, `observe`, and `recover` remain receipt-bound and `dispose()` is
 idempotent.
 
+### Browser backend selection and diagnosis
+
+The default browser path prefers native WebGPU and can retry through the
+`wgpu`/WebGL2 downlevel backend. Consequently, a native-channel
+`adapter-unavailable` error means only that `navigator.gpu.requestAdapter()` did
+not produce an adapter; it is not a verdict that the machine cannot run the
+game. A thrown `requestAdapter()` failure is reported separately as
+`webgpu-runtime-error` with the original name/message in `detail.error`, while a
+literal `null` remains `adapter-unavailable`.
+
+Always diagnose the final structured error rather than matching the word
+“WebGPU”. Inspect `.code`, `.expected`, `.hint`, and nested backend causes. Asset,
+shader, Pack, permission-policy, and application bootstrap failures belong to
+their own owners and must not be repaired by replacing ForgeaX with a second
+Canvas renderer or by swallowing the entry-module exception.
+
 ## Import each domain from its owner
 
 | Need | Canonical package | Example imports |