sci2-ts 0.0.0-stage → 0.2.1

package/packages/sci/src/script/sexpr.ts

@@ -0,0 +1,139 @@
+/**
+ * The reader for SCI script source: parenthesised lists, with a few kinds of atom.
+ *
+ *   (send obj x: 1)      a list                  [buf 3]   an array element (or declaration)
+ *   foo  x:  y?  &rest   symbols                  42 -7 $1F %101 `a   numbers
+ *   "text" {text}        strings                  #init     a selector
+ *   @buf  @[buf i]       a variable's address, an element's   ; ...  a comment, to the end of the line
+ */
+export type Node =
+  | { kind: "list"; items: Node[]; line: number }
+  | { kind: "index"; items: Node[]; line: number }
+  | { kind: "sym"; name: string; line: number }
+  | { kind: "num"; value: number; line: number }
+  | { kind: "str"; value: string; line: number }
+  | { kind: "sel"; name: string; line: number }
+  | { kind: "addr"; name: string; index?: Node; line: number };
+
+export class ReadError extends Error {
+  constructor(message: string, readonly line: number) {
+    super(`line ${line}: ${message}`);
+  }
+}
+
+const DELIMITERS = new Set([..."()[]{}\";"]);
+const isSpace = (c: string) => c === " " || c === "\t" || c === "\r" || c === "\n";
+
+export function read(text: string): Node[] {
+  let p = 0, line = 1;
+  const top: Node[] = [];
+  const stack: { node: Node & { items: Node[] }; close: string }[] = [];
+  const add = (n: Node) => (stack.length ? stack[stack.length - 1]!.node.items : top).push(n);
+
+  while (p < text.length) {
+    const c = text[p]!;
+    if (c === "\n") { line++; p++; continue; }
+    if (isSpace(c)) { p++; continue; }
+    if (c === ";") { while (p < text.length && text[p] !== "\n") p++; continue; }
+    if (c === "(" || c === "[") {
+      const node = { kind: c === "(" ? "list" : "index", items: [], line } as Node & { items: Node[] };
+      add(node);
+      stack.push({ node, close: c === "(" ? ")" : "]" });
+      p++;
+      continue;
+    }
+    if (c === ")" || c === "]") {
+      const open = stack.pop();
+      if (!open) throw new ReadError(`unexpected ${c}`, line);
+      if (open.close !== c) throw new ReadError(`expected ${open.close} to close the ${open.close === ")" ? "(" : "["} on line ${open.node.line}, got ${c}`, line);
+      p++;
+      continue;
+    }
+    if (c === '"' || c === "{") {
+      const end = c === '"' ? '"' : "}";
+      const start = line;
+      let value = "";
+      p++;
+      for (;;) {
+        if (p >= text.length) throw new ReadError("string never ends", start);
+        const ch = text[p]!;
+        if (ch === end) { p++; break; }
+        if (ch === "\n") line++;
+        if (ch === "\\") {
+          const n = text[p + 1] ?? "";
+          if (n === "n") value += "\n";
+          else if (n === "t") value += "\t";
+          else if (/[0-9a-fA-F]/.test(n) && /[0-9a-fA-F]/.test(text[p + 2] ?? "")) {
+            value += String.fromCharCode(parseInt(text.slice(p + 1, p + 3), 16));
+            p++;
+          } else value += n;
+          p += 2;
+          continue;
+        }
+        value += ch;
+        p++;
+      }
+      add({ kind: "str", value, line: start });
+      continue;
+    }
+    if (c === "`") {
+      // A character: `a is 97; `^a is control-A; `#4 is a key with a scan code (not supported).
+      const ch = text[p + 1];
+      if (ch === undefined) throw new ReadError("` needs a character", line);
+      if (ch === "^" && text[p + 2] && !isSpace(text[p + 2]!)) {
+        add({ kind: "num", value: text[p + 2]!.toUpperCase().charCodeAt(0) - 64, line });
+        p += 3;
+      } else {
+        add({ kind: "num", value: ch.charCodeAt(0), line });
+        p += 2;
+      }
+      continue;
+    }
+    let e = p;
+    while (e < text.length && !isSpace(text[e]!) && !DELIMITERS.has(text[e]!)) e++;
+    const token = text.slice(p, e);
+    p = e;
+    add(atom(token, line));
+  }
+  if (stack.length) throw new ReadError(`( never closed`, stack[stack.length - 1]!.node.line);
+  return addresses(top);
+}
+
+/** `@` then `[buf i]` is one thing: the address of an element. */
+function addresses(nodes: Node[]): Node[] {
+  const out: Node[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i]!;
+    const next = nodes[i + 1];
+    if (n.kind === "sym" && n.name === "@" && next?.kind === "index" && next.items.length === 2 && next.items[0]!.kind === "sym") {
+      out.push({ kind: "addr", name: (next.items[0] as { name: string }).name, index: addresses([next.items[1]!])[0], line: n.line });
+      i++;
+      continue;
+    }
+    if (n.kind === "list" || n.kind === "index") out.push({ ...n, items: addresses(n.items) });
+    else out.push(n);
+  }
+  return out;
+}
+
+function atom(token: string, line: number): Node {
+  if (/^-?\d+$/.test(token)) return { kind: "num", value: Number(token), line };
+  if (/^-?\$[0-9a-fA-F]+$/.test(token)) return { kind: "num", value: (token.startsWith("-") ? -1 : 1) * parseInt(token.replace(/^-?\$/, ""), 16), line };
+  if (/^%[01]+$/.test(token)) return { kind: "num", value: parseInt(token.slice(1), 2), line };
+  if (token.startsWith("#") && token.length > 1) return { kind: "sel", name: token.slice(1), line };
+  if (token.startsWith("@") && token.length > 1) return { kind: "addr", name: token.slice(1), line };
+  return { kind: "sym", name: token, line };
+}
+
+/** A node as source text again, for error messages. */
+export function show(n: Node): string {
+  switch (n.kind) {
+    case "list": return `(${n.items.map(show).join(" ")})`;
+    case "index": return `[${n.items.map(show).join(" ")}]`;
+    case "sym": return n.name;
+    case "num": return String(n.value);
+    case "str": return JSON.stringify(n.value);
+    case "sel": return `#${n.name}`;
+    case "addr": return n.index ? `@[${n.name} ${show(n.index)}]` : `@${n.name}`;
+  }
+}

