@ringozz/godot 4.7.1-8 → 4.7.1-9

package/README.md

@@ -1,123 +1,123 @@
-# @ringozz/godot
-
-Node-API bindings for the Godot Engine — call Godot classes, value types, and utility functions from JavaScript.
-
-This is the core runtime package. The React layer is a separate package ([`@ringozz/react-godot`](../react-godot/README.md)).
-
-## Installation
-
-```sh
-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 (if a `project.godot` is present at cwd, it is loaded and `res://` still maps to cwd).
-
-## Usage
-
-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';
-import { Engine } from '@ringozz/godot/Engine';
-import { SceneTree } from '@ringozz/godot/SceneTree';
-
-const tree = Engine.getMainLoop() as SceneTree;
-const root = tree.root;
-
-const label = new Label();
-label.text = 'hello from godot-node';
-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 (handed over through the shared `@ringozz/godot/boot` module instance) — this keeps the shared module graph top-level-await free, which is also what makes Bun's HMR dev server work.
-
-```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 |
-|---|---|
-| `@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` | Web boot: `preloadGodot()` (awaited before importing the app) |
-| `@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, $.dumpStr(node), $.dumpTreeStr(root), $.statsStr(), $.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.
-
-`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
-
-- **Memory**: non-RefCounted objects (`Node`, `Node2D`, `Node3D`, …) must call `free()` explicitly. RefCounted objects are managed by Godot's ref counting; calling `free()` clears the JS wrapper (decrements the ref).
-- **Class-registration tree-shaking**: `ClassDB.instantiate('X')` requires the JS class to be value-imported (`import { Label } from '@ringozz/godot/Label'`). If a class is only type-used (e.g. `as Label` casts), bundlers may drop its registration side effect, and wrappers fall back to an ancestor class. Render through JSX is unaffected. Workaround: keep a value reference (`void Label;`).
-
-## Development
-
-`gen/` is generated (and gitignored) by `dev/codegen.ts` from `godot --dump-extension-api-with-docs`. Regenerate + typecheck with `bun run prebuild`. Build the native addon with `bun run build`. See [`AGENTS.md`](../../AGENTS.md) for the full workflow.
+# @ringozz/godot
+
+Node-API bindings for the Godot Engine — call Godot classes, value types, and utility functions from JavaScript.
+
+This is the core runtime package. The React layer is a separate package ([`@ringozz/react-godot`](../react-godot/README.md)).
+
+## Installation
+
+```sh
+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 (if a `project.godot` is present at cwd, it is loaded and `res://` still maps to cwd).
+
+## Usage
+
+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';
+import { Engine } from '@ringozz/godot/Engine';
+import { SceneTree } from '@ringozz/godot/SceneTree';
+
+const tree = Engine.getMainLoop() as SceneTree;
+const root = tree.root;
+
+const label = new Label();
+label.text = 'hello from godot-node';
+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 |
+|---|---|
+| `@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, $.dumpStr(node), $.dumpTreeStr(root), $.statsStr(), $.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.
+
+`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
+
+- **Memory**: non-RefCounted objects (`Node`, `Node2D`, `Node3D`, …) must call `free()` explicitly. RefCounted objects are managed by Godot's ref counting; calling `free()` clears the JS wrapper (decrements the ref).
+- **Class-registration tree-shaking**: `ClassDB.instantiate('X')` requires the JS class to be value-imported (`import { Label } from '@ringozz/godot/Label'`). If a class is only type-used (e.g. `as Label` casts), bundlers may drop its registration side effect, and wrappers fall back to an ancestor class. Render through JSX is unaffected. Workaround: keep a value reference (`void Label;`).
+
+## Development
+
+`gen/` is generated (and gitignored) by `dev/codegen.ts` from `godot --dump-extension-api-with-docs`. Regenerate + typecheck with `bun run prebuild`. Build the native addon with `bun run build`. See [`AGENTS.md`](../../AGENTS.md) for the full workflow.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.1-8",
+  "version": "4.7.1-9",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "keywords": [
     "godot"
@@ -18,6 +18,9 @@
     "./preload": "./src/preload.ts",
     "./*": "./gen/classes/*.ts"
   },
+  "browser": {
+    "./src/boot.ts": "./src/boot.browser.ts"
+  },
   "files": [
     "src/",
     "gen/",
@@ -35,7 +38,7 @@
   "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-8"
+    "@ringozz/godot-web-wasm32": "^4.7.1-9"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/assets.d.ts

@@ -1,116 +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>;
-}
+/**********************************************************************
+ 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

@@ -2,36 +2,25 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-// Web boot helper. 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` (which throws until the native module is
-// available). `runtime.ts` statically imports this module too, so both sides
-// share the same module instance and `nativeModule` below is the handoff — no
-// global needed.
+// 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.
 
-let nativeModule: unknown = null;
+const { platform, arch } = globalThis.process ?? {};
+const mapping: any = {
+    'darwin-arm64': 'macos-arm64',
+    'win32-x64': 'windows-x86_64',
+};
 
-/** The cached wasm module import (its namespace), or `null` until `preloadGodot()` completes. */
+/** The native addon's module namespace (sync dlopen; engine boots on first call). */
 export function getNativeModule(): unknown {
-    return nativeModule;
+    return import.meta.require(`@ringozz/godot-${mapping[`${platform}-${arch}`]}`);
 }
 
-/**
- * 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');
- * ```
- */
+/** Desktop boots synchronously at import — nothing to preload. */
 export async function preloadGodot(): Promise<unknown> {
-    return nativeModule ??= await import('@ringozz/godot-web-wasm32');
+    return undefined;
 }