@ringozz/godot 4.7.1-7 → 4.7.1-9

package/README.md

@@ -10,11 +10,11 @@ This is the core runtime package. The React layer is a separate package ([`@ring
 bun add @ringozz/godot
 ```
 
-The package ships no engine binary itself — it auto-selects a platform addon from its optional dependencies on install: `@ringozz/godot-macos-arm64`, `@ringozz/godot-windows-x86_64`, or `@ringozz/godot-web-wasm32` (the WASM build is installed everywhere and used on web). No `project.godot` is required — the engine boots from engine defaults with `res://` = your working directory.
+The package ships no engine binary itself — it auto-selects a platform addon from its optional dependencies on install: `@ringozz/godot-macos-arm64`, `@ringozz/godot-windows-x86_64`, or `@ringozz/godot-web-wasm32` (the WASM build is installed everywhere and used on web). No `project.godot` is required — the engine boots from engine defaults with `res://` = your working directory (if a `project.godot` is present at cwd, it is loaded and `res://` still maps to cwd).
 
 ## Usage
 
-The engine is already running when you import — `getGodot()` returns the instance synchronously. Pump frames with `runGodot()`:
+On **desktop**, the engine is already running when you import — `getGodot()` returns the instance synchronously. Pump frames with `runGodot()`:
 
 ```ts
 import { runGodot } from '@ringozz/godot';
@@ -31,6 +31,19 @@ root.addChild(label);
 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).
+
+```ts
+// your web entry (referenced by <script type="module"> in the HTML)
+import { preloadGodot } from '@ringozz/godot/boot';
+await preloadGodot();
+await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
+```
+
+(That's exactly what `dev/demo.html.ts` does in this repo. A second `<script type="module">` tag can't replace the dynamic import — Bun's fullstack HTML bundler merges all script entries into one chunk, so the browser's in-order script/TLA serialization never applies.)
+
 ### What's exported where
 
 | Specifier | Contents |
@@ -38,19 +51,67 @@ const done = runGodot(); // pumps frames until aborted
 | `@ringozz/godot` | Value types (`Vector3`, `Color`, …), global enums, heap types, utility functions, global constants, `runGodot()`, RAF polyfills |
 | `@ringozz/godot/ClassName` | Classes, one per module — e.g. `@ringozz/godot/Label`, `@ringozz/godot/Node` |
 | `@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` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
 
+### Async resource loading
+
+The engine loads pre-baked native resources (`.scn`, `.ctex`, …) through `ResourceLoader`. On desktop these are real files (`res://` = cwd); on web there is no filesystem, so the asset's bundled files — `.import` sidecars as text and imported products (`.scn`/`.ctex`) as emitted asset paths — are staged into Emscripten's in-memory MEMFS (transient, no IndexedDB, no persistent copy) by the generated asset modules, handing the fetched bytes straight to MEMFS via Godot's own `copyToFS` (`FS.createDataFile` with `canOwn` — zero copy, JS-heap only). On web, `.ctex` files are decoded first: the embedded PNG/WebP blobs go through the browser's `createImageBitmap` and the container is rebuilt as raw RGBA (`DATA_FORMAT_IMAGE`), so no image codec runs in wasm. The source file itself is never fetched.
+
+```ts
+import { loadResourceAsync } from '@ringozz/godot/load';
+import { PackedScene } from '@ringozz/godot/PackedScene';
+import { Texture2D } from '@ringozz/godot/Texture2D';
+
+const scene = await loadResourceAsync('res://models/foo.gltf', PackedScene); // PackedScene
+const node  = scene.instantiate();
+const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); // 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:
+
+```ts
+import foo from './models/foo.gltf';
+const scene = await foo;          // PackedScene
+```
+
+Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, deps, import.meta.hot.data)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). It statically imports its own files Godot reads — `.import` sidecars and native text sources (`tscn`/`tres`/`po`) via the `text` loader, imported products (`.scn`/`.ctex`) via the `file` loader — and imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced source assets become dep modules, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
+
+```tsx
+import foo from './models/foo.gltf';
+import { Suspense, use } from 'react';
+
+function Foo() {
+  const scene = use(foo);   // suspends until the scene loads
+  return <FooView scene={scene} />;
+}
+
+<Suspense fallback={<Label text="Loading…" />}>
+  <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.
+
+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.
+
 ### Debugging
 
 ```ts
 import { initDebug } from '@ringozz/godot/debug';
 initDebug();
-// singletons + helpers now on globalThis.$: $.Engine, $.dumpTreeStr(root), $.statsStr(), $.gc()
+// singletons + helpers now on globalThis.$: $.Engine, $.dumpStr(node), $.dumpTreeStr(root), $.statsStr(), $.gc()
 ```
 
-`initDebug` also registers an `uncaughtException` handler that keeps the process alive, and adds `getBoundingClientRect()` to `CanvasItem`/`Node3D`.
+`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.
+
+`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`.
 
 ## Notes
 

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.1-7",
+  "version": "4.7.1-9",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
+  "keywords": [
+    "godot"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "types": "./gen/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./runtime": "./src/runtime.ts",
+    "./boot": "./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/",
@@ -27,11 +36,11 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.1-2",
-    "@ringozz/godot-windows-x86_64": "^4.7.1-2",
-    "@ringozz/godot-web-wasm32": "^4.7.1-7"
+    "@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"
   },
   "peerDependencies": {
-    "@types/node": "*"
+    "@types/bun": "*"
   }
 }

package/src/assets.d.ts

@@ -0,0 +1,116 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Ambient types for Godot asset imports, resolved by `@ringozz/godot/preload`
+// into modules that export a `materialize` promise (files staged into MEMFS) and
+// default to the load promise (`const { materialize, load } = loadAsset(path,
+// Class, files, deps, import.meta.hot.data)` — `load` memoized on the module's
+// HMR data, so re-evaluations return the same fulfilled promise). The default is
+// a stable module singleton, so it can be passed to React's `use()` under
+// `<Suspense>`.
+
+declare module '*.tres' {
+	import type { Resource } from '@ringozz/godot/Resource';
+	const asset: Promise<Resource>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.po' {
+	import type { Translation } from '@ringozz/godot/Translation';
+	const asset: Promise<Translation>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.gltf' {
+	import type { PackedScene } from '@ringozz/godot/PackedScene';
+	const asset: Promise<PackedScene>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.tscn' {
+	import type { PackedScene } from '@ringozz/godot/PackedScene';
+	const asset: Promise<PackedScene>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.obj' {
+	import type { PackedScene } from '@ringozz/godot/PackedScene';
+	const asset: Promise<PackedScene>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.jpg' {
+	import type { CompressedTexture2D } from '@ringozz/godot/CompressedTexture2D';
+	const asset: Promise<CompressedTexture2D>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.jpeg' {
+	import type { CompressedTexture2D } from '@ringozz/godot/CompressedTexture2D';
+	const asset: Promise<CompressedTexture2D>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.png' {
+	import type { CompressedTexture2D } from '@ringozz/godot/CompressedTexture2D';
+	const asset: Promise<CompressedTexture2D>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.webp' {
+	import type { CompressedTexture2D } from '@ringozz/godot/CompressedTexture2D';
+	const asset: Promise<CompressedTexture2D>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.svg' {
+	import type { Texture2D } from '@ringozz/godot/Texture2D';
+	const asset: Promise<Texture2D>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.exr' {
+	import type { TextureLayered } from '@ringozz/godot/TextureLayered';
+	const asset: Promise<TextureLayered>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.hdr' {
+	import type { TextureLayered } from '@ringozz/godot/TextureLayered';
+	const asset: Promise<TextureLayered>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.wav' {
+	import type { AudioStreamWAV } from '@ringozz/godot/AudioStreamWAV';
+	const asset: Promise<AudioStreamWAV>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.ogg' {
+	import type { AudioStreamOggVorbis } from '@ringozz/godot/AudioStreamOggVorbis';
+	const asset: Promise<AudioStreamOggVorbis>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
+declare module '*.mp3' {
+	import type { AudioStreamMP3 } from '@ringozz/godot/AudioStreamMP3';
+	const asset: Promise<AudioStreamMP3>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}

package/src/boot.browser.ts

@@ -0,0 +1,39 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Web boot leaf (the `browser`-field replacement for `boot.ts`): boots the
+// Godot wasm engine and hands the module to `runtime.ts` as the native module
+// *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.
+
+let nativeModule: unknown = null;
+
+/** The cached wasm module import (its namespace), or `null` until `preloadGodot()` completes. */
+export function getNativeModule(): unknown {
+    return nativeModule;
+}
+
+/**
+ * Boots the Godot wasm engine so `@ringozz/godot/runtime` can read the native
+ * module synchronously via {@link getNativeModule} — keeping the shared module
+ * graph top-level-await free (which is what lets Bun's HMR module loader
+ * evaluate sibling importers in order). Returns the wasm module's namespace
+ * (the native module is its `.default`, which `runtime.ts` destructures).
+ * Idempotent: subsequent calls return the cached import without re-booting.
+ *
+ * A web entry must `await preloadGodot()` before importing the app:
+ *
+ * ```ts
+ * import { preloadGodot } from '@ringozz/godot/boot';
+ * await preloadGodot();
+ * await import('./app.ts');
+ * ```
+ */
+export async function preloadGodot(): Promise<unknown> {
+    return nativeModule ??= await import('@ringozz/godot-web-wasm32');
+}

package/src/boot.ts

@@ -0,0 +1,26 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// 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
+// `target: 'browser'` — so the Bun-only `import.meta.require` below never
+// reaches a web bundle.
+
+const { platform, arch } = globalThis.process ?? {};
+const mapping: any = {
+    'darwin-arm64': 'macos-arm64',
+    'win32-x64': 'windows-x86_64',
+};
+
+/** The native addon's module namespace (sync dlopen; engine boots on first call). */
+export function getNativeModule(): unknown {
+    return import.meta.require(`@ringozz/godot-${mapping[`${platform}-${arch}`]}`);
+}
+
+/** Desktop boots synchronously at import — nothing to preload. */
+export async function preloadGodot(): Promise<unknown> {
+    return undefined;
+}

package/src/debug.ts

@@ -2,7 +2,7 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-import { Rect2, Vector3 } from './index.ts';
+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';
@@ -14,40 +14,25 @@ import { OS } from '../gen/classes/OS.ts';
 import { Time } from '../gen/classes/Time.ts';
 
 /**
- * Dump a Godot object's properties as an indented string.
- * Uses `getPropertyList()` + `get()` to safely introspect — never invokes JS getters.
+ * 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, etc.) or plain value
- * @param depth - Max recursion depth into sub-objects (default 2)
- * @param maxProps - Max properties to show per object (default 30)
+ * @param obj - Any Godot wrapper (Node, Resource, …), value type, or plain value
  */
-export function dumpStr(obj: unknown, depth = 2, maxProps = 30): string {
-  if (obj == null || typeof obj !== 'object') return String(obj);
-  let cls: string;
-  try { cls = (obj as any).getClass?.(); } catch { cls = (obj as any).constructor?.name ?? typeof obj; }
-  if (!cls) return String(obj);
-  const lines = [`[${cls}]`];
-  let count = 0;
-  try {
-    const plist = (obj as any).getPropertyList?.();
-    if (plist?.size) {
-      for (let i = 0; i < plist.size() && count < maxProps; i++) {
-        const name = plist.get(i).get('name');
-        if (!name || (name + '').startsWith('_')) continue;
-        let val: unknown;
-        try { val = (obj as any).get(name); } catch { val = '<err>'; }
-        if (typeof val === 'object' && val !== null && depth > 1)
-          lines.push(`  ${name}:\n${indent(dumpStr(val, depth - 1, maxProps), '    ')}`);
-        else
-          lines.push(`  ${name}: ${String(val)}`);
-        count++;
-      }
-    }
-  } catch { /* not a GodotVar */ }
-  return lines.join('\n');
-}
+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);
 
-function indent(s: string, prefix: string): string { return s.split('\n').join('\n' + prefix); }
+    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.
@@ -56,34 +41,36 @@ function indent(s: string, prefix: string): string { return s.split('\n').join('
  * @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');
+    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.
+ * 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 {
-  const tree = Engine.getMainLoop() as any;
-  return [
-    `Frames:     ${Engine.getProcessFrames()}`,
-    `FPS:        ${Engine.getFramesPerSecond()}`,
-    `Physics:    ${Engine.getPhysicsFrames()}`,
-    `Nodes:      ${tree.getNodeCount()}`,
-    `Time scale: ${Engine.timeScale}`,
-    `Main loop:  ${Engine.getMainLoop().getClass()}`,
-  ].join('\n');
+    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');
 }
 
 /**
@@ -91,16 +78,43 @@ export function statsStr(): string {
  * Requires the `--expose-gc` Node.js flag.
  */
 export function gc(): string {
-  const before = globalThis.process?.memoryUsage?.().heapUsed;
-  if ((globalThis as any).Bun)
-    (globalThis as any).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;
-  return `GC: freed ${((before - after) / 1024).toFixed(0)} KB`;
+    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 }; }
+    };
 }
 
 /**
@@ -111,109 +125,112 @@ export function gc(): string {
  *   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);
-  });
-
-  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,
-  };
+    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,
+    };
 }

package/src/index.ts

@@ -26,7 +26,7 @@ Object.assign(globalThis as any, { requestAnimationFrame, cancelAnimationFrame }
 export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike<void>) {
     signal?.throwIfAborted();
     signal?.addEventListener('abort', () => {
-        (Engine.getMainLoop() as SceneTree).quit();
+        (Engine.getMainLoop() as SceneTree)?.quit();
     }, { once: true });
 
     const godot = getGodot();

package/src/load.ts

@@ -0,0 +1,210 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { DirAccess } from '../gen/classes/DirAccess.ts';
+import { FileAccess } from '../gen/classes/FileAccess.ts';
+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 { decodeCtex } from './web-image.ts';
+
+/**
+ * A Godot `Resource` subclass constructor: its `.name` is the registered class
+ * name (used as the `ResourceLoader` type hint), and `InstanceType<C>` is the
+ * loaded resource type.
+ */
+type ResourceConstructor = { new(...args: any[]): Resource } & Function;
+
+/**
+ * A file to stage before loading, keyed by `res://` path: sidecars (`.import`)
+ * arrive as `content` (text); imported products (`.scn`/`.ctex`) arrive as
+ * `path` (fetched).
+ */
+interface AssetFile {
+	content?: string;
+	path?: string;
+}
+
+export type AssetFiles = Record<string, AssetFile>;
+
+const UID_RE = /uid="(uid:\/\/[\w.]+)"/;
+
+// Godot encodes `uid://` numbers in base 34 over `a-y` then `0-8`
+// (core/io/resource_uid.cpp). Decode in JS with BigInt: `ResourceUID.textToId`
+// returns a JS number, and these ids exceed `Number.MAX_SAFE_INTEGER`, so the
+// low digits would be lost. BigInt flows through `_C` losslessly (int64).
+const UID_CHARS = 'abcdefghijklmnopqrstuvwxy012345678';
+
+function uidToId(uid: string): bigint {
+	let id = 0n;
+	for (let i = 6; i < uid.length; i++) {
+		id = id * 34n + BigInt(UID_CHARS.indexOf(uid[i]));
+	}
+	return id;
+}
+
+/**
+ * Registers an asset's `uid://` → `res://` path so scene ext_resource references
+ * resolve it (Godot's `ResourceUID` map) instead of warning and falling back to
+ * the stored text path. Idempotent; skips unknown/malformed uids.
+ */
+function registerAssetUid(uid: string, resPath: string): void {
+	const id = uidToId(uid);
+	if (id !== 0n && !ResourceUID.hasId(id as unknown as number)) {
+		ResourceUID.addId(id as unknown as number, resPath);
+	}
+}
+
+async function materialize([resPath, entry]: [string, AssetFile]): Promise<void> {
+	if (FileAccess.fileExists(resPath)) {
+		return;
+	}
+	let bytes: Uint8Array;
+	if (entry.content !== undefined) {
+		// Sidecars (`.import`) and native text sources carry the asset's `uid=`;
+		// register it so scenes resolve by uid. `.import` maps to the source path
+		// (resPath minus the suffix); native files map to themselves.
+		const uid = entry.content.match(UID_RE)?.[1];
+		if (uid) {
+			registerAssetUid(uid, resPath.endsWith('.import') ? resPath.slice(0, -'.import'.length) : resPath);
+		}
+		bytes = new TextEncoder().encode(entry.content);
+	} else if (entry.path) {
+		const res = await fetch(entry.path);
+		if (!res.ok) {
+			return;
+		}
+		bytes = new Uint8Array(await res.arrayBuffer());
+		if (resPath.endsWith('.ctex')) {
+			// On web, decode embedded PNG/WebP blobs with the browser before
+			// staging, so the engine never runs an image codec (see web-image.ts).
+			bytes = await decodeCtex(bytes);
+		}
+	} else {
+		return;
+	}
+	stageFile?.(ProjectSettings.globalizePath(resPath), bytes);
+}
+
+const nextTick = () => new Promise(requestAnimationFrame);
+
+/**
+ * An asset module as generated by `@ringozz/godot/preload`: `default` is the
+ * load promise, `materialize` resolves once its bundled files (plus its deps'
+ * files) are staged on the engine's filesystem.
+ */
+interface AssetModule {
+	default: Promise<unknown>;
+	materialize: Promise<unknown>;
+}
+
+/**
+ * Stages the asset's bundled files before loading: `.import` sidecars as text
+ * and imported products (`.scn`/`.ctex`) as fetched paths. On web the bytes are
+ * written straight into Emscripten's MEMFS via Godot's `copyToFS` (JS-heap only,
+ * no wasm copy); a no-op on desktop where the files already exist. `deps`
+ * supplies referenced asset modules whose file-staging is awaited (so Godot can
+ * resolve them) and whose load failures are logged.
+ */
+function materializeFiles(files: AssetFiles, deps: AssetModule[] = []): Promise<unknown> {
+	for (const dep of deps) {
+		dep.default.catch((err) => console.error('[godot] dependency load failed:', err));
+	}
+	if (stageFile === undefined) {
+		// Desktop: the files already exist on disk (res:// = cwd) and uids come
+		// from `.godot/uid_cache.bin`, so there is nothing to stage.
+		return Promise.resolve();
+	}
+	return Promise.all([...Object.entries(files).map(materialize), ...deps.map((dep) => dep.materialize)]);
+}
+
+/**
+ * Returns a promise resolving to the resource already cached in the engine at
+ * `path` (`ResourceCache`), or `null` when it isn't loaded yet. Used by
+ * {@link loadAsset} to skip file staging and the threaded load when a
+ * re-evaluated module (e.g. web HMR) references an asset that is still cached.
+ * `getCachedRef` returns the same JS wrapper as `loadThreadedGet` (instance
+ * binding), so identity is preserved.
+ */
+function cachedResource<C extends ResourceConstructor>(path: string): Promise<InstanceType<C>> | null {
+	const result = ResourceLoader.getCachedRef(path) as InstanceType<C>;
+	return result ? Promise.resolve(result) : null;
+}
+
+/**
+ * Entry point for the generated asset modules (`@ringozz/godot/preload`): checks
+ * the engine's `ResourceCache` once (`cachedResource`), stages the bundled files
+ * via `materializeFiles` when needed, then loads via {@link loadResourceAsync},
+ * memoizing the resulting load promise on `data` (the module's
+ * `import.meta.hot.data`, carried across HMR re-evaluations; `{}` on desktop
+ * where modules evaluate once). Memoization keeps `use()` seeing the **same**
+ * fulfilled promise object across re-evaluations — no Suspense fallback flash on
+ * hot reload; a rejected load is evicted so the next evaluation retries. Returns
+ * the `materialize` promise (own + deps' files staged) and the load promise.
+ */
+export function loadAsset<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files: AssetFiles,
+	deps: AssetModule[] = [],
+	data: Record<string, unknown> = {},
+): { materialize: Promise<unknown>; load: Promise<InstanceType<C>> } {
+	const cached = cachedResource<C>(path);
+	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));
+	data[path] = load;
+	load.catch(() => {
+		if (data[path] === load) delete data[path];
+	});
+	return { materialize, load };
+}
+
+/**
+ * Loads a resource in the background. `cls` supplies both the `ResourceLoader`
+ * type hint (its registered `.name`) and the return type. On web, call
+ * {@link materializeFiles} with the asset's bundled files first; on desktop the
+ * files already exist. Pass the same `files` map to have the staged files
+ * deleted from MEMFS once the resource is loaded (the resource stays cached in
+ * the engine, so the bytes are no longer needed).
+ */
+export async function loadResourceAsync<C extends ResourceConstructor>(
+	path: string,
+	cls: C,
+	files?: AssetFiles,
+): Promise<InstanceType<C>> {
+	const err = ResourceLoader.loadThreadedRequest(path, cls.name);
+	if (err) {
+		throw new Error(`loadResourceAsync(${path}): loadThreadedRequest failed (${err})`);
+	}
+
+	let result: InstanceType<C>;
+	while (true) {
+		const status = ResourceLoader.loadThreadedGetStatus(path);
+		if (status === ThreadLoadStatus.THREAD_LOAD_LOADED) {
+			result = ResourceLoader.loadThreadedGet(path) as InstanceType<C>;
+			break;
+		}
+		if (status === ThreadLoadStatus.THREAD_LOAD_FAILED || status === ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE) {
+			throw new Error(`loadResourceAsync(${path}): load failed (status ${status})`);
+		}
+		await nextTick();
+	}
+	if (files && stageFile !== undefined) {
+		// Keep `.import` sidecars — they route imported source paths to their
+		// products (ResourceFormatImporter recognizes a path by its sidecar).
+		// Delete everything else: the products are read only on a cache miss, and
+		// the resource stays cached after loading, so the bytes are dead weight.
+		// Best-effort: a file may already be gone (another module's cleanup or a
+		// cache-miss re-stage).
+		for (const resPath of Object.keys(files)) {
+			if (!resPath.endsWith('.import')) {
+				DirAccess.removeAbsolute(resPath);
+			}
+		}
+	}
+	return result;
+}

