rovecode 0.3.2

package/src/sextant/frame.ts

@@ -0,0 +1,101 @@
+/** Sextant headless frame (port #41): paint every panel onto a ScreenLike and dump it as text — the
+ *  deterministic golden-test seam (DumpFrame). Ported from the user's sextant v0.4.0 app.js:223-242
+ *  (render(): layout → drawFrame → staggered panel reveal → toasts) and tools/snap.js (headless
+ *  dumps). Layout and the panel painters arrive as dependencies: #40's layout.ts and #42/#45's
+ *  code/messages/pet painters plug in here; until they do, `layoutFallback` (the same breakpoint
+ *  math) and empty titled boxes keep the frame renderable. No timers, no clocks — `now` is a parameter. */
+
+import { GridScreen } from "./grid.ts";
+import { drawFiles, drawFrame, drawToasts } from "./draw-frame.ts";
+import { drawPlan, drawUsage } from "./draw-plan.ts";
+import { panel } from "./layout.ts";
+import { pruneToasts } from "./model.ts";
+import type { DumpFrame, Layout, LayoutOptions, Rect, ScreenLike, SextantState, Theme } from "./types.ts";
+import { mainPage } from "./draw-tabs.ts";
+
+export type Painter = (scr: ScreenLike, rect: Rect, s: SextantState, theme: Theme, now: number) => void;
+export interface Painters { frame: Painter; files: Painter; code: Painter; messages: Painter; plan: Painter; usage: Painter; pet: Painter }
+export type LayoutFn = (w: number, h: number, opts: LayoutOptions) => Layout;
+export interface FrameDeps {
+  /** #40 layout(); layoutFallback when absent */
+  layout?: LayoutFn;
+  /** overrides per panel; a missing painter draws an empty titled box */
+  painters?: Partial<Painters>;
+  layoutOpts?: LayoutOptions;
+}
+
+/** boot reveal (app.js render()): panels appear in 90 ms steps after bootAt */
+export const REVEAL_STEP_MS = 90;
+
+const placeholder = (title: string): Painter => (scr, rect, _s, theme) => { panel(scr, rect, title, false, [], theme); };
+export const defaultPainters: Painters = {
+  frame: (scr, rect, s, theme, now) => drawFrame(scr, { frame: rect }, s, theme, now),
+  files: drawFiles,
+  code: placeholder("code"),
+  messages: placeholder("messages"),
+  plan: drawPlan,
+  usage: drawUsage,
+  pet: placeholder("rovecode"),
+};
+
+/** app.js layout(): files column at w ≥ 140 (30 wide at ≥ 150, else 26); right column (plan + usage)
+ *  at w ≥ 110 (34 / 28); messages = max(8, round(contentH · 0.34)); usage 5 rows; pet 14 rows when
+ *  contentH ≥ 36 — under files when present, else carved out of plan. */
+export function layoutFallback(W: number, H: number, opts: LayoutOptions): Layout {
+  const x0 = 2, x1 = W - 4, y0 = 1, y1 = H - 2;
+  const showFiles = W >= 140, showRight = W >= 110;
+  const filesW = showFiles ? (W >= 150 ? 30 : 26) : 0;
+  const rightW = showRight ? (W >= 150 ? 34 : 28) : 0;
+  const contentH = y1 - y0 + 1;
+  const files: Rect | null = showFiles ? { x: x0, y: y0, w: filesW, h: contentH } : null;
+  const rightX = x1 - rightW + 1;
+  const cx = x0 + (showFiles ? filesW + 1 : 0);
+  const cw = (showRight ? rightX - 1 : x1 + 1) - cx;
+  const msgH = Math.max(8, Math.round(contentH * 0.34));
+  const code: Rect = { x: cx, y: y0, w: cw, h: contentH - msgH };
+  const messages: Rect = { x: cx, y: y0 + code.h, w: cw, h: msgH };
+  let plan: Rect | null = null, usage: Rect | null = null, pet: Rect | null = null;
+  if (showRight) {
+    const usageH = 5;
+    plan = { x: rightX, y: y0, w: rightW, h: contentH - usageH };
+    usage = { x: rightX, y: y0 + plan.h, w: rightW, h: usageH };
+  }
+  const petH = opts.pet && contentH >= 36 ? 14 : 0;
+  if (petH && files) { files.h = contentH - petH; pet = { x: x0, y: y0 + files.h, w: filesW, h: petH }; }
+  else if (petH && plan) { plan.h -= petH; pet = { x: rightX, y: y0 + plan.h, w: rightW, h: petH }; }
+  return { w: W, h: H, frame: { x: 0, y: 0, w: W - 1, h: H }, files, code, messages, plan, usage, pet };
+}
+
+/** Paint one frame onto `scr` (the real Screen or a GridScreen); returns the layout used. */
+export function renderFrame(scr: ScreenLike, s: SextantState, theme: Theme, now: number, deps: FrameDeps = {}): Layout {
+  const P: Painters = { ...defaultPainters };
+  for (const k of Object.keys(P) as (keyof Painters)[]) { const p = deps.painters?.[k]; if (p) P[k] = p; }
+  const L = (deps.layout ?? layoutFallback)(scr.w, scr.h, deps.layoutOpts ?? { pet: true });
+  pruneToasts(s, now);
+  const age = now - s.bootAt;
+  P.frame(scr, L.frame, s, theme, now);
+  if (L.files && age >= 0) P.files(scr, L.files, s, theme, now);
+  // paging (draw-tabs.ts): on a narrow terminal the main slot shows the panel `s.page` names when
+  // the layout hid it; the tab strip itself is painted by the frame loop after the panels
+  const main = mainPage(L, s);
+  if (age >= REVEAL_STEP_MS) {
+    if (main === "files") P.files(scr, L.code, s, theme, now);
+    else if (main === "plan") P.plan(scr, L.code, s, theme, now);
+    else P.code(scr, L.code, s, theme, now);
+  }
+  if (age >= REVEAL_STEP_MS * 2) P.messages(scr, L.messages, s, theme, now);
+  if (L.plan && age >= REVEAL_STEP_MS * 3) P.plan(scr, L.plan, s, theme, now);
+  if (L.usage && age >= REVEAL_STEP_MS * 4) P.usage(scr, L.usage, s, theme, now);
+  if (L.pet && age >= REVEAL_STEP_MS * 5) P.pet(scr, L.pet, s, theme, now);
+  drawToasts(scr, s, theme, now);
+  return L;
+}
+
+/** Headless text frame at a fixed clock — identical input, identical output; creates no timers. */
+export function dumpFrame(s: SextantState, cols: number, rows: number, now: number, theme: Theme, deps: FrameDeps = {}): string {
+  const scr = new GridScreen(cols, rows, theme.bg);
+  renderFrame(scr, s, theme, now, deps);
+  return scr.toText();
+}
+/** compile-time proof that dumpFrame satisfies the contract seam */
+export const dumpFrameSeam: DumpFrame = dumpFrame;

