@vgai/engine 0.5.4 → 0.5.6

package/dist/asset-parse-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The GENERIC fetched-asset parse error.
+ *
+ * Every authored asset format the engine validates at fetch time throws this
+ * when Zod rejects the payload, naming the offending file (T4.6). It lives
+ * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
+ * every caller (the `.mat.json` parser, the input-map loader in
+ * `input/input-manager.ts`) does not have to reach into the format half for
+ * it.
+ *
+ * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
+ * this file its name deliberately deferred the class rename ("extraction, not
+ * redesign"); with `.vscn` gone the old name described nothing — a `.mat.json`
+ * or `.inputmap.json` failure is not a scene failure — so the class and its
+ * message header now say `asset`.
+ */
+import type { ZodIssue } from 'zod';
+export declare class AssetParseError extends Error {
+    readonly issues: ZodIssue[];
+    /** The offending file's path/URL, when the caller knows it (T4.6). */
+    readonly filePath?: string | undefined;
+    constructor(issues: ZodIssue[], filePath?: string);
+}
+//# sourceMappingURL=asset-parse-error.d.ts.map

package/dist/asset-parse-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-parse-error.d.ts","sourceRoot":"","sources":["../src/asset-parse-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM;CAQlD"}

package/dist/asset-parse-error.js

@@ -0,0 +1,29 @@
+/**
+ * The GENERIC fetched-asset parse error.
+ *
+ * Every authored asset format the engine validates at fetch time throws this
+ * when Zod rejects the payload, naming the offending file (T4.6). It lives
+ * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
+ * every caller (the `.mat.json` parser, the input-map loader in
+ * `input/input-manager.ts`) does not have to reach into the format half for
+ * it.
+ *
+ * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
+ * this file its name deliberately deferred the class rename ("extraction, not
+ * redesign"); with `.vscn` gone the old name described nothing — a `.mat.json`
+ * or `.inputmap.json` failure is not a scene failure — so the class and its
+ * message header now say `asset`.
+ */
+export class AssetParseError extends Error {
+    issues;
+    /** The offending file's path/URL, when the caller knows it (T4.6). */
+    filePath;
+    constructor(issues, filePath) {
+        const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+        const header = filePath ? `Asset validation failed (${filePath}):` : 'Asset validation failed:';
+        super(`${header}\n${msg}`);
+        this.name = 'AssetParseError';
+        this.issues = issues;
+        this.filePath = filePath;
+    }
+}

package/dist/asset-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Central asset registry — stores per-asset metadata (import corrections, etc.).
+ *
+ * Loaded once via fetch(), cached in memory. Both the runtime scene loader
+ * and editor entity factory import from this module.
+ */
+import * as THREE from 'three';
+export interface ImportCorrection {
+    /** Uniform scale factor applied to the GLTF clone before entity transform. */
+    scale?: number;
+    /** Euler rotation in degrees [x, y, z] applied to the GLTF clone before entity transform. */
+    rotation?: [number, number, number];
+}
+export interface AssetMeta {
+    importCorrection?: ImportCorrection;
+}
+/**
+ * Apply an asset's visual-only import correction to the loaded GLTF content.
+ * Call this on the model child, before placing it under the entity wrapper, so
+ * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
+ * -Z-forward coordinate contract.
+ */
+export declare function applyImportCorrection(content: THREE.Object3D, correction: ImportCorrection | undefined): void;
+type AssetRegistry = Record<string, AssetMeta>;
+/**
+ * Fetch and cache the asset registry. Safe to call multiple times —
+ * returns the cached result after the first successful load.
+ */
+export declare function loadRegistry(): Promise<AssetRegistry>;
+/** Get metadata for an asset path, or undefined if not in the registry. */
+export declare function getAssetMeta(path: string): AssetMeta | undefined;
+/**
+ * Update the in-memory cache directly (used by the editor after saving
+ * import settings, to avoid a re-fetch).
+ */
+export declare function setRegistryCache(data: AssetRegistry): void;
+export {};
+//# sourceMappingURL=asset-registry.d.ts.map

package/dist/asset-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-registry.d.ts","sourceRoot":"","sources":["../src/asset-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,KAAK,CAAC,QAAQ,EACvB,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,IAAI,CAUN;AAED,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAU/C;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAgBrD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAG1D"}

package/dist/asset-registry.js

@@ -0,0 +1,66 @@
+/**
+ * Central asset registry — stores per-asset metadata (import corrections, etc.).
+ *
+ * Loaded once via fetch(), cached in memory. Both the runtime scene loader
+ * and editor entity factory import from this module.
+ */
+import * as THREE from 'three';
+import { resolveUrl } from './loader';
+/**
+ * Apply an asset's visual-only import correction to the loaded GLTF content.
+ * Call this on the model child, before placing it under the entity wrapper, so
+ * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
+ * -Z-forward coordinate contract.
+ */
+export function applyImportCorrection(content, correction) {
+    if (!correction)
+        return;
+    if (correction.scale !== undefined)
+        content.scale.multiplyScalar(correction.scale);
+    if (correction.rotation) {
+        content.rotation.set(THREE.MathUtils.degToRad(correction.rotation[0]), THREE.MathUtils.degToRad(correction.rotation[1]), THREE.MathUtils.degToRad(correction.rotation[2]));
+    }
+}
+let registryCache = null;
+let registryPromise = null;
+/** Normalize asset path for registry lookup (strip leading slash). */
+function normalize(path) {
+    return path.startsWith('/') ? path.slice(1) : path;
+}
+/**
+ * Fetch and cache the asset registry. Safe to call multiple times —
+ * returns the cached result after the first successful load.
+ */
+export function loadRegistry() {
+    if (registryCache)
+        return Promise.resolve(registryCache);
+    if (registryPromise)
+        return registryPromise;
+    registryPromise = fetch(resolveUrl('asset-registry.json'))
+        .then((res) => {
+        if (!res.ok)
+            return {};
+        return res.json();
+    })
+        .catch(() => ({}))
+        .then((data) => {
+        registryCache = data;
+        return data;
+    });
+    return registryPromise;
+}
+/** Get metadata for an asset path, or undefined if not in the registry. */
+export function getAssetMeta(path) {
+    if (!registryCache)
+        return undefined;
+    // Try exact match first, then normalized
+    return registryCache[path] ?? registryCache[normalize(path)];
+}
+/**
+ * Update the in-memory cache directly (used by the editor after saving
+ * import settings, to avoid a re-fetch).
+ */
+export function setRegistryCache(data) {
+    registryCache = data;
+    registryPromise = null;
+}

package/dist/assets.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
+ *
+ * Inspired by Unity's Resources.Load / Godot's load():
+ *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
+ *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
+ *
+ * GLTF files (.glb/.gltf) resolve to GLTFResult.
+ * JSON files resolve to the parsed object (caller provides type via generic).
+ *
+ * Cache lives for the app lifetime — no dispose needed.
+ */
+import type * as THREE from 'three';
+/** Result of loading a .glb/.gltf file. */
+export interface GLTFResult {
+    scene: THREE.Group;
+    animations: THREE.AnimationClip[];
+}
+export interface AssetCache {
+    /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
+    load<T = unknown>(url: string): Promise<T>;
+    /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
+    get<T = unknown>(url: string): T;
+}
+export declare function createAssetCache(): AssetCache;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;CAClC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAiD7C"}

package/dist/assets.js

@@ -0,0 +1,55 @@
+/**
+ * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
+ *
+ * Inspired by Unity's Resources.Load / Godot's load():
+ *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
+ *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
+ *
+ * GLTF files (.glb/.gltf) resolve to GLTFResult.
+ * JSON files resolve to the parsed object (caller provides type via generic).
+ *
+ * Cache lives for the app lifetime — no dispose needed.
+ */
+import { gltfLoader, resolveUrl } from './loader';
+export function createAssetCache() {
+    const cache = new Map();
+    const resolved = new Map();
+    // Use the shared, DRACO-wired GLTFLoader (A2 / CB2) — no second loader instance.
+    // This cache keeps the parsed source GLTFResult (load/get semantics for gameplay
+    // code); it does NOT clone. Callers that need disposal-safe clones use
+    // asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
+    function load(url) {
+        const existing = cache.get(url);
+        if (existing)
+            return existing;
+        let promise;
+        if (url.endsWith('.glb') || url.endsWith('.gltf')) {
+            promise = new Promise((resolve, reject) => {
+                gltfLoader.load(url, (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }), undefined, reject);
+            });
+        }
+        else if (url.endsWith('.json')) {
+            promise = fetch(resolveUrl(url)).then((r) => {
+                if (!r.ok)
+                    throw new Error(`Failed to fetch ${url}: ${r.status}`);
+                return r.json();
+            });
+        }
+        else {
+            throw new Error(`AssetCache: unsupported file type for "${url}"`);
+        }
+        const tracked = promise.then((value) => {
+            resolved.set(url, value);
+            return value;
+        });
+        cache.set(url, tracked);
+        return tracked;
+    }
+    function get(url) {
+        if (!resolved.has(url)) {
+            throw new Error(`AssetCache: "${url}" not loaded. Call load() first and await it.`);
+        }
+        return resolved.get(url);
+    }
+    return { load, get };
+}

