@origingame/engine 0.0.0-stage → 0.1.0

package/src/web/audio.ts

@@ -0,0 +1,307 @@
+// Audio on the web (docs/design.md §2.2, §4; crates/og-audio/README.md §Host
+// contract). Two halves, like input:
+//
+// - Main thread (`AudioShell`): owns the AudioContext. It is created and
+//   resumed once, on the page's first gesture (the one audio unlock), loads
+//   the worklet (audio-worklet.ts, bundled), and hands the engine Worker
+//   either the SharedArrayBuffer ring the worklet reads (cross-origin
+//   isolated) or a MessagePort to the worklet (otherwise), with the
+//   context's sample rate, as a `{ type: "audio" }` message.
+// - Engine Worker (`WorkerAudio`): on that message opens the engine's mixer
+//   at the context's rate (og_web_audio_open), and after every frame's ticks
+//   pumps the PCM those ticks cover (og_web_audio_pump) into the ring, or
+//   posts it to the port.
+
+import {
+  PROCESSOR,
+  RING_CAPACITY,
+  RING_CHANNELS,
+  RING_HEADER,
+  RING_PRIME,
+  RING_READ,
+  RING_SAMPLE_RATE,
+  RING_UNDERRUNS,
+  RING_WRITE,
+  ringAvailable,
+  type WorkletOptions,
+} from "./audio-worklet.ts";
+
+// ── the ring (producer side) ───────────────────────────────────────────────
+
+/** Ring capacity in frames (a power of two): 8192 is 170 ms at 48 kHz. */
+export const AUDIO_RING_FRAMES = 8192;
+/** Frames the worklet buffers before playing: 2048 is 43 ms at 48 kHz. */
+export const AUDIO_PRIME_FRAMES = 2048;
+
+/** A ring for `frames` (rounded up to a power of two) stereo frames at `sampleRate`. */
+export function createAudioRing(sampleRate: number, frames = AUDIO_RING_FRAMES, prime = AUDIO_PRIME_FRAMES): SharedArrayBuffer {
+  let capacity = 1;
+  while (capacity < frames) capacity *= 2;
+  const ring = new SharedArrayBuffer(RING_HEADER * 4 + capacity * 2 * 4);
+  const header = new Int32Array(ring, 0, RING_HEADER);
+  header[RING_CAPACITY] = capacity;
+  header[RING_CHANNELS] = 2;
+  header[RING_SAMPLE_RATE] = sampleRate;
+  header[RING_PRIME] = Math.min(prime, capacity);
+  return ring;
+}
+
+/** Frames the producer may write now. */
+export function audioRingFree(ring: SharedArrayBuffer): number {
+  const header = new Int32Array(ring, 0, RING_HEADER);
+  return header[RING_CAPACITY]! - ringAvailable(header);
+}
+
+/** Producer: appends interleaved stereo frames; returns how many fit. */
+export function writeAudioRing(ring: SharedArrayBuffer, pcm: Float32Array): number {
+  const header = new Int32Array(ring, 0, RING_HEADER);
+  const data = new Float32Array(ring, RING_HEADER * 4);
+  const capacity = header[RING_CAPACITY]!;
+  const mask = capacity - 1;
+  const write = Atomics.load(header, RING_WRITE);
+  const frames = Math.min(pcm.length >> 1, capacity - ringAvailable(header));
+  for (let i = 0; i < frames; i++) {
+    const at = ((write + i) & mask) * 2;
+    data[at] = pcm[i * 2]!;
+    data[at + 1] = pcm[i * 2 + 1]!;
+  }
+  Atomics.store(header, RING_WRITE, (write + frames) | 0);
+  return frames;
+}
+
+/** Underrun frames the worklet has played so far, and frames buffered. */
+export function audioRingState(ring: SharedArrayBuffer): { buffered: number; underruns: number; read: number } {
+  const header = new Int32Array(ring, 0, RING_HEADER);
+  return { buffered: ringAvailable(header), underruns: Atomics.load(header, RING_UNDERRUNS), read: Atomics.load(header, RING_READ) };
+}
+
+// ── main thread ────────────────────────────────────────────────────────────
+
+/** The message the shell posts to the engine Worker once audio is unlocked. */
+export interface AudioMessage {
+  readonly type: "audio";
+  readonly sampleRate: number;
+  readonly ring?: SharedArrayBuffer;
+  readonly port?: MessagePort;
+  /** The context's baseLatency plus outputLatency, seconds (what the device adds after the worklet). */
+  readonly latency?: number;
+}
+
+/** A later report of the context's latency (outputLatency moves as the device settles). */
+export interface AudioLatencyMessage {
+  readonly type: "audio-latency";
+  readonly latency: number;
+}
+
+/** The context's own latency after the worklet: baseLatency and outputLatency, seconds (0 where a browser reports none). */
+export function contextLatency(context: { baseLatency?: number; outputLatency?: number }): number {
+  const n = (v: number | undefined) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0);
+  return n(context.baseLatency) + n(context.outputLatency);
+}
+
+export interface AudioShellOptions {
+  /** The engine Worker. */
+  readonly worker: Worker;
+  /** URL of the bundled audio-worklet module. */
+  readonly worklet: string;
+  /** Where the first gesture is listened for (default: the window). */
+  readonly target?: EventTarget;
+  /** Use the ring when cross-origin isolated (default true). */
+  readonly ring?: boolean;
+}
+
+const GESTURES = ["pointerdown", "keydown", "touchend"] as const;
+
+/**
+ * The page's audio: nothing until the first gesture, then one AudioContext,
+ * the worklet node, and the transport to the engine Worker.
+ */
+export class AudioShell {
+  readonly #options: AudioShellOptions;
+  #context: AudioContext | null = null;
+  #node: AudioWorkletNode | null = null;
+  #ring: SharedArrayBuffer | null = null;
+  #unlocking: Promise<AudioContext> | null = null;
+  readonly #off: Array<() => void> = [];
+
+  constructor(options: AudioShellOptions) {
+    this.#options = options;
+  }
+
+  /** Unlock on the first pointer, key or touch gesture (once). */
+  listen(): void {
+    const target = this.#options.target ?? (globalThis as unknown as EventTarget);
+    const once = () => {
+      for (const off of this.#off.splice(0)) off();
+      void this.unlock();
+    };
+    for (const type of GESTURES) {
+      target.addEventListener(type, once, { capture: true });
+      this.#off.push(() => target.removeEventListener(type, once, { capture: true }));
+    }
+  }
+
+  /** Create and resume the AudioContext (call inside a user gesture). Idempotent. */
+  unlock(): Promise<AudioContext> {
+    this.#unlocking ??= this.#start();
+    return this.#unlocking;
+  }
+
+  async #start(): Promise<AudioContext> {
+    const context = new AudioContext({ latencyHint: "interactive" });
+    // resume() first: it must run inside the gesture's task.
+    const resumed = context.resume();
+    await context.audioWorklet.addModule(this.#options.worklet);
+    const isolated = (this.#options.ring ?? true) && globalThis.crossOriginIsolated === true;
+    const sampleRate = context.sampleRate;
+    let processorOptions: WorkletOptions;
+    let message: AudioMessage;
+    let channel: MessageChannel | null = null;
+    if (isolated) {
+      this.#ring = createAudioRing(sampleRate);
+      processorOptions = { ring: this.#ring };
+      message = { type: "audio", sampleRate, ring: this.#ring };
+    } else {
+      channel = new MessageChannel();
+      processorOptions = { prime: AUDIO_PRIME_FRAMES, maxQueued: Math.round(sampleRate / 2) };
+      message = { type: "audio", sampleRate, port: channel.port2 };
+    }
+    this.#node = new AudioWorkletNode(context, PROCESSOR, {
+      numberOfInputs: 0,
+      numberOfOutputs: 1,
+      outputChannelCount: [2],
+      processorOptions,
+    });
+    if (channel) this.#node.port.postMessage({ type: "port", port: channel.port1 }, [channel.port1]);
+    this.#node.connect(context.destination);
+    message = { ...message, latency: contextLatency(context) };
+    this.#options.worker.postMessage(message, message.port ? [message.port] : []);
+    await resumed;
+    this.#context = context;
+    // outputLatency is known once the context runs and moves with the device: report changes.
+    let told = message.latency ?? 0;
+    const report = () => {
+      const now = contextLatency(context);
+      if (Math.abs(now - told) < 0.0005) return;
+      told = now;
+      this.#options.worker.postMessage({ type: "audio-latency", latency: now } satisfies AudioLatencyMessage);
+    };
+    report();
+    const timer = setInterval(report, 2000);
+    this.#off.push(() => clearInterval(timer));
+    return context;
+  }
+
+  get context(): AudioContext | null {
+    return this.#context;
+  }
+
+  /** `ring`, `message`, or `locked` before the first gesture. */
+  get transport(): "ring" | "message" | "locked" {
+    if (!this.#context) return "locked";
+    return this.#ring ? "ring" : "message";
+  }
+
+  /** The ring's fill and underruns (ring transport only). */
+  ringState(): { buffered: number; underruns: number } | null {
+    return this.#ring ? audioRingState(this.#ring) : null;
+  }
+
+  /** Suspend or resume output (the engine keeps ticking; a pause menu uses og.Audio instead). */
+  async suspend(on: boolean): Promise<void> {
+    if (!this.#context) return;
+    if (on) await this.#context.suspend();
+    else await this.#context.resume();
+  }
+
+  async dispose(): Promise<void> {
+    for (const off of this.#off.splice(0)) off();
+    this.#node?.disconnect();
+    await this.#context?.close();
+    this.#context = null;
+  }
+}
+
+// ── engine Worker ──────────────────────────────────────────────────────────
+
+/** The wasm-bindgen exports of crates/og-host-web/src/audio.rs. */
+export interface WebAudioGlue {
+  og_web_audio_open(engine: number, sampleRate: number): string;
+  og_web_audio_pump(engine: number, maxFrames: number): Float32Array;
+  og_web_audio_stats(engine: number): string;
+  og_web_audio_close(engine: number): boolean;
+  og_web_audio_insert_qoa(engine: number, id: string, qoa: Uint8Array): string;
+  og_web_audio_latency(engine: number, seconds: number): string;
+}
+
+type Wire<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+/** Without a ring, the largest chunk one pump posts (a quarter second at 48 kHz). */
+const MAX_CHUNK_FRAMES = 12_000;
+
+/** The Worker side of an engine's audio output. */
+export class WorkerAudio {
+  readonly #glue: WebAudioGlue;
+  readonly #engine: number;
+  readonly #ring: SharedArrayBuffer | null;
+  readonly #port: MessagePort | null;
+  /** Frames the ring had no room for (the worklet is behind). */
+  overflow = 0;
+
+  readonly #sampleRate: number;
+
+  private constructor(glue: WebAudioGlue, engine: number, message: AudioMessage) {
+    this.#glue = glue;
+    this.#engine = engine;
+    this.#ring = message.ring ?? null;
+    this.#port = message.port ?? null;
+    this.#sampleRate = message.sampleRate;
+  }
+
+  /** Open the engine's mixer at the context's rate, on the shell's `audio` message. */
+  static attach(glue: WebAudioGlue, engine: number, message: AudioMessage): Wire<WorkerAudio> {
+    const opened = JSON.parse(glue.og_web_audio_open(engine, message.sampleRate)) as Wire<number>;
+    if (!opened.ok) return opened;
+    const audio = new WorkerAudio(glue, engine, message);
+    audio.latency(message.latency ?? 0);
+    return { ok: true, value: audio };
+  }
+
+  /**
+   * The context's latency (`contextLatency`) arrived: og.audio.outputLatency
+   * is it plus the worklet's prime (the frames it buffers before it plays),
+   * written before the next tick. Call between frames.
+   */
+  latency(context: number): void {
+    const seconds = context + AUDIO_PRIME_FRAMES / Math.max(1, this.#sampleRate);
+    this.#glue.og_web_audio_latency(this.#engine, seconds);
+  }
+
+  /** After a frame's ticks: ship the audio they cover. Returns the frames shipped. */
+  pump(): number {
+    if (this.#ring) {
+      const pcm = this.#glue.og_web_audio_pump(this.#engine, audioRingFree(this.#ring));
+      const wrote = writeAudioRing(this.#ring, pcm);
+      this.overflow += (pcm.length >> 1) - wrote;
+      return wrote;
+    }
+    const pcm = this.#glue.og_web_audio_pump(this.#engine, MAX_CHUNK_FRAMES);
+    if (pcm.length > 0 && this.#port) this.#port.postMessage(pcm, [pcm.buffer]);
+    return pcm.length >> 1;
+  }
+
+  /** The mixer's counters. */
+  stats(): Wire<Record<string, number>> {
+    return JSON.parse(this.#glue.og_web_audio_stats(this.#engine)) as Wire<Record<string, number>>;
+  }
+
+  /** Add a sound (a cooked sound's QOA bytes); its handle is what AudioSource.sound takes. */
+  insertSound(id: string, qoa: Uint8Array): Wire<number> {
+    return JSON.parse(this.#glue.og_web_audio_insert_qoa(this.#engine, id, qoa)) as Wire<number>;
+  }
+
+  close(): void {
+    this.#glue.og_web_audio_close(this.#engine);
+    this.#port?.close();
+  }
+}

package/src/web/basis.ts

@@ -0,0 +1,239 @@
+// KTX2 / Basis Universal transcoding for the web host (og-cook README §What
+// phase 2 owes: the Rust runtime has no Basis transcoder on wasm32). Cooked
+// textures are KTX2 files (ETC1S colour, UASTC normal and linear maps, or
+// lossless RGBA8 with zlib, which og-cook's runtime decodes itself); the engine
+// Worker transcodes the Basis ones here with Binomial's transcoder
+// (vendor/basis/, Apache-2.0) into the GPU format the tier supports.
+//
+//   const basis = await loadBasisTranscoder();
+//   const format = pickFormat(compressionsFromWebGpu(adapter.features), "etc1s");
+//   const tex = transcodeKtx2(basis, ktx2Bytes, format);   // { width, height, format, levels, ... }
+//   device.createTexture({ format: wgpuFormatName(tex.format, srgb), ... })
+//
+// Works in a (module) Worker and under bun. The transcoder's script is a
+// classic Emscripten script, evaluated with the Function constructor as
+// three.js's KTX2Loader does, so a page whose CSP forbids 'unsafe-eval' must
+// allow it for the Worker or load the transcoder another way.
+
+/**
+ * The texture formats this module transcodes to, named as og-render's
+ * `TextureFormat::name` names them: BC5 and EAC RG11 hold a normal map's x
+ * and y (the renderer rebuilds z).
+ */
+export const TEXTURE_FORMATS = ["rgba8", "bc7", "bc5", "astc4x4", "etc2", "eacrg11"] as const;
+export type TextureFormat = (typeof TEXTURE_FORMATS)[number];
+
+/** GPU block compressions a device may support. */
+export type Compression = "bc" | "astc" | "etc2";
+
+/** What a cooked KTX2 holds: ETC1S (colour) or UASTC (normal and linear maps). */
+export type BasisKind = "etc1s" | "uastc";
+
+/** One level of the transcoder's KTX2 file. */
+interface LevelInfo {
+  readonly origWidth: number;
+  readonly origHeight: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** The part of the transcoder's `KTX2File` this module uses. */
+interface Ktx2File {
+  isValid(): boolean;
+  getWidth(): number;
+  getHeight(): number;
+  getLevels(): number;
+  getFaces(): number;
+  getLayers(): number;
+  getHasAlpha(): boolean;
+  isUASTC(): boolean;
+  isETC1S(): boolean;
+  getDFDTransferFunc(): number;
+  startTranscoding(): boolean;
+  getImageLevelInfo(level: number, layer: number, face: number): LevelInfo;
+  getImageTranscodedSizeInBytes(level: number, layer: number, face: number, format: number): number;
+  transcodeImage(dst: Uint8Array, level: number, layer: number, face: number, format: number, getAlphaForOpaque: number, channel0: number, channel1: number): number;
+  close(): void;
+  delete(): void;
+}
+
+/** The initialised transcoder module. */
+export interface BasisTranscoder {
+  readonly KTX2File: new (bytes: Uint8Array) => Ktx2File;
+  readonly transcoder_texture_format?: Record<string, { value: number }>;
+  initializeBasis(): void;
+}
+
+type Factory = (module: { wasmBinary?: ArrayBuffer | Uint8Array; locateFile?: (path: string) => string }) => Promise<BasisTranscoder>;
+
+/** basisu `transcoder_texture_format` values, used when the module does not export the enum. */
+const TRANSCODER_FORMAT: Record<TextureFormat, { name: string; value: number }> = {
+  etc2: { name: "cTFETC2_RGBA", value: 1 },
+  bc5: { name: "cTFBC5_RG", value: 5 },
+  bc7: { name: "cTFBC7_RGBA", value: 6 },
+  eacrg11: { name: "cTFETC2_EAC_RG11", value: 21 },
+  astc4x4: { name: "cTFASTC_4x4_RGBA", value: 10 },
+  rgba8: { name: "cTFRGBA32", value: 13 },
+};
+
+/** The vendored transcoder's files, next to this module in the package. */
+export const VENDORED = {
+  js: new URL("../../vendor/basis/basis_transcoder.js", import.meta.url).href,
+  wasm: new URL("../../vendor/basis/basis_transcoder.wasm", import.meta.url).href,
+} as const;
+
+async function bytesOf(source: string | URL | ArrayBuffer | Uint8Array): Promise<Uint8Array> {
+  if (source instanceof Uint8Array) return source;
+  if (source instanceof ArrayBuffer) return new Uint8Array(source);
+  const url = typeof source === "string" ? new URL(source, import.meta.url) : source;
+  if (url.protocol === "file:") {
+    // bun and node: fetch does not read file: URLs everywhere.
+    const { readFileSync } = await import("node:fs");
+    const { fileURLToPath } = await import("node:url");
+    return new Uint8Array(readFileSync(fileURLToPath(url)));
+  }
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`cannot fetch the Basis transcoder ${url.href}: HTTP ${response.status}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+/**
+ * Load and initialise the transcoder: `js` is the script (a URL, its text
+ * as bytes, or omitted for the vendored copy), `wasm` the module (a URL or
+ * its bytes, or omitted for the vendored copy).
+ */
+export async function loadBasisTranscoder(
+  js: string | URL | ArrayBuffer | Uint8Array = VENDORED.js,
+  wasm: string | URL | ArrayBuffer | Uint8Array = VENDORED.wasm,
+): Promise<BasisTranscoder> {
+  const [script, binary] = await Promise.all([bytesOf(js), bytesOf(wasm)]);
+  const text = new TextDecoder().decode(script);
+  // The script defines `var BASIS` (a factory) and, under CommonJS, assigns
+  // module.exports: give it no `module`, so it stays a plain factory. Under
+  // bun or node it believes it is in node and asks for `fs` and `path`; it
+  // gets inert stand-ins, because the wasm bytes are handed over and it never
+  // reads a file.
+  const inert = (name: string) => new Proxy({}, { get: (_t, key) => () => { throw new Error(`the Basis transcoder tried ${name}.${String(key)}; it is given its wasm bytes and should not`); } });
+  const factory = new Function("module", "exports", "require", "__dirname", "__filename", `${text}\n;return BASIS;`)(undefined, undefined, inert, "", "") as Factory;
+  if (typeof factory !== "function") throw new Error("the Basis transcoder script did not define BASIS");
+  const basis = await factory({ wasmBinary: binary });
+  basis.initializeBasis();
+  return basis;
+}
+
+/** The block compressions a WebGPU adapter or device supports, from its features. */
+export function compressionsFromWebGpu(features: { has(feature: string): boolean }): Set<Compression> {
+  const out = new Set<Compression>();
+  if (features.has("texture-compression-bc")) out.add("bc");
+  if (features.has("texture-compression-astc")) out.add("astc");
+  if (features.has("texture-compression-etc2")) out.add("etc2");
+  return out;
+}
+
+/** The block compressions a WebGL2 context supports, from `getSupportedExtensions()`. */
+export function compressionsFromWebGl2(extensions: Iterable<string>): Set<Compression> {
+  const have = new Set(extensions);
+  const out = new Set<Compression>();
+  if (have.has("EXT_texture_compression_bptc")) out.add("bc");
+  if (have.has("WEBGL_compressed_texture_astc")) out.add("astc");
+  if (have.has("WEBGL_compressed_texture_etc")) out.add("etc2");
+  return out;
+}
+
+/**
+ * The GPU format to transcode to on this device: BC7 where BC is supported
+ * (desktop), else ASTC 4x4 (Apple, most Android), else ETC2 (other Android),
+ * else uncompressed RGBA8. UASTC normal maps and ETC1S colour maps use the
+ * same order: BC7 and ASTC keep UASTC's quality, and every choice keeps
+ * ETC1S's.
+ */
+export function pickFormat(supported: ReadonlySet<Compression> | readonly Compression[], kind: BasisKind = "etc1s"): TextureFormat {
+  const has = (c: Compression) => (Array.isArray(supported) ? (supported as readonly Compression[]).includes(c) : (supported as ReadonlySet<Compression>).has(c));
+  void kind; // one order serves both kinds today; the parameter keeps call sites honest when it changes
+  if (has("bc")) return "bc7";
+  if (has("astc")) return "astc4x4";
+  if (has("etc2")) return "etc2";
+  return "rgba8";
+}
+
+/** The WebGPU texture format of a transcoded texture. */
+export function wgpuFormatName(format: TextureFormat, srgb: boolean): string {
+  // The two-channel formats have no sRGB variant: normal maps are linear.
+  if (format === "bc5") return "bc5-rg-unorm";
+  if (format === "eacrg11") return "eac-rg11unorm";
+  const base = { rgba8: "rgba8unorm", bc7: "bc7-rgba-unorm", astc4x4: "astc-4x4-unorm", etc2: "etc2-rgba8unorm" }[format];
+  return srgb ? `${base}-srgb` : base;
+}
+
+/** A transcoded texture: every level of layer 0, face 0. */
+export interface Transcoded {
+  /** Level 0's size in pixels. */
+  readonly width: number;
+  readonly height: number;
+  /** What `levels` hold: the requested format, or `rgba8` when a block format cannot hold this size. */
+  readonly format: TextureFormat;
+  /** Level data, level 0 first: RGBA8 rows top to bottom, or 4x4 blocks in row order. */
+  readonly levels: Uint8Array[];
+  /** Each level's size in pixels. */
+  readonly sizes: ReadonlyArray<{ readonly width: number; readonly height: number }>;
+  /** What the file held. */
+  readonly kind: BasisKind;
+  readonly alpha: boolean;
+  /** Whether the file's transfer function is sRGB (colour maps). */
+  readonly srgb: boolean;
+}
+
+function formatValue(basis: BasisTranscoder, format: TextureFormat): number {
+  const f = TRANSCODER_FORMAT[format];
+  return basis.transcoder_texture_format?.[f.name]?.value ?? f.value;
+}
+
+/** The 12-byte KTX2 identifier: «KTX 20»\r\n\x1a\n. */
+const KTX2_MAGIC = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/**
+ * Transcode a Basis Universal KTX2 file (ETC1S or UASTC) to `format`. A
+ * block format needs level 0 to be a multiple of 4 on both axes (WebGPU's
+ * rule); otherwise the texture comes back as `rgba8`. Throws with the reason
+ * for a file that is not a valid Basis KTX2 (a lossless RGBA8 cook is decoded
+ * by og-cook's runtime, not here).
+ */
+export function transcodeKtx2(basis: BasisTranscoder, bytes: Uint8Array, format: TextureFormat): Transcoded {
+  // The transcoder's own isValid() accepts garbage that merely parses.
+  if (bytes.length < 80 || !KTX2_MAGIC.every((b, i) => bytes[i] === b)) throw new Error("not a KTX2 file: the identifier «KTX 20» is missing");
+  const file = new basis.KTX2File(bytes);
+  try {
+    if (!file.isValid()) throw new Error("not a KTX2 file the Basis transcoder accepts");
+    if (!file.isETC1S() && !file.isUASTC()) throw new Error("not a Basis Universal KTX2 (neither ETC1S nor UASTC): decode it with og-cook's runtime instead");
+    const width = file.getWidth();
+    const height = file.getHeight();
+    const chosen: TextureFormat = format !== "rgba8" && (width % 4 !== 0 || height % 4 !== 0) ? "rgba8" : format;
+    if (!file.startTranscoding()) throw new Error("the Basis transcoder could not start transcoding this file");
+    const value = formatValue(basis, chosen);
+    const levels: Uint8Array[] = [];
+    const sizes: Array<{ width: number; height: number }> = [];
+    for (let level = 0; level < file.getLevels(); level++) {
+      const info = file.getImageLevelInfo(level, 0, 0);
+      const size = file.getImageTranscodedSizeInBytes(level, 0, 0, value);
+      const dst = new Uint8Array(size);
+      if (!file.transcodeImage(dst, level, 0, 0, value, 0, -1, -1)) {
+        throw new Error(`the Basis transcoder failed on level ${level} (${info.origWidth}x${info.origHeight}) to ${chosen}`);
+      }
+      levels.push(dst);
+      sizes.push({ width: info.origWidth, height: info.origHeight });
+    }
+    return {
+      width,
+      height,
+      format: chosen,
+      levels,
+      sizes,
+      kind: file.isUASTC() ? "uastc" : "etc1s",
+      alpha: file.getHasAlpha(),
+      srgb: file.getDFDTransferFunc() === 2,
+    };
+  } finally {
+    file.close();
+    file.delete();
+  }
+}

package/src/web/gamepad.ts

@@ -0,0 +1,123 @@
+// Gamepads on the web (main thread): polled once per display frame. Each
+// standard-mapping pad's state goes to the engine whole whenever it changes
+// (a `gamepad` event: og.Gamepad, the first four pads), and, as a fallback
+// for games that only read keys, as the keys of the mapping below (the same
+// for every game; og-ui counts a pad intent and the key it maps to once).
+//
+//   A (0) Space · B (1) Escape · X (2) KeyX · Y (3) KeyZ
+//   LB (4) KeyQ · RB (5) KeyE · Back (8) Tab · Start (9) Enter
+//   D-pad (12–15) and the left stick (past 0.5) ArrowUp/Down/Left/Right
+
+import { GAMEPAD_BUTTONS, type InjectedInput } from "./input.ts";
+
+export const GAMEPAD_KEYS: Readonly<Record<number, string>> = Object.freeze({
+  0: "Space",
+  1: "Escape",
+  2: "KeyX",
+  3: "KeyZ",
+  4: "KeyQ",
+  5: "KeyE",
+  8: "Tab",
+  9: "Enter",
+  12: "ArrowUp",
+  13: "ArrowDown",
+  14: "ArrowLeft",
+  15: "ArrowRight",
+});
+
+/** The stick deflection that counts as a direction. */
+export const STICK_THRESHOLD = 0.5;
+
+interface PadLike {
+  readonly connected: boolean;
+  readonly mapping: string;
+  readonly buttons: ReadonlyArray<{ readonly pressed: boolean; readonly value?: number }>;
+  readonly axes: ReadonlyArray<number>;
+  readonly index?: number;
+}
+
+/** The `gamepad` events that move the engine's pads from `before` to `now` (keyed by a state string). */
+export function padStates(pads: ReadonlyArray<PadLike | null>, before: Map<number, string>): InjectedInput[] {
+  const out: InjectedInput[] = [];
+  const seen = new Set<number>();
+  pads.forEach((pad, i) => {
+    const index = pad?.index ?? i;
+    if (!pad || !pad.connected || pad.mapping !== "standard" || index > 3) return;
+    seen.add(index);
+    const round = (v: number | undefined) => Math.round((v ?? 0) * 1000) / 1000;
+    const event: InjectedInput = {
+      kind: "gamepad",
+      pad: index,
+      connected: true,
+      buttons: GAMEPAD_BUTTONS.filter((_, b) => pad.buttons[b]?.pressed),
+      axes: [0, 1, 2, 3].map((a) => round(pad.axes[a])),
+      triggers: [round(pad.buttons[6]?.value), round(pad.buttons[7]?.value)],
+    };
+    const key = JSON.stringify(event);
+    if (before.get(index) !== key) {
+      before.set(index, key);
+      out.push(event);
+    }
+  });
+  for (const index of [...before.keys()]) {
+    if (seen.has(index)) continue;
+    before.delete(index);
+    out.push({ kind: "gamepad", pad: index, connected: false, buttons: [], axes: [0, 0, 0, 0], triggers: [0, 0] });
+  }
+  return out;
+}
+
+/** The keys a set of pads holds now (any pad holding a key holds it). */
+export function heldKeys(pads: ReadonlyArray<PadLike | null>): Set<string> {
+  const held = new Set<string>();
+  for (const pad of pads) {
+    if (!pad || !pad.connected || pad.mapping !== "standard") continue;
+    for (const [index, key] of Object.entries(GAMEPAD_KEYS)) if (pad.buttons[Number(index)]?.pressed) held.add(key);
+    const [x = 0, y = 0] = pad.axes;
+    if (x <= -STICK_THRESHOLD) held.add("ArrowLeft");
+    if (x >= STICK_THRESHOLD) held.add("ArrowRight");
+    if (y <= -STICK_THRESHOLD) held.add("ArrowUp");
+    if (y >= STICK_THRESHOLD) held.add("ArrowDown");
+  }
+  return held;
+}
+
+/** The key events that move from `before` to `now`. */
+export function keyEdges(before: ReadonlySet<string>, now: ReadonlySet<string>): InjectedInput[] {
+  const out: InjectedInput[] = [];
+  for (const key of now) if (!before.has(key)) out.push({ kind: "key", key, action: "down" });
+  for (const key of before) if (!now.has(key)) out.push({ kind: "key", key, action: "up" });
+  return out;
+}
+
+/** Poll the page's pads while any is connected; returns the stop function. */
+export function pollGamepads(send: (event: InjectedInput) => void): () => void {
+  const nav = globalThis.navigator as { getGamepads?: () => ReadonlyArray<PadLike | null> } | undefined;
+  if (!nav?.getGamepads) return () => {};
+  let held = new Set<string>();
+  const states = new Map<number, string>();
+  let frame = 0;
+  let stopped = false;
+  const poll = () => {
+    frame = 0;
+    if (stopped) return;
+    const pads = nav.getGamepads!();
+    for (const e of padStates(pads, states)) send(e);
+    const now = heldKeys(pads);
+    for (const e of keyEdges(held, now)) send(e);
+    held = now;
+    if (nav.getGamepads!().some((p) => p?.connected)) frame = requestAnimationFrame(poll);
+  };
+  const connected = () => {
+    if (!frame) frame = requestAnimationFrame(poll);
+  };
+  addEventListener("gamepadconnected", connected);
+  connected();
+  return () => {
+    stopped = true;
+    removeEventListener("gamepadconnected", connected);
+    if (frame) cancelAnimationFrame(frame);
+    for (const e of keyEdges(held, new Set())) send(e);
+    for (const e of padStates([], states)) send(e);
+  };
+}