sci2-ts 0.0.0-stage → 0.2.2

package/tools/node-files.ts

@@ -0,0 +1,33 @@
+import { open, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { FileSource } from "../packages/sci/src/index.ts";
+
+/** FileSource over a local game directory. */
+export function nodeFiles(root: string): FileSource {
+  return {
+    async read(path) {
+      try {
+        return new Uint8Array(await readFile(join(root, path)));
+      } catch {
+        return undefined;
+      }
+    },
+    async readRange(path, offset, length) {
+      const fh = await open(join(root, path));
+      try {
+        const buf = new Uint8Array(length);
+        await fh.read(buf, 0, length, offset);
+        return buf;
+      } finally {
+        await fh.close();
+      }
+    },
+    async list(dir) {
+      try {
+        return await readdir(join(root, dir));
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/tools/patches.d.ts

@@ -0,0 +1,3 @@
+import { ResourceType } from "../packages/sci/src/index.ts";
+/** Writes an SCI patch file: [type | 0x80, 0 extra header bytes] + data, e.g. 770.MSG. */
+export declare function writePatch(dir: string, type: ResourceType, number: number, data: Uint8Array): string;

package/tools/patches.js

@@ -0,0 +1,13 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { ResourceType, patchExtensions } from "../packages/sci/src/index.js";
+/** Writes an SCI patch file: [type | 0x80, 0 extra header bytes] + data, e.g. 770.MSG. */
+export function writePatch(dir, type, number, data) {
+    const ext = Object.entries(patchExtensions).find(([, t]) => t === type)?.[0];
+    if (!ext)
+        throw new Error(`No patch extension for resource type ${type}`);
+    mkdirSync(dir, { recursive: true });
+    const path = `${dir}/${number}.${ext.toUpperCase()}`;
+    writeFileSync(path, Buffer.concat([Buffer.from([type | 0x80, 0]), data]));
+    console.log(`${path}: ${data.length} bytes`);
+    return path;
+}

package/tools/patches.ts

@@ -0,0 +1,13 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { ResourceType, patchExtensions } from "../packages/sci/src/index.ts";
+
+/** Writes an SCI patch file: [type | 0x80, 0 extra header bytes] + data, e.g. 770.MSG. */
+export function writePatch(dir: string, type: ResourceType, number: number, data: Uint8Array): string {
+  const ext = Object.entries(patchExtensions).find(([, t]) => t === type)?.[0];
+  if (!ext) throw new Error(`No patch extension for resource type ${type}`);
+  mkdirSync(dir, { recursive: true });
+  const path = `${dir}/${number}.${ext.toUpperCase()}`;
+  writeFileSync(path, Buffer.concat([Buffer.from([type | 0x80, 0]), data]));
+  console.log(`${path}: ${data.length} bytes`);
+  return path;
+}

package/tools/pic-build.d.ts

@@ -0,0 +1,9 @@
+import { type PicFile, type ResourceManager } from "../packages/sci/src/index.ts";
+/** The base palette (999): the colours every room keeps. */
+export declare function basePalette(rm: ResourceManager): Promise<import("../packages/sci/src/index.ts").Palette>;
+/**
+ * A room picture from PNGs in a directory: `<n>.png` is the background (320x190), and
+ * `<n>.layer-<priority>.png` files (same size, transparent where empty) are foreground
+ * pieces that actors with a lower y walk behind.
+ */
+export declare function picFromPngs(dir: string, n: number, rm: ResourceManager, dither?: boolean): Promise<PicFile>;

package/tools/pic-build.js

@@ -0,0 +1,26 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildRoomPic, emptyPalette, parseHunkPalette, ResourceType } from "../packages/sci/src/index.js";
+import { decodePng } from "./png.js";
+/** The base palette (999): the colours every room keeps. */
+export async function basePalette(rm) {
+    return parseHunkPalette((await rm.load({ type: ResourceType.Palette, number: 999 })).data) ?? emptyPalette();
+}
+/**
+ * A room picture from PNGs in a directory: `<n>.png` is the background (320x190), and
+ * `<n>.layer-<priority>.png` files (same size, transparent where empty) are foreground
+ * pieces that actors with a lower y walk behind.
+ */
+export async function picFromPngs(dir, n, rm, dither = true) {
+    const layers = [];
+    const background = decodePng(readFileSync(join(dir, `${n}.png`)));
+    layers.push({ width: background.width, height: background.height, rgba: background.data, priority: -1000 });
+    for (const f of readdirSync(dir)) {
+        const m = new RegExp(`^${n}\\.layer-(-?\\d+)\\.png$`).exec(f);
+        if (!m)
+            continue;
+        const img = decodePng(readFileSync(join(dir, f)));
+        layers.push({ width: img.width, height: img.height, rgba: img.data, priority: Number(m[1]) });
+    }
+    return buildRoomPic(layers, await basePalette(rm), { dither });
+}

package/tools/pic-build.ts

@@ -0,0 +1,27 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildRoomPic, emptyPalette, parseHunkPalette, ResourceType, type PicFile, type PicLayer, type ResourceManager } from "../packages/sci/src/index.ts";
+import { decodePng } from "./png.ts";
+
+/** The base palette (999): the colours every room keeps. */
+export async function basePalette(rm: ResourceManager) {
+  return parseHunkPalette((await rm.load({ type: ResourceType.Palette, number: 999 })).data) ?? emptyPalette();
+}
+
+/**
+ * A room picture from PNGs in a directory: `<n>.png` is the background (320x190), and
+ * `<n>.layer-<priority>.png` files (same size, transparent where empty) are foreground
+ * pieces that actors with a lower y walk behind.
+ */
+export async function picFromPngs(dir: string, n: number, rm: ResourceManager, dither = true): Promise<PicFile> {
+  const layers: PicLayer[] = [];
+  const background = decodePng(readFileSync(join(dir, `${n}.png`)));
+  layers.push({ width: background.width, height: background.height, rgba: background.data, priority: -1000 });
+  for (const f of readdirSync(dir)) {
+    const m = new RegExp(`^${n}\\.layer-(-?\\d+)\\.png$`).exec(f);
+    if (!m) continue;
+    const img = decodePng(readFileSync(join(dir, f)));
+    layers.push({ width: img.width, height: img.height, rgba: img.data, priority: Number(m[1]) });
+  }
+  return buildRoomPic(layers, await basePalette(rm), { dither });
+}

package/tools/pic.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/pic.js

@@ -0,0 +1,64 @@
+/**
+ * Room pictures.
+ *   pnpm pic export <n> [dir]              <n>.png (background) and <n>.layer-<priority>.png pieces
+ *   pnpm pic import <dir> <n> [outDir]     build pic <n> from <dir>/<n>.png (+ layers) → <n>.P56
+ *   pnpm pic roundtrip                     parse + write every pic, compare bytes
+ * Flags: --no-dither (import).
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ResourceManager, ResourceType, hunkToPalette, mergePalette, parsePicFile, writePic } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+import { writePatch } from "./patches.js";
+import { basePalette, picFromPngs } from "./pic-build.js";
+import { rgbaPng } from "./png.js";
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith("--")));
+const [command = "roundtrip", ...args] = argv.filter((a) => !a.startsWith("--"));
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+/** Composites a pic's layers (or just some) to RGBA, 320x190. */
+function render(pic, palette, only) {
+    const w = 320, h = 190;
+    const data = new Uint8Array(w * h * 4);
+    for (const cel of [...pic.cels].sort((a, b) => a.priority - b.priority)) {
+        if (only && !only(cel.priority))
+            continue;
+        for (let y = 0; y < cel.height; y++)
+            for (let x = 0; x < cel.width; x++) {
+                const c = cel.pixels[y * cel.width + x];
+                const X = cel.x + x, Y = cel.y + y;
+                if (c === cel.skipColor || X < 0 || Y < 0 || X >= w || Y >= h)
+                    continue;
+                data.set([palette.rgb[c * 3], palette.rgb[c * 3 + 1], palette.rgb[c * 3 + 2], 255], (Y * w + X) * 4);
+            }
+    }
+    return { width: w, height: h, data };
+}
+if (command === "export") {
+    const n = Number(args[0]);
+    const dir = args[1] ?? "out/pics";
+    mkdirSync(dir, { recursive: true });
+    const pic = parsePicFile((await rm.load({ type: ResourceType.Pic, number: n })).data);
+    const palette = mergePalette(await basePalette(rm), hunkToPalette(pic.palette));
+    writeFileSync(join(dir, `${n}.png`), rgbaPng(render(pic, palette, (p) => p === -1000)));
+    for (const p of new Set(pic.cels.map((c) => c.priority).filter((p) => p > -1000))) {
+        writeFileSync(join(dir, `${n}.layer-${p}.png`), rgbaPng(render(pic, palette, (q) => q === p)));
+    }
+    console.log(`pic ${n}: ${pic.cels.length} cels → ${dir}/${n}.png${pic.cels.length > 1 ? ` + ${pic.cels.length - 1} layers` : ""}`);
+}
+else if (command === "import") {
+    const [dir, n, outDir = "out/pics"] = [args[0], Number(args[1]), args[2]];
+    const pic = await picFromPngs(dir, n, rm, !flags.has("--no-dither"));
+    writePatch(outDir, ResourceType.Pic, n, writePic(pic));
+}
+else {
+    const list = rm.list(ResourceType.Pic);
+    const bad = [];
+    for (const info of list) {
+        const d = Buffer.from((await rm.load(info)).data);
+        if (d.compare(Buffer.from(writePic(parsePicFile(d)))))
+            bad.push(info.number);
+    }
+    console.log(`${list.length - bad.length}/${list.length} pics round-trip byte-exact${bad.length ? `; differ: ${bad.join(" ")}` : ""}`);
+    process.exitCode = bad.length ? 1 : 0;
+}

package/tools/pic.ts

@@ -0,0 +1,61 @@
+/**
+ * Room pictures.
+ *   pnpm pic export <n> [dir]              <n>.png (background) and <n>.layer-<priority>.png pieces
+ *   pnpm pic import <dir> <n> [outDir]     build pic <n> from <dir>/<n>.png (+ layers) → <n>.P56
+ *   pnpm pic roundtrip                     parse + write every pic, compare bytes
+ * Flags: --no-dither (import).
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ResourceManager, ResourceType, hunkToPalette, mergePalette, parsePicFile, writePic, type PicFile } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+import { writePatch } from "./patches.ts";
+import { basePalette, picFromPngs } from "./pic-build.ts";
+import { rgbaPng } from "./png.ts";
+
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith("--")));
+const [command = "roundtrip", ...args] = argv.filter((a) => !a.startsWith("--"));
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+
+/** Composites a pic's layers (or just some) to RGBA, 320x190. */
+function render(pic: PicFile, palette: ReturnType<typeof hunkToPalette>, only?: (priority: number) => boolean) {
+  const w = 320, h = 190;
+  const data = new Uint8Array(w * h * 4);
+  for (const cel of [...pic.cels].sort((a, b) => a.priority - b.priority)) {
+    if (only && !only(cel.priority)) continue;
+    for (let y = 0; y < cel.height; y++) for (let x = 0; x < cel.width; x++) {
+      const c = cel.pixels[y * cel.width + x]!;
+      const X = cel.x + x, Y = cel.y + y;
+      if (c === cel.skipColor || X < 0 || Y < 0 || X >= w || Y >= h) continue;
+      data.set([palette.rgb[c * 3]!, palette.rgb[c * 3 + 1]!, palette.rgb[c * 3 + 2]!, 255], (Y * w + X) * 4);
+    }
+  }
+  return { width: w, height: h, data };
+}
+
+if (command === "export") {
+  const n = Number(args[0]);
+  const dir = args[1] ?? "out/pics";
+  mkdirSync(dir, { recursive: true });
+  const pic = parsePicFile((await rm.load({ type: ResourceType.Pic, number: n })).data);
+  const palette = mergePalette(await basePalette(rm), hunkToPalette(pic.palette));
+  writeFileSync(join(dir, `${n}.png`), rgbaPng(render(pic, palette, (p) => p === -1000)));
+  for (const p of new Set(pic.cels.map((c) => c.priority).filter((p) => p > -1000))) {
+    writeFileSync(join(dir, `${n}.layer-${p}.png`), rgbaPng(render(pic, palette, (q) => q === p)));
+  }
+  console.log(`pic ${n}: ${pic.cels.length} cels → ${dir}/${n}.png${pic.cels.length > 1 ? ` + ${pic.cels.length - 1} layers` : ""}`);
+} else if (command === "import") {
+  const [dir, n, outDir = "out/pics"] = [args[0]!, Number(args[1]), args[2]];
+  const pic = await picFromPngs(dir, n, rm, !flags.has("--no-dither"));
+  writePatch(outDir, ResourceType.Pic, n, writePic(pic));
+} else {
+  const list = rm.list(ResourceType.Pic);
+  const bad: number[] = [];
+  for (const info of list) {
+    const d = Buffer.from((await rm.load(info)).data);
+    if (d.compare(Buffer.from(writePic(parsePicFile(d))))) bad.push(info.number);
+  }
+  console.log(`${list.length - bad.length}/${list.length} pics round-trip byte-exact${bad.length ? `; differ: ${bad.join(" ")}` : ""}`);
+  process.exitCode = bad.length ? 1 : 0;
+}

package/tools/play.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/play.js

@@ -0,0 +1,54 @@
+/**
+ * Headless game runner for debugging the VM.
+ *   pnpm play [--frames N] [--trace] [--png-every K]
+ *     boot the game, run N FrameOut cycles, report kernel usage, save every Kth frame to out/
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { ResourceManager, Vm, allKernels, formatValue, graphics } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+import { framePng } from "./png.js";
+const argv = process.argv.slice(2);
+const frames = Number(argv[argv.indexOf("--frames") + 1] || 1);
+const trace = argv.includes("--trace");
+const pngEvery = Number(argv[argv.indexOf("--png-every") + 1] || 0) || (argv.includes("--png-every") ? 1 : 0);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+await rm.preload();
+const vm = new Vm(rm);
+vm.registerKernels(allKernels);
+// Deterministic time: each frame is one 60 Hz tick, however fast we actually run.
+vm.clock = () => (graphics(vm).frames * 1000) / 60;
+const calls = new Map();
+vm.onKernelCall = (name, args, result) => {
+    calls.set(name, (calls.get(name) ?? 0) + 1);
+    if (trace)
+        console.log(`  ${name}(${args.map(formatValue).join(", ")}) → ${formatValue(result)}`);
+};
+if (pngEvery)
+    mkdirSync("out/frames", { recursive: true });
+graphics(vm).onFrame = (f) => {
+    const n = graphics(vm).frames;
+    if (pngEvery && n % pngEvery === 0)
+        writeFileSync(`out/frames/${String(n).padStart(5, "0")}.png`, framePng(f));
+};
+const game = vm.exportAddress(0, 0);
+console.log(`game object: ${vm.object(game).name}`);
+vm.start(game, "play");
+let frame = 0;
+const t0 = performance.now();
+try {
+    while (vm.running && frame < frames) {
+        vm.run();
+        if (vm.yieldRequested)
+            frame++;
+        else if (vm.running)
+            throw new Error("instruction budget exhausted without a frame (infinite loop?)");
+    }
+}
+catch (e) {
+    console.log(`\nERROR: ${e.message}`);
+    console.log(vm.backtrace().map((l) => `  at ${l}`).join("\n"));
+}
+const ms = performance.now() - t0;
+console.log(`\n${vm.instructions.toLocaleString()} instructions in ${ms.toFixed(0)} ms, ${frame} frame(s), running=${vm.running}`);
+console.log("kernel calls:", Object.fromEntries([...calls].sort((a, b) => b[1] - a[1])));
+console.log("missing kernels:", Object.fromEntries(vm.missingKernels));

package/tools/play.ts

@@ -0,0 +1,54 @@
+/**
+ * Headless game runner for debugging the VM.
+ *   pnpm play [--frames N] [--trace] [--png-every K]
+ *     boot the game, run N FrameOut cycles, report kernel usage, save every Kth frame to out/
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { ResourceManager, Vm, allKernels, formatValue, graphics } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+import { framePng } from "./png.ts";
+
+const argv = process.argv.slice(2);
+const frames = Number(argv[argv.indexOf("--frames") + 1] || 1);
+const trace = argv.includes("--trace");
+const pngEvery = Number(argv[argv.indexOf("--png-every") + 1] || 0) || (argv.includes("--png-every") ? 1 : 0);
+
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+await rm.preload();
+const vm = new Vm(rm);
+vm.registerKernels(allKernels);
+// Deterministic time: each frame is one 60 Hz tick, however fast we actually run.
+vm.clock = () => (graphics(vm).frames * 1000) / 60;
+
+const calls = new Map<string, number>();
+vm.onKernelCall = (name, args, result) => {
+  calls.set(name, (calls.get(name) ?? 0) + 1);
+  if (trace) console.log(`  ${name}(${args.map(formatValue).join(", ")}) → ${formatValue(result)}`);
+};
+
+if (pngEvery) mkdirSync("out/frames", { recursive: true });
+graphics(vm).onFrame = (f) => {
+  const n = graphics(vm).frames;
+  if (pngEvery && n % pngEvery === 0) writeFileSync(`out/frames/${String(n).padStart(5, "0")}.png`, framePng(f));
+};
+
+const game = vm.exportAddress(0, 0);
+console.log(`game object: ${vm.object(game).name}`);
+vm.start(game, "play");
+
+let frame = 0;
+const t0 = performance.now();
+try {
+  while (vm.running && frame < frames) {
+    vm.run();
+    if (vm.yieldRequested) frame++;
+    else if (vm.running) throw new Error("instruction budget exhausted without a frame (infinite loop?)");
+  }
+} catch (e) {
+  console.log(`\nERROR: ${(e as Error).message}`);
+  console.log(vm.backtrace().map((l) => `  at ${l}`).join("\n"));
+}
+const ms = performance.now() - t0;
+console.log(`\n${vm.instructions.toLocaleString()} instructions in ${ms.toFixed(0)} ms, ${frame} frame(s), running=${vm.running}`);
+console.log("kernel calls:", Object.fromEntries([...calls].sort((a, b) => b[1] - a[1])));
+console.log("missing kernels:", Object.fromEntries(vm.missingKernels));

package/tools/png.d.ts

@@ -0,0 +1,16 @@
+import { type Frame } from "../packages/sci/src/index.ts";
+/** Encodes an indexed frame as an RGB PNG, optionally scaled up (with 4:3 aspect correction). */
+export declare function framePng(frame: Frame, scale?: number): Buffer;
+/** An RGBA image. */
+export interface Rgba {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** Encodes RGBA pixels as a PNG, 1:1. */
+export declare function rgbaPng(img: Rgba): Buffer;
+/**
+ * Decodes an 8-bit, non-interlaced PNG (greyscale, RGB, palette, grey+alpha or RGBA) to RGBA.
+ * Enough for art made in any paint program.
+ */
+export declare function decodePng(file: Uint8Array): Rgba;

package/tools/png.js

@@ -0,0 +1,124 @@
+import { deflateSync, inflateSync } from "node:zlib";
+import { frameRgb } from "../packages/sci/src/index.js";
+const crcTable = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+const crc32 = (buf) => {
+    let c = 0xffffffff;
+    for (const b of buf)
+        c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+};
+function chunk(type, data) {
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    out.write(type, 4, "ascii");
+    out.set(data, 8);
+    out.writeUInt32BE(crc32(out.subarray(4, 8 + data.length)), 8 + data.length);
+    return out;
+}
+/** Encodes an indexed frame as an RGB PNG, optionally scaled up (with 4:3 aspect correction). */
+export function framePng(frame, scale = 2) {
+    const w = frame.width * scale, h = Math.round(frame.height * scale * 1.2);
+    const raw = Buffer.alloc((w * 3 + 1) * h);
+    const rgb = frameRgb(frame);
+    for (let y = 0; y < h; y++) {
+        const sy = Math.min(frame.height - 1, Math.floor(y / (scale * 1.2)));
+        raw[y * (w * 3 + 1)] = 0;
+        for (let x = 0; x < w; x++) {
+            const i = (sy * frame.width + Math.floor(x / scale)) * 3;
+            raw.set(rgb.subarray(i, i + 3), y * (w * 3 + 1) + 1 + x * 3);
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 2; // RGB
+    return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", new Uint8Array())]);
+}
+/** Encodes RGBA pixels as a PNG, 1:1. */
+export function rgbaPng(img) {
+    const { width: w, height: h } = img;
+    const raw = Buffer.alloc((w * 4 + 1) * h);
+    for (let y = 0; y < h; y++)
+        raw.set(img.data.subarray(y * w * 4, (y + 1) * w * 4), y * (w * 4 + 1) + 1);
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6; // RGBA
+    return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", new Uint8Array(0))]);
+}
+/**
+ * Decodes an 8-bit, non-interlaced PNG (greyscale, RGB, palette, grey+alpha or RGBA) to RGBA.
+ * Enough for art made in any paint program.
+ */
+export function decodePng(file) {
+    const b = Buffer.from(file);
+    if (b.readUInt32BE(0) !== 0x89504e47)
+        throw new Error("Not a PNG");
+    let width = 0, height = 0, depth = 0, type = 0, interlace = 0;
+    let plte, trns;
+    const idat = [];
+    for (let p = 8; p < b.length;) {
+        const len = b.readUInt32BE(p), kind = b.toString("ascii", p + 4, p + 8), data = b.subarray(p + 8, p + 8 + len);
+        if (kind === "IHDR")
+            [width, height, depth, type, interlace] = [data.readUInt32BE(0), data.readUInt32BE(4), data[8], data[9], data[12]];
+        else if (kind === "PLTE")
+            plte = data;
+        else if (kind === "tRNS")
+            trns = data;
+        else if (kind === "IDAT")
+            idat.push(data);
+        p += 12 + len;
+    }
+    if (depth !== 8 || interlace)
+        throw new Error(`Only 8-bit non-interlaced PNGs are supported (bit depth ${depth}, interlace ${interlace})`);
+    const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+    if (!channels)
+        throw new Error(`Unsupported PNG colour type ${type}`);
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = width * channels;
+    const px = new Uint8Array(stride * height);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * (stride + 1)];
+        const src = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+        for (let x = 0; x < stride; x++) {
+            const a = x >= channels ? px[y * stride + x - channels] : 0;
+            const up = y ? px[(y - 1) * stride + x] : 0;
+            const c = y && x >= channels ? px[(y - 1) * stride + x - channels] : 0;
+            const pred = filter === 1 ? a : filter === 2 ? up : filter === 3 ? (a + up) >> 1 : filter === 4 ? paeth(a, up, c) : 0;
+            px[y * stride + x] = (src[x] + pred) & 0xff;
+        }
+    }
+    const data = new Uint8Array(width * height * 4);
+    for (let i = 0; i < width * height; i++) {
+        const s = px.subarray(i * channels, i * channels + channels);
+        let r, g, bl, al = 255;
+        if (type === 3) {
+            const k = s[0];
+            [r, g, bl] = [plte[k * 3], plte[k * 3 + 1], plte[k * 3 + 2]];
+            al = trns && k < trns.length ? trns[k] : 255;
+        }
+        else if (type === 0 || type === 4) {
+            r = g = bl = s[0];
+            if (type === 4)
+                al = s[1];
+        }
+        else {
+            [r, g, bl] = [s[0], s[1], s[2]];
+            if (type === 6)
+                al = s[3];
+        }
+        data.set([r, g, bl, al], i * 4);
+    }
+    return { width, height, data };
+}
+function paeth(a, b, c) {
+    const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}

package/tools/png.ts

@@ -0,0 +1,123 @@
+import { deflateSync, inflateSync } from "node:zlib";
+import { frameRgb, type Frame } from "../packages/sci/src/index.ts";
+
+const crcTable = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+const crc32 = (buf: Uint8Array) => {
+  let c = 0xffffffff;
+  for (const b of buf) c = crcTable[(c ^ b) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+};
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const out = Buffer.alloc(12 + data.length);
+  out.writeUInt32BE(data.length, 0);
+  out.write(type, 4, "ascii");
+  out.set(data, 8);
+  out.writeUInt32BE(crc32(out.subarray(4, 8 + data.length)), 8 + data.length);
+  return out;
+}
+
+/** Encodes an indexed frame as an RGB PNG, optionally scaled up (with 4:3 aspect correction). */
+export function framePng(frame: Frame, scale = 2): Buffer {
+  const w = frame.width * scale, h = Math.round(frame.height * scale * 1.2);
+  const raw = Buffer.alloc((w * 3 + 1) * h);
+  const rgb = frameRgb(frame);
+  for (let y = 0; y < h; y++) {
+    const sy = Math.min(frame.height - 1, Math.floor(y / (scale * 1.2)));
+    raw[y * (w * 3 + 1)] = 0;
+    for (let x = 0; x < w; x++) {
+      const i = (sy * frame.width + Math.floor(x / scale)) * 3;
+      raw.set(rgb.subarray(i, i + 3), y * (w * 3 + 1) + 1 + x * 3);
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // RGB
+  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", new Uint8Array())]);
+}
+
+/** An RGBA image. */
+export interface Rgba {
+  width: number;
+  height: number;
+  data: Uint8Array; // width * height * 4
+}
+
+/** Encodes RGBA pixels as a PNG, 1:1. */
+export function rgbaPng(img: Rgba): Buffer {
+  const { width: w, height: h } = img;
+  const raw = Buffer.alloc((w * 4 + 1) * h);
+  for (let y = 0; y < h; y++) raw.set(img.data.subarray(y * w * 4, (y + 1) * w * 4), y * (w * 4 + 1) + 1);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6; // RGBA
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", new Uint8Array(0))]);
+}
+
+/**
+ * Decodes an 8-bit, non-interlaced PNG (greyscale, RGB, palette, grey+alpha or RGBA) to RGBA.
+ * Enough for art made in any paint program.
+ */
+export function decodePng(file: Uint8Array): Rgba {
+  const b = Buffer.from(file);
+  if (b.readUInt32BE(0) !== 0x89504e47) throw new Error("Not a PNG");
+  let width = 0, height = 0, depth = 0, type = 0, interlace = 0;
+  let plte: Uint8Array | undefined, trns: Uint8Array | undefined;
+  const idat: Buffer[] = [];
+  for (let p = 8; p < b.length; ) {
+    const len = b.readUInt32BE(p), kind = b.toString("ascii", p + 4, p + 8), data = b.subarray(p + 8, p + 8 + len);
+    if (kind === "IHDR") [width, height, depth, type, interlace] = [data.readUInt32BE(0), data.readUInt32BE(4), data[8]!, data[9]!, data[12]!];
+    else if (kind === "PLTE") plte = data;
+    else if (kind === "tRNS") trns = data;
+    else if (kind === "IDAT") idat.push(data);
+    p += 12 + len;
+  }
+  if (depth !== 8 || interlace) throw new Error(`Only 8-bit non-interlaced PNGs are supported (bit depth ${depth}, interlace ${interlace})`);
+  const channels = ({ 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 } as Record<number, number>)[type];
+  if (!channels) throw new Error(`Unsupported PNG colour type ${type}`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const px = new Uint8Array(stride * height);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]!;
+    const src = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? px[y * stride + x - channels]! : 0;
+      const up = y ? px[(y - 1) * stride + x]! : 0;
+      const c = y && x >= channels ? px[(y - 1) * stride + x - channels]! : 0;
+      const pred = filter === 1 ? a : filter === 2 ? up : filter === 3 ? (a + up) >> 1 : filter === 4 ? paeth(a, up, c) : 0;
+      px[y * stride + x] = (src[x]! + pred) & 0xff;
+    }
+  }
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    const s = px.subarray(i * channels, i * channels + channels);
+    let r: number, g: number, bl: number, al = 255;
+    if (type === 3) {
+      const k = s[0]!;
+      [r, g, bl] = [plte![k * 3]!, plte![k * 3 + 1]!, plte![k * 3 + 2]!];
+      al = trns && k < trns.length ? trns[k]! : 255;
+    } else if (type === 0 || type === 4) {
+      r = g = bl = s[0]!;
+      if (type === 4) al = s[1]!;
+    } else {
+      [r, g, bl] = [s[0]!, s[1]!, s[2]!];
+      if (type === 6) al = s[3]!;
+    }
+    data.set([r, g, bl, al], i * 4);
+  }
+  return { width, height, data };
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}

package/tools/res.d.ts

@@ -0,0 +1 @@
+export {};