@forgeax/engine-app 0.0.0-dev.8d955ade1c79

package/dist/types.d.ts

@@ -0,0 +1,404 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { AudioBackend } from '@forgeax/engine-audio';
+import type { DebugDraw } from '@forgeax/engine-debug-draw';
+import type { TimePolicy, World } from '@forgeax/engine-ecs';
+import type { ActionConfig, InputBackend, PointerLockProvider, VirtualJoystickConfig } from '@forgeax/engine-input';
+import type { PhysicsWorld, PhysicsWorld2D } from '@forgeax/engine-physics';
+import type { Context, Plugin } from '@forgeax/engine-plugin';
+import type { Profiler } from '@forgeax/engine-profiler';
+import type { RenderError, Renderer, RenderFeature, RenderProfile } from '@forgeax/engine-render';
+import type { RhiBackendInstrumentation } from '@forgeax/engine-render/internal/construct-renderer';
+import type { RhiError, RhiInstance } from '@forgeax/engine-rhi';
+import type { EngineEnvironmentError } from '@forgeax/engine-runtime';
+import type { ImportTransport, Result } from '@forgeax/engine-types';
+import type { AppError, AppErrorCode } from './errors';
+import type { ExecutionControl, ExecutionOptions } from './execution';
+import type { RhiCapture } from './internal/rhi-capture';
+export type { AppError, AppErrorCode };
+/**
+ * Structured error union surfaced through the App `onError` fan-out + the
+ * assemble-form construction Result. Derived from the `Renderer.onError`
+ * channel contract `RendererError` (feat-20260704-runtime-tier1-decomposition
+ * M2 / w14 / D-4) so a runtime-layer error fanned out by the renderer (e.g.
+ * `'equirect-projection-failed'`) reaches host App listeners verbatim, plus the
+ * App-layer `AppError`. `RendererError` = `RhiError | RenderError |
+ * AssetRuntimeError | SkinError | PostProcessError`, so this equals the
+ * pre-decomposition `AppError | RhiError | RuntimeError | PostProcessError`
+ * exactly (RuntimeError was RenderError | AssetRuntimeError | SkinError). AI
+ * users `switch (err.code)` over the union: the disjoint `AppErrorCode` /
+ * `RhiErrorCode` / per-cluster `*ErrorCode` / `PostProcessErrorCode` literal
+ * sets let TS narrow each arm to the concrete class.
+ */
+export type AppDispatchError = AppError | RenderError;
+/**
+ * Per-frame draw description pulled from the host each frame
+ * (feat-20260709-editor-world-partition-editorworld-super-composite / M2 / D-3).
+ *
+ *   - `worlds`       — the exact world list to render this frame, in draw order.
+ *   - `cameraOwner`  — index into `worlds` whose cameras drive the frame.
+ *   - `resourceOwner`— index into `worlds` whose singleton render resources
+ *                      (skylight / skybox / postProcessParams) drive the frame.
+ *
+ * The two owners are independent (M1 owner-split): an editor can render a scene
+ * world's geometry through an editor world's camera while sourcing lighting from
+ * a third. `cameraOwner === resourceOwner` is the single-owner degenerate case.
+ *
+ * @see {@link DrawSource}
+ */
+export interface DrawSourceResult {
+    readonly worlds: readonly World[];
+    readonly cameraOwner: number;
+    readonly resourceOwner: number;
+}
+/**
+ * Stable frame-loop phase vocabulary for opt-in performance diagnostics.
+ *
+ * Local and Worker execution record these phases through the same optional
+ * Profiler capability. When omitted, the frame loop keeps its normal path and
+ * does not allocate capture records.
+ */
+export declare const APP_PHASE_CATALOG: readonly ["frame-total", "draw-source", "world-update-primary", "world-update-injected", "renderer-draw", "host-frame", "engine-update", "kernel-wait", "host-audio"];
+/**
+ * Optional per-frame draw-source injection seam
+ * (feat-20260709-editor-world-partition-editorworld-super-composite / M2 / D-3).
+ *
+ * The frame-loop invokes this callback once per frame (a "pull"). It lets a host
+ * (e.g. the editor) decide, each frame, WHICH worlds to render and which owner
+ * indices to use — without the engine knowing anything about editor world
+ * partitioning.
+ *
+ *   - Returns `undefined` → the frame-loop degrades to the single-world path,
+ *     byte-identical to `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` where `world` is
+ *     the App's own world (the single-world AI-user default). A host that wires
+ *     the seam but has nothing multi-world to inject this frame returns
+ *     `undefined`.
+ *   - Returns a {@link DrawSourceResult} → the frame-loop runs `world.update(1 / 60).unwrap()`
+ *     on EVERY returned world (so transform propagation writes each world's
+ *     derived `Transform.world` mat4 before extract reads it — no stale matrix),
+ *     then calls `renderer.draw(worlds, { cameraOwner, resourceOwner })`.
+ *
+ * When omitted entirely, the App never consults a seam and always renders its
+ * own single world (legacy behaviour unchanged).
+ */
+export type DrawSource = () => DrawSourceResult | undefined;
+/**
+ * Options for the assemble-form entry createApp({ renderer, world, ... }).
+ *
+ * Field semantics (final shape -- runtime use lands in M2..M5):
+ *   - renderer: caller-owned Renderer (host already invoked createRenderer).
+ *   - world:    caller-owned World (host already invoked new World()).
+ *   - input:    InputBackend handle the host-side attached. When omitted the
+ *               assemble entry skips input attach (caller manages input).
+ *   - silenceUnhandledErrors: when true, suppresses the console.error
+ *               fallback inside the error fan-out (M4).
+ */
+export interface AppAssembleArgs {
+    readonly renderer: Renderer;
+    /** Host-owned asset catalogue paired with the renderer construction. */
+    readonly assets?: AssetRegistry;
+    readonly world: World;
+    /** Unified plugin list (M1 feat-20260623-plugin-system-unify-build-world-protocol). */
+    readonly plugins?: readonly Plugin[];
+    readonly silenceUnhandledErrors?: boolean;
+    /**
+     * Per-frame draw-source injection seam (M2 / D-3). When supplied, the
+     * frame-loop pulls it each frame to decide which worlds to render + which
+     * owner indices to use; when omitted the App renders its own single world
+     * (legacy behaviour). See {@link DrawSource}.
+     */
+    readonly drawSource?: DrawSource;
+    /** Explicit profiler capability shared by the host and renderer. */
+    readonly profiler?: Profiler;
+}
+/** Effective physical canvas size transported to an Engine Worker frame. */
+export interface CanvasDrawingBufferSize {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Options for the canvas-form thin wrapper createApp(canvas, opts?, bundler?).
+ *
+ * feat-20260608-create-app-param-surface-trim / M2 / D-3: self-describing
+ * surface -- no longer `extends RendererOptions`. The 7 app-only fields
+ * (input / audio / physics / silenceUnhandledErrors) plus the RHI escape-hatch
+ * field (rhi) are
+ * listed inline, so IDE autocomplete shows AI users a clean surface
+ * without inheriting now-disallowed slots like clearColor (M1, on Camera)
+ * and shaderManifestUrl (M2, on BundlerOptions / 3rd arg). The escape
+ * hatches stay discoverable for the RHI debugging path (charter P1 -- not
+ * default noise, but reachable when the AI user scrolls the type).
+ */
+export interface CreateAppOptions {
+    /** Opt into realm-local engine execution. Omission preserves the existing local assembly path. */
+    readonly execution?: ExecutionOptions;
+    /** Host-owned UI root whose events do not enter gameplay input. */
+    readonly uiRoot?: Node;
+    /** Producer-owned render features forwarded to the renderer unchanged. */
+    readonly features?: readonly RenderFeature<unknown>[];
+    /** Standard profile forwarded to the single renderer-owned pipeline. */
+    readonly standardProfile?: RenderProfile;
+    /** Unified plugin list (M1 feat-20260623-plugin-system-unify-build-world-protocol). */
+    readonly plugins?: readonly Plugin[];
+    /**
+     * A host-owned input backend for this canvas. When supplied, createApp inserts
+     * it into the World instead of attaching a second browser listener set. The
+     * host retains its lifecycle; this app only consumes snapshots from the view.
+     */
+    readonly input?: InputBackend;
+    /**
+     * World-owned time policy supplied to the canvas-form World constructor.
+     * Assemble-form callers retain their pre-existing World policy.
+     */
+    readonly time?: TimePolicy;
+    /**
+     * When true, suppresses the console.error fallback inside the error
+     * fan-out for hosts that prefer total silence (M4 default: false).
+     */
+    readonly silenceUnhandledErrors?: boolean;
+    /**
+     * RHI escape hatch -- forwarded verbatim to createRenderer. Same semantics
+     * as `RendererOptions.rhi` (the createRenderer third-party-RHI-instance
+     * injection point). Use only for testing / pinning a specific backend /
+     * advanced AI users that ship their own RhiInstance shim.
+     */
+    readonly rhi?: RhiInstance | undefined;
+    /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
+    readonly rhiInstrumentation?: RhiBackendInstrumentation;
+    /**
+     * Neutral PointerLock gate forwarded verbatim to the canvas-form input
+     * attach (attachInputAuto → attachBrowserInputBackend). When it returns
+     * false, a canvas click does NOT capture the cursor. Absent => always-lock
+     * (standalone game behaviour). The engine never learns WHY locking is
+     * (dis)allowed — the host owns that decision (e.g. an editor viewport that
+     * only allows lock in its play·game quadrant). Ignored by the assemble form
+     * (host-managed input owns its own lock policy).
+     */
+    readonly pointerLockAllowed?: () => boolean;
+    /**
+     * Virtual joystick configs forwarded verbatim to the canvas-form input
+     * attach (attachInputAuto -> attachBrowserInputBackend). Each config derives
+     * a normalized 2D axis readable via `snap.virtualAxis(name)`. Absent => no
+     * virtual joysticks. Ignored by the assemble form (host-managed input wires
+     * its own backend). Mirrors `pointerLockAllowed`: the canvas-form entry must
+     * expose every backend option the standard recipe needs, or the config path
+     * dead-ends before reaching the backend that already supports it.
+     */
+    readonly virtualJoysticks?: readonly VirtualJoystickConfig[];
+    /**
+     * Action mapping configuration (M1: action semantic abstraction layer).
+     *
+     * Declares named actions (e.g. 'jump', 'moveRight') bound to raw input sources
+     * (key, mouseButton, gamepadButton, gamepadAxis). The engine derives per-frame
+     * action states via `deriveActionStates()` and exposes them via
+     * `snap.action(name).isPressed()`. Duplicate action names follow last-wins
+     * semantics (D-8).
+     *
+     * This is canvas-form only. Assemble-form hosts insert the
+     * `INPUT_MAP_KEY` Resource directly.
+     */
+    readonly inputMap?: readonly ActionConfig[] | undefined;
+    /**
+     * M2: pointer-lock provider injected by the host (e.g. editor play-runtime).
+     * Forwarded verbatim through InputAttachOptions to BrowserInputBackendOptions.
+     * When absent, the backend falls back to the W3C requestPointerLock() path.
+     * Type SSOT is @forgeax/engine-input's PointerLockProvider.
+     * Ignored by the assemble form (host-managed input owns its own lock policy).
+     */
+    readonly lockProvider?: PointerLockProvider;
+    /**
+     * Per-frame draw-source injection seam (M2 / D-3). When supplied, the
+     * frame-loop pulls it each frame to decide which worlds to render + which
+     * owner indices to use; when omitted the canvas-form App renders its own
+     * single world (legacy behaviour unchanged). See {@link DrawSource}.
+     */
+    readonly drawSource?: DrawSource;
+    /** Explicit profiler capability shared by the host and renderer. */
+    readonly profiler?: Profiler;
+}
+/**
+ * Bundler-layer injection for the canvas-form createApp(canvas, opts, bundler?)
+ * and createRenderer(canvas, opts, bundler?).
+ *
+ * feat-20260608-create-app-param-surface-trim / M2 / D-3: this is the SSOT
+ * for build-tool emit knowledge that the engine consumes at runtime.
+ * Aggregates two host-injected channels:
+ *
+ *   - importTransport: dev-only ImportTransport that the engine threads to
+ *     the AssetRegistry third ctor slot so a DDC miss can lazy-import.
+ *     Absent => shipped form (DDC miss fails fast with `asset-not-imported`).
+ *
+ *   - shaderManifestUrl: the path the host's vite-plugin-shader emit step
+ *     wrote `manifest.json` to. Absent (or `BundlerOptions` itself omitted)
+ *     => createRenderer falls back to '/shaders/manifest.json'
+ *     (createRenderer.ts D-2 q5-A) so the LO 1.1 zero-config takeoff path
+ *     keeps working without any explicit injection.
+ *
+ * Both fields are optional so `BundlerOptions = {}` is a valid call shape.
+ * M3 collapses the typical demo callsite to `forgeaxBundlerAdapter()` (a
+ * factory exported by `virtual:forgeax/bundler`), which returns an object
+ * with this same structural shape -- type compatibility is enforced by
+ * TypeScript structural typing (D-4: vite-plugin-shader does NOT import
+ * `@forgeax/engine-app`, so this interface is the consumer-side SSOT).
+ */
+export interface BundlerOptions {
+    /**
+     * Dev-only ImportTransport forwarded verbatim to createRenderer (and thence
+     * to the AssetRegistry third ctor slot). Absent => shipped form (a DDC miss
+     * fails fast with `asset-not-imported`).
+     *
+     * The `| undefined` widening is necessary because exactOptionalPropertyTypes
+     * is enabled at the workspace level (tsconfig.base.json); it lets tests
+     * (and demos that gate on a build-mode flag) write `{ importTransport:
+     * undefined }` without a TS2379 error.
+     */
+    readonly importTransport?: ImportTransport | undefined;
+    /**
+     * vite-plugin-shader emit URL (the path the build wrote `manifest.json`
+     * to). Absent => createRenderer falls back to '/shaders/manifest.json'.
+     * Tests can inject via a `data:application/json,...` URL to bypass fetch.
+     *
+     * The `| undefined` widening lets tests opt into the zero-entry mode by
+     * writing `{ shaderManifestUrl: undefined }` (the createRenderer body
+     * checks `'shaderManifestUrl' in bundler` to distinguish "absent" from
+     * "explicitly undefined"; see D-2 q5-A in plan-strategy).
+     */
+    readonly shaderManifestUrl?: string | undefined;
+}
+/**
+ * App handle returned by createApp(...). Host owns the lifecycle and
+ * interacts with the rAF loop through start / stop / pause / resume +
+ * the structured error fan-out via onError.
+ *
+ * M1 skeleton: start / stop / pause / resume return Result.ok(undefined)
+ * synchronously and onError returns a no-op unsubscribe. The 4-state
+ * machine + idempotent transitions land in M2 (plan-strategy section 7).
+ */
+export interface App {
+    /** Caller-owned Renderer (reference equality with the assemble input). */
+    readonly renderer: Renderer;
+    /** Host-owned asset catalogue paired with this renderer lease. */
+    readonly assets?: AssetRegistry;
+    /** Caller-owned World (reference equality with the assemble input). */
+    readonly world: World;
+    /** Host-side lifecycle and immutable diagnostics for the selected execution tier. */
+    readonly execution: ExecutionControl;
+    /**
+     * Pause frame submission and relinquish the renderer presentation surface
+     * without replacing World, Renderer, AssetRegistry, plugins, or history.
+     */
+    releaseSurfacePreserveWorld(): Promise<Result<void, RhiError | RenderError>>;
+    /** Restore the same surface and resume only when release paused a running App. */
+    restoreSurface(): Promise<Result<void, RhiError | RenderError>>;
+    /** Native Cordis realm that owns this App's capability fibers and effects. */
+    readonly pluginContext: Context;
+    /** InputBackend handle when input attach is enabled; undefined otherwise. */
+    readonly input?: InputBackend;
+    /** AudioBackend handle when audio attach is enabled; undefined otherwise. */
+    readonly audio?: AudioBackend;
+    /**
+     * PhysicsWorld handle when physicsPlugin is loaded; undefined
+     * otherwise. physicsPlugin.build awaits the WASM import -- createApp
+     * resolves ONLY after the WASM module is loaded, so this field is
+     * populated immediately when createApp returns (AC-06: no timing gap).
+     */
+    readonly physics?: PhysicsWorld | PhysicsWorld2D | undefined;
+    /**
+     * Immediate-mode debug-draw overlay instance (feat-20260615 debug-draw M5).
+     *
+     * Created automatically during createApp (canvas form). AI users call
+     * `app.debugDraw.line(a, b, RED)` in any system and the overlay renders
+     * at frame-end via the render-graph's debug-overlay pass. Shape calls are
+     * immediate-mode — vertices accumulate per-frame and are flushed at the
+     * tonemap suffix; stale data from frame N-1 is never visible in frame N.
+     *
+     * Undefined when debug-draw is not wired (assemble-form createApp with
+     * no explicit debugDraw creation — the auto-attach is canvas-form only).
+     */
+    readonly debugDraw?: DebugDraw | undefined;
+    /**
+     * Begin rAF scheduling. Idempotent guard lands in M2:
+     *   - first call: Result.ok(undefined)
+     *   - second call (already running): Result.err({ code: 'app-already-running' })
+     * M1 stub returns Result.ok(undefined) unconditionally.
+     */
+    start(): Result<void, AppError>;
+    /**
+     * Stop rAF scheduling. State-machine semantics land in M2:
+     *   - 'idle' / 'stopped' state: Result.err({ code: 'app-not-started' })
+     *   - 'running' / 'paused' state: Result.ok(undefined)
+     * M1 stub returns Result.ok(undefined) unconditionally.
+     */
+    stop(): Result<void, AppError>;
+    /** Tear down plugins, host resources, and renderer ownership. */
+    dispose(): Promise<Result<void, AppError>>;
+    /**
+     * Pause rAF scheduling. Idempotent in 'paused' state. M1 stub returns
+     * Result.ok(undefined) unconditionally; full state machine in M2.
+     */
+    pause(): Result<void, AppError>;
+    /**
+     * Resume rAF scheduling from paused state. M1 stub returns
+     * Result.ok(undefined) unconditionally; full state machine in M2.
+     */
+    resume(): Result<void, AppError>;
+    /**
+     * Advance one complete update/draw frame through the App-owned frame authority.
+     * The App must be paused; deterministic tools supply the explicit delta.
+     */
+    stepFrame(deltaSeconds: number): Result<void, AppDispatchError>;
+    /**
+     * Subscribe to structured errors fan-out from the rAF loop. Returns an
+     * unsubscribe handle. The callback signature deliberately excludes raw
+     * Error (charter P3 -- AI users walk .code, not message strings).
+     *
+     * M1 stub: registers nothing and returns a no-op unsubscribe; full
+     * fan-out registry lands in M4 (plan-strategy section 7).
+     */
+    onError(cb: (err: AppDispatchError) => void): () => void;
+    /**
+     * Replace the per-frame world routing pull. `undefined` restores the
+     * single-world path; an injected result updates every returned secondary
+     * World before drawing it with the declared owners. This changes routing,
+     * not scheduling or time ownership.
+     */
+    setDrawSource(drawSource: DrawSource | undefined): void;
+    /**
+     * Most recent dispatched error retained for host self-inspection without
+     * requiring an onError listener up front.
+     */
+    readonly lastError?: AppDispatchError | undefined;
+    /** Optional single-frame RHI capture capability owned by the App host. */
+    readonly rhiCapture?: RhiCapture;
+    /**
+     * Handle for the remote eval server started by createApp (dev mode).
+     *
+     * `undefined` in production builds and headless/dawn-node without explicit
+     * opt-in. When present, the host can read `app.remote.port` for WS connection
+     * details or call `await app.remote.close()` to tear down the server
+     * (feat-20260629-inspector-two-layer-model M4 / w20).
+     *
+     * Typed as {@link RemoteHandle} from `@forgeax/engine-types` — a neutral
+     * package with no dependency on `@forgeax/engine-remote`.
+     */
+    readonly remote?: import('@forgeax/engine-types').RemoteHandle | undefined;
+}
+/** Host control returned by the unified execution path. Engine-owned objects remain realm-local. */
+export type ExecutionApp = Pick<App, 'execution' | 'input' | 'audio' | 'start' | 'stop' | 'pause' | 'resume' | 'onError' | 'lastError'>;
+/**
+ * Error union returned by the assemble-form entry. The canvas-form thin
+ * wrapper widens this with EngineEnvironmentError (createRenderer
+ * construction-time failure path -- plan-strategy D-5 / requirements AC-01).
+ *
+ * Cordis activation failures are projected into AppError at this boundary.
+ */
+export type AssembleAppError = AppError | RhiError;
+/**
+ * Error union returned by the canvas-form thin wrapper. Extends
+ * AssembleAppError with EngineEnvironmentError to surface
+ * createRenderer construction-time failures unchanged (preserves
+ * .detail.webgpuError per requirements section 6.1).
+ *
+ * The canvas form adds renderer construction failures.
+ */
+export type CanvasAppError = AssembleAppError | EngineEnvironmentError;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@forgeax/engine-app",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Host assembly and execution tiers for ForgeaX: frame credit, input, Engine Worker, shared Kernels, reports, and rebuild.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-animation": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-audio": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-audio-webaudio": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-debug-draw": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-input": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-physics": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-physics-rapier2d": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-physics-rapier3d": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-profiler": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-state": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-tool-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@forgeax/engine-remote": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-debug": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-null": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-webgpu": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-wgpu": "0.0.0-dev.8d955ade1c79",
+    "@types/ws": "^8.5.10",
+    "@webgpu/types": "^0.1.71",
+    "ws": "^8.20.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": false,
+        "reason": "MVP shell package; bundle-size lock deferred until API stabilises and meaningful threshold can be locked"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library helper without bundled canvas; fps reported by hello-app and other host apps that consume createApp"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "rAF main loop is a thin orchestration layer; not a perf-critical surface for the MVP"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; AC surface coverage runs as part of pnpm test:unit + tsc -b"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; this is a production MVP per plan-strategy D-5 (double SSOT entry + thin wrapper)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}

