@vgai/engine 0.5.4 → 0.5.6

package/dist/pixi/authoring.js

@@ -0,0 +1,207 @@
+function kindOf(o) {
+    const ctor = o.constructor?.name?.toLowerCase() ?? 'container';
+    if (ctor.includes('animatedsprite'))
+        return 'animatedsprite';
+    if (ctor.includes('sprite'))
+        return 'sprite';
+    if (ctor.includes('text'))
+        return 'text';
+    return 'container';
+}
+export class AuthoringAdapter2D {
+    root;
+    byId = new Map();
+    overlay = {};
+    dirty = false;
+    constructor(root, opts = {}) {
+        this.root = root;
+        if (opts.overlay)
+            this.overlay = opts.overlay;
+        this.refresh();
+    }
+    /**
+     * Walk the live tree assigning deterministic structural-path ids.
+     *
+     * Separate from {@link refresh} because the two are wanted at different rates: the ids have to be
+     * current whenever the tree is READ (a world that mounts its content asynchronously — a
+     * translated port waiting on its resources, anything behind Suspense — commits real nodes after
+     * the adapter was handed its root, and an unindexed node is one the hierarchy cannot name), while
+     * re-applying the edit overlay is a WRITE and must happen only when something asked for it.
+     */
+    reindex() {
+        this.byId.clear();
+        let count = 0;
+        let sprites = 0;
+        const visit = (o, path) => {
+            const id = `w2d:${path}:${kindOf(o)}:${o.label ?? ''}`;
+            o.__authId = id;
+            this.byId.set(id, o);
+            count++;
+            if (kindOf(o).includes('sprite'))
+                sprites++;
+            o.children.forEach((c, i) => {
+                visit(c, `${path}/${i}`);
+            });
+        };
+        this.root.children.forEach((c, i) => {
+            visit(c, `${i}`);
+        });
+        return { count, sprites };
+    }
+    /** {@link reindex}, then reapply every saved overlay edit to the live tree. */
+    refresh() {
+        const counts = this.reindex();
+        for (const [id, ov] of Object.entries(this.overlay))
+            this.applyOverride(id, ov);
+        return counts;
+    }
+    roots() {
+        return this.root.children.map((c) => this.toNode(c));
+    }
+    node(id) {
+        const o = this.byId.get(id);
+        return o ? this.toNode(o) : null;
+    }
+    displayObject(id) {
+        return this.byId.get(id) ?? null;
+    }
+    toNode(o) {
+        const self = o;
+        return {
+            id: self.__authId ?? '',
+            label: o.label ?? kindOf(o),
+            kind: kindOf(o),
+            parentId: o.parent?.__authId ?? null,
+            childIds: o.children.map((c) => c.__authId ?? ''),
+        };
+    }
+    // --- Transforms ---
+    getTransform(id) {
+        const o = this.byId.get(id);
+        // A tracked node isn't guaranteed to be a real PixiJS display object with
+        // a transform (e.g. test doubles / non-positional fixture nodes walked
+        // via the composite adapter's overlay path) — treat a missing position
+        // the same as a missing node: no transform to report, not a crash.
+        if (!o || !o.position || !o.scale)
+            return null;
+        return {
+            position: [o.position.x, o.position.y],
+            rotation: o.rotation,
+            scale: [o.scale.x, o.scale.y],
+        };
+    }
+    setTransform(id, t) {
+        const o = this.byId.get(id);
+        if (!o)
+            return;
+        if (t.position)
+            o.position.set(t.position[0], t.position[1]);
+        if (t.rotation !== undefined)
+            o.rotation = t.rotation;
+        if (t.scale)
+            o.scale.set(t.scale[0], t.scale[1]);
+        this.overlay[id] ??= {};
+        const ov = this.overlay[id];
+        if (t.position)
+            ov.position = t.position;
+        if (t.rotation !== undefined)
+            ov.rotation = t.rotation;
+        if (t.scale)
+            ov.scale = t.scale;
+        this.dirty = true;
+    }
+    // --- Inspector (reflected fields) ---
+    properties(id) {
+        const o = this.byId.get(id);
+        if (!o)
+            return [];
+        const props = [
+            { path: 'label', label: 'Name', type: 'string', value: o.label ?? '' },
+            { path: 'visible', label: 'Visible', type: 'boolean', value: o.visible },
+            { path: 'alpha', label: 'Alpha', type: 'number', value: o.alpha },
+        ];
+        if ('tint' in o)
+            props.push({
+                path: 'tint',
+                label: 'Tint',
+                type: 'color',
+                value: o.tint,
+            });
+        return props;
+    }
+    set(id, path, value) {
+        const o = this.byId.get(id);
+        if (!o)
+            return;
+        o[path] = value;
+        this.overlay[id] ??= {};
+        if (path === 'label')
+            this.overlay[id].label = value;
+        if (path === 'alpha')
+            this.overlay[id].alpha = value;
+        if (path === 'tint')
+            this.overlay[id].tint = value;
+        if (path === 'visible')
+            this.overlay[id].visible = value;
+        this.dirty = true;
+    }
+    applyOverride(id, ov) {
+        const o = this.byId.get(id);
+        if (!o)
+            return;
+        if (ov.label !== undefined)
+            o.label = ov.label;
+        if (ov.alpha !== undefined)
+            o.alpha = ov.alpha;
+        if (ov.position)
+            o.position.set(ov.position[0], ov.position[1]);
+        if (ov.rotation !== undefined)
+            o.rotation = ov.rotation;
+        if (ov.scale)
+            o.scale.set(ov.scale[0], ov.scale[1]);
+        if (ov.tint !== undefined && 'tint' in o)
+            o.tint = ov.tint;
+        if (ov.visible !== undefined)
+            o.visible = ov.visible;
+    }
+    /**
+     * Re-apply a saved/external overlay onto the (already-walked) live tree, merging
+     * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
+     * and a later `refresh()` re-applies it again. Ids absent from the current tree
+     * are skipped (orphaned, not an error) — the 2D analog of
+     * `LiveThreeAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+     * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
+     * (re-apply a changed overlay file without a full remount).
+     */
+    applyOverlay(overlay) {
+        let applied = 0;
+        let orphaned = 0;
+        for (const [id, ov] of Object.entries(overlay)) {
+            if (!this.byId.has(id)) {
+                orphaned++;
+                continue;
+            }
+            this.applyOverride(id, ov);
+            this.overlay[id] = { ...this.overlay[id], ...ov };
+            applied++;
+        }
+        return { applied, orphaned };
+    }
+    isDirty() {
+        return this.dirty;
+    }
+    serializeOverlay() {
+        return this.overlay;
+    }
+    /** Replace, rather than merge, overlay state after an exact history restore. */
+    replaceOverlay(overlay) {
+        this.overlay = structuredClone(overlay);
+        for (const [id, ov] of Object.entries(this.overlay))
+            this.applyOverride(id, ov);
+        this.dirty = true;
+    }
+    /** Clear the dirty flag after a successful save (mirrors LiveThreeAuthoringAdapter). */
+    markClean() {
+        this.dirty = false;
+    }
+}

