@ringozz/godot 4.7.1-7 → 4.7.1-8

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

@@ -1,68 +1,72 @@
-/**********************************************************************
- 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'));
-
-/** 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;
-
-/** 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.
+***********************************************************************/
+
+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);
+}

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;
+}