package/schema/execution-report.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeax.dev/schema/execution-report.schema.json",
+  "title": "ForgeaX ExecutionReport",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "requestedTier",
+    "actualTier",
+    "selectionReason",
+    "sharedEvidencePassed",
+    "capabilities",
+    "engine",
+    "world",
+    "kernelDispatch",
+    "performance",
+    "audio",
+    "fault"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "requestedTier": { "enum": ["auto", "main-serial", "engine-worker", "shared"] },
+    "actualTier": { "enum": [null, "main-serial", "engine-worker", "shared"] },
+    "selectionReason": {
+      "enum": [null, "explicit-request", "auto-shared", "auto-engine-worker", "auto-main-serial"]
+    },
+    "sharedEvidencePassed": { "type": "boolean" },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker",
+        "offscreenCanvas",
+        "workerAnimationFrame",
+        "workerWebGpu",
+        "crossOriginIsolated",
+        "sharedArrayBuffer",
+        "atomicsWait"
+      ],
+      "properties": {
+        "worker": { "$ref": "#/$defs/capability" },
+        "offscreenCanvas": { "$ref": "#/$defs/capability" },
+        "workerAnimationFrame": { "$ref": "#/$defs/capability" },
+        "workerWebGpu": { "$ref": "#/$defs/capability" },
+        "crossOriginIsolated": { "$ref": "#/$defs/capability" },
+        "sharedArrayBuffer": { "$ref": "#/$defs/capability" },
+        "atomicsWait": { "$ref": "#/$defs/capability" }
+      }
+    },
+    "engine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["realm", "health"],
+      "properties": {
+        "realm": { "enum": ["host", "worker"] },
+        "health": { "enum": ["idle", "starting", "running", "stopped", "faulted"] }
+      }
+    },
+    "world": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "health", "partialWrite", "retryable"],
+      "properties": {
+        "identity": { "type": ["string", "null"] },
+        "health": { "enum": ["healthy", "poisoned"] },
+        "partialWrite": { "type": "boolean" },
+        "retryable": { "type": "boolean" }
+      }
+    },
+    "kernelDispatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eligible", "usedShared", "reason", "dispatched", "completed"],
+      "properties": {
+        "eligible": { "type": "boolean" },
+        "usedShared": { "type": "boolean" },
+        "reason": {
+          "enum": ["no-eligible-kernel", "zero-work", "small-span", "forced-inline", "shared", "poisoned"]
+        },
+        "dispatched": { "type": "integer", "minimum": 0 },
+        "completed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "performance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hostFrameMs", "engineUpdateMs", "kernelWaitMs", "hostAudioMs"],
+      "properties": {
+        "hostFrameMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "engineUpdateMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "kernelWaitMs": { "$ref": "#/$defs/nullableMeasurement" },
+        "hostAudioMs": { "$ref": "#/$defs/nullableMeasurement" }
+      }
+    },
+    "audio": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "contextState", "activeSourceCount", "lastError"],
+      "properties": {
+        "owner": { "const": "host" },
+        "contextState": { "enum": ["running", "suspended", "closed"] },
+        "activeSourceCount": { "type": "integer", "minimum": 0 },
+        "lastError": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "expected", "hint", "detail"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "expected": { "type": "string", "minLength": 1 },
+                "hint": { "type": "string", "minLength": 1 },
+                "detail": {}
+              }
+            }
+          ]
+        }
+      }
+    },
+    "fault": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["source", "code", "expected", "hint", "detail", "partialWrite", "retryable"],
+          "properties": {
+            "source": { "enum": ["bootstrap", "handshake", "runtime", "kernel", "world", "rebuild"] },
+            "code": { "type": "string", "minLength": 1 },
+            "expected": { "type": "string", "minLength": 1 },
+            "hint": { "type": "string", "minLength": 1 },
+            "detail": {},
+            "partialWrite": { "type": "boolean" },
+            "retryable": { "type": "boolean" }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "reason"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "reason": { "type": "string" }
+      }
+    },
+    "measurement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["samples", "p50", "p95", "p99", "jitter"],
+      "properties": {
+        "samples": { "type": "integer", "minimum": 1 },
+        "p50": { "type": "number", "minimum": 0 },
+        "p95": { "type": "number", "minimum": 0 },
+        "p99": { "type": "number", "minimum": 0 },
+        "jitter": { "type": "number", "minimum": 0 }
+      }
+    },
+    "nullableMeasurement": {
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/measurement" }]
+    }
+  }
+}