@vgai/engine 0.5.4 → 0.5.6

package/dist/defaults.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Single source of truth for default values the engine's factories read.
+ *
+ * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
+ * `animation`, `fog`, `environment` — because every one of their readers was a
+ * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
+ * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
+ * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
+ * readers anywhere in engine/editor src or tests. That guard offers two remedies
+ * — wire the group to the factory that reads it, or delete it if truly unused —
+ * and there is no surviving factory to wire these to: `transform` restated
+ * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
+ * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
+ * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
+ * forward. Keeping them would have been exactly the dead documentation T1.13
+ * created this guard to prevent.
+ *
+ */
+export declare const DEFAULTS: {
+    readonly material: {
+        readonly type: "standard";
+        readonly color: "#888888";
+        readonly metalness: 0;
+        readonly roughness: 0.5;
+        readonly emissive: "#000000";
+        readonly emissiveIntensity: 0;
+        readonly opacity: 1;
+        readonly transparent: false;
+        readonly side: "front";
+        readonly flatShading: false;
+        readonly clearcoat: {
+            readonly clearcoat: 1;
+            readonly clearcoatRoughness: 0;
+        };
+        readonly transmission: {
+            readonly transmission: 1;
+            readonly ior: 1.5;
+            readonly thickness: 0.5;
+        };
+        readonly sheen: {
+            readonly sheen: 1;
+            readonly sheenColor: "#ffffff";
+            readonly sheenRoughness: 0.5;
+        };
+        readonly iridescence: {
+            readonly iridescence: 1;
+            readonly iridescenceIOR: 1.3;
+            readonly iridescenceThicknessRange: [number, number];
+        };
+        readonly displacementScale: 1;
+        readonly displacementBias: 0;
+    };
+    readonly light: {
+        readonly color: "#ffffff";
+        readonly intensity: 1;
+        readonly groundColor: "#000000";
+        readonly distance: 0;
+        readonly decay: 2;
+        readonly angle: number;
+        readonly penumbra: 0;
+        readonly width: 10;
+        readonly height: 10;
+    };
+    readonly camera: {
+        readonly fov: 60;
+        readonly near: 0.1;
+        readonly far: 1000;
+        readonly orthoSize: 5;
+        readonly width: 1920;
+        readonly height: 1080;
+    };
+    readonly collider: {
+        readonly cuboid: {
+            readonly halfExtents: [number, number, number];
+        };
+        readonly ball: {
+            readonly radius: 0.5;
+        };
+        readonly capsule: {
+            readonly radius: 0.25;
+            readonly halfHeight: 0.5;
+        };
+    };
+    readonly toneMapping: {
+        readonly mode: "aces";
+        readonly exposure: 1;
+    };
+    readonly postProcessing: {
+        readonly bloom: {
+            readonly intensity: 1;
+            readonly luminanceThreshold: 0.9;
+            readonly luminanceSmoothing: 0.025;
+        };
+        readonly vignette: {
+            readonly darkness: 0.5;
+            readonly offset: 0.5;
+        };
+        readonly brightnessContrast: {
+            readonly brightness: 0;
+            readonly contrast: 0;
+        };
+        readonly hueSaturation: {
+            readonly hue: 0;
+            readonly saturation: 0;
+        };
+        readonly sepia: {
+            readonly intensity: 1;
+        };
+        readonly colorDepth: {
+            readonly bits: 16;
+        };
+        readonly chromaticAberration: {
+            readonly offsetX: 0.002;
+            readonly offsetY: 0.002;
+            readonly modulationOffset: 0.15;
+        };
+        readonly lensDistortion: {
+            readonly distortionX: 0;
+            readonly distortionY: 0;
+            readonly focalLengthX: 1;
+            readonly focalLengthY: 1;
+            readonly skew: 0;
+        };
+        readonly depthOfField: {
+            readonly worldFocusDistance: 10;
+            readonly worldFocusRange: 5;
+            readonly bokehScale: 3;
+            readonly focalLength: 0.04;
+        };
+        readonly tiltShift: {
+            readonly offset: 0;
+            readonly rotation: 0;
+            readonly focusArea: 0.4;
+            readonly feather: 0.3;
+        };
+        readonly noise: {
+            readonly premultiply: false;
+        };
+        readonly scanline: {
+            readonly density: 1.25;
+        };
+        readonly dotScreen: {
+            readonly angle: 1.57;
+            readonly scale: 1;
+        };
+        readonly grid: {
+            readonly scale: 1;
+            readonly lineWidth: 0;
+        };
+        readonly pixelation: {
+            readonly granularity: 6;
+        };
+        readonly glitch: {
+            readonly delayX: 1.5;
+            readonly delayY: 3.5;
+            readonly durationX: 0.6;
+            readonly durationY: 1;
+            readonly strengthX: 0.3;
+            readonly strengthY: 1;
+            readonly columns: 0.05;
+            readonly ratio: 0.85;
+        };
+        readonly shockWave: {
+            readonly speed: 2;
+            readonly maxRadius: 1;
+            readonly waveSize: 0.2;
+            readonly amplitude: 0.05;
+        };
+        readonly smaa: {
+            readonly preset: "high";
+        };
+        readonly ssao: {
+            readonly radius: 0.05;
+            readonly intensity: 2;
+            readonly bias: 0.025;
+            readonly samples: 16;
+            readonly rings: 7;
+            readonly fade: 0.01;
+        };
+        readonly n8ao: {
+            readonly aoSamples: 16;
+            readonly aoRadius: 5;
+            readonly intensity: 5;
+            readonly denoiseSamples: 8;
+            readonly denoiseRadius: 12;
+            readonly distanceFalloff: 1;
+        };
+        readonly godRays: {
+            readonly density: 0.96;
+            readonly decay: 0.93;
+            readonly weight: 0.4;
+            readonly exposure: 0.6;
+            readonly samples: 60;
+        };
+        readonly outline: {
+            readonly edgeStrength: 3;
+            readonly pulseSpeed: 0;
+            readonly visibleEdgeColor: "#ffffff";
+            readonly hiddenEdgeColor: "#22090a";
+        };
+        readonly ssr: {
+            readonly intensity: 1;
+            readonly exponent: 1;
+            readonly distance: 10;
+            readonly thickness: 10;
+            readonly maxRoughness: 1;
+        };
+        readonly ssgi: {
+            readonly intensity: 1;
+            readonly distance: 10;
+            readonly thickness: 10;
+            readonly maxRoughness: 1;
+        };
+        readonly motionBlur: {
+            readonly intensity: 1;
+            readonly jitter: 1;
+            readonly samples: 16;
+        };
+    };
+    readonly navigation: {
+        readonly cellSize: 0.3;
+        readonly cellHeight: 0.2;
+        readonly walkableSlopeAngle: 45;
+        readonly walkableHeight: 2;
+        readonly walkableClimb: 1;
+        readonly walkableRadius: 0.5;
+        readonly maxEdgeLen: 12;
+        readonly maxSimplificationError: 1.3;
+        readonly minRegionArea: 8;
+        readonly mergeRegionArea: 20;
+    };
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDAkB0B,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;kCA6BjB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6E5D,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,137 @@
+/**
+ * Single source of truth for default values the engine's factories read.
+ *
+ * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
+ * `animation`, `fog`, `environment` — because every one of their readers was a
+ * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
+ * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
+ * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
+ * readers anywhere in engine/editor src or tests. That guard offers two remedies
+ * — wire the group to the factory that reads it, or delete it if truly unused —
+ * and there is no surviving factory to wire these to: `transform` restated
+ * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
+ * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
+ * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
+ * forward. Keeping them would have been exactly the dead documentation T1.13
+ * created this guard to prevent.
+ *
+ */
+export const DEFAULTS = {
+    material: {
+        type: 'standard',
+        color: '#888888',
+        metalness: 0,
+        roughness: 0.5,
+        emissive: '#000000',
+        emissiveIntensity: 0,
+        opacity: 1,
+        transparent: false,
+        side: 'front',
+        flatShading: false,
+        clearcoat: { clearcoat: 1, clearcoatRoughness: 0 },
+        transmission: { transmission: 1, ior: 1.5, thickness: 0.5 },
+        sheen: { sheen: 1, sheenColor: '#ffffff', sheenRoughness: 0.5 },
+        iridescence: {
+            iridescence: 1,
+            iridescenceIOR: 1.3,
+            iridescenceThicknessRange: [100, 400],
+        },
+        displacementScale: 1,
+        displacementBias: 0,
+    },
+    light: {
+        color: '#ffffff',
+        intensity: 1,
+        groundColor: '#000000',
+        distance: 0,
+        decay: 2,
+        angle: Math.PI / 6,
+        penumbra: 0,
+        // three.js's own RectAreaLight constructor defaults (area lights only).
+        width: 10,
+        height: 10,
+    },
+    camera: {
+        fov: 60,
+        near: 0.1,
+        far: 1000,
+        orthoSize: 5,
+        width: 1920,
+        height: 1080,
+    },
+    collider: {
+        cuboid: { halfExtents: [0.5, 0.5, 0.5] },
+        ball: { radius: 0.5 },
+        capsule: { radius: 0.25, halfHeight: 0.5 },
+    },
+    toneMapping: {
+        // T1.13: the effective renderer default is ACES (see
+        // setup-renderer.ts's `createHostRenderer` + `applyScenePostProcessing`,
+        // which both hardcode `THREE.ACESFilmicToneMapping`/'aces' as the
+        // fallback when a scene omits `environment.toneMapping`) — NOT 'none'.
+        // This used to say 'none', silently disagreeing with the runtime and
+        // with the editor's Tone Mapping inspector dropdown.
+        mode: 'aces',
+        exposure: 1.0,
+    },
+    postProcessing: {
+        bloom: { intensity: 1.0, luminanceThreshold: 0.9, luminanceSmoothing: 0.025 },
+        vignette: { darkness: 0.5, offset: 0.5 },
+        brightnessContrast: { brightness: 0, contrast: 0 },
+        hueSaturation: { hue: 0, saturation: 0 },
+        sepia: { intensity: 1.0 },
+        colorDepth: { bits: 16 },
+        chromaticAberration: { offsetX: 0.002, offsetY: 0.002, modulationOffset: 0.15 },
+        lensDistortion: { distortionX: 0, distortionY: 0, focalLengthX: 1, focalLengthY: 1, skew: 0 },
+        depthOfField: { worldFocusDistance: 10, worldFocusRange: 5, bokehScale: 3, focalLength: 0.04 },
+        tiltShift: { offset: 0, rotation: 0, focusArea: 0.4, feather: 0.3 },
+        noise: { premultiply: false },
+        scanline: { density: 1.25 },
+        dotScreen: { angle: 1.57, scale: 1.0 },
+        grid: { scale: 1.0, lineWidth: 0.0 },
+        pixelation: { granularity: 6 },
+        glitch: {
+            delayX: 1.5,
+            delayY: 3.5,
+            durationX: 0.6,
+            durationY: 1.0,
+            strengthX: 0.3,
+            strengthY: 1.0,
+            columns: 0.05,
+            ratio: 0.85,
+        },
+        shockWave: { speed: 2, maxRadius: 1, waveSize: 0.2, amplitude: 0.05 },
+        smaa: { preset: 'high' },
+        ssao: { radius: 0.05, intensity: 2.0, bias: 0.025, samples: 16, rings: 7, fade: 0.01 },
+        n8ao: {
+            aoSamples: 16,
+            aoRadius: 5.0,
+            intensity: 5,
+            denoiseSamples: 8,
+            denoiseRadius: 12,
+            distanceFalloff: 1.0,
+        },
+        godRays: { density: 0.96, decay: 0.93, weight: 0.4, exposure: 0.6, samples: 60 },
+        outline: {
+            edgeStrength: 3,
+            pulseSpeed: 0,
+            visibleEdgeColor: '#ffffff',
+            hiddenEdgeColor: '#22090a',
+        },
+        ssr: { intensity: 1, exponent: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+        ssgi: { intensity: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+        motionBlur: { intensity: 1, jitter: 1, samples: 16 },
+    },
+    navigation: {
+        cellSize: 0.3,
+        cellHeight: 0.2,
+        walkableSlopeAngle: 45,
+        walkableHeight: 2,
+        walkableClimb: 1,
+        walkableRadius: 0.5,
+        maxEdgeLen: 12,
+        maxSimplificationError: 1.3,
+        minRegionArea: 8,
+        mergeRegionArea: 20,
+    },
+};

package/dist/dev/chrome-trace.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Chrome Trace Event Format exporter (W4b, F11 profiler → chrome://tracing /
+ * Perfetto). A PURE, deterministic function over recorded
+ * {@link PerformanceFrame}s — no clock reads, no randomness, no I/O — so the
+ * same frames always serialize to byte-identical output (asserted by the unit
+ * test).
+ *
+ * Format (https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU):
+ *  - `M` metadata events name the process and thread.
+ *  - One `X` (complete) event per frame — `ts` at the frame's absolute start,
+ *    `dur` the frame's CPU time — with nested `X` events per phase and per
+ *    system placed at their MEASURED `startMs` offsets inside the frame.
+ *  - One `C` (counter) event per frame carries the render draw/triangle
+ *    counters, so the trace viewer draws them as a graph track.
+ *
+ * All times are microseconds (the format's unit); our profiler measures ms, so
+ * every ms value is × 1000. Every event carries the full key set
+ * (`ph/ts/dur/pid/tid/name/cat`) for uniformity — metadata/counter events
+ * would normally omit `dur`, but a constant `dur: 0` is harmless to the viewer
+ * and lets a consumer read every event without per-`ph` branching.
+ */
+import type { PerformanceFrame } from './performance-profiler';
+export interface ChromeTraceEvent {
+    readonly name: string;
+    readonly cat: string;
+    readonly ph: 'X' | 'M' | 'C';
+    /** Timestamp, microseconds. */
+    readonly ts: number;
+    /** Duration, microseconds (0 for metadata/counter events). */
+    readonly dur: number;
+    readonly pid: number;
+    readonly tid: number;
+    readonly args?: Record<string, unknown>;
+}
+export interface ChromeTraceFile {
+    readonly traceEvents: readonly ChromeTraceEvent[];
+    readonly displayTimeUnit: 'ms';
+    readonly otherData: Record<string, unknown>;
+}
+export interface ChromeTraceOptions {
+    processName: string;
+    threadName: string;
+}
+export declare function buildChromeTrace(frames: readonly PerformanceFrame[], options: ChromeTraceOptions): ChromeTraceFile;
+//# sourceMappingURL=chrome-trace.d.ts.map

package/dist/dev/chrome-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome-trace.d.ts","sourceRoot":"","sources":["../../src/dev/chrome-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,OAAO,EAAE,kBAAkB,GAC1B,eAAe,CA6FjB"}

package/dist/dev/chrome-trace.js

@@ -0,0 +1,114 @@
+/**
+ * Chrome Trace Event Format exporter (W4b, F11 profiler → chrome://tracing /
+ * Perfetto). A PURE, deterministic function over recorded
+ * {@link PerformanceFrame}s — no clock reads, no randomness, no I/O — so the
+ * same frames always serialize to byte-identical output (asserted by the unit
+ * test).
+ *
+ * Format (https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU):
+ *  - `M` metadata events name the process and thread.
+ *  - One `X` (complete) event per frame — `ts` at the frame's absolute start,
+ *    `dur` the frame's CPU time — with nested `X` events per phase and per
+ *    system placed at their MEASURED `startMs` offsets inside the frame.
+ *  - One `C` (counter) event per frame carries the render draw/triangle
+ *    counters, so the trace viewer draws them as a graph track.
+ *
+ * All times are microseconds (the format's unit); our profiler measures ms, so
+ * every ms value is × 1000. Every event carries the full key set
+ * (`ph/ts/dur/pid/tid/name/cat`) for uniformity — metadata/counter events
+ * would normally omit `dur`, but a constant `dur: 0` is harmless to the viewer
+ * and lets a consumer read every event without per-`ph` branching.
+ */
+const PID = 1;
+const TID = 1;
+const MS_TO_US = 1000;
+function ms(value) {
+    return Math.round(value * MS_TO_US);
+}
+export function buildChromeTrace(frames, options) {
+    const events = [];
+    // Metadata: name the process + thread the frames live on.
+    events.push({
+        name: 'process_name',
+        cat: '__metadata',
+        ph: 'M',
+        ts: 0,
+        dur: 0,
+        pid: PID,
+        tid: TID,
+        args: { name: options.processName },
+    });
+    events.push({
+        name: 'thread_name',
+        cat: '__metadata',
+        ph: 'M',
+        ts: 0,
+        dur: 0,
+        pid: PID,
+        tid: TID,
+        args: { name: options.threadName },
+    });
+    for (const frame of frames) {
+        // Absolute frame start (ms): timestamp is the frame's END, cpuMs its span.
+        const frameStartMs = frame.timestamp - frame.cpuMs;
+        const frameStartUs = ms(frameStartMs);
+        events.push({
+            name: `frame ${frame.id}`,
+            cat: 'frame',
+            ph: 'X',
+            ts: frameStartUs,
+            dur: ms(frame.cpuMs),
+            pid: PID,
+            tid: TID,
+            args: {
+                id: frame.id,
+                drawCalls: frame.render.drawCalls,
+                triangles: frame.render.triangles,
+            },
+        });
+        for (const phase of frame.phases) {
+            events.push({
+                name: phase.name,
+                cat: 'phase',
+                ph: 'X',
+                ts: ms(frameStartMs + (phase.startMs ?? 0)),
+                dur: ms(phase.ms),
+                pid: PID,
+                tid: TID,
+            });
+        }
+        for (const system of frame.systems) {
+            events.push({
+                name: system.name,
+                cat: 'system',
+                ph: 'X',
+                ts: ms(frameStartMs + system.startMs),
+                dur: ms(system.ms),
+                pid: PID,
+                tid: TID,
+                args: { phase: system.phase },
+            });
+        }
+        // Counter track: render draw/triangle counts at this frame's start.
+        events.push({
+            name: 'render',
+            cat: 'counter',
+            ph: 'C',
+            ts: frameStartUs,
+            dur: 0,
+            pid: PID,
+            tid: TID,
+            args: { drawCalls: frame.render.drawCalls, triangles: frame.render.triangles },
+        });
+    }
+    return {
+        traceEvents: events,
+        displayTimeUnit: 'ms',
+        otherData: {
+            version: 2,
+            processName: options.processName,
+            threadName: options.threadName,
+            frameCount: frames.length,
+        },
+    };
+}

package/dist/dev/console-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dev-mode console bridge.
+ *
+ * Monkey-patches console.log / warn / error to also broadcast each message
+ * via `window.postMessage`. Any parent frame (IDE, editor, test harness) can
+ * listen for these messages — if nobody is listening they simply go nowhere.
+ *
+ * Also captures unhandled errors and promise rejections.
+ *
+ * Call once, as early as possible in the entry point:
+ *
+ *   import { installConsoleBridge } from '@engine/dev/console-bridge';
+ *   if (import.meta.env.DEV) installConsoleBridge();
+ */
+export interface ConsoleBridgeMessage {
+    type: 'console-bridge';
+    level: 'log' | 'warn' | 'error';
+    message: string;
+    timestamp: number;
+}
+export declare function installConsoleBridge(): void;
+//# sourceMappingURL=console-bridge.d.ts.map

package/dist/dev/console-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-bridge.d.ts","sourceRoot":"","sources":["../../src/dev/console-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AA6BD,wBAAgB,oBAAoB,IAAI,IAAI,CAiC3C"}

package/dist/dev/console-bridge.js

@@ -0,0 +1,71 @@
+/**
+ * Dev-mode console bridge.
+ *
+ * Monkey-patches console.log / warn / error to also broadcast each message
+ * via `window.postMessage`. Any parent frame (IDE, editor, test harness) can
+ * listen for these messages — if nobody is listening they simply go nowhere.
+ *
+ * Also captures unhandled errors and promise rejections.
+ *
+ * Call once, as early as possible in the entry point:
+ *
+ *   import { installConsoleBridge } from '@engine/dev/console-bridge';
+ *   if (import.meta.env.DEV) installConsoleBridge();
+ */
+const LEVELS = ['log', 'warn', 'error'];
+function post(level, message) {
+    const msg = {
+        type: 'console-bridge',
+        level,
+        message,
+        timestamp: Date.now(),
+    };
+    window.postMessage(msg, '*');
+}
+function stringify(args) {
+    return args
+        .map((a) => {
+        if (typeof a === 'string')
+            return a;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(' ');
+}
+let installed = false;
+export function installConsoleBridge() {
+    // Idempotent: a second call must not double-patch console (which would
+    // double-post every message) nor add duplicate window listeners.
+    if (installed)
+        return;
+    installed = true;
+    // Lazy import — avoid hard dep; if logger.ts isn't bundled the flag stays false
+    let getFlag = () => false;
+    import('./logger')
+        .then((m) => {
+        getFlag = () => m._engineLogActive;
+    })
+        .catch(() => { });
+    // Patch console methods
+    for (const level of LEVELS) {
+        const original = console[level].bind(console);
+        console[level] = (...args) => {
+            original(...args);
+            // Skip bridge posting when the engine logger is handling the message
+            // (it posts its own structured 'engine-log' message instead)
+            if (!getFlag())
+                post(level, stringify(args));
+        };
+    }
+    // Capture unhandled errors
+    window.addEventListener('error', (e) => {
+        post('error', e.message || String(e.error));
+    });
+    window.addEventListener('unhandledrejection', (e) => {
+        post('error', `Unhandled promise rejection: ${e.reason}`);
+    });
+}

package/dist/dev/debug-draw.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from 'three';
+/**
+ * Debug drawing utilities for development.
+ *
+ * Draw lines, spheres, boxes, and arrows for visualizing
+ * physics colliders, raycasts, AI paths, etc.
+ *
+ * All debug objects are added to a dedicated group that can be toggled.
+ */
+export declare function createDebugDraw(scene: THREE.Scene): {
+    /** Draw a line between two points */
+    line(from: THREE.Vector3, to: THREE.Vector3, color?: number): THREE.Line<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.LineBasicMaterial, THREE.Object3DEventMap>;
+    /** Draw a wireframe sphere at a position */
+    sphere(center: THREE.Vector3, radius?: number, color?: number): THREE.Mesh<THREE.SphereGeometry, THREE.MeshBasicMaterial, THREE.Object3DEventMap>;
+    /** Draw a wireframe box */
+    box(center: THREE.Vector3, size: THREE.Vector3, color?: number): THREE.Mesh<THREE.BoxGeometry, THREE.MeshBasicMaterial, THREE.Object3DEventMap>;
+    /** Draw an arrow (direction indicator) */
+    arrow(origin: THREE.Vector3, direction: THREE.Vector3, length?: number, color?: number): THREE.ArrowHelper;
+    /** Clear all debug drawings */
+    clear(): void;
+    /** Toggle debug draw visibility */
+    visible: boolean;
+};
+//# sourceMappingURL=debug-draw.d.ts.map

package/dist/dev/debug-draw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-draw.d.ts","sourceRoot":"","sources":["../../src/dev/debug-draw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK;IAM9C,qCAAqC;eAC1B,KAAK,CAAC,OAAO,MAAM,KAAK,CAAC,OAAO;IAQ3C,4CAA4C;mBAC7B,KAAK,CAAC,OAAO;IAS5B,2BAA2B;gBACf,KAAK,CAAC,OAAO,QAAQ,KAAK,CAAC,OAAO;IAS9C,0CAA0C;kBAC5B,KAAK,CAAC,OAAO,aAAa,KAAK,CAAC,OAAO;IAQrD,+BAA+B;;IAgB/B,mCAAmC;aACpB,OAAO;EAQzB"}