@ringozz/godot 4.7.2-614 → 4.7.2-616

package/src/debug.ts

@@ -1,357 +1,357 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import { MouseButton, str, varToStr } from './index.ts';
-import { CanvasItem } from '../gen/classes/CanvasItem.ts';
-import { ClassDB } from '../gen/classes/ClassDB.ts';
-import { Control } from '../gen/classes/Control.ts';
-import { DisplayServer } from '../gen/classes/DisplayServer.ts';
-import { Engine } from '../gen/classes/Engine.ts';
-import { InputEventMouseButton } from '../gen/classes/InputEventMouseButton.ts';
-import { Node } from '../gen/classes/Node.ts';
-import { Node3D } from '../gen/classes/Node3D.ts';
-import { OS } from '../gen/classes/OS.ts';
-import { SceneTree } from '../gen/classes/SceneTree.ts';
-import { Time } from '../gen/classes/Time.ts';
-import type { Vector2 } from '../gen/value-types/Vector2.ts';
-import type { Viewport } from '../gen/classes/Viewport.ts';
-import type { Window } from '../gen/classes/Window.ts';
-
-const tree = Engine.getMainLoop() as SceneTree;
-
-/** Does a snapshot line match a string (case-insensitive substring) or `RegExp` pattern? */
-function matches(pattern: string | RegExp | undefined, line: string): boolean {
-    return !pattern || (pattern instanceof RegExp ? pattern.test(line) : line.toLowerCase().includes(pattern.toLowerCase()));
-}
-
-/**
- * Dump a Godot value or object as a string.
- * Value types (vectors, arrays, dictionaries, …) render via Godot's `str()`.
- * Objects dump via Godot's `var_to_str` — its own property walk + recursion —
- * with the node's `name` prepended when present.
- *
- * @param obj - Any Godot wrapper (Node, Resource, …), value type, or plain value
- */
-export function dumpStr(obj: unknown): string {
-    if (obj == null || typeof obj !== 'object') return String(obj);
-
-    // Value types & heap containers (Vector3, Array, Dictionary, …) have no getClass() —
-    // let Godot's str() render them.
-    if (!(obj as any).getClass) return str(obj as any);
-
-    const dump = varToStr(obj as any);
-    let name: unknown;
-    try { name = (obj as any).name; } catch { name = undefined; }
-    return name === undefined || name === null || name === '' ? dump : `${name}: ${dump}`;
-}
-
-/**
- * Serialize a scene subtree as a tree-formatted string, optionally filtered.
- *
- * Emits one line per node: `Class "name" (N children)`. When `pattern` is a
- * string, only lines containing it (case-insensitive) are kept; a `RegExp`
- * matches against the full line.
- *
- * @param pattern - Optional substring or `RegExp` to filter the lines
- * @param node - Root node to start from (defaults to the scene tree's root Window)
- * @param depth - Max depth (default 99)
- */
-export function snapshot(pattern?: string | RegExp, node?: Node, depth = 99): string {
-    const root = node ?? tree.root;
-    const lines: string[] = [];
-    (function walk(n: Node, d: number, ind: string) {
-        if (d <= 0) return;
-        const count = n.getChildCount();
-        const line = `${ind}${n.getClass()} "${n.name}" (${count} children)`;
-        if (matches(pattern, line)) lines.push(line);
-        for (let i = 0; i < count; i++) {
-            const c = n.getChild(i);
-            if (c) walk(c as Node, d - 1, ind + '  ');
-        }
-    })(root, depth, '');
-    return lines.join('\n');
-}
-
-/**
- * Resolve a node from the scene root by absolute NodePath (`/root/...`) or
- * name glob (`findChild`). Returns `null` when not found.
- */
-function resolveNode(path: string, root: Window): Node | null {
-    if (path.startsWith('/')) return root.getNode(path);
-    return root.findChild(path, true, false);
-}
-
-/**
- * Resolve a node by path (absolute NodePath or name glob) from the scene root
- * and dump it via {@link dumpStr}.
- *
- * @param path - An absolute NodePath like `/root/Box`, or a `findChild` name/glob pattern
- */
-export function inspect(path: string): string | null {
-    const node = resolveNode(path, tree.root);
-    return node ? dumpStr(node) : null;
-}
-
-/**
- * Synthesize a left-click at the center of a {@link Control} matched by `path`.
- *
- * Press and release are pushed through `Window.pushInput` (the GUI-routing
- * path — `Input.parseInputEvent` doesn't reliably reach `Control.guiInput` on
- * the wasm build). Positions are in device space (logical × `contentScaleFactor`).
- *
- * @param path - An absolute NodePath like `/root/...`, or a `findChild` name/glob pattern
- * @returns The node's `dumpStr`, or `null` if not found or not a `Control`
- */
-export function click(path: string): string | null {
-    const root = tree.root;
-    const node = resolveNode(path, root);
-    if (!(node instanceof Control)) return null;
-    const rect = node.getGlobalRect();
-    const scale = root.contentScaleFactor;
-    const position: Vector2 = [
-        (rect[0] + rect[2] / 2) * scale,
-        (rect[1] + rect[3] / 2) * scale,
-    ];
-    const press = (down: boolean) => {
-        const event = new InputEventMouseButton();
-        event.position = position;
-        event.globalPosition = position;
-        event.buttonIndex = MouseButton.MOUSE_BUTTON_LEFT;
-        event.pressed = down;
-        root.pushInput(event);
-    };
-    press(true);
-    setTimeout(() => press(false), 50);
-    return dumpStr(node);
-}
-
-/**
- * Enumerate nodes in the scene by name pattern and/or class, in tree order.
- *
- * @param pattern - Name glob matched by `findChildren` (default `"*"`)
- * @param type - Class name to filter by, e.g. `"RigidBody3D"` (default `""` = any)
- * @param node - Root node to search under (defaults to the scene tree's root Window)
- */
-export function find(pattern = '*', type = '', node?: Node): Node[] {
-    const root = node ?? tree.root;
-    return [...root.findChildren(pattern, type, true, false)];
-}
-
-/**
- * Run `gc()` and report how much heap was freed.
- * Requires the `--expose-gc` Node.js flag.
- */
-export function gc(): string {
-    const before = globalThis.process?.memoryUsage?.().heapUsed;
-    if (globalThis.Bun)
-        globalThis.Bun.gc(true);
-    else if (globalThis.gc)
-        globalThis.gc({ type: 'major', execution: 'sync' });
-    else
-        return 'gc() unavailable — need --expose-gc';
-
-    const after = globalThis.process?.memoryUsage?.().heapUsed;
-    const freed = typeof before === 'number' && typeof after === 'number' ? (before - after) / 1024 : 0;
-    return `GC: freed ${freed.toFixed(0)} KB`;
-}
-
-/**
- * `DOMRect` is not a global in Bun (desktop), but `getBoundingClientRect()`
- * constructs one. Install a minimal spec-compatible polyfill on desktop so the
- * helper works identically on desktop and web (browsers already define it).
- */
-function ensureDOMRect(): void {
-    if (typeof (globalThis as any).DOMRect !== 'undefined') return;
-    (globalThis as any).DOMRect = class DOMRect {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        constructor(x = 0, y = 0, width = 0, height = 0) {
-            this.x = x;
-            this.y = y;
-            this.width = width;
-            this.height = height;
-        }
-        get left() { return this.x; }
-        get top() { return this.y; }
-        get right() { return this.x + this.width; }
-        get bottom() { return this.y + this.height; }
-        toJSON() { return { x: this.x, y: this.y, width: this.width, height: this.height }; }
-    };
-}
-
-type Push = (x: number, y: number) => void;
-type BoundsCollect = (node: any, push: Push, viewport: Viewport) => void;
-
-/** Affine 2D point mapper from a transform's basis/origin, optionally scaled. */
-function makeAffine(t: any, scale = 1): (x: number, y: number) => [number, number] {
-    const [tx, ty, to] = t;
-    const tox = to[0], toy = to[1];
-    const txx = tx[0], txy = tx[1];
-    const tyx = ty[0], tyy = ty[1];
-    return (x, y) => [(tox + txx * x + tyx * y) * scale, (toy + txy * x + tyy * y) * scale];
-}
-
-/**
- * Axis-aligned 2D bounds accumulator in CSS pixels. Non-finite points (e.g.
- * geometry behind the camera) are dropped; `rect()` is `null` when no point
- * was added.
- */
-function cssBounds(): { add(x: number, y: number): void; rect(): [number, number, number, number] | null } {
-    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-    let found = false;
-    return {
-        add(x, y) {
-            if (!Number.isFinite(x) || !Number.isFinite(y)) return;
-            if (x < minX) minX = x; if (y < minY) minY = y;
-            if (x > maxX) maxX = x; if (y > maxY) maxY = y;
-            found = true;
-        },
-        rect() {
-            return found ? [minX, minY, maxX - minX, maxY - minY] : null;
-        },
-    };
-}
-
-/** World-space AABB (min, max) of a local AABB under its global transform, or `null` when degenerate. */
-function worldAabb(aabb: any, gt: any): [number, number, number, number, number, number] | null {
-    const [position, size] = aabb;
-    const [bx, by, bz, origin] = gt;
-    if (size[0] === 0 && size[1] === 0 && size[2] === 0) return null;
-    const cx = position[0] + size[0] / 2;
-    const cy = position[1] + size[1] / 2;
-    const cz = position[2] + size[2] / 2;
-    const ex = Math.hypot(bx[0], bx[1], bx[2]) * size[0] / 2;
-    const ey = Math.hypot(by[0], by[1], by[2]) * size[1] / 2;
-    const ez = Math.hypot(bz[0], bz[1], bz[2]) * size[2] / 2;
-    const ox = origin[0], oy = origin[1], oz = origin[2];
-    const wx = ox + bx[0] * cx + by[0] * cy + bz[0] * cz;
-    const wy = oy + bx[1] * cx + by[1] * cy + bz[1] * cz;
-    const wz = oz + bx[2] * cx + by[2] * cy + bz[2] * cz;
-    return [wx - ex, wy - ey, wz - ez, wx + ex, wy + ey, wz + ez];
-}
-
-/**
- * World-space AABB of a node's visual content: the union of its own AABB (when
- * it is a `VisualInstance3D`) and every descendant `VisualInstance3D`'s, each in
- * its own global transform — mirrors the editor's `_calculate_spatial_bounds`.
- * Returns `null` when there is no non-degenerate visual.
- */
-function worldBounds(node: Node3D): [number, number, number, number, number, number] | null {
-    let minX = Infinity, minY = Infinity, minZ = Infinity;
-    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
-    const add = (aabb: any, gt: any) => {
-        const box = worldAabb(aabb, gt);
-        if (!box) return;
-        if (box[0] < minX) minX = box[0]; if (box[3] > maxX) maxX = box[3];
-        if (box[1] < minY) minY = box[1]; if (box[4] > maxY) maxY = box[4];
-        if (box[2] < minZ) minZ = box[2]; if (box[5] > maxZ) maxZ = box[5];
-    };
-    if (typeof (node as any).getAabb === 'function') {
-        add((node as any).getAabb(), node.globalTransform);
-    }
-    for (const child of node.findChildren('*', 'VisualInstance3D', true, false) as unknown as any[]) {
-        if (child && typeof child.getAabb === 'function') {
-            add(child.getAabb(), child.globalTransform);
-        }
-    }
-    return minX === Infinity ? null : [minX, minY, minZ, maxX, maxY, maxZ];
-}
-
-/**
- * Compute a node's bounding rect in CSS pixels. The callback pushes points in
- * viewport logical units; they're mapped through the viewport's screen transform
- * (content scale, stretch, SubViewport/child-window placement), then divided by
- * screenGetScale to reach CSS pixels. Never throws: React DevTools calls this on
- * every commit and must not see a throw (e.g. a wrapper freed by an unmount).
- */
-function boundsForViewport(node: Node, collect: (push: Push, viewport: Viewport) => void): DOMRect | null {
-    try {
-        const viewport = node.getViewport();
-        if (!viewport) return null;
-        const xform = makeAffine(viewport.getScreenTransform(), 1 / DisplayServer.screenGetScale());
-        const bounds = cssBounds();
-        collect((x, y) => bounds.add(...xform(x, y)), viewport);
-        const r = bounds.rect();
-        return r ? new DOMRect(r[0], r[1], r[2], r[3]) : null;
-    } catch {
-        return null;
-    }
-}
-
-/** Install `getBoundingClientRect` on a node prototype. */
-function defineBoundingClientRect(proto: object, collect: BoundsCollect): void {
-    Object.defineProperty(proto, 'getBoundingClientRect', {
-        configurable: true,
-        value(this: Node): DOMRect | null {
-            return boundsForViewport(this, (push, viewport) => collect(this, push, viewport));
-        },
-    });
-}
-
-/** Push the four corners of an axis-aligned rect through `emit`. */
-function pushRect(emit: (x: number, y: number) => void, x0: number, y0: number, x1: number, y1: number): void {
-    for (const px of [x0, x1]) {
-        for (const py of [y0, y1]) {
-            emit(px, py);
-        }
-    }
-}
-
-const canvasItemBounds: BoundsCollect = (node, push) => {
-    if (node instanceof Control) {
-        const [x, y, w, h] = node.getGlobalRect();
-        pushRect(push, x, y, x + w, y + h);
-        return;
-    }
-    if (typeof node.getRect !== 'function') return;
-    const [x, y, w, h] = node.getRect() as [number, number, number, number];
-    const xform = makeAffine(node.getScreenTransform());
-    pushRect((px, py) => push(...xform(px, py)), x, y, x + w, y + h);
-};
-
-const node3dBounds: BoundsCollect = (node, push, viewport) => {
-    const camera = viewport.getCamera3d();
-    if (!camera) return;
-    const box = worldBounds(node);
-    if (!box) return;
-    const [minX, minY, minZ, maxX, maxY, maxZ] = box;
-    for (let i = 0; i < 8; i++) {
-        const s = camera.unprojectPosition([
-            i & 1 ? maxX : minX,
-            i & 2 ? maxY : minY,
-            i & 4 ? maxZ : minZ,
-        ]);
-        push(s[0], s[1]);
-    }
-};
-
-/**
- * Bootstrap the debugging environment.
- *
- * - Exposes common singletons (`Engine`, `OS`, `ClassDB`, `Time`) and all
- *   debug utility functions on `globalThis.$` so they're reachable from
- *   breakpoints in any module.
- * - Registers an `uncaughtException` handler that logs but keeps the process
- *   alive for interactive debugging.
- * - Polyfills `DOMRect` (needed by `getBoundingClientRect()` on desktop).
- */
-export function initDebug(): void {
-    globalThis.process?.on?.('uncaughtException', (err, origin) => {
-        console.error(`\n✗ ${origin}:`, err.stack);
-    });
-
-    ensureDOMRect();
-    defineBoundingClientRect(CanvasItem.prototype, canvasItemBounds);
-    defineBoundingClientRect(Node3D.prototype, node3dBounds);
-
-    (globalThis as any).$ = {
-        Engine, OS, ClassDB, Time,
-        dumpStr, snapshot, inspect, click, find, gc,
-        get tree(): SceneTree { return tree; },
-        get paused(): boolean { return tree.paused; },
-        set paused(v: boolean) { tree.paused = v; },
-    };
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { MouseButton, str, varToStr } from './index.ts';
+import { CanvasItem } from '../gen/classes/CanvasItem.ts';
+import { ClassDB } from '../gen/classes/ClassDB.ts';
+import { Control } from '../gen/classes/Control.ts';
+import { DisplayServer } from '../gen/classes/DisplayServer.ts';
+import { Engine } from '../gen/classes/Engine.ts';
+import { InputEventMouseButton } from '../gen/classes/InputEventMouseButton.ts';
+import { Node } from '../gen/classes/Node.ts';
+import { Node3D } from '../gen/classes/Node3D.ts';
+import { OS } from '../gen/classes/OS.ts';
+import { SceneTree } from '../gen/classes/SceneTree.ts';
+import { Time } from '../gen/classes/Time.ts';
+import type { Vector2 } from '../gen/value-types/Vector2.ts';
+import type { Viewport } from '../gen/classes/Viewport.ts';
+import type { Window } from '../gen/classes/Window.ts';
+
+const tree = Engine.getMainLoop() as SceneTree;
+
+/** Does a snapshot line match a string (case-insensitive substring) or `RegExp` pattern? */
+function matches(pattern: string | RegExp | undefined, line: string): boolean {
+    return !pattern || (pattern instanceof RegExp ? pattern.test(line) : line.toLowerCase().includes(pattern.toLowerCase()));
+}
+
+/**
+ * Dump a Godot value or object as a string.
+ * Value types (vectors, arrays, dictionaries, …) render via Godot's `str()`.
+ * Objects dump via Godot's `var_to_str` — its own property walk + recursion —
+ * with the node's `name` prepended when present.
+ *
+ * @param obj - Any Godot wrapper (Node, Resource, …), value type, or plain value
+ */
+export function dumpStr(obj: unknown): string {
+    if (obj == null || typeof obj !== 'object') return String(obj);
+
+    // Value types & heap containers (Vector3, Array, Dictionary, …) have no getClass() —
+    // let Godot's str() render them.
+    if (!(obj as any).getClass) return str(obj as any);
+
+    const dump = varToStr(obj as any);
+    let name: unknown;
+    try { name = (obj as any).name; } catch { name = undefined; }
+    return name === undefined || name === null || name === '' ? dump : `${name}: ${dump}`;
+}
+
+/**
+ * Serialize a scene subtree as a tree-formatted string, optionally filtered.
+ *
+ * Emits one line per node: `Class "name" (N children)`. When `pattern` is a
+ * string, only lines containing it (case-insensitive) are kept; a `RegExp`
+ * matches against the full line.
+ *
+ * @param pattern - Optional substring or `RegExp` to filter the lines
+ * @param node - Root node to start from (defaults to the scene tree's root Window)
+ * @param depth - Max depth (default 99)
+ */
+export function snapshot(pattern?: string | RegExp, node?: Node, depth = 99): string {
+    const root = node ?? tree.root;
+    const lines: string[] = [];
+    (function walk(n: Node, d: number, ind: string) {
+        if (d <= 0) return;
+        const count = n.getChildCount();
+        const line = `${ind}${n.getClass()} "${n.name}" (${count} children)`;
+        if (matches(pattern, line)) lines.push(line);
+        for (let i = 0; i < count; i++) {
+            const c = n.getChild(i);
+            if (c) walk(c as Node, d - 1, ind + '  ');
+        }
+    })(root, depth, '');
+    return lines.join('\n');
+}
+
+/**
+ * Resolve a node from the scene root by absolute NodePath (`/root/...`) or
+ * name glob (`findChild`). Returns `null` when not found.
+ */
+function resolveNode(path: string, root: Window): Node | null {
+    if (path.startsWith('/')) return root.getNode(path);
+    return root.findChild(path, true, false);
+}
+
+/**
+ * Resolve a node by path (absolute NodePath or name glob) from the scene root
+ * and dump it via {@link dumpStr}.
+ *
+ * @param path - An absolute NodePath like `/root/Box`, or a `findChild` name/glob pattern
+ */
+export function inspect(path: string): string | null {
+    const node = resolveNode(path, tree.root);
+    return node ? dumpStr(node) : null;
+}
+
+/**
+ * Synthesize a left-click at the center of a {@link Control} matched by `path`.
+ *
+ * Press and release are pushed through `Window.pushInput` (the GUI-routing
+ * path — `Input.parseInputEvent` doesn't reliably reach `Control.guiInput` on
+ * the wasm build). Positions are in device space (logical × `contentScaleFactor`).
+ *
+ * @param path - An absolute NodePath like `/root/...`, or a `findChild` name/glob pattern
+ * @returns The node's `dumpStr`, or `null` if not found or not a `Control`
+ */
+export function click(path: string): string | null {
+    const root = tree.root;
+    const node = resolveNode(path, root);
+    if (!(node instanceof Control)) return null;
+    const rect = node.getGlobalRect();
+    const scale = root.contentScaleFactor;
+    const position: Vector2 = [
+        (rect[0] + rect[2] / 2) * scale,
+        (rect[1] + rect[3] / 2) * scale,
+    ];
+    const press = (down: boolean) => {
+        const event = new InputEventMouseButton();
+        event.position = position;
+        event.globalPosition = position;
+        event.buttonIndex = MouseButton.MOUSE_BUTTON_LEFT;
+        event.pressed = down;
+        root.pushInput(event);
+    };
+    press(true);
+    setTimeout(() => press(false), 50);
+    return dumpStr(node);
+}
+
+/**
+ * Enumerate nodes in the scene by name pattern and/or class, in tree order.
+ *
+ * @param pattern - Name glob matched by `findChildren` (default `"*"`)
+ * @param type - Class name to filter by, e.g. `"RigidBody3D"` (default `""` = any)
+ * @param node - Root node to search under (defaults to the scene tree's root Window)
+ */
+export function find(pattern = '*', type = '', node?: Node): Node[] {
+    const root = node ?? tree.root;
+    return [...root.findChildren(pattern, type, true, false)];
+}
+
+/**
+ * Run `gc()` and report how much heap was freed.
+ * Requires the `--expose-gc` Node.js flag.
+ */
+export function gc(): string {
+    const before = globalThis.process?.memoryUsage?.().heapUsed;
+    if (globalThis.Bun)
+        globalThis.Bun.gc(true);
+    else if (globalThis.gc)
+        globalThis.gc({ type: 'major', execution: 'sync' });
+    else
+        return 'gc() unavailable — need --expose-gc';
+
+    const after = globalThis.process?.memoryUsage?.().heapUsed;
+    const freed = typeof before === 'number' && typeof after === 'number' ? (before - after) / 1024 : 0;
+    return `GC: freed ${freed.toFixed(0)} KB`;
+}
+
+/**
+ * `DOMRect` is not a global in Bun (desktop), but `getBoundingClientRect()`
+ * constructs one. Install a minimal spec-compatible polyfill on desktop so the
+ * helper works identically on desktop and web (browsers already define it).
+ */
+function ensureDOMRect(): void {
+    if (typeof (globalThis as any).DOMRect !== 'undefined') return;
+    (globalThis as any).DOMRect = class DOMRect {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        constructor(x = 0, y = 0, width = 0, height = 0) {
+            this.x = x;
+            this.y = y;
+            this.width = width;
+            this.height = height;
+        }
+        get left() { return this.x; }
+        get top() { return this.y; }
+        get right() { return this.x + this.width; }
+        get bottom() { return this.y + this.height; }
+        toJSON() { return { x: this.x, y: this.y, width: this.width, height: this.height }; }
+    };
+}
+
+type Push = (x: number, y: number) => void;
+type BoundsCollect = (node: any, push: Push, viewport: Viewport) => void;
+
+/** Affine 2D point mapper from a transform's basis/origin, optionally scaled. */
+function makeAffine(t: any, scale = 1): (x: number, y: number) => [number, number] {
+    const [tx, ty, to] = t;
+    const tox = to[0], toy = to[1];
+    const txx = tx[0], txy = tx[1];
+    const tyx = ty[0], tyy = ty[1];
+    return (x, y) => [(tox + txx * x + tyx * y) * scale, (toy + txy * x + tyy * y) * scale];
+}
+
+/**
+ * Axis-aligned 2D bounds accumulator in CSS pixels. Non-finite points (e.g.
+ * geometry behind the camera) are dropped; `rect()` is `null` when no point
+ * was added.
+ */
+function cssBounds(): { add(x: number, y: number): void; rect(): [number, number, number, number] | null } {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    let found = false;
+    return {
+        add(x, y) {
+            if (!Number.isFinite(x) || !Number.isFinite(y)) return;
+            if (x < minX) minX = x; if (y < minY) minY = y;
+            if (x > maxX) maxX = x; if (y > maxY) maxY = y;
+            found = true;
+        },
+        rect() {
+            return found ? [minX, minY, maxX - minX, maxY - minY] : null;
+        },
+    };
+}
+
+/** World-space AABB (min, max) of a local AABB under its global transform, or `null` when degenerate. */
+function worldAabb(aabb: any, gt: any): [number, number, number, number, number, number] | null {
+    const [position, size] = aabb;
+    const [bx, by, bz, origin] = gt;
+    if (size[0] === 0 && size[1] === 0 && size[2] === 0) return null;
+    const cx = position[0] + size[0] / 2;
+    const cy = position[1] + size[1] / 2;
+    const cz = position[2] + size[2] / 2;
+    const ex = Math.hypot(bx[0], bx[1], bx[2]) * size[0] / 2;
+    const ey = Math.hypot(by[0], by[1], by[2]) * size[1] / 2;
+    const ez = Math.hypot(bz[0], bz[1], bz[2]) * size[2] / 2;
+    const ox = origin[0], oy = origin[1], oz = origin[2];
+    const wx = ox + bx[0] * cx + by[0] * cy + bz[0] * cz;
+    const wy = oy + bx[1] * cx + by[1] * cy + bz[1] * cz;
+    const wz = oz + bx[2] * cx + by[2] * cy + bz[2] * cz;
+    return [wx - ex, wy - ey, wz - ez, wx + ex, wy + ey, wz + ez];
+}
+
+/**
+ * World-space AABB of a node's visual content: the union of its own AABB (when
+ * it is a `VisualInstance3D`) and every descendant `VisualInstance3D`'s, each in
+ * its own global transform — mirrors the editor's `_calculate_spatial_bounds`.
+ * Returns `null` when there is no non-degenerate visual.
+ */
+function worldBounds(node: Node3D): [number, number, number, number, number, number] | null {
+    let minX = Infinity, minY = Infinity, minZ = Infinity;
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    const add = (aabb: any, gt: any) => {
+        const box = worldAabb(aabb, gt);
+        if (!box) return;
+        if (box[0] < minX) minX = box[0]; if (box[3] > maxX) maxX = box[3];
+        if (box[1] < minY) minY = box[1]; if (box[4] > maxY) maxY = box[4];
+        if (box[2] < minZ) minZ = box[2]; if (box[5] > maxZ) maxZ = box[5];
+    };
+    if (typeof (node as any).getAabb === 'function') {
+        add((node as any).getAabb(), node.globalTransform);
+    }
+    for (const child of node.findChildren('*', 'VisualInstance3D', true, false) as unknown as any[]) {
+        if (child && typeof child.getAabb === 'function') {
+            add(child.getAabb(), child.globalTransform);
+        }
+    }
+    return minX === Infinity ? null : [minX, minY, minZ, maxX, maxY, maxZ];
+}
+
+/**
+ * Compute a node's bounding rect in CSS pixels. The callback pushes points in
+ * viewport logical units; they're mapped through the viewport's screen transform
+ * (content scale, stretch, SubViewport/child-window placement), then divided by
+ * screenGetScale to reach CSS pixels. Never throws: React DevTools calls this on
+ * every commit and must not see a throw (e.g. a wrapper freed by an unmount).
+ */
+function boundsForViewport(node: Node, collect: (push: Push, viewport: Viewport) => void): DOMRect | null {
+    try {
+        const viewport = node.getViewport();
+        if (!viewport) return null;
+        const xform = makeAffine(viewport.getScreenTransform(), 1 / DisplayServer.screenGetScale());
+        const bounds = cssBounds();
+        collect((x, y) => bounds.add(...xform(x, y)), viewport);
+        const r = bounds.rect();
+        return r ? new DOMRect(r[0], r[1], r[2], r[3]) : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Install `getBoundingClientRect` on a node prototype. */
+function defineBoundingClientRect(proto: object, collect: BoundsCollect): void {
+    Object.defineProperty(proto, 'getBoundingClientRect', {
+        configurable: true,
+        value(this: Node): DOMRect | null {
+            return boundsForViewport(this, (push, viewport) => collect(this, push, viewport));
+        },
+    });
+}
+
+/** Push the four corners of an axis-aligned rect through `emit`. */
+function pushRect(emit: (x: number, y: number) => void, x0: number, y0: number, x1: number, y1: number): void {
+    for (const px of [x0, x1]) {
+        for (const py of [y0, y1]) {
+            emit(px, py);
+        }
+    }
+}
+
+const canvasItemBounds: BoundsCollect = (node, push) => {
+    if (node instanceof Control) {
+        const [x, y, w, h] = node.getGlobalRect();
+        pushRect(push, x, y, x + w, y + h);
+        return;
+    }
+    if (typeof node.getRect !== 'function') return;
+    const [x, y, w, h] = node.getRect() as [number, number, number, number];
+    const xform = makeAffine(node.getScreenTransform());
+    pushRect((px, py) => push(...xform(px, py)), x, y, x + w, y + h);
+};
+
+const node3dBounds: BoundsCollect = (node, push, viewport) => {
+    const camera = viewport.getCamera3d();
+    if (!camera) return;
+    const box = worldBounds(node);
+    if (!box) return;
+    const [minX, minY, minZ, maxX, maxY, maxZ] = box;
+    for (let i = 0; i < 8; i++) {
+        const s = camera.unprojectPosition([
+            i & 1 ? maxX : minX,
+            i & 2 ? maxY : minY,
+            i & 4 ? maxZ : minZ,
+        ]);
+        push(s[0], s[1]);
+    }
+};
+
+/**
+ * Bootstrap the debugging environment.
+ *
+ * - Exposes common singletons (`Engine`, `OS`, `ClassDB`, `Time`) and all
+ *   debug utility functions on `globalThis.$` so they're reachable from
+ *   breakpoints in any module.
+ * - Registers an `uncaughtException` handler that logs but keeps the process
+ *   alive for interactive debugging.
+ * - Polyfills `DOMRect` (needed by `getBoundingClientRect()` on desktop).
+ */
+export function initDebug(): void {
+    globalThis.process?.on?.('uncaughtException', (err, origin) => {
+        console.error(`\n✗ ${origin}:`, err.stack);
+    });
+
+    ensureDOMRect();
+    defineBoundingClientRect(CanvasItem.prototype, canvasItemBounds);
+    defineBoundingClientRect(Node3D.prototype, node3dBounds);
+
+    (globalThis as any).$ = {
+        Engine, OS, ClassDB, Time,
+        dumpStr, snapshot, inspect, click, find, gc,
+        get tree(): SceneTree { return tree; },
+        get paused(): boolean { return tree.paused; },
+        set paused(v: boolean) { tree.paused = v; },
+    };
+}