@vgai/editor 0.2.0

package/src/ingest/discovery-react.ts

@@ -0,0 +1,132 @@
+/**
+ * In-tree native-React ingest-game discovery (Track N, N2 —
+ * docs/REACT-INGEST-LANDING-DESIGN.md D-N2). The react sibling of
+ * `discovery.ts`/`discovery2d.ts`: every vendored native-React game gets its
+ * own `vgai.game.json` under `./games-react/<id>/` (one `react` world, an
+ * `{ ingest: { strategy: 'deduped' } }` adapter, `entry` pointing at a
+ * host-shim module in the SAME folder — D-N2). This module discovers them
+ * via `import.meta.glob`, mirroring `discovery2d.ts`'s mechanics.
+ *
+ * UNLIKE `discovery.ts`/`discovery2d.ts`, this module does NOT also glob the
+ * entry module itself: an `ingest-react` world mounts through
+ * `resolveWorldAdapter` (`adapter-resolver.ts`'s `resolveIngestReactAdapter`,
+ * N1) — the SAME `/@fs/`-dynamic-import + `createRoot` host stack
+ * `default-react` uses — rather than a capture-based bridge, so there is no
+ * "build an `IngestGame`/`IngestGame2D` descriptor with its own `load`
+ * thunk" step to replicate here. This module's ONLY job is: find every
+ * `games-react/*\/vgai.game.json`, validate its single world is a real
+ * `ingest-react` `'deduped'` world, and hand back the parsed
+ * `ResolvedGameManifest` + that world's absolute on-disk folder (the
+ * `projectRoot` `resolveWorldAdapter` needs for its `entry`'s `/@fs/`
+ * dynamic import and its `loadProjectGameProvider` lookup) — see
+ * `ingest-mode.ts`'s `enterIngestModeReact` for the mount step.
+ *
+ * `projectRoot` (an ABSOLUTE filesystem path) can't come from
+ * `import.meta.glob`/`import.meta.url` alone (those resolve to HTTP URLs in
+ * the browser, not filesystem paths) — it is built from
+ * `__VGAI_ENGINE_ROOT__` (a dev-server-only Vite `define`, `server/dev.ts`,
+ * mirroring the existing `__VGAI_PROJECT_PATH__` define) plus this folder's
+ * FIXED, known-at-build-time relative offset. `browser` editor-mode builds
+ * (no dev server) never define `__VGAI_ENGINE_ROOT__` — `getIngestGameReact`
+ * callers must check `getEditorMode() !== 'browser'` first (mirrors every
+ * other `/@fs/`-dependent ingest route's `getEditorMode() === 'browser'`
+ * guard, e.g. `ingest-mode.ts`'s `tryManifestIngestRoute`).
+ */
+
+import { loadGameManifest, type ResolvedGameManifest } from '@engine/manifest/load';
+
+declare const __VGAI_ENGINE_ROOT__: string;
+
+const manifestModules = import.meta.glob('./games-react/*/vgai.game.json', {
+  eager: true,
+  import: 'default',
+}) as Record<string, unknown>;
+
+const MANIFEST_KEY_RE = /^\.\/games-react\/([^/]+)\/vgai\.game\.json$/;
+
+function folderIdFromManifestKey(key: string): string {
+  const match = MANIFEST_KEY_RE.exec(key);
+  if (!match?.[1]) {
+    throw new Error(`react ingest discovery: unexpected manifest glob key "${key}"`);
+  }
+  return match[1];
+}
+
+/** A discovered native-React ingest fixture: its parsed manifest (exactly one
+ *  `ingest-react` `'deduped'` world) plus that world for convenience. */
+export interface IngestGameReact {
+  readonly folderId: string;
+  readonly manifest: ResolvedGameManifest;
+  readonly worldId: string;
+}
+
+function buildIngestGameReact(folderId: string, raw: unknown): IngestGameReact {
+  const manifest = loadGameManifest(raw);
+  if (manifest.worlds.length !== 1) {
+    throw new Error(
+      `react ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
+        `(found ${manifest.worlds.length}).`,
+    );
+  }
+  const world = manifest.worlds[0]!;
+  if (
+    world.kind !== 'react' ||
+    world.adapter.type !== 'ingest' ||
+    world.adapter.identity !== 'ingest-react'
+  ) {
+    throw new Error(
+      `react ingest discovery: "${folderId}/vgai.game.json"'s world must be a react { ingest } ` +
+        `world (found kind "${world.kind}", adapter identity "${world.adapter.identity}").`,
+    );
+  }
+  if (world.adapter.strategy !== 'deduped') {
+    throw new Error(
+      `react ingest discovery: "${folderId}" declares strategy "${world.adapter.strategy}" — ` +
+        "react ingestion v1 supports ONLY 'deduped' (D-N3).",
+    );
+  }
+  if (!world.entry) {
+    throw new Error(
+      `react ingest discovery: "${folderId}" has no \`entry\` — an ingest-react world's \`entry\` ` +
+        'must point at the host-shim module in the same folder (D-N2).',
+    );
+  }
+  return { folderId, manifest, worldId: world.id };
+}
+
+let _cache: IngestGameReact[] | null = null;
+
+/** Every in-tree native-React ingest fixture, discovered from
+ *  `./games-react/*\/vgai.game.json`. */
+export function discoverIngestGamesReact(): IngestGameReact[] {
+  if (!_cache) {
+    _cache = Object.entries(manifestModules)
+      .map(([key, raw]) => buildIngestGameReact(folderIdFromManifestKey(key), raw))
+      .sort((a, b) => a.folderId.localeCompare(b.folderId));
+  }
+  return _cache;
+}
+
+/** Look up one discovered react ingest game by its folder id (`?ingest=<id>`
+ *  resolution — the folder id IS the world id by convention, one world per
+ *  manifest, but callers should key off `folderId` since that's what the URL
+ *  param names). */
+export function getIngestGameReact(folderId: string): IngestGameReact | undefined {
+  return discoverIngestGamesReact().find((g) => g.folderId === folderId);
+}
+
+/**
+ * The absolute on-disk `projectRoot` for a discovered react ingest game's
+ * folder — what `resolveWorldAdapter`/`resolveAllWorlds` need to resolve its
+ * `entry` (and, transitively, `loadProjectGameProvider`'s
+ * `src/ui/game-state.tsx` lookup). `undefined` when
+ * `__VGAI_ENGINE_ROOT__` isn't defined (browser-mode static build — no dev
+ * server, no `/@fs/` route to resolve through anyway).
+ */
+export function ingestGameReactProjectRoot(folderId: string): string | undefined {
+  if (typeof __VGAI_ENGINE_ROOT__ !== 'string' || !__VGAI_ENGINE_ROOT__) return undefined;
+  const root = __VGAI_ENGINE_ROOT__.endsWith('/')
+    ? __VGAI_ENGINE_ROOT__.slice(0, -1)
+    : __VGAI_ENGINE_ROOT__;
+  return `${root}/packages/editor/src/ingest/games-react/${folderId}`;
+}

