@vgai/editor 0.2.0

package/src/authoring/ingest-iframe-reachable-adapter.ts

@@ -0,0 +1,401 @@
+/**
+ * Reachable-three iframe host — the tier-2/3 middle case the founding docs flagged
+ * as the "named remaining edge" of bundled-game coverage (`cov-iframe-reachable`).
+ *
+ * A prebuilt bundle runs in its OWN iframe document (a separate realm), but — unlike
+ * the opaque embed floor — its `three` is REACHABLE: the host wires the iframe's
+ * `import 'three'` to a tiny blob module that re-exports `window.parent`'s host
+ * `three` namespace. Because the bundle therefore constructs HOST-realm `three`
+ * objects, the cross-realm canvas/document hazard that blocked naive sharing is
+ * sidestepped two ways:
+ *   - every `Scene`/`Mesh`/`Camera` the bundle makes is a host-realm instance, so the
+ *     editor's `instanceof THREE.*`, gizmo, raycast and inspector all work on them; and
+ *   - the bundle creates + passes its OWN iframe canvas to `new WebGLRenderer({canvas})`,
+ *     so the WebGL context lives in the iframe realm — no parent-document canvas adoption.
+ *
+ * The host's scene-capture trap (installed on the shared host `three`) then captures
+ * the bundle's renderer on its first frame exactly as in the shared-ESM path — the
+ * difference is purely WHERE the bundle's code runs (an iframe document) and HOW its
+ * `three` is resolved (importmap → blob re-export). The result is a real
+ * `IngestAuthoringAdapter` over the live `Object3D` tree: full in-realm editing.
+ *
+ * See `docs/ADAPTER-ARCHITECTURE.md` §2.3 (coverage table, reachable-three row).
+ */
+
+import type { MountedGame } from '@engine/adapter';
+import { installSceneCapture, type SceneCaptureHandle } from '@engine/adapter/ingest/scene-capture';
+import * as THREE from 'three';
+import type { EditorStore } from '../editor-store';
+import { IngestAuthoringAdapter } from './ingest-authoring-adapter';
+import type { IngestMount, MountIngestOptions } from './ingest-game-adapter';
+
+/** Global key under which the host exposes its `three` namespace to the iframe realm. */
+const HOST_THREE_KEY = '__VGAI_HOST_THREE';
+
+/**
+ * Build a blob-module URL that re-exports the host `three` namespace from
+ * `window.parent[HOST_THREE_KEY]`. The iframe's importmap maps `three` to this URL,
+ * so the bundle's `import * as THREE from 'three'` yields the HOST instance.
+ */
+function makeHostThreeReexportUrl(): string {
+  // Only valid JS identifier exports can be re-bound by name; `default` is handled
+  // separately. (three's public API is all identifier-named named exports.)
+  const ident = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  const keys = Object.keys(THREE).filter((k) => k !== 'default' && ident.test(k));
+  const body =
+    `const T = window.parent[${JSON.stringify(HOST_THREE_KEY)}];\n` +
+    `export default T;\n` +
+    keys.map((k) => `export const ${k} = T[${JSON.stringify(k)}];`).join('\n');
+  return URL.createObjectURL(new Blob([body], { type: 'text/javascript' }));
+}
+
+let _hostNsReexportSeq = 0;
+
+/**
+ * D-W1 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) — the three-side twin of
+ * `ingest-iframe-2d.ts`'s `makeHostNamespaceReexportUrl`: build a blob module
+ * re-exporting an ARBITRARY host namespace (a manifest's `extraDeps` beyond
+ * `three` itself — e.g. `gsap`), for the iframe's importmap. Duplicated
+ * (rather than imported from the world2d module) to keep this file's own
+ * module boundary independent of the pixi-flavored ingest-iframe-2d stack —
+ * both are ~10-line, dependency-free functions over `window`/`Blob`/`URL`.
+ */
+function makeHostNamespaceReexportUrl(ns: Record<string, unknown>): string {
+  const key = `__vgaiHostThreeExtraDep_${_hostNsReexportSeq++}`;
+  (window as unknown as Record<string, unknown>)[key] = ns;
+  const ident = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  const keys = Object.keys(ns).filter((k) => k !== 'default' && ident.test(k));
+  const body =
+    `const T = window.parent[${JSON.stringify(key)}];\n` +
+    `export default (T && T.default !== undefined ? T.default : T);\n` +
+    keys.map((k) => `export const ${k} = T[${JSON.stringify(k)}];`).join('\n');
+  return URL.createObjectURL(new Blob([body], { type: 'text/javascript' }));
+}
+
+/**
+ * D-W1 — the three analog of pixi's `Assets.init` basePath wrap: a
+ * document.write iframe keeps the PARENT's `window.location`, so a relative
+ * asset request the bundle makes (through a `three` loader, which routes
+ * every URL through `DefaultLoadingManager`) would otherwise resolve against
+ * the parent editor page, not the served bundle directory. Absolute
+ * (has-a-scheme), root-relative (`/...`), `data:`, and `blob:` URLs already
+ * resolve correctly on their own and pass through unchanged; only bundle-
+ * relative requests get joined against `assetBaseUrl`. `assetBaseUrl` itself
+ * MUST already be absolute here (`new URL(url, assetBaseUrl)` requires an
+ * origin) — the ingest-mode.ts caller resolves a root-relative manifest
+ * value against the editor page's own URL BEFORE calling this (mirrors the
+ * pixi sibling's identical `assetBaseUrl` absolutization). Exported for
+ * direct unit testing (pure, no DOM).
+ */
+export function makeAssetUrlModifier(assetBaseUrl: string): (url: string) => string {
+  const base = assetBaseUrl.endsWith('/') ? assetBaseUrl : `${assetBaseUrl}/`;
+  const isAlreadyResolvable = /^([a-z][a-z0-9+.-]*:)|^\//i;
+  return (url: string) => {
+    if (isAlreadyResolvable.test(url)) return url;
+    return new URL(url, base).toString();
+  };
+}
+
+/**
+ * Assemble the reachable-three iframe document (D-W1): factored into a pure,
+ * directly-unit-testable function so both mount paths below — the original
+ * inline-source mount and the new prebuilt-bundle mount — build their HTML
+ * through ONE seam, and a unit test can pin the exact assembled string
+ * (importmap/base/bodyHtml/script tag) without a real iframe/DOM. Byte-
+ * compatible with the original inline-source document by construction: that
+ * mount passes the SAME `style`/`imports`/inline-script shape it always
+ * built inline, just through this shared assembler now.
+ */
+export interface ReachableThreeDocumentOptions {
+  /** Bare-specifier -> URL importmap entries (MUST include `three`). */
+  imports: Record<string, string>;
+  /** `<base href>` for the iframe, when given. */
+  baseHref?: string | undefined;
+  /** Inline `<style>` block body (kept for the original inline-source mount's exact byte output). */
+  style?: string | undefined;
+  /** DOM injected into `<body>` before the script tag. */
+  bodyHtml?: string | undefined;
+  /** The game's own script — either an inline module body or a `<script type="module" src=...>`. */
+  script: { kind: 'inline'; source: string } | { kind: 'src'; url: string };
+}
+
+export function assembleReachableThreeDocument(opts: ReachableThreeDocumentOptions): string {
+  // Split the closing script token so this module's own bundling never sees a
+  // literal `</script>` (defensive; matches the world2d iframe mounts' convention).
+  const close = `</${'scr'}ipt>`;
+  const baseTag = opts.baseHref ? `<base href="${opts.baseHref}">` : '';
+  const styleTag = opts.style ? `<style>${opts.style}</style>` : '';
+  const importmapTag = `<script type="importmap">${JSON.stringify({ imports: opts.imports })}${close}`;
+  const bodyHtml = opts.bodyHtml ?? '';
+  const scriptTag =
+    opts.script.kind === 'inline'
+      ? `<script type="module">${opts.script.source}${close}`
+      : `<script type="module" src="${opts.script.url}">${close}`;
+  return (
+    `<!doctype html><html><head><meta charset="utf-8">${baseTag}${styleTag}${importmapTag}</head>` +
+    `<body>${bodyHtml}${scriptTag}</body></html>`
+  );
+}
+
+/**
+ * Mount a prebuilt bundle inside a same-origin iframe whose `three` is the host's,
+ * capture its live scene through the shared-`three` trap, and return an
+ * {@link IngestMount} with a real authoring adapter — identical contract to the
+ * shared-ESM {@link import('./ingest-game-adapter').mountIngestGame} path.
+ */
+export async function mountIngestGameIframeReachable(
+  store: EditorStore,
+  gameModuleSrc: string,
+  gameContainer: HTMLElement,
+  opts: MountIngestOptions = {},
+): Promise<IngestMount> {
+  // Expose host `three` to the (same-origin) iframe realm.
+  (window as unknown as Record<string, unknown>)[HOST_THREE_KEY] = THREE;
+  const reexportUrl = makeHostThreeReexportUrl();
+
+  // Trap the host renderer prototype BEFORE the bundle constructs its renderer, so
+  // the bundle's (host-realm) renderer is captured and the editor's pre-existing one
+  // is not (its `render` is an own property set before the trap existed).
+  const capture: SceneCaptureHandle = installSceneCapture(THREE);
+
+  // Build a same-origin iframe and write the bundle document into it. Using
+  // document.write (not srcdoc) guarantees the about:blank doc inherits the parent
+  // origin, so `window.parent.__VGAI_HOST_THREE` and the blob: URL both resolve.
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('data-testid', 'ingest-reachable-frame');
+  iframe.style.cssText =
+    'position:absolute;inset:0;width:100%;height:100%;border:0;background:#000;';
+  gameContainer.appendChild(iframe);
+
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error('iframe contentDocument unavailable (cross-origin?)');
+  doc.open();
+  doc.write(
+    assembleReachableThreeDocument({
+      imports: { three: reexportUrl },
+      style: 'html,body{margin:0;height:100%;overflow:hidden;background:#000}canvas{display:block}',
+      script: { kind: 'inline', source: gameModuleSrc },
+    }),
+  );
+  doc.close();
+
+  // The bundle renders on its first rAF; the host trap captures it.
+  const rt = await capture.waitForCapture(opts.captureTimeoutMs ?? 10_000);
+
+  const loop = {
+    pause: () => rt.renderer.setAnimationLoop(null),
+    resume: () => {
+      const cb = capture.getAnimationLoop(rt.renderer);
+      if (cb) rt.renderer.setAnimationLoop(cb);
+    },
+  };
+
+  const authoring = new IngestAuthoringAdapter(store, rt.scene, {
+    loop,
+    overlay: opts.overlay,
+    persist: opts.persist,
+    destination: opts.destination,
+    camera: rt.camera,
+  });
+
+  const cleanup = () => {
+    try {
+      rt.renderer.setAnimationLoop(null);
+      rt.renderer.dispose();
+    } catch {
+      /* ignore */
+    }
+    capture.uninstall();
+    URL.revokeObjectURL(reexportUrl);
+    iframe.remove();
+    delete (window as unknown as Record<string, unknown>)[HOST_THREE_KEY];
+  };
+
+  const mounted: MountedGame = {
+    kind: 'threejs',
+    scene: rt.scene,
+    camera: rt.camera,
+    drivesOwnLoop: true,
+    setPaused: (paused) => (paused ? loop.pause() : loop.resume()),
+    resize: (w, h) => rt.renderer.setSize(w, h, false),
+    dispose: cleanup,
+    authoring,
+  };
+
+  return { game: mounted, authoring, hostEl: iframe, capture, scene: rt.scene };
+}
+
+/**
+ * D-W1 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) — options for
+ * {@link mountIngestGameIframeReachableBundle}, the prebuilt-EXTERNALIZED-
+ * bundle sibling of {@link mountIngestGameIframeReachable} above (which takes
+ * an INLINE module-source string). Mirrors pixi's
+ * `IframeReachableMultiOpts`/`mountIngestGame2DIframeReachableMulti`
+ * (`@engine/world2d/ingest-iframe-2d.ts`) field-for-field, minus the
+ * pixi-specific `pixiModuleUrl`/`inlineSrc` (three has no version-skew
+ * mechanism this wave — D-W7 — and this function is bundle-only, never
+ * inline).
+ */
+export interface IframeReachableBundleOpts extends MountIngestOptions {
+  /** Load the game bundle from this absolute URL (a built, externalized-`three` multi-file game). */
+  bundleUrl: string;
+  /** `<base href>` for the iframe so the game's relative asset URLs resolve. */
+  baseHref?: string | undefined;
+  /** DOM injected into the iframe body before the bundle's script boots. */
+  bodyHtml?: string | undefined;
+  /** Bare-specifier -> host module-namespace map for this game's OTHER externalized deps beyond `three` (already-resolved, D-Z3 `namespaces`). */
+  extraDeps?: Record<string, Record<string, unknown>> | undefined;
+  /** Bare-specifier -> VERBATIM URL importmap entries (the D-Z3 project-node_modules fallback, already-resolved). */
+  extraDepUrls?: Record<string, string> | undefined;
+  /** Host-side `DefaultLoadingManager.setURLModifier` basePath remap (already absolutized by the caller). */
+  assetBaseUrl?: string | undefined;
+}
+
+/**
+ * Mount a PREBUILT, externalized-`three` bundle (its own `<script type="module"
+ * src=...>`, not an inline source string) inside the same same-origin
+ * reachable-three iframe recipe {@link mountIngestGameIframeReachable} uses:
+ * `installSceneCapture` trapped BEFORE the bundle's module executes (the
+ * importmap/capture setup lives in the SAME `document.write` call, so the
+ * deferred `type="module"` script only ever sees the trap already installed
+ * — verified against the existing inline path's identical ordering), an
+ * importmap resolving `three` (+ `extraDeps`) to host-namespace re-export
+ * blobs (or verbatim D-Z3 URLs), an optional `<base href>`/`bodyHtml`, and an
+ * `assetBaseUrl` asset adapter on the host `three`'s
+ * `DefaultLoadingManager.setURLModifier` (installed before the bundle runs,
+ * restored on dispose) — the three analog of pixi's `Assets.init` wrap.
+ *
+ * Capture-timeout handling is NOT the same as the inline-source mount above
+ * (that one still throws — this task keeps it byte-compatible on purpose):
+ * this bundle path DEGRADES to an embed-only `IngestMount` on a capture
+ * failure (three unreachable/mismatched/bundle never rendered in time),
+ * mirroring `mountIngestGame`'s own degrade shape — so
+ * `enterIngestModeWithGame`'s existing `mount.embedOnly` check (ingest-mode.ts)
+ * applies uniformly to this new route too (D-W1's explicit requirement).
+ */
+export async function mountIngestGameIframeReachableBundle(
+  store: EditorStore,
+  gameContainer: HTMLElement,
+  opts: IframeReachableBundleOpts,
+): Promise<IngestMount> {
+  (window as unknown as Record<string, unknown>)[HOST_THREE_KEY] = THREE;
+  const created: string[] = [];
+  const threeReexportUrl = makeHostThreeReexportUrl();
+  created.push(threeReexportUrl);
+
+  const imports: Record<string, string> = { three: threeReexportUrl };
+  for (const [spec, ns] of Object.entries(opts.extraDeps ?? {})) {
+    const url = makeHostNamespaceReexportUrl(ns);
+    created.push(url);
+    imports[spec] = url;
+  }
+  // D-Z3 fallback: verbatim URL entries, no blob wrapping, merged in beside
+  // the host-namespace ones (mirrors `mountIngestGame2DIframeReachableMulti`'s
+  // identical merge).
+  for (const [spec, url] of Object.entries(opts.extraDepUrls ?? {})) imports[spec] = url;
+
+  // Trap the host renderer prototype BEFORE the bundle constructs its renderer
+  // (same ordering guarantee as the inline-source mount above).
+  const capture: SceneCaptureHandle = installSceneCapture(THREE);
+
+  // Host-side asset URL remap (asset adapter): install BEFORE the bundle
+  // runs, restore on dispose — pure host library configuration, never
+  // touches the game source.
+  let restoreUrlModifier: (() => void) | undefined;
+  if (opts.assetBaseUrl) {
+    THREE.DefaultLoadingManager.setURLModifier(makeAssetUrlModifier(opts.assetBaseUrl));
+    restoreUrlModifier = () => THREE.DefaultLoadingManager.setURLModifier((u) => u);
+  }
+
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('data-testid', 'ingest-reachable-frame');
+  iframe.style.cssText =
+    'position:absolute;inset:0;width:100%;height:100%;border:0;background:#000;';
+  gameContainer.appendChild(iframe);
+
+  const cleanupHost = () => {
+    capture.uninstall();
+    restoreUrlModifier?.();
+    for (const u of created) URL.revokeObjectURL(u);
+    iframe.remove();
+    delete (window as unknown as Record<string, unknown>)[HOST_THREE_KEY];
+  };
+
+  const doc = iframe.contentDocument;
+  if (!doc) {
+    cleanupHost();
+    throw new Error('iframe contentDocument unavailable (cross-origin?)');
+  }
+  doc.open();
+  doc.write(
+    assembleReachableThreeDocument({
+      imports,
+      baseHref: opts.baseHref,
+      bodyHtml: opts.bodyHtml,
+      script: { kind: 'src', url: opts.bundleUrl },
+    }),
+  );
+  doc.close();
+
+  let rt: Awaited<ReturnType<SceneCaptureHandle['waitForCapture']>>;
+  try {
+    rt = await capture.waitForCapture(opts.captureTimeoutMs ?? 10_000);
+  } catch {
+    // three unreachable / bundle failed to render a host-realm frame within
+    // the timeout — degrade to embed-only (mountIngestGame's own degrade
+    // shape) rather than throwing, so the caller's existing
+    // `mount.embedOnly` check takes over (D-W1).
+    return {
+      embedOnly: true,
+      hostEl: iframe,
+      capture,
+      game: {
+        kind: 'threejs',
+        scene: new THREE.Scene(),
+        camera: new THREE.PerspectiveCamera(),
+        drivesOwnLoop: true,
+        resize: () => {},
+        dispose: cleanupHost,
+      },
+    };
+  }
+
+  const loop = {
+    pause: () => rt.renderer.setAnimationLoop(null),
+    resume: () => {
+      const cb = capture.getAnimationLoop(rt.renderer);
+      if (cb) rt.renderer.setAnimationLoop(cb);
+    },
+  };
+
+  const authoring = new IngestAuthoringAdapter(store, rt.scene, {
+    loop,
+    overlay: opts.overlay,
+    persist: opts.persist,
+    destination: opts.destination,
+    camera: rt.camera,
+  });
+
+  const cleanup = () => {
+    try {
+      rt.renderer.setAnimationLoop(null);
+      rt.renderer.dispose();
+    } catch {
+      /* ignore */
+    }
+    cleanupHost();
+  };
+
+  const mounted: MountedGame = {
+    kind: 'threejs',
+    scene: rt.scene,
+    camera: rt.camera,
+    drivesOwnLoop: true,
+    setPaused: (paused) => (paused ? loop.pause() : loop.resume()),
+    resize: (w, h) => rt.renderer.setSize(w, h, false),
+    dispose: cleanup,
+    authoring,
+  };
+
+  return { game: mounted, authoring, hostEl: iframe, capture, scene: rt.scene };
+}

