@ringozz/godot 4.7.1-8 → 4.7.2-570

package/src/preload.ts

@@ -1,198 +1,216 @@
-/**********************************************************************
- 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);
+/**********************************************************************
+ 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: 'CompressedTexture2D' },
+	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 },
+	ttf: { cls: 'FontFile' },
+	otf: { cls: 'FontFile' },
+	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) => {
+			// Only JS module imports of Godot source assets become `godot`
+			// modules. `Bun.build` reports JS imports as `import-statement`
+			// (and `dynamic-import`/`require-*`) but HTML asset references
+			// (<link>/<img>) and CSS url() refs as `internal`/`url-token` —
+			// those fall through so Bun copies/hashes the file normally. The
+			// runtime preload (bun run / bun test) reports JS imports with no
+			// kind (`undefined`), so treat that as a JS import too.
+			if (
+				args.kind !== undefined &&
+				args.kind !== 'import-statement' &&
+				args.kind !== 'dynamic-import' &&
+				args.kind !== 'require-call' &&
+				args.kind !== 'require-resolve'
+			) {
+				return;
+			}
+			const importerAbs = args.importer?.startsWith(`${NS}:`)
+				? args.importer.slice(NS.length + 1)
+				: args.importer;
+			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

@@ -1,72 +1,84 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-const { platform, arch } = globalThis.process ?? {};
-const mapping: any = {
-    'darwin-arm64': 'macos-arm64',
-    'win32-x64': 'windows-x86_64',
-};
-
-import { getNativeModule } from './boot.ts';
-const { default: _mod } = getNativeModule() ?? import.meta.require(`@ringozz/godot-${mapping[`${platform}-${arch}`]}`);
-
-/** Godot instance */
-import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
-export const getGodot = _mod.getGodot as () => GodotInstance;
-
-/** Base constructor for all Godot object wrappers. */
-export interface GodotVar {
-    free(): void;
-}
-export const GodotVar = _mod.GodotVar as (new (...args: unknown[]) => GodotVar) & {
-    assign<T extends GodotVar>(target: T, props: Record<string, unknown>): T;
-};
-
-/** Unified entry point:
- *  - _C(this,    methodId, ...args)    → instance method
- *  - _C(classId, methodId, ...args)    → static method
- *  - _C(null,    methodId, ...args)    → singleton lookup (_getInstance) or internal
- *  - _C(0xHASHn, methodId, ...args)    → utility function (BigInt carries hash + type metadata)
- */
-export const _C = _mod._C as (...args: unknown[]) => unknown;
-
-/** Resolve a string name to its integer handle. */
-export const _S = _mod._S as (name: string) => number;
-
-/** Low-level property getter for value type fields. */
-export const _get = _mod._get as (target: GodotVar, nameId: number) => unknown;
-
-/** Low-level property setter for value type fields. */
-export const _set = _mod._set as (target: GodotVar, nameId: number, val: unknown) => void;
-
-/** 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;
-
-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/requestAnimationFrame) */
-export const requestAnimationFrame = _mod.requestAnimationFrame as typeof globalThis.requestAnimationFrame ?? globalThis.requestAnimationFrame;
-
-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/cancelAnimationFrame) */
-export const cancelAnimationFrame = _mod.cancelAnimationFrame as typeof globalThis.cancelAnimationFrame ?? globalThis.cancelAnimationFrame;
-
-/** Make a Signal PromiseLike: connects a one-shot callback that resolves with the args tuple. */
-export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
-    return new Promise<any>((resolve, reject) => {
-        if (signal.isNull()) {
-            reject(new Error('Cannot await a null Signal'));
-            return;
-        }
-        const cb = (...args: any[]) => {
-            signal.disconnect(cb);
-            resolve(args);
-        };
-        const res = signal.connect(cb);
-        if (res !== 0) reject(new Error('Failed to connect signal: error code ' + res));
-    }).then(onfulfilled, onrejected);
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+/** Shared runtime: platform-specific native-module selection lives in
+ *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the `exports` `./boot`
+ *  entry's `browser` condition). `_mod` is the native module — the desktop
+ *  addon's `module.exports` or the wasm module's `.default`.
+ *
+ *  The boot leaf is imported by **package self-reference** (`@ringozz/godot/boot`),
+ *  not by relative path: a bare specifier resolves through this package's own
+ *  `exports` map (whose `./boot` entry's `browser` condition selects
+ *  `boot.browser.ts` on web) exactly like the entrypoint's
+ *  `import { preloadGodot } from '@ringozz/godot/boot'`, so both sides land on the
+ *  same absolute path and share ONE `boot.browser.ts` module instance. (A relative
+ *  `./boot.ts` import would let a consumer's bundler realpath it into
+ *  `node_modules/.bun/...` while the entrypoint keeps the `node_modules/@ringozz/godot`
+ *  path — two instances, and the preload handoff below would read `null`.)
+ */
+import { getNativeModule } from '@ringozz/godot/boot';
+const { default: _mod } = getNativeModule() as any;
+
+/** Godot instance */
+import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
+export const getGodot = _mod.getGodot as () => GodotInstance;
+
+/** Base constructor for all Godot object wrappers. */
+export interface GodotVar {
+    free(): void;
+}
+export const GodotVar = _mod.GodotVar as (new (...args: unknown[]) => GodotVar) & {
+    assign<T extends GodotVar>(target: T, props: Record<string, unknown>): T;
+};
+
+/** Unified entry point:
+ *  - _C(this,    methodId, ...args)    → instance method
+ *  - _C(classId, methodId, ...args)    → static method
+ *  - _C(null,    methodId, ...args)    → singleton lookup (_getInstance) or internal
+ *  - _C(0xHASHn, methodId, ...args)    → utility function (BigInt carries hash + type metadata)
+ */
+export const _C = _mod._C as (...args: unknown[]) => unknown;
+
+/** Resolve a string name to its integer handle. */
+export const _S = _mod._S as (name: string) => number;
+
+/** Low-level property getter for value type fields. */
+export const _get = _mod._get as (target: GodotVar, nameId: number) => unknown;
+
+/** Low-level property setter for value type fields. */
+export const _set = _mod._set as (target: GodotVar, nameId: number, val: unknown) => void;
+
+/** 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;
+
+/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/requestAnimationFrame) */
+export const requestAnimationFrame = _mod.requestAnimationFrame as typeof globalThis.requestAnimationFrame ?? globalThis.requestAnimationFrame;
+
+/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/cancelAnimationFrame) */
+export const cancelAnimationFrame = _mod.cancelAnimationFrame as typeof globalThis.cancelAnimationFrame ?? globalThis.cancelAnimationFrame;
+
+/** Make a Signal PromiseLike: connects a one-shot callback that resolves with the args tuple. */
+export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
+    return new Promise<any>((resolve, reject) => {
+        if (signal.isNull()) {
+            reject(new Error('Cannot await a null Signal'));
+            return;
+        }
+        const cb = (...args: any[]) => {
+            signal.disconnect(cb);
+            resolve(args);
+        };
+        const res = signal.connect(cb);
+        if (res !== 0) reject(new Error('Failed to connect signal: error code ' + res));
+    }).then(onfulfilled, onrejected);
+}
+
+/** Cleanup callbacks run once by `runGodot` just before the engine is freed; may be async. */
+export const cleanupHooks: Set<() => void | Promise<void>> = new Set();