@vgai/editor 0.2.0

package/src/authoring/world2d-authoring-adapter.ts

@@ -0,0 +1,313 @@
+/**
+ * World2DAuthoringAdapter — the editor's {@link AuthoringAdapter} implemented over a
+ * live PixiJS world2d tree (first-party scene OR an ingested unmodified game). It is
+ * the world2d peer of {@link IngestAuthoringAdapter}: the editor's REAL adapter-driven
+ * panels (GameHierarchy / Inspector) render world2d entities and edits apply
+ * live, with NO SceneEntity fabricated (anti-shim rule).
+ *
+ * It wraps the engine's backend-neutral {@link AuthoringAdapter2D} (tree + structural
+ * ids + overlay) and {@link PhysicsAdapter2D} (freeze→commit→unfreeze), and translates
+ * the engine's 2D transform (x, y, scalar rotation) to/from the editor's neutral
+ * {@link Transform} tuple (position[3] / quaternion-about-Z / scale[3]).
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PropertyDescriptor,
+  SelectionProvider,
+  Transform,
+  TransformOwner,
+  TransformProvider,
+} from '@engine/adapter';
+import {
+  AuthoringAdapter2D,
+  type Overlay2D,
+  type Transform2DValue,
+} from '@engine/world2d/authoring-2d';
+import type { PhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
+import type { Container } from 'pixi.js';
+import type { EditorStore } from '../editor-store';
+import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
+
+function numToHex(n: number): string {
+  return `#${(n & 0xffffff).toString(16).padStart(6, '0')}`;
+}
+function hexToNum(hex: string): number {
+  return Number.parseInt(hex.replace('#', ''), 16);
+}
+/** Quaternion (xyzw) about Z ⇄ scalar radians. */
+function angleToQuat(a: number): [number, number, number, number] {
+  return [0, 0, Math.sin(a / 2), Math.cos(a / 2)];
+}
+function quatToAngle(q: [number, number, number, number]): number {
+  return 2 * Math.atan2(q[2], q[3]);
+}
+
+/**
+ * Save callback + human-readable destination for a world2d session's persistence
+ * (design §2/§4). Mirrors `IngestAuthoringOptions` (`ingest-authoring-adapter.ts`):
+ * absence of `persist` means runtime-only (`capabilities.persist === false`).
+ */
+export interface World2DAuthoringOptions {
+  /** Overlay to reapply once the tree is walked (edits from a previous session). */
+  overlay?: Overlay2D | undefined;
+  /** Save callback for `persistence.save()`. Absence ⇒ runtime-only (persist:false). */
+  persist?: ((overlay: Overlay2D) => Promise<void>) | undefined;
+  /** Human-readable destination (design §2), e.g. `.vgai/overlays/2d-<id>.json`. */
+  destination?: string | undefined;
+}
+
+export class World2DAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities;
+  private readonly a2d: AuthoringAdapter2D;
+  private readonly persistFn: ((overlay: Overlay2D) => Promise<void>) | undefined;
+  /** Human-readable overlay destination (design §2) — see {@link World2DAuthoringOptions.destination}. */
+  private readonly destination: string;
+  private listeners = new Set<() => void>();
+
+  constructor(
+    root: Container,
+    private readonly physics: PhysicsAdapter2D,
+    private readonly store: EditorStore,
+    opts: World2DAuthoringOptions = {},
+  ) {
+    this.a2d = new AuthoringAdapter2D(root);
+    if (opts.overlay) this.a2d.applyOverlay(opts.overlay);
+    this.persistFn = opts.persist;
+    this.destination =
+      opts.destination ?? (opts.persist ? '(world2d overlay)' : '(runtime-only — not persisted)');
+    this.capabilities = {
+      transform: true,
+      material: true, // tint
+      inspectorFields: true,
+      // Structural authoring is not supported over a world2d tree today (mirrors
+      // the 3D ingest ceiling): create/delete/reparent would need to survive the
+      // next refresh()/remount, which neither surface implements.
+      create: false,
+      delete: false,
+      reparent: false,
+      persist: !!this.persistFn, // runtime-only unless a persist callback is wired
+    };
+    // v4 architecture-review §7.1-13 (was T3.2 slice 2 for the structural twin,
+    // `IngestAuthoringAdapter`, only): this adapter IS the undo/redo target the
+    // editor-global timeline dispatches to for entries it records below
+    // (`pushUndo`). The caller (`play-mode.ts`'s `exitMultiWorldAuthoring`,
+    // `ingest-mode.ts`'s `exitIngestMode2D`) unregisters it on teardown — see
+    // those call sites' comments for why an unregistered-but-still-recorded
+    // entry is dropped (with a warn) rather than undone against a torn-down tree.
+    registerUndoAdapter(this);
+  }
+
+  refresh(): { count: number; sprites: number } {
+    return this.a2d.refresh();
+  }
+
+  /** Reapply a saved/external overlay onto the live tree (see `AuthoringAdapter2D.applyOverlay`). */
+  applyOverlay(overlay: Overlay2D): { applied: number; orphaned: number } {
+    return this.a2d.applyOverlay(overlay);
+  }
+
+  // A class GETTER, not a field initializer — a field initializer runs before the
+  // constructor body assigns `this.persistFn`/`this.destination` (the slice-1
+  // ordering bug; see `vgai-scene-authoring-adapter.ts` for the pattern).
+  get persistence(): PersistenceProvider {
+    const a2d = this.a2d;
+    const persistFn = this.persistFn;
+    const destination = this.destination;
+    return {
+      isDirty: () => a2d.isDirty(),
+      save: async () => {
+        if (!persistFn) return;
+        await persistFn(a2d.serializeOverlay());
+        a2d.markClean();
+      },
+      serialize: () => a2d.serializeOverlay(),
+      destination,
+      // The reload contract (design §5): re-apply a changed overlay onto the live
+      // tree without a full remount — `AuthoringAdapter2D.applyOverlay` already IS
+      // that remount-free logic (used at construction too).
+      applyExternal: (content) => {
+        a2d.applyOverlay(content as Overlay2D);
+      },
+    };
+  }
+
+  private notify(): void {
+    for (const l of this.listeners) l();
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: () =>
+      this.a2d
+        .roots()
+        .map((n) => this.toEditorNode(n.id))
+        .filter((n): n is EditorNode => n !== null),
+    node: (id) => this.toEditorNode(id),
+    object3D: () => null, // world2d entities are PIXI display objects, not THREE — no 3D gizmo binding
+    idForObject3D: () => null,
+  };
+
+  private toEditorNode(id: string): EditorNode | null {
+    const n = this.a2d.node(id);
+    if (!n) return null;
+    const disp = this.a2d.displayObject(id);
+    const owner: TransformOwner =
+      disp && this.physics.ownerOf(disp) === 'physics' ? 'physics' : 'editor';
+    return {
+      id: n.id,
+      label: n.label,
+      kind: n.kind,
+      parentId: n.parentId,
+      childIds: n.childIds,
+      flags: { runtimeOnly: true, transformOwner: owner },
+    };
+  }
+
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => {
+      this.store.selectMultiple(ids);
+      this.notify();
+    },
+  };
+
+  readonly transforms: TransformProvider = {
+    get: (id): Transform => {
+      const t = this.a2d.getTransform(id);
+      if (!t) return { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
+      return {
+        position: [t.position[0], t.position[1], 0],
+        rotation: angleToQuat(t.rotation),
+        scale: [t.scale[0], t.scale[1], 1],
+      };
+    },
+    owner: (id) => {
+      const disp = this.a2d.displayObject(id);
+      return disp && this.physics.ownerOf(disp) === 'physics' ? 'physics' : 'editor';
+    },
+    // Snapshot the PRE-drag transform for undo (mirrors IngestAuthoringAdapter's
+    // `editStartTransform`) — in the engine's own [x,y]/scalar-radians shape, not
+    // the editor's quaternion `Transform`, so undo/redo round-trip through the
+    // exact same primitives `setTransform`/`getTransform` already use (no lossy
+    // angle<->quaternion re-derivation on the undo path).
+    beginEdit: (id) => {
+      const disp = this.a2d.displayObject(id);
+      if (disp && this.physics.ownerOf(disp) === 'physics') this.physics.freeze(disp);
+      this.editStartTransform = this.a2d.getTransform(id) ?? undefined;
+    },
+    apply: (id, t) => {
+      const pos: [number, number] = [t.position[0], t.position[1]];
+      const angle = quatToAngle(t.rotation);
+      this.writeTransform(id, { position: pos, rotation: angle, scale: [t.scale[0], t.scale[1]] });
+    },
+    // Pushes exactly ONE undo entry per gesture: `apply` fires many times during
+    // a live drag (no undo push there — see `writeTransform`), `endEdit` fires
+    // once on commit, which is where the before/after pair is recorded.
+    endEdit: (id) => {
+      const disp = this.a2d.displayObject(id);
+      if (disp && this.physics.ownerOf(disp) === 'physics') this.physics.unfreeze(disp);
+      const prev = this.editStartTransform;
+      this.editStartTransform = undefined;
+      if (!prev) return;
+      const next = this.a2d.getTransform(id);
+      if (!next) return;
+      this.pushUndo({
+        undo: () => this.writeTransform(id, prev),
+        redo: () => this.writeTransform(id, next),
+      });
+    },
+  };
+
+  /** Write a 2D transform to the live tree (+ physics body, if owned) + the
+   *  overlay (via `AuthoringAdapter2D.setTransform`) — no undo push; shared by
+   *  `transforms.apply` (live-drag, no push) and the undo/redo thunks
+   *  `endEdit` records (which DO push, exactly once, on commit). */
+  private writeTransform(id: string, t: Transform2DValue): void {
+    const disp = this.a2d.displayObject(id);
+    if (disp && this.physics.ownerOf(disp) === 'physics') {
+      this.physics.commit(disp, t.position, t.rotation);
+    }
+    this.a2d.setTransform(id, t);
+    this.notify();
+  }
+
+  readonly inspector: InspectorProvider = {
+    properties: (id): PropertyDescriptor[] => {
+      const props: PropertyDescriptor[] = [
+        { path: 'name', label: 'Name', type: 'string' },
+        { path: 'visible', label: 'Visible', type: 'boolean' },
+        { path: 'alpha', label: 'Alpha', type: 'number' },
+      ];
+      const disp = this.a2d.displayObject(id);
+      if (disp && 'tint' in disp) props.push({ path: 'tint', label: 'Tint', type: 'color' });
+      return props;
+    },
+    get: (id, path) => {
+      const disp = this.a2d.displayObject(id) as (Container & Record<string, unknown>) | null;
+      if (!disp) return undefined;
+      if (path === 'name') return disp.label;
+      if (path === 'tint') return numToHex((disp as { tint?: number }).tint ?? 0xffffff);
+      return disp[path];
+    },
+    set: (id, path, value) => {
+      const prev = this.inspector.get(id, path); // snapshot for undo
+      this.writeProp(id, path, value);
+      this.pushUndo({
+        undo: () => this.writeProp(id, path, prev),
+        redo: () => this.writeProp(id, path, value),
+      });
+    },
+  };
+
+  /** Mutate one reflectable field on the live display object (+ overlay for
+   *  tint/visible, via `AuthoringAdapter2D.set`) — no undo push. */
+  private writeProp(id: string, path: string, value: unknown): void {
+    const disp = this.a2d.displayObject(id) as (Container & Record<string, unknown>) | null;
+    if (!disp) return;
+    if (path === 'name') disp.label = value as string;
+    else if (path === 'tint') this.a2d.set(id, 'tint', hexToNum(value as string));
+    else if (path === 'visible') this.a2d.set(id, 'visible', value as boolean);
+    else disp[path] = value;
+    this.notify();
+  }
+
+  // --- Overlay-backed undo/redo (v4 §7.1-13 — the world2d port of
+  // IngestAuthoringAdapter's "Overlay-backed undo/redo" section). ---
+  private readonly undoStack: Array<{ undo: () => void; redo: () => void }> = [];
+  private readonly redoStack: Array<{ undo: () => void; redo: () => void }> = [];
+  private editStartTransform: Transform2DValue | undefined;
+
+  private pushUndo(entry: { undo: () => void; redo: () => void }): void {
+    this.undoStack.push(entry);
+    this.redoStack.length = 0;
+    notifyUndoableOp(this); // tag this op on the global timeline
+  }
+
+  undo(): boolean {
+    // `false` tells the undo timeline "couldn't act — put the entry back" (see
+    // `UndoAdapter` in `./undo-timeline.ts`).
+    const e = this.undoStack.pop();
+    if (!e) return false;
+    e.undo();
+    this.redoStack.push(e);
+    return true;
+  }
+
+  redo(): boolean {
+    const e = this.redoStack.pop();
+    if (!e) return false;
+    e.redo();
+    this.undoStack.push(e);
+    return true;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}

package/src/browser-external-watch.ts

@@ -0,0 +1,98 @@
+/**
+ * Browser-mode EXTERNAL-change detection for the open scene (Phase A4).
+ *
+ * A2 (`browser-watch-reload.ts`) derives change events from the storage
+ * backend's OWN writes — perfect for the editor's autosave echo, but blind to
+ * edits made out-of-band: an agent's `apply-diff` writing the `.vscn.json`
+ * straight to disk, another editor, a `git checkout`. The File System Access
+ * backend points at a real on-disk folder that other tools can write, and the
+ * browser gets no OS file-change notification for it — so the only way to learn
+ * about an external edit is to poll.
+ *
+ * This polls the CURRENTLY-OPEN scene file's content on an interval and, when it
+ * differs from the last content we observed, delivers it through the SAME
+ * `onSceneChanged` consumer A2 feeds (`connectSceneEvents` →
+ * `applyExternalUpdate`). That reuse is deliberate: the store's own-echo guard
+ * (`applyExternalUpdate` skips when `rawContent === _lastSavedContent`) already
+ * drops the editor's own saves, so a self-write that the poll happens to catch
+ * is harmlessly ignored downstream, and only a genuine external edit reloads.
+ *
+ * Scope: the open scene only (the roadmap's A4). Component-source external edits
+ * (→ hot-swap) are a later extension; this is the piece the gate's "genuine
+ * external edits arrive once A4 lands" note refers to. Gated to the FSA backend
+ * by the caller — OPFS is a private-origin sandbox with no external writer.
+ */
+
+import type { StorageBackend } from './storage';
+import { getStorageBackend } from './storage';
+
+export interface SceneWatchState {
+  /** Last scene content this watcher observed (null until the first poll). */
+  lastContent: string | null;
+}
+
+/**
+ * One poll step (exported for unit tests — the interval driver just repeats it).
+ *
+ * The FIRST observation only establishes a baseline and never delivers: on watch
+ * start the on-disk content equals what the editor already has loaded, so firing
+ * would be a spurious reload. Every later change from that baseline delivers.
+ */
+export async function pollExternalSceneOnce(
+  state: SceneWatchState,
+  getScenePath: () => string | null,
+  backend: StorageBackend,
+  deliver: (event: { path: string; content: string }) => void,
+): Promise<void> {
+  const path = getScenePath();
+  if (!path) return;
+  let content: string;
+  try {
+    content = await backend.read(path);
+  } catch {
+    // File missing/unreadable this tick (mid-write, removed) — try again next.
+    return;
+  }
+  if (content === state.lastContent) return;
+  const isBaseline = state.lastContent === null;
+  state.lastContent = content;
+  if (isBaseline) return; // establish baseline silently
+  deliver({ path, content });
+}
+
+/**
+ * Poll the open scene for external edits. `getScenePath` is read live each tick
+ * (so switching the open scene re-baselines automatically). Returns an
+ * unsubscribe that stops the interval. Overlapping ticks are coalesced — a slow
+ * read never stacks up.
+ */
+export function watchExternalSceneChanges(
+  getScenePath: () => string | null,
+  deliver: (event: { path: string; content: string }) => void,
+  opts: { backend?: StorageBackend; intervalMs?: number } = {},
+): () => void {
+  const backend = opts.backend ?? getStorageBackend();
+  const intervalMs = opts.intervalMs ?? 1500;
+  const state: SceneWatchState = { lastContent: null };
+  let stopped = false;
+  let inFlight = false;
+
+  const tick = async (): Promise<void> => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      await pollExternalSceneOnce(state, getScenePath, backend, deliver);
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  const timer = setInterval(() => {
+    if (!stopped) void tick();
+  }, intervalMs);
+
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+}

package/src/browser-play-entry.ts

@@ -0,0 +1,112 @@
+/**
+ * Browser play entry — a STATIC, dynamic-import-free version of the template's
+ * `src/scripts/main.ts` for the static/browser editor build.
+ *
+ * The static host has no dev server, so play mode can't `import('/@fs/.../main.ts')`.
+ * Instead this file is pre-bundled (see `scripts/bundle-project-scripts.mjs`) into a
+ * single self-contained ESM (`public/project-scripts.bundle.js`) with all engine +
+ * vendor modules kept EXTERNAL, then loaded in-browser via esbuild-wasm transpile
+ * (`browser-project-scripts.ts` → `importFromSource`), which shims each external
+ * import to the editor's LIVE singleton.
+ *
+ * Dispatch is over `SETUP_BY_EXAMPLE_ID`, a plain exampleId → setup map of STATIC
+ * imports spanning `examples/<id>/src/...` (repo-root sibling packages — see
+ * docs/EXAMPLES-AS-PROJECTS-DESIGN.md §4), so the bundle has zero dynamic imports.
+ * That map is not hand-maintained: `generated/setup-by-example.generated.ts` is
+ * GENERATED from each example folder's `vgai.game.json` manifest by
+ * `scripts/bundle-project-scripts.mjs` — regenerate with
+ * `node scripts/bundle-project-scripts.mjs` after editing an example manifest.
+ *
+ * Design note (Adjudication H's plumbing point, closed by Track H): which
+ * example to run is threaded through `EditorPreview.exampleId`
+ * (`@engine/runtime/types`) — the ONLY channel a caller has into this bundle's
+ * exported `setup(ctx, editor)`, since `GameSetupFn`'s signature is fixed and
+ * used broadly. The caller is play-mode.ts's legacy browser branch, fed by the
+ * hosted `?project=<id>` routing (`hosted-example.ts`); undefined still means
+ * the generic scene-loader fallback. `loadBrowserProjectScripts()` itself
+ * stays a plain no-arg loader — it just returns whatever `setup` the bundle
+ * exports, unmodified.
+ */
+
+import { setAssetPrefix } from '@engine/loader';
+import type { EditorPreview, GameCleanup, GameContext } from '@engine/runtime/types';
+import { loadScene, loadSceneFromData } from '@engine/scene/scene-loader';
+import { applyScenePostProcessing } from '@engine/setup/setup-renderer';
+// The generic fallback's component registry is still the template's (soon-to-be
+// minimal) `src/scripts/registry.ts` — unrelated to example dispatch, and this
+// migration wave does not touch the template layout (a later wave does).
+import { componentRegistry, gameComponents } from '../template/src/scripts/registry';
+import { SETUP_BY_EXAMPLE_ID } from './generated/setup-by-example.generated';
+
+const DEFAULT_SCENE = 'scenes/default.vscn.json';
+
+/** Exported so the editor inspector can read component `static schema`s. */
+export const components = gameComponents;
+
+export async function setup(ctx: GameContext, editor?: EditorPreview): Promise<GameCleanup> {
+  // If the caller (Track H's `?project=<id>` routing, or a future picker)
+  // asked for a specific bundled example, delegate to its setup (registers the
+  // correct gameplay systems + component registries) after namespacing
+  // relative asset fetches to that example's own copied public/ output (see
+  // vite-plugin-example-assets.ts). An exampleId with NO dispatch entry (e.g.
+  // a server-room example the static host can't run — see the generated
+  // file's header) falls through to the generic loader below, KEEPING the
+  // example prefix so the open scene's relative asset refs still resolve.
+  if (editor?.exampleId) {
+    setAssetPrefix(`/examples/${editor.exampleId}/`);
+    const exampleSetup = SETUP_BY_EXAMPLE_ID[editor.exampleId];
+    if (exampleSetup) {
+      return exampleSetup(ctx);
+    }
+  } else {
+    // Generic fallback prefix: `editor.assetPrefix` when the editor is playing
+    // a bundled example's non-default scene (Track H `?scene=` override),
+    // otherwise the deploy root — always reset here so a previously mounted
+    // example's namespaced prefix never leaks into this path.
+    setAssetPrefix(editor?.assetPrefix ?? '/');
+  }
+
+  // Generic fallback: load the scene with the full component registry so ECS
+  // components apply, but no example-specific gameplay systems are registered.
+  const loadOpts = {
+    scene: ctx.scene,
+    rapierWorld: ctx.rapierWorld,
+    rapier: ctx.rapier,
+    physics: ctx.physics,
+    audioListener: ctx.audio.listener,
+    componentRegistry,
+    componentManager: ctx.components,
+    particleRenderer: ctx.particles.batchedRenderer,
+    renderer: ctx.composer.getRenderer(),
+  };
+
+  if (editor?.viewportCamera) {
+    ctx.camera.position.fromArray(editor.viewportCamera.position);
+    ctx.camera.quaternion.fromArray(editor.viewportCamera.quaternion);
+  } else {
+    ctx.camera.position.set(3, 3, 3);
+    ctx.camera.lookAt(0, 0.5, 0);
+  }
+
+  const sceneInstance = editor
+    ? await loadSceneFromData(editor.sceneData, loadOpts)
+    : await loadScene(DEFAULT_SCENE, loadOpts);
+
+  if (sceneInstance.environment?.postProcessing) {
+    applyScenePostProcessing(
+      ctx.composer,
+      ctx.composer.getRenderer(),
+      ctx.scene,
+      ctx.camera,
+      sceneInstance.environment,
+    );
+  }
+
+  ctx.systems.add('postPhysics', (dt) => sceneInstance.update(dt));
+
+  return {
+    dispose() {
+      sceneInstance.dispose();
+    },
+  };
+}

package/src/browser-project-scripts.ts

@@ -0,0 +1,112 @@
+/**
+ * Browser-build play-mode script loader.
+ *
+ * The static/browser build has no dev server, so play mode can't
+ * `import('/@fs/.../src/scripts/main.ts')`. Instead we ship the project scripts
+ * pre-bundled to a single self-contained ESM (`public/project-scripts.bundle.js`,
+ * built by `scripts/bundle-project-scripts.mjs`) with all engine + vendor modules
+ * kept EXTERNAL, and run it through the same in-browser transpile path the
+ * Playground uses (`importFromSource`). Each external bare import is shimmed to
+ * the editor's LIVE singleton via `registerRuntimeModules`, so the bundled
+ * examples share the editor's THREE / GameComponent / physics world.
+ */
+
+import type { GameComponentClass } from '@engine/ecs/game-component';
+import type { GameSetupFn } from '@engine/runtime/types';
+import { importFromSource, registerRuntimeModules } from './browser-transpile';
+import { type ProjectScripts, setLoadedComponents } from './script-loader';
+
+let _modulesRegistered = false;
+
+/**
+ * One lazy loader per external specifier the bundle imports — the keys ARE the
+ * registered-specifier list (exported below for the drift-guard test). Lazy
+ * (only awaited on first Play) so these heavy modules aren't pulled into the
+ * editor's startup chunk. The list must mirror the externals actually present
+ * in `project-scripts.bundle.js` — a new external missing here makes
+ * `importFromSource` throw "not a registered runtime module" AT PLAY TIME in
+ * the hosted build only, which is exactly how the Track E2 starfighter
+ * relocation silently broke hosted Play (caught live in Track H's H3
+ * verification: RGBELoader/BufferGeometryUtils were bundled but unregistered).
+ * `browser-bundle-runtime-modules.test.ts` now fails CI on that drift.
+ */
+const BUNDLE_RUNTIME_MODULE_LOADERS: Record<string, () => Promise<unknown>> = {
+  three: () => import('three'),
+  'three/addons/controls/OrbitControls.js': () => import('three/addons/controls/OrbitControls.js'),
+  'three/addons/interactive/SelectionBox.js': () =>
+    import('three/addons/interactive/SelectionBox.js'),
+  'three/addons/loaders/RGBELoader.js': () => import('three/addons/loaders/RGBELoader.js'),
+  'three/addons/utils/BufferGeometryUtils.js': () =>
+    import('three/addons/utils/BufferGeometryUtils.js'),
+  'three/addons/utils/SkeletonUtils.js': () => import('three/addons/utils/SkeletonUtils.js'),
+  'three/examples/jsm/animation/CCDIKSolver.js': () =>
+    import('three/examples/jsm/animation/CCDIKSolver.js'),
+  'three.quarks': () => import('three.quarks'),
+  'quarks.core': () => import('quarks.core'),
+  postprocessing: () => import('postprocessing'),
+  gsap: () => import('gsap'),
+  zod: () => import('zod'),
+  react: () => import('react'),
+  'react/jsx-runtime': () => import('react/jsx-runtime'),
+  'react-dom/client': () => import('react-dom/client'),
+  '@engine/adapter': () => import('@engine/adapter'),
+  '@engine/ai/navigation': () => import('@engine/ai/navigation'),
+  '@engine/animation/xstate-animation-binding': () =>
+    import('@engine/animation/xstate-animation-binding'),
+  '@engine/audio': () => import('@engine/audio'),
+  '@engine/data/data-asset': () => import('@engine/data/data-asset'),
+  '@engine/ecs/game-component': () => import('@engine/ecs/game-component'),
+  '@engine/scene/scene-loader': () => import('@engine/scene/scene-loader'),
+  '@engine/scene/scene-query': () => import('@engine/scene/scene-query'),
+  '@engine/scene/user-data': () => import('@engine/scene/user-data'),
+  '@engine/setup/setup-renderer': () => import('@engine/setup/setup-renderer'),
+  // littlest-tokyo (GLTF quick-start) extras:
+  '@engine/loader': () => import('@engine/loader'),
+  '@engine/scene/parse': () => import('@engine/scene/parse'),
+  // E5 — XState-driven character animation (third-person/rts/third-person-arena):
+  xstate: () => import('xstate'),
+};
+
+/** The bundle-external specifiers the browser build can shim at Play time —
+ *  exported for `browser-bundle-runtime-modules.test.ts` (bundle-drift guard). */
+export const REGISTERED_BUNDLE_SPECIFIERS: readonly string[] = Object.keys(
+  BUNDLE_RUNTIME_MODULE_LOADERS,
+);
+
+async function ensureRuntimeModulesRegistered(): Promise<void> {
+  if (_modulesRegistered) return;
+  const entries = await Promise.all(
+    Object.entries(BUNDLE_RUNTIME_MODULE_LOADERS).map(
+      async ([specifier, load]) => [specifier, (await load()) as Record<string, unknown>] as const,
+    ),
+  );
+  const mods: Record<string, Record<string, unknown>> = Object.fromEntries(entries);
+  registerRuntimeModules(mods);
+  _modulesRegistered = true;
+}
+
+/**
+ * Load the pre-bundled project scripts in the browser build: register live
+ * runtime modules, fetch the bundle, transpile+import it in-browser, and return
+ * its `setup` / `components`. Mirrors `loadProjectScripts`'s return shape.
+ */
+export async function loadBrowserProjectScripts(): Promise<ProjectScripts> {
+  await ensureRuntimeModulesRegistered();
+
+  const url = `${import.meta.env.BASE_URL}project-scripts.bundle.js`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `Failed to fetch ${url} (${res.status}) — is the project-scripts bundle built?`,
+    );
+  }
+  const source = await res.text();
+
+  const mod = await importFromSource(source, 'project-scripts.bundle.js');
+  if (typeof mod['setup'] !== 'function') {
+    throw new Error('project-scripts bundle does not export a setup() function');
+  }
+  const components = mod['components'] as Record<string, GameComponentClass> | undefined;
+  setLoadedComponents(components ?? {});
+  return { setup: mod['setup'] as GameSetupFn, components };
+}