@ringozz/godot 4.7.2-654 → 4.7.2-659

package/README.md

@@ -53,7 +53,7 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_R`, `_G`, `_P`, `_V`, `toValueType`, `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`, `loadAsset`, `loadAssetPack` (native `.pck` packs) |
-| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per scene |
+| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per level (its scene, or the `.gltfx` its plan lives in) |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -97,7 +97,7 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 
 `godot pack` (the `godot` bin, `@ringozz/godot/pack`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for each source's packed closure and its loose (WebP-backed) textures, and exports native `.pck`s — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
 
-The bake always splits: **one pack per scene, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A project with no scene under its roots gets a single `shared.pck`. What the runtime reads is `.godot/packs/packs.json` beside the packs: which packs exist, which sources each owns, and which loose (WebP-backed) textures the host must stage and transcode per file. The preload plugin mounts the right packs per asset, so importing a level pulls in the shared pack and that level's, nothing else. How the split is decided — and why it needs no configuration — is in `AGENTS.md`.
+The bake always splits: **one pack per level, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A level is its scene — or, in a project that builds levels from their plans at run time, the `.gltfx` its plan lives in; a project with neither under its roots gets a single `shared.pck`. What the runtime reads is `.godot/packs/packs.json` beside the packs: which packs exist, which sources each owns, and which loose sources the host must stage per file (the WebP-backed textures are transcoded; a plan's plain header JSONs are just written). The preload plugin mounts the right packs per asset, so importing a level pulls in the shared pack and that level's, nothing else. How the split is decided — and why it needs no configuration — is in `AGENTS.md`.
 
 ```ts
 import { loadAssetPack } from '@ringozz/godot/load';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-654",
+  "version": "4.7.2-659",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -66,9 +66,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-654",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-654",
-    "@ringozz/godot-web-wasm32": "^4.7.2-654"
+    "@ringozz/godot-macos-arm64": "^4.7.2-659",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-659",
+    "@ringozz/godot-web-wasm32": "^4.7.2-659"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/dump-deps.gd.uid

@@ -0,0 +1 @@
+uid://dfbmw3t660p7v

package/src/pack.ts

@@ -7,6 +7,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveEditor } from './editor.ts';
+import { mergePlanRefs, planRefs } from './planRefs.ts';
 
 // Bakes a Godot project's assets for the runtime: imports them, then exports one native
 // `.pck` **per scene** plus a shared one, so a host fetches the shared data and only the
