@a-t-h-i/bot-lobby 0.6.3 → 0.6.5

package/prompts/reviewer.md

@@ -18,6 +18,30 @@ Review requirements, the approved plan, the actual diff, affected files, tests,
 security, accessibility where relevant, error handling, reliability,
 performance where relevant, maintainability, and scope discipline.
 
+## Change provenance
+
+The working tree can hold changes that are not this task's: the user makes
+quick fixes from the lobby while tasks run, other tasks may run beside this
+one, and there may have been uncommitted work before the task started. When
+your context lists who changed each file (bot-lobby's own record of every
+agent's `edit`/`write` calls), judge each change by its source:
+
+- **planned**: this task's workers. Review it against the plan, scope
+  discipline included.
+- **quick fix**: a change the user asked for directly. It is authorised and
+  outside this task's plan, so it is never scope creep or a rogue change, and
+  you never ask for it to be reverted. Mention it only if it breaks this task
+  or its checks, naming the quick fix.
+- **another task** or **pre-existing**: not this task's work. Leave it alone
+  unless it breaks this task.
+- **unattributed**: no agent recorded the edit (the user by hand, a shell
+  command, another tool). Do not call it rogue: list the files in one `info`
+  finding so the Master can ask the user. It fails the gate only when it
+  breaks this task.
+
+A file with several sources holds more than this task's work: judge this task
+only by what its workers were asked to do.
+
 ## You MAY
 
 - read files
@@ -51,6 +75,24 @@ If implementation changes are required, report them to the Master.
 - Always pass a bash `timeout` to test and build commands; never start watch
   mode or servers.
 
+## Verdict
+
+- **PASS** when the acceptance criteria are met and your checks pass. Minor
+  and info findings never block: list them, then PASS. (The engine passes a
+  CHANGES_REQUIRED whose findings are all tagged minor or info.)
+- **CHANGES_REQUIRED** only for a critical or major finding: broken
+  behaviour, a failing check, an unmet acceptance criterion, a security
+  problem. Tag every finding with its severity.
+- **BLOCKED** only when you cannot review at all (it does not build, the
+  checks cannot run).
+- **A re-review verifies; it does not start over.** When your context lists
+  what the previous round asked for, check each item first and say which are
+  addressed. Do not raise the bar between rounds: a new blocking finding must
+  be critical or major.
+- Work committed during the task counts. The diff you are given runs from the
+  commit the task started at, so committed fixes are in it; use `git log` and
+  `git diff` against that commit to look further.
+
 ## Pushback
 
 If the approved requirement or a requested change is itself unsound, add a

package/prompts/worker.md

@@ -43,6 +43,13 @@ Work efficiently: read what you need, make the change, verify, report. If the
 engine asks you to wrap up, stop exploring, leave every file consistent, and
 write your report with anything unfinished under Blockers or Notes.
 
+When your context has a **Time** section, the step has that many minutes. Land
+the most important part first and keep files consistent as you go. When the
+time is up you are told to stop: finish or revert the edit in progress, then
+report with `## Left Off` (what you were doing, what is still to do) and
+`## More Time` (`N minutes — why`), honestly sized. If the user gives you more,
+you carry on from where you stopped.
+
 ## Working alongside other workers (file desk)
 
 When the `claim_file` tool is available, other workers are editing the same

package/src/agents/backend.ts

@@ -4,7 +4,7 @@ export const backendSpec: DomainSpec = {
   domain: "backend",
   promptFile: "backend.md",
   scoutFocus:
-    "API, business logic, data models, persistence, authentication/authorization, integrations, and backend reliability",
+    "server-side code: API, business logic, data models, persistence, authentication/authorization, integrations, and backend reliability",
   boundary:
-    "Stay inside backend code. Do not modify frontend implementation; report frontend requirements to the Master.",
+    "Stay inside server-side code. Do not modify browser code (pages, components, client-side logic or graphics); report frontend requirements to the Master.",
 };

package/src/agents/designer.ts

@@ -4,7 +4,7 @@ export const designerSpec: DomainSpec = {
   domain: "designer",
   promptFile: "designer.md",
   scoutFocus:
-    "UI/UX, frontend implementation, accessibility, responsive behavior, and the existing design language",
+    "UI/UX and everything that runs in the browser (pages, components, client-side logic, canvas and WebGL/three.js graphics), accessibility, responsive behavior, and the existing design language",
   boundary:
-    "Stay inside frontend/UI. Do not modify backend implementation; report backend dependencies to the Master.",
+    "Stay inside the frontend: everything that runs in the browser. Do not modify server-side code; report backend dependencies to the Master.",
 };

package/src/ask/dialog.ts

@@ -0,0 +1,167 @@
+/**
+ * Putting questions to the user. In pi's terminal the questionnaire opens as
+ * an overlay (over the lobby too) with Markdown throughout and each option's
+ * preview beside it. Where pi cannot draw one — RPC mode, which background
+ * sessions and editor hosts run in — the same questions go through pi's own
+ * select and input dialogs, which those hosts do forward.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
+import type { LobbyTheme } from "../lobby/layout.ts";
+import { lobbyTheme } from "../lobby/theme.ts";
+import { initialState, step, type AskKey, type AskState } from "./state.ts";
+import { renderAsk, type AskFrame } from "./view.ts";
+import { loadImages } from "./image.ts";
+import { isAbsolute, resolve } from "node:path";
+import type { AskAnswer, AskQuestion, AskResult } from "./types.ts";
+
+/**
+ * Puts up to `MAX_QUESTIONS` questions to the user and returns what they
+ * chose. `from` names who asks when it is not this session's model (an agent
+ * whose questions the oracle relays).
+ */
+export type Asker = (questions: readonly AskQuestion[], ctx: ExtensionContext, signal?: AbortSignal, from?: string) => Promise<AskResult>;
+
+/** Share of the terminal the overlay may take. */
+const OVERLAY_HEIGHT = 0.9;
+
+/** A key press as the questionnaire reads it; undefined for keys it ignores. */
+export function readKey(data: string): AskKey | undefined {
+  if (matchesKey(data, Key.up)) return { type: "up" };
+  if (matchesKey(data, Key.down)) return { type: "down" };
+  if (matchesKey(data, Key.left) || matchesKey(data, Key.shift("tab"))) return { type: "left" };
+  if (matchesKey(data, Key.right) || matchesKey(data, Key.tab)) return { type: "right" };
+  if (matchesKey(data, Key.enter)) return { type: "enter" };
+  if (matchesKey(data, Key.escape)) return { type: "escape" };
+  if (matchesKey(data, Key.backspace)) return { type: "backspace" };
+  if (data === " ") return { type: "space" };
+  if (/^[1-9]$/.test(data)) return { type: "digit", value: Number(data) };
+  // Typed or pasted text: anything printable (control sequences are dropped).
+  const text = [...data].filter((char) => char >= " " && char !== "\x7f").join("");
+  if (text && !data.startsWith("\x1b")) return { type: "text", value: text };
+  return undefined;
+}
+
+/** The questionnaire as a pi component: keys step its state, each frame draws it. */
+export class AskDialog implements Component {
+  private state: AskState;
+  private readonly tui: TUI;
+  private readonly theme: LobbyTheme;
+  private readonly done: (result: AskResult) => void;
+  private readonly frame: AskFrame;
+
+  constructor(tui: TUI, theme: LobbyTheme, questions: readonly AskQuestion[], done: (result: AskResult) => void, frame: AskFrame = {}) {
+    this.tui = tui;
+    this.theme = theme;
+    this.state = initialState(questions);
+    this.done = done;
+    this.frame = frame;
+  }
+
+  handleInput(data: string): void {
+    const key = readKey(data);
+    if (!key) return;
+    this.state = step(this.state, key);
+    if (this.state.result) this.done(this.state.result);
+    else this.tui.requestRender();
+  }
+
+  /** Put the questions away from outside (the turn was aborted). */
+  cancel(): void {
+    if (!this.state.result) this.handleInput("\x1b");
+  }
+
+  render(width: number): string[] {
+    return renderAsk(this.state, width, Math.max(8, Math.floor(this.tui.terminal.rows * OVERLAY_HEIGHT)), this.theme, this.frame);
+  }
+
+  invalidate(): void {}
+}
+
+/**
+ * The questions in pi's terminal, or through its plain dialogs where it
+ * cannot draw the questionnaire. Without any UI nobody can answer: the
+ * result says the questions were put away.
+ */
+export const askUser: Asker = async (questions, ctx, signal, from) => {
+  if (!ctx.hasUI || questions.length === 0) return { answers: [], cancelled: true };
+  if ((ctx as { mode?: string }).mode === "rpc") return dialogAsker(questions, ctx, signal, from);
+  // Option images are read before the questionnaire opens, so drawing it never waits on the disk.
+  const images = await loadImages(questions.flatMap((question) => question.options.map((option) => (option.image?.trim() ? imagePath(option.image, ctx.cwd) : ""))));
+  const shown = questions.map((question) => ({ ...question, options: question.options.map((option) => (option.image?.trim() ? { ...option, image: imagePath(option.image, ctx.cwd) } : option)) }));
+  let dialog: AskDialog | undefined;
+  const onAbort = () => dialog?.cancel();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    const result = await ctx.ui.custom<AskResult>((tui, theme, _keys, done) => {
+      dialog = new AskDialog(tui, lobbyTheme(theme), shown, done, { ...(from ? { from } : {}), ...(images.size > 0 ? { images } : {}) });
+      if (signal?.aborted) queueMicrotask(onAbort);
+      return dialog;
+    }, { overlay: true, overlayOptions: { width: "90%", maxHeight: "90%", anchor: "center", margin: 1 } });
+    // A host that cannot draw custom components resolves at once with nothing.
+    return result ?? dialogAsker(questions, ctx, signal, from);
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+  }
+};
+
+function imagePath(path: string, cwd: string): string {
+  const trimmed = path.trim();
+  return isAbsolute(trimmed) ? trimmed : resolve(cwd, trimmed);
+}
+
+const TYPE_ANSWER = "Type an answer…";
+const SKIP = "Skip";
+const DONE = "Done";
+/** Longest description or preview folded into a plain dialog's title. */
+const MAX_FOLDED = 600;
+
+/** A question as one plain dialog's title: the question, then each option's description and preview. */
+function dialogTitle(question: AskQuestion, index: number, total: number, from?: string): string {
+  const details = question.options
+    .map((option) => [
+      option.description?.trim() ? `${option.label}: ${option.description.trim()}` : "",
+      option.preview?.trim() ? `--- ${option.label} ---\n${option.preview.trim().slice(0, MAX_FOLDED)}` : "",
+      option.image?.trim() ? `(${option.label}: see the image ${option.image.trim()})` : "",
+    ].filter(Boolean).join("\n"))
+    .filter(Boolean);
+  return [`${from ? `${from} asks · ` : ""}${question.header} · ${index + 1}/${total}`, question.question, ...details].join("\n\n");
+}
+
+/** The same questions through pi's select and input dialogs: pick, type an answer, or skip; esc stops. */
+export const dialogAsker: Asker = async (questions, ctx, _signal, from) => {
+  const answers: AskAnswer[] = [];
+  for (const [index, question] of questions.entries()) {
+    const title = dialogTitle(question, index, questions.length, from);
+    if (question.multiSelect) {
+      const selected: string[] = [];
+      for (;;) {
+        const left = question.options.map((option) => option.label).filter((label) => !selected.includes(label));
+        const choice = await ctx.ui.select(`${title}${selected.length > 0 ? `\n\nPicked: ${selected.join(", ")}` : ""}`, [...left, TYPE_ANSWER, selected.length > 0 ? DONE : SKIP]);
+        if (choice === undefined) return { answers, cancelled: true };
+        if (choice === DONE || choice === SKIP) break;
+        if (choice === TYPE_ANSWER) {
+          const typed = await ctx.ui.input(question.question, "your answer");
+          if (typed === undefined) return { answers, cancelled: true };
+          if (typed.trim()) selected.push(typed.trim());
+          break;
+        }
+        selected.push(choice);
+        if (left.length === 1) break;
+      }
+      if (selected.length > 0) answers.push({ questionIndex: index, question: question.question, kind: "multi", answer: selected.join(", "), selected });
+      continue;
+    }
+    const choice = await ctx.ui.select(title, [...question.options.map((option) => option.label), TYPE_ANSWER, SKIP]);
+    if (choice === undefined) return { answers, cancelled: true };
+    if (choice === SKIP) continue;
+    if (choice === TYPE_ANSWER) {
+      const typed = await ctx.ui.input(question.question, "your answer");
+      if (typed === undefined) return { answers, cancelled: true };
+      if (typed.trim()) answers.push({ questionIndex: index, question: question.question, kind: "custom", answer: typed.trim() });
+      continue;
+    }
+    answers.push({ questionIndex: index, question: question.question, kind: "option", answer: choice });
+  }
+  return { answers, cancelled: false };
+};

