@ringozz/godot 4.7.1-5 → 4.7.1-560

package/README.md

@@ -1,62 +1,128 @@
-# @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.
-
-## Usage
-
-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
-```
-
-### 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/debug` | `initDebug()`, `dumpStr`, `dumpTreeStr`, `statsStr`, `gc` |
-
-Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
-
-### Debugging
-
-```ts
-import { initDebug } from '@ringozz/godot/debug';
-initDebug();
-// singletons + helpers now on globalThis.$: $.Engine, $.dumpTreeStr(root), $.statsStr(), $.gc()
-```
-
-`initDebug` also registers an `uncaughtException` handler that keeps the process alive, 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/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)
+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`, `snapshot`, `inspect`, `click`, `find`, `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. 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';
+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, $.tree, $.dumpStr(node), $.snapshot([pattern]), $.inspect(path), $.click(path), $.find([pattern], [type]), $.paused, $.gc()
+```
+
+- `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`.
+
+## 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/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/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.1-5",
+  "version": "4.7.1-560",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "godot"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "types": "./gen/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./runtime": "./src/runtime.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"
   },
   "files": [
@@ -20,18 +32,18 @@
   "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_build": "custom_build",
+    "version_full_name": "Godot Engine v4.7.2.stable.custom_build",
     "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-3"
+    "@ringozz/godot-macos-arm64": "^4.7.1-560",
+    "@ringozz/godot-windows-x86_64": "^4.7.1-560",
+    "@ringozz/godot-web-wasm32": "^4.7.1-560"
   },
   "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,41 @@
+/**********************************************************************
+ 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 — 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;
+
+/** 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,27 @@
+/**********************************************************************
+ 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 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.
+
+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;
+}