package/dist/pixi/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * pixi — the PixiJS surface substrate.
+ *
+ * PixiJS is opt-in: the engine core never imports it, so a three-only bundle
+ * never pays for it. What lives here is what the host needs to mount and
+ * inspect a PixiJS game it did not write — the render-call capture trap, the
+ * in-realm and iframe mounts, the live display-tree authoring adapter, and the
+ * Rapier-2D handle registry the editor's transform coordination reads.
+ */
+export { AuthoringAdapter2D, type EditorNode2D, type Overlay2D, type Override2D, type Property2D, type Transform2DValue, } from './authoring';
+export { type ExtraDepsResolution2D, type IngestGame2D, type IngestMount2D, mountIngestGame2D, } from './ingest';
+export { type EmbedMount2D, type IframeReachableMount2D, type IframeReachableMultiOpts, mountIngestGame2DEmbed, mountIngestGame2DIframeReachable, mountIngestGame2DIframeReachableMulti, } from './ingest-iframe';
+export { createPhysics2DRegistry, type Physics2DRefs, type Physics2DRegistry, } from './physics-registry';
+export { type CapturedRuntime2D, installSceneCapture2D, type SceneCapture2DHandle, } from './scene-capture';
+export { createPhysicsAdapter2D, type PhysicsAdapter2D } from './system-adapters';
+//# sourceMappingURL=index.d.ts.map

package/dist/pixi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pixi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,sBAAsB,EACtB,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/pixi/index.js

@@ -0,0 +1,15 @@
+/**
+ * pixi — the PixiJS surface substrate.
+ *
+ * PixiJS is opt-in: the engine core never imports it, so a three-only bundle
+ * never pays for it. What lives here is what the host needs to mount and
+ * inspect a PixiJS game it did not write — the render-call capture trap, the
+ * in-realm and iframe mounts, the live display-tree authoring adapter, and the
+ * Rapier-2D handle registry the editor's transform coordination reads.
+ */
+export { AuthoringAdapter2D, } from './authoring';
+export { mountIngestGame2D, } from './ingest';
+export { mountIngestGame2DEmbed, mountIngestGame2DIframeReachable, mountIngestGame2DIframeReachableMulti, } from './ingest-iframe';
+export { createPhysics2DRegistry, } from './physics-registry';
+export { installSceneCapture2D, } from './scene-capture';
+export { createPhysicsAdapter2D } from './system-adapters';