package/src/authoring/ingest-overlay.ts

@@ -0,0 +1,193 @@
+/**
+ * Ingest overlay persistence — the honest serialize-back for an UNMODIFIED game.
+ *
+ * We never touch the game's source. Instead we persist the editor's edits beside
+ * it as an OVERLAY keyed by the object's stable structural-path id, and reapply it
+ * on the next ingest (after the game rebuilds its scene). This is the founding
+ * doc's "Overlay file" persistence mode (`docs/ADAPTER-ARCHITECTURE.md` §3.2,
+ * `docs/ADAPTER-VISION-ORIGINAL.md` "Patch File"): same `PersistenceProvider`
+ * interface as `.vscn`, different source of truth.
+ *
+ * The envelope TYPE + pure parsing (`OverlayFile`, `parseOverlayFile`, the
+ * legacy-flat-file upgrade) moved engine-side (T3.8, docs/DECISIONS-PENDING.md
+ * §D9) so the runtime ship-path applier (`@engine/adapter/ingest/overlay-applier.ts`)
+ * can share the SAME parsing rather than duplicating it — re-exported below
+ * unchanged so every existing import site here keeps working byte-for-byte.
+ *
+ * Storage transport (the "overlay unification" fix, docs/BACKBONE-TASKS.md's
+ * T3.3 close-out finding): `loadOverlay`/`saveOverlay` used to go straight
+ * through `getStorageBackend()`, which in server mode is `HttpStorage` —
+ * hard-rooted at `<projectRoot>/public/` — so the overlay actually landed at
+ * `<projectRoot>/public/.vgai/overlays/<id>.json`, contradicting `overlayPath()`'s
+ * "project-root-relative" doc comment and splitting the project into TWO
+ * `.vgai/` dirs (the editor-state/thumbnail/scaffold-baseline machinery, and
+ * `authoring/world-overlay.ts`'s manifest-world overlays, both use the
+ * project-root `.vgai/`). This module now follows the EXACT mode-branched
+ * pattern `world-overlay.ts` established (T6.1 §1.G):
+ *   - browser mode (`getEditorMode() === 'browser'`): `getStorageBackend()`
+ *     directly — OPFS/FSA already root at the TRUE project folder, no `public/`
+ *     insertion exists there.
+ *   - server mode: the dedicated `/__editor/vgai-file` GET/POST route pair
+ *     (`editor-server.ts`), which reads/writes `<projectRoot>/.vgai/...`
+ *     directly via `node:fs`, bypassing `HttpStorage`'s `public/` rooting.
+ * `overlayPath(gameId)` itself is UNCHANGED — it is also the ship path's
+ * default fetch URL (`overlay-applier.ts`).
+ *
+ * Back-compat read: `loadOverlay` tries the unified project-root location
+ * first, and — only if nothing is found there — falls back to the legacy
+ * `public/`-rooted location a pre-fix save would have written, so overlays
+ * saved before this fix keep loading. A hit on the legacy path logs one
+ * `console.warn` per `gameId` (never repeated) and is NEVER written back or
+ * deleted; the next `saveOverlay` for that id writes only the unified
+ * project-root location.
+ */
+
+import {
+  emptyOverlayFile,
+  type IngestOverlay,
+  type IngestOverride,
+  OVERLAY_FORMAT_VERSION,
+  type OverlayFile,
+  overlayPath,
+  parseOverlayFile,
+} from '@engine/adapter/ingest/overlay-file';
+import { getEditorMode } from '../editor-mode';
+import { getStorageBackend } from '../storage';
+
+export type { IngestOverlay, IngestOverride, OverlayFile };
+export { OVERLAY_FORMAT_VERSION, overlayPath };
+
+const BASE = '/__editor';
+
+/** `gameId`s we've already warned about finding only at the legacy location. */
+const warnedLegacyIds = new Set<string>();
+
+/** Read the unified project-root overlay location, or `undefined` if absent/unreadable. */
+async function readProjectRoot(path: string): Promise<string | undefined> {
+  try {
+    if (getEditorMode() === 'browser') {
+      const backend = getStorageBackend();
+      if (!(await backend.exists(path))) return undefined;
+      return await backend.read(path);
+    }
+    const res = await fetch(`${BASE}/vgai-file?${new URLSearchParams({ path })}`);
+    if (!res.ok) return undefined;
+    return await res.text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the legacy `public/`-rooted overlay location, or `undefined` if
+ * absent/unreadable. Server mode's `getStorageBackend()` IS `HttpStorage`
+ * (hard-rooted at `<projectRoot>/public/`), so the plain `overlayPath(gameId)`
+ * string already resolves there; browser mode's backend roots at the TRUE
+ * project folder, so the legacy file must be addressed with an explicit
+ * `public/` prefix.
+ */
+async function readLegacy(gameId: string): Promise<string | undefined> {
+  try {
+    const backend = getStorageBackend();
+    const legacyPath =
+      getEditorMode() === 'browser' ? `public/${overlayPath(gameId)}` : overlayPath(gameId);
+    if (!(await backend.exists(legacyPath))) return undefined;
+    return await backend.read(legacyPath);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Load a game's saved overlay envelope, or an empty envelope if none exists /
+ * is unreadable anywhere. Always returns the {@link OverlayFile} shape —
+ * legacy flat-file content is transparently wrapped (`parseOverlayFile`,
+ * engine-side), whether found at the unified or the legacy location. Loads
+ * are read-only: a legacy hit is never rewritten or deleted here — only the
+ * next `saveOverlay` moves this `gameId` onto the unified location.
+ */
+export async function loadOverlay(gameId: string): Promise<OverlayFile> {
+  const path = overlayPath(gameId);
+
+  const primary = await readProjectRoot(path);
+  if (primary !== undefined) {
+    try {
+      return parseOverlayFile(JSON.parse(primary) as unknown);
+    } catch {
+      // Unparseable at the unified location — fall through and try legacy too.
+    }
+  }
+
+  const legacy = await readLegacy(gameId);
+  if (legacy !== undefined) {
+    try {
+      const parsed = parseOverlayFile(JSON.parse(legacy) as unknown);
+      if (!warnedLegacyIds.has(gameId)) {
+        warnedLegacyIds.add(gameId);
+        const legacyPath = getEditorMode() === 'browser' ? `public/${path}` : path;
+        console.warn(
+          `ingest-overlay: '${gameId}' overlay found only at the legacy location (${legacyPath}), ` +
+            `not the unified project-root location (${path}). The next save will write ${path}.`,
+        );
+      }
+      return parsed;
+    } catch {
+      // Unparseable legacy content either — fall through to empty.
+    }
+  }
+
+  return emptyOverlayFile();
+}
+
+/**
+ * Persist a game's overlay — always as the D9 envelope (including the first
+ * save after loading a legacy flat file: the silent-upgrade path), and always
+ * to the unified project-root location (browser: `getStorageBackend()`
+ * directly; server: the dedicated `/__editor/vgai-file` POST route — never
+ * the legacy `public/`-rooted path, even if this `gameId`'s overlay was just
+ * loaded from there). `gameVersion` is the mounted game's manifest `version`
+ * (`ingest-mode.ts` threads it from either the manifest route's resolved
+ * manifest or the fixture route's `IngestGame.gameVersion`); omitted/`null`
+ * stamps `authoredAgainst.gameVersion: null` rather than fabricating one
+ * (anti-shim).
+ *
+ * `upstreamPin` (R5, docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)) is the
+ * mounted game's `UPSTREAM.md` pin, when `ingest-mode.ts` could discover one
+ * for this session (see its `readUpstreamPinForActiveProject`). Deliberately
+ * OMITTED (not defaulted to `null`) when the caller doesn't pass it at all —
+ * that keeps every pre-R5 call site (and every existing test pinning the
+ * on-disk envelope shape byte-for-byte) writing the EXACT SAME JSON as
+ * before, with no `upstreamPin` key at all: that omission is itself the
+ * signal `./overlay-file.ts`'s `parseOverlayFile`/`overlay-report.ts` treat
+ * as "legacy, never checked" on a later load. Once a caller DOES pass a
+ * value (a string, or an explicit `null` for "looked, found nothing" —
+ * `ingest-mode.ts` always passes one of these two once it's R5-aware), the
+ * key is always written from then on.
+ */
+export async function saveOverlay(
+  gameId: string,
+  overlay: IngestOverlay,
+  gameVersion?: string | null,
+  upstreamPin?: string | null,
+): Promise<void> {
+  const authoredAgainst: OverlayFile['authoredAgainst'] = { gameVersion: gameVersion ?? null };
+  if (upstreamPin !== undefined) authoredAgainst.upstreamPin = upstreamPin;
+  const file: OverlayFile = {
+    formatVersion: OVERLAY_FORMAT_VERSION,
+    authoredAgainst,
+    overrides: overlay,
+  };
+  const path = overlayPath(gameId);
+  const content = JSON.stringify(file, null, 2);
+
+  if (getEditorMode() === 'browser') {
+    await getStorageBackend().write(path, content);
+    return;
+  }
+  const res = await fetch(`${BASE}/vgai-file`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, content }),
+  });
+  if (!res.ok) throw new Error(`saveOverlay '${gameId}': HTTP ${res.status}`);
+}

package/src/authoring/layered-pick.ts

@@ -0,0 +1,87 @@
+/**
+ * Layered viewport picking (B4, D12) — "click anything you can see; topmost
+ * visible layer wins." Shell POLICY over the composite's public seams, kept a
+ * separate module (rather than living inline in `editor-viewport.ts`) so it
+ * stays lean AND unit-testable with plain fake adapters — no real DOM/canvas
+ * needed.
+ *
+ * This module speaks ONLY the public contract: `CompositeAuthoringAdapter
+ * .childAdapters()` (T0), the `AuthoringAdapter.pickable` provider (D12,
+ * `@engine/adapter`), and `world-session-state.ts`'s session toggles. It never
+ * reaches into any one child adapter's own private, format-specific model (no
+ * concrete-world-shape vocabulary of any kind here) — `instanceof
+ * CompositeAuthoringAdapter` is the ONE sanctioned type check (that class's
+ * own doc comment blesses exactly this use, mirroring
+ * `authoring/first-party-inspector/is-first-party-selection.ts`'s identical
+ * precedent).
+ *
+ * Walk order: the composite's NON-threejs children (react/pixi design-time
+ * layers), topmost-first by (install-time) manifest zOrder — `stackOrder`
+ * sorts bottom-to-top, so `.reverse()` gives topmost-first while preserving
+ * its own tie-break rule. The focused threejs world is appended LAST
+ * (canvas-bottom) regardless of its manifest zOrder — it always renders
+ * beneath every positioned design-time layer (`design-time-layers.ts`'s own
+ * doc comment: "the threejs canvas keeps its existing slot"), so it is
+ * correct for it to lose every pick to a layer that also claims the point.
+ *
+ * A layer that is eye-hidden or pick-locked (`world-session-state.ts`, B1) is
+ * skipped ENTIRELY — its `pickable.pick` is never even called. This is a
+ * SEPARATE mechanism from a layer's `interactive` toggle: an interactive
+ * layer's DOM has `pointer-events: auto`, so a real pointer event lands on the
+ * layer's own element and this walk (triggered only by the CANVAS's own
+ * `pointerup` listener) never runs at all for that event — mutually exclusive
+ * by construction, no code needed here for it.
+ *
+ * When the active adapter is NOT a composite (single-world project, or a
+ * non-composite override), this degrades to that one adapter's own
+ * `pickable.pick` (or `null` if it doesn't have one) — today's single-world
+ * behavior, unchanged.
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import { stackOrder } from '@engine/runtime/input-router';
+import type { EditorStore } from '../editor-store';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { isWorldHidden, isWorldPickLocked } from './world-session-state';
+
+/** Topmost-first pick across every visible, pick-unlocked layer of the active
+ *  (possibly composite) authoring adapter. Returns the winning node id, or
+ *  `null` when nothing under `(clientX, clientY)` claims the point. */
+export function pickTopmost(store: EditorStore, clientX: number, clientY: number): string | null {
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) {
+    return active.pickable?.pick(clientX, clientY) ?? null;
+  }
+
+  const children = active.childAdapters();
+  const layered = children.filter((c) => c.kind !== 'threejs');
+  const threejs = children.filter((c) => c.kind === 'threejs');
+
+  // `stackOrder` wants `{id, zOrder}` (`ClaimEntry`) — reuse `worldId` as its
+  // `id` (this walk has no separate id vocabulary of its own).
+  const layeredClaims = layered.map((c) => ({
+    id: c.worldId,
+    zOrder: c.zOrder,
+    worldId: c.worldId,
+    adapter: c.adapter,
+  }));
+
+  // Topmost-first: `stackOrder` is bottom-to-top (ascending zOrder, ties by
+  // original array order) — `.reverse()` flips it without disturbing its own
+  // tie-break rule (a later-declared same-zOrder layer still wins the tie,
+  // now by being checked FIRST instead of sorting last).
+  const order: Array<{ worldId: string; adapter: AuthoringAdapter }> = [
+    ...stackOrder(layeredClaims).reverse(),
+    // The focused threejs world paints/picks LAST — canvas-bottom, regardless
+    // of its own manifest zOrder (see module doc comment).
+    ...threejs,
+  ];
+
+  for (const { worldId, adapter } of order) {
+    if (isWorldHidden(worldId) || isWorldPickLocked(worldId)) continue;
+    const hit = adapter.pickable?.pick(clientX, clientY);
+    if (hit) return hit;
+  }
+  return null;
+}