package/src/ask/image.ts

@@ -0,0 +1,202 @@
+/**
+ * Images in the questionnaire: a screenshot or rendered mockup an option
+ * carries, drawn in its preview. Terminals that speak the Kitty graphics
+ * protocol (Kitty, Ghostty, WezTerm) get the image itself; everywhere else a
+ * PNG is drawn with coloured half-blocks, which any colour terminal shows and
+ * which sit in a box like text. Other formats there get a line saying what
+ * and where the file is. `BOT_LOBBY_IMAGES=blocks` always draws blocks;
+ * `off` never draws images.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { getCapabilities, getImageDimensions, renderImage, type ImageDimensions } from "@earendil-works/pi-tui";
+import { paint, type LobbyTheme } from "../lobby/layout.ts";
+import { decodePng, type Pixels } from "./png.ts";
+
+/** Larger files are not read. */
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+export type ImageMime = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+
+export interface LoadedImage {
+  path: string;
+  mime: ImageMime;
+  base64: string;
+  dimensions: ImageDimensions;
+  /** Decoded on first use, for the half-block drawing (PNG only). */
+  pixels?: Pixels | string;
+  /** Kitty reuses one id per image so a redraw replaces it. */
+  kittyId?: number;
+  /** Half-block drawings already made, by size: every key press redraws the questionnaire. */
+  blocks?: Map<string, string[]>;
+}
+
+/** An image option whose file could not be read, and why. */
+export interface MissingImage {
+  path: string;
+  error: string;
+}
+
+export type ImagePreview = LoadedImage | MissingImage;
+
+const EXTENSIONS = /\.(png|jpe?g|gif|webp)$/i;
+
+export function isImagePath(path: string): boolean {
+  return EXTENSIONS.test(path.trim());
+}
+
+function sniff(bytes: Uint8Array): ImageMime | undefined {
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return "image/gif";
+  if (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 && bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) return "image/webp";
+  return undefined;
+}
+
+/** Read an option's image file: a PNG, JPEG, GIF or WebP of at most 10 MB. */
+export async function loadImage(path: string): Promise<ImagePreview> {
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return { path, error: "not a file" };
+    if (info.size > MAX_IMAGE_BYTES) return { path, error: `too large to show (${Math.round(info.size / 1024 / 1024)} MB)` };
+    const bytes = new Uint8Array(await readFile(path));
+    const mime = sniff(bytes);
+    if (!mime) return { path, error: "not a PNG, JPEG, GIF or WebP image" };
+    const base64 = Buffer.from(bytes).toString("base64");
+    const dimensions = getImageDimensions(base64, mime) ?? { widthPx: 800, heightPx: 600 };
+    return { path, mime, base64, dimensions };
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    return { path, error: code === "ENOENT" ? "no such file" : error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Every option image the questions carry, read once before the questionnaire opens. */
+export async function loadImages(paths: readonly string[]): Promise<Map<string, ImagePreview>> {
+  const unique = [...new Set(paths.filter(Boolean))];
+  const loaded = await Promise.all(unique.map((path) => loadImage(path)));
+  return new Map(unique.map((path, index) => [path, loaded[index]!]));
+}
+
+type Mode = "native" | "blocks" | "off";
+
+function mode(): Mode {
+  const chosen = (process.env.BOT_LOBBY_IMAGES ?? "").trim().toLowerCase();
+  if (chosen === "off" || chosen === "blocks") return chosen;
+  return getCapabilities().images === "kitty" ? "native" : "blocks";
+}
+
+function pixelsOf(image: LoadedImage): Pixels | string {
+  if (image.pixels === undefined) {
+    if (image.mime !== "image/png") image.pixels = "only PNG images can be drawn in this terminal";
+    else {
+      try {
+        image.pixels = decodePng(Buffer.from(image.base64, "base64"));
+      } catch (error) {
+        image.pixels = error instanceof Error ? error.message : String(error);
+      }
+    }
+  }
+  return image.pixels;
+}
+
+/** The cell grid an image fits in: at most `columns` × `rows`, its aspect kept (a cell is about twice as tall as wide). */
+function fitCells(dimensions: ImageDimensions, columns: number, rows: number): { columns: number; rows: number } {
+  const aspect = dimensions.heightPx / Math.max(1, dimensions.widthPx);
+  let width = Math.max(1, columns);
+  let height = Math.max(1, Math.round((width * aspect) / 2));
+  if (height > rows) {
+    height = Math.max(1, rows);
+    width = Math.max(1, Math.min(columns, Math.round((height * 2) / aspect)));
+  }
+  return { columns: width, rows: height };
+}
+
+/** Average the pixels of one block of the image, over the box's dark background where they are see-through. */
+function averageColor(pixels: Pixels, x0: number, y0: number, x1: number, y1: number): [number, number, number] {
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  const backdrop = 24;
+  for (let y = y0; y < Math.max(y1, y0 + 1); y += 1) {
+    for (let x = x0; x < Math.max(x1, x0 + 1); x += 1) {
+      const at = (Math.min(y, pixels.height - 1) * pixels.width + Math.min(x, pixels.width - 1)) * 4;
+      const alpha = pixels.data[at + 3]! / 255;
+      r += pixels.data[at]! * alpha + backdrop * (1 - alpha);
+      g += pixels.data[at + 1]! * alpha + backdrop * (1 - alpha);
+      b += pixels.data[at + 2]! * alpha + backdrop * (1 - alpha);
+      count += 1;
+    }
+  }
+  return [Math.round(r / count), Math.round(g / count), Math.round(b / count)];
+}
+
+/** Colour escape for a cell's foreground or background: 24-bit where the terminal has it, else the nearest of the 256. */
+function colour(rgb: [number, number, number], background: boolean, trueColor: boolean): string {
+  const [r, g, b] = rgb;
+  if (trueColor) return `\x1b[${background ? 48 : 38};2;${r};${g};${b}m`;
+  const level = (value: number) => (value < 48 ? 0 : value < 115 ? 1 : Math.min(5, Math.floor((value - 35) / 40)));
+  return `\x1b[${background ? 48 : 38};5;${16 + 36 * level(r) + 6 * level(g) + level(b)}m`;
+}
+
+/** An image as rows of half-blocks: each cell's upper half is the foreground colour, its lower half the background. */
+export function halfBlocks(pixels: Pixels, columns: number, rows: number, trueColor = true): string[] {
+  const cells = fitCells({ widthPx: pixels.width, heightPx: pixels.height }, columns, rows);
+  const lines: string[] = [];
+  const stepX = pixels.width / cells.columns;
+  const stepY = pixels.height / (cells.rows * 2);
+  for (let row = 0; row < cells.rows; row += 1) {
+    let line = "";
+    for (let column = 0; column < cells.columns; column += 1) {
+      const x0 = Math.floor(column * stepX);
+      const x1 = Math.floor((column + 1) * stepX);
+      const top = averageColor(pixels, x0, Math.floor(row * 2 * stepY), x1, Math.floor((row * 2 + 1) * stepY));
+      const bottom = averageColor(pixels, x0, Math.floor((row * 2 + 1) * stepY), x1, Math.floor((row * 2 + 2) * stepY));
+      line += `${colour(top, false, trueColor)}${colour(bottom, true, trueColor)}▀`;
+    }
+    lines.push(`${line}\x1b[0m`);
+  }
+  return lines;
+}
+
+function describe(preview: ImagePreview): string {
+  if ("error" in preview) return `${basename(preview.path)}: ${preview.error}`;
+  return `${basename(preview.path)} · ${preview.dimensions.widthPx}×${preview.dimensions.heightPx} ${preview.mime.slice(6).toUpperCase()}`;
+}
+
+/**
+ * An option's image drawn in at most `columns` × `rows` cells, with a caption
+ * line under it naming the file; or, where it cannot be drawn, lines saying
+ * what and where it is.
+ */
+export function imageLines(preview: ImagePreview, columns: number, rows: number, theme?: LobbyTheme): string[] {
+  const caption = paint(theme, "dim", describe(preview));
+  if ("error" in preview) return [paint(theme, "warning", `Image not shown: ${describe(preview)}`)];
+  const room = Math.max(1, rows - 1);
+  const how = mode();
+  if (how === "native") {
+    const size = fitCells(preview.dimensions, columns, room);
+    const drawn = renderImage(preview.base64, preview.dimensions, { maxWidthCells: size.columns, maxHeightCells: size.rows, moveCursor: false, ...(preview.kittyId ? { imageId: preview.kittyId } : {}) });
+    if (drawn) {
+      if (drawn.imageId) preview.kittyId = drawn.imageId;
+      return [drawn.sequence, ...Array.from({ length: Math.max(0, drawn.rows - 1) }, () => ""), caption];
+    }
+  }
+  if (how !== "off") {
+    const pixels = pixelsOf(preview);
+    if (typeof pixels !== "string") {
+      const trueColor = getCapabilities().trueColor !== false;
+      const key = `${columns}x${room}:${trueColor}`;
+      preview.blocks ??= new Map();
+      let drawn = preview.blocks.get(key);
+      if (!drawn) {
+        drawn = halfBlocks(pixels, columns, room, trueColor);
+        preview.blocks.set(key, drawn);
+      }
+      return [...drawn, caption];
+    }
+    return [paint(theme, "muted", `${describe(preview)}: ${pixels}; open ${preview.path} to see it`)];
+  }
+  return [paint(theme, "muted", `${describe(preview)}: open ${preview.path} to see it`)];
+}

package/src/ask/png.ts

@@ -0,0 +1,179 @@
+/**
+ * A small PNG decoder: every colour type and bit depth, interlaced or not,
+ * into 8-bit RGBA. Enough to draw a screenshot as coloured blocks in any
+ * terminal; no dependency (zlib is Node's).
+ */
+import { inflateSync } from "node:zlib";
+
+export interface Pixels {
+  width: number;
+  height: number;
+  /** RGBA, 4 bytes per pixel, row by row. */
+  data: Uint8Array;
+}
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Larger images are not decoded (a screenshot is far smaller). */
+const MAX_PIXELS = 50_000_000;
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+/** Adam7: each pass's first column and row, and the steps between them. */
+const ADAM7 = [
+  [0, 0, 8, 8],
+  [4, 0, 8, 8],
+  [0, 4, 4, 8],
+  [2, 0, 4, 4],
+  [0, 2, 2, 4],
+  [1, 0, 2, 2],
+  [0, 1, 1, 2],
+] as const;
+
+export function isPng(bytes: Uint8Array): boolean {
+  return bytes.length >= 8 && SIGNATURE.every((value, index) => bytes[index] === value);
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+/** Undo the per-row filters of one (sub)image in place, returning its raw rows. */
+function unfilter(source: Uint8Array, offset: number, rowBytes: number, rows: number, bpp: number): { rows: Uint8Array[]; next: number } {
+  const out: Uint8Array[] = [];
+  let previous = new Uint8Array(rowBytes);
+  let at = offset;
+  for (let row = 0; row < rows; row += 1) {
+    if (at + 1 + rowBytes > source.length) throw new Error("the PNG image data is cut short");
+    const filter = source[at]!;
+    const line = source.slice(at + 1, at + 1 + rowBytes);
+    at += 1 + rowBytes;
+    for (let index = 0; index < rowBytes; index += 1) {
+      const left = index >= bpp ? line[index - bpp]! : 0;
+      const up = previous[index]!;
+      const corner = index >= bpp ? previous[index - bpp]! : 0;
+      switch (filter) {
+        case 0:
+          break;
+        case 1:
+          line[index] = (line[index]! + left) & 255;
+          break;
+        case 2:
+          line[index] = (line[index]! + up) & 255;
+          break;
+        case 3:
+          line[index] = (line[index]! + ((left + up) >> 1)) & 255;
+          break;
+        case 4:
+          line[index] = (line[index]! + paeth(left, up, corner)) & 255;
+          break;
+        default:
+          throw new Error(`unknown PNG filter ${filter}`);
+      }
+    }
+    out.push(line);
+    previous = line;
+  }
+  return { rows: out, next: at };
+}
+
+/** Decode a PNG into RGBA pixels; throws with a reason when it cannot. */
+export function decodePng(bytes: Uint8Array): Pixels {
+  if (!isPng(bytes)) throw new Error("not a PNG file");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let width = 0;
+  let height = 0;
+  let depth = 8;
+  let type = 6;
+  let interlace = 0;
+  let palette: Uint8Array | undefined;
+  let alphas: Uint8Array | undefined;
+  let transparent: number[] | undefined;
+  const data: Uint8Array[] = [];
+  for (let at = 8; at + 8 <= bytes.length; ) {
+    const length = view.getUint32(at);
+    const name = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+    const body = bytes.subarray(at + 8, at + 8 + length);
+    at += 12 + length;
+    if (name === "IHDR") {
+      const header = new DataView(body.buffer, body.byteOffset, body.byteLength);
+      width = header.getUint32(0);
+      height = header.getUint32(4);
+      depth = body[8]!;
+      type = body[9]!;
+      interlace = body[12]!;
+    } else if (name === "PLTE") palette = body;
+    else if (name === "tRNS") {
+      if (type === 3) alphas = body;
+      else if (type === 0 && body.length >= 2) transparent = [(body[0]! << 8) | body[1]!];
+      else if (type === 2 && body.length >= 6) transparent = [(body[0]! << 8) | body[1]!, (body[2]! << 8) | body[3]!, (body[4]! << 8) | body[5]!];
+    } else if (name === "IDAT") data.push(body);
+    else if (name === "IEND") break;
+  }
+  const channels = CHANNELS[type];
+  if (!width || !height || channels === undefined) throw new Error("the PNG header is missing or unsupported");
+  if (width * height > MAX_PIXELS) throw new Error(`the PNG is too large to draw (${width}×${height})`);
+  if (type === 3 && !palette) throw new Error("the PNG palette is missing");
+  const joined = new Uint8Array(data.reduce((total, chunk) => total + chunk.length, 0));
+  let offset = 0;
+  for (const chunk of data) {
+    joined.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const raw = inflateSync(joined);
+  const bitsPerPixel = channels * depth;
+  const bpp = Math.max(1, bitsPerPixel >> 3);
+  const out = new Uint8Array(width * height * 4);
+  const max = (1 << depth) - 1;
+
+  const sample = (row: Uint8Array, index: number): number => {
+    if (depth === 8) return row[index]!;
+    if (depth === 16) return (row[index * 2]! << 8) | row[index * 2 + 1]!;
+    const bit = index * depth;
+    return (row[bit >> 3]! >> (8 - depth - (bit & 7))) & max;
+  };
+  const to8 = (value: number) => (depth === 16 ? value >> 8 : depth === 8 ? value : Math.round((value * 255) / max));
+
+  const put = (rowData: Uint8Array, column: number, x: number, y: number) => {
+    const target = (y * width + x) * 4;
+    const base = column * channels;
+    if (type === 3) {
+      const index = sample(rowData, column);
+      out[target] = palette![index * 3] ?? 0;
+      out[target + 1] = palette![index * 3 + 1] ?? 0;
+      out[target + 2] = palette![index * 3 + 2] ?? 0;
+      out[target + 3] = alphas?.[index] ?? 255;
+      return;
+    }
+    const values = Array.from({ length: channels }, (_, channel) => sample(rowData, base + channel));
+    const gray = type === 0 || type === 4;
+    const [r, g, b] = gray ? [values[0]!, values[0]!, values[0]!] : [values[0]!, values[1]!, values[2]!];
+    const alpha = type === 4 ? to8(values[1]!) : type === 6 ? to8(values[3]!) : 255;
+    const clear = transparent && (gray ? values[0] === transparent[0] : values[0] === transparent[0] && values[1] === transparent[1] && values[2] === transparent[2]);
+    out[target] = to8(r);
+    out[target + 1] = to8(g);
+    out[target + 2] = to8(b);
+    out[target + 3] = clear ? 0 : alpha;
+  };
+
+  if (interlace === 0) {
+    const { rows } = unfilter(raw, 0, Math.ceil((width * bitsPerPixel) / 8), height, bpp);
+    rows.forEach((row, y) => {
+      for (let x = 0; x < width; x += 1) put(row, x, x, y);
+    });
+  } else {
+    let at = 0;
+    for (const [x0, y0, dx, dy] of ADAM7) {
+      const passWidth = Math.ceil((width - x0) / dx);
+      const passHeight = Math.ceil((height - y0) / dy);
+      if (passWidth <= 0 || passHeight <= 0) continue;
+      const pass = unfilter(raw, at, Math.ceil((passWidth * bitsPerPixel) / 8), passHeight, bpp);
+      at = pass.next;
+      pass.rows.forEach((row, py) => {
+        for (let px = 0; px < passWidth; px += 1) put(row, px, x0 + px * dx, y0 + py * dy);
+      });
+    }
+  }
+  return { width, height, data: out };
+}