@ringozz/godot 4.7.1-8 → 4.7.2-570

package/src/debug.ts

@@ -1,236 +1,354 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-import { Rect2, str, varToStr, Vector3 } 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 { Node } from '../gen/classes/Node.ts';
-import { Node3D } from '../gen/classes/Node3D.ts';
-import { OS } from '../gen/classes/OS.ts';
-import { Time } from '../gen/classes/Time.ts';
-
-/**
- * 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.
- *
- * @param node - Root node to start from
- * @param depth - Max depth (default 99)
- */
-export function dumpTreeStr(node: Node, depth = 99): string {
-    const lines: string[] = [];
-    (function walk(n: Node, d: number, ind: string) {
-        if (d <= 0) return;
-        lines.push(`${ind}${n.getClass()} "${n.name}" (${n.getChildCount()} children)`);
-        for (let i = 0; i < n.getChildCount(); i++) {
-            const c = n.getChild(i);
-            if (c) walk(c as Node, d - 1, ind + '  ');
-        }
-    })(node, depth, '');
-    return lines.join('\n');
-}
-
-/**
- * Return a snapshot of engine runtime stats as a formatted string.
- *
- * Includes process frames, FPS, physics frames, node count, time scale,
- * and main-loop class. Never throws: `Engine.getMainLoop()` can be null or
- * throw while the engine is starting/stopping, in which case those rows show `N/A`.
- */
-export function statsStr(): string {
-    let tree: any = null;
-    try { tree = Engine.getMainLoop(); } catch { tree = null; }
-    return [
-        `Frames:     ${Engine.getProcessFrames()}`,
-        `FPS:        ${Engine.getFramesPerSecond()}`,
-        `Physics:    ${Engine.getPhysicsFrames()}`,
-        `Nodes:      ${tree?.getNodeCount?.() ?? 'N/A'}`,
-        `Time scale: ${Engine.timeScale}`,
-        `Main loop:  ${tree ? tree.getClass() : 'N/A'}`,
-    ].join('\n');
-}
-
-/**
- * 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 }; }
-    };
-}
-
-/**
- * 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();
-
-    Object.defineProperty(CanvasItem.prototype, 'getBoundingClientRect', {
-        configurable: true,
-        value(this: CanvasItem): DOMRect | null {
-            const scale = DisplayServer.screenGetScale();
-            if (this instanceof Control) {
-                const rc = (this as Control).getGlobalRect();
-                return new DOMRect(
-                    rc.position.x / scale, rc.position.y / scale,
-                    rc.size.x / scale, rc.size.y / scale,
-                );
-            }
-
-            if (typeof (this as any).getRect !== 'function') return null;
-
-            const rect = (this as any).getRect() as Rect2;
-            const t = this.getScreenTransform();
-
-            const pos = rect.position;
-            const sz = rect.size;
-            const tx = t.x;
-            const ty = t.y;
-            const to = t.origin;
-
-            const x0 = pos.x, y0 = pos.y;
-            const x1 = x0 + sz.x, y1 = y0 + sz.y;
-            const txx = tx.x, txy = tx.y;
-            const tyx = ty.x, tyy = ty.y;
-            const tox = to.x, toy = to.y;
-
-            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-            const accum = (px: number, py: number) => {
-                if (px < minX) minX = px; if (py < minY) minY = py;
-                if (px > maxX) maxX = px; if (py > maxY) maxY = py;
-            };
-
-            accum(txx * x0 + tyx * y0 + tox, txy * x0 + tyy * y0 + toy);
-            accum(txx * x1 + tyx * y0 + tox, txy * x1 + tyy * y0 + toy);
-            accum(txx * x0 + tyx * y1 + tox, txy * x0 + tyy * y1 + toy);
-            accum(txx * x1 + tyx * y1 + tox, txy * x1 + tyy * y1 + toy);
-
-            return new DOMRect(
-                minX / scale, minY / scale,
-                (maxX - minX) / scale, (maxY - minY) / scale,
-            );
-        },
-    });
-
-    Object.defineProperty(Node3D.prototype, 'getBoundingClientRect', {
-        configurable: true,
-        value(this: Node3D): DOMRect | null {
-            if (typeof (this as any).getAabb !== 'function') return null;
-
-            const aabb = (this as any).getAabb();
-            const gt = this.globalTransform;
-            const viewport = this.getViewport();
-            if (!viewport) return null;
-            const camera = viewport.getCamera3d();
-            if (!camera) return null;
-            const scale = DisplayServer.screenGetScale();
-
-            const b = gt.basis;
-            const bx = b.x, by = b.y, bz = b.z;
-            const o = gt.origin;
-            const p = aabb.position, e = aabb.end;
-
-            const [px, py, pz] = [p.x, p.y, p.z];
-            const [ex, ey, ez] = [e.x, e.y, e.z];
-            const [bxx, bxy, bxz] = [bx.x, bx.y, bx.z];
-            const [byx, byy, byz] = [by.x, by.y, by.z];
-            const [bzx, bzy, bzz] = [bz.x, bz.y, bz.z];
-            const [ox, oy, oz] = [o.x, o.y, o.z];
-
-            const corners = [
-                [px, py, pz], [ex, py, pz], [px, ey, pz], [ex, ey, pz],
-                [px, py, ez], [ex, py, ez], [px, ey, ez], [ex, ey, ez],
-            ];
-
-            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-
-            for (const [cx, cy, cz] of corners) {
-                const wx = bxx * cx + byx * cy + bzx * cz + ox;
-                const wy = bxy * cx + byy * cy + bzy * cz + oy;
-                const wz = bxz * cx + byz * cy + bzz * cz + oz;
-                const s = camera.unprojectPosition(new Vector3(wx, wy, wz));
-                if (s.x < minX) minX = s.x; if (s.y < minY) minY = s.y;
-                if (s.x > maxX) maxX = s.x; if (s.y > maxY) maxY = s.y;
-            }
-
-            return new DOMRect(
-                minX / scale, minY / scale,
-                (maxX - minX) / scale, (maxY - minY) / scale,
-            );
-        },
-    });
-
-    (globalThis as any).$ = {
-        Engine, OS, ClassDB, Time,
-        dumpStr, dumpTreeStr, statsStr, gc,
-    };
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { MouseButton, Rect2, str, varToStr, Vector2, Vector3 } 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 { 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 = new Vector2(
+        (rect.position.x + rect.size.x / 2) * scale,
+        (rect.position.y + rect.size.y / 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 tox = t.origin.x, toy = t.origin.y;
+    const txx = t.x.x, txy = t.x.y;
+    const tyx = t.y.x, tyy = t.y.y;
+    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 {
+    if (aabb.size.x === 0 && aabb.size.y === 0 && aabb.size.z === 0) return null;
+    const bx = gt.basis.x, by = gt.basis.y, bz = gt.basis.z;
+    const cx = aabb.position.x + aabb.size.x / 2;
+    const cy = aabb.position.y + aabb.size.y / 2;
+    const cz = aabb.position.z + aabb.size.z / 2;
+    const ex = Math.hypot(bx.x, bx.y, bx.z) * aabb.size.x / 2;
+    const ey = Math.hypot(by.x, by.y, by.z) * aabb.size.y / 2;
+    const ez = Math.hypot(bz.x, bz.y, bz.z) * aabb.size.z / 2;
+    const ox = gt.origin.x, oy = gt.origin.y, oz = gt.origin.z;
+    const wx = ox + bx.x * cx + by.x * cy + bz.x * cz;
+    const wy = oy + bx.y * cx + by.y * cy + bz.y * cz;
+    const wz = oz + bx.z * cx + by.z * cy + bz.z * 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 rc = node.getGlobalRect();
+        pushRect(push, rc.position.x, rc.position.y, rc.position.x + rc.size.x, rc.position.y + rc.size.y);
+        return;
+    }
+    if (typeof node.getRect !== 'function') return;
+    const rect = node.getRect() as Rect2;
+    const xform = makeAffine(node.getScreenTransform());
+    pushRect((px, py) => push(...xform(px, py)), rect.position.x, rect.position.y, rect.position.x + rect.size.x, rect.position.y + rect.size.y);
+};
+
+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(new Vector3(
+            i & 1 ? maxX : minX,
+            i & 2 ? maxY : minY,
+            i & 4 ? maxZ : minZ,
+        ));
+        push(s.x, s.y);
+    }
+};
+
+/**
+ * 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; },
+    };
+}