@vgai/engine 0.2.0

package/src/world2d/ingest-iframe-2d.ts

@@ -0,0 +1,255 @@
+/**
+ * world2d iframe ingest tiers — the PixiJS analogs of the 3D ingest-iframe adapters.
+ *
+ *  - OPAQUE EMBED (tier 0-1): a prebuilt/self-contained bundle runs in a sandboxed
+ *    iframe; hosted + sized + disposed, NOT introspectable.
+ *  - IFRAME-REACHABLE (tier 2-3): a bundle runs in its own iframe realm, but its
+ *    `import 'pixi.js'` is wired (via an importmap) to a blob module re-exporting the
+ *    HOST's pixi instance, so every Application/Sprite it creates is a HOST-realm
+ *    object → the host `Application.prototype.render` trap fires and capture works.
+ */
+import {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture-2d';
+
+export interface EmbedMount2D {
+  iframe: HTMLIFrameElement;
+  dispose: () => void;
+}
+
+/** OPAQUE EMBED: sandboxed iframe, no scene introspection (tier 0-1). */
+export function mountIngestGame2DEmbed(html: string, container: HTMLElement): EmbedMount2D {
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('sandbox', 'allow-scripts');
+  iframe.style.border = '0';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  iframe.srcdoc = html;
+  container.appendChild(iframe);
+  return { iframe, dispose: () => iframe.remove() };
+}
+
+const HOST_PIXI_KEY = '__vgaiHostPixi';
+
+/** Build a blob module that re-exports the host's pixi namespace (for the importmap). */
+function makeHostPixiReexportUrl(pixiNamespace: Record<string, unknown>): string {
+  (window as unknown as Record<string, unknown>)[HOST_PIXI_KEY] = pixiNamespace;
+  const ident = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  const keys = Object.keys(pixiNamespace).filter((k) => k !== 'default' && ident.test(k));
+  const body =
+    `const T = window.parent[${JSON.stringify(HOST_PIXI_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 _reexportKeySeq = 0;
+
+/**
+ * Generalized host-namespace re-export (the multi-dep analog of {@link makeHostPixiReexportUrl}).
+ * Stashes `ns` (an ES module namespace object, e.g. `import * as ns from 'gsap'`) on a unique
+ * window key and builds a blob module re-exporting it, so the iframe's importmap can map a bare
+ * specifier (pixi.js, @pixi/sound, @pixi/ui, gsap, …) to the HOST's single instance. Default-export
+ * handling: `export default T.default ?? T` so `import gsap from 'gsap'` gets gsap, while a
+ * default-less namespace (pixi.js) re-exports the namespace itself for `import * as`.
+ */
+function makeHostNamespaceReexportUrl(ns: Record<string, unknown>): string {
+  const key = `__vgaiHostNs_${_reexportKeySeq++}`;
+  (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' }));
+}
+
+export interface IframeReachableMultiOpts {
+  captureTimeoutMs?: number;
+  /**
+   * Bare-specifier → host module-namespace map. MUST include the pixi.js instance the trap is
+   * installed on (passed separately as `pixiNamespace`); list the game's OTHER shared bare deps
+   * here (@pixi/sound, @pixi/ui, gsap, pixi-filters) so they resolve to host instances and their
+   * extension side-effects register on the host pixi (the trapped instance).
+   */
+  extraDeps?: Record<string, Record<string, unknown>>;
+  /**
+   * D-Z3 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — bare-specifier -> VERBATIM
+   * URL importmap entries (the project-node_modules fallback for a specifier
+   * that isn't in the host-namespace registry but IS installed in the open
+   * project's own `node_modules`). Written into the importmap DIRECTLY
+   * alongside the `extraDeps` blob-namespace entries — no host-side import,
+   * no blob wrapping, no decision logic here: this function just merges
+   * whatever `Record<specifier, url>` the caller (editor-side
+   * `host-namespace-registry.ts`) already decided. The URL's own transitive
+   * `import 'pixi.js'` resolves through this SAME importmap back to the host
+   * pixi trap (§0.3), keeping module identity converged without a second pixi
+   * instance.
+   */
+  extraDepUrls?: Record<string, string>;
+  /** <base href> for the iframe so the game's relative asset URLs (Assets basePath) resolve. */
+  baseHref?: string;
+  /**
+   * HOST-SIDE asset URL remap (the Pixi analog of the three.js DefaultLoadingManager.setURLModifier
+   * asset adapter). A document.write iframe keeps the PARENT's window.location, so PixiJS's Assets
+   * resolver (which builds absolute URLs from window.location, not document.baseURI) would resolve
+   * the game's relative `basePath:'assets'` against the parent page. Wrapping the host pixi's
+   * Assets.init to force this ABSOLUTE basePath fixes resolution without touching the game source —
+   * pure host library configuration, restored on dispose.
+   */
+  assetBaseUrl?: string;
+  /** Load the game bundle from this absolute URL (a built multi-file game). */
+  bundleUrl?: string;
+  /** …or run this inline module source (a single-file game). One of bundleUrl/inlineSrc required. */
+  inlineSrc?: string;
+  /** DOM the game expects to find before it boots (e.g. a `<div id="game-root">` it appends to). */
+  bodyHtml?: string;
+}
+
+/**
+ * IFRAME-REACHABLE for REAL MULTI-FILE GAMES (cov2d-bundled-dedupe): run a built game bundle
+ * (its OWN unaltered source, externalized against pixi at build time) in its own iframe realm
+ * whose importmap maps EVERY shared bare dep — pixi.js + @pixi/sound/@pixi/ui/gsap/… — to the
+ * HOST instances, and (optionally) a <base href> so its AssetPack/manifest URLs resolve. The
+ * host `Application.prototype.render` trap then captures the live stage IN-REALM. The game's
+ * source is never touched; all of this is host-side wiring.
+ */
+export async function mountIngestGame2DIframeReachableMulti(
+  pixiNamespace: unknown,
+  container: HTMLElement,
+  opts: IframeReachableMultiOpts,
+): Promise<IframeReachableMount2D> {
+  const capture = installSceneCapture2D(pixiNamespace);
+  const created: string[] = [];
+  const mkUrl = (ns: Record<string, unknown>): string => {
+    const u = makeHostNamespaceReexportUrl(ns);
+    created.push(u);
+    return u;
+  };
+
+  const imports: Record<string, string> = {
+    'pixi.js': mkUrl(pixiNamespace as Record<string, unknown>),
+  };
+  for (const [spec, ns] of Object.entries(opts.extraDeps ?? {})) imports[spec] = mkUrl(ns);
+  // D-Z3 fallback: verbatim URL entries, no blob wrapping, merged in beside
+  // the host-namespace ones — decision-free (see `extraDepUrls`'s doc comment).
+  for (const [spec, url] of Object.entries(opts.extraDepUrls ?? {})) imports[spec] = url;
+
+  // Host-side asset URL remap (asset adapter): force the game's Assets.init basePath to an
+  // absolute URL so its assets resolve to the served bundle dir, not the parent page path.
+  let restoreInit: (() => void) | undefined;
+  if (opts.assetBaseUrl) {
+    const assetsApi = (
+      pixiNamespace as { Assets?: { init?: (o?: Record<string, unknown>) => unknown } }
+    ).Assets;
+    if (assetsApi?.init) {
+      const orig = assetsApi.init.bind(assetsApi);
+      assetsApi.init = (o: Record<string, unknown> = {}) =>
+        orig({ ...o, basePath: opts.assetBaseUrl });
+      restoreInit = () => {
+        assetsApi.init = orig;
+      };
+    }
+  }
+
+  const iframe = document.createElement('iframe');
+  iframe.style.border = '0';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  container.appendChild(iframe);
+
+  // Split the closing script token so this module's own bundling never sees a literal
+  // </script> (defensive; matches the single-dep mount's convention).
+  const close = `</${'scr'}ipt>`;
+  const baseTag = opts.baseHref ? `<base href="${opts.baseHref}">` : '';
+  const scriptTag = opts.bundleUrl
+    ? `<script type="module" src="${opts.bundleUrl}">${close}`
+    : `<script type="module">${opts.inlineSrc ?? ''}${close}`;
+  const importmapTag = `<script type="importmap">${JSON.stringify({ imports })}${close}`;
+  const bodyHtml = opts.bodyHtml ?? '';
+
+  const doc = iframe.contentDocument!;
+  doc.open();
+  doc.write(
+    `<!doctype html><html><head><meta charset="utf-8">${baseTag}${importmapTag}</head><body>${bodyHtml}${scriptTag}</body></html>`,
+  );
+  doc.close();
+
+  let captured: CapturedRuntime2D | null = null;
+  try {
+    captured = await capture.waitForCapture(opts.captureTimeoutMs ?? 12_000);
+  } catch {
+    captured = null;
+  }
+
+  return {
+    iframe,
+    capture,
+    captured,
+    dispose: () => {
+      capture.uninstall();
+      restoreInit?.();
+      for (const u of created) URL.revokeObjectURL(u);
+      iframe.remove();
+    },
+  };
+}
+
+export interface IframeReachableMount2D {
+  iframe: HTMLIFrameElement;
+  capture: SceneCapture2DHandle;
+  captured: CapturedRuntime2D | null;
+  dispose: () => void;
+}
+
+/**
+ * IFRAME-REACHABLE (tier 2-3): run `gameModuleSrc` in an iframe whose importmap maps
+ * `pixi.js` to a host-pixi re-export blob, and trap the host `Application.prototype`
+ * so the bundle's render is captured in-realm.
+ */
+export async function mountIngestGame2DIframeReachable(
+  pixiNamespace: unknown,
+  gameModuleSrc: string,
+  container: HTMLElement,
+  opts: { captureTimeoutMs?: number } = {},
+): Promise<IframeReachableMount2D> {
+  const capture = installSceneCapture2D(pixiNamespace);
+  const reexportUrl = makeHostPixiReexportUrl(pixiNamespace as Record<string, unknown>);
+
+  const iframe = document.createElement('iframe');
+  iframe.style.border = '0';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  container.appendChild(iframe);
+
+  const doc = iframe.contentDocument!;
+  doc.open();
+  doc.write(
+    `<!doctype html><html><head><meta charset="utf-8">` +
+      `<script type="importmap">${JSON.stringify({ imports: { 'pixi.js': reexportUrl } })}</scr` +
+      `ipt></head><body><script type="module">${gameModuleSrc}</scr` +
+      `ipt></body></html>`,
+  );
+  doc.close();
+
+  let captured: CapturedRuntime2D | null = null;
+  try {
+    captured = await capture.waitForCapture(opts.captureTimeoutMs ?? 8000);
+  } catch {
+    captured = null;
+  }
+
+  return {
+    iframe,
+    capture,
+    captured,
+    dispose: () => {
+      capture.uninstall();
+      URL.revokeObjectURL(reexportUrl);
+      iframe.remove();
+    },
+  };
+}

package/src/world2d/ingest2d.ts

@@ -0,0 +1,131 @@
+import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture-2d';
+
+/**
+ * D-Z3 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — a manifest's `extraDeps`
+ * resolve to TWO kinds of importmap entry: `namespaces` are today's
+ * registry-known bare specifiers (host-namespace-registry.ts), re-exported
+ * via a blob module (`ingest-iframe-2d.ts`'s `makeHostNamespaceReexportUrl`);
+ * `urls` are the D-Z3 fallback — a specifier that isn't registered but IS
+ * present in the open project's own `node_modules`, mapped DIRECTLY to its
+ * `/project-game-static/node_modules/<spec>/<esm entry>` URL (no host-side
+ * import, no blob — the dep executes in the iframe realm and its own
+ * transitive `import 'pixi.js'` resolves through the same importmap back to
+ * the host pixi trap). All probing/decision logic (which kind a specifier
+ * resolves to, exports-map parsing, anti-shim throws) lives editor-side
+ * (`host-namespace-registry.ts`) — this engine module only carries the
+ * ALREADY-DECIDED shape; `ingest-iframe-2d.ts` stays decision-free and just
+ * merges both maps into the iframe importmap.
+ */
+export interface ExtraDepsResolution2D {
+  namespaces: Record<string, Record<string, unknown>>;
+  urls: Record<string, string>;
+}
+
+/** A registered unmodified PixiJS game (the world2d analog of `IngestGame`). */
+export interface IngestGame2D {
+  id: string;
+  name: string;
+  description: string;
+  /** Shared-pixi path: import + run the unmodified game module. */
+  load?: () => Promise<unknown>;
+  /** Tier ceiling: how reachable the game's pixi instance is. */
+  tier?: 'shared' | 'iframe-reachable' | 'opaque-embed';
+  captureTimeoutMs?: number;
+  /**
+   * IFRAME-REACHABLE-MULTI fields (Track P, docs/PIXI-INGEST-LANDING-DESIGN.md
+   * §2): an externalized built bundle mounted via
+   * `mountIngestGame2DIframeReachableMulti` (`./ingest-iframe-2d.ts`) instead
+   * of `load()` — populated only when `tier` is `'iframe-reachable'` AND
+   * `load` is absent. Mirror `IframeReachableMultiOpts`'s fields, EXCEPT
+   * `extraDeps`/`pixiNamespace` are THUNKS here, not resolved values — the
+   * same "lazy, only invoked at mount time" shape `load` already uses, so
+   * building this descriptor (`resolveIngest2DDescriptor` / `discovery2d.ts`,
+   * editor-side) never has to be async just to wire up which specifiers/
+   * version-skew URL a game needs; only actually MOUNTING it (the ingest-mode
+   * mount bridge) pays for the dynamic import of `@pixi/sound`/`gsap`/spine/
+   * a standalone pixi build.
+   */
+  bundleUrl?: string;
+  /** <base href> for the iframe (see `IframeReachableMultiOpts.baseHref`). */
+  baseHref?: string;
+  /** Host-side Assets.init basePath remap (see `IframeReachableMultiOpts.assetBaseUrl`). */
+  assetBaseUrl?: string;
+  /**
+   * Lazily resolve this game's bare-specifier -> extraDeps resolution via the
+   * editor's host-namespace registry. Absent (or omitted) means no extra deps
+   * beyond pixi.js.
+   */
+  extraDeps?: () => Promise<ExtraDepsResolution2D>;
+  /**
+   * Lazily resolve the trapped-pixi namespace for version-skewed games (a
+   * dynamic `import()` of the manifest's `pixiModuleUrl`) — absent means
+   * "mount against the host's own `pixi.js`" (no skew).
+   */
+  pixiNamespace?: () => Promise<unknown>;
+  /** DOM the game expects before boot (see `IframeReachableMultiOpts.bodyHtml`). */
+  bodyHtml?: string;
+  /**
+   * Lazily read an OPAQUE prebuilt bundle's self-contained HTML (D-W2,
+   * docs/WAVE4-FTUE-HARDENING-DESIGN.md) — the pixi twin of `IngestGame.embedHtml`.
+   * Always a lazy thunk here (no in-tree world2d opaque-embed fixture exists
+   * yet to need a plain-string form, unlike the three side):
+   * `resolveIngest2DDescriptor` (adapter-resolver.ts) builds one that reads
+   * the declared `entryHtml` file's bytes through the `/project-game-static/`
+   * route, only when the game is actually mounted. The host runs the
+   * resolved HTML in a sandboxed iframe at the embed-only floor (Tier 0-1),
+   * `mountIngestGame2DEmbed` (`./ingest-iframe-2d.ts`).
+   */
+  embedHtml?: () => Promise<string>;
+}
+
+export interface IngestMount2D {
+  /** The captured live stage Container (null if capture failed/degraded). */
+  stage: unknown | null;
+  capture: SceneCapture2DHandle;
+  embedOnly: boolean;
+  setPaused(paused: boolean): void;
+  dispose(): void;
+}
+
+/**
+ * Mount an UNMODIFIED PixiJS game via the shared-instance capture path — the 2D
+ * analog of `mountIngestGame`. Installs the render trap on the host's pixi
+ * instance, runs the game's `load()`, waits for the game to render its first
+ * frame (capturing its live stage), and exposes loop gating + cleanup. If capture
+ * times out (pixi unreachable / bundled / mismatched), degrades to embed-only —
+ * never a silent failure.
+ */
+export async function mountIngestGame2D(
+  pixiNamespace: unknown,
+  game: IngestGame2D,
+  opts: { captureTimeoutMs?: number } = {},
+): Promise<IngestMount2D> {
+  const capture = installSceneCapture2D(pixiNamespace);
+  try {
+    await game.load?.();
+  } catch (err) {
+    capture.uninstall();
+    throw new Error(`world2d ingest: game "${game.id}" failed to load: ${err}`);
+  }
+
+  const timeout = opts.captureTimeoutMs ?? game.captureTimeoutMs ?? 8000;
+  try {
+    const rt = await capture.waitForCapture(timeout);
+    return {
+      stage: rt.stage,
+      capture,
+      embedOnly: false,
+      setPaused: (p) => capture.setPaused(p),
+      dispose: () => capture.uninstall(),
+    };
+  } catch {
+    // Capture failed → pixi unreachable/mismatched → degrade to embed-only.
+    return {
+      stage: null,
+      capture,
+      embedOnly: true,
+      setPaused: () => {},
+      dispose: () => capture.uninstall(),
+    };
+  }
+}

package/src/world2d/physics2d-registry.ts

@@ -0,0 +1,49 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import type { Container } from 'pixi.js';
+
+/** The Rapier 2D handles owned by a single display-object entity. */
+export interface Physics2DRefs {
+  body: RAPIER.RigidBody;
+  collider: RAPIER.Collider;
+}
+
+/**
+ * Maps PixiJS display objects to their Rapier 2D bodies/colliders and back —
+ * the world2d analog of `PhysicsRegistry`. Two indexes:
+ *  - `Container → {body, collider}` for the postPhysics transform writer.
+ *  - `colliderHandle → Container` reverse index for collision/trigger dispatch.
+ */
+export function createPhysics2DRegistry() {
+  const byObject = new Map<Container, Physics2DRefs>();
+  const byColliderHandle = new Map<number, Container>();
+
+  return {
+    add(display: Container, body: RAPIER.RigidBody, collider: RAPIER.Collider): void {
+      byObject.set(display, { body, collider });
+      byColliderHandle.set(collider.handle, display);
+    },
+    get(display: Container): Physics2DRefs | undefined {
+      return byObject.get(display);
+    },
+    getByColliderHandle(handle: number): Container | undefined {
+      return byColliderHandle.get(handle);
+    },
+    remove(display: Container): void {
+      const refs = byObject.get(display);
+      if (refs) byColliderHandle.delete(refs.collider.handle);
+      byObject.delete(display);
+    },
+    entries(): IterableIterator<[Container, Physics2DRefs]> {
+      return byObject.entries();
+    },
+    get size(): number {
+      return byObject.size;
+    },
+    clear(): void {
+      byObject.clear();
+      byColliderHandle.clear();
+    },
+  };
+}
+
+export type Physics2DRegistry = ReturnType<typeof createPhysics2DRegistry>;