@vgai/engine 0.2.0 → 0.3.0

package/dist/world2d/authoring-2d.js

@@ -0,0 +1,176 @@
+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, reapply overlay. */
+    refresh() {
+        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}`);
+        });
+        // Reapply any saved overlay edits to the live tree.
+        for (const [id, ov] of Object.entries(this.overlay))
+            this.applyOverride(id, ov);
+        return { count, sprites };
+    }
+    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);
+        if (!o)
+            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 === '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.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
+     * `IngestAuthoringAdapter.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;
+    }
+    /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
+    markClean() {
+        this.dirty = false;
+    }
+}

package/dist/world2d/capture-to-scene2d.d.ts

@@ -0,0 +1,5 @@
+import type { Container } from 'pixi.js';
+import type { Scene2DFile } from './schema/entity2d';
+/** Capture selected subtree roots (by display object) into a Scene2D file. */
+export declare function captureToScene2D(roots: Container[], name?: string): Scene2DFile;
+//# sourceMappingURL=capture-to-scene2d.d.ts.map

package/dist/world2d/capture-to-scene2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-to-scene2d.d.ts","sourceRoot":"","sources":["../../src/world2d/capture-to-scene2d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0C/D,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,SAAqB,GAAG,WAAW,CAO3F"}

package/dist/world2d/capture-to-scene2d.js

@@ -0,0 +1,49 @@
+/**
+ * Capture an ingested/live PixiJS subtree into authored Scene2D entities — the
+ * world2d analog of capture-to-vscn (`ingest-capture.ts`). Recognizable sprites/
+ * text/containers map to first-party `sprite`/`text`/`transform2d` sections;
+ * turns inspection into portable authored content.
+ *
+ * Honest ceiling (mirrors the 3D one): a Scene2D `sprite` expresses tint + size +
+ * anchor, not an arbitrary texture/GraphicsContext, so a captured display keeps its
+ * transform + tint + size; bespoke Graphics geometry is captured as a plain tinted
+ * sprite placeholder.
+ */
+function numToHex(n) {
+    return `#${((n ?? 0xffffff) & 0xffffff).toString(16).padStart(6, '0')}`;
+}
+function captureNode(o) {
+    const ctor = o.constructor?.name?.toLowerCase() ?? '';
+    const entity = {
+        name: o.label ?? ctor ?? 'entity',
+        surface: 'world2d',
+        transform2d: {
+            position: [o.position.x, o.position.y],
+            rotation: o.rotation,
+            scale: [o.scale.x, o.scale.y],
+        },
+    };
+    if (ctor.includes('text')) {
+        entity.text = { text: o.text ?? '' };
+    }
+    else if (ctor.includes('sprite')) {
+        entity.sprite = {
+            tint: numToHex(o.tint),
+            width: Math.round(o.width),
+            height: Math.round(o.height),
+        };
+    }
+    const kids = o.children?.filter((c) => c.label !== undefined) ?? [];
+    if (kids.length)
+        entity.children = kids.map((c) => captureNode(c));
+    return entity;
+}
+/** Capture selected subtree roots (by display object) into a Scene2D file. */
+export function captureToScene2D(roots, name = 'captured-world2d') {
+    return {
+        version: 1,
+        name,
+        surface: 'world2d',
+        entities: roots.map(captureNode),
+    };
+}

package/dist/world2d/collision-2d.d.ts

