@ringozz/godot 4.7.1-9 → 4.7.2-570

package/README.md

@@ -33,7 +33,7 @@ const done = runGodot(); // pumps frames until aborted
 
 ### Web
 
-The wasm engine boots asynchronously, so on web the entry script must boot it **before** importing the app. `@ringozz/godot/runtime` reads the booted native module synchronously through the `@ringozz/godot/boot` export — the package's `browser` field remaps the desktop `boot.ts` leaf to `boot.browser.ts` in browser-targeted bundles, which hands the module over to `runtime.ts` via a shared module instance — keeping the shared module graph top-level-await free, which is also what makes Bun's HMR dev server work. On desktop `preloadGodot()` is a no-op (the engine boots at import).
+The wasm engine boots asynchronously, so on web the entry script must boot it **before** importing the app: `@ringozz/godot/boot`'s `preloadGodot()` starts the engine, and `@ringozz/godot/runtime` then reads the booted module synchronously (the package's `exports` map routes `./boot` to the web leaf in browser-targeted bundles). This keeps the shared module graph top-level-await free, which is also what makes Bun's HMR dev server work. On desktop `preloadGodot()` is a no-op — the engine boots at import.
 
 ```ts
 // your web entry (referenced by <script type="module"> in the HTML)
@@ -53,7 +53,7 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_get`, `_set`, `_R`, `_G`, `_P`, `getGodot`, `GodotVar` |
 | `@ringozz/godot/boot` | Platform boot: `getNativeModule()`; web `preloadGodot()` (awaited before importing the app; no-op on desktop) |
 | `@ringozz/godot/load` | Async resource loading: `loadResourceAsync` |
-| `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `dumpTreeStr`, `statsStr`, `gc` |
+| `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
 