package/src/ingest/discovery.ts

@@ -0,0 +1,205 @@
+/**
+ * In-tree ingest-game discovery — T3.3 slice 3 (docs/CLI-ON-FOLDER-DESIGN.md
+ * §1E). Replaces the deleted `ingest/games/registry.ts` (`INGEST_GAMES`
+ * array): every fixture game folder under `ingest/games/<id>/` now carries
+ * its own `vgai.game.json` (one `threejs` world, `{ ingest }` adapter); this
+ * module discovers them via `import.meta.glob` and builds the SAME
+ * `IngestGame[]` shape the registry used to hand-maintain — adding a new
+ * fixture becomes "drop a folder with a manifest", zero code edits here.
+ *
+ * Module-loading choice (the slice's CAVEAT): `resolveIngestDescriptor`'s
+ * `/@fs/${projectRoot}/...` dynamic-import route (adapter-resolver.ts) is
+ * built for an EXTERNAL project folder outside this package's own source
+ * tree (the CLI-on-folder route, §1E's other half) — not for these IN-TREE
+ * fixtures, which Vite already knows about statically. So this module does
+ * NOT call `resolveIngestDescriptor` at all; it uses separate
+ * `import.meta.glob`s, all statically analyzable by Vite (and by Vitest,
+ * which shares Vite's transform pipeline) in both dev AND unit tests, with
+ * no runtime fetch/`/@fs/` involved:
+ *   - manifests (`vgai.game.json`, eager, parsed JSON) — the source of truth
+ *     for id/description/strategy/assets/domStubs/captureTimeoutMs (`name`
+ *     comes from the manifest's top-level game name);
+ *   - entry modules (`*.js`, LAZY thunks) for the `shared`/`deduped`
+ *     strategies — same shape as the registry's `load: () => import(...)`,
+ *     side-effecting only when actually launched (a bare `import.meta.glob`
+ *     with no `eager`/`query` option yields exactly `() => Promise<Module>`
+ *     thunks, matching `IngestGame.load` byte-for-byte);
+ *   - raw text (`?raw` query) for `entryHtml` files (iframe-reachable's `.js`
+ *     module source / opaque-embed's `.html` document) — never
+ *     imported/executed by the host, just read as a string;
+ *   - `?url` asset globs for the manifest's `assets` map (relative paths ->
+ *     Vite's built/served asset URL, same as the registry's per-game `?url`
+ *     imports, just data-driven instead of one hand-written import per game).
+ */
+
+import { loadGameManifest } from '@engine/manifest/load';
+import type { IngestGame } from './types';
+
+const manifestModules = import.meta.glob('./games/*/vgai.game.json', {
+  eager: true,
+  import: 'default',
+}) as Record<string, unknown>;
+
+const entryModules = import.meta.glob('./games/*/*.js') as Record<string, () => Promise<unknown>>;
+
+const entryHtmlText = import.meta.glob('./games/*/*.{html,js}', {
+  eager: true,
+  query: '?raw',
+  import: 'default',
+}) as Record<string, string>;
+
+const assetUrls = import.meta.glob('./games/*/assets/**', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+}) as Record<string, string>;
+
+const MANIFEST_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.game\.json$/;
+
+function folderIdFromManifestKey(key: string): string {
+  const match = MANIFEST_KEY_RE.exec(key);
+  if (!match?.[1]) {
+    throw new Error(`ingest discovery: unexpected manifest glob key "${key}"`);
+  }
+  return match[1];
+}
+
+function resolveAssetUrls(
+  folderId: string,
+  assets: Record<string, string>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [pathSubstring, relPath] of Object.entries(assets)) {
+    const key = `./games/${folderId}/${relPath}`;
+    const url = assetUrls[key];
+    if (!url) {
+      throw new Error(
+        `ingest discovery: "${folderId}"'s asset "${relPath}" did not match any served asset ` +
+          `(looked for glob key "${key}" — available: ${Object.keys(assetUrls).join(', ')})`,
+      );
+    }
+    resolved[pathSubstring] = url;
+  }
+  return resolved;
+}
+
+type BaseFields = Pick<
+  IngestGame,
+  'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs' | 'gameVersion'
+>;
+
+/** `shared`/`deduped`: a `load` thunk off the entry-module glob. */
+function buildModuleLoadedGame(
+  folderId: string,
+  world: { entry: string | undefined },
+  strategy: 'shared' | 'deduped',
+  base: BaseFields,
+): IngestGame {
+  if (!world.entry) {
+    throw new Error(
+      `ingest discovery: "${folderId}" (strategy "${strategy}") has no \`entry\` — ` +
+        "shared/deduped ingest worlds need the game module's folder-relative path there.",
+    );
+  }
+  const key = `./games/${folderId}/${world.entry}`;
+  const load = entryModules[key];
+  if (!load) {
+    throw new Error(
+      `ingest discovery: "${folderId}"'s entry "${world.entry}" did not match any game ` +
+        `module (looked for glob key "${key}").`,
+    );
+  }
+  return { ...base, load };
+}
+
+/** `iframe-reachable`/`opaque-embed`: raw text off the entryHtml file glob. */
+function buildFileBackedGame(
+  folderId: string,
+  entryHtml: string | undefined,
+  strategy: 'iframe-reachable' | 'opaque-embed',
+  base: BaseFields,
+): IngestGame {
+  if (!entryHtml) {
+    throw new Error(
+      `ingest discovery: "${folderId}" (strategy "${strategy}") has no \`entryHtml\`.`,
+    );
+  }
+  const key = `./games/${folderId}/${entryHtml}`;
+  const text = entryHtmlText[key];
+  if (text === undefined) {
+    throw new Error(
+      `ingest discovery: "${folderId}"'s entryHtml "${entryHtml}" did not match any file ` +
+        `(looked for glob key "${key}").`,
+    );
+  }
+  return strategy === 'iframe-reachable'
+    ? { ...base, iframeReachableSrc: text }
+    : { ...base, embedHtml: text };
+}
+
+function buildIngestGame(folderId: string, raw: unknown): IngestGame {
+  const manifest = loadGameManifest(raw);
+  if (manifest.worlds.length !== 1) {
+    throw new Error(
+      `ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
+        `(found ${manifest.worlds.length}).`,
+    );
+  }
+  const world = manifest.worlds[0]!;
+  if (world.adapter.type !== 'ingest' || world.adapter.identity !== 'ingest-three') {
+    throw new Error(
+      `ingest discovery: "${folderId}/vgai.game.json"'s world must be a threejs { ingest } ` +
+        `world (found adapter identity "${world.adapter.identity}").`,
+    );
+  }
+  const { adapter } = world;
+
+  const base: BaseFields = {
+    id: world.id,
+    name: manifest.name,
+    description: world.description ?? '',
+    // D9 (docs/DECISIONS-PENDING.md §D9): the manifest's own `version`, so a
+    // later mount can compare a saved overlay's `authoredAgainst.gameVersion`
+    // against what's currently running (`overlay-report.ts`).
+    gameVersion: manifest.version,
+    ...(adapter.assets !== undefined ? { assets: resolveAssetUrls(folderId, adapter.assets) } : {}),
+    ...(adapter.domStubs !== undefined ? { domStubs: adapter.domStubs } : {}),
+    ...(adapter.captureTimeoutMs !== undefined
+      ? { captureTimeoutMs: adapter.captureTimeoutMs }
+      : {}),
+  };
+
+  switch (adapter.strategy) {
+    case 'shared':
+    case 'deduped':
+      return buildModuleLoadedGame(folderId, world, adapter.strategy, base);
+    case 'iframe-reachable':
+    case 'opaque-embed':
+      return buildFileBackedGame(folderId, adapter.entryHtml, adapter.strategy, base);
+    default: {
+      // Exhaustive per IngestStrategySchema's 4 members — a new strategy
+      // value added to the schema without a branch here is a compile error.
+      const exhaustive: never = adapter.strategy;
+      throw new Error(
+        `ingest discovery: "${folderId}" has an unhandled ingest strategy ${JSON.stringify(exhaustive)}.`,
+      );
+    }
+  }
+}
+
+let _cache: IngestGame[] | null = null;
+
+/** Every in-tree ingest fixture game, discovered from `./games/*\/vgai.game.json`. */
+export function discoverIngestGames(): IngestGame[] {
+  if (!_cache) {
+    _cache = Object.entries(manifestModules)
+      .map(([key, raw]) => buildIngestGame(folderIdFromManifestKey(key), raw))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  }
+  return _cache;
+}
+
+/** Look up one discovered ingest game by id (`?ingest=<id>` resolution). */
+export function getIngestGame(id: string): IngestGame | undefined {
+  return discoverIngestGames().find((g) => g.id === id);
+}

