@forgeax/engine-app 0.1.2

package/src/create-app.ts

@@ -0,0 +1,1351 @@
+// @forgeax/engine-app -- createApp double-SSOT entry (M3 wiring).
+//
+// This file ships the final-shape signatures for both overload routes
+// (canvas thin wrapper + assemble form per plan-strategy D-5):
+//
+//   - createApp({ renderer, world, ... })  -- assemble form: returns an
+//     App with the supplied renderer / world wired through; the M2 rAF
+//     frame-loop + state machine + dt clamp drive start / stop / pause /
+//     resume. M3 lands listener-registry-backed onError + input-attach
+//     plumbing: when the host passes a pre-built InputBackend through
+//     args.input, the assemble form treats it as host-managed (no auto
+//     attach, no auto cleanup -- the host owns the lifetime).
+//
+//   - createApp(canvas, opts?)             -- canvas form (M3 partial):
+//     calls createRenderer(canvas, opts?), constructs a new World, and
+//     (when opts.input !== false) wires the auto input-attach helper so
+//     world.getResource('InputSnapshot') is populated each frame.
+//     Falls through to the assemble form for the rest of the wiring.
+//     Full canvas form (canvas-detached check, EngineEnvironmentError
+//     catch, console.error fallback) lands in M4 (plan-strategy section 7).
+//
+// 'tagName' in arg dispatch (per plan-strategy D-5): HTMLCanvasElement
+// inherits .tagName from HTMLElement, so the property test cleanly
+// separates the canvas argument from the AppAssembleArgs plain object.
+
+import {
+  type AssetRegistry,
+  type CatalogSource,
+  createAssetRegistry,
+  createCatalogSource,
+} from '@forgeax/engine-assets-runtime';
+import { getAssetRegistryResolver } from '@forgeax/engine-assets-runtime/internal';
+import type { AudioBackend } from '@forgeax/engine-audio';
+import type { DebugDraw } from '@forgeax/engine-debug-draw';
+import { createWorldContext, Update, World } from '@forgeax/engine-ecs';
+import type { InputBackend } from '@forgeax/engine-input';
+import type { Context, Plugin } from '@forgeax/engine-plugin';
+import type { Renderer, RendererError } from '@forgeax/engine-render';
+import { loadRhiPack } from '@forgeax/engine-render/internal';
+import { RhiError } from '@forgeax/engine-rhi';
+import type {
+  CaptureFrameOptions,
+  CreateShaderModuleFn,
+  RecorderAttachment,
+} from '@forgeax/engine-rhi-debug';
+import * as engineRuntimeModule from '@forgeax/engine-runtime';
+import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { type AssetDecoderContributionRef, err, ok, type Result } from '@forgeax/engine-types';
+
+import { createAnimationPayloadLookup } from './animation-asset-lookup';
+
+export { syncCameraAspect } from './canvas-policy';
+
+import {
+  type AssetRuntimeAssembly,
+  type AssetRuntimeAssemblyError,
+  assembleAssetRuntime,
+} from './assets-runtime-assembly';
+import { syncCameraAspect } from './canvas-policy';
+import type { AppErrorCode, AppErrorDetailFor } from './errors';
+import { APP_ERROR_HINTS, APP_EXPECTED, AppError } from './errors';
+import {
+  createExecutionReport,
+  type ExecutionControl,
+  executionBootstrapHostPlugin,
+  type PreparedExecutionBootstrap,
+  prepareBootstrapEntry,
+  probeExecutionCapabilities,
+  selectExecutionTier,
+  unavailableExecutionCapabilities,
+} from './execution';
+import { createLocalExecutionControl } from './execution/control';
+import { createWorkerExecutionApp } from './execution/host-controller';
+import { assembledEngineProfile } from './internal/assembled-engine-profile';
+import { projectComponentIntrospection } from './internal/component-introspection';
+import { ErrorFanoutRegistry } from './internal/error-fanout';
+import { createFrameLoop } from './internal/frame-loop';
+import { attachInputAuto } from './internal/input-attach';
+import { mainEngineProfile } from './internal/main-engine-profile';
+import { resolveRemoteServeFlag } from './internal/remote-serve-flag';
+import { remoteServerPlugin } from './internal/remote-server-plugin';
+import {
+  bindRhiCaptureFrameDriver,
+  createRhiCapture,
+  createRhiInstrumentation,
+  type RhiCapture,
+} from './internal/rhi-capture';
+import { resolveRhiDebugFlag } from './internal/rhi-debug-flag';
+import type {
+  App,
+  AppAssembleArgs,
+  AppDispatchError,
+  AssembleAppError,
+  BundlerOptions,
+  CanvasAppError,
+  CanvasDrawingBufferSize,
+  CreateAppOptions,
+  ExecutionApp,
+} from './types';
+
+const DEFAULT_ASSET_CATALOG_PATH = 'pack-index.json';
+
+function defaultAssetCatalogUrl(): string {
+  const base =
+    typeof document !== 'undefined'
+      ? document.baseURI
+      : (globalThis as { location?: { href?: string } }).location?.href;
+  return base === undefined
+    ? DEFAULT_ASSET_CATALOG_PATH
+    : new URL(DEFAULT_ASSET_CATALOG_PATH, base).href;
+}
+
+function assembleAppAssetRuntime(
+  catalog: CatalogSource | undefined,
+  contributions: readonly AssetDecoderContributionRef[] | undefined,
+): Result<AssetRuntimeAssembly, AssetRuntimeAssemblyError> {
+  const registry = createAssetRegistry({
+    catalog: catalog ?? createCatalogSource({ url: defaultAssetCatalogUrl() }),
+  });
+  const assembled = assembleAssetRuntime(registry, contributions ?? []);
+  if (!assembled.ok) registry.dispose();
+  return assembled;
+}
+
+function makeAppError<C extends AppErrorCode>(
+  code: C,
+  expected: string,
+  hint: string,
+  detail: AppErrorDetailFor<C>,
+): AppError {
+  return new AppError({ code, expected, hint, detail }) as AppError;
+}
+
+function normalizeExecutionBootstrapUrl(bootstrap: string | URL): Result<string, AppError> {
+  const moduleUrl = typeof bootstrap === 'string' ? bootstrap : bootstrap.href;
+  try {
+    return ok(new URL(bootstrap, globalThis.location?.href).href);
+  } catch (cause) {
+    return err(
+      makeAppError(
+        'app-execution-bootstrap-failed',
+        APP_EXPECTED['app-execution-bootstrap-failed'],
+        APP_ERROR_HINTS['app-execution-bootstrap-failed'],
+        { phase: 'prepare', moduleUrl, cause },
+      ),
+    );
+  }
+}
+
+function canvasAspectPlugin(canvas: HTMLCanvasElement, maxCanvasPixelRatio?: number): Plugin {
+  return {
+    name: 'canvas-aspect',
+    inject: ['world'],
+    apply(ctx) {
+      ctx.effect(() => {
+        const system = {
+          name: 'app-sync-camera-aspect',
+          queries: [],
+          fn: () => {
+            syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio);
+            syncCameraAspect(ctx.world, canvas.width, canvas.height);
+          },
+        };
+        ctx.world.addSystem(Update, system).unwrap();
+        return () => ctx.world.removeSystem(Update, system.name).unwrap();
+      }, 'app/canvas-aspect');
+    },
+  };
+}
+
+function rhiDebugHostPlugin(dispose: () => void): Plugin {
+  return {
+    name: 'rhi-debug-host',
+    apply(ctx) {
+      ctx.effect(() => dispose, 'rhi-debug/host');
+    },
+  };
+}
+
+/**
+ * createApp(canvas, opts?, bundler?) -- canvas thin wrapper SSOT (per
+ * plan-strategy D-5). Resolves with Result.ok(app) on success; failure routes
+ * through AppError | RhiError | EngineEnvironmentError per requirements AC-01.
+ *
+ * feat-20260608-create-app-param-surface-trim / M2 / D-3: the third arg is
+ * `BundlerOptions` (importTransport + shaderManifestUrl) -- the SSOT for
+ * host-injected build-tool emit knowledge. M3 demos collapse the third-arg
+ * literal to `forgeaxBundlerAdapter()` exported by `virtual:forgeax/bundler`.
+ *
+ * M3 ships the path needed by AC-05 (auto input acquisition plus an ECS scan
+ * plugin). M4 finalises the canvas-detached guard +
+ * EngineEnvironmentError try/catch + onError default fallback.
+ *
+ * The host-engine contract defines the boundary between host (DOM, canvas, UI)
+ * and engine (renderer, world, frame loop). Only the `createApp(canvas)` path
+ * auto-wires the aspect-sync sidecar; the assemble form and bare
+ * `createRenderer` path do not.
+ *
+ * @see {@link https://github.com/Ubpa/forgeax-engine/blob/main/docs/how-to/2026-06-18-host-engine-contract.md | Host-engine contract SSOT}
+ */
+export function createApp(
+  canvas: HTMLCanvasElement,
+  opts: CreateAppOptions & { readonly execution: NonNullable<CreateAppOptions['execution']> },
+  bundler?: BundlerOptions,
+): Promise<Result<ExecutionApp, CanvasAppError>>;
+export function createApp(
+  canvas: HTMLCanvasElement,
+  opts?: CreateAppOptions,
+  bundler?: BundlerOptions,
+): Promise<Result<App, CanvasAppError>>;
+
+/**
+ * createApp({ renderer, world, input?, schedule?, ... }) -- assemble-form
+ * SSOT (per plan-strategy D-5). Host already owns renderer / world; the
+ * returned App holds them by reference equality (per AC-02).
+ *
+ * M3 wires the rAF frame-loop + listener-registry-backed onError. When
+ * args.input is supplied, the assemble form treats it as host-managed:
+ * it is exposed verbatim as app.input, and the host is responsible for
+ * detaching it (no auto-cleanup on stop). The canvas form is the entry
+ * that engages the auto-attach helper (input-attach.ts).
+ */
+export function createApp(args: AppAssembleArgs): Promise<Result<App, AssembleAppError>>;
+
+export function createApp(
+  arg: HTMLCanvasElement | AppAssembleArgs,
+  opts?: CreateAppOptions,
+  bundler?: BundlerOptions,
+): Promise<Result<App | ExecutionApp, CanvasAppError>> {
+  if ('tagName' in arg) {
+    return createAppFromCanvas(arg, opts, bundler);
+  }
+  return createAppFromAssemble(arg);
+}
+
+async function createAppFromCanvas(
+  canvas: HTMLCanvasElement,
+  opts: CreateAppOptions | undefined,
+  // feat-20260608-create-app-param-surface-trim / M2 / D-3: BundlerOptions is
+  // the host-injection SSOT (importTransport + shaderManifestUrl). Forwarded
+  // verbatim to createRenderer's third arg, so the engine reads
+  // shaderManifestUrl in its ShaderRegistry fallback (D-2 q5-A) and threads
+  // importTransport to AssetRegistry (AC-05 / R-4: keeps build-tool
+  // injection out of RendererOptions / CreateAppOptions).
+  bundler: BundlerOptions | undefined,
+): Promise<Result<App | ExecutionApp, CanvasAppError>> {
+  // M4: 4-step thin wrapper per plan-strategy D-5.
+  //
+  // Step 1: canvas-detached fail-fast guard (AC-08). isConnected returns
+  //   false when the canvas is not in the document tree, including freshly
+  //   document.createElement('canvas') without appendChild. Returning
+  //   Result.err here short-circuits before createRenderer fires off any
+  //   async adapter / device / shader work that would only fail later.
+  const maxCanvasPixelRatio = opts?.maxCanvasPixelRatio;
+  if (
+    maxCanvasPixelRatio !== undefined &&
+    (!Number.isFinite(maxCanvasPixelRatio) || maxCanvasPixelRatio <= 0)
+  ) {
+    return err(
+      makeAppError(
+        'app-invalid-canvas-pixel-ratio',
+        APP_EXPECTED['app-invalid-canvas-pixel-ratio'],
+        APP_ERROR_HINTS['app-invalid-canvas-pixel-ratio'],
+        { value: maxCanvasPixelRatio },
+      ),
+    );
+  }
+  if (!canvas.isConnected) {
+    return err(
+      makeAppError(
+        'app-canvas-detached',
+        'canvas.isConnected === true at createApp(canvas) entry',
+        'append the canvas to the document tree before calling createApp; or use the assemble entry createApp({ renderer, world }) when the host already manages canvas lifetime',
+        {},
+      ),
+    );
+  }
+
+  const executionOptions = opts?.execution;
+  const normalizedExecutionBootstrap =
+    executionOptions === undefined
+      ? undefined
+      : normalizeExecutionBootstrapUrl(executionOptions.bootstrap);
+  if (normalizedExecutionBootstrap?.ok === false) {
+    return err(normalizedExecutionBootstrap.error);
+  }
+
+  // The DOM canvas starts with a 300x150 drawing buffer even when CSS lays it
+  // out at a different size. Set the physical buffer before the renderer
+  // configures its swap chain; the same helper runs before each frame so a CSS
+  // resize remains visible to both rendering and camera policy.
+  syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio);
+
+  if (opts?.execution !== undefined && normalizedExecutionBootstrap?.ok === true) {
+    const realmBoundOption = [
+      ['features', opts.features],
+      ['plugins', opts.plugins],
+      ['rhi', opts.rhi],
+      ['rawDeviceForContextConfigure', opts.rawDeviceForContextConfigure],
+      ['drawSource', opts.drawSource],
+      ['membershipTiming', opts.membershipTiming],
+      ['assetCatalog', opts.assetCatalog],
+      ['assetDecoders', opts.assetDecoders],
+      ['bundler.importTransport', bundler?.importTransport],
+    ].find(([, value]) => value !== undefined)?.[0];
+    if (realmBoundOption !== undefined) {
+      return err(
+        makeAppError(
+          'app-execution-bootstrap-failed',
+          APP_EXPECTED['app-execution-bootstrap-failed'],
+          APP_ERROR_HINTS['app-execution-bootstrap-failed'],
+          {
+            phase: 'prepare',
+            moduleUrl: normalizedExecutionBootstrap.value,
+            cause: new TypeError(
+              `${realmBoundOption} must be constructed by the execution bootstrap module`,
+            ),
+          },
+        ),
+      );
+    }
+  }
+
+  let executionContext:
+    | {
+        readonly capabilities: import('./execution').ExecutionCapabilities;
+        readonly selection: import('./execution').ExecutionSelection;
+      }
+    | undefined;
+  let preparedExecutionBootstrap: PreparedExecutionBootstrap | undefined;
+  if (opts?.execution !== undefined && normalizedExecutionBootstrap?.ok === true) {
+    const executionOptions = opts.execution;
+    const capabilities = await probeExecutionCapabilities(canvas);
+    const selected = selectExecutionTier({
+      requestedTier: executionOptions.tier ?? 'auto',
+      capabilities,
+      sharedEvidencePassed: true,
+    });
+    if (!selected.ok) return err(selected.error);
+    executionContext = { capabilities, selection: selected.value };
+    if (selected.value.actualTier !== 'main-serial') {
+      return createWorkerExecutionApp({
+        canvas,
+        appOptions: opts,
+        syncCanvas: () => measureCanvasDrawingBuffer(canvas, maxCanvasPixelRatio),
+        ...(bundler !== undefined ? { bundler } : {}),
+        capabilities,
+        selection: selected.value,
+      });
+    }
+    const prepared = await prepareBootstrapEntry(
+      normalizedExecutionBootstrap.value,
+      executionOptions.bootstrapData,
+    );
+    if (!prepared.ok) return err(prepared.error);
+    preparedExecutionBootstrap = prepared.value;
+  }
+
+  // Step 2: createRenderer try/catch -> Result.err(EngineEnvironmentError)
+  //   (AC-01 / research section 2.2). createRenderer throws at
+  //   createRenderer.ts:400 / :429 (rhi pack load failure /
+  //   all WebGPU channels unavailable); we forward the original
+  //   EngineEnvironmentError instance verbatim to preserve the
+  //   .detail.webgpuError surface. RhiError instances raised mid-
+  //   construction are also forwarded -- the AppError | RhiError leg of
+  //   the union covers them. Any other unexpected throw is also
+  //   forwarded to keep the contract honest (AI users walk the union
+  //   discriminant rather than parse error.message strings).
+  // feat-20260608 / M2 / D-3: CreateAppOptions stops `extends RendererOptions`,
+  // so the two RHI escape hatches (rhi / rawDeviceForContextConfigure) are
+  // forwarded explicitly. Build a RendererOptions object out of just those
+  // fields when present; an empty {} keeps createRenderer on its default path.
+  const rendererOpts: import('@forgeax/engine-render').RendererOptions = {};
+  if (opts?.rhi !== undefined) {
+    Object.assign(rendererOpts, { rhi: opts.rhi });
+  }
+  if (opts?.rhiInstrumentation !== undefined) {
+    Object.assign(rendererOpts, { rhiInstrumentation: opts.rhiInstrumentation });
+  }
+  if (opts?.rawDeviceForContextConfigure !== undefined) {
+    Object.assign(rendererOpts, {
+      rawDeviceForContextConfigure: opts.rawDeviceForContextConfigure,
+    });
+  }
+  if (opts?.profiler !== undefined) {
+    Object.assign(rendererOpts, { profiler: opts.profiler });
+  }
+  if (opts?.membershipTiming !== undefined) {
+    Object.assign(rendererOpts, { membershipTiming: opts.membershipTiming });
+  }
+  const rendererFeatures = preparedExecutionBootstrap?.features ?? opts?.features;
+  if (rendererFeatures !== undefined) {
+    Object.assign(rendererOpts, { features: rendererFeatures });
+  }
+
+  // Optional RHI instrumentation is assembled once and forwarded through the
+  // typed Runtime -> Render seam. App keeps only the capture capability.
+  let rhiAttachment: RecorderAttachment | undefined;
+  let rhiCapture: RhiCapture | undefined;
+  let rhiDebugGlobal:
+    | {
+        captureFrame(options?: CaptureFrameOptions): ReturnType<RhiCapture['captureFrame']>;
+      }
+    | undefined;
+  const cleanupRhiDebugHost = (): void => {
+    const host = globalThis as { __forgeax?: typeof rhiDebugGlobal };
+    if (host.__forgeax === rhiDebugGlobal) delete host.__forgeax;
+    rhiDebugGlobal = undefined;
+    const attachment = rhiAttachment;
+    rhiAttachment = undefined;
+    if (attachment !== undefined) void attachment.dispose();
+  };
+  // Read FORGEAX_ENGINE_RHI_DEBUG from two sources (plan-strategy D-4):
+  //   - browser: import.meta.env, statically replaced by the
+  //     vite-plugin-rhi-debug `define` hook. The `typeof import.meta !==
+  //     'undefined'` prefix short-circuits under dawn-node, where import.meta
+  //     itself can be undefined (C5).
+  //   - dawn-node: globalThis.process.env (no vite define on the native path).
+  // resolveRhiDebugFlag (internal/rhi-debug-flag) is the SSOT for the `??`
+  // precedence; the source bags are computed inline here so the
+  // typeof-import.meta prefix stays at the call site. Keeps this file
+  // @types/node-free (engine-app ships ESM into both browser + dawn-node;
+  // same pattern as runtime/src/render-system-record.ts:isMeshSsboDevMode).
+  // Keep the Vite define key in a direct property expression. Wrapping
+  // `import.meta` in a structural cast hides the token from Vite's define
+  // pass, so production builds retain the debug-only dynamic chunks even when
+  // the Preview host explicitly sets the flag to `0`. Optional chaining keeps
+  // the package safe on the Dawn/Node path where `import.meta.env` is absent.
+  const importMetaEnv =
+    typeof import.meta !== 'undefined'
+      ? { FORGEAX_ENGINE_RHI_DEBUG: import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG }
+      : undefined;
+  // A browser production build must be able to erase the entire recorder
+  // branch. The `undefined` arm preserves Dawn/Node's process.env fallback;
+  // Vite replaces the direct property with `"0"` or `"1"`, making this outer
+  // guard a literal false/true before Rollup sees the debug-only imports.
+  const browserBuildRhiDebugFlag =
+    typeof import.meta !== 'undefined' ? import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG : undefined;
+  const processEnv = (globalThis as { process?: { env?: { FORGEAX_ENGINE_RHI_DEBUG?: string } } })
+    .process?.env;
+  const rhiDebugFlag = resolveRhiDebugFlag(importMetaEnv, processEnv);
+  const nav: { gpu?: unknown } | undefined =
+    typeof globalThis !== 'undefined'
+      ? (globalThis as { navigator?: { gpu?: unknown } }).navigator
+      : undefined;
+  const hasWebGPU = nav !== undefined && 'gpu' in nav && nav.gpu !== undefined;
+  if (
+    opts?.rhi === undefined &&
+    (browserBuildRhiDebugFlag === undefined || browserBuildRhiDebugFlag === '1') &&
+    rhiDebugFlag === '1'
+  ) {
+    const backend = hasWebGPU
+      ? await import('@forgeax/engine-rhi-webgpu')
+      : await import('@forgeax/engine-rhi-wgpu');
+    if (!hasWebGPU && 'ensureReady' in backend) await backend.ensureReady();
+    const pack = loadRhiPack(backend);
+    const debugModule = await import(/* @vite-ignore */ '@forgeax/engine-rhi-debug');
+    if (pack.createShaderModule === undefined) {
+      throw new Error('RHI debug capture requires the backend shader-module entry');
+    }
+    const createShaderModule: CreateShaderModuleFn = pack.createShaderModule;
+    const attached = debugModule.attachRecorder({
+      rhi: pack.rhi,
+      createShaderModule,
+    });
+    if (!attached.ok) throw new Error(attached.error.hint);
+    const attachment = attached.value;
+    rhiAttachment = attachment;
+    const capture = createRhiCapture(attachment);
+    rhiCapture = capture;
+
+    Object.assign(rendererOpts, {
+      rhi: attachment.backend.rhi,
+      rhiInstrumentation: createRhiInstrumentation(attachment),
+    });
+
+    rhiDebugGlobal = {
+      captureFrame: (options) => capture.captureFrame(options),
+    };
+    (globalThis as { __forgeax?: typeof rhiDebugGlobal }).__forgeax = rhiDebugGlobal;
+  }
+
+  const assetAssemblyResult = assembleAppAssetRuntime(opts?.assetCatalog, opts?.assetDecoders);
+  if (!assetAssemblyResult.ok) {
+    cleanupRhiDebugHost();
+    return err(assetAssemblyResult.error);
+  }
+  const assetAssembly = assetAssemblyResult.value;
+  let renderer: Renderer;
+  try {
+    renderer = await createRenderer(canvas, rendererOpts, {
+      ...bundler,
+      assetResolver: getAssetRegistryResolver(assetAssembly.registry),
+    });
+  } catch (e: unknown) {
+    cleanupRhiDebugHost();
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    if (e instanceof EngineEnvironmentError) {
+      return err(e);
+    }
+    // Unknown throw shapes (RhiError surfaced as throw, raw Error, ...).
+    // Re-raise to preserve fail-fast: the contract pins
+    // EngineEnvironmentError as the only construction-time failure
+    // shape; anything else is an engine bug, not an app-shell concern.
+    throw e;
+  }
+
+  // Step 2.4 decision: resolve whether the remote eval server should start
+  // (feat-20260629-inspector-two-layer-model M4 / w20). Dual-source gating
+  // mirrors the rhi-debug-flag pattern. The actual startServer call is
+  // deferred to after World creation (Step 3) because the server needs
+  // a live World reference.
+  const shouldStartRemote = resolveRemoteServeFlag(
+    typeof import.meta !== 'undefined'
+      ? (import.meta as { env?: { DEV?: boolean } }).env?.DEV
+      : undefined,
+    (globalThis as { process?: { env?: { FORGEAX_ENGINE_REMOTE_SERVE?: string } } }).process?.env,
+    typeof window !== 'undefined',
+  );
+
+  let debugDraw: DebugDraw | undefined;
+
+  // Step 3: new World() -- the canvas form owns world lifetime, in
+  // contrast to the assemble form where the host owns it.
+  const world = new World(opts?.time !== undefined ? { time: opts.time } : {});
+  // Step 3.1 (M2 plugin-system-unify / D-4): app-layer side effects that the
+  // plugins consume via pre-injected world resources.
+  //
+  // Animation keeps durable clip GUIDs in graph payloads. The canvas default
+  // plugin receives the renderer-owned GUID catalogue as a lookup bridge; it
+  // still projects payloads into this World through the animation owner.
+  // transform + animation system registration lives in the plugins (default set).
+
+  // A normal canvas app owns its browser acquisition. An embedding host that
+  // shares this physical canvas with another world supplies its routed view via
+  // opts.input; createApp then consumes that one boundary instead of attaching a
+  // second listener set. The host owns the supplied backend's lifetime.
+  const inputHandle =
+    opts?.input === undefined
+      ? attachInputAuto(canvas, {
+          ...(opts?.uiRoot ? { uiRoot: opts.uiRoot } : {}),
+          ...(opts?.pointerLockAllowed ? { pointerLockAllowed: opts.pointerLockAllowed } : {}),
+          ...(opts?.virtualJoysticks ? { virtualJoysticks: opts.virtualJoysticks } : {}),
+          ...(opts?.lockProvider ? { lockProvider: opts.lockProvider } : {}),
+        })
+      : undefined;
+  const inputBackend = opts?.input ?? inputHandle?.backend;
+  const userPlugins =
+    preparedExecutionBootstrap === undefined
+      ? (opts?.plugins ?? [])
+      : [
+          executionBootstrapHostPlugin({
+            ...(opts?.execution?.bootstrapPort === undefined
+              ? {}
+              : { port: opts.execution.bootstrapPort }),
+            setPointerLockAllowed: (allowed) => inputBackend?.setPointerLockAllowed?.(allowed),
+          }),
+          ...(preparedExecutionBootstrap.plugins ?? []),
+        ];
+  let pluginContext: Context;
+  try {
+    pluginContext = await createWorldContext(
+      world,
+      mainEngineProfile({
+        renderer,
+        assetAssembly,
+        animationPayloads: createAnimationPayloadLookup(renderer.assets),
+        ...(inputBackend === undefined ? {} : { input: inputBackend }),
+        ...(inputHandle === undefined ? {} : { inputDispose: inputHandle.cleanup }),
+        ...(opts?.inputMap === undefined ? {} : { inputMap: opts.inputMap }),
+        onDebugDrawReady: (value) => {
+          debugDraw = value;
+        },
+        extensions: [
+          rhiDebugHostPlugin(cleanupRhiDebugHost),
+          ...userPlugins,
+          canvasAspectPlugin(canvas, maxCanvasPixelRatio),
+        ],
+      }),
+    );
+  } catch (cause) {
+    cleanupRhiDebugHost();
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    return err(
+      makeAppError(
+        'app-plugin-activation-failed',
+        APP_EXPECTED['app-plugin-activation-failed'],
+        APP_ERROR_HINTS['app-plugin-activation-failed'],
+        { cause },
+      ),
+    );
+  }
+  const audioBackend = pluginContext.audio;
+
+  const executionControl = createLocalExecutionControl(
+    executionContext === undefined
+      ? {
+          ...createExecutionReport('main-serial', unavailableExecutionCapabilities('not required')),
+          actualTier: 'main-serial',
+          selectionReason: 'explicit-request',
+          sharedEvidencePassed: true,
+          engine: { realm: 'host', health: 'idle' },
+          world: {
+            identity: world.identity,
+            health: world.execution.health,
+            partialWrite: false,
+            retryable: true,
+          },
+        }
+      : {
+          ...createExecutionReport(
+            opts?.execution?.tier ?? 'auto',
+            executionContext.capabilities,
+            executionContext.selection,
+          ),
+          engine: { realm: 'host', health: 'idle' },
+          world: {
+            identity: world.identity,
+            health: world.execution.health,
+            partialWrite: false,
+            retryable: true,
+          },
+        },
+    {
+      ...(audioBackend === undefined ? {} : { audio: () => audioBackend.getState() }),
+      world: () => ({
+        identity: world.identity,
+        health: world.execution.health,
+        partialWrite: world.execution.fault?.partialWrite ?? false,
+        retryable: world.execution.fault?.retryable ?? true,
+      }),
+    },
+  );
+
+  // Step 3.3: Remote eval server auto-start (deferred from Step 2.4 so
+  // World is available). Dynamic import keeps @forgeax/engine-app free
+  // of static dep on @forgeax/engine-remote. Component reflection crosses
+  // this boundary as JSON-safe host data; app does not own any component.
+  const remoteHandle = shouldStartRemote
+    ? await startRemoteServer(
+        world,
+        renderer,
+        assetAssembly.registry,
+        rhiCapture,
+        opts?.profiler,
+        executionControl,
+      )
+    : undefined;
+  if (remoteHandle !== undefined) await pluginContext.plugin(remoteServerPlugin(remoteHandle));
+
+  const buildArgs: BuildAppArgs = {
+    renderer,
+    assets: assetAssembly.registry,
+    world,
+    pluginContext,
+    executionControl,
+    ...(inputBackend !== undefined ? { inputBackend } : {}),
+    ...(inputHandle === undefined
+      ? {}
+      : {
+          wireOnLockErrorDispatch: (dispatch: (err: AppError) => void) => {
+            inputHandle.setOnErrorDispatch(dispatch);
+          },
+        }),
+  };
+  if (audioBackend !== undefined) {
+    Object.assign(buildArgs, {
+      audioBackend,
+    });
+  }
+  if (opts?.silenceUnhandledErrors !== undefined) {
+    Object.assign(buildArgs, { silenceUnhandledErrors: opts.silenceUnhandledErrors });
+  }
+  // M2 / D-3: canvas form forwards the host-supplied draw-source pull.
+  if (opts?.drawSource !== undefined) {
+    Object.assign(buildArgs, { drawSource: opts.drawSource });
+  }
+  if (opts?.profiler !== undefined) {
+    Object.assign(buildArgs, { profiler: opts.profiler });
+  }
+  if (rhiCapture !== undefined) {
+    Object.assign(buildArgs, {
+      rhiCapture,
+      ...(rhiAttachment === undefined ? {} : { rhiAttachment }),
+    });
+  }
+  if (debugDraw !== undefined) {
+    Object.assign(buildArgs, { debugDraw });
+  }
+  if (remoteHandle !== undefined) {
+    Object.assign(buildArgs, { remoteHandle });
+  }
+
+  // The aspect-sync sidecar belongs to the canvas path because it owns the DOM
+  // canvas. It runs as an Update system so it shares World scheduling semantics.
+  const built = await buildApp(buildArgs);
+  if (!built.ok) {
+    await pluginContext.fiber.dispose();
+    return built;
+  }
+  if (built.ok) {
+    // DEV-only browser remote bridge (remote-live). A browser cannot host the
+    // Node WS server that @forgeax/engine-remote/server needs, so the running
+    // engine would be unreachable from a CLI in a real dev browser. Instead the
+    // page dials OUT to a loopback relay and runs the ws-free eval core against
+    // the live world/renderer/assets/rhiCapture.
+    //
+    // OPT-IN via VITE_FORGEAX_ENGINE_BRIDGE=1 (set by scripts/dev-live.mjs), NOT
+    // on-by-default: a page that dials a relay which is not running makes the
+    // BROWSER itself log "WebSocket connection failed" to the console — noise a
+    // JS catch cannot suppress — which trips every zero-console-error browser
+    // smoke (collectathon / hello-*). So a plain `pnpm --filter <app> dev` (and
+    // CI) stays silent; only dev-live.mjs, which also launches the relay, turns
+    // it on. Production DCE's the whole block (import.meta.env.DEV === false).
+    // Additive: the Node startServer path above and app.remote are untouched.
+    if (
+      typeof import.meta !== 'undefined' &&
+      (import.meta as { env?: { DEV?: boolean; VITE_FORGEAX_ENGINE_BRIDGE?: string } }).env?.DEV ===
+        true &&
+      (import.meta as { env?: { VITE_FORGEAX_ENGINE_BRIDGE?: string } }).env
+        ?.VITE_FORGEAX_ENGINE_BRIDGE === '1'
+    ) {
+      const bridgePort =
+        (import.meta as { env?: { VITE_FORGEAX_ENGINE_BRIDGE_PORT?: string } }).env
+          ?.VITE_FORGEAX_ENGINE_BRIDGE_PORT ?? '5733';
+      await pluginContext.plugin({
+        name: 'browser-remote-bridge',
+        inject: ['world', 'renderer', 'assetRegistry'],
+        async apply(ctx) {
+          if (ctx.renderer === undefined || ctx.assetRegistry === undefined) {
+            throw new Error('browser remote bridge requires renderer and assetRegistry services');
+          }
+          try {
+            const bridge = await import('./internal/browser-remote-bridge');
+            const teardown = await bridge.installBrowserRemoteBridge({
+              world: ctx.world,
+              renderer: ctx.renderer,
+              assets: ctx.assetRegistry,
+              runtimeModule: engineRuntimeModule,
+              ...(rhiCapture !== undefined ? { rhiCapture } : {}),
+              ...(opts?.profiler !== undefined ? { profiler: opts.profiler } : {}),
+              execution: built.value.execution,
+              port: bridgePort,
+            });
+            ctx.effect(() => teardown, 'remote/browser-bridge');
+          } catch {
+            // The optional live bridge does not make App creation fail.
+          }
+        },
+      });
+    }
+  }
+  return built;
+}
+
+/**
+ * Synchronize a DOM canvas drawing buffer with its CSS size and device pixel
+ * ratio. Detached or zero-sized hosts are left untouched so a hidden canvas
+ * cannot be converted into a 1x1 render target accidentally.
+ */
+export function syncCanvasDrawingBuffer(
+  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
+    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
+  },
+  maxCanvasPixelRatio?: number,
+): CanvasDrawingBufferSize {
+  const size = resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio);
+  if (size === undefined) return { width: canvas.width, height: canvas.height };
+  if (canvas.width !== size.width) canvas.width = size.width;
+  if (canvas.height !== size.height) canvas.height = size.height;
+  return size;
+}
+
+/**
+ * Measure the next effective drawing buffer without writing the DOM canvas.
+ * This is the Worker host path because transferControlToOffscreen makes the
+ * HTML canvas dimensions immutable; the Worker owns the transferred surface.
+ */
+export function measureCanvasDrawingBuffer(
+  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
+    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
+  },
+  maxCanvasPixelRatio?: number,
+): CanvasDrawingBufferSize {
+  return (
+    resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio) ?? {
+      width: canvas.width,
+      height: canvas.height,
+    }
+  );
+}
+
+function resolveCanvasDrawingBufferSize(
+  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
+    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
+  },
+  maxCanvasPixelRatio?: number,
+): CanvasDrawingBufferSize | undefined {
+  if (
+    !Number.isFinite(canvas.clientWidth) ||
+    !Number.isFinite(canvas.clientHeight) ||
+    canvas.clientWidth <= 0 ||
+    canvas.clientHeight <= 0
+  )
+    return undefined;
+  // An intrinsic canvas with no CSS dimensions already has an explicit
+  // drawing-buffer contract. `clientWidth` mirrors `width` for this shape;
+  // multiplying it by DPR would change the caller's requested pixel size and
+  // can feed that new width back as the next layout measurement. CSS-sized
+  // canvases take the DPR path below (including stylesheet-sized canvases
+  // whose layout width differs from the initial intrinsic width).
+  const hasExplicitCssSize =
+    (canvas.style?.width ?? '') !== '' || (canvas.style?.height ?? '') !== '';
+  if (
+    !hasExplicitCssSize &&
+    canvas.clientWidth === canvas.width &&
+    canvas.clientHeight === canvas.height
+  ) {
+    return { width: canvas.width, height: canvas.height };
+  }
+  const devicePixelRatio = Math.max(1, globalThis.devicePixelRatio || 1);
+  const dpr =
+    maxCanvasPixelRatio === undefined ||
+    !Number.isFinite(maxCanvasPixelRatio) ||
+    maxCanvasPixelRatio <= 0
+      ? devicePixelRatio
+      : Math.min(devicePixelRatio, maxCanvasPixelRatio);
+  const previous = syncedCanvasSizes.get(canvas);
+  const drawingBufferIsTheLayoutMeasurement =
+    previous !== undefined &&
+    canvas.width === previous.drawingWidth &&
+    canvas.height === previous.drawingHeight &&
+    canvas.clientWidth === previous.drawingWidth &&
+    canvas.clientHeight === previous.drawingHeight;
+  const cssWidth = drawingBufferIsTheLayoutMeasurement ? previous.cssWidth : canvas.clientWidth;
+  const cssHeight = drawingBufferIsTheLayoutMeasurement ? previous.cssHeight : canvas.clientHeight;
+  const width = Math.max(1, Math.round(cssWidth * dpr));
+  const height = Math.max(1, Math.round(cssHeight * dpr));
+  syncedCanvasSizes.set(canvas, {
+    cssWidth,
+    cssHeight,
+    drawingWidth: width,
+    drawingHeight: height,
+  });
+  return { width, height };
+}
+
+const syncedCanvasSizes = new WeakMap<
+  object,
+  {
+    readonly cssWidth: number;
+    readonly cssHeight: number;
+    readonly drawingWidth: number;
+    readonly drawingHeight: number;
+  }
+>();
+
+async function startRemoteServer(
+  world: World,
+  renderer: Renderer,
+  assets: AssetRegistry,
+  rhiCapture: RhiCapture | undefined,
+  profiler: import('@forgeax/engine-profiler').Profiler | undefined,
+  execution: ExecutionControl,
+): Promise<{ readonly port: number; close(): Promise<void> } | undefined> {
+  try {
+    const remoteServerMod = (await import(
+      /* @vite-ignore */ '@forgeax/engine-remote/server'
+    )) as unknown as {
+      startServer: (opts: {
+        port: number;
+        host?: string;
+        world: unknown;
+        renderer?: unknown;
+        assets?: unknown;
+        rhiCapture?: unknown;
+        introspection?: readonly unknown[];
+        profiler?: unknown;
+        execution?: unknown;
+      }) => Promise<{
+        ok: boolean;
+        value?: { port: number; close(): Promise<void> };
+      }>;
+    };
+    const serverResult = await remoteServerMod.startServer({
+      port: 0,
+      host: '127.0.0.1',
+      world,
+      renderer,
+      assets,
+      introspection: projectComponentIntrospection(world.components.entries()),
+      ...(rhiCapture !== undefined ? { rhiCapture } : {}),
+      ...(profiler !== undefined ? { profiler } : {}),
+      execution,
+    });
+    if (serverResult.ok && serverResult.value !== undefined) {
+      return { port: serverResult.value.port, close: serverResult.value.close };
+    }
+  } catch (_error) {
+    // Dynamic import or server start failed; the app continues without remote.
+  }
+  return undefined;
+}
+
+async function createAppFromAssemble(
+  args: AppAssembleArgs,
+): Promise<Result<App, AssembleAppError>> {
+  const assetAssemblyResult = assembleAppAssetRuntime(args.assetCatalog, args.assetDecoders);
+  if (!assetAssemblyResult.ok) return err(assetAssemblyResult.error);
+  const assetAssembly = assetAssemblyResult.value;
+  let pluginContext: Context;
+  try {
+    pluginContext = await createWorldContext(
+      args.world,
+      assembledEngineProfile({
+        renderer: args.renderer,
+        assetAssembly,
+        extensions: args.plugins ?? [],
+      }),
+    );
+  } catch (cause) {
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    return err(
+      makeAppError(
+        'app-plugin-activation-failed',
+        APP_EXPECTED['app-plugin-activation-failed'],
+        APP_ERROR_HINTS['app-plugin-activation-failed'],
+        { cause },
+      ),
+    );
+  }
+
+  const shouldStartRemote = resolveRemoteServeFlag(
+    undefined,
+    (globalThis as { process?: { env?: { FORGEAX_ENGINE_REMOTE_SERVE?: string } } }).process?.env,
+  );
+  const assembledAudioBackend = pluginContext.audio;
+  const executionControl = createLocalExecutionControl(
+    {
+      ...createExecutionReport('main-serial', unavailableExecutionCapabilities('not required')),
+      actualTier: 'main-serial',
+      selectionReason: 'explicit-request',
+      sharedEvidencePassed: true,
+      engine: { realm: 'host', health: 'idle' },
+      world: {
+        identity: args.world.identity,
+        health: args.world.execution.health,
+        partialWrite: false,
+        retryable: true,
+      },
+    },
+    {
+      ...(assembledAudioBackend === undefined
+        ? {}
+        : { audio: () => assembledAudioBackend.getState() }),
+      world: () => ({
+        identity: args.world.identity,
+        health: args.world.execution.health,
+        partialWrite: args.world.execution.fault?.partialWrite ?? false,
+        retryable: args.world.execution.fault?.retryable ?? true,
+      }),
+    },
+  );
+  const remoteHandle = shouldStartRemote
+    ? await startRemoteServer(
+        args.world,
+        args.renderer,
+        assetAssembly.registry,
+        undefined,
+        args.profiler,
+        executionControl,
+      )
+    : undefined;
+  if (remoteHandle !== undefined) await pluginContext.plugin(remoteServerPlugin(remoteHandle));
+
+  const buildArgs: BuildAppArgs = {
+    renderer: args.renderer,
+    assets: assetAssembly.registry,
+    world: args.world,
+    pluginContext,
+    executionControl,
+    ...(remoteHandle !== undefined ? { remoteHandle } : {}),
+  };
+
+  const assembledInputBackend = pluginContext.input;
+  if (assembledInputBackend !== undefined) {
+    Object.assign(buildArgs, {
+      inputBackend: assembledInputBackend,
+    });
+  }
+  if (assembledAudioBackend !== undefined) {
+    Object.assign(buildArgs, {
+      audioBackend: assembledAudioBackend,
+    });
+  }
+  if (args.silenceUnhandledErrors !== undefined) {
+    Object.assign(buildArgs, { silenceUnhandledErrors: args.silenceUnhandledErrors });
+  }
+  // M2 / D-3: assemble form forwards the host-supplied draw-source pull.
+  if (args.drawSource !== undefined) {
+    Object.assign(buildArgs, { drawSource: args.drawSource });
+  }
+  if (args.profiler !== undefined) {
+    Object.assign(buildArgs, { profiler: args.profiler });
+  }
+  const built = await buildApp(buildArgs);
+  if (!built.ok) await pluginContext.fiber.dispose();
+  return built;
+}
+
+interface BuildAppArgs {
+  readonly renderer: Renderer;
+  readonly assets: AssetRegistry;
+  readonly world: World;
+  readonly pluginContext: Context;
+  readonly inputBackend?: InputBackend;
+  /**
+   * M2 D-4: callback that buildApp calls after creating the ErrorFanoutRegistry
+   * dispatch function. The input handle's onLockError callback needs the dispatch
+   * function to fan out 'app-pointer-lock-failed' errors, but the dispatch function
+   * is created inside buildApp (after the input handle is already constructed).
+   * This callback bridges the gap.
+   */
+  readonly wireOnLockErrorDispatch?: (dispatch: (err: AppError) => void) => void;
+  readonly audioBackend?: AudioBackend;
+  readonly silenceUnhandledErrors?: boolean;
+  /** M4: host-owned RHI capture capability attached to the app surface. */
+  readonly rhiCapture?: RhiCapture;
+  /** Internal attachment used to bind capture to this App's frame authority. */
+  readonly rhiAttachment?: RecorderAttachment;
+  /** feat-20260615 debug-draw M5: DebugDraw instance created by createDebugDrawOnReady. */
+  readonly debugDraw?: DebugDraw;
+  /** feat-20260629 M4 / w20: remote eval server handle from createAppFromCanvas. */
+  readonly remoteHandle?: { readonly port: number; close(): Promise<void> };
+  /**
+   * feat-20260709-editor-world-partition-editorworld-super-composite / M2 / D-3:
+   * per-frame draw-source pull forwarded verbatim into the frame-loop. Absent =>
+   * the allocation-free primary-World path. Both createApp forms (canvas + assemble) forward
+   * it from their respective options object.
+   */
+  readonly drawSource?: () =>
+    | {
+        worlds: readonly import('@forgeax/engine-ecs').World[];
+        cameraOwner: number;
+        resourceOwner: number;
+      }
+    | undefined;
+  readonly profiler?: import('@forgeax/engine-profiler').Profiler;
+  readonly executionControl?: import('./execution/control').LocalExecutionControl;
+}
+
+/**
+ * Internal builder shared by both overloads. Wires the frame-loop +
+ * listener-registry onError and returns the App handle. Effectful ownership
+ * has already moved into pluginContext before this boundary runs.
+ */
+async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiError>> {
+  const {
+    renderer,
+    assets,
+    world,
+    pluginContext,
+    inputBackend,
+    audioBackend,
+    silenceUnhandledErrors,
+    rhiCapture,
+    rhiAttachment,
+    debugDraw,
+    remoteHandle,
+    profiler,
+  } = args;
+
+  // Physics is a Context service; the App exposes the active provider without
+  // storing a second mutable slot.
+  function readPhysicsWorld():
+    | import('@forgeax/engine-physics').PhysicsWorld
+    | import('@forgeax/engine-physics').PhysicsWorld2D
+    | undefined {
+    return pluginContext.physics;
+  }
+  // M4 (w11): listener registry replaces the M3 inline Set so console.error
+  // fallback + duplicate-add no-op + unsubscribe handle behaviour matches
+  // packages/runtime/src/createRenderer.ts:532-566 LostListenerRegistry
+  // (plan-strategy D-9). silenceUnhandledErrors threads through verbatim.
+  const fanout = new ErrorFanoutRegistry(
+    silenceUnhandledErrors !== undefined ? { silenceUnhandledErrors } : {},
+  );
+  const execution =
+    args.executionControl ??
+    createLocalExecutionControl(
+      {
+        ...createExecutionReport('main-serial', unavailableExecutionCapabilities('not required')),
+        actualTier: 'main-serial',
+        selectionReason: 'explicit-request',
+        sharedEvidencePassed: true,
+        engine: { realm: 'host', health: 'idle' },
+        world: {
+          identity: world.identity,
+          health: world.execution.health,
+          partialWrite: world.execution.fault?.partialWrite ?? false,
+          retryable: world.execution.fault?.retryable ?? true,
+        },
+      },
+      {
+        ...(audioBackend === undefined ? {} : { audio: () => audioBackend.getState() }),
+        world: () => ({
+          identity: world.identity,
+          health: world.execution.health,
+          partialWrite: world.execution.fault?.partialWrite ?? false,
+          retryable: world.execution.fault?.retryable ?? true,
+        }),
+      },
+    );
+
+  function dispatch(e: AppDispatchError): void {
+    fanout.fire(e);
+  }
+
+  // M2 D-4: wire the input handle's onLockError callback to the error fan-out.
+  // The dispatch function is created here; the input handle was created earlier
+  // in createAppFromCanvas and passed to buildApp with a wireOnLockErrorDispatch
+  // callback that calls setOnErrorDispatch on the handle.
+  if (args.wireOnLockErrorDispatch) {
+    args.wireOnLockErrorDispatch(dispatch);
+  }
+
+  const loopOpts: Parameters<typeof createFrameLoop>[0] = {
+    world,
+    renderer,
+    onError: dispatch,
+  };
+  // M2 / D-3: forward the optional draw-source pull into the frame-loop. Absent
+  // => the loop keeps the allocation-free primary-World draw path.
+  if (args.drawSource !== undefined) {
+    Object.assign(loopOpts, { drawSource: args.drawSource });
+  }
+  if (profiler !== undefined) {
+    Object.assign(loopOpts, { profiler });
+  }
+  const loop = createFrameLoop(loopOpts);
+
+  if (rhiCapture !== undefined && rhiAttachment !== undefined) {
+    bindRhiCaptureFrameDriver(rhiCapture, {
+      getState: () => loop.getState(),
+      pause: () => {
+        const result = loop.pause();
+        if (result.ok) execution.setEngineHealth('idle');
+        return result;
+      },
+      resume: () => {
+        const result = loop.resume();
+        if (result.ok) execution.setEngineHealth('running');
+        return result;
+      },
+      stepFrame: (deltaSeconds) => loop.stepFrame(deltaSeconds),
+    });
+  }
+
+  let lastError: AppDispatchError | undefined;
+
+  // M4 (w13) device-lost internal subscription. R-1 timing contract:
+  // app.start() arms the rAF handle BEFORE this listener subscribes, so
+  // a synchronous late-attach replay of a persisted device-lost event
+  // (LostListenerRegistry replay -- runtime/src/renderer.ts:337-345)
+  // hits a frame-loop with a real rAF handle to cancel (M2 setStopped
+  // tolerates pendingFrameId === 0 as a no-op so even pre-rAF replays
+  // do not NPE). The subscription remains active across pause / resume;
+  // unsubscribe runs only on stop / disposal (charter P3:
+  // device-lost is a terminal lifecycle signal, not a transient blip).
+  let rendererUnsubscribe: (() => void) | undefined;
+  let resumeAfterSurfaceRestore = false;
+
+  function subscribeRendererErrors(): void {
+    if (rendererUnsubscribe !== undefined) {
+      return;
+    }
+    rendererUnsubscribe = renderer.onError((e: RendererError) => {
+      // D-3: device-lost stays in RhiError 18-member union; AppError does
+      // NOT add 'app-device-lost'. The host onError listener receives the
+      // error verbatim through the fanout dispatch below.
+      //
+      // feat-20260531-skybox-env-background F-1: the renderer onError channel
+      // now fans out RhiError | RuntimeError (e.g. 'equirect-projection-failed').
+      // Device loss is recoverable at the Renderer boundary: the frame-loop
+      // heartbeat remains armed and freezes World/update work until the host
+      // explicitly calls `renderer.recover()`. Stopping the loop here would
+      // leave a successful recovery
+      // with no frame submitter.
+      //
+      // Note: we discriminate by .code rather than instanceof RhiError
+      // because the listener may be invoked across module boundaries
+      // (re-export from @forgeax/engine-runtime vs direct
+      // @forgeax/engine-rhi/errors import). Bundler dedup is not
+      // guaranteed on subpath exports, so an instanceof check is a
+      // false-negative trap. The union .code type still provides static
+      // safety on .code access.
+      if (e?.code === 'device-lost') {
+        lastError = e;
+      }
+      // Always fan out to host listeners (D-2 last bullet: device-lost
+      // error is forwarded as-is to host onError listener so the host
+      // can decide whether to rebuild the renderer).
+      dispatch(e);
+    });
+  }
+
+  function unsubscribeRendererErrors(): void {
+    if (rendererUnsubscribe !== undefined) {
+      rendererUnsubscribe();
+      rendererUnsubscribe = undefined;
+    }
+  }
+
+  const stub: App = {
+    renderer,
+    assets,
+    world,
+    execution,
+    async releaseSurfacePreserveWorld(): Promise<Result<void, RhiError>> {
+      if (loop.getState() === 'running') {
+        const paused = loop.pause();
+        if (!paused.ok) {
+          return err(
+            new RhiError({
+              code: 'rhi-not-available',
+              expected: 'running App pauses before releasing its presentation surface',
+              hint: paused.error.hint,
+            }),
+          );
+        }
+        resumeAfterSurfaceRestore = true;
+        execution.setEngineHealth('idle');
+      }
+      // A surface handoff can be requested by an Update system while the
+      // current frame is still in progress. Let that frame reach renderer.draw
+      // before unconfiguring the surface; pause() only cancels the next rAF.
+      await Promise.resolve();
+      const released = renderer.releaseSurface();
+      if (!released.ok && resumeAfterSurfaceRestore) {
+        loop.resume();
+        resumeAfterSurfaceRestore = false;
+        execution.setEngineHealth('running');
+      }
+      return released.ok ? ok(undefined) : err(released.error);
+    },
+    async restoreSurface(): Promise<Result<void, RhiError>> {
+      const restored = renderer.restoreSurface();
+      if (!restored.ok) return err(restored.error);
+      if (resumeAfterSurfaceRestore) {
+        const resumed = loop.resume();
+        if (!resumed.ok) {
+          return err(
+            new RhiError({
+              code: 'rhi-not-available',
+              expected: 'paused App resumes after restoring its presentation surface',
+              hint: resumed.error.hint,
+            }),
+          );
+        }
+        resumeAfterSurfaceRestore = false;
+        execution.setEngineHealth('running');
+      }
+      return ok(undefined);
+    },
+    pluginContext,
+    ...(inputBackend !== undefined ? { input: inputBackend } : {}),
+    ...(audioBackend !== undefined ? { audio: audioBackend } : {}),
+    get physics():
+      | import('@forgeax/engine-physics').PhysicsWorld
+      | import('@forgeax/engine-physics').PhysicsWorld2D
+      | undefined {
+      return readPhysicsWorld();
+    },
+    start(): Result<void, AppError> {
+      // R-1: arm the rAF handle FIRST (loop.start schedules raf(tick))
+      // and only THEN subscribe to renderer.onError. If the renderer
+      // late-attach replays a persisted device-lost event during the
+      // subscribe call, the loop is already armed and can retain the error.
+      const r = loop.start();
+      if (r.ok) {
+        execution.setEngineHealth('running');
+        subscribeRendererErrors();
+      }
+      return r;
+    },
+    stop(): Result<void, AppError> {
+      const r = loop.stop();
+      if (r.ok) execution.setEngineHealth('stopped');
+      unsubscribeRendererErrors();
+      return r;
+    },
+    async dispose(): Promise<Result<void, AppError>> {
+      const state = loop.getState();
+      if (state === 'running' || state === 'paused') loop.stop();
+      else if (state !== 'stopped') loop.setStopped();
+      await pluginContext.fiber.dispose();
+      unsubscribeRendererErrors();
+      execution.setEngineHealth('stopped');
+      return ok(undefined);
+    },
+    pause(): Result<void, AppError> {
+      const r = loop.pause();
+      if (r.ok) execution.setEngineHealth('idle');
+      return r;
+    },
+    resume(): Result<void, AppError> {
+      const r = loop.resume();
+      if (r.ok) execution.setEngineHealth('running');
+      return r;
+    },
+    stepFrame(deltaSeconds): Result<void, AppDispatchError> {
+      return loop.stepFrame(deltaSeconds);
+    },
+    onError(cb: (e: AppDispatchError) => void): () => void {
+      return fanout.add(cb);
+    },
+    setDrawSource(drawSource): void {
+      loop.setDrawSource(drawSource);
+    },
+    /**
+     * Most recent device-loss error retained for host self-inspection.
+     */
+    get lastError(): AppDispatchError | undefined {
+      return lastError;
+    },
+    ...(rhiCapture !== undefined ? { rhiCapture } : {}),
+    ...(debugDraw !== undefined ? { debugDraw } : {}),
+    ...(remoteHandle !== undefined ? { remote: remoteHandle } : {}),
+  };
+
+  // Readiness barrier (charter Fail Fast). createRenderer resolves before
+  // its `ready` Promise (manifest -> pipeline -> asset upload three-step
+  // chain) settles, so a host that calls app.start() immediately would arm
+  // the rAF loop while renderer.draw(world) still returns 'rhi-not-available'
+  // every frame -- a startup race that surfaces as intermittent console.error
+  // spam on cold loads. Awaiting ready here makes "App ready" mean "renderer
+  // ready": start() never observes a pre-ready frame, and a genuine pipeline
+  // build failure fail-fasts as Result.err(rhiError) (caught by the canonical
+  // `if (!app.ok) reportError(app.error)` takeoff) instead of per-frame noise.
+  // The audio tick system is registered by audioPlugin before buildApp as the 'audio-tick'
+  // world system, so there is no buildApp-side Update system anymore.
+  const readyResult = await renderer.ready;
+  if (!readyResult.ok) {
+    return err(readyResult.error);
+  }
+
+  return ok(stub);
+}