package/packages/sci/src/script/vocab.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vocab 997: selector names, indexed by selector id. Selectors name every property and
+ * method across all classes (e.g. 0x93 = init, 0x45 = doit).
+ *   u16 count, u16 offset per selector → { u16 length, chars }
+ */
+export declare function parseSelectorNames(data: Uint8Array): string[];
+/**
+ * Vocab 996: which script defines each class, indexed by class (species) number.
+ *   4 bytes per class: u16 (unused), u16 script number
+ */
+export declare function parseClassTable(data: Uint8Array): number[];
+/** Vocab 997 from selector names, in id order (the inverse of parseSelectorNames). */
+export declare function writeSelectorNames(names: readonly string[]): Uint8Array;
+/** Vocab 996 from the script defining each class, by species (the inverse of parseClassTable). */
+export declare function writeClassTable(scripts: readonly number[]): Uint8Array;

package/packages/sci/src/script/vocab.js

@@ -0,0 +1,44 @@
+const view = (d) => new DataView(d.buffer, d.byteOffset, d.byteLength);
+/**
+ * Vocab 997: selector names, indexed by selector id. Selectors name every property and
+ * method across all classes (e.g. 0x93 = init, 0x45 = doit).
+ *   u16 count, u16 offset per selector → { u16 length, chars }
+ */
+export function parseSelectorNames(data) {
+    const v = view(data);
+    const count = v.getUint16(0, true);
+    const decoder = new TextDecoder("latin1");
+    return Array.from({ length: count }, (_, i) => {
+        const o = v.getUint16(2 + i * 2, true);
+        return decoder.decode(data.subarray(o + 2, o + 2 + v.getUint16(o, true)));
+    });
+}
+/**
+ * Vocab 996: which script defines each class, indexed by class (species) number.
+ *   4 bytes per class: u16 (unused), u16 script number
+ */
+export function parseClassTable(data) {
+    const v = view(data);
+    return Array.from({ length: data.length / 4 }, (_, i) => v.getUint16(i * 4 + 2, true));
+}
+/** Vocab 997 from selector names, in id order (the inverse of parseSelectorNames). */
+export function writeSelectorNames(names) {
+    const bytes = names.map((n) => Uint8Array.from(n, (ch) => ch.charCodeAt(0) & 0xff));
+    const out = new Uint8Array(2 + names.length * 2 + bytes.reduce((n, b) => n + 2 + b.length, 0));
+    const v = view(out);
+    v.setUint16(0, names.length, true);
+    let at = 2 + names.length * 2;
+    bytes.forEach((b, i) => {
+        v.setUint16(2 + i * 2, at, true);
+        v.setUint16(at, b.length, true);
+        out.set(b, at + 2);
+        at += 2 + b.length;
+    });
+    return out;
+}
+/** Vocab 996 from the script defining each class, by species (the inverse of parseClassTable). */
+export function writeClassTable(scripts) {
+    const out = new Uint8Array(scripts.length * 4);
+    scripts.forEach((s, i) => view(out).setUint16(i * 4 + 2, s, true));
+    return out;
+}