package/src/ingest/discovery2d.ts

@@ -0,0 +1,204 @@
+/**
+ * In-tree world2d (PixiJS) ingest-game discovery — T6.1 slice 4
+ * (docs/MULTI-WORLD-DESIGN.md §1.E/§3 slice 4, world2d silo retirement). The
+ * pixi sibling of `discovery.ts`: replaces the deleted
+ * `world2d-demo/games/registry.ts` (`WORLD2D_INGEST_GAMES` array) — the three
+ * vgai-authored mini-games (bunnymark, flappy, tilemap-camera) each now carry
+ * their own `vgai.game.json` under `./games-2d/<id>/` (one `pixijs` world, a
+ * `{ ingest }` adapter); this module discovers them via `import.meta.glob`,
+ * mirroring `discovery.ts`'s mechanics exactly (see that file's doc comment
+ * for the full "why glob, not resolveIngest2DDescriptor" rationale — same
+ * reasoning applies here: these are IN-TREE fixtures Vite already knows about
+ * statically, not an external project folder).
+ *
+ * OVERLAY-KEY CONTINUITY (§1.E/§1.G): each fixture's world id is UNCHANGED
+ * from its old registry-era id (`bunnymark`/`flappy`/`tilemap-camera`, no
+ * `2d-` prefixing) — a pre-existing silo-era overlay would have lived at
+ * `.vgai/overlays/2d-<id>.json` (the retired `overlayPath2D`); this slice's
+ * unified overlay path is `.vgai/overlays/<id>.json` (`authoring/
+ * world-overlay.ts`, §1.G) — a DIFFERENT file, not a rename. Old `2d-*.json`
+ * overlays are dev-local artifacts, left in place, per §1.H's "no migration"
+ * note. `id` reachability (the id string itself) survives; the overlay FILE
+ * does not carry forward automatically.
+ *
+ * Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2, P1/P2) added a real
+ * `iframe-reachable` branch alongside `shared`/`deduped`: an externalized
+ * built bundle descriptor built straight from the manifest's six new
+ * `ingest.{bundleUrl,baseHref,assetBaseUrl,extraDeps,pixiModuleUrl,bodyHtml}`
+ * fields — see `buildIframeReachableGame2D` below. `opaque-embed` still
+ * throws HERE (no in-tree world2d fixture uses it, and this synchronous
+ * glob-discovery route has no runtime fetch to build a lazy `embedHtml`
+ * thunk from) — D-W2 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) wires it for the
+ * manifest-driven external-folder route instead
+ * (`resolveIngest2DDescriptor`/`adapter-resolver.ts`), where `IngestGame2D`
+ * now DOES have an `embedHtml` field.
+ */
+
+import { loadGameManifest } from '@engine/manifest/load';
+import type { IngestGame2D } from '@engine/world2d/ingest2d';
+import { resolveExtraDeps } from './host-namespace-registry';
+
+const manifestModules = import.meta.glob('./games-2d/*/vgai.game.json', {
+  eager: true,
+  import: 'default',
+}) as Record<string, unknown>;
+
+const entryModules = import.meta.glob('./games-2d/*/*.ts') as Record<
+  string,
+  () => Promise<unknown>
+>;
+
+const MANIFEST_KEY_RE = /^\.\/games-2d\/([^/]+)\/vgai\.game\.json$/;
+
+function folderIdFromManifestKey(key: string): string {
+  const match = MANIFEST_KEY_RE.exec(key);
+  if (!match?.[1]) {
+    throw new Error(`world2d ingest discovery: unexpected manifest glob key "${key}"`);
+  }
+  return match[1];
+}
+
+type BaseFields2D = Pick<IngestGame2D, 'id' | 'name' | 'description' | 'captureTimeoutMs'>;
+
+function buildModuleLoadedGame2D(
+  folderId: string,
+  world: { entry: string | undefined },
+  strategy: 'shared' | 'deduped',
+  base: BaseFields2D,
+): IngestGame2D {
+  if (!world.entry) {
+    throw new Error(
+      `world2d ingest discovery: "${folderId}" (strategy "${strategy}") has no \`entry\` — ` +
+        "shared/deduped ingest-pixi worlds need the game module's folder-relative path there.",
+    );
+  }
+  const key = `./games-2d/${folderId}/${world.entry}`;
+  const load = entryModules[key];
+  if (!load) {
+    throw new Error(
+      `world2d ingest discovery: "${folderId}"'s entry "${world.entry}" did not match any game ` +
+        `module (looked for glob key "${key}").`,
+    );
+  }
+  return { ...base, tier: 'shared', load };
+}
+
+/**
+ * Build an `IngestGame2D` for the `iframe-reachable` strategy straight from
+ * the manifest's Track P fields (docs/PIXI-INGEST-LANDING-DESIGN.md §2) —
+ * `bundleUrl` is required by the schema's cross-field check for this
+ * strategy (exactly one of `bundleUrl`/`entryHtml`); `entryHtml`-only
+ * iframe-reachable worlds still have no builder here (mirrors the
+ * `resolveIngestDescriptor`/three-side gap: reading a raw HTML/inline-source
+ * file's contents needs a runtime fetch this synchronous builder doesn't do).
+ * `extraDeps`/`pixiModuleUrl` become LAZY thunks (`IngestGame2D.extraDeps`/
+ * `.pixiNamespace`) closing over the host-namespace registry / a dynamic
+ * `import()` — never resolved just to build this descriptor.
+ */
+export function buildIframeReachableGame2D(
+  folderId: string,
+  adapter: {
+    bundleUrl: string | undefined;
+    baseHref: string | undefined;
+    assetBaseUrl: string | undefined;
+    extraDeps: string[] | undefined;
+    pixiModuleUrl: string | undefined;
+    bodyHtml: string | undefined;
+  },
+  base: BaseFields2D,
+): IngestGame2D {
+  if (!adapter.bundleUrl) {
+    throw new Error(
+      `world2d ingest discovery: "${folderId}" (strategy "iframe-reachable") has no \`bundleUrl\` ` +
+        '— only the externalized-bundle route is buildable here (an `entryHtml`-only iframe-' +
+        "reachable world needs a runtime file fetch this synchronous glob discovery doesn't do).",
+    );
+  }
+  const { bundleUrl, baseHref, assetBaseUrl, extraDeps, pixiModuleUrl, bodyHtml } = adapter;
+  return {
+    ...base,
+    tier: 'iframe-reachable',
+    bundleUrl,
+    ...(baseHref !== undefined ? { baseHref } : {}),
+    ...(assetBaseUrl !== undefined ? { assetBaseUrl } : {}),
+    ...(extraDeps !== undefined ? { extraDeps: () => resolveExtraDeps(extraDeps) } : {}),
+    ...(pixiModuleUrl !== undefined
+      ? { pixiNamespace: () => import(/* @vite-ignore */ pixiModuleUrl) }
+      : {}),
+    ...(bodyHtml !== undefined ? { bodyHtml } : {}),
+  };
+}
+
+function buildIngestGame2D(folderId: string, raw: unknown): IngestGame2D {
+  const manifest = loadGameManifest(raw);
+  if (manifest.worlds.length !== 1) {
+    throw new Error(
+      `world2d ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
+        `(found ${manifest.worlds.length}).`,
+    );
+  }
+  const world = manifest.worlds[0]!;
+  if (world.adapter.type !== 'ingest' || world.adapter.identity !== 'ingest-pixi') {
+    throw new Error(
+      `world2d ingest discovery: "${folderId}/vgai.game.json"'s world must be a pixijs ` +
+        `{ ingest } world (found adapter identity "${world.adapter.identity}").`,
+    );
+  }
+  const { adapter } = world;
+
+  const base: BaseFields2D = {
+    id: world.id,
+    name: manifest.name,
+    description: world.description ?? '',
+    ...(adapter.captureTimeoutMs !== undefined
+      ? { captureTimeoutMs: adapter.captureTimeoutMs }
+      : {}),
+  };
+
+  switch (adapter.strategy) {
+    case 'shared':
+    case 'deduped':
+      return buildModuleLoadedGame2D(folderId, world, adapter.strategy, base);
+    case 'iframe-reachable':
+      return buildIframeReachableGame2D(folderId, adapter, base);
+    case 'opaque-embed':
+      // D-W2 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) wired `IngestGame2D.embedHtml`
+      // for the manifest-driven external-folder route (`resolveIngest2DDescriptor`,
+      // reading `entryHtml`'s bytes through the project-static route as a lazy
+      // thunk) — but no in-tree world2d fixture uses opaque-embed, and this
+      // SYNCHRONOUS glob-discovery route has no runtime fetch to build that
+      // thunk from (mirrors the three side's identical `entryHtml`-only gap,
+      // `discovery.ts`'s own file-glob route DOES have one via `?raw`, since
+      // Vite already knows these files statically — porting that mechanism
+      // here is unclaimed, not attempted, since nothing needs it yet).
+      throw new Error(
+        `world2d ingest discovery: "${folderId}" declares strategy "${adapter.strategy}" — not ` +
+          'buildable from this synchronous glob-discovery route (no in-tree world2d opaque-embed ' +
+          'fixture exists yet; see resolveIngest2DDescriptor for the manifest-driven route).',
+      );
+    default: {
+      // Exhaustive per IngestStrategySchema's 4 members.
+      const exhaustive: never = adapter.strategy;
+      throw new Error(
+        `world2d ingest discovery: "${folderId}" has an unhandled ingest strategy ${JSON.stringify(exhaustive)}.`,
+      );
+    }
+  }
+}
+
+let _cache: IngestGame2D[] | null = null;
+
+/** Every in-tree world2d ingest fixture game, discovered from `./games-2d/*\/vgai.game.json`. */
+export function discoverIngestGames2D(): IngestGame2D[] {
+  if (!_cache) {
+    _cache = Object.entries(manifestModules)
+      .map(([key, raw]) => buildIngestGame2D(folderIdFromManifestKey(key), raw))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  }
+  return _cache;
+}
+
+/** Look up one discovered world2d ingest game by id. */
+export function getIngestGame2D(id: string): IngestGame2D | undefined {
+  return discoverIngestGames2D().find((g) => g.id === id);
+}