package/dist/pixi/ingest-iframe.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pixi 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, type SceneCapture2DHandle } from './scene-capture';
+export interface EmbedMount2D {
+    iframe: HTMLIFrameElement;
+    dispose: () => void;
+}
+/** OPAQUE EMBED: sandboxed iframe, no scene introspection (tier 0-1). */
+export declare function mountIngestGame2DEmbed(html: string, container: HTMLElement): EmbedMount2D;
+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>>;
+    /**
+     * 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 declare function mountIngestGame2DIframeReachableMulti(pixiNamespace: unknown, container: HTMLElement, opts: IframeReachableMultiOpts): Promise<IframeReachableMount2D>;
+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 declare function mountIngestGame2DIframeReachable(pixiNamespace: unknown, gameModuleSrc: string, container: HTMLElement, opts?: {
+    captureTimeoutMs?: number;
+}): Promise<IframeReachableMount2D>;
+//# sourceMappingURL=ingest-iframe.d.ts.map

package/dist/pixi/ingest-iframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-iframe.d.ts","sourceRoot":"","sources":["../../src/pixi/ingest-iframe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,GAAG,YAAY,CASzF;AAsCD,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,qCAAqC,CACzD,aAAa,EAAE,OAAO,EACtB,SAAS,EAAE,WAAW,EACtB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,sBAAsB,CAAC,CA2EjC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,WAAW,EACtB,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC,sBAAsB,CAAC,CAqCjC"}

package/dist/pixi/ingest-iframe.js

@@ -0,0 +1,166 @@
+/**
+ * Pixi 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 { installSceneCapture2D, } from './scene-capture';
+/** OPAQUE EMBED: sandboxed iframe, no scene introspection (tier 0-1). */
+export function mountIngestGame2DEmbed(html, container) {
+    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) {
+    window[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) {
+    const key = `__vgaiHostNs_${_reexportKeySeq++}`;
+    window[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' }));
+}
+/**
+ * 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, container, opts) {
+    const capture = installSceneCapture2D(pixiNamespace);
+    const created = [];
+    const mkUrl = (ns) => {
+        const u = makeHostNamespaceReexportUrl(ns);
+        created.push(u);
+        return u;
+    };
+    const imports = {
+        'pixi.js': mkUrl(pixiNamespace),
+    };
+    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;
+    if (opts.assetBaseUrl) {
+        const assetsApi = pixiNamespace.Assets;
+        if (assetsApi?.init) {
+            const orig = assetsApi.init.bind(assetsApi);
+            assetsApi.init = (o = {}) => 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 = 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();
+        },
+    };
+}
+/**
+ * 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, gameModuleSrc, container, opts = {}) {
+    const capture = installSceneCapture2D(pixiNamespace);
+    const reexportUrl = makeHostPixiReexportUrl(pixiNamespace);
+    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 = 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/dist/pixi/ingest.d.ts

@@ -0,0 +1,97 @@
+import { type SceneCapture2DHandle } from './scene-capture';
+/**
+ * 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 Pixi 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): 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` / the canvas surface's
+     * `ingest/surface-canvas.ts`, editor-side — Wave 0.6 replaced the three
+     * per-surface `discovery*.ts` modules with one manifest-driven registry) 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) — the pixi
+     * twin of `IngestGame.embedHtml`. Always a lazy thunk here (no in-tree Pixi
+     * 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 declare function mountIngestGame2D(pixiNamespace: unknown, game: IngestGame2D, opts?: {
+    captureTimeoutMs?: number;
+}): Promise<IngestMount2D>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/pixi/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/pixi/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,cAAc,CAAC;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC,aAAa,CAAC,CA6BxB"}

package/dist/pixi/ingest.js

@@ -0,0 +1,40 @@
+import { installSceneCapture2D } from './scene-capture';
+/**
+ * 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, game, opts = {}) {
+    const capture = installSceneCapture2D(pixiNamespace);
+    try {
+        await game.load?.();
+    }
+    catch (err) {
+        capture.uninstall();
+        throw new Error(`pixi 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/dist/pixi/physics-registry.d.ts

@@ -0,0 +1,24 @@
+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 Pixi analog of `PhysicsRegistry`. Two indexes:
+ *  - `Container → {body, collider}` for the postPhysics transform writer.
+ *  - `colliderHandle → Container` reverse index for collision/trigger dispatch.
+ */
+export declare function createPhysics2DRegistry(): {
+    add(display: Container, body: RAPIER.RigidBody, collider: RAPIER.Collider): void;
+    get(display: Container): Physics2DRefs | undefined;
+    getByColliderHandle(handle: number): Container | undefined;
+    remove(display: Container): void;
+    entries(): IterableIterator<[Container, Physics2DRefs]>;
+    readonly size: number;
+    clear(): void;
+};
+export type Physics2DRegistry = ReturnType<typeof createPhysics2DRegistry>;
+//# sourceMappingURL=physics-registry.d.ts.map