@@ -84,27 +85,43 @@ interface Dump {
  * reach, or none does, is shared**. A scene whose own pack would be empty is dropped: every
  * source it reaches is reached by another scene too, so it is already in `shared`, and a pack
  * is mounted by *owner*.
+ *
+ * The graph it reads is the dump's *plus* every level's plan refs (`mergePlanRefs`), so a level's
+ * terrain, its layered containers and their layers, and its ground/environment textures are part of
+ * its closure whether or not a baked scene names them. When a project stops baking one scene per
+ * level — a level built from its plan at run time is a single shared scene plus the plan — the level
+ * unit becomes the `.gltfx` its plan lives in instead; until then both units exist and this keying
+ * keeps the scenes.
  */
 export function splitPacks(graph: Graph): AssetPackSplit[] {
-	const stem = (asset: string) => asset.slice(asset.lastIndexOf('/') + 1).replace(/\.[^.]+$/, '');
+	const stem = (asset: string) =>
+		asset.slice(asset.lastIndexOf('/') + 1).replace(/\.(prefab|level)\.[^.]+$/i, '').replace(/\.[^.]+$/, '');
+	// A level is its scene — and, in a project that builds levels from their plans at run time, the
+	// `.gltfx` its plan lives in. A `.gltfx` a scene **reaches** is that scene's composition, not a
+	// second level: keying both would make every source of a baked level look shared.
 	const scenes = Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.tscn')).sort();
-	const closure = new Map(scenes.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
+	const reachedByScene = new Set(scenes.flatMap((s) => graph[s] ?? []));
+	const levels = [
+		...scenes,
+		...Object.keys(graph).filter((s) => s.toLowerCase().endsWith('.gltfx') && !reachedByScene.has(s)),
+	].sort();
+	const closure = new Map(levels.map((s) => [s, new Set([s, ...(graph[s] ?? [])])]));
 
-	// One pack per scene, named after its file stem (`shared` is reserved; a repeated stem —
+	// One pack per level, named after its file stem (`shared` is reserved; a repeated stem —
 	// two `level.tscn` in different directories — gets a suffix).
 	const used = new Set(['shared']);
 	const packOf = new Map<string, AssetPackSplit>();
-	for (const scene of scenes) {
-		let name = stem(scene);
-		for (let n = 2; used.has(name); n++) name = `${stem(scene)}-${n}`;
+	for (const level of levels) {
+		let name = stem(level);
+		for (let n = 2; used.has(name); n++) name = `${stem(level)}-${n}`;
 		used.add(name);
-		packOf.set(scene, { name, owns: [] });
+		packOf.set(level, { name, owns: [] });
 	}
 
 	const shared: string[] = [];
 	const sources = new Set([...Object.keys(graph), ...Object.values(graph).flat()]);
 	for (const source of sources) {
-		const owners = scenes.filter((scene) => closure.get(scene)!.has(source));
+		const owners = levels.filter((level) => closure.get(level)!.has(source));
 		if (owners.length === 1) packOf.get(owners[0])!.owns.push(source);
 		else shared.push(source);
 	}
@@ -138,6 +155,10 @@ export async function buildAssetPacks(opts: BuildAssetPackOptions = {}): Promise
 	const run = runner(editor, cwd);
 	run(['--headless', '--path', '.', '--import']);
 	const { graph, deps } = dump(run, cwd, roots);
+	// A level's plan names what no scene does any more — its terrain directory, its layered containers
+	// and their layers, its ground/environment textures (`planRefs`). Merged here so the graph and the
+	// loose lists carry the level's whole closure with or without a baked scene.
+	mergePlanRefs(graph, deps, planRefs(cwd, roots));
 
 	const packs = splitPacks(graph);
 	const owned = packs.flatMap((pack) => pack.owns);

package/src/planRefs.ts

@@ -0,0 +1,209 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// A level's refs, read from its **plan**. A `.gltfx` level scene carries the converter's derived
+// render state under `extras.wartales.plan`: it names the level's terrain by *directory* and its
+// ground/environment textures by resource route. A host's closure walk cannot see any of it — the
+// routes are relative to the manifest that names them, a layered container's layers are plain text
+// lines, and a runtime script reads the plan dynamically (so no scene names them literally any more).
+// Reading it here keeps a `.gltfx` source's closure complete without a baked scene.
+//
+// Pure filesystem: a project directory plus the `res://` roots a host scans in, the refs out. No
+// engine, no editor — so it is unit-testable and runs before the pack bake.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The refs a `.gltfx`'s plan implies, ready to merge into a dump. */
+export interface PlanRefs {
+	/** The level source's own extra loose refs: its terrain data, layered-container manifests, and the
+	 *  ground/environment textures its plan names. */
+	loose: string[];
+}
+
+// Two of the refs a plan names are plain files rather than imported sources — the terrain's header
+// JSONs, which a plan-built level reads at run time. They are in the level's `loose` list, so a
+// *staging* host writes them; a *pack* needs no help either, because Godot loads a `.json` as a
+// `JSON` resource (verified: `ResourceLoader.exists` is true and the class is `JSON`), so an
+// `all_resources` preset packs it — and since no pack *owns* a source it is not excluded from any,
+// every pack carries those few KB.
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The `extras.wartales.plan` of a parsed gltfx document, or null for a foreign/older document. */
+export function planOf(doc: unknown): Record<string, unknown> | null {
+	if (!isObject(doc) || !isObject(doc.extras)) return null;
+	const w = (doc.extras as Record<string, unknown>)['wartales'];
+	if (!isObject(w) || !isObject(w.plan)) return null;
+	return w.plan as Record<string, unknown>;
+}
+
+/** Every `src/<dir>`-style root as an absolute disk directory, paired with its `res://` prefix. */
+function rootDirs(projectDir: string, roots: string[]): { disk: string; res: string }[] {
+	const out: { disk: string; res: string }[] = [];
+	for (const root of roots) {
+		const rel = root.replace(/^res:\/\//, '');
+		out.push({ disk: join(projectDir, ...rel.split('/')), res: `res://${rel}` });
+	}
+	return out;
+}
+
+/** A path's last segment. */
+const base = (p: string) => p.slice(p.lastIndexOf('/') + 1);
+
+/** Every file under `dir`, as paths relative to `dir` (posix, one level of nesting per entry). */
+function walk(dir: string, prefix = ''): string[] {
+	const out: string[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return out;
+	}
+	for (const name of entries) {
+		if (name.startsWith('.')) continue;
+		const full = join(dir, name);
+		const rel = prefix ? `${prefix}/${name}` : name;
+		try {
+			if (readdirSync(full).length >= 0) {
+				out.push(...walk(full, rel));
+				continue;
+			}
+		} catch {
+			// not a directory
+		}
+		out.push(rel);
+	}
+	return out;
+}
+
+/**
+ * The environment a **host renders**: the level's authored stage — `stages[0].env`, which the plan
+ * also carries as `lighting.env`. A host shows one time of day, so the other stages (a viewer's
+ * blend material) and the reflection probe (which a host does not sample) are not runtime refs.
+ */
+function authoredEnvMap(lighting: Record<string, unknown>): string | null {
+	const stages = Array.isArray(lighting.stages) ? lighting.stages : [];
+	const stage0 = stages.length && isObject(stages[0]) ? (stages[0] as Record<string, unknown>) : null;
+	const env = (stage0 && isObject(stage0.env) ? stage0.env : null) ?? (isObject(lighting.env) ? lighting.env : null);
+	return env && typeof env.map === 'string' ? env.map : null;
+}
+
+/**
+ * The layer file names the `.webparray` manifests in `dir` name, one per line. Those layers are read
+ * by their *importer* and live inside the imported product afterwards, so nothing loads them at run
+ * time: they are import-time inputs, and the directory walk must not stage them.
+ */
+function layerSources(dir: string): Set<string> {
+	const names = new Set<string>();
+	for (const manifest of walk(dir)) {
+		if (!manifest.toLowerCase().endsWith(".webparray")) continue;
+		let text: string;
+		try {
+			text = readFileSync(join(dir, ...manifest.split("/")), "utf8");
+		} catch {
+			continue;
+		}
+		for (const line of text.split("\n")) {
+			const ref = line.trim();
+			if (ref && !ref.startsWith("#")) names.add(base(ref));
+		}
+	}
+	return names;
+}
+
+/** The resource route of a ref the plan names, probing the served `.webp` suffix a texture carries. */
+function routeOf(root: { disk: string; res: string }, route: string): string | null {
+	for (const candidate of [route, `${route}.webp`]) {
+		if (existsSync(join(root.disk, ...candidate.split('/')))) return `${root.res}/${candidate}`;
+	}
+	return null;
+}
+
+/**
+ * Every `.gltfx` under `roots` with its plan-derived refs. A level's terrain is discovered by
+ * *listing* its directory (the tree holds exactly the level's atlas there, so no name list to keep in
+ * step), its manifests' layers are read from the manifests, and its ground/environment textures are
+ * probed per route (a plan route may or may not carry the served `.webp` suffix).
+ */
+export function planRefs(projectDir: string, roots: string[]): Map<string, PlanRefs> {
+	const out = new Map<string, PlanRefs>();
+	for (const root of rootDirs(projectDir, roots)) {
+		for (const file of walk(root.disk)) {
+			if (!file.toLowerCase().endsWith('.gltfx')) continue;
+			let doc: unknown;
+			try {
+				doc = JSON.parse(readFileSync(join(root.disk, ...file.split('/')), 'utf8'));
+			} catch {
+				continue;
+			}
+			const plan = planOf(doc);
+			if (!plan) continue;
+			const levelRoute = `${root.res}/${file}`;
+			const loose = new Set<string>();
+
+			// The terrain: the plan names its directory, and the tree holds exactly the level's own atlas
+			// there (the height and tile-normal maps, the composed weight planes, the passmap and its
+			// meta, the header JSON and the layered containers) — so the directory *is* the list. A
+			// container's *layers* are deliberately not listed: they live inside its imported product,
+			// and are import-time inputs, so nothing stages them at run time.
+			const terrain = isObject(plan.terrain) ? plan.terrain : null;
+			if (terrain && typeof terrain.dir === 'string') {
+				const dir = terrain.dir;
+				const abs = join(root.disk, ...dir.split('/'));
+				const layers = layerSources(abs);
+				for (const name of walk(abs)) {
+					if (name.endsWith(".import") || layers.has(base(name))) continue;
+					loose.add(`${root.res}/${dir}/${name}`);
+				}
+			}
+
+			// The ground's patches and the rig's skies: plain resource routes with the served suffix.
+			const ground = Array.isArray(plan.ground) ? plan.ground : [];
+			for (const g of ground) {
+				if (!isObject(g)) continue;
+				const fields = g.source === 'overlay' ? [isObject(g.material) ? g.material : {}] : [isObject(g.water) ? g.water : {}];
+				for (const f of fields) {
+					for (const key of ['diffuse', 'normal', 'orm']) {
+						if (typeof f[key] !== 'string') continue;
+						const route = routeOf(root, f[key] as string);
+						if (route) loose.add(route);
+					}
+				}
+			}
+			const lighting = isObject(plan.lighting) ? plan.lighting : {};
+			const map = authoredEnvMap(lighting);
+			const route = map ? routeOf(root, map) : null;
+			if (route) loose.add(route);
+
+			out.set(levelRoute, { loose: [...loose].sort() });
+		}
+	}
+	return out;
+}
+
+/**
+ * Merge `planRefs` into a dump's `graph`/`loose` halves: a `.gltfx` source gains its plan's refs, and
+ * so does every source that reaches it (a scene that instances it, so mounting the scene stages the
+ * level's terrain and ground too — a union, and a no-op for a project with no plan).
+ */
+export function mergePlanRefs(
+	graph: Record<string, string[]>,
+	deps: Record<string, string[]>,
+	refs: Map<string, PlanRefs>,
+): void {
+	for (const [level, r] of refs) {
+		if (!(level in graph)) continue;
+		deps[level] = [...new Set([...(deps[level] ?? []), ...r.loose])].sort();
+	}
+	// A scene that instances a `.gltfx` carries that plan's refs too: mounting the scene must stage the
+	// level's terrain and ground, not only its model composition. (The scene may already name some of
+	// them — a baked one does — so this is a union, and a no-op for a project with no plan.)
+	for (const source of Object.keys(graph)) {
+		const plans = graph[source].filter((dep) => refs.has(dep));
+		if (!plans.length || refs.has(source)) continue;
+		const extra = plans.flatMap((p) => refs.get(p)!.loose);
+		deps[source] = [...new Set([...(deps[source] ?? []), ...extra])].sort();
+	}
+}

package/src/web-image.ts

@@ -1,388 +1,388 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-// Web-only compressed-texture (`ctex`) handling. Two container layouts share the
-// same per-image body (`sub-header + level-size table + payloads`):
-//  - `GST2` `CompressedTexture2D` (`.ctex`): one body.
-//  - `GSTL` `CompressedTexture2DArray` / `Cubemap` / `CubemapArray`
-//    (`.ctexarray` / `.ccube` / `.ccubearray`): N bodies of identical geometry.
-// `CompressedTexture3D` (`.ctex3d`) has its own layout and is not handled, and
-// the outer headers are the same size for both (`magic + 8 x u32`), which is why
-// a single parse/allocate pair covers everything — a container is just a list of
-// layers.
-//
-// Exposes the container/format helpers, `pickGodotFormats` (the driver's
-// compressed-format list) and `decodeCtex` — the default staging path, which
-// decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
-// container so no image codec runs in wasm. The optional compressed-transcode
-// hook lives in load.ts.
-
-// Both container layouts share the outer header (magic + 8 x u32) and the
-// per-image sub-header, so an image body's data starts at a fixed offset.
-const OUTER_HEADER_SIZE = 36;
-const SUB_HEADER_SIZE = 16;
-
-const DATA_FORMAT_PNG = 1;
-const DATA_FORMAT_WEBP = 2;
-
-// `Image::Format` targets we emit (`core/io/image.h`). Every compressed target
-// is a 4x4 block format; they differ only in bytes per block, so the size math
-// is a small table rather than a per-format switch.
-export const FORMAT_DXT1 = 17; // BC1
-export const FORMAT_RGTC_R = 20; // BC4
-export const FORMAT_RGTC_RG = 21; // BC5
-export const FORMAT_BPTC_RGBA = 22; // BC7
-export const FORMAT_ETC2_R11 = 26; // EAC R
-export const FORMAT_ETC2_RG11 = 28; // EAC RG
-export const FORMAT_ETC2_RGB8 = 30;
-export const FORMAT_ASTC_4x4 = 35;
-
-// Image-body data starts here: outer header + sub-header.
-export const BLOB_TABLE_OFFSET = OUTER_HEADER_SIZE + SUB_HEADER_SIZE;
-
-const DATA_FORMAT_IMAGE = 0;
-const FORMAT_RGBA8 = 5;
-const RGBA8_PIXEL_SIZE = 4;
-
-const FORMAT_BIT_STREAM = 1 << 22;
-const MAGIC_LAYERED = 0x4c; // 'GSTL'; 'GST2' (0x32) is the single-image layout
-
-// Bytes per 4x4 block for each compressed target; RGBA8 is 4 bytes/pixel.
-const BLOCK_BYTES: Record<number, number> = {
-	[FORMAT_DXT1]: 8,
-	[FORMAT_ETC2_RGB8]: 8,
-	[FORMAT_ETC2_R11]: 8,
-	[FORMAT_RGTC_R]: 8,
-	[FORMAT_RGTC_RG]: 16,
-	[FORMAT_ETC2_RG11]: 16,
-	[FORMAT_BPTC_RGBA]: 16,
-	[FORMAT_ASTC_4x4]: 16,
-};
-
-/**
- * Bytes per 4x4 block of a compressed `Image::Format` target (RGBA8 reports 4,
- * its bytes per pixel). Unknown formats fall back to a 16-byte block.
- */
-export function blockBytes(format: number): number {
-	return format === FORMAT_RGBA8 ? RGBA8_PIXEL_SIZE : (BLOCK_BYTES[format] ?? 16);
-}
-
-export interface CtexLayer {
-	/** `DATA_FORMAT_PNG` (1) / `DATA_FORMAT_WEBP` (2). */
-	dataFormat: number;
-	width: number;
-	height: number;
-	/** Highest mipmap index (total levels = `mipmaps + 1`). */
-	mipmaps: number;
-	/** Per-level payload byte ranges, level 0 first. */
-	levels: { offset: number; size: number }[];
-}
-
-function isLayered(bytes: Uint8Array): boolean {
-	return bytes.length >= OUTER_HEADER_SIZE && bytes[3] === MAGIC_LAYERED;
-}
-
-/**
- * Parses a container into its layers — one for `GST2` (`.ctex`), N for `GSTL`
- * (`.ctexarray`/`.ccube`/`.ccubearray`), in order. Returns `null` for anything
- * else: non-ctex bytes, a streamable container, or payloads that aren't
- * PNG/WebP-embedded (raw / BASIS / VRAM containers pass through untouched), or
- * layers of differing geometry. Throws on a truncated level table so a malformed
- * file fails loudly rather than decoding garbage.
- */
-export function parseCtex(bytes: Uint8Array): CtexLayer[] | null {
-	if (
-		bytes.length < OUTER_HEADER_SIZE + SUB_HEADER_SIZE ||
-		bytes[0] !== 0x47 || // 'G'
-		bytes[1] !== 0x53 || // 'S'
-		bytes[2] !== 0x54 || // 'T'
-		(bytes[3] !== 0x32 && bytes[3] !== MAGIC_LAYERED)
-	) {
-		return null;
-	}
-	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
-		return null; // streamable layout differs; leave it to the engine
-	}
-	const count = isLayered(bytes) ? dv.getUint32(8, true) : 1;
-	const layers: CtexLayer[] = [];
-	let offset = OUTER_HEADER_SIZE;
-	for (let i = 0; i < count; i++) {
-		if (offset + SUB_HEADER_SIZE > bytes.length) {
-			return null;
-		}
-		const dataFormat = dv.getUint32(offset, true);
-		if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
-			return null;
-		}
-		const width = dv.getUint16(offset + 4, true);
-		const height = dv.getUint16(offset + 6, true);
-		const mipmaps = dv.getUint32(offset + 8, true);
-		const levels: { offset: number; size: number }[] = [];
-		let p = offset + SUB_HEADER_SIZE;
-		for (let level = 0; level <= mipmaps; level++) {
-			if (p + 4 > bytes.length) {
-				throw new Error(`web-image: truncated ctex at mipmap ${level}`);
-			}
-			const size = dv.getUint32(p, true);
-			p += 4;
-			if (p + size > bytes.length) {
-				throw new Error(`web-image: truncated ctex blob at mipmap ${level}`);
-			}
-			levels.push({ offset: p, size });
-			p += size;
-		}
-		const first = layers[0];
-		if (first && (width !== first.width || height !== first.height || mipmaps !== first.mipmaps)) {
-			return null; // texture arrays need uniform layer geometry
-		}
-		layers.push({ dataFormat, width, height, mipmaps, levels });
-		offset = p;
-	}
-	return count === 0 ? null : layers;
-}
-
-/** Dimensions of a mipmap level (`max(dim >> level, 1)`). */
-export function mipLevelDimensions(width: number, height: number, level: number): [number, number] {
-	return [Math.max(width >> level, 1), Math.max(height >> level, 1)];
-}
-
-/** Number of levels in the full mip chain down to 1×1 (>= 1). */
-export function mipChainLength(width: number, height: number): number {
-	let levels = 1;
-	while (width > 1 || height > 1) {
-		width = Math.max(1, width >> 1);
-		height = Math.max(1, height >> 1);
-		levels++;
-	}
-	return levels;
-}
-
-// Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
-// levels. RGBA8 is 4 bytes/pixel; compressed targets are 4x4 blocks (8 or 16
-// bytes) whose dimensions round up, matching `Image::_get_dst_image_size`.
-function bodySize(width: number, height: number, mipmaps: number, format: number): number {
-	const rgba8 = format === FORMAT_RGBA8;
-	const block = rgba8 ? 1 : 4;
-	const bytesPerBlock = blockBytes(format);
-	let dataSize = 0;
-	for (let level = 0; level <= mipmaps; level++) {
-		const [w, h] = mipLevelDimensions(width, height, level);
-		dataSize += Math.ceil(w / block) * Math.ceil(h / block) * bytesPerBlock;
-	}
-	return SUB_HEADER_SIZE + dataSize;
-}
-
-/**
- * Allocates a `.ctex` with `count` identical `DATA_FORMAT_IMAGE` bodies (one
- * array, no intermediate copies), reporting `stride` — bytes per body, so layer
- * `i`'s data goes at `BLOB_TABLE_OFFSET + i * stride`. The outer header is kept
- * verbatim (the layer count / layered type are the container's, not ours),
- * except that `GST2` also carries the image dimensions there, which are patched.
- */
-export function allocateCtex(
-	source: Uint8Array,
-	count: number,
-	width: number,
-	height: number,
-	mipmaps: number,
-	format: number,
-): { bytes: Uint8Array; stride: number } {
-	const stride = bodySize(width, height, mipmaps, format);
-	const bytes = new Uint8Array(OUTER_HEADER_SIZE + count * stride);
-	bytes.set(source.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim (version/flags)
-	const dv = new DataView(bytes.buffer);
-	if (!isLayered(source)) {
-		dv.setUint32(8, width, true); // GST2 outer width
-		dv.setUint32(12, height, true); // GST2 outer height
-	}
-	for (let i = 0; i < count; i++) {
-		const offset = OUTER_HEADER_SIZE + i * stride;
-		dv.setUint32(offset, DATA_FORMAT_IMAGE, true);
-		dv.setUint16(offset + 4, width, true);
-		dv.setUint16(offset + 6, height, true);
-		dv.setUint32(offset + 8, mipmaps, true);
-		dv.setUint32(offset + 12, format, true);
-	}
-	return { bytes, stride };
-}
-
-// ---------------------------------------------------------------------------
-// Capability probing. GLES3 uploads a compressed format only when its config
-// reports it supported, and this build compiles in NO decompressors, so a format
-// the device can't upload breaks the texture rather than degrading. Ask the
-// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
-// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
-// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
-// layered differ — `_texture_set_data` force-decompresses them for
-// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
-// ---------------------------------------------------------------------------
-
-// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
-// encoder can emit; only the unsigned-normal variants (their siblings share it).
-const GL_TO_GODOT_FORMAT: Record<number, number> = {
-	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
-	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
-	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
-	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
-	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
-	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
-	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
-	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
-};
-
-/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
-const PROBED_EXTENSIONS = [
-	'EXT_texture_compression_bptc',
-	'EXT_texture_compression_rgtc',
-	'WEBGL_compressed_texture_s3tc',
-	'WEBGL_compressed_texture_astc',
-	'WEBGL_compressed_texture_etc',
-];
-
-/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
-export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
-	const formats = new Set<number>();
-	for (let i = 0; i < glFormats.length; i++) {
-		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
-		if (godot !== undefined) {
-			formats.add(godot);
-		}
-	}
-	return [...formats];
-}
-
-/**
- * Compressed `Image::Format` targets the running device can upload. A list
- * because the encoder may also reject a format the browser exposes (e.g. spark
- * skips BC on iOS); the caller intersects it with spark's supported set, and
- * order here is not significant (the encoder has its own preference chain).
- */
-export function pickGodotFormats(): number[] {
-	let gl: WebGL2RenderingContext | null = null;
-	try {
-		// Prefer a DOM canvas (works everywhere WebGL2 does); fall back to
-		// OffscreenCanvas for worker contexts.
-		const canvas =
-			typeof document !== 'undefined'
-				? document.createElement('canvas')
-				: typeof OffscreenCanvas !== 'undefined'
-					? new OffscreenCanvas(1, 1)
-					: null;
-		gl = (canvas?.getContext('webgl2', {
-			antialias: false,
-			depth: false,
-			stencil: false,
-			alpha: false,
-		}) ?? null) as WebGL2RenderingContext | null;
-	} catch {
-		gl = null;
-	}
-	if (!gl) {
-		return [];
-	}
-	try {
-		for (const name of PROBED_EXTENSIONS) {
-			gl.getExtension(name);
-		}
-		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
-	} finally {
-		// Don't retain the probe context for the page's lifetime.
-		gl.getExtension('WEBGL_lose_context')?.loseContext();
-	}
-}
-
-/**
- * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
- * (staging then keeps the raw RGBA8 decode). `path` is the resource path being
- * staged, so a platform transcoder can pick a block format from the file name.
- * Produced by `transcoder*.ts` and installed by `load.ts`'s staging.
- */
-export type CtexTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
-
-/**
- * Decodes the embedded PNG/WebP payloads of a `.ctex` with the browser's
- * `createImageBitmap` and rebuilds it as raw RGBA8 (`DATA_FORMAT_IMAGE`) — for
- * `GST2` and for each layer of a `GSTL` array/cubemap. Non-ctex bytes,
- * streamable containers, and `DATA_FORMAT_IMAGE` / `DATA_FORMAT_BASIS_UNIVERSAL`
- * containers are returned unchanged. Throws if an embedded payload 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`). Levels are decoded concurrently and written
- * straight into the output container (no per-level array).
- */
-export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
-	if (typeof createImageBitmap !== 'function') {
-		return bytes;
-	}
-	const layers = parseCtex(bytes);
-	if (!layers) {
-		return bytes;
-	}
-	const { width, height, mipmaps } = layers[0];
-	const { bytes: out, stride } = allocateCtex(bytes, layers.length, width, height, mipmaps, FORMAT_RGBA8);
-	for (let i = 0; i < layers.length; i++) {
-		await rasterizeLevels(bytes, layers[i], out, BLOB_TABLE_OFFSET + i * stride);
-	}
-	return out;
-}
-
-/**
- * Decodes one PNG/WebP payload into an `ImageBitmap` (level 0 for an encoder,
- * every level for {@link decodeCtex}). Pixel values are handed over unchanged
- * (`colorSpaceConversion`/`premultiplyAlpha` off).
- */
-export function payloadBitmap(
-	bytes: Uint8Array,
-	dataFormat: number,
-	level: { offset: number; size: number },
-): Promise<ImageBitmap> {
-	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
-	// The Blob ctor needs an ArrayBuffer-backed view.
-	return createImageBitmap(
-		new Blob([bytes.subarray(level.offset, level.offset + level.size) as Uint8Array<ArrayBuffer>], { type }),
-		{ colorSpaceConversion: 'none', premultiplyAlpha: 'none' },
-	);
-}
-
-// Decodes a layer's PNG/WebP levels and rasterizes them into `out` at
-// `outOffset`, reusing one canvas across levels.
-async function rasterizeLevels(bytes: Uint8Array, layer: CtexLayer, out: Uint8Array, outOffset: number): Promise<void> {
-	const { width, height } = layer;
-	const bitmaps = await Promise.all(layer.levels.map((l) => payloadBitmap(bytes, layer.dataFormat, l)));
-	const canvas = new OffscreenCanvas(width, height);
-	try {
-		let p = outOffset;
-		for (let i = 0; i < bitmaps.length; i++) {
-			const [lw, lh] = mipLevelDimensions(width, height, i);
-			const bmp = bitmaps[i];
-			if (bmp.width !== lw || bmp.height !== lh) {
-				throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${lw}x${lh}`);
-			}
-			out.set(rasterize(canvas, bmp), p);
-			p += lw * lh * RGBA8_PIXEL_SIZE;
-		}
-	} finally {
-		// close() on an already-closed bitmap is a no-op.
-		for (const bmp of bitmaps) {
-			bmp.close();
-		}
-	}
-}
-
-// Rasterizes an ImageBitmap into a raw RGBA8 view, drawing into the caller's
-// shared canvas (resized per level) so one canvas serves every mipmap.
-function rasterize(canvas: OffscreenCanvas, bmp: ImageBitmap): Uint8Array {
-	const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
-		| OffscreenCanvasRenderingContext2D
-		| null;
-	if (!ctx) {
-		throw new Error('web-image: no 2d context for OffscreenCanvas');
-	}
-	canvas.width = bmp.width;
-	canvas.height = bmp.height;
-	ctx.drawImage(bmp, 0, 0);
-	const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
-	return new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength);
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Web-only compressed-texture (`ctex`) handling. Two container layouts share the
+// same per-image body (`sub-header + level-size table + payloads`):
+//  - `GST2` `CompressedTexture2D` (`.ctex`): one body.
+//  - `GSTL` `CompressedTexture2DArray` / `Cubemap` / `CubemapArray`
+//    (`.ctexarray` / `.ccube` / `.ccubearray`): N bodies of identical geometry.
+// `CompressedTexture3D` (`.ctex3d`) has its own layout and is not handled, and
+// the outer headers are the same size for both (`magic + 8 x u32`), which is why
+// a single parse/allocate pair covers everything — a container is just a list of
+// layers.
+//
+// Exposes the container/format helpers, `pickGodotFormats` (the driver's
+// compressed-format list) and `decodeCtex` — the default staging path, which
+// decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
+// container so no image codec runs in wasm. The optional compressed-transcode
+// hook lives in load.ts.
+
+// Both container layouts share the outer header (magic + 8 x u32) and the
+// per-image sub-header, so an image body's data starts at a fixed offset.
+const OUTER_HEADER_SIZE = 36;
+const SUB_HEADER_SIZE = 16;
+
+const DATA_FORMAT_PNG = 1;
+const DATA_FORMAT_WEBP = 2;
+
+// `Image::Format` targets we emit (`core/io/image.h`). Every compressed target
+// is a 4x4 block format; they differ only in bytes per block, so the size math
+// is a small table rather than a per-format switch.
+export const FORMAT_DXT1 = 17; // BC1
+export const FORMAT_RGTC_R = 20; // BC4
+export const FORMAT_RGTC_RG = 21; // BC5
+export const FORMAT_BPTC_RGBA = 22; // BC7
+export const FORMAT_ETC2_R11 = 26; // EAC R
+export const FORMAT_ETC2_RG11 = 28; // EAC RG
+export const FORMAT_ETC2_RGB8 = 30;
+export const FORMAT_ASTC_4x4 = 35;
+
+// Image-body data starts here: outer header + sub-header.
+export const BLOB_TABLE_OFFSET = OUTER_HEADER_SIZE + SUB_HEADER_SIZE;
+
+const DATA_FORMAT_IMAGE = 0;
+const FORMAT_RGBA8 = 5;
+const RGBA8_PIXEL_SIZE = 4;
+
+const FORMAT_BIT_STREAM = 1 << 22;
+const MAGIC_LAYERED = 0x4c; // 'GSTL'; 'GST2' (0x32) is the single-image layout
+
+// Bytes per 4x4 block for each compressed target; RGBA8 is 4 bytes/pixel.
+const BLOCK_BYTES: Record<number, number> = {
+	[FORMAT_DXT1]: 8,
+	[FORMAT_ETC2_RGB8]: 8,
+	[FORMAT_ETC2_R11]: 8,
+	[FORMAT_RGTC_R]: 8,
+	[FORMAT_RGTC_RG]: 16,
+	[FORMAT_ETC2_RG11]: 16,
+	[FORMAT_BPTC_RGBA]: 16,
+	[FORMAT_ASTC_4x4]: 16,
+};
+
+/**
+ * Bytes per 4x4 block of a compressed `Image::Format` target (RGBA8 reports 4,
+ * its bytes per pixel). Unknown formats fall back to a 16-byte block.
+ */
+export function blockBytes(format: number): number {
+	return format === FORMAT_RGBA8 ? RGBA8_PIXEL_SIZE : (BLOCK_BYTES[format] ?? 16);
+}
+
+export interface CtexLayer {
+	/** `DATA_FORMAT_PNG` (1) / `DATA_FORMAT_WEBP` (2). */
+	dataFormat: number;
+	width: number;
+	height: number;
+	/** Highest mipmap index (total levels = `mipmaps + 1`). */
+	mipmaps: number;
+	/** Per-level payload byte ranges, level 0 first. */
+	levels: { offset: number; size: number }[];
+}
+
+function isLayered(bytes: Uint8Array): boolean {
+	return bytes.length >= OUTER_HEADER_SIZE && bytes[3] === MAGIC_LAYERED;
+}
+
+/**
+ * Parses a container into its layers — one for `GST2` (`.ctex`), N for `GSTL`
+ * (`.ctexarray`/`.ccube`/`.ccubearray`), in order. Returns `null` for anything
+ * else: non-ctex bytes, a streamable container, or payloads that aren't
+ * PNG/WebP-embedded (raw / BASIS / VRAM containers pass through untouched), or
+ * layers of differing geometry. Throws on a truncated level table so a malformed
+ * file fails loudly rather than decoding garbage.
+ */
+export function parseCtex(bytes: Uint8Array): CtexLayer[] | null {
+	if (
+		bytes.length < OUTER_HEADER_SIZE + SUB_HEADER_SIZE ||
+		bytes[0] !== 0x47 || // 'G'
+		bytes[1] !== 0x53 || // 'S'
+		bytes[2] !== 0x54 || // 'T'
+		(bytes[3] !== 0x32 && bytes[3] !== MAGIC_LAYERED)
+	) {
+		return null;
+	}
+	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
+		return null; // streamable layout differs; leave it to the engine
+	}
+	const count = isLayered(bytes) ? dv.getUint32(8, true) : 1;
+	const layers: CtexLayer[] = [];
+	let offset = OUTER_HEADER_SIZE;
+	for (let i = 0; i < count; i++) {
+		if (offset + SUB_HEADER_SIZE > bytes.length) {
+			return null;
+		}
+		const dataFormat = dv.getUint32(offset, true);
+		if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
+			return null;
+		}
+		const width = dv.getUint16(offset + 4, true);
+		const height = dv.getUint16(offset + 6, true);
+		const mipmaps = dv.getUint32(offset + 8, true);
+		const levels: { offset: number; size: number }[] = [];
+		let p = offset + SUB_HEADER_SIZE;
+		for (let level = 0; level <= mipmaps; level++) {
+			if (p + 4 > bytes.length) {
+				throw new Error(`web-image: truncated ctex at mipmap ${level}`);
+			}
+			const size = dv.getUint32(p, true);
+			p += 4;
+			if (p + size > bytes.length) {
+				throw new Error(`web-image: truncated ctex blob at mipmap ${level}`);
+			}
+			levels.push({ offset: p, size });
+			p += size;
+		}
+		const first = layers[0];
+		if (first && (width !== first.width || height !== first.height || mipmaps !== first.mipmaps)) {
+			return null; // texture arrays need uniform layer geometry
+		}
+		layers.push({ dataFormat, width, height, mipmaps, levels });
+		offset = p;
+	}
+	return count === 0 ? null : layers;
+}
+
+/** Dimensions of a mipmap level (`max(dim >> level, 1)`). */
+export function mipLevelDimensions(width: number, height: number, level: number): [number, number] {
+	return [Math.max(width >> level, 1), Math.max(height >> level, 1)];
+}
+
+/** Number of levels in the full mip chain down to 1×1 (>= 1). */
+export function mipChainLength(width: number, height: number): number {
+	let levels = 1;
+	while (width > 1 || height > 1) {
+		width = Math.max(1, width >> 1);
+		height = Math.max(1, height >> 1);
+		levels++;
+	}
+	return levels;
+}
+
+// Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
+// levels. RGBA8 is 4 bytes/pixel; compressed targets are 4x4 blocks (8 or 16
+// bytes) whose dimensions round up, matching `Image::_get_dst_image_size`.
+function bodySize(width: number, height: number, mipmaps: number, format: number): number {
+	const rgba8 = format === FORMAT_RGBA8;
+	const block = rgba8 ? 1 : 4;
+	const bytesPerBlock = blockBytes(format);
+	let dataSize = 0;
+	for (let level = 0; level <= mipmaps; level++) {
+		const [w, h] = mipLevelDimensions(width, height, level);
+		dataSize += Math.ceil(w / block) * Math.ceil(h / block) * bytesPerBlock;
+	}
+	return SUB_HEADER_SIZE + dataSize;
+}
+
+/**
+ * Allocates a `.ctex` with `count` identical `DATA_FORMAT_IMAGE` bodies (one
+ * array, no intermediate copies), reporting `stride` — bytes per body, so layer
+ * `i`'s data goes at `BLOB_TABLE_OFFSET + i * stride`. The outer header is kept
+ * verbatim (the layer count / layered type are the container's, not ours),
+ * except that `GST2` also carries the image dimensions there, which are patched.
+ */
+export function allocateCtex(
+	source: Uint8Array,
+	count: number,
+	width: number,
+	height: number,
+	mipmaps: number,
+	format: number,
+): { bytes: Uint8Array; stride: number } {
+	const stride = bodySize(width, height, mipmaps, format);
+	const bytes = new Uint8Array(OUTER_HEADER_SIZE + count * stride);
+	bytes.set(source.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim (version/flags)
+	const dv = new DataView(bytes.buffer);
+	if (!isLayered(source)) {
+		dv.setUint32(8, width, true); // GST2 outer width
+		dv.setUint32(12, height, true); // GST2 outer height
+	}
+	for (let i = 0; i < count; i++) {
+		const offset = OUTER_HEADER_SIZE + i * stride;
+		dv.setUint32(offset, DATA_FORMAT_IMAGE, true);
+		dv.setUint16(offset + 4, width, true);
+		dv.setUint16(offset + 6, height, true);
+		dv.setUint32(offset + 8, mipmaps, true);
+		dv.setUint32(offset + 12, format, true);
+	}
+	return { bytes, stride };
+}
+
+// ---------------------------------------------------------------------------
+// Capability probing. GLES3 uploads a compressed format only when its config
+// reports it supported, and this build compiles in NO decompressors, so a format
+// the device can't upload breaks the texture rather than degrading. Ask the
+// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
+// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
+// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
+// layered differ — `_texture_set_data` force-decompresses them for
+// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
+// ---------------------------------------------------------------------------
+
+// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
+// encoder can emit; only the unsigned-normal variants (their siblings share it).
+const GL_TO_GODOT_FORMAT: Record<number, number> = {
+	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
+	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
+	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
+	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
+	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
+	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
+	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
+};
+
+/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
+const PROBED_EXTENSIONS = [
+	'EXT_texture_compression_bptc',
+	'EXT_texture_compression_rgtc',
+	'WEBGL_compressed_texture_s3tc',
+	'WEBGL_compressed_texture_astc',
+	'WEBGL_compressed_texture_etc',
+];
+
+/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
+export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
+	const formats = new Set<number>();
+	for (let i = 0; i < glFormats.length; i++) {
+		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
+		if (godot !== undefined) {
+			formats.add(godot);
+		}
+	}
+	return [...formats];
+}
+
+/**
+ * Compressed `Image::Format` targets the running device can upload. A list
+ * because the encoder may also reject a format the browser exposes (e.g. spark
+ * skips BC on iOS); the caller intersects it with spark's supported set, and
+ * order here is not significant (the encoder has its own preference chain).
+ */
+export function pickGodotFormats(): number[] {
+	let gl: WebGL2RenderingContext | null = null;
+	try {
+		// Prefer a DOM canvas (works everywhere WebGL2 does); fall back to
+		// OffscreenCanvas for worker contexts.
+		const canvas =
+			typeof document !== 'undefined'
+				? document.createElement('canvas')
+				: typeof OffscreenCanvas !== 'undefined'
+					? new OffscreenCanvas(1, 1)
+					: null;
+		gl = (canvas?.getContext('webgl2', {
+			antialias: false,
+			depth: false,
+			stencil: false,
+			alpha: false,
+		}) ?? null) as WebGL2RenderingContext | null;
+	} catch {
+		gl = null;
+	}
+	if (!gl) {
+		return [];
+	}
+	try {
+		for (const name of PROBED_EXTENSIONS) {
+			gl.getExtension(name);
+		}
+		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
+	} finally {
+		// Don't retain the probe context for the page's lifetime.
+		gl.getExtension('WEBGL_lose_context')?.loseContext();
+	}
+}
+
+/**
+ * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
+ * (staging then keeps the raw RGBA8 decode). `path` is the resource path being
+ * staged, so a platform transcoder can pick a block format from the file name.
+ * Produced by `transcoder*.ts` and installed by `load.ts`'s staging.
+ */
+export type CtexTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
+
+/**
+ * Decodes the embedded PNG/WebP payloads of a `.ctex` with the browser's
+ * `createImageBitmap` and rebuilds it as raw RGBA8 (`DATA_FORMAT_IMAGE`) — for
+ * `GST2` and for each layer of a `GSTL` array/cubemap. Non-ctex bytes,
+ * streamable containers, and `DATA_FORMAT_IMAGE` / `DATA_FORMAT_BASIS_UNIVERSAL`
+ * containers are returned unchanged. Throws if an embedded payload 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`). Levels are decoded concurrently and written
+ * straight into the output container (no per-level array).
+ */
+export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+	if (typeof createImageBitmap !== 'function') {
+		return bytes;
+	}
+	const layers = parseCtex(bytes);
+	if (!layers) {
+		return bytes;
+	}
+	const { width, height, mipmaps } = layers[0];
+	const { bytes: out, stride } = allocateCtex(bytes, layers.length, width, height, mipmaps, FORMAT_RGBA8);
+	for (let i = 0; i < layers.length; i++) {
+		await rasterizeLevels(bytes, layers[i], out, BLOB_TABLE_OFFSET + i * stride);
+	}
+	return out;
+}
+
+/**
+ * Decodes one PNG/WebP payload into an `ImageBitmap` (level 0 for an encoder,
+ * every level for {@link decodeCtex}). Pixel values are handed over unchanged
+ * (`colorSpaceConversion`/`premultiplyAlpha` off).
+ */
+export function payloadBitmap(
+	bytes: Uint8Array,
+	dataFormat: number,
+	level: { offset: number; size: number },
+): Promise<ImageBitmap> {
+	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
+	// The Blob ctor needs an ArrayBuffer-backed view.
+	return createImageBitmap(
+		new Blob([bytes.subarray(level.offset, level.offset + level.size) as Uint8Array<ArrayBuffer>], { type }),
+		{ colorSpaceConversion: 'none', premultiplyAlpha: 'none' },
+	);
+}
+
+// Decodes a layer's PNG/WebP levels and rasterizes them into `out` at
+// `outOffset`, reusing one canvas across levels.
+async function rasterizeLevels(bytes: Uint8Array, layer: CtexLayer, out: Uint8Array, outOffset: number): Promise<void> {
+	const { width, height } = layer;
+	const bitmaps = await Promise.all(layer.levels.map((l) => payloadBitmap(bytes, layer.dataFormat, l)));
+	const canvas = new OffscreenCanvas(width, height);
+	try {
+		let p = outOffset;
+		for (let i = 0; i < bitmaps.length; i++) {
+			const [lw, lh] = mipLevelDimensions(width, height, i);
+			const bmp = bitmaps[i];
+			if (bmp.width !== lw || bmp.height !== lh) {
+				throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${lw}x${lh}`);
+			}
+			out.set(rasterize(canvas, bmp), p);
+			p += lw * lh * RGBA8_PIXEL_SIZE;
+		}
+	} finally {
+		// close() on an already-closed bitmap is a no-op.
+		for (const bmp of bitmaps) {
+			bmp.close();
+		}
+	}
+}
+
+// Rasterizes an ImageBitmap into a raw RGBA8 view, drawing into the caller's
+// shared canvas (resized per level) so one canvas serves every mipmap.
+function rasterize(canvas: OffscreenCanvas, bmp: ImageBitmap): Uint8Array {
+	const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
+		| OffscreenCanvasRenderingContext2D
+		| null;
+	if (!ctx) {
+		throw new Error('web-image: no 2d context for OffscreenCanvas');
+	}
+	canvas.width = bmp.width;
+	canvas.height = bmp.height;
+	ctx.drawImage(bmp, 0, 0);
+	const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
+	return new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength);
+}