package/src/ingest/esm-entry-resolution.ts

@@ -0,0 +1,102 @@
+/**
+ * ESM-entry resolution from a parsed `package.json` — the ONE pure-logic
+ * home for the minimal `exports`/`module`-field subset D-Z3
+ * (docs/EXTERNAL-FOLDER-INGEST-DESIGN.md's wave-3 addendum) and D-Z4
+ * (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md §1) both need.
+ *
+ * Two callers share this logic on purpose, per D-Z4's own design note ("put
+ * shared pure logic in one place if feasible rather than duplicating"):
+ *   - `host-namespace-registry.ts`'s `probeProjectNodeModules` — editor-side,
+ *     FETCHES a project's `node_modules/<spec>/package.json` through the
+ *     `/project-game-static` dev-server route (browser-realm, no `node:fs`).
+ *   - `packages/editor/scripts/run-bundle.ts`'s extraDeps pre-build
+ *     validation — a plain Node CLI script, READS the same file straight off
+ *     disk via `node:fs`.
+ * Both need byte-identical SEMANTICS (same exports-subset, same "found"
+ * dump for the CJS-only case) even though the I/O differs — this module is
+ * the fs-free, fetch-free core both wrap.
+ */
+
+/** The one exports-map shape this fallback honors: a "." entry (string, or an
+ *  { import | module | default } conditions object — the real shapes
+ *  `@pixi/sound` and `gsap` ship, D-Z3's reference packages). Reads a single
+ *  string condition off `conditions`, preferring `import`, then `module`,
+ *  then `default` — the order D-Z3 specifies. */
+function esmEntryFromConditions(conditions: Record<string, unknown>): string | null {
+  for (const key of ['import', 'module', 'default']) {
+    const v = conditions[key];
+    if (typeof v === 'string') return v;
+  }
+  return null;
+}
+
+/**
+ * Resolve the ESM entry PATH (package-folder-relative, e.g. "./lib/index.mjs")
+ * from a parsed `package.json`'s `exports` field, honoring the minimal subset
+ * this fallback supports (see module doc comment). Returns `null` (never
+ * throws) when the shape doesn't fit this subset or no ESM entry is declared
+ * at all — the CALLER decides how to report that (trap: exports-map parsing
+ * is a rabbit hole, so this stays an honest minimal subset, not a full
+ * resolver).
+ */
+function esmEntryFromExportsField(exportsField: unknown): string | null {
+  if (typeof exportsField === 'string') return exportsField;
+  if (!exportsField || typeof exportsField !== 'object' || Array.isArray(exportsField)) {
+    return null;
+  }
+  const exportsObj = exportsField as Record<string, unknown>;
+  const dot = exportsObj['.'];
+  if (typeof dot === 'string') return dot;
+  if (dot && typeof dot === 'object' && !Array.isArray(dot)) {
+    return esmEntryFromConditions(dot as Record<string, unknown>);
+  }
+  if (dot === undefined) {
+    // No "." subpath key at all — a package with a SINGLE entry point may
+    // declare `exports` as a bare conditions map with no subpaths (no key
+    // starts with '.'). Anything else (real subpaths like "./foo") is
+    // outside this minimal subset — leave it to the caller's "found" dump.
+    const hasSubpathKeys = Object.keys(exportsObj).some((k) => k.startsWith('.'));
+    if (!hasSubpathKeys) return esmEntryFromConditions(exportsObj);
+  }
+  return null;
+}
+
+/**
+ * Resolve the ESM entry PATH from a parsed `package.json`: `exports["."]`
+ * (string or conditions object) first, then the top-level `module` field.
+ * `null` when neither is present/parseable (CJS-only or an unrecognized
+ * shape) — never throws.
+ */
+export function resolveEsmEntryPath(pkg: Record<string, unknown>): string | null {
+  const fromExports = esmEntryFromExportsField(pkg['exports']);
+  if (fromExports) return fromExports;
+
+  const moduleField = pkg['module'];
+  if (typeof moduleField === 'string') return moduleField;
+
+  return null;
+}
+
+/** Outcome of probing one parsed `package.json` for a usable ESM entry. */
+export type EsmEntryProbeResult =
+  | { readonly kind: 'cjs-only'; readonly found: Record<string, unknown> }
+  | { readonly kind: 'esm-entry'; readonly entryPath: string };
+
+/**
+ * Probe an already-parsed `package.json` for a usable ESM entry, per the
+ * minimal subset this module supports. Package-folder-relative `entryPath`
+ * has any leading `./` stripped (callers join it onto their own base path/URL
+ * however they need). `found` on the CJS-only branch is the same
+ * introspection dump both callers surface in their distinct named error
+ * ("installed but CJS-only").
+ */
+export function probePackageJsonForEsmEntry(pkg: Record<string, unknown>): EsmEntryProbeResult {
+  const esmEntryPath = resolveEsmEntryPath(pkg);
+  if (!esmEntryPath) {
+    return {
+      kind: 'cjs-only',
+      found: { main: pkg['main'], module: pkg['module'], exports: pkg['exports'] },
+    };
+  }
+  return { kind: 'esm-entry', entryPath: esmEntryPath.replace(/^\.\//, '') };
+}