package/packages/sci/src/script/vocab.ts

@@ -0,0 +1,48 @@
+const view = (d: Uint8Array) => new DataView(d.buffer, d.byteOffset, d.byteLength);
+
+/**
+ * Vocab 997: selector names, indexed by selector id. Selectors name every property and
+ * method across all classes (e.g. 0x93 = init, 0x45 = doit).
+ *   u16 count, u16 offset per selector → { u16 length, chars }
+ */
+export function parseSelectorNames(data: Uint8Array): string[] {
+  const v = view(data);
+  const count = v.getUint16(0, true);
+  const decoder = new TextDecoder("latin1");
+  return Array.from({ length: count }, (_, i) => {
+    const o = v.getUint16(2 + i * 2, true);
+    return decoder.decode(data.subarray(o + 2, o + 2 + v.getUint16(o, true)));
+  });
+}
+
+/**
+ * Vocab 996: which script defines each class, indexed by class (species) number.
+ *   4 bytes per class: u16 (unused), u16 script number
+ */
+export function parseClassTable(data: Uint8Array): number[] {
+  const v = view(data);
+  return Array.from({ length: data.length / 4 }, (_, i) => v.getUint16(i * 4 + 2, true));
+}
+
+/** Vocab 997 from selector names, in id order (the inverse of parseSelectorNames). */
+export function writeSelectorNames(names: readonly string[]): Uint8Array {
+  const bytes = names.map((n) => Uint8Array.from(n, (ch) => ch.charCodeAt(0) & 0xff));
+  const out = new Uint8Array(2 + names.length * 2 + bytes.reduce((n, b) => n + 2 + b.length, 0));
+  const v = view(out);
+  v.setUint16(0, names.length, true);
+  let at = 2 + names.length * 2;
+  bytes.forEach((b, i) => {
+    v.setUint16(2 + i * 2, at, true);
+    v.setUint16(at, b.length, true);
+    out.set(b, at + 2);
+    at += 2 + b.length;
+  });
+  return out;
+}
+
+/** Vocab 996 from the script defining each class, by species (the inverse of parseClassTable). */
+export function writeClassTable(scripts: readonly number[]): Uint8Array {
+  const out = new Uint8Array(scripts.length * 4);
+  scripts.forEach((s, i) => view(out).setUint16(i * 4 + 2, s, true));
+  return out;
+}

package/packages/sci/src/script/world.d.ts

@@ -0,0 +1,25 @@
+import type { ResourceManager } from "../resource/manager.ts";
+import type { AsmContext } from "./assembly.ts";
+import type { DisasmContext } from "./disasm.ts";
+import { type Script, type ScriptObject } from "./script.ts";
+/**
+ * Game-wide script knowledge: selector names, the class table, and lazily loaded scripts.
+ * Resolves class names and property layouts across script boundaries.
+ */
+export declare class ScriptWorld {
+    private readonly rm;
+    readonly selectorNames: string[];
+    readonly classScripts: number[];
+    private readonly scripts;
+    private readonly classes;
+    private constructor();
+    static open(rm: ResourceManager): Promise<ScriptWorld>;
+    script(number: number): Promise<Script>;
+    /** Loads every script that defines a class, so class lookups are synchronous afterwards. */
+    loadAllClasses(): Promise<void>;
+    classObject(species: number): ScriptObject | undefined;
+    /** For the assembler: names both ways and class layouts. Requires `loadAllClasses()`. */
+    asmContext(): AsmContext;
+    /** Requires `loadAllClasses()` first. */
+    context(): DisasmContext;
+}