@@ -74,7 +74,7 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 - `loadResourceAsync(path, cls, files?)` — generic over the Godot class: `cls.name` is the `ResourceLoader` type hint, and the return type is `InstanceType<typeof cls>`. Loads in the background (`loadThreadedRequest` + status polling). Godot default arguments apply: the napi dispatch truncates trailing `undefined` args, so `loadThreadedRequest` uses its default `CACHE_MODE_REUSE` and the resource stays cached in the engine (scene re-references don't re-read the file). On web it only works for paths already staged into MEMFS (generated asset modules handle this). When the asset's `files` map is passed, the staged product files (`.ctex`/`.scn`/native sources) are deleted from MEMFS after the resource loads — only the `.import` sidecars are kept, since they route imported source paths to their products. The decoded texture bytes don't linger in the JS heap.
 - `loadAsset(path, cls, files, deps, data)` — the generated asset modules' entry point (also usable directly): returns `{ materialize, load }`. It checks the engine's `ResourceCache` first (when the asset is already loaded, `load` resolves to the cached instance and staging is skipped), stages the bundled files via Godot's `copyToFS` (zero-copy handover of the fetched bytes; a no-op on desktop where the files already exist), loads via `loadResourceAsync`, and memoizes `load` on `data` (pass `import.meta.hot.data`) so HMR re-evaluations reuse the same fulfilled promise.
 
-Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset:
+Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset. Only **JS imports** are virtualized — HTML asset references (`<link rel="icon">`, `<img src>`) and CSS `url()` refs fall through to Bun's normal (content-hashed) asset handling, so favicons and other web assets co-exist with Godot imports:
 
 ```ts
 import foo from './models/foo.gltf';
@@ -97,7 +97,7 @@ function Foo() {
 </Suspense>
 ```
 
-Each extension maps to its Godot class (source assets only — `gltf`/`tscn`/`obj` → `PackedScene`, `jpg`/`jpeg`/`png`/`webp` → `CompressedTexture2D`, `svg` → `Texture2D`, `exr`/`hdr` → `TextureLayered`, `wav` → `AudioStreamWAV`, `ogg` → `AudioStreamOggVorbis`, `mp3` → `AudioStreamMP3`, `tres` → `Resource`, `po` → `Translation`), declared in `src/assets.d.ts`. Imported products (`.scn`/`.ctex`) are never imported directly.
+Each extension maps to its Godot class (source assets only — `gltf`/`tscn`/`obj` → `PackedScene`, `jpg`/`jpeg`/`png`/`webp` → `CompressedTexture2D`, `svg` → `Texture2D`, `exr`/`hdr` → `TextureLayered`, `wav` → `AudioStreamWAV`, `ogg` → `AudioStreamOggVorbis`, `mp3` → `AudioStreamMP3`, `ttf`/`otf` → `FontFile`, `tres` → `Resource`, `po` → `Translation`), declared in `src/assets.d.ts`. Imported products (`.scn`/`.ctex`) are never imported directly.
 
 Textures are shared only through Godot's `ResourceLoader` path cache. The glTF import pipeline may produce per-scene texture instances (same `res://` path, separate objects), so don't assume two scenes referencing the same image share one texture object.
 
@@ -106,12 +106,17 @@ Textures are shared only through Godot's `ResourceLoader` path cache. The glTF i
 ```ts
 import { initDebug } from '@ringozz/godot/debug';
 initDebug();
-// singletons + helpers now on globalThis.$: $.Engine, $.dumpStr(node), $.dumpTreeStr(root), $.statsStr(), $.gc()
+// singletons + helpers now on globalThis.$: $.Engine, $.tree, $.dumpStr(node), $.snapshot([pattern]), $.inspect(path), $.click(path), $.find([pattern], [type]), $.paused, $.gc()
 ```
 
-`dumpStr` renders value types inline (`(1.0, 2.0, 3.0)`, arrays, dictionaries) via Godot's `str()` and dumps objects via Godot's `var_to_str`, with the node's `name` prepended.
+- `dumpStr(obj)` renders value types inline (`(1.0, 2.0, 3.0)`, arrays, dictionaries) via Godot's `str()` and dumps objects via Godot's `var_to_str`, with the node's `name` prepended.
+- `snapshot(pattern?, node?)` dumps the scene tree from the root `Window` as `Class "name" (N children)` lines; pass a string (case-insensitive substring) or `RegExp` to filter. `$.snapshot()` with no arg dumps the whole tree.
+- `inspect(path)` resolves a node by absolute NodePath (`/root/Box`) or name/glob pattern (`findChild`) and returns its `dumpStr`.
+- `click(path)` synthesizes a left-click at the center of a `Control` via `Window.pushInput` (device-space coordinates), returning the node's `dumpStr` or `null` if it isn't a `Control`.
+- `find(pattern?, type?)` returns a JS array of nodes matching a name glob and/or class (`$.find('*', 'RigidBody3D')` lists all physics bodies).
+- `$.tree` is the live `SceneTree`; `$.paused = true` freezes the scene tree for inspection; `$.paused = false` resumes.
 
-`initDebug` also registers an `uncaughtException` handler that keeps the process alive, polyfills `DOMRect` (not defined in Bun, needed by `getBoundingClientRect()`), and adds `getBoundingClientRect()` to `CanvasItem`/`Node3D`.
+`initDebug` also registers an `uncaughtException` handler that keeps the process alive, polyfills `DOMRect` (not defined in Bun, needed by `getBoundingClientRect()`), and adds `getBoundingClientRect()` to `CanvasItem`/`Node3D` (Node3D covers descendant meshes; returns CSS-pixel coordinates).
 
 ## Notes
 

package/gen/classes/DisplayServer.ts

@@ -729,7 +729,7 @@ export class DisplayServer extends GodotVar {
     static screenGetDpi(screen?: number /* = -1 */): number { return _C($(), 10248, screen) as number; }
 
     /**
-     * Returns the scale factor of the specified screen by index. Returns `1.0` if `screen` is invalid.
+     * Returns the scale factor of the specified screen by index. Returns `1.0` if `screen` is invalid. See also {@link screenGetMaxScale}.
      * **Note:** One of the following constants can be used as `screen`: {@link SCREEN_OF_MAIN_WINDOW}, {@link SCREEN_PRIMARY}, {@link SCREEN_WITH_MOUSE_FOCUS}, or {@link SCREEN_WITH_KEYBOARD_FOCUS}.
      * **Note:** On macOS, the returned value is `2.0` for hiDPI (Retina) screens, and `1.0` for all other cases.
      * **Note:** On Linux (Wayland), the returned value is accurate only when `screen` is {@link SCREEN_OF_MAIN_WINDOW}. Due to API limitations, passing a direct index will return a rounded-up integer, if the screen has a fractional scale (e.g. `1.25` would get rounded up to `2.0`).
@@ -743,9 +743,8 @@ export class DisplayServer extends GodotVar {
     static isTouchscreenAvailable(): boolean { return _C($(), 8369) as boolean; }
 
     /**
-     * Returns the greatest scale factor of all screens.
-     * **Note:** On macOS returned value is `2.0` if there is at least one hiDPI (Retina) screen in the system, and `1.0` in all other cases.
-     * **Note:** This method is implemented only on macOS.
+     * Returns the greatest scale factor of all screens. See also {@link screenGetScale}.
+     * **Note:** On macOS, the returned value is `2.0` if there is at least one hiDPI (Retina) screen in the system, and `1.0` in all other cases.
      */
     static screenGetMaxScale(): number { return _C($(), 10253) as number; }
 

package/gen/classes/Light3D.ts

@@ -296,12 +296,14 @@ export const BakeMode = {
      */
     BAKE_DISABLED: 0,
     /**
-     * Light is taken into account in static baking ({@link VoxelGI}, {@link LightmapGI}, SDFGI ({@link Environment.sdfgiEnabled})). The light can be moved around or modified, but its global illumination will not update in real-time. This is suitable for subtle changes (such as flickering torches), but generally not large changes such as toggling a light on and off.
+     * Light is taken into account in static baking ({@link VoxelGI}, {@link LightmapGI}, SDFGI ({@link Environment.sdfgiEnabled})). The light can be moved around or modified, but its global illumination will not update in real-time.
      * **Note:** The light is not baked in {@link LightmapGI} if {@link editorOnly} is `true`.
+     * **Note:** When using {@link LightmapGI}, both the direct and indirect light are baked. Since direct light is baked, the light doesn't display a specular lobe on static lightmapped meshes. Shadows on static lightmapped meshes will also look less detailed, but the light still casts shadows that can be displayed on dynamic objects. Since real-time light computations are skipped on static lightmapped meshes, this bake mode improves runtime performance compared to {@link BAKE_DYNAMIC} and {@link BAKE_DISABLED}.
      */
     BAKE_STATIC: 1,
     /**
-     * Light is taken into account in dynamic baking ({@link VoxelGI} and SDFGI ({@link Environment.sdfgiEnabled}) only). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to {@link BAKE_STATIC}. This has a greater performance cost compared to {@link BAKE_STATIC}. When using SDFGI, the update speed of dynamic lights is affected by {@link ProjectSettings.rendering/globalIllumination/sdfgi/framesToUpdateLights}.
+     * Light is taken into account in dynamic baking ({@link VoxelGI} and SDFGI ({@link Environment.sdfgiEnabled})). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to {@link BAKE_STATIC}. This has a greater performance cost compared to {@link BAKE_STATIC}. When using SDFGI, the update speed of dynamic lights is affected by {@link ProjectSettings.rendering/globalIllumination/sdfgi/framesToUpdateLights}.
+     * **Note:** When using {@link LightmapGI}, the light's indirect light is baked, but direct light and shadows remain real-time. This mode allows performing *subtle* changes to a light's color, energy, and position while still looking fairly correct. For example, you can use this to create flickering static torches that have their indirect light baked.
      */
     BAKE_DYNAMIC: 2,
 } as const;

package/gen/classes/RandomNumberGenerator.ts

@@ -48,9 +48,9 @@ export class RandomNumberGenerator extends RefCounted {
     randiRange(from: number, to: number): number { return _C(this, 9725, from, to) as number; }
 
     /**
-     * Returns a random integer between `0` and the size of the array that is passed as a parameter. Each value in the array should be a floating-point number that represents the relative likelihood that it will be returned as an index. A higher value means the value is more likely to be returned as an index, while a value of `0` means it will never be returned as an index.
+     * Returns a random integer between `0` and the size of the array that is passed as a parameter. Each value in the array should be a non-negative floating-point number that represents the relative likelihood that it will be returned as an index. A higher value means the value is more likely to be returned as an index, while a value of `0` means it will never be returned as an index.
      * For example, if {@link code skip-lint}{@link 0.5, 1, 1, 2} is passed as a parameter, then the method is twice as likely to return `3` (the index of the value `2`) and twice as unlikely to return `0` (the index of the value `0.5`) compared to the indices `1` and `2`.
-     * Prints an error and returns `-1` if the array is empty.
+     * Prints an error and returns `-1` if the array is empty or contains any negative values.
      *
      *
      * ```gdscript

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-570",
   "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-570",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-570",
+    "@ringozz/godot-web-wasm32": "^4.7.2-570"
   },
   "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);
 }

package/src/preload.ts

@@ -36,7 +36,7 @@ const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }
 	jpeg: { cls: 'CompressedTexture2D' },
 	png: { cls: 'CompressedTexture2D' },
 	webp: { cls: 'CompressedTexture2D' },
-	svg: { cls: 'Texture2D' },
+	svg: { cls: 'CompressedTexture2D' },
 	exr: { cls: 'TextureLayered' },
 	hdr: { cls: 'TextureLayered' },
 	wav: { cls: 'AudioStreamWAV' },
@@ -44,6 +44,8 @@ const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }
 	mp3: { cls: 'AudioStreamMP3' },
 	tres: { cls: 'Resource', scan: true, native: true },
 	po: { cls: 'Translation', native: true },
+	ttf: { cls: 'FontFile' },
+	otf: { cls: 'FontFile' },
 	mtl: { scan: true },
 };
 
@@ -175,6 +177,22 @@ const assetPlugin: BunPlugin = {
 	name: 'godot-assets',
 	setup(build) {
 		build.onResolve({ filter: ASSET_RE }, (args) => {
+			// Only JS module imports of Godot source assets become `godot`
+			// modules. `Bun.build` reports JS imports as `import-statement`
+			// (and `dynamic-import`/`require-*`) but HTML asset references
+			// (<link>/<img>) and CSS url() refs as `internal`/`url-token` —
+			// those fall through so Bun copies/hashes the file normally. The
+			// runtime preload (bun run / bun test) reports JS imports with no
+			// kind (`undefined`), so treat that as a JS import too.
+			if (
+				args.kind !== undefined &&
+				args.kind !== 'import-statement' &&
+				args.kind !== 'dynamic-import' &&
+				args.kind !== 'require-call' &&
+				args.kind !== 'require-resolve'
+			) {
+				return;
+			}
 			const importerAbs = args.importer?.startsWith(`${NS}:`)
 				? args.importer.slice(NS.length + 1)
 				: args.importer;

package/src/runtime.ts

@@ -3,11 +3,21 @@
 ***********************************************************************/
 
 /** Shared runtime: platform-specific native-module selection lives in
- *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the package's
- *  `browser` field). `_mod` is the native module — the desktop addon's
- *  `module.exports` or the wasm module's `.default`.
+ *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the `exports` `./boot`
+ *  entry's `browser` condition). `_mod` is the native module — the desktop
+ *  addon's `module.exports` or the wasm module's `.default`.
+ *
+ *  The boot leaf is imported by **package self-reference** (`@ringozz/godot/boot`),
+ *  not by relative path: a bare specifier resolves through this package's own
+ *  `exports` map (whose `./boot` entry's `browser` condition selects
+ *  `boot.browser.ts` on web) exactly like the entrypoint's
+ *  `import { preloadGodot } from '@ringozz/godot/boot'`, so both sides land on the
+ *  same absolute path and share ONE `boot.browser.ts` module instance. (A relative
+ *  `./boot.ts` import would let a consumer's bundler realpath it into
+ *  `node_modules/.bun/...` while the entrypoint keeps the `node_modules/@ringozz/godot`
+ *  path — two instances, and the preload handoff below would read `null`.)
  */
-import { getNativeModule } from './boot.ts';
+import { getNativeModule } from '@ringozz/godot/boot';
 const { default: _mod } = getNativeModule() as any;
 
 /** Godot instance */
@@ -69,3 +79,6 @@ export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
         if (res !== 0) reject(new Error('Failed to connect signal: error code ' + res));
     }).then(onfulfilled, onrejected);
 }
+
+/** Cleanup callbacks run once by `runGodot` just before the engine is freed; may be async. */
+export const cleanupHooks: Set<() => void | Promise<void>> = new Set();