@downdraft/engine 0.0.0 → 0.1.1

package/app/src/shared/types.ts

@@ -0,0 +1,324 @@
+// ============================================================================
+// @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.
+
+import type { FeatureLogData, HostCapabilities, ISaveStore } from "@downdraft/engine";
+import type {
+    AtlasLayout,
+    AtlasPanelRect,
+    OSRInputEvent,
+    OSRPanelConfig,
+    OSRRendererConfig,
+    OSRRendererEvent,
+} from "@downdraft/engine/modules/native-osr";
+export type { FeatureLogData };
+
+// ---------------------------------------------------------------------------
+// OSR (Offscreen Rendering) — re-exported from the plugin for convenience
+// ---------------------------------------------------------------------------
+
+    export type {
+        AtlasLayout,
+        AtlasPanelRect,
+        OSRInputEvent,
+        OSRPanelConfig,
+        OSRRendererConfig,
+        OSRRendererEvent
+    };
+
+/** Layout data delivered by `HostOsrAPI.onPanelLayout`. */
+export type OSRPanelLayout = AtlasLayout;
+
+// ---------------------------------------------------------------------------
+// GPU Info
+// ---------------------------------------------------------------------------
+
+/** Response from `nvidia-smi` query (host system probe — runtime-agnostic). */
+export interface GPUSystemInfo {
+  gpus: Array<Record<string, string | number>>;
+  processes: Array<{
+    pid: number;
+    processName: string;
+    usedMemoryMB: number;
+  }>;
+  source: "nvidia-smi";
+  timestamp: number;
+}
+
+/** Host GPU adapter identity + negotiated device features.
+ *  On native this is the wgpu adapter info + the feature set the single
+ *  host-owned device was created with. */
+export interface HostGpuInfo {
+  vendor: string;
+  architecture: string;
+  device: string;
+  description: string;
+  /** GPU backend label — e.g. "wgpu/vulkan", "wgpu/metal", "webgpu". */
+  backend: string;
+  /** Feature names enabled on the device (e.g. "timestamp-query"). */
+  features: string[];
+}
+
+/** Response from the Vulkan validation status query (env-var probe —
+ *  meaningful only on hosts where validation is switchable). */
+export interface VulkanValidationStatus {
+  enabled: boolean;
+  envVar: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Event Payloads (host -> engine)
+// ---------------------------------------------------------------------------
+
+/** Payload for the `sim-ready` event. */
+export interface SimReadyData {
+  isDev: boolean;
+  deterministic: boolean;
+}
+
+/** Payload for the `display-info` event and `getDisplayInfo()` response. */
+export interface DisplayInfoData {
+  refreshRate: number;
+}
+
+/** Payload for the `display-metrics-changed` event. */
+export interface DisplayMetricsChangedData {
+  scaleFactor: number;
+}
+
+/** Payload for the `perf-stats` event (single-process host). */
+export interface PerfStatsData {
+  cpuPercent: number;
+  memUsedMB: number;
+  heapUsedMB: number;
+  heapTotalMB: number;
+  externalMB: number;
+  timestamp: number;
+}
+
+/** Typed host event names + payloads — the union behind the `on*` event
+ *  methods. There is no free-form channel registry on the live contract. */
+export interface HostEventMap {
+  "sim-ready": SimReadyData;
+  "display-info": DisplayInfoData;
+  "display-metrics-changed": DisplayMetricsChangedData;
+  "perf-stats": PerfStatsData;
+  "debug-mode": boolean;
+  "devtools-toggle": undefined;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Proxy
+// ---------------------------------------------------------------------------
+
+export interface McpRequest {
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface McpResponse {
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+// ---------------------------------------------------------------------------
+// Import Cache
+// ---------------------------------------------------------------------------
+
+export interface ImportCacheEntry {
+  settings: unknown;
+  sourceMtime: number;
+  sidecarMtime: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Save Slots
+// ---------------------------------------------------------------------------
+
+export interface SaveSlotInfo {
+  slot: string;
+  timestamp: number;
+  entityCount: number;
+  playerCount: number;
+  engineVersion: string;
+  fileSize: number;
+  currentGen: number;
+  generationCount: number;
+  hasThumbnail: boolean;
+  properties?: Record<string, unknown>;
+}
+
+export interface SaveGenerationInfo {
+  gen: number;
+  timestamp: number;
+  engineVersion: string;
+  entityCount: number;
+  playerCount: number;
+  bodySize: number;
+  blobCount: number;
+}
+
+export interface SaveOptions {
+  maxGenerations?: number;
+  thumbnail?: ArrayBuffer | Uint8Array;
+  properties?: Record<string, unknown>;
+  blobs?: Record<string, ArrayBuffer>;
+}
+
+export interface LoadOptions {
+  gen?: number;
+  includeBlobs?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Process stats (single native process)
+// ---------------------------------------------------------------------------
+
+export interface ProcessStatsData {
+  timestamp: number;
+  rss: number;
+  heapTotal: number;
+  heapUsed: number;
+  external: number;
+  arrayBuffers: number;
+  cpuUser: number;
+  cpuSystem: number;
+  uptimeSec: number;
+}
+
+// ---------------------------------------------------------------------------
+// OSR host API (sub-object of HostAPI)
+// ---------------------------------------------------------------------------
+
+/** Host-side OSR surface — Blitz-backed native implementation. Panels render
+ *  offscreen on the host; the engine pulls dirty RGBA frames + hit-tests
+ *  directly (no shared-texture or paint-region machinery). */
+export interface HostOsrAPI {
+  createRenderer(config: OSRRendererConfig): Promise<void>;
+  destroyRenderer(id: string): Promise<void>;
+  addPanel(config: OSRPanelConfig): Promise<AtlasPanelRect | null>;
+  removePanel(rendererId: string, panelId: string): Promise<AtlasLayout | null>;
+  updatePanel(rendererId: string, panelId: string, html: string): Promise<void>;
+  updateData(rendererId: string, panelId: string, values: Record<string, string | number | boolean>): void;
+  setContent(rendererId: string, html: string): Promise<void>;
+  loadURL(rendererId: string, url: string): Promise<void>;
+  sendInputEvent(rendererId: string, event: Omit<OSRInputEvent, "rendererId">): void;
+  setSoftwareCursor(rendererId: string, enabled: boolean): void;
+  onPanelLayout(cb: (rendererId: string, layout: OSRPanelLayout) => void): void;
+  onRendererEvent(cb: (event: OSRRendererEvent) => void): void;
+  onCursorStyle(cb: (rendererId: string, cursor: string) => void): void;
+
+  // ── In-process frame pull (Blitz backend) ──
+  /** Pull the renderer's dirty RGBA8 frame; null when clean or unknown. */
+  pullFrame(rendererId: string): Uint8Array | null;
+  /** Pixel-space dirty rect of the frame pullFrame just produced. */
+  frameRect(rendererId: string): { x: number; y: number; w: number; h: number } | null;
+  /** Renderer texture dimensions in physical px. */
+  getDimensions(rendererId: string): { width: number; height: number } | null;
+  /** Hit-test against `data-ui` elements in the Blitz document. */
+  hitTest(rendererId: string, x: number, y: number): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// HostAPI — the object installed on `globalThis.downdraft`
+// ---------------------------------------------------------------------------
+
+export interface HostAPI {
+  /** Host feature descriptor — what this host can actually do. Games should
+   *  gate on `getHostCapabilities()` (which prefers this field and falls
+   *  back to runtime detection) rather than probing globals. */
+  readonly capabilities?: HostCapabilities;
+  /** Typed host save store — present on the native host. Carries real
+   *  SaveState/LoadResult with no JSON boundary; the saveGameState/
+   *  loadGameState methods below are the JSON-string compatibility surface
+   *  for hosts without a typed store. */
+  readonly saveStore?: ISaveStore;
+  saveGameState(slotName: string, stateJson: string, opts?: SaveOptions): Promise<boolean>;
+  loadGameState(slotName: string, opts?: LoadOptions): Promise<string | null>;
+  deleteGameState(slotName: string): Promise<boolean>;
+  listSaveSlots(): Promise<SaveSlotInfo[]>;
+  listSaveGenerations(slotName: string): Promise<SaveGenerationInfo[]>;
+  deleteSaveGeneration(slotName: string, gen: number): Promise<boolean>;
+  setThumbnail(slotName: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+  getThumbnail(slotName: string): Promise<ArrayBuffer | null>;
+  setSaveProperties(slotName: string, props: Record<string, unknown>): Promise<void>;
+  getSaveProperties(slotName: string): Promise<Record<string, unknown>>;
+  quit(): Promise<void>;
+  /** Request a full host restart for unrecoverable failures (device loss,
+   *  resetGame, HMR fallback). Native: detached self-respawn with a restart
+   *  budget; DOM hosts may leave this unimplemented — callers fall back to
+   *  `window.location.reload()`. Returns false when refused. */
+  requestRestart?(reason: string): boolean;
+  setDebugMode(enabled: boolean): void;
+  toggleDevtools(): void;
+  toggleFullscreen(): void;
+  getDisplayInfo(): Promise<DisplayInfoData>;
+  openExternal(url: string): void;
+  /** Host system GPU probe (nvidia-smi); null when unavailable. */
+  getGPUSystemInfo(): Promise<GPUSystemInfo | null>;
+  /** GPU adapter identity + negotiated features (wgpu on native). */
+  getGpuInfo(): Promise<HostGpuInfo | null>;
+  /** Fetch the host's feature log (for the combined DevTools/MCP view). */
+  getFeatureLog(): Promise<FeatureLogData | null>;
+  /** Capture the composited frame (swapchain + overlay layers) as a PNG
+   *  buffer. Returns null if the window is gone or the capture is empty. */
+  captureFrame(): Promise<ArrayBuffer | null>;
+  /** Single-process memory/CPU snapshot. */
+  getProcessStats(): Promise<ProcessStatsData>;
+
+  importCacheGet(modelPath: string): Promise<ImportCacheEntry | null>;
+  importCacheSet(modelPath: string, entry: ImportCacheEntry): Promise<void>;
+  importCacheInvalidate(modelPath: string): Promise<void>;
+
+  // ── Typed events (see HostEventMap). Each returns an unsubscribe fn. ──
+  onSimReady(cb: (data: SimReadyData) => void): () => void;
+  onDisplayInfo(cb: (data: DisplayInfoData) => void): () => void;
+  onDisplayMetricsChanged(cb: (data: DisplayMetricsChangedData) => void): () => void;
+  onPerfStats(cb: (data: PerfStatsData) => void): () => void;
+  /** Debug-mode intent relayed by `setDebugMode` — subscribe to react. */
+  onDebugMode(cb: (enabled: boolean) => void): () => void;
+  /** DevTools-toggle intent relayed by `toggleDevtools`. */
+  onDevtoolsToggle(cb: () => void): () => void;
+
+  osr: HostOsrAPI;
+  /** Native raw mouse capture (pointer lock polyfill). Undefined when the feature is disabled. */
+  rawInput?: HostRawInputAPI;
+  deterministic: boolean;
+  onMcpRequest(cb: (request: McpRequest) => Promise<McpResponse>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Raw Input host API (sub-object of HostAPI)
+// ---------------------------------------------------------------------------
+
+/** Status returned by the native raw input addon. */
+export interface RawInputStatus {
+  platform: "x11" | "wayland" | "win32" | "macos" | "unsupported";
+  capturing: boolean;
+  detail: string;
+}
+
+export interface HostRawInputAPI {
+  /** Begin raw mouse capture (called by the polyfill on requestPointerLock). */
+  start(): Promise<RawInputStatus>;
+  /** Stop raw mouse capture (called by the polyfill on exitPointerLock). */
+  stop(): Promise<void>;
+  /** Set the OS cursor visibility. */
+  setCursorVisible(visible: boolean): Promise<void>;
+  /** Register a callback for raw mouse deltas (dx, dy in pixels). */
+  onDelta(cb: (dx: number, dy: number) => void): void;
+  /** Register a callback for when capture stops unexpectedly (e.g. window lost focus). */
+  onStopped(cb: () => void): void;
+}

package/asset-bake/src/bake-audio.ts

@@ -0,0 +1,119 @@
+// ============================================================================
+// 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";
+import type { BakeResult, ResolvedBakeOptions } from "./config";
+
+let ffmpegChecked: boolean | null = null;
+
+/** Returns true if a system `ffmpeg` binary is on PATH. */
+export function hasFfmpeg(): boolean {
+  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: Record<string, string> = {
+  ogg: "ogg",
+  mp3: "mp3",
+  wav: "wav",
+  flac: "flac",
+};
+
+const TARGET_CODEC: Record<string, string> = {
+  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: string,
+  opts: ResolvedBakeOptions,
+  log?: (msg: string) => void,
+): Promise<BakeResult> {
+  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: string[] = ["-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: string, srcSize: number): BakeResult {
+  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: Record<string, string> = {
+  wav: "audio/wav",
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+};
+
+const PASS_THROUGH_MIME: Record<string, string> = AUDIO_MIME;

package/asset-bake/src/bake-gltf.ts

@@ -0,0 +1,172 @@
+// ============================================================================
+// 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 type { Document as GltfDocument } from "@gltf-transform/core";
+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";
+import type { BakeResult, ResolvedBakeOptions, TextureCodecMode } from "./config";
+
+let encoderReady: Promise<void> | null = null;
+function ensureMeshoptEncoder(): Promise<void> {
+  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: Uint8Array): Promise<{ width: number; height: number; data: Uint8Array }> {
+  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: string,
+  opts: ResolvedBakeOptions,
+  log?: (msg: string) => void,
+): Promise<BakeResult> {
+  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: Array<Promise<unknown> | unknown> = [];
+
+  // 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 as "medium" | "high" }),
+    );
+    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: GltfDocument,
+  codec: TextureCodecMode,
+  t: ResolvedBakeOptions["gltf"]["textures"],
+  log?: (msg: string) => void,
+): Promise<void> {
+  // 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: string): string {
+  return dirname(sourceAbsPath);
+}
+export function sourceBase(sourceAbsPath: string): string {
+  return basename(sourceAbsPath);
+}

package/asset-bake/src/bake.ts

@@ -0,0 +1,78 @@
+// ============================================================================
+// bake.ts — dispatch baking by file extension, with cache integration.
+// ============================================================================
+
+import { extname } from "node:path";
+import { readFileSync } from "node:fs";
+import { BakeCache, type BakeCacheHit } from "./cache";
+import { resolveOptions, type AssetBakeOptions, type BakeResult, type ResolvedBakeOptions } from "./config";
+import { bakeGltf } from "./bake-gltf";
+import { bakeAudio } from "./bake-audio";
+
+const GLTF_EXTS = new Set([".gltf", ".glb"]);
+const AUDIO_EXTS = new Set([".wav", ".mp3", ".ogg", ".flac"]);
+
+/** All extensions the bake pipeline handles. */
+export const BAKEABLE_EXTENSIONS = [...GLTF_EXTS, ...AUDIO_EXTS] as const;
+
+export function isBakeable(absPath: string, opts: ResolvedBakeOptions): boolean {
+  const ext = extname(absPath).toLowerCase();
+  if (GLTF_EXTS.has(ext) && opts.gltf.enabled) return true;
+  if (AUDIO_EXTS.has(ext) && opts.audio.enabled) return true;
+  return false;
+}
+
+/**
+ * Bake a single asset file (by absolute path). Uses the BakeCache for hits;
+ * on miss, bakes and stores the result.
+ *
+ * @param sourceAbsPath  absolute path to the source asset.
+ * @param gameRoot       absolute path to the game root (for the cache dir).
+ * @param userOpts       user bake options (merged with defaults).
+ * @param log            optional verbose logger.
+ * @returns the cache hit (path to the baked file + metadata).
+ */
+export async function bakeAsset(
+  sourceAbsPath: string,
+  gameRoot: string,
+  userOpts?: AssetBakeOptions,
+  log?: (msg: string) => void,
+): Promise<BakeCacheHit> {
+  const opts = resolveOptions(userOpts);
+  const cache = new BakeCache(gameRoot);
+
+  const hit = cache.get(sourceAbsPath, opts);
+  if (hit) {
+    log?.(`  cache hit: ${hit.ext} (${hit.size} bytes)`);
+    return hit;
+  }
+
+  const result = await bakeAssetFromBytes(sourceAbsPath, opts, log);
+  return cache.put(sourceAbsPath, result.bytes, result.ext, result.mimeType, opts);
+}
+
+/**
+ * Bake a single asset file without the cache (returns the baked bytes
+ * directly). Useful for tests and one-off bakes.
+ */
+export async function bakeAssetFromBytes(
+  sourceAbsPath: string,
+  opts: ResolvedBakeOptions,
+  log?: (msg: string) => void,
+): Promise<BakeResult> {
+  const ext = extname(sourceAbsPath).toLowerCase();
+  if (GLTF_EXTS.has(ext)) {
+    return bakeGltf(sourceAbsPath, opts, log);
+  }
+  if (AUDIO_EXTS.has(ext)) {
+    return bakeAudio(sourceAbsPath, opts, log);
+  }
+  // Not bakeable — pass through unchanged.
+  const data = readFileSync(sourceAbsPath);
+  return {
+    bytes: new Uint8Array(data),
+    ext: ext.slice(1) || "bin",
+    mimeType: "application/octet-stream",
+    sourceSize: data.byteLength,
+  };
+}