@@ -0,0 +1,52 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import type { NodeOf } from '../ecs/game-component';
+import type { GameContext } from '../runtime/types';
+import type { Physics2DRegistry } from './physics2d-registry';
+export type Collision2DHandler = (handleA: number, handleB: number, started: boolean) => void;
+/**
+ * Drains the Rapier 2D event queue each postPhysics and dispatches collision
+ * events — the world2d analog of `createCollisionSystem`. Events are buffered then
+ * handlers run after the drain returns (same re-entrancy guard as the 3D system:
+ * a handler must not call back into Rapier while the queue is borrowed).
+ */
+export declare function createCollision2DSystem(rapierWorld: RAPIER.World, eventQueue: RAPIER.EventQueue): {
+    onCollision(handler: Collision2DHandler): void;
+    offCollision(handler: Collision2DHandler): void;
+    drain(): void;
+    getBodyHandleFromCollider(colliderHandle: number): number | undefined;
+};
+export type Collision2DSystem = ReturnType<typeof createCollision2DSystem>;
+/**
+ * The minimal component-manager capability `createTriggerDispatch2D` needs —
+ * `getComponents` returning instances with optional trigger callbacks, typed
+ * honestly against `NodeOf<'pixijs'>` (T7.2, D8 — this dispatch is always
+ * pixi-world-scoped) rather than the full manager type. Deliberately a
+ * structural slice: the unified `ComponentManager` (`ecs/component-manager.ts`,
+ * what production wires up since T7.3 slice 1, and the only manager left —
+ * the world2d silo's manager is deleted, T7.3 slice 2) satisfies it — this
+ * dispatcher has no dependency on which `WorldKind` a caller's manager was
+ * constructed for.
+ */
+export interface TriggerDispatchComponents {
+    getComponents(node: NodeOf<'pixijs'>): ReadonlyArray<{
+        onTriggerEnter?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
+        onTriggerExit?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
+    }>;
+}
+/**
+ * Turn Rapier 2D sensor overlaps into `onTriggerEnter`/`onTriggerExit` callbacks on
+ * the GameComponents of the two involved display objects — the 2D analog of
+ * `createTriggerDispatch`. Only sensor-involved collisions dispatch triggers.
+ *
+ * `ctx` is typed `GameContext` (the unified manager's typing) — production
+ * (`pixi-game-adapter.ts`) casts its real `World2DContext` to `GameContext`
+ * before passing it here; individual `GameComponent<'pixijs'>` subclasses
+ * that need real 2D fields off `ctx` widen their own lifecycle-method
+ * signature to `GameContext | World2DContext` and narrow back down (see
+ * `Camera2DFollow.update` in `./components-2d.ts` — the worked example of
+ * the pattern since the world2d-demo silo and its `first-party-scene.ts`
+ * were deleted, T6.1 slice 4). This function only ever forwards `ctx` — it
+ * never reads a field off it itself.
+ */
+export declare function createTriggerDispatch2D(physics: Physics2DRegistry, components: TriggerDispatchComponents, rapierWorld: RAPIER.World, ctx: GameContext): Collision2DHandler;
+//# sourceMappingURL=collision-2d.d.ts.map

package/dist/world2d/collision-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/collision-2d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAE9F;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU;yBAGvE,kBAAkB;0BAGjB,kBAAkB;;8CAaE,MAAM,GAAG,MAAM,GAAG,SAAS;EAKxE;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC;QACnD,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;QACjE,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;KACjE,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,yBAAyB,EACrC,WAAW,EAAE,MAAM,CAAC,KAAK,EACzB,GAAG,EAAE,WAAW,GACf,kBAAkB,CAapB"}

package/dist/world2d/collision-2d.js

@@ -0,0 +1,70 @@
+/**
+ * Drains the Rapier 2D event queue each postPhysics and dispatches collision
+ * events — the world2d analog of `createCollisionSystem`. Events are buffered then
+ * handlers run after the drain returns (same re-entrancy guard as the 3D system:
+ * a handler must not call back into Rapier while the queue is borrowed).
+ */
+export function createCollision2DSystem(rapierWorld, eventQueue) {
+    const handlers = [];
+    return {
+        onCollision(handler) {
+            handlers.push(handler);
+        },
+        offCollision(handler) {
+            const idx = handlers.indexOf(handler);
+            if (idx !== -1)
+                handlers.splice(idx, 1);
+        },
+        drain() {
+            const events = [];
+            eventQueue.drainCollisionEvents((h1, h2, started) => {
+                events.push([h1, h2, started]);
+            });
+            for (const [h1, h2, started] of events) {
+                for (let i = 0; i < handlers.length; i++)
+                    handlers[i](h1, h2, started);
+            }
+        },
+        getBodyHandleFromCollider(colliderHandle) {
+            const collider = rapierWorld.getCollider(colliderHandle);
+            return collider?.parent()?.handle;
+        },
+    };
+}
+/**
+ * Turn Rapier 2D sensor overlaps into `onTriggerEnter`/`onTriggerExit` callbacks on
+ * the GameComponents of the two involved display objects — the 2D analog of
+ * `createTriggerDispatch`. Only sensor-involved collisions dispatch triggers.
+ *
+ * `ctx` is typed `GameContext` (the unified manager's typing) — production
+ * (`pixi-game-adapter.ts`) casts its real `World2DContext` to `GameContext`
+ * before passing it here; individual `GameComponent<'pixijs'>` subclasses
+ * that need real 2D fields off `ctx` widen their own lifecycle-method
+ * signature to `GameContext | World2DContext` and narrow back down (see
+ * `Camera2DFollow.update` in `./components-2d.ts` — the worked example of
+ * the pattern since the world2d-demo silo and its `first-party-scene.ts`
+ * were deleted, T6.1 slice 4). This function only ever forwards `ctx` — it
+ * never reads a field off it itself.
+ */
+export function createTriggerDispatch2D(physics, components, rapierWorld, ctx) {
+    return (handleA, handleB, started) => {
+        const colA = rapierWorld.getCollider(handleA);
+        const colB = rapierWorld.getCollider(handleB);
+        if (!colA?.isSensor() && !colB?.isSensor())
+            return;
+        const objA = physics.getByColliderHandle(handleA);
+        const objB = physics.getByColliderHandle(handleB);
+        if (!objA || !objB)
+            return;
+        notify(components, objA, objB, started, ctx);
+        notify(components, objB, objA, started, ctx);
+    };
+}
+function notify(components, self, other, started, ctx) {
+    for (const inst of components.getComponents(self)) {
+        if (started)
+            inst.onTriggerEnter?.(other, ctx);
+        else
+            inst.onTriggerExit?.(other, ctx);
+    }
+}

