@ringozz/godot 4.7.1-9 → 4.7.2-579

package/gen/classes/Window.ts

@@ -542,7 +542,7 @@ export class Window extends Viewport {
      * **Note:** This property is implemented on Linux (X11), macOS and Windows.
      */
     get mousePassthroughPolygon(): PackedVector2Array { return _C(this, 5590) as PackedVector2Array; }
-    set mousePassthroughPolygon(v: PackedVector2Array) { _C(this, 12096, v); }
+    set mousePassthroughPolygon(v: PackedVector2Array | Vector2[]) { _C(this, 12096, v); }
 
     /**
      * If `true`, the window is visible.

package/gen/classes/XRFaceTracker.ts

@@ -26,7 +26,7 @@ export class XRFaceTracker extends XRTracker {
      * The array of face blend shape weights with indices corresponding to the {@link BlendShapeEntry} enum.
      */
     get blendShapes(): PackedFloat32Array { return _C(this, 3942) as PackedFloat32Array; }
-    set blendShapes(v: PackedFloat32Array) { _C(this, 10685, v); }
+    set blendShapes(v: PackedFloat32Array | number[]) { _C(this, 10685, v); }
 
     static readonly name = _R(980, XRFaceTracker);
 }

package/gen/heap-types/GodotArray.ts