package/packages/sci/src/script/world.js

@@ -0,0 +1,65 @@
+import { ResourceType } from "../resource/types.js";
+import { kernelNames } from "./kernel-names.js";
+import { parseScript } from "./script.js";
+import { parseClassTable, parseSelectorNames } from "./vocab.js";
+/**
+ * Game-wide script knowledge: selector names, the class table, and lazily loaded scripts.
+ * Resolves class names and property layouts across script boundaries.
+ */
+export class ScriptWorld {
+    rm;
+    selectorNames;
+    classScripts;
+    scripts = new Map();
+    classes = new Map();
+    constructor(rm, selectorNames, classScripts) {
+        this.rm = rm;
+        this.selectorNames = selectorNames;
+        this.classScripts = classScripts;
+    }
+    static async open(rm) {
+        const vocab = async (n) => (await rm.load({ type: ResourceType.Vocab, number: n })).data;
+        return new ScriptWorld(rm, parseSelectorNames(await vocab(997)), parseClassTable(await vocab(996)));
+    }
+    async script(number) {
+        let s = this.scripts.get(number);
+        if (!s) {
+            const code = (await this.rm.load({ type: ResourceType.Script, number })).data;
+            const heap = (await this.rm.load({ type: ResourceType.Heap, number })).data;
+            s = parseScript(number, code, heap);
+            this.scripts.set(number, s);
+            for (const obj of s.objects)
+                if (obj.isClass)
+                    this.classes.set(obj.species, obj);
+        }
+        return s;
+    }
+    /** Loads every script that defines a class, so class lookups are synchronous afterwards. */
+    async loadAllClasses() {
+        const numbers = new Set(this.classScripts.filter((n) => this.rm.has({ type: ResourceType.Script, number: n })));
+        for (const n of numbers)
+            await this.script(n);
+    }
+    classObject(species) {
+        return this.classes.get(species);
+    }
+    /** For the assembler: names both ways and class layouts. Requires `loadAllClasses()`. */
+    asmContext() {
+        const byName = new Map([...this.classes.values()].map((c) => [c.name, c.species]));
+        return {
+            ...this.context(),
+            classSpecies: (name) => byName.get(name),
+            classPropSelectors: (species) => this.classes.get(species)?.propSelectors,
+            classDefaults: (species) => this.classes.get(species)?.properties,
+        };
+    }
+    /** Requires `loadAllClasses()` first. */
+    context() {
+        return {
+            selectorNames: this.selectorNames,
+            kernelNames,
+            className: (species) => this.classes.get(species)?.name,
+            propSelectors: (obj) => (obj.isClass ? obj.propSelectors : this.classes.get(obj.superclass)?.propSelectors),
+        };
+    }
+}

package/packages/sci/src/script/world.ts