package/dist/world2d/components-2d.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { GameComponent } from '../ecs/game-component';
+import type { GameContext } from '../runtime/types';
+import type { World2DContext } from './types';
+/**
+ * Camera2DFollow — the canonical 2D camera (spec backend-2d-camera): a 2D camera is
+ * a transform on the world Container (`ctx.stage`). Attached to the entity to follow;
+ * each frame it pans/zooms `ctx.stage` so the target display stays centered. Mirrors
+ * the 3D "camera GameComponent on a camera entity" canonical-way rule.
+ */
+export declare class Camera2DFollow extends GameComponent<'pixijs'> {
+    static declaredKind: "pixijs";
+    static phase: "preRender";
+    static schema: z.ZodObject<{
+        zoom: z.ZodDefault<z.ZodNumber>;
+        smoothing: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    zoom: number;
+    smoothing: number;
+    update(_dt: number, gameCtx: GameContext | World2DContext): void;
+}
+/**
+ * Clickable2D — federated-events picking (spec backend-2d-input-picking). The sprite
+ * must be authored `interactive: true` (loader sets eventMode='static'); on pointerdown
+ * the sprite cycles tint, proving Pixi world picking works and is independent of the
+ * React/DOM HUD layer.
+ *
+ * INPUT ROUTING RULE (resolves the headline open design question): the three surfaces
+ * are stacked DOM siblings — React/DOM HUD (top, z-index, pointer-events gated) gets the
+ * event first; if it doesn't consume it, the Pixi canvas's federated EventSystem hit-tests
+ * world2d display objects; Three's raycaster handles the world3d canvas. Because each
+ * surface owns its own canvas/DOM node, a click on the HUD does not also pick the Pixi
+ * world beneath it, and vice-versa — no cross-surface double-picking.
+ */
+export declare class Clickable2D extends GameComponent<'pixijs'> {
+    static declaredKind: "pixijs";
+    static schema: z.ZodObject<{
+        tints: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    tints: string[];
+    private idx;
+    private handler;
+    init(): void;
+    update(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=components-2d.d.ts.map

package/dist/world2d/components-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/components-2d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,aAAa,CAAC,QAAQ,CAAC;IACzD,MAAM,CAAC,YAAY,EAAG,QAAQ,CAAU;IACxC,MAAM,CAAC,KAAK,EAAG,WAAW,CAAU;IACpC,MAAM,CAAC,MAAM;;;sBAGV;IACH,IAAI,SAAK;IACT,SAAS,SAAQ;IAcjB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,GAAG,IAAI;CAUjE;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,SAAQ,aAAa,CAAC,QAAQ,CAAC;IACtD,MAAM,CAAC,YAAY,EAAG,QAAQ,CAAU;IACxC,MAAM,CAAC,MAAM;;sBAKV;IACH,KAAK,EAAE,MAAM,EAAE,CAAgD;IAC/D,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,OAAO,CAMb;IAEF,IAAI,IAAI,IAAI;IAKZ,MAAM,IAAI,IAAI;IACd,OAAO,IAAI,IAAI;CAGhB"}

package/dist/world2d/components-2d.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { GameComponent } from '../ecs/game-component';
+/**
+ * Camera2DFollow — the canonical 2D camera (spec backend-2d-camera): a 2D camera is
+ * a transform on the world Container (`ctx.stage`). Attached to the entity to follow;
+ * each frame it pans/zooms `ctx.stage` so the target display stays centered. Mirrors
+ * the 3D "camera GameComponent on a camera entity" canonical-way rule.
+ */
+export class Camera2DFollow extends GameComponent {
+    static declaredKind = 'pixijs';
+    static phase = 'preRender';
+    static schema = z.object({
+        zoom: z.number().default(1).describe('Camera zoom (world Container scale)'),
+        smoothing: z.number().default(0.12).describe('Follow lerp factor 0..1 (1 = instant)'),
+    });
+    zoom = 1;
+    smoothing = 0.12;
+    // CONFLICT (bridged, same mechanism the deleted `GameComponent2D` alias
+    // used — T7.3 slice 2): `GameComponent<K>`'s lifecycle methods are typed
+    // `ctx: GameContext` (D8 §2 — `ctx` always means the game-level context),
+    // but this component genuinely needs `World2DContext` fields (`app`/
+    // `stage`), which share no structure with `GameContext` (neither is
+    // assignable to the other) — a plain `ctx: World2DContext` override would
+    // fail even under method bivariance (TS2416). Widening the parameter to
+    // the union is a valid (non-bivariant) override on its own — accepting a
+    // superset of the base signature is always sound — then narrowing back
+    // down via the cast below. At runtime this always receives the real
+    // `World2DContext` (`pixi-game-adapter.ts` casts it to `GameContext` only
+    // for the unified manager's internal typing).
+    update(_dt, gameCtx) {
+        const ctx = gameCtx;
+        const screen = ctx.app.screen;
+        const targetX = screen.width / 2 - this.node.x * this.zoom;
+        const targetY = screen.height / 2 - this.node.y * this.zoom;
+        const stage = ctx.stage;
+        stage.scale.set(this.zoom);
+        stage.position.x += (targetX - stage.position.x) * this.smoothing;
+        stage.position.y += (targetY - stage.position.y) * this.smoothing;
+    }
+}
+/**
+ * Clickable2D — federated-events picking (spec backend-2d-input-picking). The sprite
+ * must be authored `interactive: true` (loader sets eventMode='static'); on pointerdown
+ * the sprite cycles tint, proving Pixi world picking works and is independent of the
+ * React/DOM HUD layer.
+ *
+ * INPUT ROUTING RULE (resolves the headline open design question): the three surfaces
+ * are stacked DOM siblings — React/DOM HUD (top, z-index, pointer-events gated) gets the
+ * event first; if it doesn't consume it, the Pixi canvas's federated EventSystem hit-tests
+ * world2d display objects; Three's raycaster handles the world3d canvas. Because each
+ * surface owns its own canvas/DOM node, a click on the HUD does not also pick the Pixi
+ * world beneath it, and vice-versa — no cross-surface double-picking.
+ */
+export class Clickable2D extends GameComponent {
+    static declaredKind = 'pixijs';
+    static schema = z.object({
+        tints: z
+            .array(z.string())
+            .default(['#ff6b6b', '#4ecdc4', '#ffd23f', '#a06bff'])
+            .describe('Tint cycle'),
+    });
+    tints = ['#ff6b6b', '#4ecdc4', '#ffd23f', '#a06bff'];
+    idx = 0;
+    handler = () => {
+        this.idx = (this.idx + 1) % this.tints.length;
+        this.node.tint = Number.parseInt(this.tints[this.idx].replace('#', ''), 16);
+    };
+    init() {
+        this.node.eventMode = 'static';
+        this.node.cursor = 'pointer';
+        this.node.on('pointerdown', this.handler);
+    }
+    update() { }
+    dispose() {
+        this.node.off('pointerdown', this.handler);
+    }
+}

package/dist/world2d/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * world2d — the PixiJS 2D render surface for vgai.
+ *
+ * A peer to the Three.js world3d surface and the React UI surface (ARCHITECTURE.md
+ * §Render Surfaces). It LITERALLY reuses the engine's loop primitives (`createGameLoop`,
+ * `createSystemRunner`, `PHASE_ORDER`) and faithfully MIRRORS the entity / authored-data
+ * model as a 2D twin (`Scene2D`), instantiating entities as PixiJS display objects
+ * instead of Object3Ds, with 2D physics/collision via native Rapier 2D — built on
+ * native libraries with thin adapters. Gameplay behavior attaches via the SAME
+ * `GameComponent<'pixijs'>` (`ecs/game-component.ts`) and unified `ComponentManager`
+ * (`ecs/component-manager.ts`) every threejs world uses (T7.3).
+ *
+ * See docs/PIXI-WORLD2D-MAXIMAL-SPEC.json (FROZEN).
+ */
+export { AuthoringAdapter2D, type EditorNode2D, type Overlay2D, type Override2D, type Property2D, type Transform2DValue, } from './authoring-2d';
+export { captureToScene2D } from './capture-to-scene2d';
+export { type Collision2DSystem, createCollision2DSystem, createTriggerDispatch2D, } from './collision-2d';
+export { Camera2DFollow, Clickable2D } from './components-2d';
+export { type EmbedMount2D, type IframeReachableMount2D, mountIngestGame2DEmbed, mountIngestGame2DIframeReachable, } from './ingest-iframe-2d';
+export { type IngestGame2D, type IngestMount2D, mountIngestGame2D } from './ingest2d';
+export { createPhysics2DRegistry, type Physics2DRefs, type Physics2DRegistry, } from './physics2d-registry';
+export { createWorld2DRuntime, type MountedGame2D, type PixiSceneConfig, PixiSceneGameAdapter, type World2DHost, type World2DSession, type World2DSetupFn, } from './pixi-game-adapter';
+export { createPixiSurface, type PixiSurface, type PixiSurfaceOptions } from './pixi-surface';
+export { type CapturedRuntime2D, installSceneCapture2D, type SceneCapture2DHandle, } from './scene-capture-2d';
+export { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
+export * from './schema/entity2d';
+export * from './schema/physics2d';
+export * from './schema/sprite';
+export * from './schema/tilemap';
+export * from './schema/tuples2d';
+export { createPhysicsAdapter2D, type PhysicsAdapter2D } from './system-adapters-2d';
+export { createTransformWriter2D } from './transform-writer-2d';
+export type { Component2DRegistry, World2DContext } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world2d/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EACL,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,sBAAsB,EACtB,gCAAgC,GACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EACL,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC7E,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/world2d/index.js

@@ -0,0 +1,32 @@
+/**
+ * world2d — the PixiJS 2D render surface for vgai.
+ *
+ * A peer to the Three.js world3d surface and the React UI surface (ARCHITECTURE.md
+ * §Render Surfaces). It LITERALLY reuses the engine's loop primitives (`createGameLoop`,
+ * `createSystemRunner`, `PHASE_ORDER`) and faithfully MIRRORS the entity / authored-data
+ * model as a 2D twin (`Scene2D`), instantiating entities as PixiJS display objects
+ * instead of Object3Ds, with 2D physics/collision via native Rapier 2D — built on
+ * native libraries with thin adapters. Gameplay behavior attaches via the SAME
+ * `GameComponent<'pixijs'>` (`ecs/game-component.ts`) and unified `ComponentManager`
+ * (`ecs/component-manager.ts`) every threejs world uses (T7.3).
+ *
+ * See docs/PIXI-WORLD2D-MAXIMAL-SPEC.json (FROZEN).
+ */
+export { AuthoringAdapter2D, } from './authoring-2d';
+export { captureToScene2D } from './capture-to-scene2d';
+export { createCollision2DSystem, createTriggerDispatch2D, } from './collision-2d';
+export { Camera2DFollow, Clickable2D } from './components-2d';
+export { mountIngestGame2DEmbed, mountIngestGame2DIframeReachable, } from './ingest-iframe-2d';
+export { mountIngestGame2D } from './ingest2d';
+export { createPhysics2DRegistry, } from './physics2d-registry';
+export { createWorld2DRuntime, PixiSceneGameAdapter, } from './pixi-game-adapter';
+export { createPixiSurface } from './pixi-surface';
+export { installSceneCapture2D, } from './scene-capture-2d';
+export { loadScene2DFromData } from './scene2d-loader';
+export * from './schema/entity2d';
+export * from './schema/physics2d';
+export * from './schema/sprite';
+export * from './schema/tilemap';
+export * from './schema/tuples2d';
+export { createPhysicsAdapter2D } from './system-adapters-2d';
+export { createTransformWriter2D } from './transform-writer-2d';

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

@@ -0,0 +1,82 @@
+/**
+ * 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, type SceneCapture2DHandle } from './scene-capture-2d';
+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>>;
+    /**
+     * 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 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-2d.d.ts.map

package/dist/world2d/ingest-iframe-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-iframe-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/ingest-iframe-2d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,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"}