package/src/sextant/git-status.ts

@@ -0,0 +1,197 @@
+/** Sextant git status (port #41): the ONLY I/O in the sextant model — branch, porcelain statuses
+ *  (M/A/D per cwd-relative posix path) and HEAD file content for the diff view. Replaces the user's
+ *  sextant v0.4.0 mock `fileStatus` (app.js:133) with real `git status --porcelain=v1 -z`. Every call
+ *  returns null (never throws) when git is missing, times out or the cwd is not a repo; the spawn is
+ *  the coding/repomap-files.ts:38-47 spawnSync idiom (5 s timeout, windowsHide). The renderer (#44)
+ *  uses the `…Async` twins — same contract over child_process.spawn — so a 200 ms `git status` on a
+ *  large repo runs beside the frame loop instead of freezing it; the sync forms stay for the
+ *  synchronous callers and as the parity oracle. */
+
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import type { FileStatus } from "./types.ts";
+
+export interface GitResult { status: number | null; stdout: string }
+/** `git -C <cwd> <args…>`; null when git cannot run at all (the injectable seam for tests) */
+export type GitRunner = (args: readonly string[], cwd: string) => GitResult | null;
+/** the async twin: resolves (never rejects) with the same result, off the caller's stack */
+/** `signal` (optional): abort kills the child and the promise settles null only once the process is
+ *  GONE (its `close`), so a caller awaiting it can safely remove the cwd afterwards — on Windows a live
+ *  `git status` holds the directory, and that was the tui-sextant "flake" (EBUSY at rmSync). */
+export type GitRunnerAsync = (args: readonly string[], cwd: string, signal?: AbortSignal) => Promise<GitResult | null>;
+
+const TIMEOUT_MS = 5000;
+const MAX_BUFFER = 64 * 1024 * 1024;
+const PORCELAIN_ARGS: readonly string[] = ["status", "--porcelain=v1", "-z", "--untracked-files=all"];
+
+export const spawnGit: GitRunner = (args, cwd) => {
+  try {
+    const res = spawnSync("git", ["-C", cwd, ...args], { timeout: TIMEOUT_MS, maxBuffer: MAX_BUFFER, encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+    if (res.error || typeof res.stdout !== "string") return null;
+    return { status: res.status, stdout: res.stdout };
+  } catch {
+    return null;
+  }
+};
+
+export interface AsyncRunnerOptions {
+  /** the child is killed and the call yields null after this long (default 5 s, like spawnGit) */
+  timeoutMs?: number;
+  /** executable + argv to spawn (default `git -C <cwd> <args…>`); tests point it at a sleeper or a missing binary */
+  argv?: (args: readonly string[], cwd: string) => string[];
+}
+
+/** child_process.spawn under the spawnGit contract: stdin ignored, stderr dropped, stdout collected up to
+ *  MAX_BUFFER, the child killed at the timeout (spawn's own `timeout`/`killSignal`, so this module still
+ *  starts no timer of its own). Resolves null — never rejects — when the binary is missing, the call times
+ *  out, overflows or dies by signal; a non-zero exit is an ordinary `{ status, stdout }`. */
+export function gitRunnerAsync(o: AsyncRunnerOptions = {}): GitRunnerAsync {
+  const timeout = o.timeoutMs ?? TIMEOUT_MS;
+  const argv = o.argv ?? ((args: readonly string[], cwd: string): string[] => ["git", "-C", cwd, ...args]);
+  return (args, cwd, signal) => new Promise<GitResult | null>((resolve) => {
+    if (signal?.aborted) { resolve(null); return; } // already stopping: never spawn
+    let done = false;
+    const finish = (r: GitResult | null): void => { if (!done) { done = true; signal?.removeEventListener("abort", onAbort); resolve(r); } };
+    let child: ChildProcess;
+    // abort = kill, but settle from `close` below: the promise resolves only once the process is gone
+    const onAbort = (): void => { child?.kill("SIGKILL"); };
+    try {
+      const [exe, ...rest] = argv(args, cwd);
+      child = spawn(exe ?? "git", rest, { timeout, killSignal: "SIGKILL", windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+    } catch { finish(null); return; }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const chunks: Buffer[] = [];
+    let size = 0;
+    child.stdout?.on("data", (b: Buffer) => { size += b.length; if (size > MAX_BUFFER) { child.kill("SIGKILL"); } else chunks.push(b); });
+    child.on("error", () => finish(null));
+    child.on("close", (code, sig) => finish(code === null || sig !== null || size > MAX_BUFFER ? null : { status: code, stdout: Buffer.concat(chunks).toString("utf8") }));
+  });
+}
+export const spawnGitAsync: GitRunnerAsync = gitRunnerAsync();
+
+/** a sync runner (a test fake, or spawnGit) as an async one — a throwing runner becomes a null result */
+export const toAsync = (run: GitRunner | GitRunnerAsync): GitRunnerAsync => (args, cwd) => Promise.resolve().then(() => run(args, cwd));
+
+function ok(run: GitRunner, args: readonly string[], cwd: string): string | null {
+  try {
+    const r = run(args, cwd);
+    return r && r.status === 0 ? r.stdout : null;
+  } catch {
+    return null;
+  }
+}
+async function okAsync(run: GitRunnerAsync, args: readonly string[], cwd: string): Promise<string | null> {
+  try {
+    const r = await run(args, cwd);
+    return r && r.status === 0 ? r.stdout : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Current branch; a detached HEAD reports the short commit id. null = no git / not a repo. */
+export function gitBranch(cwd: string, run: GitRunner = spawnGit): string | null {
+  const ref = ok(run, ["rev-parse", "--abbrev-ref", "HEAD"], cwd)?.trim();
+  if (!ref) {
+    // an empty repo (no commits) still has a symbolic HEAD
+    const sym = ok(run, ["symbolic-ref", "--short", "-q", "HEAD"], cwd)?.trim();
+    return sym || null;
+  }
+  if (ref !== "HEAD") return ref;
+  const sha = ok(run, ["rev-parse", "--short", "HEAD"], cwd)?.trim();
+  return sha || "HEAD";
+}
+/** gitBranch, awaited */
+export async function gitBranchAsync(cwd: string, run: GitRunnerAsync = spawnGitAsync): Promise<string | null> {
+  const ref = (await okAsync(run, ["rev-parse", "--abbrev-ref", "HEAD"], cwd))?.trim();
+  if (!ref) {
+    const sym = (await okAsync(run, ["symbolic-ref", "--short", "-q", "HEAD"], cwd))?.trim();
+    return sym || null;
+  }
+  if (ref !== "HEAD") return ref;
+  const sha = (await okAsync(run, ["rev-parse", "--short", "HEAD"], cwd))?.trim();
+  return sha || "HEAD";
+}
+
+/** C-style unquoting for the non -z porcelain form (`"path with\ttab"`); octal escapes are UTF-8
+ *  BYTES (git quotes `café.ts` as `"caf\303\251.ts"`), so the result is decoded as a byte string. */
+export function unquotePath(p: string): string {
+  if (p.length < 2 || !p.startsWith("\"") || !p.endsWith("\"")) return p;
+  const body = p.slice(1, -1);
+  const bytes: number[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]!;
+    if (c !== "\\") { bytes.push(...Buffer.from(c, "utf8")); continue; }
+    const n = body[i + 1] ?? "";
+    if (/[0-7]/.test(n)) {
+      const oct = /^[0-7]{1,3}/.exec(body.slice(i + 1))![0];
+      bytes.push(parseInt(oct, 8) & 255); i += oct.length; continue;
+    }
+    bytes.push(n === "n" ? 10 : n === "t" ? 9 : n === "r" ? 13 : (n.charCodeAt(0) || 92)); i++;
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+const norm = (p: string): string => p.replace(/\\/g, "/").replace(/^\.\/+/, "");
+
+function classify(x: string, y: string): FileStatus | null {
+  if (x === "!" && y === "!") return null;      // ignored
+  if (x === "?" && y === "?") return "A";       // untracked
+  if (x === "D" || y === "D") return "D";
+  if (x === "A") return "A";
+  return "M";                                   // M/T/U/R/C and index-vs-worktree mixes
+}
+
+/** Parse porcelain v1 output — the -z form (NUL-separated, rename = `R  new\0old\0`) or the plain
+ *  newline form (`R  old -> new`, quoted paths). Renames/copies map to M on the NEW path, `??` to A,
+ *  any D to D, everything else to M; ignored entries and paths above cwd (`../`) are dropped. */
+export function parsePorcelain(text: string): Map<string, FileStatus> {
+  const out = new Map<string, FileStatus>();
+  const zForm = text.includes("\0");
+  const fields = zForm ? text.split("\0") : text.split(/\r?\n/);
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i]!;
+    if (f.length < 4) continue;
+    const x = f[0]!, y = f[1]!;
+    let path = f.slice(3);
+    if (x === "R" || y === "R" || x === "C" || y === "C") {
+      if (zForm) i++;                                   // the ORIGINAL path follows as its own field
+      else { const arrow = path.indexOf(" -> "); if (arrow >= 0) path = path.slice(arrow + 4); }
+    }
+    if (!zForm) path = unquotePath(path);
+    path = norm(path);
+    if (!path || path.startsWith("../")) continue;
+    const st = classify(x, y);
+    if (st) out.set(path, st);
+  }
+  return out;
+}
+
+/** cwd-relative posix path → M/A/D for every changed file; null when git is unavailable or the
+ *  cwd is not inside a repository (NEVER throws). */
+export function gitPorcelain(cwd: string, run: GitRunner = spawnGit): Map<string, FileStatus> | null {
+  const text = ok(run, PORCELAIN_ARGS, cwd);
+  return text === null ? null : parsePorcelain(text);
+}
+/** gitPorcelain, awaited */
+export async function gitPorcelainAsync(cwd: string, run: GitRunnerAsync = spawnGitAsync): Promise<Map<string, FileStatus> | null> {
+  const text = await okAsync(run, PORCELAIN_ARGS, cwd);
+  return text === null ? null : parsePorcelain(text);
+}
+
+/** the `HEAD:./<rel>` spec for a cwd-relative path; null for an empty path or one above cwd */
+function headSpec(path: string): string | null {
+  const rel = norm(path);
+  return !rel || rel.startsWith("../") ? null : `HEAD:./${rel}`;
+}
+
+/** The committed (HEAD) content of a cwd-relative path; null when git is unavailable, the path is
+ *  not in HEAD (new file) or the content cannot be read. */
+export function gitHeadContent(cwd: string, path: string, run: GitRunner = spawnGit): string | null {
+  const spec = headSpec(path);
+  return spec === null ? null : ok(run, ["show", spec], cwd);
+}
+/** gitHeadContent, awaited */
+export async function gitHeadContentAsync(cwd: string, path: string, run: GitRunnerAsync = spawnGitAsync): Promise<string | null> {
+  const spec = headSpec(path);
+  return spec === null ? null : okAsync(run, ["show", spec], cwd);
+}

package/src/sextant/grid.ts

@@ -0,0 +1,59 @@
+/** Sextant headless cell grid (port #41) — term.js Screen minus I/O (user's sextant v0.4.0
+ *  src/term.js:32-147): the ScreenLike double dumpFrame paints on. One cell per code point;
+ *  writes outside the buffer clip; bg -1 inherits the cell's current background. */
+
+import type { ScreenLike, Seg, Style } from "./types.ts";
+
+export class GridScreen implements ScreenLike {
+  readonly w: number; readonly h: number;
+  readonly ch: string[]; readonly fg: Int32Array; readonly bg: Int32Array; readonly at: Uint8Array;
+
+  constructor(cols: number, rows: number, bg = -1) {
+    this.w = Math.max(1, Math.floor(cols)); this.h = Math.max(1, Math.floor(rows));
+    const n = this.w * this.h;
+    this.ch = new Array<string>(n).fill(" "); this.fg = new Int32Array(n).fill(-1); this.bg = new Int32Array(n).fill(bg); this.at = new Uint8Array(n);
+  }
+  put(x: number, y: number, str: string, st?: Style, maxW = Infinity): number {
+    if (y < 0 || y >= this.h || !str) return x;
+    const fg = st ? st.fg : -1, bg = st ? st.bg : -1, a = st ? st.a : 0, end = Math.min(this.w, x + maxW);
+    let cx = x;
+    for (const c of str) {
+      if (cx >= end) break;
+      if (cx >= 0) { const i = y * this.w + cx; this.ch[i] = c; this.fg[i] = fg; if (bg >= 0) this.bg[i] = bg; this.at[i] = a; }
+      cx++;
+    }
+    return cx;
+  }
+  text(x: number, y: number, segs: readonly Seg[], maxW = Infinity): number {
+    let cx = x;
+    for (const [s, st] of segs) { if (cx >= x + maxW) break; cx = this.put(cx, y, s, st, x + maxW - cx); }
+    return cx;
+  }
+  clip(x: number, y: number, str: string, st: Style | undefined, maxW: number): number {
+    if (maxW <= 0) return x;
+    const cps = [...str];
+    return this.put(x, y, cps.length > maxW ? (maxW > 1 ? cps.slice(0, maxW - 1).join("") + "…" : cps.slice(0, maxW).join("")) : str, st, maxW);
+  }
+  fill(x: number, y: number, w: number, h: number, ch: string, st?: Style): void {
+    for (let yy = Math.max(0, y); yy < Math.min(this.h, y + h); yy++) for (let xx = Math.max(0, x); xx < Math.min(this.w, x + w); xx++) {
+      const i = yy * this.w + xx;
+      this.ch[i] = ch; this.fg[i] = st ? st.fg : -1; if (st && st.bg >= 0) this.bg[i] = st.bg; this.at[i] = st ? st.a : 0;
+    }
+  }
+  tint(x: number, y: number, w: number, h: number, bg: number): void {
+    for (let yy = Math.max(0, y); yy < Math.min(this.h, y + h); yy++) for (let xx = Math.max(0, x); xx < Math.min(this.w, x + w); xx++) this.bg[yy * this.w + xx] = bg;
+  }
+  hline(x: number, y: number, w: number, st?: Style, ch = "─"): void { for (let i = 0; i < w; i++) this.put(x + i, y, ch, st); }
+  vline(x: number, y: number, h: number, st?: Style, ch = "│"): void { for (let i = 0; i < h; i++) this.put(x, y + i, ch, st); }
+  box(x: number, y: number, w: number, h: number, st?: Style, bgFill?: number): void {
+    if (bgFill !== undefined) this.fill(x, y, w, h, " ", { fg: -1, bg: bgFill, a: 0 });
+    this.put(x, y, "╭", st); this.put(x + w - 1, y, "╮", st); this.put(x, y + h - 1, "╰", st); this.put(x + w - 1, y + h - 1, "╯", st);
+    this.hline(x + 1, y, w - 2, st); this.hline(x + 1, y + h - 1, w - 2, st); this.vline(x, y + 1, h - 2, st); this.vline(x + w - 1, y + 1, h - 2, st);
+  }
+  /** plain-text dump: one line per row, trailing whitespace trimmed (the golden-test form) */
+  toText(): string {
+    const lines: string[] = [];
+    for (let y = 0; y < this.h; y++) lines.push(this.ch.slice(y * this.w, (y + 1) * this.w).join("").replace(/\s+$/, ""));
+    return lines.join("\n");
+  }
+}

package/src/sextant/input.ts

@@ -0,0 +1,119 @@
+/** ported from the user's sextant v0.4.0 prototype, src/term.js (parseInput, enter, leave) — raw key/mouse/paste parser */
+/* Pure: bytes in → events out. The stdin/stdout hookup (raw mode, resize, carrying `rest` into the
+   next chunk) belongs to the renderer (#44). Additions over the prototype: bracketed paste arrives
+   as ONE event (a paste split across chunks waits in `rest`), an incomplete control sequence at the
+   end of a chunk is carried instead of dropped, and mouseKind() encodes app.js's onMouse rules
+   (releases ignored, 64/65 = wheel under any modifier, only the plain left button — b&3 = 0 and no
+   modifier bits — clicks or drags).
+   Renderer notes (#44): a chunk ending in a lone ESC is ambiguous — hold it ~20 ms before parsing,
+   since a chunk boundary right after ESC turns the next sequence into typed keys; decode stdin as
+   utf8 (a surrogate pair can split across chunks, so never decode chunks independently); OSC/DCS
+   replies are not recognized here, so the renderer must not send OSC queries — a reply would arrive
+   as typed text. */
+
+import type { InputEvent, KeyEvent, MouseEvent } from "./types.ts";
+
+const ESC = "\x1b";
+const CSI = ESC + "[";
+const PASTE_START = CSI + "200~";
+const PASTE_END = CSI + "201~";
+/** no real control sequence is this long; a longer unterminated fragment is garbage and is dropped */
+export const MAX_CSI = 32;
+
+const CSI_KEYS: Readonly<Record<string, string>> = { A: "up", B: "down", C: "right", D: "left", H: "home", F: "end", Z: "shift-tab", P: "f1", Q: "f2", R: "f3", S: "f4" };
+const TILDE_KEYS: Readonly<Record<string, string>> = { 1: "home", 2: "insert", 3: "delete", 4: "end", 5: "pageup", 6: "pagedown", 7: "home", 8: "end", 11: "f1", 12: "f2", 13: "f3", 14: "f4", 15: "f5", 17: "f6", 18: "f7", 19: "f8", 20: "f9", 21: "f10", 23: "f11", 24: "f12" };
+const CTRL_NAMES: Readonly<Record<number, string>> = { 0: "space", 28: "\\", 29: "]", 30: "^", 31: "/" };
+
+const MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+const TILDE_RE = /^\x1b\[(\d+)(?:;(\d+))?~/;
+const CSI_LETTER_RE = /^\x1b\[(?:(\d+);(\d+))?([A-Z])/;
+const SS3_RE = /^\x1bO([A-Z])/;
+/** what ends a sequence we do not otherwise recognize (prototype: skip to the final byte) */
+const FINAL_RE = /[A-Za-z~]/;
+
+export interface ParseResult {
+  events: InputEvent[];
+  /** an unfinished sequence (split CSI, open paste) to prepend to the next chunk */
+  rest: string;
+}
+
+/** xterm modifier parameter (1 + bits: 1 shift, 2 alt, 4 ctrl) → key event */
+function withMods(name: string, mod: string | undefined): KeyEvent {
+  const m = (mod ? Number(mod) : 1) - 1;
+  return { type: "key", name, shift: !!(m & 1), alt: !!(m & 2), ctrl: !!(m & 4) };
+}
+
+/** parse raw terminal input (carry = the previous call's `rest`) into key/mouse/paste events */
+export function parseInput(chunk: string, carry = ""): ParseResult {
+  const s = carry + chunk;
+  const evs: InputEvent[] = [];
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i]!;
+    if (c === ESC) {
+      const rest = s.slice(i);
+      if (rest.startsWith(PASTE_START)) {
+        const end = s.indexOf(PASTE_END, i + PASTE_START.length);
+        if (end < 0) return { events: evs, rest }; // the paste continues in the next chunk
+        evs.push({ type: "paste", text: s.slice(i + PASTE_START.length, end) });
+        i = end + PASTE_END.length;
+        continue;
+      }
+      let m: RegExpExecArray | null;
+      if ((m = MOUSE_RE.exec(rest))) { evs.push({ type: "mouse", b: +m[1]!, x: +m[2]! - 1, y: +m[3]! - 1, press: m[4] === "M" }); i += m[0].length; continue; }
+      if ((m = TILDE_RE.exec(rest))) { evs.push(withMods(TILDE_KEYS[m[1]!] ?? "unknown", m[2])); i += m[0].length; continue; }
+      if ((m = CSI_LETTER_RE.exec(rest))) { evs.push(withMods(CSI_KEYS[m[3]!] ?? "unknown", m[2])); i += m[0].length; continue; }
+      if ((m = SS3_RE.exec(rest))) { evs.push(withMods(CSI_KEYS[m[1]!] ?? "unknown", undefined)); i += m[0].length; continue; }
+      if (rest.length === 1) { evs.push({ type: "key", name: "escape" }); i++; continue; }
+      const nextCp = s.codePointAt(i + 1)!;
+      // ESC followed by a control byte (ESC ESC, ESC Enter…) is a bare Escape; the next byte parses on its own
+      // (the prototype reported alt+<control>, which broke the esc-esc "again to stop" arm)
+      if (nextCp < 0x20 || nextCp === 0x7f) { evs.push({ type: "key", name: "escape" }); i++; continue; }
+      const next = String.fromCodePoint(nextCp);
+      if (next !== "[" && next !== "O") { evs.push({ type: "key", name: next.toLowerCase(), alt: true, ch: next }); i += 1 + next.length; continue; }
+      // unknown or unfinished CSI/SS3: find the final byte
+      let j = i + 2;
+      while (j < s.length && !FINAL_RE.test(s[j]!)) j++;
+      if (j >= s.length) {
+        if (rest.length > MAX_CSI) { i = s.length; continue; } // garbage, not a split sequence
+        return { events: evs, rest };                          // split across chunks: keep it for the next call
+      }
+      i = j + 1; // unknown sequence: consumed, never echoed as text
+      continue;
+    }
+    if (c === "\r" || c === "\n") { evs.push({ type: "key", name: "enter" }); i++; continue; }
+    if (c === "\t") { evs.push({ type: "key", name: "tab" }); i++; continue; }
+    if (c === "\x7f" || c === "\b") { evs.push({ type: "key", name: "backspace" }); i++; continue; }
+    const code = c.charCodeAt(0);
+    if (code < 32) { evs.push({ type: "key", name: CTRL_NAMES[code] ?? String.fromCharCode(code + 96), ctrl: true }); i++; continue; }
+    const ch = String.fromCodePoint(s.codePointAt(i)!);
+    evs.push({ type: "key", name: ch, ch });
+    i += ch.length;
+  }
+  return { events: evs, rest: "" };
+}
+
+export type MouseKind = "click" | "drag" | "wheel-up" | "wheel-down" | "release" | "other";
+
+/** app.js onMouse rules: releases do nothing, 64/65 scroll — with the modifier bits (4 shift, 8 meta,
+ *  16 ctrl) masked off first, so shift+wheel over a hit zone scrolls and never clicks it — and only the
+ *  plain left button (b&3 = 0, no modifiers) clicks or drags */
+export function mouseKind(e: MouseEvent): MouseKind {
+  if (!e.press) return "release";
+  const button = e.b & ~28;
+  if (button === 64) return "wheel-up";
+  if (button === 65) return "wheel-down";
+  if ((e.b & 31) !== 0) return "other"; // a non-left (b&3) or modified (b&28) button never clicks or drags
+  return e.b & 32 ? "drag" : "click";
+}
+
+/** term.js enter(): alt screen, cursor off, no autowrap, clear, home, SGR mouse (1000/1002/1006) and bracketed paste (2004) */
+export function enterSequence(mouse = true): string {
+  return CSI + "?1049h" + CSI + "?25l" + CSI + "?7l" + CSI + "2J" + CSI + "H"
+    + (mouse ? CSI + "?1000h" + CSI + "?1002h" + CSI + "?1006h" : "") + CSI + "?2004h";
+}
+
+/** term.js leave(): the exact inverse, ending with the main screen restored */
+export function leaveSequence(): string {
+  return CSI + "?2004l" + CSI + "?1006l" + CSI + "?1002l" + CSI + "?1000l" + CSI + "0m" + CSI + "?7h" + CSI + "?25h" + CSI + "?1049l";
+}