@forgeax/engine-app 0.1.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,418 @@
+# @forgeax/engine-app
+
+> **App is the browser host adapter: it measures one frame delta, passes it to the World, and draws.** Game scheduling, time resources, fixed-step policy, and gameplay behavior belong to the ECS World.
+
+## One-screen takeoff
+
+```ts
+import { createApp } from '@forgeax/engine-app';
+import { Time, Update } from '@forgeax/engine-ecs';
+import { forgeaxBundlerAdapter } from 'virtual:forgeax/bundler';
+
+const result = await createApp(canvas, {}, forgeaxBundlerAdapter());
+if (!result.ok) {
+  console.error(result.error.code, result.error.hint);
+  throw result.error;
+}
+
+const app = result.value;
+app.world.addSystem(Update, {
+  name: 'move-player',
+  queries: [],
+  fn: (world) => {
+    const delta = world.getResource(Time).delta;
+    movePlayer(delta);
+  },
+}).unwrap();
+app.start().unwrap();
+```
+
+The canvas form creates a World, renderer, default plugins, browser input backend, and rAF loop. Handle the `Result` before calling `start`.
+
+## RHI capture
+
+When the development RHI-debug flag is enabled, `app.rhiCapture` exposes one
+single-frame `captureFrame()` capability. A successful call returns one
+self-contained `rhi-tape` artifact; pass that same artifact to DevKit's
+`rhi.summary` and `rhi.inspect` operations, using the summary's
+`FrameModel.works[].workIndex` for selection.
+
+App owns only the optional capture capability. Replay, readback, PNG output,
+and artifact/file handling remain in the RHI-debug core and DevKit shells, so
+the live App surface does not grow a second replay cache or inspection API.
+
+## Execution tiers
+
+`execution` moves the complete World, Renderer, AssetRegistry, render features,
+and gameplay plugins into one Engine Worker. The Host keeps DOM input, frame
+credit, Web Audio, and inspection. `shared` adds a lazy persistent Kernel Worker
+pool over shared ECS numeric columns; it does not split the live World or render
+graph across realms.
+
+The bootstrap module constructs renderer features and native Cordis plugins
+inside the selected realm. Those plugins receive the real owners through
+`inject`; there is no parallel `run(context)` or cleanup ledger.
+
+```ts
+// game-bootstrap.ts
+import type { ExecutionBootstrapEntry } from '@forgeax/engine-app';
+import { audioPlugin } from '@forgeax/engine-audio';
+
+const bootstrap: ExecutionBootstrapEntry = (data) => ({
+  features: [createGameRenderFeature(data)],
+  plugins: [
+    audioPlugin(),
+    createGamePhysicsPlugin(data),
+    {
+      name: 'game-session',
+      inject: ['world', 'renderer', 'assets', 'executionBootstrapHost'],
+      async apply(ctx) {
+        const session = await createGameSession({
+          world: ctx.world,
+          renderer: ctx.renderer,
+          assets: ctx.assets,
+          port: ctx.executionBootstrapHost.port,
+        });
+        ctx.effect(() => () => session.dispose(), 'game/session');
+      },
+    },
+  ],
+});
+
+export default bootstrap;
+```
+
+```ts
+const result = await createApp(canvas, {
+  execution: {
+    tier: 'auto',
+    bootstrap: new URL('./game-bootstrap.mjs', import.meta.url),
+    bootstrapData: { gameId: 'example' },
+    bootstrapPort: realmPort,
+  },
+}, forgeaxBundlerAdapter());
+if (!result.ok) throw result.error;
+
+const app = result.value;
+app.start().unwrap();
+const report = app.execution.report();
+console.log(report.requestedTier, report.actualTier, report.selectionReason);
+
+if (report.world.health === 'poisoned') {
+  const rebuilt = await app.execution.rebuild();
+  if (!rebuilt.ok) throw rebuilt.error;
+}
+```
+
+```mermaid
+flowchart LR
+    H["Host: DOM UI, input, frame credit, Web Audio"] <--> P["Typed MessagePort"]
+    P <--> E["Engine realm: World, Renderer, Assets, game bootstrap"]
+    E --> K["Kernel Workers: eligible QuerySpan shards"]
+    K --> E
+```
+
+| Requested tier | Runtime shape | Selection rule |
+|:--|:--|:--|
+| `main-serial` | Host-owned World and Renderer | Always available |
+| `engine-worker` | Co-located Engine Worker | Requires Worker, OffscreenCanvas, and Worker WebGPU |
+| `shared` | Engine Worker plus SAB Kernel pool | Also requires isolation headers, SharedArrayBuffer, and Atomics wait |
+| `auto` | Best available proven tier | Reports the actual tier and reason; never disguises fallback |
+
+An explicit unavailable tier returns a structured `AppError`; only `auto` falls back. Serve `shared` with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` or `credentialless`, then verify the Worker-realm facts in `app.execution.report()`. Every SharedKernel module is imported, export-checked, and retained in every lane before the Engine Worker reports ready; frame jobs invoke that retained module synchronously, so an invalid module fails before the first shared write without adding a dynamic-import Promise to each dispatch. A partial Kernel write poisons the World, stops update/draw, and requires explicit rebuild to obtain a new World identity.
+
+`bootstrapData` must be structured-cloneable and is validated before a canvas is
+transferred. `bootstrapPort` is the realm side of a host-created
+`MessageChannel`; `executionBootstrapHostPlugin` provides it and closes it with
+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.
+
+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
+`main-serial` fallback. Construct them in the bootstrap module so `auto` has one
+game assembly path in every selected tier.
+
+The machine-readable report contract is [`schema/execution-report.schema.json`](./schema/execution-report.schema.json). Shared Kernel eligibility and storage rules are owned by [`@forgeax/engine-ecs`](../ecs). The production reference and benchmark commands are in [`hello/multithreaded-execution`](../../apps/hello/multithreaded-execution).
+
+## Renderer feature passthrough
+
+`CreateAppOptions.membershipTiming` is a transparent Render option. App does
+not timestamp frames or own timing reasons; it forwards the value to Runtime
+and Render. Omit it for zero timing work, use `cpu-control` for the independent
+CPU control path, or use `gpu` for bounded backend-aware evidence.
+
+`CreateAppOptions.features` is the transparent app seam for producer-owned
+renderer features. The array is forwarded to the existing renderer options
+without reordering, copying, or adding an App-level VFX branch. A feature host
+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,
+);
+if (!result.ok) {
+  console.error(result.error.code, result.error.hint);
+  throw result.error;
+}
+result.value.start().unwrap();
+```
+
+The app does not attach a VFX World or registry. Call
+`vfxHost.attachWorld({ world, assets })` before the first update and
+`vfxHost.detachWorld({ world })` during teardown. Inspect structured Result
+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:
+
+```text
+measured deltaSeconds -> world.update(deltaSeconds) -> renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })
+```
+
+The host measures the delta once and forwards that same value to its World. A `World` validates the delta, owns `Time` and `FixedTime`, runs its `Update` and `FixedUpdate` schedules, and applies its own time policy. App does not maintain an elapsed clock, clamp time, register frame callbacks, or offer a second scheduling surface.
+
+`app.onError` receives structured failures from the World update and renderer draw paths.
+
+```ts
+const unlisten = app.onError((error) => {
+  console.error(error.code, error.hint);
+});
+
+const started = app.start();
+if (!started.ok) console.error(started.error.code, started.error.hint);
+
+// Pause scheduling without destroying the realm:
+unlisten();
+app.stop();
+
+// Final ownership release:
+await app.dispose();
+```
+
+Hosts that discover additional Worlds during bootstrap can update the routing pull
+without creating a second frame loop:
+
+```ts
+app.setDrawSource(() => ({
+  worlds: [app.world, overlayWorld],
+  cameraOwner: 0,
+  resourceOwner: 0,
+}));
+// `app.setDrawSource(undefined)` restores the single-world path.
+```
+
+The injected Worlds are updated by the same frame loop before the renderer draw;
+the setter changes only draw routing, while each World retains its own time policy.
+
+## Opt-in CPU profiling
+
+Performance tooling passes one `Profiler` capability through the canvas or assemble options. App
+and Render write bounded records into that capability only while a capture is active; default App
+construction has no profiler work and no capture artifact.
+
+```ts
+import { createProfiler } from '@forgeax/engine-profiler';
+
+const profiler = createProfiler();
+const result = await createApp({ renderer, world, profiler });
+if (!result.ok) throw result.error;
+
+const started = profiler.startCapture({ frameLimit: 120, eventLimit: 1024 });
+if (!started.ok) throw started.error;
+// Run the App for the requested frames, then finish the bounded session.
+const capture = started.value.finish();
+if (!capture.ok) throw capture.error;
+```
+
+Read `profiler.phaseCatalog` for the owner-declared App and Render relation. Use
+`validateProfileCapture(capture.value)` before persisting or passing an artifact to the CLI. The
+profiler is a CPU diagnostic capability; it does not replace ECS schedules, GPU timestamps, or a
+browser UI.
+
+## Time policy
+
+Canvas-form callers configure the World time policy when they create the App.
+
+```ts
+const result = await createApp(canvas, {
+  time: {
+    fixedDeltaSeconds: 1 / 60,
+    maxStepsPerUpdate: 4,
+    maxDeltaSeconds: 0.1,
+  },
+});
+```
+
+Systems read time through ECS resources:
+
+- `Time.delta`: validated variable-rate seconds for the current frame.
+- `Time.elapsed`: accumulated validated variable-rate seconds.
+- `FixedTime.delta`: fixed simulation interval.
+- `FixedTime.tick`: completed fixed updates.
+- `FixedTime.overstep`: seconds accrued toward the next fixed update.
+- `FixedTime.droppedSeconds` and `FixedTime.droppedUpdates`: explicit metrics when the configured catch-up cap truncates work.
+
+The assemble form preserves the injected World's policy. Create that World before assembly instead of passing a competing app option.
+
+```ts
+import { World } from '@forgeax/engine-ecs';
+import { createApp } from '@forgeax/engine-app';
+
+const world = new World({ time: { fixedDeltaSeconds: 1 / 120, maxStepsPerUpdate: 8 } });
+const result = await createApp({ renderer, world, plugins: [myPlugin] });
+if (!result.ok) throw result.error;
+result.value.start().unwrap();
+```
+
+## Callback deletion migration
+
+`registerUpdate` is deleted. Convert each former callback into a named ECS system and select its schedule explicitly.
+
+```ts
+import { Time, Update, defineSystem } from '@forgeax/engine-ecs';
+
+const AnimateHud = defineSystem({
+  name: 'animate-hud',
+  queries: [],
+  fn: (world) => updateHud(Math.sin(world.getResource(Time).elapsed)),
+});
+
+app.world.addSystem(Update, AnimateHud).unwrap();
+```
+
+Use `FixedUpdate` for deterministic simulation.
+
+```ts
+import { FixedUpdate } from '@forgeax/engine-ecs';
+
+app.world.addSystem(FixedUpdate, {
+  name: 'step-combat',
+  queries: [],
+  fn: () => stepCombat(),
+}).unwrap();
+```
+
+Schedule ordering is ECS data. Use `before`, `after`, system sets, and token-first mutation APIs rather than a callback list.
+
+## Input and plugins
+
+The canvas form inserts the input backend and activates its scan system on `Update` before user systems. Gameplay systems consume the frozen `InputSnapshot`; they do not install raw browser event listeners.
+
+```ts
+import { INPUT_SNAPSHOT_RESOURCE_KEY, type InputSnapshot } from '@forgeax/engine-input';
+import { Update, defineSystem } from '@forgeax/engine-ecs';
+
+const ReadInput = defineSystem({
+  name: 'read-input',
+  queries: [],
+  fn: (world) => {
+    const input = world.getResource<InputSnapshot>(INPUT_SNAPSHOT_RESOURCE_KEY);
+    if (input.keyboard.down('KeyW')) moveForward();
+  },
+});
+app.world.addSystem(Update, ReadInput).unwrap();
+```
+
+Pass optional capabilities as native Cordis plugins. Providers are explicit:
+
+```ts
+import { audioPlugin } from '@forgeax/engine-audio';
+import { webAudioPlugin } from '@forgeax/engine-audio-webaudio';
+import { physicsPlugin } from '@forgeax/engine-physics';
+
+const result = await createApp(canvas, {
+  plugins: [webAudioPlugin(), audioPlugin(), physicsPlugin('rapier-3d')],
+});
+if (!result.ok) throw result.error;
+
+const feature = await result.value.pluginContext.plugin(optionalGameplayFeature);
+await feature.dispose();
+await result.value.dispose();
+```
+
+Every App owns one `pluginContext`. Cordis `inject`, `provide`, `effect`, and
+`Fiber` are the only composition lifecycle. `stop()` controls frame scheduling;
+`dispose()` drains plugin effects and releases Host/renderer ownership. An
+assemble-form host still owns the World and renderer objects it supplied, while
+the App owns the Cordis realm it assembled around them.
+
+## API index
+
+| Entry | Shape | Purpose |
+|:--|:--|:--|
+| `createApp(canvas, options?, bundler?)` | `Promise<Result<App, CanvasAppError>>` | Creates the canvas-form World, renderer, plugins, input, and frame loop. |
+| `createApp({ renderer, world, plugins?, ... })` | `Promise<Result<App, AssembleAppError>>` | Assembles host-owned renderer and World without replacing their policy. |
+| `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. |
+| `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. |
+| `App.stop()` / `pause()` / `resume()` | `Result<void, AppError>` | Controls the rAF lifecycle. |
+| `App.dispose()` | `Promise<Result<void, AppError>>` | Drains the Cordis realm, Host resources, and renderer ownership. |
+| `App.pluginContext` | `Context` | Native Cordis realm for runtime and asset-resident game plugins. |
+| `App.stepFrame(deltaSeconds)` | `Result<void, AppDispatchError>` | While paused, advances one deterministic update/draw frame through the same App frame authority used by rAF. |
+| `App.releaseSurfacePreserveWorld()` / `restoreSurface()` | `Promise<Result<void, RhiError>>` | Temporarily pauses presentation and relinquishes the canvas surface while preserving the same World, Renderer, registry, and execution authority; restore resumes only a loop that was running before release. |
+| `App.onError(callback)` | `() => void` | Subscribes to structured World and renderer failures. |
+| `App.setDrawSource(drawSource)` | `void` | Replaces per-frame multi-world routing; `undefined` restores the single-world path. |
+| `App.world` / `App.renderer` | readonly | Exposes the assembled ECS and renderer instances. |
+
+## Boundaries
+
+- `createApp` returns `Result`; inspect `.ok`, `.error.code`, and `.error.hint` rather than swallowing failures.
+- `createRenderer` is the lower-level route. Its host is responsible for `world.update(deltaSeconds)` and renderer drawing.
+- Demo motion failures are engine or schedule integration failures. Do not restore a demo-local callback or manual frame loop workaround.
+- Deterministic preview and tooling seeks must pause the App and use `stepFrame`; they must not call `world.update` or `renderer.draw` as a parallel frame path.
+- `Camera.clearColor` belongs to the Camera component, and bundler wiring belongs to `BundlerOptions`; neither is an App time responsibility.
+
+See `packages/app/src/types.ts` for option and Result types, `packages/app/src/internal/frame-loop.ts` for the frame-loop implementation, `packages/plugin/README.md` for the Cordis lifecycle, and `packages/ecs/README.md` for World schedule and time semantics.
+
+## Remote component discovery
+
+Quick start in a Node or dawn-node host:
+
+```ts
+import { createApp } from '@forgeax/engine-app';
+
+process.env.FORGEAX_ENGINE_REMOTE_SERVE = '1';
+const result = await createApp({ world, renderer });
+// Use the existing WS client to call the existing introspect method.
+```
+
+The app host derives JSON-safe descriptors from the global ECS component
+registry after plugins build. It injects those descriptors into the existing
+remote `introspect` response; app does not define, validate, or own a component.
+
+| Boundary | Contract | Recovery |
+|:--|:--|:--|
+| App -> remote | `startServer({ introspection })` carries data only | If remote is absent, verify dev mode or the explicit headless env flag |
+| Remote -> consumer | Existing `eval` and `introspect` methods remain the full surface | Use the returned `RemoteError` fields, never message parsing |
+| ECS/render | Registry and `Visibility` remain package-owned | Use `_import('@forgeax/engine-render')` in eval, not app-local labels |
+
+The descriptor is a transport projection, not a live token: it contains schema,
+field reflection, labels, and JSON-safe metadata, but no methods or validator
+functions. Camera, picking, lifecycle, assets, and VFX shadow policy remain
+outside the app host.