@@ -0,0 +1,70 @@
+import type { ResourceManager } from "../resource/manager.ts";
+import { ResourceType } from "../resource/types.ts";
+import type { AsmContext } from "./assembly.ts";
+import type { DisasmContext } from "./disasm.ts";
+import { kernelNames } from "./kernel-names.ts";
+import { parseScript, type Script, type ScriptObject } from "./script.ts";
+import { parseClassTable, parseSelectorNames } from "./vocab.ts";
+
+/**
+ * Game-wide script knowledge: selector names, the class table, and lazily loaded scripts.
+ * Resolves class names and property layouts across script boundaries.
+ */
+export class ScriptWorld {
+  private readonly scripts = new Map<number, Script>();
+  private readonly classes = new Map<number, ScriptObject>();
+
+  private constructor(
+    private readonly rm: ResourceManager,
+    readonly selectorNames: string[],
+    readonly classScripts: number[],
+  ) {}
+
+  static async open(rm: ResourceManager): Promise<ScriptWorld> {
+    const vocab = async (n: number) => (await rm.load({ type: ResourceType.Vocab, number: n })).data;
+    return new ScriptWorld(rm, parseSelectorNames(await vocab(997)), parseClassTable(await vocab(996)));
+  }
+
+  async script(number: number): Promise<Script> {
+    let s = this.scripts.get(number);
+    if (!s) {
+      const code = (await this.rm.load({ type: ResourceType.Script, number })).data;
+      const heap = (await this.rm.load({ type: ResourceType.Heap, number })).data;
+      s = parseScript(number, code, heap);
+      this.scripts.set(number, s);
+      for (const obj of s.objects) if (obj.isClass) this.classes.set(obj.species, obj);
+    }
+    return s;
+  }
+
+  /** Loads every script that defines a class, so class lookups are synchronous afterwards. */
+  async loadAllClasses(): Promise<void> {
+    const numbers = new Set(this.classScripts.filter((n) => this.rm.has({ type: ResourceType.Script, number: n })));
+    for (const n of numbers) await this.script(n);
+  }
+
+  classObject(species: number): ScriptObject | undefined {
+    return this.classes.get(species);
+  }
+
+  /** For the assembler: names both ways and class layouts. Requires `loadAllClasses()`. */
+  asmContext(): AsmContext {
+    const byName = new Map([...this.classes.values()].map((c) => [c.name, c.species] as const));
+    return {
+      ...this.context(),
+      classSpecies: (name) => byName.get(name),
+      classPropSelectors: (species) => this.classes.get(species)?.propSelectors,
+      classDefaults: (species) => this.classes.get(species)?.properties,
+    };
+  }
+
+  /** Requires `loadAllClasses()` first. */
+  context(): DisasmContext {
+    return {
+      selectorNames: this.selectorNames,
+      kernelNames,
+      className: (species) => this.classes.get(species)?.name,
+      propSelectors: (obj) => (obj.isClass ? obj.propSelectors : this.classes.get(obj.superclass)?.propSelectors),
+    };
+  }
+}

package/packages/sci/src/text/font.d.ts

@@ -0,0 +1,37 @@
+export interface Glyph {
+    width: number;
+    height: number;
+    /** 1 byte per pixel, 1 = ink. */
+    pixels: Uint8Array;
+}
+export interface Font {
+    /** Line height in pixels. */
+    height: number;
+    /** Indexed by character code; missing codes are undefined. */
+    glyphs: (Glyph | undefined)[];
+}
+/**
+ * SCI bitmap font (unchanged since SCI0):
+ *
+ *   +0 u16 first char (unused in practice)
+ *   +2 u16 char count
+ *   +4 u16 line height
+ *   +6 u16 offset per char
+ *
+ * Each glyph: u8 width, u8 height, then rows of 1bpp pixels, MSB first,
+ * each row padded to a whole byte.
+ */
+export declare function parseFont(data: Uint8Array): Font;
+/** A font resource (the inverse of parseFont). Missing glyphs are written as 0×0. */
+export declare function writeFont(font: Font): Uint8Array;
+export declare const textWidth: (font: Font, text: string) => number;
+/** Splits text into lines no wider than `maxWidth`, breaking at spaces and honouring CR/LF. */
+export declare function wrapText(font: Font, text: string, maxWidth: number): string[];
+/** A 1-byte-per-pixel ink mask of rendered text. */
+export interface TextBitmap {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+}
+/** Renders already-wrapped lines, each aligned within the bitmap width. */
+export declare function renderText(font: Font, lines: string[], align?: "left" | "center"): TextBitmap;

package/packages/sci/src/text/font.js

