@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/app/src/shared/feature-log.js

@@ -0,0 +1,54 @@
+// ============================================================================
+// Host-process feature log — collects OS/CPU/RAM/runtime/flags/GPU identity
+// ============================================================================
+//
+// Synchronous collector for the `dd-host|...` startup line — used by the
+// native host bridge. GPU identity is passed in by the caller (wgpu adapter
+// info); otherwise the fields are omitted and the renderer's WebGPU adapter
+// line carries GPU identity.
+// ============================================================================
+import { condenseText, formatBytesShort } from "@downdraft/engine/util/feature-log";
+import { ENGINE_VERSION } from "@downdraft/engine/version";
+import os from "node:os";
+/**
+ * Collect the host-process feature log data. Synchronous; safe to call at
+ * startup. Returns the data (callers cache it if they want to serve it later).
+ */
+export function collectHostFeatureLog(opts) {
+    const { isDev, deterministic, flags } = opts;
+    const versions = process.versions;
+    const cpus = os.cpus();
+    const cpuModel = cpus.length > 0 ? cpus[0].model : "";
+    const data = {
+        sv: 1,
+        scope: opts.scope ?? "host",
+        v: ENGINE_VERSION,
+        mode: deterministic ? "deterministic" : isDev ? "dev" : "packaged",
+        os: process.platform,
+        osRel: os.release(),
+        arch: process.arch,
+        cpu: condenseText(cpuModel, 48),
+        cpuCores: cpus.length,
+        mem: formatBytesShort(os.totalmem()),
+        node: versions.node,
+        v8: versions.v8,
+        sw: flags.length > 0 ? flags.join(",") : undefined,
+    };
+    // GPU identity (best-effort, provided by the caller).
+    if (opts.gpuDevice)
+        data.gpu = condenseText(opts.gpuDevice, 48);
+    if (opts.gpuDriverVersion)
+        data.drv = condenseText(opts.gpuDriverVersion, 32);
+    // Runtime tag — distinguishes bun/node/deno hosts in combined views.
+    data.rt = opts.runtime ?? runtimeTag();
+    return data;
+}
+/** Detect the JS runtime for the feature log's `rt` field. */
+function runtimeTag() {
+    const p = process;
+    if (typeof p.bun !== "undefined" || process.versions.bun)
+        return "bun";
+    if (globalThis.Deno)
+        return "deno";
+    return "node";
+}

package/dist/app/src/shared/gpu-info.js