package/src/preload.ts

@@ -0,0 +1,198 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { plugin } from 'bun';
+import type { BunPlugin } from 'bun';
+
+// Registers the godot-assets plugin: imports of Godot source assets become
+// virtual modules (namespace `godot`) that call `loadAsset` (`@ringozz/godot/load`)
+// and export the resulting `materialize` (own + deps' files) and load promise.
+// `loadAsset` checks the engine's `ResourceCache` once; when the asset is
+// already loaded (e.g. a re-evaluated module under web HMR) the load resolves to
+// the cached instance and `materialize` short-circuits, skipping file staging
+// and the threaded load. The load promise persists on the module's
+// `import.meta.hot.data` (per-module state carried across hot replacements), so
+// HMR re-evaluations return the *same* fulfilled promise object — React's `use()`
+// keeps its tracked status and never re-suspends (no Suspense fallback flash); a
+// rejected load is evicted from `data` so the next evaluation retries; on
+// desktop `data` is `{}` and modules evaluate once. Dependencies are generated
+// modules too, so a dep's load starts at module evaluation while the parent only
+// waits for dep *files*. The default export is the single plugin — registered
+// globally via bunfig preload and loaded by `[serve.static] plugins` for
+// `Bun.serve` HTML routes.
+
+const ROOT = process.cwd();
+const NS = 'godot';
+
+/** Format metadata: `cls` = Godot class (importable), `scan` = scan text refs, `native` = no `.import` sidecar. */
+const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }> = {
+	gltf: { cls: 'PackedScene', scan: true },
+	tscn: { cls: 'PackedScene', scan: true, native: true },
+	obj: { cls: 'PackedScene', scan: true },
+	jpg: { cls: 'CompressedTexture2D' },
+	jpeg: { cls: 'CompressedTexture2D' },
+	png: { cls: 'CompressedTexture2D' },
+	webp: { cls: 'CompressedTexture2D' },
+	svg: { cls: 'Texture2D' },
+	exr: { cls: 'TextureLayered' },
+	hdr: { cls: 'TextureLayered' },
+	wav: { cls: 'AudioStreamWAV' },
+	ogg: { cls: 'AudioStreamOggVorbis' },
+	mp3: { cls: 'AudioStreamMP3' },
+	tres: { cls: 'Resource', scan: true, native: true },
+	po: { cls: 'Translation', native: true },
+	mtl: { scan: true },
+};
+
+const ASSET_RE = new RegExp(
+	`\\.(${Object.entries(FORMATS).filter(([, f]) => f.cls).map(([k]) => k).join('|')})$`,
+	'i',
+);
+const CLASS_BY_EXT: Record<string, string> = Object.fromEntries(
+	Object.entries(FORMATS).filter(([, f]) => f.cls).map(([k, f]) => [k, f.cls!]),
+);
+const SCANNED = new Set(Object.entries(FORMATS).filter(([, f]) => f.scan).map(([k]) => k));
+const NATIVE = new Set(Object.entries(FORMATS).filter(([, f]) => f.native).map(([k]) => k));
+
+const extOf = (abs: string) => abs.slice(abs.lastIndexOf('.') + 1).toLowerCase();
+const resOf = (abs: string) => 'res://' + abs.slice(ROOT.length + 1).replaceAll('\\', '/');
+const isScannableText = (abs: string) => SCANNED.has(extOf(abs));
+const isNativeText = (abs: string) => NATIVE.has(extOf(abs));
+const isSourceAsset = (abs: string) => existsSync(abs + '.import') || isNativeText(abs);
+
+/** Reads the imported destination (`dest_files`) out of an `.import` sidecar. */
+function parseSidecarDest(text: string): string | null {
+	const deps = text.match(/^dest_files=\[([^\]]*)\]/m);
+	if (deps) {
+		const first = deps[1].match(/"([^"]+)"/);
+		if (first) {
+			return first[1];
+		}
+	}
+	const remap = text.match(/^path="([^"]+)"/m);
+	return remap ? remap[1] : null;
+}
+
+// Generalized reference extraction for text-based source assets: absolute
+// `res://` paths (Godot scenes/resources) and relative path tokens ending in a
+// known asset extension (glTF uris, OBJ/MTL textures). The literal dot before
+// the extension avoids matching MIME types inside `data:` URIs.
+const RES_RE = /res:\/\/[\w./\\-]+/g;
+const REL_RE = new RegExp(`([\\w./\\\\-]+\\.(?:${Object.keys(FORMATS).join('|')}))`, 'g');
+
+function extractRefs(text: string): string[] {
+	const refs: string[] = [];
+	for (const m of text.matchAll(RES_RE)) refs.push(m[0]);
+	for (const m of text.matchAll(REL_RE)) refs.push(m[1]);
+	return refs;
+}
+
+/**
+ * Adds a source asset's own files to `files`: imported assets contribute their
+ * `.import` sidecar (text) + imported product (file); native text formats
+ * (tscn/tres/po) contribute the file itself (text).
+ */
+function addSource(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
+	const impAbs = srcAbs + '.import';
+	if (existsSync(impAbs)) {
+		files.set(resOf(srcAbs) + '.import', 'text');
+		const dest = parseSidecarDest(readFileSync(impAbs, 'utf8'));
+		if (dest) {
+			files.set(dest, 'file');
+		}
+	} else if (isNativeText(srcAbs)) {
+		files.set(resOf(srcAbs), 'text');
+	}
+}
+
+/**
+ * Collects the referenced source assets (deps) of a text source: source assets
+ * become dep modules (each handles its own transitive deps); raw text formats
+ * without a sidecar (`.mtl`) are recursed into. Buffers (`.bin`) are skipped.
+ */
+function collectDeps(abs: string, visited: Set<string>, deps: string[]): void {
+	if (visited.has(abs)) {
+		return;
+	}
+	visited.add(abs);
+	if (!isScannableText(abs)) {
+		return;
+	}
+	for (const ref of extractRefs(readFileSync(abs, 'utf8'))) {
+		const refAbs = ref.startsWith('res://')
+			? resolve(ROOT, ref.slice('res://'.length))
+			: resolve(dirname(abs), ref);
+		if (visited.has(refAbs)) {
+			continue;
+		}
+		if (isSourceAsset(refAbs)) {
+			deps.push(refAbs);
+		} else if (isScannableText(refAbs)) {
+			collectDeps(refAbs, visited, deps);
+		}
+	}
+}
+
+function analyze(abs: string): { files: Map<string, 'text' | 'file'>; deps: string[] } {
+	const files = new Map<string, 'text' | 'file'>();
+	const deps: string[] = [];
+	addSource(abs, files);
+	collectDeps(abs, new Set(), deps);
+	return { files, deps };
+}
+
+function ensureModule(abs: string): string {
+	const res = resOf(abs);
+	const cls = CLASS_BY_EXT[extOf(abs)] ?? 'Resource';
+	const { files, deps } = analyze(abs);
+
+	const imports = [
+		`import { loadAsset } from '@ringozz/godot/load';`,
+		`import { ${cls} } from '@ringozz/godot/${cls}';`,
+	];
+	const map: string[] = [];
+	let ti = 0;
+	let fi = 0;
+	for (const [resPath, kind] of files) {
+		const absP = resolve(ROOT, resPath.slice('res://'.length));
+		const v = kind === 'text' ? `c${ti++}` : `f${fi++}`;
+		const type = kind === 'text' ? 'text' : 'file';
+		const field = kind === 'text' ? 'content' : 'path';
+		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: '${type}' };`);
+		map.push(`  ${JSON.stringify(resPath)}: { ${field}: ${v} },`);
+	}
+	deps.forEach((dep, i) => imports.push(`import * as dep${i} from ${JSON.stringify(dep)};`));
+
+	const filesVar = files.size ? `const files = {\n${map.join('\n')}\n};` : `const files = {};`;
+	const loadAsset = `const { materialize, load } = loadAsset(${JSON.stringify(res)}, ${cls}, files, [${deps.map((_, i) => `dep${i}`).join(', ')}], import.meta.hot.data);`;
+	return imports.join('\n') + '\n' + filesVar + '\n' + loadAsset + '\n' + `export { materialize, load as default };` + '\n';
+}
+
+const assetPlugin: BunPlugin = {
+	name: 'godot-assets',
+	setup(build) {
+		build.onResolve({ filter: ASSET_RE }, (args) => {
+			const importerAbs = args.importer?.startsWith(`${NS}:`)
+				? args.importer.slice(NS.length + 1)
+				: args.importer;
+			const base = importerAbs ? dirname(importerAbs) : (args.resolveDir ?? ROOT);
+			const abs = resolve(base, args.path);
+			// A module's own native-text source (e.g. `.tscn`) self-imports the
+			// same path — let it load as a real file.
+			if (abs === importerAbs) {
+				return;
+			}
+			return { path: abs, namespace: NS };
+		});
+		build.onLoad({ filter: /.*/, namespace: NS }, (args) => ({
+			contents: ensureModule(args.path),
+			loader: 'js',
+		}));
+	},
+};
+
+export default assetPlugin;
+plugin(assetPlugin);

package/src/runtime.ts

@@ -2,13 +2,13 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-const { platform, arch } = globalThis.process ?? {};
-const mapping: any = {
-    'darwin-arm64': 'macos-arm64',
-    'win32-x64': 'windows-x86_64',
-};
-const suffix = mapping[`${platform}-${arch}`];
-const { default: _mod } = await (suffix ? import(`@ringozz/godot-${suffix}`) : import('@ringozz/godot-web-wasm32'));
+/** 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`.
+ */
+import { getNativeModule } from './boot.ts';
+const { default: _mod } = getNativeModule() as any;
 
 /** Godot instance */
 import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
@@ -42,6 +42,9 @@ export const _set = _mod._set as (target: GodotVar, nameId: number, val: unknown
 /** Register Godot object wrapper. */
 export const _R = _mod._R as (typeId: number, ctor: Function) => string;
 
+/** Stage bytes into the web MEMFS (Godot's `copyToFS`); undefined on desktop. */
+export const stageFile = (_mod as any).stageFile as ((path: string, bytes: Uint8Array) => void) | undefined;
+
 /** Get a Signal value from an Object by signal name, or connect a callback when 3rd arg given. */
 export const _G = _mod._G as (target: GodotVar, signalNameId: number, callback?: unknown) => unknown;
 

package/src/web-image.ts

@@ -0,0 +1,118 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Web-only: decode the embedded PNG/WebP blobs of a `.ctex` CompressedTexture2D
+// container with the browser's `createImageBitmap`, and rebuild the container as
+// a raw RGBA8 `DATA_FORMAT_IMAGE` ctex — so no image codec runs in wasm on web.
+// Anything that isn't a PNG/WebP-embedded ctex is returned unchanged.
+
+const CTEX_MAGIC = 'GST2';
+const DATA_FORMAT_IMAGE = 0;
+const DATA_FORMAT_PNG = 1;
+const DATA_FORMAT_WEBP = 2;
+const FORMAT_RGBA8 = 5;
+const FORMAT_BIT_STREAM = 1 << 22;
+
+// Outer header: magic(4) version(4) w(4) h(4) df(4) mipmap_limit(4) reserved(12).
+const OUTER_HEADER_SIZE = 36;
+// Sub-header: data_format(4) w(2) h(2) mipmaps(4) format(4).
+const SUB_HEADER_OFFSET = OUTER_HEADER_SIZE;
+const SUB_HEADER_SIZE = 16;
+const BLOB_TABLE_OFFSET = SUB_HEADER_OFFSET + SUB_HEADER_SIZE;
+
+interface DecodedBitmap {
+	width: number;
+	height: number;
+	data: Uint8Array;
+}
+
+async function decodeWebBitmap(blob: Uint8Array<ArrayBuffer>, type: string): Promise<DecodedBitmap> {
+	const bmp = await createImageBitmap(new Blob([blob], { type }), {
+		imageOrientation: 'none',
+		colorSpaceConversion: 'none',
+		premultiplyAlpha: 'none',
+	});
+	try {
+		const canvas = new OffscreenCanvas(bmp.width, bmp.height);
+		const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!ctx) {
+			throw new Error('web-image: no 2d context for OffscreenCanvas');
+		}
+		ctx.drawImage(bmp, 0, 0);
+		const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
+		return { width: bmp.width, height: bmp.height, data: new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength) };
+	} finally {
+		bmp.close();
+	}
+}
+
+/**
+ * Decodes the embedded PNG/WebP blobs of a `.ctex` file with the browser's
+ * `createImageBitmap` and rebuilds it as a raw RGBA8 (`DATA_FORMAT_IMAGE`)
+ * container. Non-ctex bytes, streamable textures, and `DATA_FORMAT_IMAGE` /
+ * `DATA_FORMAT_BASIS_UNIVERSAL` containers are returned unchanged. Throws if an
+ * embedded blob can't be decoded or its dimensions don't match the expected
+ * mipmap layout, so a would-be undecodable texture fails loudly at materialize
+ * time. A no-op outside browsers (no `createImageBitmap`).
+ */
+export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+	if (
+		typeof createImageBitmap !== 'function' ||
+		bytes.length < SUB_HEADER_OFFSET + SUB_HEADER_SIZE ||
+		String.fromCharCode(...bytes.subarray(0, 4)) !== CTEX_MAGIC
+	) {
+		return bytes;
+	}
+	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
+		return bytes; // streamable layout differs; leave it to the engine
+	}
+	const dataFormat = dv.getUint32(SUB_HEADER_OFFSET, true);
+	if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
+		return bytes; // raw and BASIS_UNIVERSAL containers pass through
+	}
+	const w = dv.getUint16(SUB_HEADER_OFFSET + 4, true);
+	const h = dv.getUint16(SUB_HEADER_OFFSET + 6, true);
+	const mipmaps = dv.getUint32(SUB_HEADER_OFFSET + 8, true);
+	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
+
+	let ofs = BLOB_TABLE_OFFSET;
+	const levels: Uint8Array[] = [];
+	for (let i = 0; i <= mipmaps; i++) {
+		if (ofs + 4 > bytes.length) {
+			throw new Error(`web-image: truncated ctex at mipmap ${i}`);
+		}
+		const size = dv.getUint32(ofs, true);
+		ofs += 4;
+		if (ofs + size > bytes.length) {
+			throw new Error(`web-image: truncated ctex blob at mipmap ${i}`);
+		}
+		const bmp = await decodeWebBitmap(bytes.slice(ofs, ofs + size), type);
+		ofs += size;
+		const ew = Math.max(w >> i, 1);
+		const eh = Math.max(h >> i, 1);
+		if (bmp.width !== ew || bmp.height !== eh) {
+			throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${ew}x${eh}`);
+		}
+		levels.push(bmp.data);
+	}
+
+	const dataSize = levels.reduce((n, level) => n + level.length, 0);
+	const out = new Uint8Array(BLOB_TABLE_OFFSET + dataSize);
+	out.set(bytes.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim
+	const odv = new DataView(out.buffer);
+	odv.setUint32(SUB_HEADER_OFFSET, DATA_FORMAT_IMAGE, true);
+	odv.setUint16(SUB_HEADER_OFFSET + 4, w, true);
+	odv.setUint16(SUB_HEADER_OFFSET + 6, h, true);
+	odv.setUint32(SUB_HEADER_OFFSET + 8, mipmaps, true);
+	odv.setUint32(SUB_HEADER_OFFSET + 12, FORMAT_RGBA8, true);
+	let p = BLOB_TABLE_OFFSET;
+	for (const level of levels) {
+		out.set(level, p);
+		p += level.length;
+	}
+	return out;
+}