@forgeax/engine-app 0.1.4 → 0.1.7

package/README.md

@@ -128,6 +128,14 @@ the execution Fiber. Keep DOM UI on the Host side of that typed channel.
 `ExecutionBootstrapHost.setPointerLockAllowed` is the one built-in
 realm-to-Host control because browser input ownership remains on the Host.
 
+> [!IMPORTANT]
+> Runtime asset delivery in an execution realm uses `execution.assetCatalog`,
+> a serializable `{ url, expectedScope? }` descriptor. Engine constructs the
+> `CatalogSource` and `AssetRegistry` inside the selected realm, so an Engine
+> Worker never captures a Host-side registry. `expectedScope` keeps a scoped
+> game catalog tied to its `scopeId` and `generation`; `CreateAppOptions.assetCatalog`
+> remains realm-bound and is rejected when `execution` is requested.
+
 When `execution` is present, realm-bound `CreateAppOptions` (`features`,
 `plugins`, RHI injection, draw source, membership
 timing, and bundler import transport) are rejected instead of working only in a
@@ -151,21 +159,13 @@ therefore remains the owner of its feature and lifecycle:
 ```ts
 import { createApp } from '@forgeax/engine-app';
 import { createVfxRuntimeHost } from '@forgeax/engine-vfx-render';
-import { vfxGpuEffectContribution } from '@forgeax/engine-vfx';
 
 declare const canvas: HTMLCanvasElement;
 declare const camera: import('@forgeax/engine-vfx-render').ParticleRenderCameraSource;
 declare const bundler: import('@forgeax/engine-app').BundlerOptions;
 
 const vfxHost = createVfxRuntimeHost({ camera });
-const result = await createApp(
-  canvas,
-  {
-    features: [vfxHost.feature],
-    assetDecoders: [vfxGpuEffectContribution],
-  },
-  bundler,
-);
+const result = await createApp(canvas, { features: [vfxHost.feature] }, bundler);
 if (!result.ok) {
   console.error(result.error.code, result.error.hint);
   throw result.error;
@@ -179,11 +179,6 @@ The app does not attach a VFX World or registry. Call
 errors by `code`, `expected`, `hint`, and `detail`; do not treat a successful App
 construction as proof that a particle asset is ready or visible.
 
-The App default assembly includes a device-neutral `particle-effect` decoder.
-VFX rendering selects the artifact-backed GPU owner explicitly with
-`assetDecoders: [vfxGpuEffectContribution]`; the host then shares that decoder
-lease instead of installing a competing kind.
-
 ## Frame-loop responsibility
 
 Every frame follows one host-owned sequence:
@@ -212,6 +207,16 @@ app.stop();
 await app.dispose();
 ```
 
+`App.lastError` retains the most recent dispatch failure after the listener
+callback runs, so an AI host can inspect the same object without scraping
+console output:
+
+| Fact | Recovery surface |
+|:--|:--|
+| `app-system-update-failed` | `detail.cause` preserves the original failure and `detail.systemName` identifies the owner when known. |
+| Renderer or device failure | `app.onError` and `lastError` expose the closed error code with `expected`, `hint`, and discriminated `detail`. |
+| No failure observed | `lastError` is `undefined`; do not infer readiness from App construction alone. |
+
 Hosts that discover additional Worlds during bootstrap can update the routing pull
 without creating a second frame loop:
 
@@ -368,6 +373,7 @@ the App owns the Cordis realm it assembled around them.
 | `CreateAppOptions.time` | `TimePolicy` | Policy used only for the newly created canvas-form World. |
 | `CreateAppOptions.features` | `readonly RenderFeature<unknown>[]` | Existing renderer feature seam, forwarded by reference and order. |
 | `CreateAppOptions.execution` | `ExecutionOptions` | Selects `auto`, `main-serial`, `engine-worker`, or `shared` and names the bootstrap module. |
+| `ExecutionOptions.assetCatalog` | `ExecutionAssetCatalog` | Supplies the serializable catalog URL and optional scope fence to the selected Engine realm. |
 | `App.execution.report()` | `ExecutionReport` | Returns the schema-valid requested/actual tier, capabilities, health, performance, audio, and fault projection. |
 | `App.execution.rebuild()` | `Promise<Result<ExecutionReport, AppError>>` | Rebuilds only a poisoned Worker World with a new identity. |
 | `App.start()` | `Result<void, AppError>` | Arms the rAF loop. |