@@ -0,0 +1,74 @@
+// ============================================================================
+// GPU system info helpers for the native (Bun/Node) host bridge.
+//
+// nvidia-smi is queried via child_process; Vulkan validation
+// status reads environment variables. Importable from any process — the only
+// hard requirement is that `nvidia-smi` exists on PATH (returns null when it
+// does not, e.g. non-NVIDIA systems).
+// ============================================================================
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+let cachedGpuInfo = null;
+const GPU_INFO_CACHE_MS = 1000;
+/**
+ * Query GPU utilization/memory/temperature via `nvidia-smi`. Cached for 1s.
+ * Returns null when nvidia-smi is absent or errors (AMD/Intel GPUs, CI).
+ */
+export async function queryNvidiaSmi() {
+    const now = Date.now();
+    if (cachedGpuInfo && now - cachedGpuInfo.ts < GPU_INFO_CACHE_MS) {
+        return cachedGpuInfo.data;
+    }
+    try {
+        const gpuQuery = "utilization.gpu,memory.used,memory.total,temperature.gpu,power.draw,clocks.sm,clocks.mem,name,driver_version";
+        const { stdout: output } = await execFileAsync("nvidia-smi", [
+            "--query-gpu", gpuQuery,
+            "--format", "csv,noheader,nounits",
+        ], { timeout: 3000, encoding: "utf-8" });
+        const labels = gpuQuery.split(",").map(l => l.replace(/\./g, "_"));
+        const gpus = output.trim().split("\n").map((line) => {
+            const vals = line.trim().split(",").map((v) => v.trim());
+            const obj = {};
+            for (let i = 0; i < labels.length && i < vals.length; i++) {
+                const num = parseFloat(vals[i]);
+                obj[labels[i]] = isNaN(num) ? vals[i] : num;
+            }
+            return obj;
+        });
+        let processes = [];
+        try {
+            const { stdout: procOutput } = await execFileAsync("nvidia-smi", [
+                "--query-compute-apps", "pid,process_name,used_memory",
+                "--format", "csv,noheader,nounits",
+            ], { timeout: 3000, encoding: "utf-8" });
+            const procStr = procOutput.trim();
+            if (procStr) {
+                processes = procStr.split("\n").map((line) => {
+                    const vals = line.trim().split(",").map((v) => v.trim());
+                    return {
+                        pid: parseInt(vals[0]) || 0,
+                        processName: vals[1] || "",
+                        usedMemoryMB: parseFloat(vals[2]) || 0,
+                    };
+                });
+            }
+        }
+        catch {
+            // nvidia-smi process query not available
+        }
+        const data = { gpus, processes, source: "nvidia-smi", timestamp: Date.now() };
+        cachedGpuInfo = { data, ts: Date.now() };
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether Vulkan validation layers were requested via env. */
+export function getVulkanValidationStatus() {
+    const enabled = process.env.VK_LAYER_KHRONOS_validation === "1" ||
+        process.env.VK_LAYER_KHRONOS_validation === "true" ||
+        process.env.ENABLE_VULKAN_VALIDATION === "1";
+    return { enabled, envVar: process.env.VK_LAYER_KHRONOS_VALIDATION ?? null };
+}

package/dist/app/src/shared/import-cache-store.js

@@ -0,0 +1,123 @@
+// ============================================================================
+// Import cache store — SQLite-backed cache for resolved ImportSettings
+// ============================================================================
+//
+// Storage layer used by the native host bridge. Uses node:sqlite (stable in
+// Node 24+, implemented by Bun ≥1.1). If node:sqlite is unavailable, falls
+// back to an in-memory Map (no persistence across restarts).
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger("info");
+/**
+ * Open (or create) the import cache at `dbPath`. Falls back to an in-memory
+ * store when node:sqlite is unavailable.
+ */
+export function createImportCacheStore(dbPath) {
+    let db = null;
+    let memoryFallback = null;
+    try {
+        // Dynamic require to avoid bundler issues with node:sqlite
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { DatabaseSync } = require("node:sqlite");
+        const database = new DatabaseSync(dbPath);
+        db = database;
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS import_cache (
+        path TEXT PRIMARY KEY,
+        source_mtime INTEGER NOT NULL,
+        sidecar_mtime INTEGER NOT NULL,
+        settings_json TEXT NOT NULL,
+        updated_at REAL NOT NULL
+      )
+    `);
+        log.info("import-cache", `SQLite cache opened at ${dbPath}`);
+    }
+    catch (err) {
+        log.warn("import-cache", `node:sqlite unavailable, using in-memory fallback: ${err}`);
+        memoryFallback = new Map();
+    }
+    return {
+        get(modelPath) {
+            try {
+                if (memoryFallback) {
+                    const row = memoryFallback.get(modelPath);
+                    if (!row)
+                        return null;
+                    return {
+                        settings: JSON.parse(row.settings_json),
+                        sourceMtime: row.source_mtime,
+                        sidecarMtime: row.sidecar_mtime,
+                        updatedAt: row.updated_at,
+                    };
+                }
+                if (!db)
+                    return null;
+                const stmt = db.prepare("SELECT * FROM import_cache WHERE path = ?");
+                const row = stmt.get(modelPath);
+                if (!row)
+                    return null;
+                return {
+                    settings: JSON.parse(row.settings_json),
+                    sourceMtime: row.source_mtime,
+                    sidecarMtime: row.sidecar_mtime,
+                    updatedAt: row.updated_at,
+                };
+            }
+            catch (err) {
+                log.error("import-cache", `GET failed for ${modelPath}: ${err}`);
+                return null;
+            }
+        },
+        set(modelPath, entry) {
+            try {
+                const settingsJson = JSON.stringify(entry.settings);
+                if (memoryFallback) {
+                    memoryFallback.set(modelPath, {
+                        path: modelPath,
+                        source_mtime: entry.sourceMtime,
+                        sidecar_mtime: entry.sidecarMtime,
+                        settings_json: settingsJson,
+                        updated_at: entry.updatedAt,
+                    });
+                    return;
+                }
+                if (!db)
+                    return;
+                const stmt = db.prepare(`
+          INSERT OR REPLACE INTO import_cache (path, source_mtime, sidecar_mtime, settings_json, updated_at)
+          VALUES (?, ?, ?, ?, ?)
+        `);
+                stmt.run(modelPath, entry.sourceMtime, entry.sidecarMtime, settingsJson, entry.updatedAt);
+            }
+            catch (err) {
+                log.error("import-cache", `SET failed for ${modelPath}: ${err}`);
+            }
+        },
+        invalidate(modelPath) {
+            try {
+                if (memoryFallback) {
+                    memoryFallback.delete(modelPath);
+                    return;
+                }
+                if (!db)
+                    return;
+                const stmt = db.prepare("DELETE FROM import_cache WHERE path = ?");
+                stmt.run(modelPath);
+            }
+            catch (err) {
+                log.error("import-cache", `INVALIDATE failed for ${modelPath}: ${err}`);
+            }
+        },
+        close() {
+            if (db) {
+                try {
+                    db.close();
+                }
+                catch { /* ignore */ }
+                db = null;
+            }
+            memoryFallback?.clear();
+            memoryFallback = null;
+        },
+    };
+}

package/dist/app/src/shared/index.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// @downdraft/engine/app/shared — HostAPI contract types (host + engine)
+// ============================================================================
+export * from "./types.js";

package/dist/app/src/shared/mcp-discovery.js

@@ -0,0 +1,55 @@
+// ============================================================================
+// MCP instance discovery — PID-file based. Lets the stdio bridge
+// auto-discover running game instances.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const log = createLogger("info");
+/**
+ * Directory holding one PID file per running downdraft game instance.
+ * Each file is named `<pid>` and contains the bound MCP HTTP port (string).
+ * The stdio bridge reads this directory to auto-discover running instances;
+ * dead-PID files are pruned on read. Best-effort cleanup on process exit.
+ */
+export function mcpPortDir() {
+    return join(homedir(), ".downdraft", "port");
+}
+/**
+ * Write `~/.downdraft/port/<pid>` containing the bound port, so the stdio
+ * bridge (and other local clients) can discover this instance. Also writes
+ * `<pid>.token` holding the transport's bearer token — clients that opt into
+ * auth (`mcp.requireAuth` / `MCP_AUTH=1`) read it and send the token via the
+ * `Authorization: Bearer <token>` or `X-Downdraft-Token` header. The port
+ * file format stays a bare number for backward compatibility with existing
+ * bridges. Returns a cleanup function that removes both files (best-effort).
+ *
+ * `suffix` distinguishes a second endpoint in the same process:
+ * `writeMcpPidFile(port, token, ".editor")` writes `<pid>.editor` +
+ * `<pid>.editor.token` (the createMcpModule editor toolset endpoint), leaving
+ * the automation endpoint's `<pid>` file untouched.
+ */
+export function writeMcpPidFile(port, token, suffix = "") {
+    const dir = mcpPortDir();
+    const pidFile = join(dir, `${process.pid}${suffix}`);
+    const tokenFile = `${pidFile}.token`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(pidFile, String(port));
+        writeFileSync(tokenFile, token, { mode: 0o600 });
+    }
+    catch (e) {
+        log.warn("mcp", `Failed to write PID file ${pidFile}: ${e.message}`);
+    }
+    return () => {
+        try {
+            unlinkSync(pidFile);
+        }
+        catch { /* already gone */ }
+        try {
+            unlinkSync(tokenFile);
+        }
+        catch { /* already gone */ }
+    };
+}

package/dist/app/src/shared/mcp-proxy.js

@@ -0,0 +1,71 @@
+// ============================================================================
+// MCP proxy-handler factory — merges "host-side" tools with the renderer
+// harness's tools behind a single JSON-RPC proxy handler.
+//
+// The caller provides `forwardToRenderer` — on the native host it's a
+// direct function call into the handler registered via
+// `downdraft.onMcpRequest`.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger("info");
+/**
+ * Create a proxy handler that:
+ *  - dispatches `tools/call` to host-side tools by name (no renderer hop),
+ *  - merges host tool defs with renderer tool defs in `tools/list`,
+ *  - forwards everything else to `forwardToRenderer`.
+ */
+export function createMcpProxyHandler(hostTools, forwardToRenderer) {
+    const hostToolMap = new Map();
+    hostTools.forEach((t) => { hostToolMap.set(t.def.name, t); ; });
+    return async (request) => {
+        const { method, params = {} } = request;
+        // --- Host-side tool dispatch ---
+        if (method === "tools/call") {
+            const name = params.name;
+            if (hostToolMap.has(name)) {
+                const tool = hostToolMap.get(name);
+                const args = params.arguments ?? {};
+                try {
+                    return await tool.handler(args);
+                }
+                catch (e) {
+                    return {
+                        content: [{ type: "text", text: `Tool "${name}" failed: ${e.message}` }],
+                        isError: true,
+                    };
+                }
+            }
+            // Not a host tool — fall through to renderer.
+        }
+        // --- tools/list: merge host tool defs with renderer's ---
+        if (method === "tools/list") {
+            let rendererTools = [];
+            try {
+                const rendererResult = await forwardToRenderer({ method, params });
+                const r = rendererResult;
+                if ("error" in r && r.error) {
+                    log.warn("mcp", `tools/list renderer error: ${JSON.stringify(r.error)} (returning host tools only)`);
+                }
+                else {
+                    rendererTools = r.tools ?? [];
+                }
+            }
+            catch (e) {
+                log.warn("mcp", `tools/list renderer unavailable: ${e.message} (returning host tools only)`);
+            }
+            const hostDefs = hostTools.map((t) => ({
+                name: t.def.name,
+                description: t.def.description,
+                inputSchema: t.def.inputSchema,
+            }));
+            // tools/call prefers host tools by name — the list must match that
+            // dispatch order or clients see a tool that never actually runs (e.g.
+            // the renderer's own capture_screenshot loses to the host's).
+            const hostNames = new Set(hostToolMap.keys());
+            const deduped = rendererTools.filter((t) => !t?.name || !hostNames.has(t.name));
+            return { tools: [...hostDefs, ...deduped] };
+        }
+        // --- All other methods: forward to renderer ---
+        return forwardToRenderer({ method, params });
+    };
+}

package/dist/app/src/shared/types.js

@@ -0,0 +1,13 @@
+// ============================================================================
+// @downdraft/engine/app/shared/types — host ↔ engine contract types
+// ============================================================================
+//
+// These interfaces describe the `HostAPI` contract: the object the host
+// installs on `globalThis.downdraft` (native bridge — see
+// @downdraft/platform-native) and that renderer/bootstrap code consumes
+// through the typed `downdraft` accessor. There is no process boundary on
+// native — every method is a direct in-process call.
+//
+// These are type-only — no runtime code — so importing them from any
+// context (host / renderer / worker) is safe.
+export {};

package/dist/asset-bake/src/bake-audio.js

@@ -0,0 +1,103 @@
+// ============================================================================
+// bake-audio.ts — normalize/transcode audio assets.
+// ============================================================================
+//
+// Strategy:
+//   1. If a system `ffmpeg` binary is available → transcode via child process
+//      (fast, no extra deps).
+//   2. Else → skip with a warning (do NOT fail the build over audio). The
+//      original file is passed through unchanged.
+//
+// We deliberately avoid bundling a wasm ffmpeg here (large + slow). Games that
+// need guaranteed audio baking can install ffmpeg on the build host.
+//
+import { spawnSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+let ffmpegChecked = null;
+/** Returns true if a system `ffmpeg` binary is on PATH. */
+export function hasFfmpeg() {
+    if (ffmpegChecked !== null)
+        return ffmpegChecked;
+    try {
+        const r = spawnSync("ffmpeg", ["-version"], { stdio: "ignore", timeout: 5000 });
+        ffmpegChecked = r.status === 0;
+    }
+    catch {
+        ffmpegChecked = false;
+    }
+    return ffmpegChecked;
+}
+const TARGET_EXT = {
+    ogg: "ogg",
+    mp3: "mp3",
+    wav: "wav",
+    flac: "flac",
+};
+const TARGET_CODEC = {
+    ogg: "libvorbis",
+    mp3: "libmp3lame",
+    wav: "pcm_s16le",
+    flac: "flac",
+};
+/**
+ * Bake an audio file. If ffmpeg is unavailable, the original bytes are
+ * returned unchanged with a warning (the build never fails over audio).
+ */
+export async function bakeAudio(sourceAbsPath, opts, log) {
+    const a = opts.audio;
+    const srcSize = statSync(sourceAbsPath).size;
+    if (!a.enabled) {
+        return passThrough(sourceAbsPath, srcSize);
+    }
+    if (!hasFfmpeg()) {
+        log?.(`  audio: ffmpeg not found — skipping (pass-through)`);
+        return passThrough(sourceAbsPath, srcSize);
+    }
+    const target = a.target;
+    const outExt = TARGET_EXT[target];
+    const codec = TARGET_CODEC[target];
+    // Write to a temp file, then transcode.
+    const tmpOut = join(tmpdir(), `downdraft-bake-${process.pid}-${Date.now()}.${outExt}`);
+    const args = ["-y", "-i", sourceAbsPath];
+    if (a.sampleRate > 0)
+        args.push("-ar", String(a.sampleRate));
+    if (a.channels > 0)
+        args.push("-ac", String(a.channels));
+    if (target === "ogg" || target === "mp3") {
+        args.push("-b:a", `${a.bitrate}k`);
+    }
+    args.push("-c:a", codec, tmpOut);
+    const res = spawnSync("ffmpeg", args, { stdio: "ignore", timeout: 120000 });
+    if (res.status !== 0) {
+        log?.(`  audio: ffmpeg failed (exit ${res.status}) — pass-through`);
+        return passThrough(sourceAbsPath, srcSize);
+    }
+    const baked = readFileSync(tmpOut);
+    try {
+        const { unlinkSync } = await import("node:fs");
+        unlinkSync(tmpOut);
+    }
+    catch { }
+    log?.(`  audio: ${srcSize} → ${baked.byteLength} bytes (${outExt})`);
+    return {
+        bytes: new Uint8Array(baked),
+        ext: outExt,
+        mimeType: AUDIO_MIME[outExt] ?? `audio/${outExt}`,
+        sourceSize: srcSize,
+    };
+}
+function passThrough(sourceAbsPath, srcSize) {
+    const data = readFileSync(sourceAbsPath);
+    const ext = sourceAbsPath.split(".").pop()?.toLowerCase() ?? "bin";
+    const mime = PASS_THROUGH_MIME[ext] ?? "application/octet-stream";
+    return { bytes: new Uint8Array(data), ext, mimeType: mime, sourceSize: srcSize };
+}
+const AUDIO_MIME = {
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+    flac: "audio/flac",
+};
+const PASS_THROUGH_MIME = AUDIO_MIME;

package/dist/asset-bake/src/bake-gltf.js

@@ -0,0 +1,141 @@
+// ============================================================================
+// bake-gltf.ts — glTF/GLB → meshopt-compressed GLB with Basis KTX2 textures.
+// ============================================================================
+//
+// Pipeline (via @gltf-transform):
+//   1. dedup   — remove duplicate accessors/textures
+//   2. weld    — weld coincident vertices
+//   3. prune   — remove unused nodes/materials/textures/cameras
+//   4. quantize— quantize vertex attributes (prep for meshopt)
+//   5. meshopt — EXT_meshopt_compression (geometry + animation)
+//   6. ktx2    — KHR_texture_basisu (textures → Basis Universal KTX2)
+//
+// Output is a single self-contained .glb. The runtime decodes meshopt via
+// meshopt-codec.ts and basisu KTX2 via basisu-codec.ts (which transcodes to
+// BC7/RGBA32 through @h00w/basis-universal-transcoder).
+//
+import { NodeIO } from "@gltf-transform/core";
+import { EXTMeshoptCompression, KHRTextureBasisu } from "@gltf-transform/extensions";
+import { dedup, meshopt, prune, weld } from "@gltf-transform/functions";
+import { Jimp } from "jimp";
+import { MeshoptEncoder } from "meshoptimizer";
+import { statSync } from "node:fs";
+import { basename, dirname, extname } from "node:path";
+let encoderReady = null;
+function ensureMeshoptEncoder() {
+    if (!encoderReady)
+        encoderReady = MeshoptEncoder.ready;
+    return encoderReady;
+}
+/**
+ * jimp-based image decoder for the ktx2-encoder (Node.js requires an
+ * imageDecoder to turn PNG/JPG/WebP bytes into raw RGBA for the basisu
+ * encoder). Avoids the heavy native `sharp` dependency.
+ */
+async function jimpImageDecoder(buffer) {
+    const img = await Jimp.read(Buffer.from(buffer));
+    // Ensure RGBA. Jimp always stores 4 channels internally.
+    const { data, width, height } = img.bitmap;
+    return { width, height, data: new Uint8Array(data) };
+}
+/**
+ * Bake a glTF/GLB file (by absolute path) into an optimized self-contained
+ * GLB. External `.bin`/texture references are resolved relative to the source
+ * file via NodeIO.read().
+ */
+export async function bakeGltf(sourceAbsPath, opts, log) {
+    const ext = extname(sourceAbsPath).toLowerCase();
+    if (ext !== ".gltf" && ext !== ".glb") {
+        throw new Error(`bakeGltf: unsupported extension "${ext}" (${sourceAbsPath})`);
+    }
+    const srcSize = statSync(sourceAbsPath).size;
+    const g = opts.gltf;
+    const t = g.textures;
+    await ensureMeshoptEncoder();
+    const io = new NodeIO()
+        .registerExtensions([EXTMeshoptCompression, KHRTextureBasisu])
+        .registerDependencies({ "meshopt.encoder": MeshoptEncoder });
+    const document = await io.read(sourceAbsPath);
+    const transforms = [];
+    // Geometry transforms (applied in order).
+    if (g.dedup)
+        await document.transform(dedup());
+    if (g.weld)
+        await document.transform(weld());
+    if (g.prune)
+        await document.transform(prune());
+    if (g.quantize || g.meshoptLevel) {
+        const level = g.meshoptLevel === "high" ? "high" : "medium";
+        await document.transform(meshopt({ encoder: MeshoptEncoder, level: level }));
+        log?.(`  meshopt: ${level}`);
+    }
+    // Texture transforms → Basis Universal KTX2.
+    if (t.enabled) {
+        await applyKtx2Textures(document, t.codec, t, log);
+    }
+    const outBytes = await io.writeBinary(document);
+    log?.(`  glb: ${srcSize} → ${outBytes.byteLength} bytes`);
+    return {
+        bytes: outBytes,
+        ext: "glb",
+        mimeType: "model/gltf-binary",
+        sourceSize: srcSize,
+    };
+}
+/**
+ * Apply KTX2/basisu texture compression. In "auto" mode, UASTC is used for
+ * quality-sensitive slots (normal/ORM/emissive) and ETC1S for base color.
+ */
+async function applyKtx2Textures(document, codec, t, log) {
+    // Lazily import the ktx2-encoder gltf-transform transform. It dynamically
+    // selects the Node encoder path internally.
+    const { ktx2 } = await import("ktx2-encoder/gltf-transform");
+    const baseOpts = {
+        generateMipmap: t.generateMipmap,
+        imageDecoder: jimpImageDecoder,
+        enableDebug: false,
+    };
+    if (codec === "uastc") {
+        await document.transform(ktx2({
+            ...baseOpts,
+            isUASTC: true,
+            uastcLDRQualityLevel: t.uastcLevel,
+            enableRDO: t.uastcRdo,
+        }));
+        log?.(`  textures: UASTC (all slots)`);
+    }
+    else if (codec === "etc1s") {
+        await document.transform(ktx2({
+            ...baseOpts,
+            isUASTC: false,
+            qualityLevel: t.etc1sQuality,
+        }));
+        log?.(`  textures: ETC1S (all slots)`);
+    }
+    else {
+        // "auto": UASTC for normal/ORM/emissive, ETC1S for base color.
+        const qualitySlots = /^(normalTexture|occlusionTexture|metallicRoughnessTexture|emissiveTexture)$/;
+        const colorSlots = /^(baseColorTexture)$/;
+        await document.transform(ktx2({
+            ...baseOpts,
+            isUASTC: true,
+            uastcLDRQualityLevel: t.uastcLevel,
+            enableRDO: t.uastcRdo,
+            slots: qualitySlots,
+        }));
+        await document.transform(ktx2({
+            ...baseOpts,
+            isUASTC: false,
+            qualityLevel: t.etc1sQuality,
+            slots: colorSlots,
+        }));
+        log?.(`  textures: UASTC (quality) + ETC1S (color)`);
+    }
+}
+/** Re-export for tests that need the source dir. */
+export function sourceDir(sourceAbsPath) {
+    return dirname(sourceAbsPath);
+}
+export function sourceBase(sourceAbsPath) {
+    return basename(sourceAbsPath);
+}