@@ -0,0 +1,103 @@
+/**
+ * SCI bitmap font (unchanged since SCI0):
+ *
+ *   +0 u16 first char (unused in practice)
+ *   +2 u16 char count
+ *   +4 u16 line height
+ *   +6 u16 offset per char
+ *
+ * Each glyph: u8 width, u8 height, then rows of 1bpp pixels, MSB first,
+ * each row padded to a whole byte.
+ */
+export function parseFont(data) {
+    const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const count = v.getUint16(2, true);
+    const height = v.getUint16(4, true);
+    const glyphs = [];
+    for (let c = 0; c < count; c++) {
+        const offset = v.getUint16(6 + c * 2, true);
+        const width = data[offset];
+        const h = data[offset + 1];
+        const stride = Math.ceil(width / 8);
+        const pixels = new Uint8Array(width * h);
+        for (let y = 0; y < h; y++) {
+            for (let x = 0; x < width; x++) {
+                const byte = data[offset + 2 + y * stride + (x >> 3)];
+                pixels[y * width + x] = (byte >> (7 - (x & 7))) & 1;
+            }
+        }
+        glyphs[c] = { width, height: h, pixels };
+    }
+    return { height, glyphs };
+}
+/** A font resource (the inverse of parseFont). Missing glyphs are written as 0×0. */
+export function writeFont(font) {
+    const count = font.glyphs.length;
+    const bodies = Array.from({ length: count }, (_, c) => {
+        const g = font.glyphs[c] ?? { width: 0, height: 0, pixels: new Uint8Array(0) };
+        if (g.width > 255 || g.height > 255)
+            throw new Error(`glyph ${c} is ${g.width}x${g.height}`);
+        const stride = Math.ceil(g.width / 8);
+        const out = new Uint8Array(2 + stride * g.height);
+        out[0] = g.width;
+        out[1] = g.height;
+        for (let y = 0; y < g.height; y++) {
+            for (let x = 0; x < g.width; x++)
+                if (g.pixels[y * g.width + x])
+                    out[2 + y * stride + (x >> 3)] |= 0x80 >> (x & 7);
+        }
+        return out;
+    });
+    const out = new Uint8Array(6 + count * 2 + bodies.reduce((n, b) => n + b.length, 0));
+    const v = new DataView(out.buffer);
+    v.setUint16(2, count, true);
+    v.setUint16(4, font.height, true);
+    let at = 6 + count * 2;
+    bodies.forEach((b, c) => {
+        if (at > 0xffff)
+            throw new Error("font too large: offsets are 16-bit");
+        v.setUint16(6 + c * 2, at, true);
+        out.set(b, at);
+        at += b.length;
+    });
+    return out;
+}
+export const textWidth = (font, text) => [...text].reduce((w, ch) => w + (font.glyphs[ch.charCodeAt(0)]?.width ?? 0), 0);
+/** Splits text into lines no wider than `maxWidth`, breaking at spaces and honouring CR/LF. */
+export function wrapText(font, text, maxWidth) {
+    const lines = [];
+    for (const paragraph of text.split(/\r\n|\r|\n/)) {
+        let line = "";
+        for (const word of paragraph.split(/(?<= )/)) {
+            if (line && textWidth(font, (line + word).trimEnd()) > maxWidth) {
+                lines.push(line.trimEnd());
+                line = "";
+            }
+            line += word;
+        }
+        lines.push(line.trimEnd());
+    }
+    return lines;
+}
+/** Renders already-wrapped lines, each aligned within the bitmap width. */
+export function renderText(font, lines, align = "left") {
+    const width = Math.max(1, ...lines.map((l) => textWidth(font, l)));
+    const height = Math.max(1, lines.length * font.height);
+    const pixels = new Uint8Array(width * height);
+    lines.forEach((line, row) => {
+        let x = align === "center" ? Math.floor((width - textWidth(font, line)) / 2) : 0;
+        for (const ch of line) {
+            const g = font.glyphs[ch.charCodeAt(0)];
+            if (!g)
+                continue;
+            for (let gy = 0; gy < g.height; gy++) {
+                for (let gx = 0; gx < g.width; gx++) {
+                    if (g.pixels[gy * g.width + gx])
+                        pixels[(row * font.height + gy) * width + x + gx] = 1;
+                }
+            }
+            x += g.width;
+        }
+    });
+    return { width, height, pixels };
+}

package/packages/sci/src/text/font.ts