package/dist/audio/wav-encode.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half).
+ * This module takes already-rendered Float32 channel data (e.g.
+ * `AudioBuffer.getChannelData(n)` from a `Tone.Offline` render,
+ * `audio/tone-offline-render.ts`) and produces a standard little-endian,
+ * 16-bit-PCM, interleaved RIFF/WAVE file as raw bytes — no
+ * `AudioBuffer`/`AudioContext` dependency, so this runs equally in a browser
+ * render-mode page (`runtime/render-audio-control.ts`) and in plain Node (this
+ * module's own `packages/engine/test/audio/wav-encode.test.ts`, no Playwright
+ * needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+export interface PcmToWavInput {
+    /** One `Float32Array` per channel, each sample in `[-1, 1]` (values outside
+     *  that range are clamped, not thrown on — real synthesis can transiently
+     *  clip). All channels must have equal length. */
+    readonly channelData: readonly Float32Array[];
+    readonly sampleRate: number;
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export declare function encodeWav16(input: PcmToWavInput): Uint8Array;
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export declare function pcmStats(channelData: readonly Float32Array[]): {
+    rms: number;
+    peak: number;
+};
+//# sourceMappingURL=wav-encode.d.ts.map

package/dist/audio/wav-encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav-encode.d.ts","sourceRoot":"","sources":["../../src/audio/wav-encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;sEAIsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAwD5D;AAED;;;2DAG2D;AAC3D,wBAAgB,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa5F"}

package/dist/audio/wav-encode.js

@@ -0,0 +1,97 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half).
+ * This module takes already-rendered Float32 channel data (e.g.
+ * `AudioBuffer.getChannelData(n)` from a `Tone.Offline` render,
+ * `audio/tone-offline-render.ts`) and produces a standard little-endian,
+ * 16-bit-PCM, interleaved RIFF/WAVE file as raw bytes — no
+ * `AudioBuffer`/`AudioContext` dependency, so this runs equally in a browser
+ * render-mode page (`runtime/render-audio-control.ts`) and in plain Node (this
+ * module's own `packages/engine/test/audio/wav-encode.test.ts`, no Playwright
+ * needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+const BYTES_PER_SAMPLE = 2; // 16-bit PCM
+const WAV_HEADER_BYTES = 44;
+function clamp(value, lo, hi) {
+    return Math.min(hi, Math.max(lo, value));
+}
+function writeAsciiString(view, offset, text) {
+    for (let i = 0; i < text.length; i++) {
+        view.setUint8(offset + i, text.charCodeAt(i));
+    }
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export function encodeWav16(input) {
+    const { channelData, sampleRate } = input;
+    const numChannels = channelData.length;
+    if (numChannels === 0) {
+        throw new Error('[wav-encode] channelData must contain at least one channel');
+    }
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`[wav-encode] sampleRate must be a finite number > 0, got ${sampleRate}`);
+    }
+    const numFrames = channelData[0]?.length ?? 0;
+    for (let ch = 0; ch < numChannels; ch++) {
+        const len = channelData[ch]?.length ?? -1;
+        if (len !== numFrames) {
+            throw new Error(`[wav-encode] channel ${ch} has length ${len}, expected ${numFrames} (all channels must match)`);
+        }
+    }
+    const blockAlign = numChannels * BYTES_PER_SAMPLE;
+    const byteRate = sampleRate * blockAlign;
+    const dataSize = numFrames * blockAlign;
+    const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+    const view = new DataView(buffer);
+    // RIFF chunk descriptor
+    writeAsciiString(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAsciiString(view, 8, 'WAVE');
+    // fmt subchunk (PCM)
+    writeAsciiString(view, 12, 'fmt ');
+    view.setUint32(16, 16, true); // subchunk size for PCM
+    view.setUint16(20, 1, true); // audio format 1 = PCM
+    view.setUint16(22, numChannels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, BYTES_PER_SAMPLE * 8, true); // bits per sample
+    // data subchunk
+    writeAsciiString(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    let offset = WAV_HEADER_BYTES;
+    for (let i = 0; i < numFrames; i++) {
+        for (let ch = 0; ch < numChannels; ch++) {
+            const sample = clamp(channelData[ch]?.[i] ?? 0, -1, 1);
+            const intSample = Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff);
+            view.setInt16(offset, intSample, true);
+            offset += BYTES_PER_SAMPLE;
+        }
+    }
+    return new Uint8Array(buffer);
+}
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export function pcmStats(channelData) {
+    let sumSquares = 0;
+    let peak = 0;
+    let count = 0;
+    for (const data of channelData) {
+        for (let i = 0; i < data.length; i++) {
+            const v = data[i] ?? 0;
+            sumSquares += v * v;
+            peak = Math.max(peak, Math.abs(v));
+            count++;
+        }
+    }
+    return { rms: count > 0 ? Math.sqrt(sumSquares / count) : 0, peak };
+}

package/dist/canvas-react/engine-bridge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@engine/canvas-react` — the React context that carries a canvas world's
+ * engine runtime into its `@pixi/react` tree: the world's `GameContext`, read
+ * with {@link useGameContext}.
+ *
+ * The bridge value is built by `createPixiReactAdapter`'s `mount()`
+ * (./pixi-react-adapter.tsx), whose `update(dt)` runs this world's phases under
+ * the HOST loop — so registered systems tick in engine phase order, pause
+ * included (no update while the world is frozen).
+ *
+ * Behavior in a canvas world is components + hooks: `useGameContext` reaches
+ * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
+ * `useApplication` is the door to the live `Application`.
+ */
+import type { GameContext } from '../runtime/types';
+export interface EngineBridgeValue {
+    /** This root's `GameContext` — `input`, `debug`, `random`, `clock`, `game`,
+     *  `roots`, `systems`, `registerSystemAdapter`. Present so ordinary
+     *  components can reach engine services with a HOOK (see
+     *  {@link useGameContext}). */
+    readonly ctx?: GameContext | undefined;
+}
+export declare const EngineBridge: import("react").Context<EngineBridgeValue | null>;
+/**
+ * This canvas root's `GameContext`, for use inside any component in the tree.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 220 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<Sprite>(null);
+ *   useTick(({ deltaMS }) => {
+ *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *   });
+ *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
+ * }
+ * ```
+ *
+ * Throws when called outside a canvas root mounted by
+ * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
+ * `null` would surface as a mystery `undefined` deep in a tick callback.
+ */
+export declare function useGameContext(): GameContext;
+//# sourceMappingURL=engine-bridge.d.ts.map

package/dist/canvas-react/engine-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/canvas-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC;;;mCAG+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACxC;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAU5C"}

package/dist/canvas-react/engine-bridge.js

@@ -0,0 +1,45 @@
+/**
+ * `@engine/canvas-react` — the React context that carries a canvas world's
+ * engine runtime into its `@pixi/react` tree: the world's `GameContext`, read
+ * with {@link useGameContext}.
+ *
+ * The bridge value is built by `createPixiReactAdapter`'s `mount()`
+ * (./pixi-react-adapter.tsx), whose `update(dt)` runs this world's phases under
+ * the HOST loop — so registered systems tick in engine phase order, pause
+ * included (no update while the world is frozen).
+ *
+ * Behavior in a canvas world is components + hooks: `useGameContext` reaches
+ * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
+ * `useApplication` is the door to the live `Application`.
+ */
+import { createContext, useContext } from 'react';
+export const EngineBridge = createContext(null);
+/**
+ * This canvas root's `GameContext`, for use inside any component in the tree.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 220 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<Sprite>(null);
+ *   useTick(({ deltaMS }) => {
+ *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *   });
+ *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
+ * }
+ * ```
+ *
+ * Throws when called outside a canvas root mounted by
+ * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
+ * `null` would surface as a mystery `undefined` deep in a tick callback.
+ */
+export function useGameContext() {
+    const bridge = useContext(EngineBridge);
+    if (!bridge?.ctx) {
+        throw new Error('useGameContext(): no engine root context. This hook only works inside a canvas ' +
+            'root mounted by createPixiReactAdapter (@engine/canvas-react) — check that the ' +
+            'component is rendered inside your world entry, not in a standalone <Application>.');
+    }
+    return bridge.ctx;
+}

package/dist/canvas-react/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * canvas-react — the `@pixi/react` lane for vgai's canvas surface
+ * (`@engine/canvas-react`).
+ *
+ * The canvas surface is source-as-truth: a canvas root's document IS its
+ * TSX world file, exactly as a three root's document is its R3F source. This
+ * module is the peer of `world3d-react/` — same seam, same shape, Pixi instead
+ * of three — and the peer of `pixi/`, which holds what the host needs to mount
+ * and inspect a PixiJS game it did NOT write.
+ *
+ * The engine CORE never imports this (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/` and `world3d-react/`, and
+ * core files may not import it), so a three-only bundle never pays for react
+ * or the Pixi reconciler.
+ *
+ * Surface:
+ *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
+ *    a first-party `surface: "canvas"` root under the host's gated loop.
+ *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
+ *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
+ *    render a container the game already owns, and place a spawn in the
+ *    display tree ahead of the commit that renders it.
+ *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
+ *    Behavior in a canvas world is components + hooks, never a class under a
+ *    string key.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
+ *    adopters building their own bridge.
+ *
+ * The Pixi runtime itself is NOT re-exported here. A component reaches the live
+ * `Application` (and therefore `stage`, `renderer`, `ticker`) with
+ * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
+ * assets with Pixi's own `Assets` — the library's API, not a second one.
+ */
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
+export { adoptNow, PixiPrimitive, type PixiPrimitiveProps } from './pixi-primitive';
+export { type CreatePixiReactAdapterOptions, createPixiReactAdapter, } from './pixi-react-adapter';
+export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
+export { type CanvasRootContextOptions, type CanvasRootRuntime, createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';
+//# sourceMappingURL=index.d.ts.map

package/dist/canvas-react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/canvas-react/index.js

@@ -0,0 +1,41 @@
+/**
+ * canvas-react — the `@pixi/react` lane for vgai's canvas surface
+ * (`@engine/canvas-react`).
+ *
+ * The canvas surface is source-as-truth: a canvas root's document IS its
+ * TSX world file, exactly as a three root's document is its R3F source. This
+ * module is the peer of `world3d-react/` — same seam, same shape, Pixi instead
+ * of three — and the peer of `pixi/`, which holds what the host needs to mount
+ * and inspect a PixiJS game it did NOT write.
+ *
+ * The engine CORE never imports this (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/` and `world3d-react/`, and
+ * core files may not import it), so a three-only bundle never pays for react
+ * or the Pixi reconciler.
+ *
+ * Surface:
+ *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
+ *    a first-party `surface: "canvas"` root under the host's gated loop.
+ *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
+ *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
+ *    render a container the game already owns, and place a spawn in the
+ *    display tree ahead of the commit that renders it.
+ *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
+ *    Behavior in a canvas world is components + hooks, never a class under a
+ *    string key.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
+ *    adopters building their own bridge.
+ *
+ * The Pixi runtime itself is NOT re-exported here. A component reaches the live
+ * `Application` (and therefore `stage`, `renderer`, `ticker`) with
+ * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
+ * assets with Pixi's own `Assets` — the library's API, not a second one.
+ */
+export { EngineBridge, useGameContext } from './engine-bridge';
+export { adoptNow, PixiPrimitive } from './pixi-primitive';
+export { createPixiReactAdapter, } from './pixi-react-adapter';
+export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
+export { createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';