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

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 };
+}

package/src/ask/relay.ts

@@ -0,0 +1,89 @@
+/**
+ * Asking the user from a subagent. A subagent runs as `pi --mode rpc` with no
+ * terminal of its own, so its `ask_user_question` goes out as an RPC editor
+ * dialog carrying the questions (marked with `RELAY_TITLE`); the runner in the
+ * master process answers it by putting the questionnaire to the user and
+ * sends the answers back the same way. Only runs the master lets ask (the
+ * designer's) get the tool: it sets `ASK_ENV` for them.
+ */
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Asker } from "./dialog.ts";
+import { MAX_OPTIONS, MAX_QUESTIONS, type AskQuestion, type AskResult } from "./types.ts";
+
+/** Env flag the master sets for a subagent that may ask the user. */
+export const ASK_ENV = "BOT_LOBBY_ASK";
+/** Title of the RPC dialog that carries a relayed questionnaire. */
+export const RELAY_TITLE = "bot-lobby:ask_user_question";
+
+export function relayEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[ASK_ENV] === "1";
+}
+
+/** Where an agent saves the images it shows the user for a task: outside the repository, so they are never part of its change. */
+export function previewDir(taskId: string): string {
+  return join(tmpdir(), "bot-lobby-previews", taskId.replace(/[^\w.-]/g, "_"));
+}
+
+/** Image paths made absolute, so the master finds them whatever its cwd. */
+function withAbsoluteImages(questions: readonly AskQuestion[], cwd: string): AskQuestion[] {
+  return questions.map((question) => ({
+    ...question,
+    options: question.options.map((option) => (option.image && !isAbsolute(option.image) ? { ...option, image: resolve(cwd, option.image) } : option)),
+  }));
+}
+
+/** The answers the master sent back, or undefined when they do not read as answers. */
+export function readRelayAnswer(value: string | undefined): AskResult | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(value) as Partial<AskResult>;
+    if (!Array.isArray(parsed.answers) || typeof parsed.cancelled !== "boolean") return undefined;
+    return { answers: parsed.answers, cancelled: parsed.cancelled, ...(typeof parsed.globalNote === "string" ? { globalNote: parsed.globalNote } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+const text = (value: unknown): value is string => typeof value === "string";
+
+/** One relayed question as the questionnaire can show it, or undefined when it is not one. */
+function asQuestion(value: unknown): AskQuestion | undefined {
+  const raw = value as Partial<AskQuestion> | null;
+  if (!raw || !text(raw.question) || !text(raw.header) || !Array.isArray(raw.options)) return undefined;
+  const options = raw.options
+    .filter((option) => option && text(option.label))
+    .slice(0, MAX_OPTIONS)
+    .map((option) => ({
+      label: option.label,
+      ...(text(option.description) ? { description: option.description } : {}),
+      ...(text(option.preview) ? { preview: option.preview } : {}),
+      ...(text(option.image) ? { image: option.image } : {}),
+    }));
+  if (options.length === 0) return undefined;
+  return { question: raw.question, header: raw.header, options, ...(raw.multiSelect === true ? { multiSelect: true } : {}) };
+}
+
+/**
+ * The questions a relayed dialog carries, or undefined when it is not one.
+ * The master takes only what the questionnaire can show from them: the
+ * subagent checked them, but its process is not trusted to have.
+ */
+export function readRelayRequest(title: string | undefined, prefill: string | undefined): AskQuestion[] | undefined {
+  if (title !== RELAY_TITLE || !prefill) return undefined;
+  try {
+    const parsed = JSON.parse(prefill) as { questions?: unknown };
+    if (!Array.isArray(parsed.questions)) return undefined;
+    const questions = parsed.questions.slice(0, MAX_QUESTIONS).map(asQuestion);
+    return questions.length > 0 && questions.every(Boolean) ? (questions as AskQuestion[]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Inside a subagent: the questions go to the master as an RPC dialog, and its answers come back. */
+export const relayAsker: Asker = async (questions, ctx: ExtensionContext) => {
+  const value = await ctx.ui.editor(RELAY_TITLE, JSON.stringify({ questions: withAbsoluteImages(questions, ctx.cwd) }));
+  return readRelayAnswer(value) ?? { answers: [], cancelled: true };
+};

package/src/ask/state.ts

@@ -0,0 +1,160 @@
+/**
+ * The questionnaire as state and keys, with no terminal in sight: each key
+ * press is one pure step, so every path (pick, toggle, type your own answer,
+ * move between questions, submit, cancel) is tested directly.
+ *
+ * Every question lists its options, then a row for the user's own answer.
+ * Enter on an option answers a single-choice question and moves on; space
+ * toggles options of a multi-choice one and enter moves on. Answering the
+ * last question submits; ←/→ move between questions first. Esc stops typing,
+ * or puts the questions away.
+ */
+import type { AskAnswer, AskQuestion, AskResult } from "./types.ts";
+
+export type AskKey =
+  | { type: "up" }
+  | { type: "down" }
+  | { type: "left" }
+  | { type: "right" }
+  | { type: "enter" }
+  | { type: "space" }
+  | { type: "escape" }
+  | { type: "backspace" }
+  /** 1-9: pick (or toggle) that option. */
+  | { type: "digit"; value: number }
+  /** Typed or pasted text, only used while writing an answer. */
+  | { type: "text"; value: string };
+
+export interface AskState {
+  questions: readonly AskQuestion[];
+  /** The question in view. */
+  tab: number;
+  /** The focused row of each question: an option index, or `options.length` for the own-answer row. */
+  cursor: number[];
+  /** Options picked in each question (one for a single-choice question). */
+  picked: number[][];
+  /** The user's own answer to each question, when they wrote one. */
+  typed: Array<string | undefined>;
+  /** Writing the own answer of the question in view. */
+  editing: boolean;
+  draft: string;
+  /** Set once the user submits or puts the questions away. */
+  result?: AskResult;
+}
+
+export function initialState(questions: readonly AskQuestion[]): AskState {
+  return {
+    questions,
+    tab: 0,
+    cursor: questions.map(() => 0),
+    picked: questions.map(() => []),
+    typed: questions.map(() => undefined),
+    editing: false,
+    draft: "",
+  };
+}
+
+/** Whether a question has an answer yet. */
+export function isAnswered(state: AskState, index: number): boolean {
+  return (state.picked[index]?.length ?? 0) > 0 || Boolean(state.typed[index]?.trim());
+}
+
+/** The answers given, in the order asked; unanswered questions are left out. */
+export function answersOf(state: AskState): AskAnswer[] {
+  const answers: AskAnswer[] = [];
+  state.questions.forEach((question, index) => {
+    const picked = (state.picked[index] ?? []).map((option) => question.options[option]!.label);
+    const own = state.typed[index]?.trim();
+    if (question.multiSelect) {
+      const selected = own ? [...picked, own] : picked;
+      if (selected.length > 0) answers.push({ questionIndex: index, question: question.question, kind: "multi", answer: selected.join(", "), selected });
+    } else if (own) answers.push({ questionIndex: index, question: question.question, kind: "custom", answer: own });
+    else if (picked[0]) answers.push({ questionIndex: index, question: question.question, kind: "option", answer: picked[0] });
+  });
+  return answers;
+}
+
+function set<T>(list: readonly T[], index: number, value: T): T[] {
+  const next = [...list];
+  next[index] = value;
+  return next;
+}
+
+/** The next question, or the submitted result after the last one. */
+function advance(state: AskState): AskState {
+  if (state.tab < state.questions.length - 1) return { ...state, tab: state.tab + 1, editing: false, draft: "" };
+  return { ...state, editing: false, draft: "", result: { answers: answersOf(state), cancelled: false } };
+}
+
+function choose(state: AskState, option: number): AskState {
+  const question = state.questions[state.tab]!;
+  if (option < 0 || option >= question.options.length) return state;
+  if (question.multiSelect) {
+    const picked = state.picked[state.tab] ?? [];
+    const next = picked.includes(option) ? picked.filter((entry) => entry !== option) : [...picked, option].sort((a, b) => a - b);
+    return { ...state, cursor: set(state.cursor, state.tab, option), picked: set(state.picked, state.tab, next) };
+  }
+  // One answer to a single-choice question: picking an option replaces any words of the user's own.
+  return advance({ ...state, cursor: set(state.cursor, state.tab, option), picked: set(state.picked, state.tab, [option]), typed: set(state.typed, state.tab, undefined) });
+}
+
+function typing(state: AskState, key: AskKey): AskState {
+  switch (key.type) {
+    case "text":
+      return { ...state, draft: state.draft + key.value.replace(/[\r\n\t]+/g, " ") };
+    case "space":
+      return { ...state, draft: `${state.draft} ` };
+    case "digit":
+      return { ...state, draft: state.draft + String(key.value) };
+    case "backspace":
+      return { ...state, draft: [...state.draft].slice(0, -1).join("") };
+    case "escape":
+      return { ...state, editing: false, draft: "" };
+    case "enter": {
+      const own = state.draft.trim();
+      const question = state.questions[state.tab]!;
+      const typed = set(state.typed, state.tab, own || undefined);
+      // Your own words answer a single-choice question instead of a picked option.
+      const picked = own && !question.multiSelect ? set(state.picked, state.tab, []) : state.picked;
+      const next = { ...state, typed, picked, editing: false, draft: "" };
+      return own ? advance(next) : next;
+    }
+    default:
+      return state;
+  }
+}
+
+/** One key press. */
+export function step(state: AskState, key: AskKey): AskState {
+  if (state.result) return state;
+  if (state.editing) return typing(state, key);
+  const question = state.questions[state.tab];
+  if (!question) return { ...state, result: { answers: [], cancelled: false } };
+  const rows = question.options.length + 1;
+  const cursor = state.cursor[state.tab] ?? 0;
+  switch (key.type) {
+    case "up":
+      return { ...state, cursor: set(state.cursor, state.tab, (cursor - 1 + rows) % rows) };
+    case "down":
+      return { ...state, cursor: set(state.cursor, state.tab, (cursor + 1) % rows) };
+    case "left":
+      return state.tab > 0 ? { ...state, tab: state.tab - 1 } : state;
+    case "right":
+      return state.tab < state.questions.length - 1 ? { ...state, tab: state.tab + 1 } : state;
+    case "digit":
+      return choose(state, key.value - 1);
+    case "space":
+      return cursor < question.options.length && question.multiSelect ? choose(state, cursor) : state;
+    case "enter": {
+      if (cursor === question.options.length) return { ...state, editing: true, draft: state.typed[state.tab] ?? "" };
+      if (!question.multiSelect) return choose(state, cursor);
+      // A multi-choice question moves on with what is picked; with nothing picked, enter picks the focused option.
+      if (!isAnswered(state, state.tab)) return advance(choose(state, cursor));
+      return advance(state);
+    }
+    case "escape":
+      return { ...state, result: { answers: answersOf(state), cancelled: true } };
+    default:
+      return state;
+  }
+}