@@ -0,0 +1,125 @@
+export interface Glyph {
+  width: number;
+  height: number;
+  /** 1 byte per pixel, 1 = ink. */
+  pixels: Uint8Array;
+}
+
+export interface Font {
+  /** Line height in pixels. */
+  height: number;
+  /** Indexed by character code; missing codes are undefined. */
+  glyphs: (Glyph | undefined)[];
+}
+
+/**
+ * SCI bitmap font (unchanged since SCI0):
+ *
+ *   +0 u16 first char (unused in practice)
+ *   +2 u16 char count
+ *   +4 u16 line height
+ *   +6 u16 offset per char
+ *
+ * Each glyph: u8 width, u8 height, then rows of 1bpp pixels, MSB first,
+ * each row padded to a whole byte.
+ */
+export function parseFont(data: Uint8Array): Font {
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const count = v.getUint16(2, true);
+  const height = v.getUint16(4, true);
+
+  const glyphs: (Glyph | undefined)[] = [];
+  for (let c = 0; c < count; c++) {
+    const offset = v.getUint16(6 + c * 2, true);
+    const width = data[offset]!;
+    const h = data[offset + 1]!;
+    const stride = Math.ceil(width / 8);
+    const pixels = new Uint8Array(width * h);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < width; x++) {
+        const byte = data[offset + 2 + y * stride + (x >> 3)]!;
+        pixels[y * width + x] = (byte >> (7 - (x & 7))) & 1;
+      }
+    }
+    glyphs[c] = { width, height: h, pixels };
+  }
+  return { height, glyphs };
+}
+
+/** A font resource (the inverse of parseFont). Missing glyphs are written as 0×0. */
+export function writeFont(font: Font): Uint8Array {
+  const count = font.glyphs.length;
+  const bodies = Array.from({ length: count }, (_, c) => {
+    const g = font.glyphs[c] ?? { width: 0, height: 0, pixels: new Uint8Array(0) };
+    if (g.width > 255 || g.height > 255) throw new Error(`glyph ${c} is ${g.width}x${g.height}`);
+    const stride = Math.ceil(g.width / 8);
+    const out = new Uint8Array(2 + stride * g.height);
+    out[0] = g.width;
+    out[1] = g.height;
+    for (let y = 0; y < g.height; y++) {
+      for (let x = 0; x < g.width; x++) if (g.pixels[y * g.width + x]) out[2 + y * stride + (x >> 3)]! |= 0x80 >> (x & 7);
+    }
+    return out;
+  });
+  const out = new Uint8Array(6 + count * 2 + bodies.reduce((n, b) => n + b.length, 0));
+  const v = new DataView(out.buffer);
+  v.setUint16(2, count, true);
+  v.setUint16(4, font.height, true);
+  let at = 6 + count * 2;
+  bodies.forEach((b, c) => {
+    if (at > 0xffff) throw new Error("font too large: offsets are 16-bit");
+    v.setUint16(6 + c * 2, at, true);
+    out.set(b, at);
+    at += b.length;
+  });
+  return out;
+}
+
+export const textWidth = (font: Font, text: string): number =>
+  [...text].reduce((w, ch) => w + (font.glyphs[ch.charCodeAt(0)]?.width ?? 0), 0);
+
+/** Splits text into lines no wider than `maxWidth`, breaking at spaces and honouring CR/LF. */
+export function wrapText(font: Font, text: string, maxWidth: number): string[] {
+  const lines: string[] = [];
+  for (const paragraph of text.split(/\r\n|\r|\n/)) {
+    let line = "";
+    for (const word of paragraph.split(/(?<= )/)) {
+      if (line && textWidth(font, (line + word).trimEnd()) > maxWidth) {
+        lines.push(line.trimEnd());
+        line = "";
+      }
+      line += word;
+    }
+    lines.push(line.trimEnd());
+  }
+  return lines;
+}
+
+/** A 1-byte-per-pixel ink mask of rendered text. */
+export interface TextBitmap {
+  width: number;
+  height: number;
+  pixels: Uint8Array;
+}
+
+/** Renders already-wrapped lines, each aligned within the bitmap width. */
+export function renderText(font: Font, lines: string[], align: "left" | "center" = "left"): TextBitmap {
+  const width = Math.max(1, ...lines.map((l) => textWidth(font, l)));
+  const height = Math.max(1, lines.length * font.height);
+  const pixels = new Uint8Array(width * height);
+
+  lines.forEach((line, row) => {
+    let x = align === "center" ? Math.floor((width - textWidth(font, line)) / 2) : 0;
+    for (const ch of line) {
+      const g = font.glyphs[ch.charCodeAt(0)];
+      if (!g) continue;
+      for (let gy = 0; gy < g.height; gy++) {
+        for (let gx = 0; gx < g.width; gx++) {
+          if (g.pixels[gy * g.width + gx]) pixels[(row * font.height + gy) * width + x + gx] = 1;
+        }
+      }
+      x += g.width;
+    }
+  });
+  return { width, height, pixels };
+}