@@ -6,7 +6,10 @@ import type { Callable, StringName, Variant } from './index.ts';
 
 /** Godot's Array type — lazy, indexed container. */
 export class GodotArray<T = any> extends GodotVar implements Iterable<T> {
-    constructor(...args: any[]) { super(28, ...args); }
+    constructor(from?: Iterable<T>) {
+        super(28);
+        if (from != null) for (const x of from) _C(this, 9630, x);
+    }
 
     get length(): number { return _C(this, 13608) as number; }
 

package/gen/heap-types/GodotDictionary.ts

@@ -6,7 +6,12 @@ import type { GodotArray, StringName, Variant } from './index.ts';
 
 /** Godot's Dictionary type — lazy, keyed container. */
 export class GodotDictionary<K = any, V = any> extends GodotVar implements Iterable<[K, V]> {
-    constructor(...args: any[]) { super(27, ...args); }
+    constructor(from?: Record<string, V> | GodotDictionary<K, V>) {
+        super(27);
+        if (from == null) return;
+        if (from instanceof GodotDictionary) { this.assign(from); return; }
+        for (const [k, v] of Object.entries(from)) this.set(k as K, v);
+    }
 
     *[Symbol.iterator](): Iterator<[K, V]> {
         const ks = _C(this, 8530) as any;

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.1-9",
+  "version": "4.7.2-579",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "godot"
   ],
@@ -11,16 +14,19 @@
   "types": "./gen/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./assets": {
+      "types": "./src/assets.d.ts"
+    },
     "./runtime": "./src/runtime.ts",
-    "./boot": "./src/boot.ts",
+    "./boot": {
+      "browser": "./src/boot.browser.ts",
+      "default": "./src/boot.ts"
+    },
     "./load": "./src/load.ts",
     "./debug": "./src/debug.ts",
     "./preload": "./src/preload.ts",
     "./*": "./gen/classes/*.ts"
   },
-  "browser": {
-    "./src/boot.ts": "./src/boot.browser.ts"
-  },
   "files": [
     "src/",
     "gen/",
@@ -29,16 +35,16 @@
   "godot": {
     "version_major": 4,
     "version_minor": 7,
-    "version_patch": 1,
+    "version_patch": 2,
     "version_status": "stable",
     "version_build": "official",
-    "version_full_name": "Godot Engine v4.7.1.stable.official",
+    "version_full_name": "Godot Engine v4.7.2.stable.official",
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.1-3",
-    "@ringozz/godot-windows-x86_64": "^4.7.1-3",
-    "@ringozz/godot-web-wasm32": "^4.7.1-9"
+    "@ringozz/godot-macos-arm64": "^4.7.2-579",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-579",
+    "@ringozz/godot-web-wasm32": "^4.7.2-579"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/assets.d.ts

@@ -101,6 +101,20 @@ declare module '*.wav' {
 	export const materialize: Promise<unknown>;
 }
 
+declare module '*.ttf' {
+	import type { FontFile } from '@ringozz/godot/FontFile';
+	const asset: Promise<FontFile>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.otf' {
+	import type { FontFile } from '@ringozz/godot/FontFile';
+	const asset: Promise<FontFile>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
 declare module '*.ogg' {
 	import type { AudioStreamOggVorbis } from '@ringozz/godot/AudioStreamOggVorbis';
 	const asset: Promise<AudioStreamOggVorbis>;

package/src/boot.browser.ts

@@ -7,9 +7,11 @@
 // *namespace* (whose `.default` is the wasm module). This module is a leaf — it
 // imports nothing from the godot class graph, so a web entry can call
 // `preloadGodot()` *before* importing the app without pulling in `runtime.ts`.
-// `runtime.ts` statically imports this module too (through the browser-field
-// remap), so both sides share the same module instance and `nativeModule`
-// below is the handoff — no global needed.
+// `runtime.ts` statically imports this module too — by package self-reference
+// (`@ringozz/godot/boot`, whose `exports` `./boot` entry's `browser` condition
+// selects this file), the same resolution as the entrypoint's import, so both
+// sides are guaranteed the same module instance and `nativeModule` below is the
+// handoff — no global needed.
 
 let nativeModule: unknown = null;
 

package/src/boot.ts

@@ -4,8 +4,9 @@
 
 // Desktop boot leaf: resolves the native addon for the current host and
 // hands it to `runtime.ts` as the native module *namespace* (whose `.default`
-// is the addon's `module.exports`). `runtime.ts` imports this module, and the
-// package's `browser` field remaps it to `boot.browser.ts` when bundling for
+// is the addon's `module.exports`). `runtime.ts` imports this module by package
+// self-reference (`@ringozz/godot/boot`), whose `exports` `./boot` entry's
+// `browser` condition selects `boot.browser.ts` when bundling for
 // `target: 'browser'` — so the Bun-only `import.meta.require` below never
 // reaches a web bundle.
 

package/src/debug.ts

@@ -2,16 +2,27 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-import { Rect2, str, varToStr, Vector3 } from './index.ts';
+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.
@@ -35,42 +46,95 @@ export function dumpStr(obj: unknown): string {
 }
 
 /**
- * Serialize a scene subtree as a tree-formatted string.
+ * 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 node - Root node to start from
+ * @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 dumpTreeStr(node: Node, depth = 99): string {
+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;
-        lines.push(`${ind}${n.getClass()} "${n.name}" (${n.getChildCount()} children)`);
-        for (let i = 0; i < n.getChildCount(); i++) {
+        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 + '  ');
         }
-    })(node, depth, '');
+    })(root, depth, '');
     return lines.join('\n');
 }
 
 /**
- * Return a snapshot of engine runtime stats as a formatted string.
+ * 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.
  *
- * 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`.
+ * @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 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');
+export function find(pattern = '*', type = '', node?: Node): Node[] {
+    const root = node ?? tree.root;
+    return [...root.findChildren(pattern, type, true, false)];
 }
 
 /**
@@ -117,6 +181,150 @@ function ensureDOMRect(): void {
     };
 }
 
+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.
  *
@@ -133,104 +341,14 @@ export function initDebug(): void {
     });
 
     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,
-            );
-        },
-    });
+    defineBoundingClientRect(CanvasItem.prototype, canvasItemBounds);
+    defineBoundingClientRect(Node3D.prototype, node3dBounds);
 
     (globalThis as any).$ = {
         Engine, OS, ClassDB, Time,
-        dumpStr, dumpTreeStr, statsStr, gc,
+        dumpStr, snapshot, inspect, click, find, gc,
+        get tree(): SceneTree { return tree; },
+        get paused(): boolean { return tree.paused; },
+        set paused(v: boolean) { tree.paused = v; },
     };
 }

package/src/index.ts

@@ -10,7 +10,7 @@ import { GodotInstance } from '../gen/classes/GodotInstance.ts';
 import { SceneTree } from '../gen/classes/SceneTree.ts';
 import { Window } from '../gen/classes/Window.ts';
 import { gc } from './debug.ts';
-import { cancelAnimationFrame, getGodot, requestAnimationFrame } from './runtime.ts';
+import { cancelAnimationFrame, cleanupHooks, getGodot, requestAnimationFrame } from './runtime.ts';
 
 // ---- make sure these classes are not tree-shaked ----
 void ValueTypes;
@@ -34,7 +34,19 @@ export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike
         await new Promise(requestAnimationFrame);
 
     await unmount?.();
-    console.log(gc());
+    while (cleanupHooks.size) {
+        const hooks = Array.from(cleanupHooks); cleanupHooks.clear();
+        await Promise.all(hooks.map((hook) => hook()));
+    }
+
+    // Let pending Napi wrapper finalizers run before tearing down the engine:
+    // Bun.gc(true) marks unreachable wrappers but their ~GodotVar/~Variant
+    // (which unrefs RefCounted objects) only runs on later macrotasks — and one
+    // wrapper's finalizer can free others. Freeing the engine first would report
+    // every still-referenced RefCounted as leaked, so drain a few gc+tick rounds.
+    for (let i = 0; i < 4; i++) {
+        console.log(gc());
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
     return godot.free();
 }
-

package/src/load.ts

@@ -8,9 +8,25 @@ import { ProjectSettings } from '../gen/classes/ProjectSettings.ts';
 import { ResourceLoader, ThreadLoadStatus } from '../gen/classes/ResourceLoader.ts';
 import { ResourceUID } from '../gen/classes/ResourceUID.ts';
 import type { Resource } from '../gen/classes/Resource.ts';
-import { stageFile } from './runtime.ts';
+import { cleanupHooks, stageFile } from './runtime.ts';
 import { decodeCtex } from './web-image.ts';
 
+// Each loaded wrapper is released at shutdown via a `cleanupHooks` entry
+// holding a WeakRef: module-scope asset imports (the preload modules' memoized
+// load promises) keep their wrappers reachable, so GC alone can't collect them
+// before the engine stops. WeakRef keeps the entries from pinning resources
+// during the app's lifetime.
+function track<T extends Resource>(res: T): T {
+    const ref = new WeakRef<Resource>(res);
+    cleanupHooks.add(() => {
+        const r = ref.deref();
+        if (r) {
+            try { r.free(); } catch {}
+        }
+    });
+    return res;
+}
+
 /**
  * A Godot `Resource` subclass constructor: its `.name` is the registered class
  * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
@@ -153,6 +169,7 @@ export function loadAsset<C extends ResourceConstructor>(
 	data: Record<string, unknown> = {},
 ): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
 	const cached = cachedResource<C>(path);
+	if (cached) cached.then(track);
 	const materialize = cached ? Promise.resolve() : materializeFiles(files, deps);
 	const existing = data[path] as Promise<InstanceType<C>> | undefined;
 	const load = existing ?? cached ?? materialize.then(() => loadResourceAsync(path, cls, files));
@@ -189,6 +206,10 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 			break;
 		}
 		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
+			// Collect the engine's LoadToken so a failed load doesn't leave it
+			// registered (a bare `RefCounted` leaked at exit). Safe no-op when
+			// no token exists.
+			ResourceLoader.loadThreadedGet(path);
 			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
 		}
 		await nextTick();
@@ -206,5 +227,5 @@ export async function loadResourceAsync<C extends ResourceConstructor>(
 			}
 		}
 	}
-	return result;
+	return track(result);
 }