@forgeax/engine-app 0.1.2

package/dist/index.mjs

@@ -0,0 +1,3985 @@
+import { Update, World, createWorldContext, componentDefinition } from '@forgeax/engine-ecs';
+export { Context } from '@forgeax/engine-plugin';
+import * as engineRuntimeModule from '@forgeax/engine-runtime';
+import { defaultAssetDecoderContributions, createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { err, ok } from '@forgeax/engine-types';
+import { createAssetRegistry, createCatalogSource } from '@forgeax/engine-assets-runtime';
+import { getAssetRegistryResolver } from '@forgeax/engine-assets-runtime/internal';
+import { loadRhiPack, createDebugDrawOnReady, releaseDebugDraw } from '@forgeax/engine-render/internal';
+import { RhiError } from '@forgeax/engine-rhi';
+import { Camera, perspective, ownedRendererPlugin, renderComponentsPlugin, rendererPlugin, CAMERA_PROJECTION_PERSPECTIVE } from '@forgeax/engine-render';
+import { createHostAudioConsumer } from '@forgeax/engine-audio-webaudio';
+import { INPUT_BACKEND_KEY, InputSet, InputFrameStartScan, attachBrowserInputBackend, inputBackendPlugin, ownedInputBackendPlugin, INPUT_MAP_KEY } from '@forgeax/engine-input';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { animationPayloadsPlugin, animationRuntimePlugin } from '@forgeax/engine-animation';
+import { Transform, scenePlugin } from '@forgeax/engine-scene';
+import { statePlugin } from '@forgeax/engine-state';
+import { decodeTape, openReplay, decodeToRgba8, attachRecorder, buildTapeIndex, createRhiDebugError } from '@forgeax/engine-rhi-debug';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { isSerializableValue, createPreviewArtifactManifest, validatePreviewArtifactManifest, createArtifactRef, snapshotStaleError } from '@forgeax/engine-tool-runtime';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/internal/ecs-import.ts
+function isRecord2(value) {
+  return value !== null && typeof value === "object";
+}
+function projectEcsPublicModule(value) {
+  if (!isRecord2(value)) return {};
+  const projected = {};
+  for (const symbol of ECS_PUBLIC_SYMBOLS) {
+    if (symbol in value) projected[symbol] = value[symbol];
+  }
+  return projected;
+}
+function createEcsImportModule(importModule) {
+  return async (specifier) => {
+    const moduleValue = await importModule(specifier);
+    return specifier === ECS_MODULE_SPECIFIER ? projectEcsPublicModule(moduleValue) : moduleValue;
+  };
+}
+var ECS_MODULE_SPECIFIER, ECS_PUBLIC_SYMBOLS;
+var init_ecs_import = __esm({
+  "src/internal/ecs-import.ts"() {
+    ECS_MODULE_SPECIFIER = "@forgeax/engine-ecs";
+    ECS_PUBLIC_SYMBOLS = Object.freeze([
+      "World",
+      "Entity",
+      "Update",
+      "FixedUpdate",
+      "Time",
+      "FixedTime"
+    ]);
+  }
+});
+
+// src/internal/browser-remote-bridge.ts
+var browser_remote_bridge_exports = {};
+__export(browser_remote_bridge_exports, {
+  installBrowserRemoteBridge: () => installBrowserRemoteBridge
+});
+function canonicalRuntimeModule(moduleValue, world) {
+  if (moduleValue === null || typeof moduleValue !== "object") return moduleValue;
+  const componentsByName = /* @__PURE__ */ new Map();
+  for (const [name, component] of world.components.entries()) {
+    if (!componentsByName.has(name)) componentsByName.set(name, component);
+  }
+  const projected = { ...moduleValue };
+  for (const [key, value] of Object.entries(projected)) {
+    if (value === null || typeof value !== "object" || !("name" in value)) continue;
+    const canonical = componentsByName.get(value.name);
+    if (canonical !== void 0) projected[key] = canonical;
+  }
+  return projected;
+}
+function serializeError(error) {
+  if (error !== null && typeof error === "object") {
+    const e = error;
+    const out = {
+      code: typeof e.code === "string" ? e.code : "script-runtime-error"
+    };
+    if (typeof e.expected === "string") out.expected = e.expected;
+    if (typeof e.hint === "string") out.hint = e.hint;
+    if (e.detail !== void 0) out.detail = e.detail;
+    if (out.hint === void 0 && typeof e.message === "string") out.hint = e.message;
+    return out;
+  }
+  return { code: "script-runtime-error", hint: String(error) };
+}
+async function installBrowserRemoteBridge(deps) {
+  const { world, renderer, assets, rhiCapture, profiler, execution, port } = deps;
+  const mod = await import(
+    /* @vite-ignore */
+    '@forgeax/engine-remote/execute'
+  );
+  const executeScript = mod.executeScript;
+  const importModule = createEcsImportModule((specifier) => {
+    if (specifier === "@forgeax/engine-runtime")
+      return Promise.resolve(canonicalRuntimeModule(deps.runtimeModule, world));
+    const browserSpecifier = specifier.startsWith("@") ? `/@id/${specifier}` : specifier;
+    return import(
+      /* @vite-ignore */
+      browserSpecifier
+    ).then(
+      (moduleValue) => canonicalRuntimeModule(moduleValue, world)
+    );
+  });
+  let ws = null;
+  let backoff = 1e3;
+  let stopped = false;
+  const evalQueue = [];
+  const drainEvalQueue = () => {
+    if (evalQueue.length === 0) return;
+    const jobs = evalQueue.splice(0, evalQueue.length);
+    for (const job of jobs) {
+      const reply = (payload) => {
+        try {
+          ws?.send(JSON.stringify({ type: "result", id: job.id, payload }));
+        } catch {
+        }
+      };
+      void (async () => {
+        let res;
+        try {
+          res = await executeScript(job.code, {
+            world,
+            renderer,
+            assets,
+            rhiCapture,
+            profiler,
+            execution,
+            importModule
+          });
+        } catch (e) {
+          reply({
+            ok: false,
+            error: { code: "BRIDGE_EVAL_THREW", hint: String(e?.message ?? e) }
+          });
+          return;
+        }
+        const envelope = res.ok ? { ok: true, value: res.value } : { ok: false, error: serializeError(res.error) };
+        try {
+          JSON.stringify(envelope);
+          reply(envelope);
+        } catch {
+          reply({ ok: true, value: "[unserializable value \u2014 inspect in the live window]" });
+        }
+      })();
+    }
+  };
+  world.addSystem(Update, {
+    name: "browser-remote-bridge-drain-eval-queue",
+    queries: [],
+    fn: drainEvalQueue
+  }).unwrap();
+  const connect = () => {
+    if (stopped) return;
+    try {
+      ws = new WebSocket(`ws://127.0.0.1:${port}/bridge`);
+    } catch {
+      return;
+    }
+    ws.addEventListener("open", () => {
+      backoff = 1e3;
+    });
+    ws.addEventListener("message", (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(typeof ev.data === "string" ? ev.data : "");
+      } catch {
+        return;
+      }
+      if (msg?.type !== "eval" || typeof msg.id !== "number" || typeof msg.code !== "string")
+        return;
+      evalQueue.push({ id: msg.id, code: msg.code });
+    });
+    const retry = () => {
+      ws = null;
+      if (stopped) return;
+      setTimeout(connect, backoff);
+      backoff = Math.min(backoff * 2, 15e3);
+    };
+    ws.addEventListener("close", retry);
+    ws.addEventListener("error", () => {
+      try {
+        ws?.close();
+      } catch {
+      }
+    });
+  };
+  connect();
+  const teardown = () => {
+    if (stopped) return;
+    stopped = true;
+    world.removeSystem(Update, "browser-remote-bridge-drain-eval-queue");
+    const s = ws;
+    ws = null;
+    if (s) {
+      try {
+        s.onclose = null;
+        s.close();
+      } catch {
+      }
+    }
+  };
+  const hot = import.meta.hot;
+  if (hot) hot.dispose(teardown);
+  return teardown;
+}
+var init_browser_remote_bridge = __esm({
+  "src/internal/browser-remote-bridge.ts"() {
+    init_ecs_import();
+  }
+});
+function assembleAssetRuntime(registry, contributions) {
+  const leases = [];
+  const overrides = new Set(contributions.map((contribution) => contribution.kind.kind));
+  const defaults = defaultAssetDecoderContributions ?? [];
+  const assembledContributions = [
+    ...defaults.filter((contribution) => !overrides.has(contribution.kind.kind)),
+    ...contributions
+  ];
+  try {
+    const installedKinds = /* @__PURE__ */ new Set();
+    for (const contribution of assembledContributions) {
+      if (installedKinds.has(contribution.kind.kind)) {
+        throw new TypeError(`duplicate decoder kind "${contribution.kind.kind}"`);
+      }
+      installedKinds.add(contribution.kind.kind);
+      leases.push(
+        registry.installDecoder(
+          contribution.kind,
+          contribution.decoder
+        )
+      );
+    }
+  } catch (cause) {
+    for (const lease of leases) lease.dispose();
+    const failed = assembledContributions[leases.length];
+    return err({
+      code: "asset-assembly-failed",
+      expected: "each owner decoder contribution to install exactly once in the realm registry",
+      hint: "remove the conflicting owner contribution and assemble the current realm again",
+      detail: { kind: failed?.kind.kind ?? "unknown", cause }
+    });
+  }
+  let disposed = false;
+  return ok({
+    registry,
+    leases: Object.freeze([...leases]),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const lease of leases) lease.dispose();
+    }
+  });
+}
+
+// src/animation-asset-lookup.ts
+function createAnimationPayloadLookup(source) {
+  return (guid) => source?.lookup(guid);
+}
+function syncCameraAspect(world, canvasW, canvasH) {
+  if (canvasW <= 0 || canvasH <= 0) return;
+  const aspect = canvasW / canvasH;
+  const query = world.query({ with: [Camera] }).unwrap();
+  for (const row of query) {
+    const camera = world.get(row.entity, Camera);
+    if (!camera.ok) continue;
+    if (camera.value.autoAspect !== true) continue;
+    if (camera.value.projection !== CAMERA_PROJECTION_PERSPECTIVE) continue;
+    world.set(row.entity, Camera, { aspect });
+  }
+}
+
+// src/errors.ts
+function summarizeCause(cause) {
+  if (cause === null || cause === void 0) return String(cause);
+  if (typeof cause !== "object") return String(cause);
+  const r = cause;
+  const name = typeof r.name === "string" && r.name.length > 0 ? r.name : "Error";
+  const code = typeof r.code === "string" && r.code.length > 0 ? r.code : "";
+  const message = typeof r.message === "string" ? r.message : "";
+  const head = code !== "" ? `${name} ${code}` : name;
+  const body = message !== "" ? `: ${message}` : "";
+  return `${head}${body}`.replace(/\s*\n+\s*/g, " / ");
+}
+var AppErrorClass = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    let causeSuffix = "";
+    if (args.code === "app-system-update-failed") {
+      const d = args.detail;
+      const sys = typeof d.systemName === "string" && d.systemName.length > 0 ? ` (system=${d.systemName})` : "";
+      causeSuffix = `; cause: ${summarizeCause(d.cause)}${sys}`;
+    } else if (args.code === "app-pointer-lock-failed") {
+      const d = args.detail;
+      causeSuffix = `; path: ${d.path}; cause: ${summarizeCause(d.cause)}`;
+    } else if (args.code === "app-plugin-activation-failed") {
+      const d = args.detail;
+      causeSuffix = `; cause: ${summarizeCause(d.cause)}`;
+    } else if (args.code === "app-execution-bootstrap-failed") {
+      const d = args.detail;
+      causeSuffix = `; phase: ${d.phase}; cause: ${summarizeCause(d.cause)}`;
+    } else if (args.code === "app-execution-kernel-failed") {
+      const d = args.detail;
+      causeSuffix = `; kernel: ${d.kernelName}; cause: ${summarizeCause(d.cause)}`;
+    } else if (args.code === "app-execution-rebuild-failed") {
+      const d = args.detail;
+      causeSuffix = `; cause: ${summarizeCause(d.cause)}`;
+    }
+    super(`[AppError ${args.code}] expected: ${args.expected}; hint: ${args.hint}${causeSuffix}`);
+    this.name = "AppError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+var AppError = AppErrorClass;
+var appErrorPolicy = {
+  "app-not-started": {
+    expected: 'state must be "running" or "paused" to accept stop/pause/resume; "idle" / "stopped" terminal sinks reject',
+    hint: "check getState() before calling stop/pause/resume; rebuild the handle via createApp({...}) when the previous one terminated on device-lost"
+  },
+  "app-already-running": {
+    expected: 'state must be "idle" or "paused" to start; "running" handles ignore subsequent start() calls',
+    hint: "call stop() first or audit start() call sites; the second start() is a no-op so state is preserved"
+  },
+  "app-canvas-detached": {
+    expected: "canvas.isConnected === true at createApp(canvas) entry",
+    hint: "append the canvas to the document tree before calling createApp(canvas), or use the assemble entry createApp({ renderer, world }) when the host already manages canvas lifetime"
+  },
+  "app-invalid-canvas-pixel-ratio": {
+    expected: "maxCanvasPixelRatio is finite and greater than 0",
+    hint: "omit maxCanvasPixelRatio to keep the device pixel ratio, or pass a finite value > 0 from the Host policy"
+  },
+  "app-frame-step-invalid": {
+    expected: "stepFrame(deltaSeconds) runs only while the App is paused and deltaSeconds is finite and non-negative",
+    hint: "pause the App before deterministic stepping and pass an explicit finite delta; resume after the bounded step sequence completes"
+  },
+  "app-system-update-failed": {
+    expected: "world.update(world), renderer.draw(world), and frame-loop callbacks complete without failure",
+    hint: "inspect detail.cause for the original thrown value (EcsError / RhiError / host system bug); detail.systemName names the offending system when the call site can supply it"
+  },
+  "app-pointer-lock-failed": {
+    expected: "pointer-lock request (W3C requestPointerLock or host lockProvider.requestLock) to succeed; failure signals the browser rejected the lock or the host provider threw",
+    hint: 'remain in unlocked state; the next trusted click will automatically retry the lock request. inspect detail.path ("w3c" or "provider") and detail.cause to determine the root cause'
+  },
+  "app-plugin-activation-failed": {
+    expected: "every requested Cordis plugin fiber reaches a stable active or pending state",
+    hint: "inspect detail.cause and the plugin fiber effects; repair the failing activation before creating the App again"
+  },
+  "app-execution-tier-unavailable": {
+    expected: "the explicitly requested execution tier has every required observed capability and the shipped shared evidence gate",
+    hint: 'inspect detail.missingCapabilities and detail.sharedEvidencePassed; use tier="auto" only when an observed fallback is acceptable'
+  },
+  "app-execution-bootstrap-failed": {
+    expected: "the bootstrap URL imports a module whose default export completes as an ExecutionBootstrapEntry in the selected Engine Realm",
+    hint: "inspect detail.phase, moduleUrl and cause; export one default ExecutionBootstrapEntry that creates only realm-local engine state"
+  },
+  "app-execution-deadline-exceeded": {
+    expected: "the execution startup, handshake or frame completes within its configured bounded deadline",
+    hint: "inspect detail.phase and timeoutMs; the timed-out Worker has been terminated, so fix startup or frame work before creating a new App"
+  },
+  "app-execution-kernel-failed": {
+    expected: "a shared kernel completes every dispatched shard without leaving a possibly partial World write",
+    hint: "do not retry or draw the poisoned World; inspect detail.kernelName and cause, then call app.execution.rebuild()"
+  },
+  "app-execution-stale-world": {
+    expected: "every execution message targets the currently active World identity before it can write",
+    hint: "discard the late message and keep the current World; inspect expectedIdentity, receivedIdentity and messageKind"
+  },
+  "app-execution-rebuild-failed": {
+    expected: "explicit rebuild disposes the poisoned World and bootstraps a fresh World identity in the surviving Engine Realm",
+    hint: "inspect detail.cause; this App remains stopped, so fix the bootstrap failure or create a new App explicitly"
+  }
+};
+var APP_EXPECTED = Object.fromEntries(
+  Object.entries(appErrorPolicy).map(([code, policy]) => [code, policy.expected])
+);
+var APP_ERROR_HINTS = Object.fromEntries(
+  Object.entries(appErrorPolicy).map(([code, policy]) => [code, policy.hint])
+);
+function isAppError(err13) {
+  return err13 instanceof AppErrorClass;
+}
+function executionBootstrapHostPlugin(host) {
+  return {
+    name: "execution-bootstrap-host",
+    provide: "executionBootstrapHost",
+    apply(ctx) {
+      ctx.provide("executionBootstrapHost", host);
+      if (host.port !== void 0) {
+        ctx.effect(() => () => host.port?.close(), "execution/bootstrap-port");
+      }
+    }
+  };
+}
+function bootstrapError(phase, moduleUrl, cause) {
+  return new AppError({
+    code: "app-execution-bootstrap-failed",
+    expected: APP_EXPECTED["app-execution-bootstrap-failed"],
+    hint: APP_ERROR_HINTS["app-execution-bootstrap-failed"],
+    detail: { phase, moduleUrl, cause }
+  });
+}
+function validateExecutionBootstrapData(data, moduleUrl) {
+  if (data === void 0) return ok(void 0);
+  try {
+    structuredClone(data);
+    return ok(void 0);
+  } catch (cause) {
+    return err(bootstrapError("data", moduleUrl, cause));
+  }
+}
+async function loadBootstrapEntry(moduleUrl) {
+  let loaded;
+  try {
+    loaded = await import(
+      /* @vite-ignore */
+      moduleUrl
+    );
+  } catch (cause) {
+    return err(bootstrapError("import", moduleUrl, cause));
+  }
+  const entry = loaded.default;
+  if (typeof entry !== "function") {
+    return err(
+      bootstrapError(
+        "export",
+        moduleUrl,
+        new TypeError("default export is not an ExecutionBootstrapEntry function")
+      )
+    );
+  }
+  return ok(entry);
+}
+async function prepareBootstrapEntry(moduleUrl, data) {
+  const valid = validateExecutionBootstrapData(data, moduleUrl);
+  if (!valid.ok) return valid;
+  const loaded = await loadBootstrapEntry(moduleUrl);
+  if (!loaded.ok) return loaded;
+  try {
+    const prepared = await loaded.value(data);
+    if (typeof prepared !== "object" || prepared === null || prepared.features !== void 0 && !Array.isArray(prepared.features) || prepared.plugins !== void 0 && !Array.isArray(prepared.plugins)) {
+      return err(
+        bootstrapError(
+          "prepare",
+          moduleUrl,
+          new TypeError("execution bootstrap must return an object with feature and plugin arrays")
+        )
+      );
+    }
+    return ok(prepared);
+  } catch (cause) {
+    return err(bootstrapError("prepare", moduleUrl, cause));
+  }
+}
+
+// src/execution/types.ts
+var EXECUTION_TIERS = ["main-serial", "engine-worker", "shared"];
+var EXECUTION_REQUESTED_TIERS = ["auto", ...EXECUTION_TIERS];
+var EXECUTION_CAPABILITY_NAMES = [
+  "worker",
+  "offscreenCanvas",
+  "workerAnimationFrame",
+  "workerWebGpu",
+  "crossOriginIsolated",
+  "sharedArrayBuffer",
+  "atomicsWait"
+];
+
+// src/execution/capabilities.ts
+function unavailableExecutionCapabilities(reason) {
+  return Object.fromEntries(
+    EXECUTION_CAPABILITY_NAMES.map((name) => [name, { available: false, reason }])
+  );
+}
+function missingExecutionCapabilities(capabilities, required) {
+  return required.filter((name) => !capabilities[name].available);
+}
+function probeWorker(timeoutMs) {
+  return new Promise((resolve) => {
+    const source = `postMessage({workerAnimationFrame:typeof requestAnimationFrame==='function',workerWebGpu:typeof navigator==='object'&&navigator.gpu!==undefined,atomicsWait:typeof Atomics==='object'&&typeof Atomics.wait==='function'})`;
+    const url = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+    const worker = new Worker(url);
+    const finish = (result) => {
+      worker.terminate();
+      URL.revokeObjectURL(url);
+      resolve(result);
+    };
+    const timeout = setTimeout(
+      () => finish({ workerAnimationFrame: false, workerWebGpu: false, atomicsWait: false }),
+      timeoutMs
+    );
+    worker.onmessage = (event) => {
+      clearTimeout(timeout);
+      finish(event.data);
+    };
+    worker.onerror = () => {
+      clearTimeout(timeout);
+      finish({ workerAnimationFrame: false, workerWebGpu: false, atomicsWait: false });
+    };
+  });
+}
+async function probeExecutionCapabilities(canvas, timeoutMs = 2e3) {
+  const workerAvailable = typeof Worker === "function";
+  const offscreenAvailable = typeof canvas.transferControlToOffscreen === "function";
+  const isolated = globalThis.crossOriginIsolated === true;
+  const sabAvailable = typeof SharedArrayBuffer === "function";
+  const worker = workerAvailable ? await probeWorker(timeoutMs) : { workerAnimationFrame: false, workerWebGpu: false, atomicsWait: false };
+  return {
+    worker: {
+      available: workerAvailable,
+      reason: workerAvailable ? "Worker constructor observed" : "Worker constructor unavailable"
+    },
+    offscreenCanvas: {
+      available: offscreenAvailable,
+      reason: offscreenAvailable ? "canvas transferControlToOffscreen observed" : "canvas cannot transfer to OffscreenCanvas"
+    },
+    workerAnimationFrame: {
+      available: worker.workerAnimationFrame,
+      reason: worker.workerAnimationFrame ? "requestAnimationFrame observed in DedicatedWorker" : "requestAnimationFrame unavailable in DedicatedWorker"
+    },
+    workerWebGpu: {
+      available: worker.workerWebGpu,
+      reason: worker.workerWebGpu ? "navigator.gpu observed in DedicatedWorker" : "navigator.gpu unavailable in DedicatedWorker"
+    },
+    crossOriginIsolated: {
+      available: isolated,
+      reason: isolated ? "crossOriginIsolated is true" : "crossOriginIsolated is false"
+    },
+    sharedArrayBuffer: {
+      available: sabAvailable,
+      reason: sabAvailable ? "SharedArrayBuffer constructor observed" : "SharedArrayBuffer constructor unavailable"
+    },
+    atomicsWait: {
+      available: worker.atomicsWait,
+      reason: worker.atomicsWait ? "Atomics.wait observed in DedicatedWorker" : "Atomics.wait unavailable in DedicatedWorker"
+    }
+  };
+}
+
+// src/execution/schema.ts
+var EXECUTION_REPORT_SCHEMA_VERSION = 1;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every((key) => key in value);
+}
+function isMeasurement(value) {
+  if (!isRecord(value) || !hasExactKeys(value, ["samples", "p50", "p95", "p99", "jitter"])) {
+    return false;
+  }
+  return Number.isInteger(value.samples) && value.samples > 0 && ["p50", "p95", "p99", "jitter"].every(
+    (key) => typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0
+  );
+}
+function isExecutionReport(value) {
+  if (!isRecord(value)) return false;
+  if (!hasExactKeys(value, [
+    "schemaVersion",
+    "requestedTier",
+    "actualTier",
+    "selectionReason",
+    "sharedEvidencePassed",
+    "capabilities",
+    "engine",
+    "world",
+    "kernelDispatch",
+    "performance",
+    "audio",
+    "fault"
+  ])) {
+    return false;
+  }
+  const report = value;
+  if (report.schemaVersion !== EXECUTION_REPORT_SCHEMA_VERSION) return false;
+  if (!EXECUTION_REQUESTED_TIERS.includes(report.requestedTier)) return false;
+  if (report.actualTier !== null && !EXECUTION_TIERS.includes(report.actualTier)) {
+    return false;
+  }
+  if (typeof report.sharedEvidencePassed !== "boolean" || report.capabilities === void 0) {
+    return false;
+  }
+  if (!EXECUTION_CAPABILITY_NAMES.every((name) => {
+    const fact = report.capabilities?.[name];
+    return typeof fact?.available === "boolean" && typeof fact.reason === "string";
+  }))
+    return false;
+  const engine = report.engine;
+  const world = report.world;
+  const dispatch = report.kernelDispatch;
+  const performance2 = report.performance;
+  const audio = report.audio;
+  if (!isRecord(engine) || !hasExactKeys(engine, ["realm", "health"])) return false;
+  if (!["host", "worker"].includes(engine.realm)) return false;
+  if (!["idle", "starting", "running", "stopped", "faulted"].includes(engine.health)) {
+    return false;
+  }
+  if (!isRecord(world) || !hasExactKeys(world, ["identity", "health", "partialWrite", "retryable"])) {
+    return false;
+  }
+  if (world.identity !== null && typeof world.identity !== "string") return false;
+  if (!["healthy", "poisoned"].includes(world.health)) return false;
+  if (typeof world.partialWrite !== "boolean" || typeof world.retryable !== "boolean") return false;
+  if (!isRecord(dispatch) || !hasExactKeys(dispatch, ["eligible", "usedShared", "reason", "dispatched", "completed"])) {
+    return false;
+  }
+  if (typeof dispatch.eligible !== "boolean" || typeof dispatch.usedShared !== "boolean")
+    return false;
+  if (![
+    "no-eligible-kernel",
+    "zero-work",
+    "small-span",
+    "forced-inline",
+    "shared",
+    "poisoned"
+  ].includes(dispatch.reason))
+    return false;
+  if (!Number.isInteger(dispatch.dispatched) || !Number.isInteger(dispatch.completed)) return false;
+  if (!isRecord(performance2) || !hasExactKeys(performance2, ["hostFrameMs", "engineUpdateMs", "kernelWaitMs", "hostAudioMs"]))
+    return false;
+  for (const key of ["hostFrameMs", "engineUpdateMs", "kernelWaitMs", "hostAudioMs"]) {
+    const measurement = performance2[key];
+    if (measurement !== null && !isMeasurement(measurement)) return false;
+  }
+  if (!isRecord(audio) || !hasExactKeys(audio, ["owner", "contextState", "activeSourceCount", "lastError"]))
+    return false;
+  if (audio.owner !== "host") return false;
+  if (!["running", "suspended", "closed"].includes(audio.contextState)) return false;
+  if (!Number.isInteger(audio.activeSourceCount) || audio.activeSourceCount < 0)
+    return false;
+  if (audio.lastError !== null) {
+    if (!isRecord(audio.lastError)) return false;
+    if (!hasExactKeys(audio.lastError, ["code", "expected", "hint", "detail"])) return false;
+    if (typeof audio.lastError.code !== "string" || typeof audio.lastError.expected !== "string" || typeof audio.lastError.hint !== "string")
+      return false;
+  }
+  if (report.fault !== null) {
+    if (!isRecord(report.fault)) return false;
+    if (!hasExactKeys(report.fault, [
+      "source",
+      "code",
+      "expected",
+      "hint",
+      "detail",
+      "partialWrite",
+      "retryable"
+    ]))
+      return false;
+    if (!["bootstrap", "handshake", "runtime", "kernel", "world", "rebuild"].includes(
+      report.fault.source
+    ))
+      return false;
+    if (typeof report.fault.code !== "string" || typeof report.fault.expected !== "string" || typeof report.fault.hint !== "string")
+      return false;
+    if (typeof report.fault.partialWrite !== "boolean" || typeof report.fault.retryable !== "boolean")
+      return false;
+  }
+  return true;
+}
+
+// src/execution/report.ts
+function executionAudioReport(state) {
+  const error = state?.lastError ?? null;
+  return {
+    owner: "host",
+    contextState: state?.contextState ?? "suspended",
+    activeSourceCount: state?.activeSourceCount ?? 0,
+    lastError: error === null ? null : {
+      code: error.code,
+      expected: error.expected,
+      hint: error.hint,
+      detail: error.detail
+    }
+  };
+}
+function createExecutionReport(requestedTier, capabilities, selection) {
+  return {
+    schemaVersion: EXECUTION_REPORT_SCHEMA_VERSION,
+    requestedTier,
+    actualTier: selection?.actualTier ?? null,
+    selectionReason: selection?.selectionReason ?? null,
+    sharedEvidencePassed: selection?.sharedEvidencePassed ?? false,
+    capabilities,
+    engine: {
+      realm: selection?.actualTier === "main-serial" ? "host" : "worker",
+      health: "idle"
+    },
+    world: {
+      identity: null,
+      health: "healthy",
+      partialWrite: false,
+      retryable: true
+    },
+    kernelDispatch: {
+      eligible: false,
+      usedShared: false,
+      reason: "no-eligible-kernel",
+      dispatched: 0,
+      completed: 0
+    },
+    performance: {
+      hostFrameMs: null,
+      engineUpdateMs: null,
+      kernelWaitMs: null,
+      hostAudioMs: null
+    },
+    audio: executionAudioReport(),
+    fault: null
+  };
+}
+
+// src/execution/control.ts
+function cloneExecutionReport(report) {
+  return structuredClone(report);
+}
+function createLocalExecutionControl(initial, providers = {}) {
+  let current = cloneExecutionReport(initial);
+  return {
+    setEngineHealth: (health) => {
+      current = { ...current, engine: { ...current.engine, health } };
+    },
+    report: () => cloneExecutionReport({
+      ...current,
+      world: providers.world?.() ?? current.world,
+      audio: executionAudioReport(providers.audio?.())
+    }),
+    rebuild: async () => {
+      if (providers.rebuild !== void 0) return providers.rebuild();
+      return err(
+        new AppError({
+          code: "app-execution-rebuild-failed",
+          expected: APP_EXPECTED["app-execution-rebuild-failed"],
+          hint: APP_ERROR_HINTS["app-execution-rebuild-failed"],
+          detail: {
+            worldIdentity: current.world.identity,
+            cause: new Error("This local assembly has no bootstrap module.")
+          }
+        })
+      );
+    }
+  };
+}
+var ENGINE_WORKER_CAPABILITIES = [
+  "worker",
+  "offscreenCanvas",
+  "workerWebGpu"
+];
+var SHARED_CAPABILITIES = [
+  ...ENGINE_WORKER_CAPABILITIES,
+  "crossOriginIsolated",
+  "sharedArrayBuffer",
+  "atomicsWait"
+];
+function requiredCapabilities(tier) {
+  if (tier === "main-serial") return [];
+  if (tier === "engine-worker") return ENGINE_WORKER_CAPABILITIES;
+  return SHARED_CAPABILITIES;
+}
+function missingFor(tier, capabilities) {
+  return missingExecutionCapabilities(capabilities, requiredCapabilities(tier));
+}
+function selectExecutionTier(input) {
+  if (input.requestedTier !== "auto") {
+    const missing = missingFor(input.requestedTier, input.capabilities);
+    if (missing.length > 0 || input.requestedTier === "shared" && !input.sharedEvidencePassed) {
+      return err(
+        new AppError({
+          code: "app-execution-tier-unavailable",
+          expected: APP_EXPECTED["app-execution-tier-unavailable"],
+          hint: APP_ERROR_HINTS["app-execution-tier-unavailable"],
+          detail: {
+            requestedTier: input.requestedTier,
+            missingCapabilities: missing,
+            sharedEvidencePassed: input.sharedEvidencePassed
+          }
+        })
+      );
+    }
+    return ok({
+      requestedTier: input.requestedTier,
+      actualTier: input.requestedTier,
+      selectionReason: "explicit-request",
+      missingCapabilities: [],
+      sharedEvidencePassed: input.sharedEvidencePassed
+    });
+  }
+  const sharedMissing = missingFor("shared", input.capabilities);
+  if (sharedMissing.length === 0 && input.sharedEvidencePassed) {
+    return ok({
+      requestedTier: "auto",
+      actualTier: "shared",
+      selectionReason: "auto-shared",
+      missingCapabilities: [],
+      sharedEvidencePassed: true
+    });
+  }
+  const workerMissing = missingFor("engine-worker", input.capabilities);
+  if (workerMissing.length === 0) {
+    return ok({
+      requestedTier: "auto",
+      actualTier: "engine-worker",
+      selectionReason: "auto-engine-worker",
+      missingCapabilities: sharedMissing,
+      sharedEvidencePassed: input.sharedEvidencePassed
+    });
+  }
+  return ok({
+    requestedTier: "auto",
+    actualTier: "main-serial",
+    selectionReason: "auto-main-serial",
+    missingCapabilities: workerMissing,
+    sharedEvidencePassed: input.sharedEvidencePassed
+  });
+}
+
+// src/internal/error-fanout.ts
+var ErrorFanoutRegistry = class {
+  listeners = /* @__PURE__ */ new Set();
+  silenceUnhandledErrors;
+  constructor(opts = {}) {
+    this.silenceUnhandledErrors = opts.silenceUnhandledErrors === true;
+  }
+  /**
+   * Register a listener. Returns an unsubscribe function. Calling
+   * unsubscribe more than once is a safe no-op (Set.delete returns
+   * false on the second call but does not throw). Re-registering the
+   * same listener function is a no-op (Set semantics).
+   */
+  add(cb) {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+  /**
+   * Iterate over a snapshot of the listener set so a listener that
+   * mutates the set mid-fire does not perturb the iteration. When the
+   * set is empty AND silenceUnhandledErrors !== true, call
+   * console.error(err) so the unhandled error is visible in devtools
+   * (charter P3 explicit failure: silent drop is a footgun).
+   */
+  fire(err13) {
+    if (this.listeners.size === 0) {
+      if (!this.silenceUnhandledErrors) {
+        console.error(err13);
+      }
+      return;
+    }
+    const snapshot = Array.from(this.listeners);
+    for (const cb of snapshot) {
+      cb(err13);
+    }
+  }
+  /**
+   * Number of currently registered listeners. Reserved for diagnostics +
+   * test fixtures (e.g. asserting cleanup paths reach the registry); not
+   * part of the public app-shell surface.
+   *
+   * @internal
+   */
+  _size() {
+    return this.listeners.size;
+  }
+};
+
+// src/types.ts
+var APP_PHASE_CATALOG = [
+  "frame-total",
+  "draw-source",
+  "world-update-primary",
+  "world-update-injected",
+  "renderer-draw",
+  "host-frame",
+  "engine-update",
+  "kernel-wait",
+  "host-audio"
+];
+function deadlineError(timeoutMs) {
+  return new AppError({
+    code: "app-execution-deadline-exceeded",
+    expected: APP_EXPECTED["app-execution-deadline-exceeded"],
+    hint: APP_ERROR_HINTS["app-execution-deadline-exceeded"],
+    detail: { phase: "handshake", timeoutMs }
+  });
+}
+function startupFault(message, moduleUrl) {
+  return new AppError({
+    code: "app-execution-bootstrap-failed",
+    expected: APP_EXPECTED["app-execution-bootstrap-failed"],
+    hint: APP_ERROR_HINTS["app-execution-bootstrap-failed"],
+    detail: { phase: "bootstrap", moduleUrl, cause: message.detail }
+  });
+}
+async function startEngineWorker(options) {
+  const validData = validateExecutionBootstrapData(options.bootstrapData, options.bootstrapUrl);
+  if (!validData.ok) return validData;
+  const worker = options.workerFactory?.() ?? new Worker(new URL("./engine-worker-runtime.mjs", import.meta.url), {
+    type: "module",
+    name: "forgeax-engine"
+  });
+  const listeners = /* @__PURE__ */ new Set();
+  let settled = false;
+  let resolveReady = () => {
+  };
+  const readyPromise = new Promise((resolve) => {
+    resolveReady = resolve;
+  });
+  const timeout = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    worker.terminate();
+    resolveReady(err(deadlineError(options.timeoutMs)));
+  }, options.timeoutMs);
+  worker.onmessage = (event) => {
+    const message = event.data;
+    if (!settled && message.kind === "ready") {
+      settled = true;
+      clearTimeout(timeout);
+      resolveReady(ok(message));
+    } else if (!settled && message.kind === "fault") {
+      settled = true;
+      clearTimeout(timeout);
+      worker.terminate();
+      resolveReady(err(startupFault(message, options.bootstrapUrl)));
+    }
+    for (const listener of listeners) listener(message);
+  };
+  worker.onerror = (event) => {
+    if (settled) {
+      const crash = {
+        kind: "fault",
+        worldIdentity: null,
+        source: "runtime",
+        code: "worker-crashed",
+        expected: "Engine Worker remains alive while the App is running",
+        hint: "inspect the Worker error and create a new App; transferred canvas ownership is terminal",
+        detail: { message: event.message },
+        partialWrite: false,
+        retryable: false
+      };
+      for (const listener of listeners) listener(crash);
+      return;
+    }
+    settled = true;
+    clearTimeout(timeout);
+    worker.terminate();
+    resolveReady(
+      err(
+        startupFault(
+          {
+            detail: { message: event.message }},
+          options.bootstrapUrl
+        )
+      )
+    );
+  };
+  const offscreen = options.canvas.transferControlToOffscreen();
+  const init = {
+    kind: "init",
+    canvas: offscreen,
+    bootstrapUrl: options.bootstrapUrl,
+    ...options.bootstrapData === void 0 ? {} : { bootstrapData: options.bootstrapData },
+    ...options.bootstrapPort === void 0 ? {} : { bootstrapPort: options.bootstrapPort },
+    ...options.shaderManifestUrl !== void 0 ? { shaderManifestUrl: options.shaderManifestUrl } : {},
+    ...options.time !== void 0 ? { time: options.time } : {},
+    tier: options.tier
+  };
+  worker.postMessage(init, [
+    offscreen,
+    ...options.bootstrapPort === void 0 ? [] : [options.bootstrapPort]
+  ]);
+  const ready = await readyPromise;
+  if (!ready.ok) return ready;
+  return ok({
+    worker,
+    ready: ready.value,
+    post(message, transfer = []) {
+      worker.postMessage(message, transfer);
+    },
+    listen(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    dispose() {
+      worker.postMessage({ kind: "dispose" });
+      worker.terminate();
+      listeners.clear();
+    }
+  });
+}
+
+// src/execution/measurement.ts
+function percentile(sorted, fraction) {
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1));
+  return sorted[index] ?? 0;
+}
+function createMeasurementSeries(capacity = 240) {
+  const values = [];
+  let samples = 0;
+  return {
+    add(value) {
+      samples += 1;
+      values.push(value);
+      if (values.length > capacity) values.shift();
+      const sorted = [...values].sort((a, b) => a - b);
+      let jitter = 0;
+      for (let index = 1; index < values.length; index += 1) {
+        jitter += Math.abs((values[index] ?? 0) - (values[index - 1] ?? 0));
+      }
+      return {
+        samples,
+        p50: percentile(sorted, 0.5),
+        p95: percentile(sorted, 0.95),
+        p99: percentile(sorted, 0.99),
+        jitter: values.length < 2 ? 0 : jitter / (values.length - 1)
+      };
+    },
+    clear() {
+      values.length = 0;
+      samples = 0;
+    }
+  };
+}
+
+// src/execution/protocol.ts
+var FrameCreditLedger = class {
+  constructor(worldIdentity) {
+    this.worldIdentity = worldIdentity;
+  }
+  worldIdentity;
+  nextFrameId = 1;
+  inFlight = null;
+  completed = 0;
+  issue(deltaSeconds, sampleInput, canvasSize) {
+    if (this.inFlight !== null) return void 0;
+    const frameId = this.nextFrameId;
+    this.nextFrameId += 1;
+    this.inFlight = frameId;
+    return {
+      kind: "frame",
+      worldIdentity: this.worldIdentity,
+      frameId,
+      deltaSeconds,
+      inputSample: sampleInput(),
+      canvasWidth: canvasSize.width,
+      canvasHeight: canvasSize.height
+    };
+  }
+  complete(message) {
+    if (message.worldIdentity !== this.worldIdentity) return "stale-world";
+    if (message.frameId <= this.completed) return "duplicate";
+    if (message.frameId !== this.inFlight) return "late";
+    this.completed = message.frameId;
+    this.inFlight = null;
+    return "accepted";
+  }
+  get hasCreditInFlight() {
+    return this.inFlight !== null;
+  }
+};
+
+// src/execution/host-controller.ts
+function lifecycleError(code) {
+  return new AppError({
+    code,
+    expected: APP_EXPECTED[code],
+    hint: APP_ERROR_HINTS[code],
+    detail: {}
+  });
+}
+function runtimeError(message) {
+  if (message.code === "shared-kernel-failed" && message.worldIdentity !== null) {
+    return new AppError({
+      code: "app-execution-kernel-failed",
+      expected: APP_EXPECTED["app-execution-kernel-failed"],
+      hint: APP_ERROR_HINTS["app-execution-kernel-failed"],
+      detail: {
+        kernelName: message.detail?.kernelName ?? "unknown",
+        worldIdentity: message.worldIdentity,
+        cause: message.detail,
+        partialWrite: true,
+        retryable: false
+      }
+    });
+  }
+  return new AppError({
+    code: "app-system-update-failed",
+    expected: APP_EXPECTED["app-system-update-failed"],
+    hint: APP_ERROR_HINTS["app-system-update-failed"],
+    detail: { cause: message.detail }
+  });
+}
+async function createWorkerExecutionApp(options) {
+  const executionOptions = options.appOptions.execution;
+  if (executionOptions === void 0) throw new Error("execution options are required");
+  const syncCanvas = options.syncCanvas;
+  const bootstrapUrl = new URL(executionOptions.bootstrap, globalThis.location?.href).href;
+  const startupTimeoutMs = executionOptions.startupTimeoutMs ?? 1e4;
+  const frameTimeoutMs = executionOptions.frameTimeoutMs ?? 2e3;
+  const started = await startEngineWorker({
+    canvas: options.canvas,
+    bootstrapUrl,
+    ...executionOptions.bootstrapData === void 0 ? {} : { bootstrapData: executionOptions.bootstrapData },
+    ...executionOptions.bootstrapPort === void 0 ? {} : { bootstrapPort: executionOptions.bootstrapPort },
+    ...options.bundler?.shaderManifestUrl !== void 0 ? { shaderManifestUrl: options.bundler.shaderManifestUrl } : {},
+    ...options.appOptions.time !== void 0 ? { time: options.appOptions.time } : {},
+    timeoutMs: startupTimeoutMs,
+    tier: options.selection.actualTier
+  });
+  if (!started.ok) return started;
+  const session = started.value;
+  const profiler = options.appOptions.profiler;
+  const phaseCatalogRegistration = profiler?.registerPhaseCatalog("app", APP_PHASE_CATALOG);
+  let releasePhaseCatalog = phaseCatalogRegistration?.ok === true ? phaseCatalogRegistration.value : void 0;
+  const fanout = new ErrorFanoutRegistry(
+    options.appOptions.silenceUnhandledErrors === void 0 ? {} : { silenceUnhandledErrors: options.appOptions.silenceUnhandledErrors }
+  );
+  const inputHandle = options.appOptions.input === void 0 ? attachBrowserInputBackend(options.canvas, {
+    ...options.appOptions.uiRoot !== void 0 ? { uiRoot: options.appOptions.uiRoot } : {},
+    ...options.appOptions.pointerLockAllowed !== void 0 ? { pointerLockAllowed: options.appOptions.pointerLockAllowed } : {},
+    ...options.appOptions.virtualJoysticks !== void 0 ? { virtualJoysticks: options.appOptions.virtualJoysticks } : {},
+    ...options.appOptions.lockProvider !== void 0 ? { lockProvider: options.appOptions.lockProvider } : {},
+    onLockError: (detail) => fanout.fire(
+      new AppError({
+        code: "app-pointer-lock-failed",
+        expected: APP_EXPECTED["app-pointer-lock-failed"],
+        hint: APP_ERROR_HINTS["app-pointer-lock-failed"],
+        detail
+      })
+    )
+  }) : void 0;
+  const input = options.appOptions.input ?? inputHandle?.backend ?? {
+    sample: () => ({
+      downKeys: /* @__PURE__ */ new Set(),
+      upKeys: /* @__PURE__ */ new Set(),
+      buttons: [false, false, false],
+      movementX: 0,
+      movementY: 0,
+      wheelDelta: 0,
+      focused: true,
+      pointerLocked: false
+    }),
+    detach: () => {
+    }
+  };
+  let report = {
+    ...createExecutionReport(
+      executionOptions.tier ?? "auto",
+      options.capabilities,
+      options.selection
+    ),
+    engine: { realm: "worker", health: "idle" },
+    world: {
+      identity: session.ready.worldIdentity,
+      health: "healthy",
+      partialWrite: false,
+      retryable: true
+    }
+  };
+  let state = "idle";
+  let ledger = new FrameCreditLedger(session.ready.worldIdentity);
+  let rafId = 0;
+  let lastTimestamp = 0;
+  let frameDeadline;
+  let lastError;
+  let rebuildResolve;
+  let rebuildInFlight;
+  const hostFrameMeasurements = createMeasurementSeries();
+  const engineMeasurements = createMeasurementSeries();
+  const kernelMeasurements = createMeasurementSeries();
+  const audioMeasurements = createMeasurementSeries();
+  let audio = createHostAudioConsumer();
+  let frameSentAt = 0;
+  let profilerCaptureId;
+  let profilerFrameId = 0;
+  let frameProfile = profiler?.activeSession();
+  let profileFrameOpen = false;
+  let hostFrameOpen = false;
+  const setEngineHealth = (health) => {
+    report = { ...report, engine: { ...report.engine, health } };
+  };
+  const finishProfile = () => {
+    if (hostFrameOpen) frameProfile?.endPhase();
+    if (profileFrameOpen) frameProfile?.endFrame();
+    frameProfile = void 0;
+    profileFrameOpen = false;
+    hostFrameOpen = false;
+    try {
+      profiler?.activeSession()?.finish();
+    } catch {
+    }
+    releasePhaseCatalog?.();
+    releasePhaseCatalog = void 0;
+  };
+  const terminalFault = (message) => {
+    if (frameDeadline !== void 0) {
+      clearTimeout(frameDeadline);
+      frameDeadline = void 0;
+    }
+    const error = runtimeError(message);
+    lastError = error;
+    state = message.partialWrite ? "faulted" : "stopped";
+    report = {
+      ...report,
+      engine: { ...report.engine, health: "faulted" },
+      world: {
+        identity: message.worldIdentity,
+        health: message.partialWrite ? "poisoned" : report.world.health,
+        partialWrite: message.partialWrite,
+        retryable: message.retryable
+      },
+      kernelDispatch: {
+        ...report.kernelDispatch,
+        reason: message.partialWrite ? "poisoned" : report.kernelDispatch.reason
+      },
+      fault: {
+        source: message.source,
+        code: message.code,
+        expected: message.expected,
+        hint: message.hint,
+        detail: message.detail,
+        partialWrite: message.partialWrite,
+        retryable: message.retryable
+      }
+    };
+    fanout.fire(error);
+    if (!message.partialWrite) {
+      audio.dispose();
+      session.dispose();
+    }
+    finishProfile();
+  };
+  const scheduleFrame = () => {
+    rafId = requestAnimationFrame((timestamp) => {
+      if (state !== "running") return;
+      const deltaSeconds = lastTimestamp === 0 ? 0 : Math.max(0, (timestamp - lastTimestamp) / 1e3);
+      lastTimestamp = timestamp;
+      const canvasSize = syncCanvas?.() ?? {
+        width: options.canvas.width,
+        height: options.canvas.height
+      };
+      const frame = ledger.issue(deltaSeconds, () => input.sample(), canvasSize);
+      if (frame === void 0) return;
+      frameProfile = profiler?.activeSession();
+      if (frameProfile !== void 0 && profilerCaptureId !== frameProfile.captureId) {
+        profilerCaptureId = frameProfile.captureId;
+        profilerFrameId = 0;
+      }
+      profileFrameOpen = frameProfile?.beginFrame(++profilerFrameId).ok ?? false;
+      hostFrameOpen = profileFrameOpen ? frameProfile?.beginPhase("app", "host-frame").ok ?? false : false;
+      session.post(frame);
+      frameSentAt = performance.now();
+      frameDeadline = setTimeout(() => {
+        if (state !== "running") return;
+        terminalFault({
+          worldIdentity: report.world.identity,
+          source: "runtime",
+          code: "app-execution-deadline-exceeded",
+          expected: APP_EXPECTED["app-execution-deadline-exceeded"],
+          hint: APP_ERROR_HINTS["app-execution-deadline-exceeded"],
+          detail: { phase: "frame", timeoutMs: frameTimeoutMs },
+          partialWrite: false,
+          retryable: false
+        });
+      }, frameTimeoutMs);
+    });
+  };
+  session.listen((message) => {
+    if (message.kind === "frame-complete") {
+      if (ledger.complete(message) !== "accepted") return;
+      if (frameDeadline !== void 0) clearTimeout(frameDeadline);
+      if (hostFrameOpen) frameProfile?.endPhase();
+      if (profileFrameOpen) {
+        frameProfile?.recordSkip({
+          source: "app",
+          phase: "engine-update",
+          reason: `worker-report:${message.engineUpdateMs.toFixed(3)}ms`
+        });
+        frameProfile?.recordSkip({
+          source: "app",
+          phase: "kernel-wait",
+          reason: `worker-report:${message.kernelWaitMs.toFixed(3)}ms`
+        });
+      }
+      const audioStarted = performance.now();
+      const audioProfileOpen = profileFrameOpen ? frameProfile?.beginPhase("app", "host-audio").ok ?? false : false;
+      for (const intent of message.audioIntents ?? []) audio.consume(intent);
+      if (audioProfileOpen) frameProfile?.endPhase();
+      const audioMs = performance.now() - audioStarted;
+      report = {
+        ...report,
+        performance: {
+          ...report.performance,
+          hostFrameMs: hostFrameMeasurements.add(performance.now() - frameSentAt),
+          engineUpdateMs: engineMeasurements.add(message.engineUpdateMs),
+          kernelWaitMs: kernelMeasurements.add(message.kernelWaitMs),
+          hostAudioMs: audioMeasurements.add(audioMs)
+        }
+      };
+      if (message.kernelDispatch !== void 0) {
+        report = { ...report, kernelDispatch: message.kernelDispatch };
+      }
+      if (profileFrameOpen) frameProfile?.endFrame();
+      frameProfile = void 0;
+      profileFrameOpen = false;
+      hostFrameOpen = false;
+      if (state === "running") scheduleFrame();
+    } else if (message.kind === "fault") {
+      terminalFault(message);
+    } else if (message.kind === "rebuilt") {
+      audio.dispose();
+      audio = createHostAudioConsumer();
+      ledger = new FrameCreditLedger(message.worldIdentity);
+      hostFrameMeasurements.clear();
+      engineMeasurements.clear();
+      kernelMeasurements.clear();
+      audioMeasurements.clear();
+      state = "idle";
+      report = {
+        ...report,
+        engine: { ...report.engine, health: "idle" },
+        world: {
+          identity: message.worldIdentity,
+          health: "healthy",
+          partialWrite: false,
+          retryable: true
+        },
+        kernelDispatch: {
+          eligible: false,
+          usedShared: false,
+          reason: "no-eligible-kernel",
+          dispatched: 0,
+          completed: 0
+        },
+        fault: null,
+        performance: {
+          hostFrameMs: null,
+          engineUpdateMs: null,
+          kernelWaitMs: null,
+          hostAudioMs: null
+        }
+      };
+      rebuildResolve?.(ok(cloneExecutionReport(report)));
+      rebuildResolve = void 0;
+      rebuildInFlight = void 0;
+    } else if (message.kind === "host-control") {
+      if (message.command === "set-pointer-lock-allowed") {
+        input.setPointerLockAllowed?.(message.allowed);
+      }
+    }
+  });
+  const execution = {
+    report: () => cloneExecutionReport({
+      ...report,
+      audio: executionAudioReport(audio.state())
+    }),
+    rebuild: () => {
+      if (rebuildInFlight !== void 0) return rebuildInFlight;
+      if (state !== "faulted" || report.world.identity === null) {
+        return Promise.resolve(
+          err(
+            new AppError({
+              code: "app-execution-rebuild-failed",
+              expected: APP_EXPECTED["app-execution-rebuild-failed"],
+              hint: APP_ERROR_HINTS["app-execution-rebuild-failed"],
+              detail: {
+                worldIdentity: report.world.identity,
+                cause: new Error("World is not in a rebuildable poisoned state.")
+              }
+            })
+          )
+        );
+      }
+      rebuildInFlight = new Promise((resolve) => {
+        rebuildResolve = resolve;
+        session.post({ kind: "rebuild", worldIdentity: report.world.identity });
+        setTimeout(() => {
+          if (rebuildResolve !== resolve) return;
+          rebuildResolve = void 0;
+          rebuildInFlight = void 0;
+          resolve(
+            err(
+              new AppError({
+                code: "app-execution-deadline-exceeded",
+                expected: APP_EXPECTED["app-execution-deadline-exceeded"],
+                hint: APP_ERROR_HINTS["app-execution-deadline-exceeded"],
+                detail: { phase: "handshake", timeoutMs: startupTimeoutMs }
+              })
+            )
+          );
+        }, startupTimeoutMs);
+      });
+      return rebuildInFlight;
+    }
+  };
+  const app = {
+    execution,
+    input,
+    start: () => {
+      if (state === "running") return err(lifecycleError("app-already-running"));
+      if (state === "stopped" || state === "faulted") return err(lifecycleError("app-not-started"));
+      state = "running";
+      setEngineHealth("running");
+      lastTimestamp = 0;
+      scheduleFrame();
+      return ok(void 0);
+    },
+    stop: () => {
+      if (state !== "running" && state !== "paused") return err(lifecycleError("app-not-started"));
+      if (state === "running") cancelAnimationFrame(rafId);
+      state = "stopped";
+      inputHandle?.();
+      audio.dispose();
+      session.dispose();
+      setEngineHealth("stopped");
+      finishProfile();
+      return ok(void 0);
+    },
+    pause: () => {
+      if (state !== "running") return err(lifecycleError("app-not-started"));
+      state = "paused";
+      cancelAnimationFrame(rafId);
+      return ok(void 0);
+    },
+    resume: () => {
+      if (state !== "paused") return err(lifecycleError("app-not-started"));
+      state = "running";
+      lastTimestamp = 0;
+      scheduleFrame();
+      return ok(void 0);
+    },
+    onError: (listener) => fanout.add(listener),
+    get lastError() {
+      return lastError;
+    }
+  };
+  return ok(app);
+}
+
+// src/internal/assets-world-plugin.ts
+var RENDER_ASSET_PORT_RESOURCE_KEY = "RenderAssetPort";
+var ASSET_REGISTRY_RESOURCE_KEY = "AssetRegistry";
+function rendererAssetsPlugin() {
+  return {
+    name: "renderer-assets",
+    inject: ["renderer"],
+    provide: "assets",
+    apply(ctx) {
+      if (ctx.renderer === void 0) throw new Error("assets require the renderer service");
+      ctx.provide("assets", ctx.renderer.assets);
+    }
+  };
+}
+function assetRegistryPlugin(assembly) {
+  return {
+    name: "asset-registry",
+    provide: "assetRegistry",
+    apply(ctx) {
+      ctx.provide("assetRegistry", assembly.registry);
+      ctx.effect(
+        () => () => {
+          assembly.dispose();
+          assembly.registry.dispose();
+        },
+        "assets/registry"
+      );
+    }
+  };
+}
+function assetsWorldPlugin() {
+  return {
+    name: "assets-world",
+    inject: ["world", "assets"],
+    apply(ctx) {
+      ctx.effect(() => {
+        ctx.world.insertResource(RENDER_ASSET_PORT_RESOURCE_KEY, ctx.assets);
+        return () => {
+          ctx.world.removeResource(RENDER_ASSET_PORT_RESOURCE_KEY);
+        };
+      }, "assets/world-render-projection");
+    }
+  };
+}
+function assetRegistryWorldPlugin() {
+  return {
+    name: "asset-registry-world",
+    inject: ["world", "assetRegistry"],
+    apply(ctx) {
+      ctx.effect(() => {
+        ctx.world.insertResource(ASSET_REGISTRY_RESOURCE_KEY, ctx.assetRegistry);
+        return () => {
+          ctx.world.removeResource(ASSET_REGISTRY_RESOURCE_KEY);
+        };
+      }, "assets/world-registry");
+    }
+  };
+}
+
+// src/internal/assembled-engine-profile.ts
+function assembledEngineProfile(options) {
+  return [
+    rendererPlugin(options.renderer),
+    rendererAssetsPlugin(),
+    ...options.assetAssembly === void 0 ? [] : [assetRegistryPlugin(options.assetAssembly), assetRegistryWorldPlugin()],
+    assetsWorldPlugin(),
+    ...options.extensions ?? []
+  ];
+}
+function projectJson(value, seen) {
+  if (value === null) return null;
+  if (typeof value === "boolean" || typeof value === "string") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (typeof value !== "object") return void 0;
+  if (seen.has(value)) return void 0;
+  seen.add(value);
+  if (ArrayBuffer.isView(value)) {
+    const values = Array.from(value);
+    const projected = values.map((entry) => projectJson(entry, seen));
+    seen.delete(value);
+    return projected.every((entry) => entry !== void 0) ? projected : void 0;
+  }
+  if (Array.isArray(value)) {
+    const projected = value.map((entry) => projectJson(entry, seen));
+    seen.delete(value);
+    return projected.every((entry) => entry !== void 0) ? projected : void 0;
+  }
+  const object = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const projected = projectJson(entry, seen);
+    if (projected !== void 0) object[key] = projected;
+  }
+  seen.delete(value);
+  return object;
+}
+function isJsonRecord(value) {
+  return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function projectMeta(meta) {
+  const projected = projectJson(meta, /* @__PURE__ */ new Set());
+  return isJsonRecord(projected) ? projected : {};
+}
+function projectField(reflection) {
+  const field = { type: reflection.type };
+  const defaultValue = projectJson(reflection.default, /* @__PURE__ */ new Set());
+  if (defaultValue !== void 0) Object.assign(field, { default: defaultValue });
+  if (reflection.shape !== void 0) Object.assign(field, { shape: reflection.shape });
+  if (reflection.transient !== void 0) Object.assign(field, { transient: reflection.transient });
+  if (reflection.arrayMeta !== void 0) {
+    Object.assign(field, {
+      arrayMeta: {
+        elementType: reflection.arrayMeta.elementType,
+        ...reflection.arrayMeta.length !== void 0 ? { length: reflection.arrayMeta.length } : {}
+      }
+    });
+  }
+  if (reflection.labels !== void 0) Object.assign(field, { labels: { ...reflection.labels } });
+  return Object.freeze(field);
+}
+function projectComponent(component) {
+  const definition = componentDefinition(component);
+  const fields = {};
+  for (const [name, reflection] of Object.entries(definition.fields)) {
+    fields[name] = projectField(reflection);
+  }
+  return Object.freeze({
+    name: component.name,
+    schema: Object.freeze({ ...componentSchema(component) }),
+    fields: Object.freeze(fields),
+    meta: Object.freeze(projectMeta(definition.policy.meta))
+  });
+}
+function projectComponentIntrospection(components) {
+  return Object.freeze(
+    [...components.values()].sort((left, right) => left.name.localeCompare(right.name)).map(projectComponent)
+  );
+}
+function beginFrame(session, frameId) {
+  if (session === void 0) return false;
+  try {
+    return session.beginFrame(frameId).ok;
+  } catch {
+    return false;
+  }
+}
+function beginPhase(session, phase) {
+  if (session === void 0) return false;
+  try {
+    return session.beginPhase("app", phase).ok;
+  } catch {
+    return false;
+  }
+}
+function endPhase(session) {
+  if (session === void 0) return;
+  try {
+    session.endPhase();
+  } catch {
+  }
+}
+function endFrame(session) {
+  if (session === void 0) return;
+  try {
+    session.endFrame();
+  } catch {
+  }
+}
+function finishProfilerCapture(profiler) {
+  const session = profiler?.activeSession();
+  if (session === void 0) return;
+  try {
+    session.finish();
+  } catch {
+  }
+}
+function makeAppError(code, expected, hint, detail) {
+  return new AppError({ code, expected, hint, detail });
+}
+function makeWorldUpdateError(cause) {
+  return makeAppError(
+    "app-system-update-failed",
+    "world.update(deltaSeconds) completes successfully",
+    "check detail.cause for the original structured ECS error",
+    { cause }
+  );
+}
+function fireWorldUpdateResult(result, fireError) {
+  if (!result.ok && fireError !== void 0) {
+    fireError(makeWorldUpdateError(result.error));
+  }
+  return result.ok;
+}
+function updateInjectedWorlds(worlds, ownWorld, deltaSeconds, fireError, attachedWorlds, updatedWorlds) {
+  for (const injectedWorld of worlds) {
+    if (injectedWorld === ownWorld || updatedWorlds.has(injectedWorld) || !attachedWorlds.has(injectedWorld)) {
+      continue;
+    }
+    try {
+      if (fireWorldUpdateResult(injectedWorld.update(deltaSeconds), fireError)) {
+        updatedWorlds.add(injectedWorld);
+      }
+    } catch (cause) {
+      if (fireError !== void 0) fireError(makeWorldUpdateError(cause));
+    }
+  }
+}
+function resolveNow(opts) {
+  if (opts.now !== void 0) return opts.now;
+  return () => {
+    const perf = globalThis.performance;
+    const fn = perf?.now;
+    return typeof fn === "function" ? fn.call(perf) : Date.now();
+  };
+}
+function resolveRaf(opts) {
+  if (opts.raf !== void 0) return opts.raf;
+  const g = globalThis;
+  return typeof g.requestAnimationFrame === "function" ? g.requestAnimationFrame.bind(globalThis) : () => 0;
+}
+function resolveCaf(opts) {
+  if (opts.caf !== void 0) return opts.caf;
+  const g = globalThis;
+  return typeof g.cancelAnimationFrame === "function" ? g.cancelAnimationFrame.bind(globalThis) : () => {
+  };
+}
+function createFrameLoop(opts) {
+  const { world, renderer } = opts;
+  const primaryDrawWorlds = [world];
+  const phaseCatalogRegistration = opts.profiler?.registerPhaseCatalog("app", APP_PHASE_CATALOG);
+  let releasePhaseCatalog = phaseCatalogRegistration?.ok === true ? phaseCatalogRegistration.value : void 0;
+  let drawSource = opts.drawSource;
+  const now = resolveNow(opts);
+  const raf = resolveRaf(opts);
+  const caf = resolveCaf(opts);
+  let state = "idle";
+  let lastTimestamp = 0;
+  let pendingFrameId = 0;
+  let profilerFrameId = 0;
+  let profilerCaptureId;
+  let primaryAttached = false;
+  let activeInjectedWorlds;
+  let nextInjectedWorlds;
+  function attachPrimary(fireError) {
+    if (primaryAttached) return;
+    try {
+      const result = renderer.attachWorld(world);
+      primaryAttached = result.ok;
+      if (!result.ok) fireError(result.error);
+    } catch (cause) {
+      fireError(makeWorldUpdateError(cause));
+    }
+  }
+  function syncInjectedAttachments(worlds, fireError) {
+    if (worlds === void 0) {
+      if (activeInjectedWorlds !== void 0) {
+        for (const attached of activeInjectedWorlds) renderer.detachWorld(attached);
+        activeInjectedWorlds.clear();
+      }
+      return void 0;
+    }
+    const next = nextInjectedWorlds ?? /* @__PURE__ */ new Set();
+    nextInjectedWorlds = next;
+    next.clear();
+    const active = activeInjectedWorlds;
+    for (const candidate of worlds) {
+      if (candidate === world || next.has(candidate)) continue;
+      if (active?.has(candidate) === true) {
+        next.add(candidate);
+        continue;
+      }
+      try {
+        const result = renderer.attachWorld(candidate);
+        if (result.ok) next.add(candidate);
+        else fireError?.(result.error);
+      } catch (cause) {
+        fireError?.(makeWorldUpdateError(cause));
+      }
+    }
+    if (active !== void 0) {
+      for (const attached of active) {
+        if (!next.has(attached)) renderer.detachWorld(attached);
+      }
+      active.clear();
+    }
+    activeInjectedWorlds = next;
+    nextInjectedWorlds = active;
+    return next;
+  }
+  function releaseInjectedAttachments() {
+    syncInjectedAttachments(void 0);
+  }
+  function releaseAttachments() {
+    releaseInjectedAttachments();
+    if (!primaryAttached) return;
+    renderer.detachWorld(world);
+    primaryAttached = false;
+  }
+  function runProfiledPhase(session, phase, action) {
+    const opened = beginPhase(session, phase);
+    try {
+      return action();
+    } finally {
+      if (opened) endPhase(session);
+    }
+  }
+  function runFrame(deltaSeconds) {
+    const session = opts.profiler?.activeSession();
+    let profileFrame;
+    let frameError;
+    let primaryUpdated = false;
+    const reportError = (error) => {
+      frameError ??= error;
+      opts.onError?.(error);
+    };
+    if (session !== void 0) {
+      if (profilerCaptureId !== session.captureId) {
+        profilerCaptureId = session.captureId;
+        profilerFrameId = 0;
+      }
+      const frameId = ++profilerFrameId;
+      if (beginFrame(session, frameId)) {
+        profileFrame = { captureId: session.captureId, frameId };
+      }
+    }
+    runProfiledPhase(session, "frame-total", () => {
+      attachPrimary(reportError);
+      runProfiledPhase(session, "world-update-primary", () => {
+        try {
+          if (fireWorldUpdateResult(world.update(deltaSeconds), reportError)) {
+            primaryUpdated = true;
+          }
+        } catch (cause) {
+          reportError(makeWorldUpdateError(cause));
+        }
+      });
+      let injected;
+      runProfiledPhase(session, "draw-source", () => {
+        if (drawSource === void 0) return;
+        try {
+          injected = drawSource();
+        } catch (cause) {
+          reportError(makeWorldUpdateError(cause));
+        }
+      });
+      const attachedInjectedWorlds = syncInjectedAttachments(injected?.worlds, reportError);
+      const updatedWorlds = injected === void 0 ? void 0 : /* @__PURE__ */ new Set();
+      if (updatedWorlds !== void 0 && primaryUpdated && primaryAttached) {
+        updatedWorlds.add(world);
+      }
+      runProfiledPhase(session, "world-update-injected", () => {
+        if (injected !== void 0 && attachedInjectedWorlds !== void 0 && updatedWorlds !== void 0) {
+          updateInjectedWorlds(
+            injected.worlds,
+            world,
+            deltaSeconds,
+            reportError,
+            attachedInjectedWorlds,
+            updatedWorlds
+          );
+        }
+      });
+      runProfiledPhase(session, "renderer-draw", () => {
+        try {
+          const profileOptions = profileFrame === void 0 ? {} : { profileFrame };
+          let drawResult;
+          if (injected === void 0) {
+            if (!primaryUpdated || !primaryAttached) return;
+            drawResult = renderer.draw(primaryDrawWorlds, {
+              cameraOwner: 0,
+              resourceOwner: 0,
+              ...profileOptions
+            });
+          } else {
+            if (updatedWorlds === void 0) return;
+            const readyWorlds = injected.worlds.filter((candidate) => updatedWorlds.has(candidate));
+            const cameraWorld = injected.worlds[injected.cameraOwner];
+            const resourceWorld = injected.worlds[injected.resourceOwner];
+            const cameraOwner = cameraWorld === void 0 ? -1 : readyWorlds.indexOf(cameraWorld);
+            const resourceOwner = resourceWorld === void 0 ? -1 : readyWorlds.indexOf(resourceWorld);
+            if (readyWorlds.length === 0 || cameraOwner < 0 || resourceOwner < 0) return;
+            drawResult = renderer.draw(readyWorlds, {
+              cameraOwner,
+              resourceOwner,
+              ...profileOptions
+            });
+          }
+          if (drawResult !== void 0) {
+            const result = drawResult;
+            if (!result.ok && result.error !== void 0) {
+              reportError(result.error);
+            }
+          }
+        } catch (cause) {
+          reportError(makeWorldUpdateError(cause));
+        }
+      });
+    });
+    endFrame(session);
+    return frameError === void 0 ? ok(void 0) : err(frameError);
+  }
+  function tick() {
+    if (state !== "running") return;
+    if (renderer.health?.().reason === "device-lost") {
+      pendingFrameId = raf(tick);
+      return;
+    }
+    const timestamp = now();
+    const deltaSeconds = (timestamp - lastTimestamp) / 1e3;
+    lastTimestamp = timestamp;
+    runFrame(deltaSeconds);
+    pendingFrameId = raf(tick);
+  }
+  function releaseProfiler() {
+    finishProfilerCapture(opts.profiler);
+    releasePhaseCatalog?.();
+    releasePhaseCatalog = void 0;
+  }
+  return {
+    setDrawSource(nextDrawSource) {
+      if (drawSource !== nextDrawSource) syncInjectedAttachments(void 0);
+      drawSource = nextDrawSource;
+    },
+    stepFrame(deltaSeconds) {
+      const reason = state !== "paused" ? "state" : !Number.isFinite(deltaSeconds) || deltaSeconds < 0 ? "delta" : void 0;
+      if (reason !== void 0) {
+        return err(
+          makeAppError(
+            "app-frame-step-invalid",
+            'state is "paused" and deltaSeconds is finite and non-negative',
+            "pause the App and pass a finite non-negative delta before retrying",
+            { state, deltaSeconds, reason }
+          )
+        );
+      }
+      return runFrame(deltaSeconds);
+    },
+    start() {
+      if (state === "running") {
+        return err(
+          makeAppError(
+            "app-already-running",
+            'state must be "idle" or "paused" to start',
+            "call stop() first or check getState() before retrying",
+            {}
+          )
+        );
+      }
+      if (state === "stopped") {
+        return err(
+          makeAppError(
+            "app-not-started",
+            'frame-loop is in terminal "stopped" state',
+            "create a new App via createApp({...}); the existing handle is dead",
+            {}
+          )
+        );
+      }
+      lastTimestamp = now();
+      state = "running";
+      pendingFrameId = raf(tick);
+      return ok(void 0);
+    },
+    stop() {
+      if (state === "idle") {
+        return err(
+          makeAppError(
+            "app-not-started",
+            'state must be "running" to stop',
+            "check getState() before calling stop(); idle handles cannot stop",
+            {}
+          )
+        );
+      }
+      if (state === "stopped") {
+        return err(
+          makeAppError(
+            "app-not-started",
+            'frame-loop is in terminal "stopped" state',
+            "discard this handle and create a new App",
+            {}
+          )
+        );
+      }
+      caf(pendingFrameId);
+      pendingFrameId = 0;
+      state = "stopped";
+      releaseAttachments();
+      releaseProfiler();
+      return ok(void 0);
+    },
+    pause() {
+      if (state === "paused") return ok(void 0);
+      if (state !== "running") {
+        return err(
+          makeAppError(
+            "app-not-started",
+            'state must be "running" or "paused" to pause',
+            "call start() first; idle handles cannot pause",
+            {}
+          )
+        );
+      }
+      caf(pendingFrameId);
+      pendingFrameId = 0;
+      state = "paused";
+      return ok(void 0);
+    },
+    resume() {
+      if (state === "idle" || state === "stopped") {
+        return err(
+          makeAppError(
+            "app-not-started",
+            'state must be "paused" to resume',
+            "call start() first to leave idle; resume() expects an active handle",
+            {}
+          )
+        );
+      }
+      if (state === "running") return ok(void 0);
+      lastTimestamp = now();
+      state = "running";
+      pendingFrameId = raf(tick);
+      return ok(void 0);
+    },
+    getState() {
+      return state;
+    },
+    setStopped() {
+      if (pendingFrameId !== 0) {
+        caf(pendingFrameId);
+        pendingFrameId = 0;
+      }
+      releaseAttachments();
+      releaseProfiler();
+      state = "stopped";
+    }
+  };
+}
+function attachInputAuto(canvas, options = {}) {
+  let onLockErrorDispatch;
+  const backendOpts = {
+    ...options.uiRoot ? { uiRoot: options.uiRoot } : {},
+    ...options.pointerLockAllowed ? { pointerLockAllowed: options.pointerLockAllowed } : {},
+    ...options.virtualJoysticks ? { virtualJoysticks: options.virtualJoysticks } : {},
+    ...options.lockProvider ? { lockProvider: options.lockProvider } : {},
+    onLockError: (detail) => {
+      if (onLockErrorDispatch) {
+        const err13 = new AppError({
+          code: "app-pointer-lock-failed",
+          expected: APP_EXPECTED["app-pointer-lock-failed"],
+          hint: APP_ERROR_HINTS["app-pointer-lock-failed"],
+          detail
+        });
+        onLockErrorDispatch(err13);
+      }
+    }
+  };
+  const detach = attachBrowserInputBackend(canvas, backendOpts);
+  const backend = detach.backend;
+  let cleanedUp = false;
+  return {
+    backend,
+    setOnErrorDispatch(fn) {
+      onLockErrorDispatch = fn;
+    },
+    cleanup() {
+      if (cleanedUp) {
+        return;
+      }
+      cleanedUp = true;
+      detach();
+    }
+  };
+}
+function inputMapPlugin(configs) {
+  const deduped = /* @__PURE__ */ new Map();
+  for (const config of configs) {
+    if (config.action.length > 0) deduped.set(config.action, config);
+  }
+  const inputMap = Object.freeze([...deduped.values()]);
+  return {
+    name: "input-map",
+    inject: ["world"],
+    apply(ctx) {
+      ctx.effect(() => {
+        ctx.world.insertResource(INPUT_MAP_KEY, inputMap);
+        return () => ctx.world.removeResource(INPUT_MAP_KEY);
+      }, "input/action-map");
+    }
+  };
+}
+function inputPlugin() {
+  return {
+    name: "input",
+    inject: ["world", "input"],
+    apply(ctx) {
+      const world = ctx.world;
+      const input = ctx.input;
+      if (input === void 0) throw new Error("Cordis activated input without its provider");
+      ctx.effect(() => {
+        world.insertResource(INPUT_BACKEND_KEY, input);
+        return () => {
+          world.removeResource(INPUT_BACKEND_KEY);
+        };
+      }, "input/resource");
+      ctx.effect(() => {
+        world.addSystems(Update, InputSet, [InputFrameStartScan]).unwrap();
+        return () => world.removeSystem(Update, InputFrameStartScan.name);
+      }, "input/frame-start-scan");
+    }
+  };
+}
+
+// src/internal/main-engine-profile.ts
+function debugDrawPlugin(onReady) {
+  return {
+    name: "debug-draw",
+    inject: ["renderer"],
+    async apply(ctx) {
+      if (ctx.renderer === void 0) throw new Error("debug draw requires the renderer service");
+      try {
+        const debugDraw = await createDebugDrawOnReady(ctx.renderer);
+        onReady(debugDraw);
+        ctx.effect(() => () => releaseDebugDraw(debugDraw), "render/debug-draw");
+      } catch {
+      }
+    }
+  };
+}
+function mainEngineProfile(options) {
+  return [
+    ownedRendererPlugin(options.renderer),
+    renderComponentsPlugin(),
+    rendererAssetsPlugin(),
+    ...options.assetAssembly === void 0 ? [] : [assetRegistryPlugin(options.assetAssembly), assetRegistryWorldPlugin()],
+    assetsWorldPlugin(),
+    ...options.input === void 0 ? [] : [
+      options.inputDispose === void 0 ? inputBackendPlugin(options.input) : ownedInputBackendPlugin(options.input, options.inputDispose)
+    ],
+    scenePlugin(),
+    animationPayloadsPlugin(options.animationPayloads),
+    animationRuntimePlugin(),
+    statePlugin(),
+    ...options.onDebugDrawReady === void 0 ? [] : [debugDrawPlugin(options.onDebugDrawReady)],
+    ...options.input === void 0 ? [] : [inputPlugin()],
+    ...options.inputMap === void 0 ? [] : [inputMapPlugin(options.inputMap)],
+    ...options.extensions ?? []
+  ];
+}
+
+// src/internal/remote-serve-flag.ts
+function resolveRemoteServeFlag(isDev, processEnv, isBrowser = false) {
+  if (isBrowser) return false;
+  if (isDev === true) return true;
+  if (processEnv?.FORGEAX_ENGINE_REMOTE_SERVE === "1") return true;
+  return false;
+}
+
+// src/internal/remote-server-plugin.ts
+function remoteServerPlugin(handle) {
+  return {
+    name: "remote-server",
+    apply(ctx) {
+      ctx.effect(() => async () => handle.close(), "remote/server");
+    }
+  };
+}
+var captureDrivers = /* @__PURE__ */ new WeakMap();
+function createRhiCapture(attachment) {
+  let activeCapture;
+  const capture = {
+    captureFrame(options) {
+      const driver = captureDrivers.get(capture);
+      if (driver === void 0) return captureAttachment(attachment, options);
+      if (activeCapture !== void 0) {
+        return Promise.resolve(
+          err(
+            createRhiDebugError("capture-busy", {
+              stage: "capture",
+              cause: "another App capture transaction is active"
+            })
+          )
+        );
+      }
+      const request = captureWithAppFrame(attachment, driver, options);
+      activeCapture = request;
+      void request.then(
+        () => {
+          if (activeCapture === request) activeCapture = void 0;
+        },
+        () => {
+          if (activeCapture === request) activeCapture = void 0;
+        }
+      );
+      return request;
+    }
+  };
+  return capture;
+}
+function bindRhiCaptureFrameDriver(capture, driver) {
+  captureDrivers.set(capture, driver);
+}
+async function captureAttachment(attachment, options) {
+  const result = await attachment.captureFrame(options);
+  if (!result.ok) return result;
+  return ok(toArtifact(result.value));
+}
+async function captureWithAppFrame(attachment, driver, options) {
+  const state = driver.getState();
+  if (state !== "running" && state !== "paused") {
+    return err(
+      createRhiDebugError("capture-unavailable", {
+        stage: "capture",
+        cause: `App capture requires a running or paused frame loop, received '${state}'`
+      })
+    );
+  }
+  if (options?.signal?.aborted) return captureAttachment(attachment, options);
+  const resumeAfter = state === "running";
+  if (resumeAfter) {
+    const paused = driver.pause();
+    if (!paused.ok) {
+      return err(
+        createRhiDebugError("capture-unavailable", {
+          stage: "capture",
+          cause: `App capture could not pause the frame loop: ${describeFailure(paused.error)}`
+        })
+      );
+    }
+  }
+  const controller = new AbortController();
+  const abortFromUser = () => controller.abort();
+  options?.signal?.addEventListener("abort", abortFromUser, { once: true });
+  let captureResult;
+  try {
+    captureResult = attachment.captureFrame({
+      ...options ?? {},
+      signal: controller.signal
+    });
+  } catch (cause) {
+    options?.signal?.removeEventListener("abort", abortFromUser);
+    if (resumeAfter && driver.getState() === "paused") driver.resume();
+    return err(
+      createRhiDebugError("capture-unavailable", {
+        stage: "capture",
+        cause: `App capture could not arm the recorder: ${describeFailure(cause)}`
+      })
+    );
+  }
+  let result;
+  let transactionError;
+  try {
+    const snapshot = await attachment.frameBoundary();
+    if (!snapshot.ok) {
+      result = await captureResult;
+    } else if (options?.signal?.aborted) {
+      controller.abort();
+      result = await captureResult;
+    } else {
+      const stepped = driver.stepFrame(0);
+      if (!stepped.ok) {
+        transactionError = createRhiDebugError("capture-unavailable", {
+          stage: "capture",
+          cause: `App capture frame failed: ${describeFailure(stepped.error)}`
+        });
+        controller.abort();
+        result = await captureResult;
+      } else {
+        result = await captureResult;
+      }
+    }
+  } catch (cause) {
+    transactionError = createRhiDebugError("capture-unavailable", {
+      stage: "capture",
+      cause: `App capture transaction failed: ${describeFailure(cause)}`
+    });
+    controller.abort();
+    result = await captureResult;
+  } finally {
+    options?.signal?.removeEventListener("abort", abortFromUser);
+    if (resumeAfter && driver.getState() === "paused") {
+      const resumed = driver.resume();
+      if (!resumed.ok && transactionError === void 0) {
+        transactionError = createRhiDebugError("capture-unavailable", {
+          stage: "capture",
+          cause: `App capture could not resume the frame loop: ${describeFailure(resumed.error)}`
+        });
+      }
+    }
+  }
+  if (transactionError !== void 0) return err(transactionError);
+  if (result === void 0) result = await captureResult;
+  if (!result.ok) return result;
+  return ok(toArtifact(result.value));
+}
+function describeFailure(cause) {
+  if (typeof cause === "string") return cause;
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === "object" && cause !== null && "hint" in cause) {
+    const hint = cause.hint;
+    if (typeof hint === "string") return hint;
+  }
+  return String(cause);
+}
+function createRhiInstrumentation(attachment) {
+  return {
+    resolveSurfaceDevice(device) {
+      const resolved = attachment.backend.unwrapDeviceForSurface(device);
+      if (resolved.ok) return resolved;
+      return err(
+        new RhiError({
+          code: "rhi-not-available",
+          expected: "the recorder can resolve the wrapped surface device",
+          hint: resolved.error.hint
+        })
+      );
+    },
+    onFrameBoundary() {
+      void attachment.frameBoundary();
+    },
+    onDeviceLost() {
+      attachment.deviceLost();
+    }
+  };
+}
+function toArtifact(encoded) {
+  return {
+    kind: "rhi-tape",
+    digest: encoded.digest,
+    bytes: encoded.bytes
+  };
+}
+
+// src/internal/rhi-debug-flag.ts
+function resolveRhiDebugFlag(importMetaEnv, processEnv) {
+  return importMetaEnv?.FORGEAX_ENGINE_RHI_DEBUG ?? processEnv?.FORGEAX_ENGINE_RHI_DEBUG;
+}
+
+// src/create-app.ts
+var DEFAULT_ASSET_CATALOG_PATH = "pack-index.json";
+function defaultAssetCatalogUrl() {
+  const base = typeof document !== "undefined" ? document.baseURI : globalThis.location?.href;
+  return base === void 0 ? DEFAULT_ASSET_CATALOG_PATH : new URL(DEFAULT_ASSET_CATALOG_PATH, base).href;
+}
+function assembleAppAssetRuntime(catalog, contributions) {
+  const registry = createAssetRegistry({
+    catalog: catalog ?? createCatalogSource({ url: defaultAssetCatalogUrl() })
+  });
+  const assembled = assembleAssetRuntime(registry, contributions ?? []);
+  if (!assembled.ok) registry.dispose();
+  return assembled;
+}
+function makeAppError2(code, expected, hint, detail) {
+  return new AppError({ code, expected, hint, detail });
+}
+function normalizeExecutionBootstrapUrl(bootstrap) {
+  const moduleUrl = typeof bootstrap === "string" ? bootstrap : bootstrap.href;
+  try {
+    return ok(new URL(bootstrap, globalThis.location?.href).href);
+  } catch (cause) {
+    return err(
+      makeAppError2(
+        "app-execution-bootstrap-failed",
+        APP_EXPECTED["app-execution-bootstrap-failed"],
+        APP_ERROR_HINTS["app-execution-bootstrap-failed"],
+        { phase: "prepare", moduleUrl, cause }
+      )
+    );
+  }
+}
+function canvasAspectPlugin(canvas, maxCanvasPixelRatio) {
+  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) {
+  return {
+    name: "rhi-debug-host",
+    apply(ctx) {
+      ctx.effect(() => dispose, "rhi-debug/host");
+    }
+  };
+}
+function createApp(arg, opts, bundler) {
+  if ("tagName" in arg) {
+    return createAppFromCanvas(arg, opts, bundler);
+  }
+  return createAppFromAssemble(arg);
+}
+async function createAppFromCanvas(canvas, opts, bundler) {
+  const maxCanvasPixelRatio = opts?.maxCanvasPixelRatio;
+  if (maxCanvasPixelRatio !== void 0 && (!Number.isFinite(maxCanvasPixelRatio) || maxCanvasPixelRatio <= 0)) {
+    return err(
+      makeAppError2(
+        "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(
+      makeAppError2(
+        "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 === void 0 ? void 0 : normalizeExecutionBootstrapUrl(executionOptions.bootstrap);
+  if (normalizedExecutionBootstrap?.ok === false) {
+    return err(normalizedExecutionBootstrap.error);
+  }
+  syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio);
+  if (opts?.execution !== void 0 && 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 !== void 0)?.[0];
+    if (realmBoundOption !== void 0) {
+      return err(
+        makeAppError2(
+          "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;
+  let preparedExecutionBootstrap;
+  if (opts?.execution !== void 0 && normalizedExecutionBootstrap?.ok === true) {
+    const executionOptions2 = opts.execution;
+    const capabilities = await probeExecutionCapabilities(canvas);
+    const selected = selectExecutionTier({
+      requestedTier: executionOptions2.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 !== void 0 ? { bundler } : {},
+        capabilities,
+        selection: selected.value
+      });
+    }
+    const prepared = await prepareBootstrapEntry(
+      normalizedExecutionBootstrap.value,
+      executionOptions2.bootstrapData
+    );
+    if (!prepared.ok) return err(prepared.error);
+    preparedExecutionBootstrap = prepared.value;
+  }
+  const rendererOpts = {};
+  if (opts?.rhi !== void 0) {
+    Object.assign(rendererOpts, { rhi: opts.rhi });
+  }
+  if (opts?.rhiInstrumentation !== void 0) {
+    Object.assign(rendererOpts, { rhiInstrumentation: opts.rhiInstrumentation });
+  }
+  if (opts?.rawDeviceForContextConfigure !== void 0) {
+    Object.assign(rendererOpts, {
+      rawDeviceForContextConfigure: opts.rawDeviceForContextConfigure
+    });
+  }
+  if (opts?.profiler !== void 0) {
+    Object.assign(rendererOpts, { profiler: opts.profiler });
+  }
+  if (opts?.membershipTiming !== void 0) {
+    Object.assign(rendererOpts, { membershipTiming: opts.membershipTiming });
+  }
+  const rendererFeatures = preparedExecutionBootstrap?.features ?? opts?.features;
+  if (rendererFeatures !== void 0) {
+    Object.assign(rendererOpts, { features: rendererFeatures });
+  }
+  let rhiAttachment;
+  let rhiCapture;
+  let rhiDebugGlobal;
+  const cleanupRhiDebugHost = () => {
+    const host = globalThis;
+    if (host.__forgeax === rhiDebugGlobal) delete host.__forgeax;
+    rhiDebugGlobal = void 0;
+    const attachment = rhiAttachment;
+    rhiAttachment = void 0;
+    if (attachment !== void 0) void attachment.dispose();
+  };
+  const importMetaEnv = typeof import.meta !== "undefined" ? { FORGEAX_ENGINE_RHI_DEBUG: import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG } : void 0;
+  const browserBuildRhiDebugFlag = typeof import.meta !== "undefined" ? import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG : void 0;
+  const processEnv = globalThis.process?.env;
+  const rhiDebugFlag = resolveRhiDebugFlag(importMetaEnv, processEnv);
+  const nav = typeof globalThis !== "undefined" ? globalThis.navigator : void 0;
+  const hasWebGPU = nav !== void 0 && "gpu" in nav && nav.gpu !== void 0;
+  if (opts?.rhi === void 0 && (browserBuildRhiDebugFlag === void 0 || 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 === void 0) {
+      throw new Error("RHI debug capture requires the backend shader-module entry");
+    }
+    const createShaderModule = 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.__forgeax = rhiDebugGlobal;
+  }
+  const assetAssemblyResult = assembleAppAssetRuntime(opts?.assetCatalog, opts?.assetDecoders);
+  if (!assetAssemblyResult.ok) {
+    cleanupRhiDebugHost();
+    return err(assetAssemblyResult.error);
+  }
+  const assetAssembly = assetAssemblyResult.value;
+  let renderer;
+  try {
+    renderer = await createRenderer(canvas, rendererOpts, {
+      ...bundler,
+      assetResolver: getAssetRegistryResolver(assetAssembly.registry)
+    });
+  } catch (e) {
+    cleanupRhiDebugHost();
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    if (e instanceof EngineEnvironmentError) {
+      return err(e);
+    }
+    throw e;
+  }
+  const shouldStartRemote = resolveRemoteServeFlag(
+    typeof import.meta !== "undefined" ? import.meta.env?.DEV : void 0,
+    globalThis.process?.env,
+    typeof window !== "undefined"
+  );
+  let debugDraw;
+  const world = new World(opts?.time !== void 0 ? { time: opts.time } : {});
+  const inputHandle = opts?.input === void 0 ? attachInputAuto(canvas, {
+    ...opts?.uiRoot ? { uiRoot: opts.uiRoot } : {},
+    ...opts?.pointerLockAllowed ? { pointerLockAllowed: opts.pointerLockAllowed } : {},
+    ...opts?.virtualJoysticks ? { virtualJoysticks: opts.virtualJoysticks } : {},
+    ...opts?.lockProvider ? { lockProvider: opts.lockProvider } : {}
+  }) : void 0;
+  const inputBackend = opts?.input ?? inputHandle?.backend;
+  const userPlugins = preparedExecutionBootstrap === void 0 ? opts?.plugins ?? [] : [
+    executionBootstrapHostPlugin({
+      ...opts?.execution?.bootstrapPort === void 0 ? {} : { port: opts.execution.bootstrapPort },
+      setPointerLockAllowed: (allowed) => inputBackend?.setPointerLockAllowed?.(allowed)
+    }),
+    ...preparedExecutionBootstrap.plugins ?? []
+  ];
+  let pluginContext;
+  try {
+    pluginContext = await createWorldContext(
+      world,
+      mainEngineProfile({
+        renderer,
+        assetAssembly,
+        animationPayloads: createAnimationPayloadLookup(renderer.assets),
+        ...inputBackend === void 0 ? {} : { input: inputBackend },
+        ...inputHandle === void 0 ? {} : { inputDispose: inputHandle.cleanup },
+        ...opts?.inputMap === void 0 ? {} : { inputMap: opts.inputMap },
+        onDebugDrawReady: (value) => {
+          debugDraw = value;
+        },
+        extensions: [
+          rhiDebugHostPlugin(cleanupRhiDebugHost),
+          ...userPlugins,
+          canvasAspectPlugin(canvas, maxCanvasPixelRatio)
+        ]
+      })
+    );
+  } catch (cause) {
+    cleanupRhiDebugHost();
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    return err(
+      makeAppError2(
+        "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 === void 0 ? {
+      ...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 === void 0 ? {} : { audio: () => audioBackend.getState() },
+      world: () => ({
+        identity: world.identity,
+        health: world.execution.health,
+        partialWrite: world.execution.fault?.partialWrite ?? false,
+        retryable: world.execution.fault?.retryable ?? true
+      })
+    }
+  );
+  const remoteHandle = shouldStartRemote ? await startRemoteServer(
+    world,
+    renderer,
+    assetAssembly.registry,
+    rhiCapture,
+    opts?.profiler,
+    executionControl
+  ) : void 0;
+  if (remoteHandle !== void 0) await pluginContext.plugin(remoteServerPlugin(remoteHandle));
+  const buildArgs = {
+    renderer,
+    assets: assetAssembly.registry,
+    world,
+    pluginContext,
+    executionControl,
+    ...inputBackend !== void 0 ? { inputBackend } : {},
+    ...inputHandle === void 0 ? {} : {
+      wireOnLockErrorDispatch: (dispatch) => {
+        inputHandle.setOnErrorDispatch(dispatch);
+      }
+    }
+  };
+  if (audioBackend !== void 0) {
+    Object.assign(buildArgs, {
+      audioBackend
+    });
+  }
+  if (opts?.silenceUnhandledErrors !== void 0) {
+    Object.assign(buildArgs, { silenceUnhandledErrors: opts.silenceUnhandledErrors });
+  }
+  if (opts?.drawSource !== void 0) {
+    Object.assign(buildArgs, { drawSource: opts.drawSource });
+  }
+  if (opts?.profiler !== void 0) {
+    Object.assign(buildArgs, { profiler: opts.profiler });
+  }
+  if (rhiCapture !== void 0) {
+    Object.assign(buildArgs, {
+      rhiCapture,
+      ...rhiAttachment === void 0 ? {} : { rhiAttachment }
+    });
+  }
+  if (debugDraw !== void 0) {
+    Object.assign(buildArgs, { debugDraw });
+  }
+  if (remoteHandle !== void 0) {
+    Object.assign(buildArgs, { remoteHandle });
+  }
+  const built = await buildApp(buildArgs);
+  if (!built.ok) {
+    await pluginContext.fiber.dispose();
+    return built;
+  }
+  if (built.ok) {
+    if (typeof import.meta !== "undefined" && import.meta.env?.DEV === true && import.meta.env?.VITE_FORGEAX_ENGINE_BRIDGE === "1") {
+      const bridgePort = import.meta.env?.VITE_FORGEAX_ENGINE_BRIDGE_PORT ?? "5733";
+      await pluginContext.plugin({
+        name: "browser-remote-bridge",
+        inject: ["world", "renderer", "assetRegistry"],
+        async apply(ctx) {
+          if (ctx.renderer === void 0 || ctx.assetRegistry === void 0) {
+            throw new Error("browser remote bridge requires renderer and assetRegistry services");
+          }
+          try {
+            const bridge = await Promise.resolve().then(() => (init_browser_remote_bridge(), browser_remote_bridge_exports));
+            const teardown = await bridge.installBrowserRemoteBridge({
+              world: ctx.world,
+              renderer: ctx.renderer,
+              assets: ctx.assetRegistry,
+              runtimeModule: engineRuntimeModule,
+              ...rhiCapture !== void 0 ? { rhiCapture } : {},
+              ...opts?.profiler !== void 0 ? { profiler: opts.profiler } : {},
+              execution: built.value.execution,
+              port: bridgePort
+            });
+            ctx.effect(() => teardown, "remote/browser-bridge");
+          } catch {
+          }
+        }
+      });
+    }
+  }
+  return built;
+}
+function syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio) {
+  const size = resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio);
+  if (size === void 0) 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;
+}
+function measureCanvasDrawingBuffer(canvas, maxCanvasPixelRatio) {
+  return resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio) ?? {
+    width: canvas.width,
+    height: canvas.height
+  };
+}
+function resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio) {
+  if (!Number.isFinite(canvas.clientWidth) || !Number.isFinite(canvas.clientHeight) || canvas.clientWidth <= 0 || canvas.clientHeight <= 0)
+    return void 0;
+  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 === void 0 || !Number.isFinite(maxCanvasPixelRatio) || maxCanvasPixelRatio <= 0 ? devicePixelRatio : Math.min(devicePixelRatio, maxCanvasPixelRatio);
+  const previous = syncedCanvasSizes.get(canvas);
+  const drawingBufferIsTheLayoutMeasurement = previous !== void 0 && 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 };
+}
+var syncedCanvasSizes = /* @__PURE__ */ new WeakMap();
+async function startRemoteServer(world, renderer, assets, rhiCapture, profiler, execution) {
+  try {
+    const remoteServerMod = await import(
+      /* @vite-ignore */
+      '@forgeax/engine-remote/server'
+    );
+    const serverResult = await remoteServerMod.startServer({
+      port: 0,
+      host: "127.0.0.1",
+      world,
+      renderer,
+      assets,
+      introspection: projectComponentIntrospection(world.components.entries()),
+      ...rhiCapture !== void 0 ? { rhiCapture } : {},
+      ...profiler !== void 0 ? { profiler } : {},
+      execution
+    });
+    if (serverResult.ok && serverResult.value !== void 0) {
+      return { port: serverResult.value.port, close: serverResult.value.close };
+    }
+  } catch (_error) {
+  }
+  return void 0;
+}
+async function createAppFromAssemble(args) {
+  const assetAssemblyResult = assembleAppAssetRuntime(args.assetCatalog, args.assetDecoders);
+  if (!assetAssemblyResult.ok) return err(assetAssemblyResult.error);
+  const assetAssembly = assetAssemblyResult.value;
+  let pluginContext;
+  try {
+    pluginContext = await createWorldContext(
+      args.world,
+      assembledEngineProfile({
+        renderer: args.renderer,
+        assetAssembly,
+        extensions: args.plugins ?? []
+      })
+    );
+  } catch (cause) {
+    assetAssembly.dispose();
+    assetAssembly.registry.dispose();
+    return err(
+      makeAppError2(
+        "app-plugin-activation-failed",
+        APP_EXPECTED["app-plugin-activation-failed"],
+        APP_ERROR_HINTS["app-plugin-activation-failed"],
+        { cause }
+      )
+    );
+  }
+  const shouldStartRemote = resolveRemoteServeFlag(
+    void 0,
+    globalThis.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 === void 0 ? {} : { 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,
+    void 0,
+    args.profiler,
+    executionControl
+  ) : void 0;
+  if (remoteHandle !== void 0) await pluginContext.plugin(remoteServerPlugin(remoteHandle));
+  const buildArgs = {
+    renderer: args.renderer,
+    assets: assetAssembly.registry,
+    world: args.world,
+    pluginContext,
+    executionControl,
+    ...remoteHandle !== void 0 ? { remoteHandle } : {}
+  };
+  const assembledInputBackend = pluginContext.input;
+  if (assembledInputBackend !== void 0) {
+    Object.assign(buildArgs, {
+      inputBackend: assembledInputBackend
+    });
+  }
+  if (assembledAudioBackend !== void 0) {
+    Object.assign(buildArgs, {
+      audioBackend: assembledAudioBackend
+    });
+  }
+  if (args.silenceUnhandledErrors !== void 0) {
+    Object.assign(buildArgs, { silenceUnhandledErrors: args.silenceUnhandledErrors });
+  }
+  if (args.drawSource !== void 0) {
+    Object.assign(buildArgs, { drawSource: args.drawSource });
+  }
+  if (args.profiler !== void 0) {
+    Object.assign(buildArgs, { profiler: args.profiler });
+  }
+  const built = await buildApp(buildArgs);
+  if (!built.ok) await pluginContext.fiber.dispose();
+  return built;
+}
+async function buildApp(args) {
+  const {
+    renderer,
+    assets,
+    world,
+    pluginContext,
+    inputBackend,
+    audioBackend,
+    silenceUnhandledErrors,
+    rhiCapture,
+    rhiAttachment,
+    debugDraw,
+    remoteHandle,
+    profiler
+  } = args;
+  function readPhysicsWorld() {
+    return pluginContext.physics;
+  }
+  const fanout = new ErrorFanoutRegistry(
+    silenceUnhandledErrors !== void 0 ? { 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 === void 0 ? {} : { 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) {
+    fanout.fire(e);
+  }
+  if (args.wireOnLockErrorDispatch) {
+    args.wireOnLockErrorDispatch(dispatch);
+  }
+  const loopOpts = {
+    world,
+    renderer,
+    onError: dispatch
+  };
+  if (args.drawSource !== void 0) {
+    Object.assign(loopOpts, { drawSource: args.drawSource });
+  }
+  if (profiler !== void 0) {
+    Object.assign(loopOpts, { profiler });
+  }
+  const loop = createFrameLoop(loopOpts);
+  if (rhiCapture !== void 0 && rhiAttachment !== void 0) {
+    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;
+  let rendererUnsubscribe;
+  let resumeAfterSurfaceRestore = false;
+  function subscribeRendererErrors() {
+    if (rendererUnsubscribe !== void 0) {
+      return;
+    }
+    rendererUnsubscribe = renderer.onError((e) => {
+      if (e?.code === "device-lost") {
+        lastError = e;
+      }
+      dispatch(e);
+    });
+  }
+  function unsubscribeRendererErrors() {
+    if (rendererUnsubscribe !== void 0) {
+      rendererUnsubscribe();
+      rendererUnsubscribe = void 0;
+    }
+  }
+  const stub = {
+    renderer,
+    assets,
+    world,
+    execution,
+    async releaseSurfacePreserveWorld() {
+      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");
+      }
+      await Promise.resolve();
+      const released = renderer.releaseSurface();
+      if (!released.ok && resumeAfterSurfaceRestore) {
+        loop.resume();
+        resumeAfterSurfaceRestore = false;
+        execution.setEngineHealth("running");
+      }
+      return released.ok ? ok(void 0) : err(released.error);
+    },
+    async restoreSurface() {
+      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(void 0);
+    },
+    pluginContext,
+    ...inputBackend !== void 0 ? { input: inputBackend } : {},
+    ...audioBackend !== void 0 ? { audio: audioBackend } : {},
+    get physics() {
+      return readPhysicsWorld();
+    },
+    start() {
+      const r = loop.start();
+      if (r.ok) {
+        execution.setEngineHealth("running");
+        subscribeRendererErrors();
+      }
+      return r;
+    },
+    stop() {
+      const r = loop.stop();
+      if (r.ok) execution.setEngineHealth("stopped");
+      unsubscribeRendererErrors();
+      return r;
+    },
+    async dispose() {
+      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(void 0);
+    },
+    pause() {
+      const r = loop.pause();
+      if (r.ok) execution.setEngineHealth("idle");
+      return r;
+    },
+    resume() {
+      const r = loop.resume();
+      if (r.ok) execution.setEngineHealth("running");
+      return r;
+    },
+    stepFrame(deltaSeconds) {
+      return loop.stepFrame(deltaSeconds);
+    },
+    onError(cb) {
+      return fanout.add(cb);
+    },
+    setDrawSource(drawSource) {
+      loop.setDrawSource(drawSource);
+    },
+    /**
+     * Most recent device-loss error retained for host self-inspection.
+     */
+    get lastError() {
+      return lastError;
+    },
+    ...rhiCapture !== void 0 ? { rhiCapture } : {},
+    ...debugDraw !== void 0 ? { debugDraw } : {},
+    ...remoteHandle !== void 0 ? { remote: remoteHandle } : {}
+  };
+  const readyResult = await renderer.ready;
+  if (!readyResult.ok) {
+    return err(readyResult.error);
+  }
+  return ok(stub);
+}
+function ensureFallbackCamera(world, aspect = 1) {
+  const cameras = world.query({ with: [Camera] }).unwrap();
+  if (!cameras[Symbol.iterator]().next().done) return void 0;
+  return world.spawn(
+    { component: Transform, data: { pos: [0, 0.6, 5] } },
+    { component: Camera, data: perspective({ fov: Math.PI / 3, aspect, far: 1e3 }) }
+  );
+}
+
+// src/game-context.ts
+function gameHostPlugin(host) {
+  return {
+    name: "game-host",
+    provide: "gameHost",
+    apply(ctx) {
+      ctx.provide("gameHost", host);
+    }
+  };
+}
+
+// src/load-game-errors.ts
+var LoadGameErrorClass = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    super(`[LoadGameError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = "LoadGameError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+var LoadGameError = LoadGameErrorClass;
+var loadGameErrorPolicy = {
+  "module-not-found": {
+    expected: "resolver should return a module with a native Cordis default export for the given slug",
+    hint: "verify the game slug matches an existing template directory; check the resolver import path for typos"
+  },
+  "invalid-format": {
+    expected: "resolved module must default-export a Cordis function, class, or object plugin",
+    hint: "default-export one plugin and let the Host mount it into App.pluginContext"
+  },
+  "import-failed": {
+    expected: "resolver should complete without throwing; import path, network, and build errors are forwarded here",
+    hint: "inspect detail.cause for the original error (network failure, build error, dynamic import timeout, etc.)"
+  }
+};
+var LOAD_GAME_EXPECTED = Object.fromEntries(
+  Object.entries(loadGameErrorPolicy).map(([code, policy]) => [code, policy.expected])
+);
+var LOAD_GAME_ERROR_HINTS = Object.fromEntries(
+  Object.entries(loadGameErrorPolicy).map(([code, policy]) => [code, policy.hint])
+);
+function isLoadGameError(err13) {
+  return err13 instanceof LoadGameErrorClass;
+}
+function isPlugin(value) {
+  return typeof value === "function" || typeof value === "object" && value !== null && "apply" in value && typeof value.apply === "function";
+}
+async function loadGame(slug, resolver) {
+  let module;
+  try {
+    module = await resolver(slug);
+  } catch (thrown) {
+    if (thrown instanceof Error && thrown.message.includes(slug)) {
+      return err(
+        new LoadGameError({
+          code: "module-not-found",
+          expected: LOAD_GAME_EXPECTED["module-not-found"],
+          hint: LOAD_GAME_ERROR_HINTS["module-not-found"],
+          detail: { slug }
+        })
+      );
+    }
+    return err(
+      new LoadGameError({
+        code: "import-failed",
+        expected: LOAD_GAME_EXPECTED["import-failed"],
+        hint: LOAD_GAME_ERROR_HINTS["import-failed"],
+        detail: { cause: thrown }
+      })
+    );
+  }
+  if (!isPlugin(module.default)) {
+    const exportKeys = Object.keys(module);
+    return err(
+      new LoadGameError({
+        code: "invalid-format",
+        expected: LOAD_GAME_EXPECTED["invalid-format"],
+        hint: LOAD_GAME_ERROR_HINTS["invalid-format"],
+        detail: { exportKeys }
+      })
+    );
+  }
+  return ok(module.default);
+}
+function hasWebGpu() {
+  const nav = globalThis.navigator;
+  return nav?.gpu !== void 0;
+}
+async function loadBackend() {
+  const backend = hasWebGpu() ? await import('@forgeax/engine-rhi-webgpu') : await import('@forgeax/engine-rhi-wgpu');
+  if (!hasWebGpu()) await backend.ensureReady?.();
+  return backend;
+}
+async function createBrowserRhiDebugRuntime() {
+  const backend = await loadBackend();
+  const attached = attachRecorder(backend);
+  if (!attached.ok) throw new Error(attached.error.hint);
+  const attachment = attached.value;
+  return {
+    rhi: attachment.backend.rhi,
+    attachment,
+    createShaderModule: backend.createShaderModule,
+    rhiInstrumentation: createRhiInstrumentation(attachment),
+    createReplayDevice: async () => {
+      const adapter = await backend.rhi.requestAdapter();
+      if (!adapter.ok) return adapter;
+      return adapter.value.requestDevice();
+    },
+    attachRenderer(_renderer) {
+      return () => {
+      };
+    }
+  };
+}
+function createToolPreviewRecipe(options) {
+  if (options.backend !== void 0 && options.backend !== "webgpu") {
+    throw new TypeError("tool preview requires the real WebGPU backend");
+  }
+  const viewport = options.viewport ?? { width: 640, height: 360 };
+  if (!Number.isSafeInteger(viewport.width) || !Number.isSafeInteger(viewport.height) || viewport.width <= 0 || viewport.height <= 0) {
+    throw new TypeError("tool preview viewport must contain positive safe integers");
+  }
+  const deltaSeconds = options.deltaSeconds ?? 1 / 60;
+  const frames = options.frames ?? 1;
+  if (!Number.isFinite(deltaSeconds) || deltaSeconds < 0) {
+    throw new TypeError("tool preview deltaSeconds must be finite and non-negative");
+  }
+  if (!Number.isSafeInteger(frames) || frames <= 0) {
+    throw new TypeError("tool preview frames must be a positive safe integer");
+  }
+  const actions = (options.actions ?? []).map((action) => ({ ...action }));
+  for (const action of actions) {
+    if (!Number.isSafeInteger(action.frame) || action.frame < 0 || action.frame >= frames || action.name.length === 0 || action.value !== void 0 && !isSerializableValue(action.value)) {
+      throw new TypeError("tool preview actions require a valid frame, name, and JSON value");
+    }
+  }
+  return {
+    backend: "webgpu",
+    presentation: options.presentation ?? "hidden",
+    viewport: { width: viewport.width, height: viewport.height },
+    actions,
+    deltaSeconds,
+    frames
+  };
+}
+var REQUIRED_EVENTS = [
+  "canvas-created",
+  "rhi-debug-armed",
+  "renderer-created",
+  "world-updated",
+  "draw-submitted",
+  "validation-complete"
+];
+function validateToolPreviewTrace(trace) {
+  if (trace.backend !== "webgpu") {
+    return {
+      ok: false,
+      error: {
+        code: "tool-preview-invalid-trace",
+        expected: 'trace.backend === "webgpu"',
+        hint: "run the same recipe with a real WebGPU adapter; RHI-null is not a preview backend",
+        detail: { missing: "webgpu-backend", index: -1 }
+      }
+    };
+  }
+  let last = -1;
+  for (const event of REQUIRED_EVENTS) {
+    const index = trace.events.indexOf(event);
+    if (index <= last) {
+      return {
+        ok: false,
+        error: {
+          code: "tool-preview-invalid-trace",
+          expected: `event '${event}' occurs after the previous recipe phase`,
+          hint: "arm RHI-debug before Renderer construction and retain update/draw/validation evidence",
+          detail: { missing: event, index }
+        }
+      };
+    }
+    last = index;
+  }
+  return { ok: true, value: trace };
+}
+
+// src/tool-preview/bootstrap.ts
+function layoutCanvas(canvas, recipe) {
+  canvas.width = recipe.viewport.width;
+  canvas.height = recipe.viewport.height;
+  canvas.style.position = "fixed";
+  canvas.style.inset = "0";
+  canvas.style.width = `${recipe.viewport.width}px`;
+  canvas.style.height = `${recipe.viewport.height}px`;
+  canvas.style.opacity = "1";
+  canvas.style.visibility = "visible";
+  canvas.style.pointerEvents = "auto";
+}
+function appendCanvas(canvas, root) {
+  if (canvas.isConnected) return;
+  const parent = typeof Document !== "undefined" && root instanceof Document ? root.body : root ?? (typeof document === "undefined" ? void 0 : document.body);
+  parent?.appendChild(canvas);
+}
+function removeOwnedCanvas(canvas, owned) {
+  if (owned && canvas.isConnected) canvas.remove();
+}
+function bytesToDataUri(bytes, mediaType) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 8192) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+  }
+  return `data:${mediaType};base64,${btoa(binary)}`;
+}
+async function sha256(bytes) {
+  const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes).buffer);
+  return `sha256:${[...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function dataUriBytes(uri) {
+  const encoded = uri.slice(uri.indexOf(",") + 1);
+  const binary = atob(encoded);
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+function generateRunId() {
+  return `preview-${crypto.randomUUID()}`;
+}
+function countDrawCalls(tape) {
+  return buildTapeIndex(tape).works.filter((work) => isRenderDraw(work.kind)).length;
+}
+function lastRenderDrawIndex(tape) {
+  const works = buildTapeIndex(tape).works;
+  return works.reduce((last, work) => isRenderDraw(work.kind) ? work.workIndex : last, -1);
+}
+function isRenderDraw(kind) {
+  return kind === "draw" || kind === "drawIndexed" || kind === "drawIndirect" || kind === "drawIndexedIndirect";
+}
+function resourceSubjectDigest(resource) {
+  if (resource === void 0) return void 0;
+  const asset = typeof resource.asset === "object" && resource.asset !== null ? resource.asset : void 0;
+  const candidates = [
+    resource.observation?.subjectDigest,
+    resource.digest,
+    asset?.digest,
+    asset?.programFingerprint
+  ];
+  return candidates.find((value) => typeof value === "string" && value.length > 0);
+}
+async function replayToolPreviewCapture(capture) {
+  const analyzeStartedAtMs = performance.now();
+  const tapeBytes = dataUriBytes(capture.tape.jsonUri);
+  const parsed = decodeTape(tapeBytes);
+  if (!parsed.ok) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the finalized tape to deserialize for fresh-device replay",
+      hint: parsed.error.hint,
+      detail: { phase: "tape-parse", cause: parsed.error }
+    });
+  }
+  const subjectDigest = resourceSubjectDigest(capture.resource);
+  if (capture.resource !== void 0 && subjectDigest === void 0) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the resource owner to publish a subject identity before evidence publication",
+      hint: "repair AssetRegistry owner facts or post-frame observation; recipe and trace are not subject identity",
+      detail: { phase: "resource-identity" }
+    });
+  }
+  let runtime;
+  try {
+    runtime = await createBrowserRhiDebugRuntime();
+  } catch (cause) {
+    return err({
+      code: "tool-preview-capability-unavailable",
+      expected: "a fresh browser WebGPU runtime for offline replay",
+      hint: "Run replay in an isolated browser process; do not reuse the capture device.",
+      detail: { phase: "replay-runtime", cause }
+    });
+  }
+  const replayDevice = await runtime.createReplayDevice();
+  if (!replayDevice.ok) {
+    return err({
+      code: "tool-preview-capability-unavailable",
+      expected: "a fresh WebGPU device for offline replay",
+      hint: "the capture device cannot be reused as a substitute for fresh-device replay",
+      detail: { phase: "replay-device", cause: replayDevice.error }
+    });
+  }
+  const replayResult = await openReplay(parsed.value, {
+    device: replayDevice.value,
+    createShaderModule: runtime.createShaderModule
+  });
+  if (!replayResult.ok) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the self-contained tape to replay on a fresh WebGPU device",
+      hint: replayResult.error.hint,
+      detail: { phase: "replay-create", cause: replayResult.error }
+    });
+  }
+  const replay = replayResult.value;
+  const drawCalls = countDrawCalls(parsed.value);
+  if (drawCalls === 0) {
+    await replay.dispose();
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the preview recipe to submit at least one render draw",
+      hint: "seed a visible mesh and camera before capturing the preview frame",
+      detail: { phase: "replay-draws", cause: { appErrors: capture.appErrors } }
+    });
+  }
+  const committedDrawIndex = lastRenderDrawIndex(parsed.value);
+  if (committedDrawIndex < 0) {
+    await replay.dispose();
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the preview tape to contain a render draw after compute work",
+      hint: "seed a visible render output after simulation dispatches before capturing the preview frame",
+      detail: { phase: "replay-draws", cause: { appErrors: capture.appErrors } }
+    });
+  }
+  const committed = await replay.inspectWork(committedDrawIndex, ["pixels"]);
+  if (!committed.ok || committed.value.attachment === void 0) {
+    await replay.dispose();
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the fresh replay session to expose a color attachment for the final render work",
+      hint: committed.ok ? "the tape contains no readable color attachment for PNG evidence" : committed.error.hint,
+      detail: { phase: "replay-inspect", cause: committed.ok ? void 0 : committed.error }
+    });
+  }
+  const attachment = committed.value.attachment;
+  const width = attachment.width ?? 0;
+  const height = attachment.height ?? 0;
+  const rgba = attachment.format === void 0 ? void 0 : decodeToRgba8(attachment.bytes, attachment.format, width, height);
+  if (rgba === null || rgba === void 0 || width <= 0 || height <= 0) {
+    await replay.dispose();
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the replayed color attachment to have a supported display format",
+      hint: "move PNG encoding to the producer-owned preview shell for unsupported formats",
+      detail: { phase: "png-readback", cause: { format: attachment.format, width, height } }
+    });
+  }
+  const outputCanvas = document.createElement("canvas");
+  outputCanvas.width = width;
+  outputCanvas.height = height;
+  const outputContext = outputCanvas.getContext("2d");
+  if (outputContext === null) {
+    await replay.dispose();
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the browser to provide a 2D canvas context for replay PNG encoding",
+      hint: "enable the browser canvas 2D context before running the preview host",
+      detail: { phase: "png-encode" }
+    });
+  }
+  outputContext.putImageData(new ImageData(rgba, width, height), 0, 0);
+  await replay.dispose();
+  const pixels = outputContext.getImageData(0, 0, width, height).data;
+  let nonBlackPixels = 0;
+  if (pixels !== void 0) {
+    for (let offset = 0; offset < pixels.length; offset += 4) {
+      if ((pixels[offset] ?? 0) + (pixels[offset + 1] ?? 0) + (pixels[offset + 2] ?? 0) > 0) {
+        nonBlackPixels += 1;
+      }
+    }
+  }
+  if (nonBlackPixels === 0) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the replayed PNG to contain non-black pixels",
+      hint: "inspect the RHI tape and renderer draw submission before accepting the preview",
+      detail: { phase: "png-non-black" }
+    });
+  }
+  const analyzeDurationMs = performance.now() - analyzeStartedAtMs;
+  const finalizeStartedAtMs = performance.now();
+  const pngUri = outputCanvas.toDataURL("image/png");
+  const pngBytes = dataUriBytes(pngUri);
+  if (!capture.capturePng.uri.startsWith("data:image/png") || capture.capturePng.width <= 0 || capture.capturePng.height <= 0) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the capture browser to provide a PNG before fresh replay",
+      hint: "capture the rendered canvas before closing the capture carrier; do not reuse the replay PNG",
+      detail: { phase: "capture-png" }
+    });
+  }
+  const capturePngBytes = dataUriBytes(capture.capturePng.uri);
+  if (capturePngBytes.byteLength === 0) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the capture PNG to contain encoded bytes",
+      hint: "repair the capture carrier readback before publishing evidence",
+      detail: { phase: "capture-png" }
+    });
+  }
+  const profileBytes = dataUriBytes(capture.profile.uri);
+  const tapeDigest = await sha256(tapeBytes);
+  const capturePngDigest = await sha256(capturePngBytes);
+  const pngDigest = await sha256(pngBytes);
+  const profileDigest = await sha256(profileBytes);
+  const presentationDigest = await sha256(new TextEncoder().encode(capture.trace.presentation));
+  const manifest = createPreviewArtifactManifest({
+    schemaVersion: "2.0.0",
+    identity: {
+      runId: capture.tape.runId,
+      snapshotDigest: capture.snapshot.digest,
+      subjectDigest: subjectDigest ?? capture.snapshot.digest,
+      presentationDigest,
+      frameId: 0,
+      captureId: capture.captureId
+    },
+    artifacts: [
+      {
+        owner: "rhi-debug",
+        kind: "rhi-tape",
+        role: "rhi-tape",
+        uri: capture.tape.jsonUri,
+        digest: tapeDigest,
+        byteLength: tapeBytes.byteLength,
+        mediaType: "application/json",
+        derivedFrom: []
+      },
+      {
+        owner: "visual",
+        kind: "png",
+        role: "capture",
+        uri: capture.capturePng.uri,
+        digest: capturePngDigest,
+        byteLength: capturePngBytes.byteLength,
+        mediaType: "image/png",
+        derivedFrom: [tapeDigest]
+      },
+      {
+        owner: "rhi-debug-replay",
+        kind: "png",
+        role: "fresh-replay",
+        uri: pngUri,
+        digest: pngDigest,
+        byteLength: pngBytes.byteLength,
+        mediaType: "image/png",
+        derivedFrom: [tapeDigest, capturePngDigest]
+      },
+      {
+        owner: "profiler",
+        kind: "profile-capture",
+        role: "profile-capture",
+        uri: capture.profile.uri,
+        digest: profileDigest,
+        byteLength: profileBytes.byteLength,
+        mediaType: "application/json",
+        derivedFrom: []
+      }
+    ]
+  });
+  const finalizeDurationMs = performance.now() - finalizeStartedAtMs;
+  const durationMs = capture.executeDurationMs + capture.captureDurationMs + analyzeDurationMs + finalizeDurationMs;
+  const memory = performance.memory?.usedJSHeapSize;
+  const browserJsHeapBytes = typeof memory === "number" && Number.isFinite(memory) && memory >= 0 ? Math.max(Math.round(memory), capture.browserJsHeapBytes ?? 0) : capture.browserJsHeapBytes;
+  return ok({
+    trace: capture.trace,
+    captureId: capture.captureId,
+    drawCalls,
+    committedDrawIndex,
+    nonBlackPixels,
+    actionTrace: capture.actionTrace,
+    tape: capture.tape,
+    profile: capture.profile,
+    capturePng: capture.capturePng,
+    png: { uri: pngUri, width: outputCanvas.width, height: outputCanvas.height },
+    manifest,
+    artifacts: manifest.artifacts.flatMap((artifact) => {
+      if (artifact.kind !== "rhi-tape" && artifact.kind !== "png" && artifact.kind !== "profile-capture") {
+        return [];
+      }
+      return [
+        {
+          kind: artifact.kind,
+          digest: artifact.digest,
+          uri: artifact.uri,
+          sizeBytes: artifact.byteLength
+        }
+      ];
+    }),
+    operationTiming: {
+      startedAtMs: 0,
+      endedAtMs: durationMs,
+      durationMs,
+      phases: {
+        lookup: { status: "not-applicable" },
+        lease: { status: "not-applicable" },
+        transport: { status: "not-applicable" },
+        execute: {
+          status: "observed",
+          durationMs: capture.executeDurationMs,
+          workUnits: capture.recipe.frames
+        },
+        capture: { status: "observed", durationMs: capture.captureDurationMs },
+        finalize: { status: "observed", durationMs: finalizeDurationMs },
+        analyze: { status: "observed", durationMs: analyzeDurationMs }
+      },
+      unattributedMs: 0,
+      resources: {
+        "node-rss": { status: "not-applicable" },
+        "browser-js-heap": browserJsHeapBytes === void 0 ? { status: "unavailable", reason: "performance.memory is not exposed" } : {
+          status: "observed",
+          bytes: browserJsHeapBytes,
+          source: "maximum performance.memory.usedJSHeapSize across capture and replay"
+        },
+        "artifact-bytes": {
+          status: "observed",
+          bytes: tapeBytes.byteLength + dataUriBytes(capture.capturePng.uri).byteLength + pngBytes.byteLength + profileBytes.byteLength,
+          source: "browser-produced artifact payloads"
+        },
+        "gpu-memory": {
+          status: "unavailable",
+          reason: "WebGPU does not expose portable allocation totals"
+        }
+      }
+    },
+    ...capture.resource === void 0 ? {} : { resource: capture.resource }
+  });
+}
+async function createToolPreviewHost(options) {
+  const recipe = createToolPreviewRecipe(options.recipe);
+  const runId = options.runId ?? generateRunId();
+  const doc = options.root ?? (typeof document === "undefined" ? void 0 : document);
+  if (options.canvas === void 0 && doc === void 0) {
+    return err({
+      code: "tool-preview-capability-unavailable",
+      expected: "a DOM document or caller-owned HTMLCanvasElement",
+      hint: "run the browser host or provide an attached canvas; headless does not mean RHI-null",
+      detail: { phase: "canvas" }
+    });
+  }
+  const canvas = options.canvas ?? (typeof Document !== "undefined" && doc instanceof Document ? doc.createElement("canvas") : void 0);
+  const ownsCanvas = options.canvas === void 0;
+  if (canvas === void 0) {
+    return err({
+      code: "tool-preview-capability-unavailable",
+      expected: "root document can create an HTMLCanvasElement",
+      hint: "provide a document root or an existing canvas",
+      detail: { phase: "canvas" }
+    });
+  }
+  layoutCanvas(canvas, recipe);
+  appendCanvas(canvas, options.root);
+  if (!canvas.isConnected) {
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "preview canvas is connected before App creation",
+      hint: "attach the canvas to the document or pass a connected caller-owned canvas",
+      detail: { phase: "canvas" }
+    });
+  }
+  let runtime;
+  try {
+    runtime = await createBrowserRhiDebugRuntime();
+  } catch (cause) {
+    removeOwnedCanvas(canvas, ownsCanvas);
+    return err({
+      code: "tool-preview-capability-unavailable",
+      expected: "a real WebGPU adapter and device",
+      hint: "install or enable WebGPU; do not replace this route with RHI-null",
+      detail: { phase: "rhi-debug", cause }
+    });
+  }
+  const profiler = createProfiler();
+  const appResult = await createApp(
+    canvas,
+    {
+      ...options.app ?? {},
+      rhi: runtime.rhi,
+      rhiInstrumentation: runtime.rhiInstrumentation,
+      profiler
+    },
+    options.bundler
+  );
+  if (!appResult.ok) {
+    await runtime.attachment.dispose();
+    removeOwnedCanvas(canvas, ownsCanvas);
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "createApp constructs a real WebGPU Renderer",
+      hint: "inspect the structured App/RHI error; the preview must not fall back to RHI-null",
+      detail: { phase: "renderer", cause: appResult.error }
+    });
+  }
+  const app = appResult.value;
+  const appErrors = [];
+  const unsubscribeAppErrors = app.onError((error) => appErrors.push(error));
+  const rendererReady = await app.renderer.ready;
+  if (!rendererReady.ok) {
+    unsubscribeAppErrors();
+    await app.dispose();
+    await runtime.attachment.dispose();
+    removeOwnedCanvas(canvas, ownsCanvas);
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the real WebGPU Renderer to finish pipeline initialization before preview frames",
+      hint: rendererReady.error.hint,
+      detail: { phase: "renderer-ready", cause: rendererReady.error }
+    });
+  }
+  let resourceFacts;
+  try {
+    const prepared = await options.prepare?.(app);
+    if (prepared !== void 0) resourceFacts = prepared;
+  } catch (cause) {
+    unsubscribeAppErrors();
+    await app.dispose();
+    await runtime.attachment.dispose();
+    removeOwnedCanvas(canvas, ownsCanvas);
+    const bootstrapFailure = options.resource === void 0 ? {
+      expected: "the project bootstrap to prepare the preview World",
+      hint: "Repair the project Entry, assets, or scene before retrying the same recipe.",
+      phase: "project-bootstrap"
+    } : {
+      expected: "the resource preview bootstrap to prepare the preview World",
+      hint: "Repair the resource owner, cooked payload, or preview environment before retrying the same recipe.",
+      phase: "resource-bootstrap"
+    };
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      ...bootstrapFailure,
+      detail: { phase: bootstrapFailure.phase, cause }
+    });
+  }
+  const attached = app.renderer.attachWorld(app.world);
+  if (!attached.ok) {
+    unsubscribeAppErrors();
+    await app.dispose();
+    await runtime.attachment.dispose();
+    removeOwnedCanvas(canvas, ownsCanvas);
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the preview World to attach to the real Renderer before stepping",
+      hint: attached.error.hint,
+      detail: { phase: "world-attach", cause: attached.error }
+    });
+  }
+  const profileSession = profiler.startCapture({ frameLimit: recipe.frames, eventLimit: 1024 });
+  if (!profileSession.ok) {
+    await app.dispose();
+    await runtime.attachment.dispose();
+    removeOwnedCanvas(canvas, ownsCanvas);
+    return err({
+      code: "tool-preview-bootstrap-failed",
+      expected: "the App profiler to start a bounded capture",
+      hint: profileSession.error.hint,
+      detail: { phase: "profiler", cause: profileSession.error }
+    });
+  }
+  const detach = runtime.attachRenderer(app.renderer);
+  const trace = {
+    events: ["canvas-created", "rhi-debug-armed", "renderer-created"],
+    backend: "webgpu",
+    adapter: "webgpu-adapter",
+    presentation: recipe.presentation
+  };
+  let disposed = false;
+  const capturePreview = async () => {
+    if (disposed) {
+      return err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "preview host remains alive until capture completes",
+        hint: "create a new preview host after dispose",
+        detail: { phase: "capture" }
+      });
+    }
+    const started = app.start();
+    if (!started.ok)
+      return err({
+        ...started.error,
+        code: "tool-preview-bootstrap-failed",
+        detail: { phase: "start", cause: started.error }
+      });
+    const paused = app.pause();
+    if (!paused.ok)
+      return err({
+        ...paused.error,
+        code: "tool-preview-bootstrap-failed",
+        detail: { phase: "pause", cause: paused.error }
+      });
+    const executeStartedAtMs = performance.now();
+    const actionTrace = [];
+    const encodedCapture = runtime.attachment.captureFrame();
+    for (let frame = 0; frame < recipe.frames; frame += 1) {
+      for (const action of recipe.actions.filter((candidate) => candidate.frame === frame)) {
+        let accepted = false;
+        try {
+          accepted = await options.executeAction?.(action, app) === true;
+        } catch (cause) {
+          return err({
+            code: "tool-preview-bootstrap-failed",
+            expected: `project action '${action.name}' to execute at frame ${frame}`,
+            hint: "Repair the project-owned preview action handler and rerun the same recipe.",
+            detail: { phase: "action", cause }
+          });
+        }
+        if (!accepted) {
+          return err({
+            code: "tool-preview-bootstrap-failed",
+            expected: `project action '${action.name}' to have a registered handler`,
+            hint: "Register the action in the project plugin or remove it from the recipe.",
+            detail: { phase: "action", cause: { frame, name: action.name } }
+          });
+        }
+        actionTrace.push(action);
+      }
+      const stepped = app.stepFrame(recipe.deltaSeconds);
+      if (!stepped.ok)
+        return err({
+          ...stepped.error,
+          code: "tool-preview-bootstrap-failed",
+          detail: { phase: "frame", cause: stepped.error }
+        });
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    await runtime.attachment.frameBoundary();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await runtime.attachment.frameBoundary();
+    if (options.collectResourceFacts !== void 0) {
+      try {
+        const collected = await options.collectResourceFacts(app, resourceFacts);
+        if (collected !== void 0) resourceFacts = collected;
+      } catch (cause) {
+        return err({
+          code: "tool-preview-bootstrap-failed",
+          expected: "the resource owner to publish post-frame preview facts",
+          hint: "Repair the producer-owned preview observation and retry the same recipe.",
+          detail: { phase: "resource-observation", cause }
+        });
+      }
+    }
+    const executeDurationMs = performance.now() - executeStartedAtMs;
+    const finalTrace = {
+      ...trace,
+      events: [...trace.events, "world-updated", "draw-submitted", "validation-complete"]
+    };
+    const captureStartedAtMs = performance.now();
+    const profile = profileSession.value.finish();
+    if (!profile.ok) {
+      return err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "the bounded App profiler to finish with ProfileCapture",
+        hint: profile.error.hint,
+        detail: { phase: "profiler-finish", cause: profile.error }
+      });
+    }
+    const tape = await encodedCapture;
+    if (!tape.ok)
+      return err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "RHI-debug produces a self-contained tape",
+        hint: tape.error.hint,
+        detail: { phase: "rhi-finalize", cause: tape.error }
+      });
+    const captureDurationMs = performance.now() - captureStartedAtMs;
+    const tapeBytes = tape.value.bytes;
+    const profileBytes = new TextEncoder().encode(JSON.stringify(profile.value));
+    const capturePng = {
+      uri: canvas.toDataURL("image/png"),
+      width: canvas.width,
+      height: canvas.height
+    };
+    const memory = performance.memory?.usedJSHeapSize;
+    return ok({
+      recipe,
+      snapshot: options.snapshot,
+      trace: finalTrace,
+      captureId: profile.value.captureId,
+      actionTrace,
+      tape: {
+        runId,
+        jsonUri: bytesToDataUri(tapeBytes, "application/octet-stream"),
+        blobUri: bytesToDataUri(new Uint8Array(), "application/octet-stream"),
+        byteLength: tapeBytes.byteLength
+      },
+      profile: {
+        captureId: profile.value.captureId,
+        uri: bytesToDataUri(profileBytes, "application/json")
+      },
+      capturePng,
+      executeDurationMs,
+      captureDurationMs,
+      ...typeof memory === "number" && Number.isFinite(memory) && memory >= 0 ? { browserJsHeapBytes: Math.round(memory) } : {},
+      appErrors,
+      ...resourceFacts === void 0 ? {} : { resource: resourceFacts }
+    });
+  };
+  return ok({
+    app,
+    recipe,
+    trace,
+    capture: capturePreview,
+    async run() {
+      const capture = await capturePreview();
+      if (!capture.ok) return capture;
+      return replayToolPreviewCapture(capture.value);
+    },
+    async dispose() {
+      if (disposed) return ok(void 0);
+      disposed = true;
+      detach();
+      unsubscribeAppErrors();
+      let disposeError;
+      try {
+        await options.onDispose?.(app);
+      } catch (cause) {
+        disposeError = cause;
+      }
+      const result = await app.dispose();
+      removeOwnedCanvas(canvas, ownsCanvas);
+      if (disposeError !== void 0) {
+        return err({
+          code: "tool-preview-bootstrap-failed",
+          expected: "producer-owned preview attachments to dispose before the App",
+          hint: "Repair the preview owner lifecycle and retry the same operation.",
+          detail: { phase: "producer-dispose", cause: disposeError }
+        });
+      }
+      return result.ok ? ok(void 0) : err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "preview app disposes cleanly",
+        hint: result.error.hint,
+        detail: { phase: "dispose", cause: result.error }
+      });
+    }
+  });
+}
+function joinToolPreviewEvidence(input) {
+  const validated = validatePreviewArtifactManifest(input.manifest, input.required);
+  if (!validated.ok) return err(validated.error);
+  const artifacts = input.manifest.artifacts.map(
+    (artifact) => createArtifactRef({
+      kind: artifact.kind === "report" || artifact.kind === "contact-sheet" ? "tool-result" : artifact.kind,
+      digest: artifact.digest,
+      uri: artifact.uri,
+      mediaType: artifact.mediaType,
+      sizeBytes: artifact.byteLength
+    })
+  );
+  return ok({ trace: input.trace, artifacts, manifest: input.manifest });
+}
+function createToolPreviewEvidence(trace, artifacts) {
+  return { trace, artifacts: [...artifacts] };
+}
+function joinResourcePreviewEvidence(input) {
+  if (input.manifest.identity.snapshotDigest !== input.snapshot.digest) {
+    return err(snapshotStaleError(input.snapshot.digest, input.manifest.identity.snapshotDigest));
+  }
+  const validated = validatePreviewArtifactManifest(input.manifest, input.requiredRoles);
+  return validated.ok ? ok(validated.value) : err(validated.error);
+}
+
+// src/tool-preview/framing.ts
+function fitToolPreviewCameraToAabb(aabb, options) {
+  const [minX, minY, minZ, maxX, maxY, maxZ] = aabb;
+  if (![minX, minY, minZ, maxX, maxY, maxZ].every(Number.isFinite) || minX > maxX || minY > maxY || minZ > maxZ || !Number.isFinite(options.aspect) || options.aspect <= 0 || !Number.isFinite(options.fov) || options.fov <= 0 || options.fov >= Math.PI) {
+    throw new TypeError("tool preview camera framing requires a finite AABB, aspect, and FOV");
+  }
+  const center = [
+    (minX + maxX) / 2,
+    (minY + maxY) / 2,
+    (minZ + maxZ) / 2
+  ];
+  const radius = Math.max(
+    Math.hypot((maxX - minX) / 2, (maxY - minY) / 2, (maxZ - minZ) / 2),
+    1e-3
+  );
+  const verticalHalfFov = options.fov / 2;
+  const horizontalHalfFov = Math.atan(Math.tan(verticalHalfFov) * options.aspect);
+  const limitingHalfFov = Math.min(verticalHalfFov, horizontalHalfFov);
+  const padding = options.padding ?? 1.15;
+  if (!Number.isFinite(padding) || padding < 1) {
+    throw new TypeError("tool preview camera framing padding must be finite and at least one");
+  }
+  const distance = radius / Math.sin(limitingHalfFov) * padding;
+  const depthMargin = radius * (padding - 1);
+  return {
+    center,
+    radius,
+    distance,
+    near: Math.max(1e-3, distance - radius - depthMargin),
+    far: distance + radius + depthMargin
+  };
+}
+
+export { APP_ERROR_HINTS, APP_EXPECTED, APP_PHASE_CATALOG, AppError, EXECUTION_CAPABILITY_NAMES, EXECUTION_REPORT_SCHEMA_VERSION, EXECUTION_REQUESTED_TIERS, EXECUTION_TIERS, LOAD_GAME_ERROR_HINTS, LOAD_GAME_EXPECTED, LoadGameError, assembleAssetRuntime, createApp, createExecutionReport, createToolPreviewEvidence, createToolPreviewHost, createToolPreviewRecipe, ensureFallbackCamera, executionBootstrapHostPlugin, fitToolPreviewCameraToAabb, gameHostPlugin, inputPlugin, isAppError, isExecutionReport, isLoadGameError, joinResourcePreviewEvidence, joinToolPreviewEvidence, loadBootstrapEntry, loadGame, measureCanvasDrawingBuffer, missingExecutionCapabilities, prepareBootstrapEntry, probeExecutionCapabilities, replayToolPreviewCapture, selectExecutionTier, syncCanvasDrawingBuffer, unavailableExecutionCapabilities, validateExecutionBootstrapData, validateToolPreviewTrace };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map