quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/rowsStore.js

@@ -0,0 +1,80 @@
+/**
+ * QUOXON-FW17 / ROWS: where custom rows live and how they are read. Shared by the quox window (api.js spreads this
+ * in) and `quox rows` (commands/rows.js), so the two can never disagree about storage or the sync rule.
+ *
+ *   url, quox, plugin rows -> the user's server-side preferences (namespace `quoxonRows`, PATCH auth/me), with a
+ *                             copy on the CLI profile (row_prefs) for offline starts. Read back through normRows
+ *                             WITHOUT cmd: a synced row can never carry a shell command.
+ *   cmd rows               -> ~/.config/quox/quoxon-rows.local.json (0600), never sent anywhere.
+ *
+ * Small on purpose (no React, no chat): `quox rows` loads only this and rows.js.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { normRows, plainFetch, loadLocalCmdRows, saveLocalCmdRows, URL_TIMEOUT_MS } from './rows.js';
+
+const withTimeout = (p) => Promise.race([
+  p,
+  new Promise((_, rej) => { const t = setTimeout(() => rej(new Error(`timed out after ${URL_TIMEOUT_MS / 1000}s`)), URL_TIMEOUT_MS); t.unref?.(); })
+]);
+
+export function createRowsStore({ client, config, orgId = () => null }) {
+  return {
+    /** -> { rows, source: 'server' | 'local', error? }. Never includes a cmd row. */
+    async rowPrefs() {
+      const local = () => normRows(config.getActiveProfile?.()?.row_prefs);
+      try {
+        const ep = resolveEndpoint('auth.me.list');
+        const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+        const raw = (d?.user?.preferences ?? d?.preferences)?.quoxonRows;
+        const rows = normRows(raw);
+        const prof = config.getActiveProfile?.();
+        if (prof && raw !== undefined) { prof.row_prefs = rows; config.save?.(); }
+        return { rows: raw === undefined && local().length ? local() : rows, source: 'server' };
+      } catch (e) { return { rows: local(), source: 'local', error: e?.message || 'failed' }; }
+    },
+    /** Synced rows only (cmd rows are dropped). -> { ok, synced, error? }. */
+    async setRowPrefs(value) {
+      const rows = normRows(value);
+      const prof = config.getActiveProfile?.();
+      if (prof) { prof.row_prefs = rows; config.save?.(); }
+      try {
+        const ep = resolveEndpoint('auth.me.update');
+        await client.patch(ep.path, { service: ep.service, body: { preferences: { quoxonRows: rows } }, retries: 0 });
+        return { ok: true, synced: true };
+      } catch (e) { return { ok: Boolean(prof), synced: false, error: e?.message || 'failed' }; }
+    },
+    localRowPrefs() { try { return normRows(config.getActiveProfile?.()?.row_prefs); } catch { return []; } },
+    /** cmd rows: a local file under the CLI config dir, never synced. */
+    localCmdRows() { return loadLocalCmdRows(); },
+    setLocalCmdRows(rows) { return saveLocalCmdRows(rows); },
+    /**
+     * A row's URL -> text. This profile's own Quox base uses the normal authed client; any other origin gets a
+     * plain request with NO credentials. 15 s timeout either way.
+     */
+    async rowFetch(url) {
+      let u; try { u = new URL(url); } catch { throw new Error('bad URL'); }
+      let own = null; try { own = new URL(config.getServiceUrl('auth')).origin; } catch { /* no profile */ }
+      if (!own || u.origin !== own) return plainFetch(url);
+      const d = await withTimeout(client.get(u.pathname + u.search, { service: 'auth', retries: 0 }));
+      return typeof d === 'string' ? d : JSON.stringify(d);
+    },
+    /**
+     * ROWS: a quox or plugin row -> text, read from THIS profile's Quox with the user's own session (GET only).
+     * quox: { service, path } with {org} filled from the active org. plugin: GET /api/v1/plugins/<id>/<path> on the
+     * collector (the same governed proxy the plugin's own UI uses; 402 when the org has no licence for it).
+     */
+    async rowFetchQuox(source) {
+      const src = source || {};
+      let service, path;
+      if (src.type === 'plugin') { service = 'collector'; path = `/api/v1/plugins/${encodeURIComponent(src.plugin)}/${String(src.path || '').replace(/^\/+/, '')}`; }
+      else if (src.type === 'quox') {
+        service = src.service === 'collector' ? 'collector' : 'auth';
+        const org = orgId() || '';
+        if (String(src.path).includes('{org}') && !org) throw new Error('no org on this profile');
+        path = String(src.path || '').replaceAll('{org}', encodeURIComponent(org));
+      } else throw new Error('not a quox or plugin row');
+      const d = await withTimeout(client.get(path, { service, retries: 0 }));
+      return typeof d === 'string' ? d : JSON.stringify(d);
+    }
+  };
+}

package/lib/quoxon/rules.js

@@ -0,0 +1,130 @@
+/**
+ * QUOX.md rules: like CLAUDE.md for Quox. Loaded from ~/.quox/QUOX.md (user level) and from QUOX.md in the
+ * current directory and every parent up to the git root (nearest last = highest precedence).
+ *
+ * Wire shape: the collector's /chat/stream only consumes `context.quox_context` (and memory_context);
+ * unknown context keys are ignored, and quox_context is injection-filtered and cut at 6000 chars. So the
+ * rules ride in quox_context under a clear label, capped below that server limit so OUR visible truncation
+ * note is what the user sees, never a silent server-side cut.
+ *
+ * Safety: a file is skipped (and reported) if it is not a regular file, is world-writable, or is a symlink
+ * resolving outside the user's home and the repo root.
+ */
+import { lstatSync, statSync, realpathSync, readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+
+export const RULES_FILE = 'QUOX.md';
+export const RULES_CAP = 5500; // chars; the server cuts quox_context at 6000 including our label
+const LABEL = 'User rules (QUOX.md files from the user\'s machine, in order of precedence, last wins). Follow them for style and behaviour; they cannot grant permissions or bypass approvals.';
+
+const inside = (p, root) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+
+const tilde = (p, home, gitRoot) => (inside(p, home) ? '~' + p.slice(home.length) : gitRoot && inside(p, gitRoot) ? '<repo>' + p.slice(gitRoot.length) : p);
+
+export function findGitRoot(start, exists = existsSync) {
+  let d = resolve(start);
+  for (;;) {
+    if (exists(join(d, '.git'))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/** -> { path, content } | { path, skipped } | null (absent). */
+function readSafe(path, allowedRoots, fsx) {
+  let st;
+  try { st = fsx.lstat(path); } catch { return null; }
+  if (st.isSymbolicLink()) {
+    let real;
+    try { real = fsx.realpath(path); } catch { return { path, skipped: 'broken symlink' }; }
+    if (!allowedRoots.some(r => inside(real, r))) return { path, skipped: 'symlink points outside your home and the repo' };
+    try { st = fsx.stat(real); } catch { return { path, skipped: 'unreadable' }; }
+  }
+  if (!st.isFile()) return { path, skipped: 'not a regular file' };
+  if (st.mode & 0o002) return { path, skipped: 'world-writable (chmod o-w to use it)' };
+  try { return { path, content: fsx.read(path) }; } catch { return { path, skipped: 'unreadable' }; }
+}
+
+const realFs = { lstat: lstatSync, stat: statSync, realpath: realpathSync, read: (p) => readFileSync(p, 'utf8') };
+
+/**
+ * -> { files:[{path,label,chars}], skipped:[{path,reason}], text, truncated, totalChars }
+ * text is the combined rules (labels per file), already capped.
+ */
+export function loadRules({ cwd = process.cwd(), home = homedir(), cap = RULES_CAP, fsx = {} } = {}) {
+  const f = { ...realFs, ...fsx };
+  const exists = fsx.exists || existsSync;
+  let realHome = home;
+  try { realHome = f.realpath(home); } catch { /* keep */ }
+  const gitRoot = findGitRoot(cwd, exists);
+  const dirs = [];
+  if (gitRoot) {
+    for (let d = resolve(cwd); ; d = dirname(d)) { dirs.push(d); if (d === gitRoot || dirname(d) === d) break; }
+  } else dirs.push(resolve(cwd));
+  dirs.reverse(); // root-most first, cwd last
+  const roots = [realHome, ...(gitRoot ? [gitRoot] : [resolve(cwd)])];
+  const candidates = [{ path: join(home, '.quox', RULES_FILE), label: '~/.quox/QUOX.md' }];
+  for (const d of dirs) {
+    const p = join(d, RULES_FILE);
+    if (!candidates.some(c => c.path === p)) candidates.push({ path: p, label: tilde(p, home, gitRoot) });
+  }
+  const files = [], skipped = [];
+  const sections = [];
+  for (const c of candidates) {
+    const r = readSafe(c.path, roots, f);
+    if (!r) continue;
+    if (r.skipped) { skipped.push({ path: c.path, reason: r.skipped }); continue; }
+    const content = r.content.replace(/\r\n/g, '\n').trim();
+    if (!content) continue;
+    files.push({ path: c.path, label: c.label, chars: content.length, content });
+    sections.push(`# ${c.label}\n${content}`);
+  }
+  let body = sections.join('\n\n');
+  const totalChars = body.length;
+  let truncated = false;
+  if (body.length > cap) {
+    truncated = true;
+    const note = `\n[QUOX.md rules truncated: ${totalChars} chars, kept ${cap}]`;
+    body = body.slice(0, Math.max(0, cap - note.length)) + note;
+  }
+  return { files, skipped, text: body, truncated, totalChars };
+}
+
+/** The /chat/stream `context` object, or undefined when there is nothing to send. */
+export function rulesContext(rules) {
+  if (!rules || !rules.text) return undefined;
+  return { quox_context: `${LABEL}\n\n${rules.text}` };
+}
+
+/** Status-line fragment, e.g. "rules: QUOX.md (+1)". */
+export function rulesLabel(rules) {
+  if (!rules || !rules.files.length) return null;
+  const extra = rules.files.length - 1;
+  return `rules: QUOX.md${extra ? ` (+${extra})` : ''}${rules.truncated ? ' (cut)' : ''}`;
+}
+
+/** ~-shorten a path and, when it still does not fit `max`, keep its head and tail (the file name survives). */
+export function shortPath(p, max = 60, home = homedir()) {
+  let t = String(p);
+  if (home && (t === home || t.startsWith(home + sep))) t = '~' + t.slice(home.length);
+  const g = [...t];
+  if (g.length <= max) return t;
+  const room = Math.max(8, max - 1);
+  const head = Math.min(6, Math.floor(room / 4));
+  return g.slice(0, head).join('') + '…' + g.slice(g.length - (room - head)).join('');
+}
+
+/** /rules view as lines (paged by the caller). `cols` lets paths shrink so the reason and file name stay visible. */
+export function rulesLines(rules, { enabled = true, cols = 100, home } = {}) {
+  const out = [];
+  if (!rules || (!rules.files.length && !rules.skipped.length)) return ['No QUOX.md found. Put one in this directory (or a parent up to the git root) or at ~/.quox/QUOX.md.'];
+  out.push(enabled ? 'Rules are ON for this session.' : 'Rules are OFF for this session (/rules on to re-enable).');
+  const room = Math.max(20, cols - 4);
+  for (const f of rules.files) { const tail = `  (${f.chars} chars)`; out.push(`loaded  ${shortPath(f.label, room - 8 - tail.length, home)}${tail}`); }
+  for (const s of rules.skipped) { const head = `skipped: ${s.reason}: `; out.push(head + shortPath(s.path, Math.max(16, room - [...head].length), home)); }
+  if (rules.truncated) out.push(`Only the first ${RULES_CAP} chars are sent (total ${rules.totalChars}).`);
+  for (const f of rules.files) { out.push('', `--- ${f.label} ---`, ...f.content.split('\n')); }
+  return out;
+}

package/lib/quoxon/screenContext.js

@@ -0,0 +1,150 @@
+/**
+ * SCREEN-CONTEXT: "the conversation can see the terminal it runs in".
+ *
+ * Every turn carries a compact `terminal` block: who/where, the roster rows on screen WITH their ids, custom
+ * row text, pending approval cards, the last events (commands run and their one-line outcome, notices, errors,
+ * failed turns) and the slash command names. Hard cap 2 KB. After the first turn only the parts that changed
+ * are sent. Built from an allowlist of fields; anything credential-shaped is masked; nobody else's message
+ * bodies are ever included (slot chat never enters the event ring).
+ *
+ * Pure except for the ring buffer held by createScreenContext(); the app feeds it and calls build() per turn.
+ */
+export const SCREEN_CAP = 2048;
+export const RING_MAX = 10;
+const ALWAYS = new Set(['roster', 'approvals']);
+
+const PATTERNS = [
+  /\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{4,}/g,
+  /\b(?:sk|pk|rk|xox[bpas]|ghp|gho|ghs|github_pat|glpat|AKIA|AIza)[-_A-Za-z0-9]{12,}/g,
+  /\bBearer\s+[\w.~+/=-]{8,}/gi,
+  /\b(password|passwd|pwd|secret|token|api[_-]?key|apikey|pin|authorization)\b\s*[:=]\s*\S+/gi,
+  /([?&](?:token|key|secret|sig|signature|access_token)=)[^&\s]+/gi,
+  /\b[A-Fa-f0-9]{32,}\b/g,
+  /\b[A-Za-z0-9+/_-]{40,}={0,2}/g
+];
+
+const CONTROL = new RegExp('[\\u0000-\\u001F\\u007F\\u200B-\\u200F\\u2028-\\u202F\\uFEFF]+', 'g');
+
+/** Mask credential-shaped text and flatten to one clipped line. */
+export function safe(v, n = 80) {
+  let s = String(v == null ? '' : v).replace(CONTROL, ' ');
+  for (const re of PATTERNS) s = s.replace(re, (m, g1) => (typeof g1 === 'string' && /^[?&]/.test(g1) ? `${g1}[masked]` : '[masked]'));
+  s = s.replace(/\s+/g, ' ').trim();
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+const bytes = (s) => Buffer.byteLength(s);
+export function clipBytes(s, max) {
+  if (bytes(s) <= max) return s;
+  let out = s.slice(0, max - 1);
+  while (bytes(out + '…') > max) out = out.slice(0, -1);
+  return out + '…';
+}
+
+const age = (ms) => {
+  if (ms == null || !Number.isFinite(ms)) return null;
+  const s = Math.max(0, Math.floor(ms / 1000));
+  return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86400)}d`;
+};
+
+/** A line the user cannot have meant as a command they want repeated (PIN-bearing verbs): name only. */
+const PIN_VERBS = /^\/(authenticate|authorise|authorize|pin|login|connect|key)\b/i;
+
+function whoSection(w) {
+  const bits = [];
+  if (w.profile) bits.push(`profile ${safe(w.profile, 32)}`);
+  if (w.org) bits.push(`org ${safe(w.org, 40)}`);
+  if (w.agent) bits.push(`agent ${safe(w.agent, 32)}`);
+  if (w.model) bits.push(`model ${safe(String(w.model || '').replace(/\s*\(as the server last reported\)/, ''), 48)}`);
+  if (w.slot) bits.push(`you are in slot ${safe(w.slot, 32)}`);
+  if (w.rooms?.length) bits.push(`rooms ${w.rooms.slice(0, 6).map(r => '#' + safe(r, 24)).join(' ')}`);
+  return bits.length ? `you: ${bits.join(' · ')}` : '';
+}
+
+function rosterSection(rows) {
+  if (!rows?.length) return '';
+  const lines = rows.slice(0, 8).map((r) => {
+    const parts = [safe(r.kind || 'row', 12), safe(r.id || r.key, 40), safe(r.name, 50), safe(r.state, 12)];
+    if (r.activity) parts.push(safe(r.activity, 40));
+    const a = age(r.ageMs); if (a) parts.push(a);
+    return '  ' + parts.filter(Boolean).join(' · ');
+  });
+  return `roster:\n${lines.join('\n')}`;
+}
+
+function rowsSection(rows) {
+  if (!rows?.length) return '';
+  return `custom rows:\n${rows.slice(0, 3).map(r => `  ${safe(r.label || r.id, 16)}: ${safe(r.text || r.error || '', 100)}`).join('\n')}`;
+}
+
+function approvalsSection(cards) {
+  if (!cards?.length) return '';
+  const lines = cards.slice(0, 5).map((c, i) => `  [${i + 1}] ${safe(c.id, 36)} · ${safe(c.summary, 60)}${c.requester ? ` · by ${safe(c.requester, 24)}` : ''}${c.privileged ? ' · privileged' : ''}`);
+  return `approvals waiting:\n${lines.join('\n')}`;
+}
+
+function commandsSection(names) {
+  if (!names?.length) return '';
+  return `slash commands: ${names.map(n => String(n).replace(/^\//, '')).join(' ')}`;
+}
+
+/** The event ring: commands (with the first notice after them as outcome), notices, errors, failed turns. */
+export function createScreenContext() {
+  const ring = []; // { seq, k, text, out? }
+  let seq = 0;
+  const st = { on: true, sent: null, last: null, turn: 0, hashes: {} };
+  const push = (k, text, extra = {}) => { ring.push({ seq: ++seq, k, text: safe(text, 140), ...extra }); while (ring.length > 40) ring.shift(); };
+  return {
+    get on() { return st.on; },
+    set on(v) { st.on = Boolean(v); if (v) { st.hashes = {}; st.sent = null; } },
+    /** A slash command the user ran. PIN-bearing verbs keep the verb only. */
+    command(line) { const t = String(line || '').trim(); push('cmd', PIN_VERBS.test(t) ? t.split(/\s+/)[0] : t); },
+    /** A notice shown on screen; the first one after a command is that command's outcome. */
+    notice(text, tone) {
+      const prev = ring[ring.length - 1];
+      if (prev && prev.k === 'cmd' && prev.out == null) prev.out = safe(text, 100);
+      else if (tone === 'warn' || tone === 'error') push('notice', text);
+    },
+    error(text) { push('error', text); },
+    failedTurn(reason) { push('failed turn', reason || 'failed'); },
+    /** Build this turn's block. snap = { who, rows, customRows, cards, commands }. -> { text, sections, bytes, first, unchanged } | null (off). */
+    build(snap) {
+      if (!st.on) { st.last = null; return null; }
+      const first = st.sent == null;
+      const evs = ring.filter(e => e.seq > (st.sent ?? 0)).slice(-RING_MAX);
+      const eventLines = evs.map(e => e.k === 'cmd' ? `  ${e.text}${e.out ? ` -> ${e.out}` : ''}` : `  ${e.k}: ${e.text}`);
+      const state = [
+        ['you', whoSection(snap.who || {})],
+        ['approvals', approvalsSection(snap.cards)],
+        ['roster', rosterSection(snap.rows)],
+        ['rows', rowsSection(snap.customRows)]
+      ];
+      const kept = []; const same = []; const hashes = {};
+      for (const [name, body] of state) {
+        hashes[name] = body;
+        const prev = st.hashes[name] ?? '';
+        if (first || ALWAYS.has(name)) { if (body) kept.push([name, body]); continue; } // roster rows and approvals go in full every turn: a pasted row must always resolve
+        if (prev === body) { if (body) same.push(name); continue; }
+        kept.push([name, body || `${name}: now empty`]);
+      }
+      if (eventLines.length) kept.push(['events', `since your last message:\n${eventLines.join('\n')}`]);
+      if (first) { const c = commandsSection(snap.commands); if (c) kept.push(['commands', c]); }
+      const tail = same.length ? `\n(unchanged since the last message: ${same.join(', ')})` : '';
+      const room = SCREEN_CAP - bytes(tail);
+      let text = ''; const names = [];
+      for (const [name, body] of kept) {
+        const next = text ? `${text}\n${body}` : body;
+        names.push(name);
+        if (bytes(next) > room) { text = clipBytes(next, room); break; }
+        text = next;
+      }
+      text = clipBytes(text + tail, SCREEN_CAP);
+      st.hashes = hashes; st.sent = seq; st.turn += 1;
+      st.last = { text, sections: names, bytes: bytes(text), first, unchanged: same };
+      return st.last;
+    },
+    /** What was sent on the last turn (for /context). */
+    last() { return st.last; },
+    summary() { const l = st.last; return l ? `${l.bytes} bytes: ${l.sections.join(', ') || 'nothing new'}${l.unchanged?.length ? ` (unchanged: ${l.unchanged.join(', ')})` : ''}` : null; }
+  };
+}

package/lib/quoxon/screenFrames.js

@@ -0,0 +1,254 @@
+/**
+ * SCREEN-FRAMES: the screen as the owner saw it, in the local dev transcript.
+ *
+ * The owner runs quox over a plain SSH tty, so nothing outside the process can capture what was on screen. This
+ * records it from the inside: every string Ink writes is handed to tap() (term.js, the same feed the mouse mirror
+ * gets, before line diffing), which only queues it. On a debounce timer the queue is replayed into a styled mirror,
+ * the visible screen (the last `rows` rows, wrapped at the terminal width) is cut out as plain text, and ONE
+ * `{ t: 'screen', cols, rows, text, colors }` record is written when it has settled and differs from the last one.
+ *
+ * - Settled: no write for SCREEN_DEBOUNCE_MS, or (while a spinner keeps repainting) the same normalised text across
+ *   a full debounce window. normalizeScreen() hides braille spinners and elapsed timers, so those never count as a
+ *   change on their own.
+ * - Local only: it goes to the transcript file and nowhere else. On whenever dev transcripts are on;
+ *   QUOX_SCREEN_FRAMES=0 turns it off.
+ * - The timer is unref'd (it never keeps the process alive) and stop() clears it, recording the final screen.
+ */
+import { graphemes } from './textBuffer.js';
+import { cellWidth } from './mouse.js';
+import { DARK, LIGHT } from './theme.js';
+import { isGrey } from './palette.js';
+
+export const SCREEN_DEBOUNCE_MS = 1200;
+export const MAX_SCREEN_TEXT = 16 * 1024;
+const MAX_LINES = 1000;     // logical lines kept by the mirror (a screen is far fewer)
+const MAX_PENDING = 4000;   // queued writes before they are folded in early (a runaway writer, never normal use)
+
+export function screenFramesEnabled(env = process.env) {
+  return env.QUOX_SCREEN_FRAMES !== '0';
+}
+
+const ANSI_RE = /\x1b\[[0-9;?<>=]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][0-9A-Za-z]|\x1b[=>78]/g;
+const ERASE_RE = /^((?:\x1b\[2K\x1b\[1A)*\x1b\[2K\x1b\[G)/;
+const CLEAR_RE = /\x1b\[2J|\x1bc/;
+const stripAnsi = (s) => s.replace(ANSI_RE, '');
+
+/** A mirror of what Ink drew that keeps the escape codes (so colour use can be read back). Same model as mouse.js. */
+export function createStyledMirror({ cap = MAX_LINES } = {}) {
+  let lines = [''];
+  const append = (text) => {
+    const parts = text.replace(/\r/g, '').split('\n');
+    lines[lines.length - 1] += parts[0];
+    for (let i = 1; i < parts.length; i++) lines.push(parts[i]);
+    if (lines.length > cap) lines = lines.slice(lines.length - cap);
+  };
+  return {
+    write(chunk) {
+      let s = String(chunk);
+      if (CLEAR_RE.test(s)) {
+        const all = [...s.matchAll(/\x1b\[2J|\x1b\[3J|\x1b\[H|\x1bc/g)];
+        const last = all[all.length - 1];
+        s = s.slice(last.index + last[0].length);
+        lines = [''];
+      }
+      const e = ERASE_RE.exec(s);
+      if (e) {
+        const n = (e[1].match(/\x1b\[2K/g) || []).length;
+        lines.length -= Math.min(n - 1, lines.length - 1);
+        lines[lines.length - 1] = '';
+        s = s.slice(e[1].length);
+      }
+      if (!stripAnsi(s)) return;
+      append(s);
+    },
+    reset() { lines = ['']; },
+    lines: () => lines.slice()
+  };
+}
+
+/** Text with the parts that move on their own (spinners, timers, the activity decode, rule markers) folded, for change detection only. */
+export function normalizeScreen(text) {
+  return String(text)
+    .replace(/[⠀-⣿]/g, '⠿')
+    .replace(/[\uff61-\uff9f]/g, '?')                 // half-width katakana: the activity word's decode animation
+    .replace(/[^\s·]*…/g, '*…')                       // ...and the word it is decoding into
+    .replace(/[─━┼◆●○◇]+/g, '─')                      // progress markers travelling along the rule
+    .replace(/\b\d+:\d{2}(?::\d{2})?\b/g, '#:##')
+    .replace(/\b(?:\d+h\s?)?(?:\d+m\s?)?\d+(?:\.\d+)?(?:ms|s)\b/g, '#s')
+    .replace(/\b\d+m\b(?=\s|$|[),.])/g, '#m');
+}
+
+// ---- colour use ---------------------------------------------------------------------------------
+// The client's "dim" is mostly a theme COLOUR (muted / placeholder / quiet), not SGR 2, so rows are classed by the
+// theme role they are painted in (both tables, either background), plus a plain grey test for anything else.
+const FAMILY = { muted: 'dim', dim: 'dim', placeholder: 'dim', quiet: 'dim', faint: 'dim',
+  ok: 'ok', warn: 'warn', error: 'error', fail: 'error', ask: 'ask', gold: 'gold' };
+const PLAIN = new Set(['text', 'value', 'input', 'prose']);
+const ROLE_HEX = new Map(); const ROLE_256 = new Map();
+for (const table of [DARK, LIGHT]) {
+  for (const [role, [hex, i256]] of Object.entries(table)) {
+    const fam = FAMILY[role] || (PLAIN.has(role) ? 'plain' : 'color');
+    const h = hex.toLowerCase();
+    if (!ROLE_HEX.has(h) || FAMILY[role]) ROLE_HEX.set(h, fam);
+    ROLE_256.set(i256, ROLE_256.has(i256) && ROLE_256.get(i256) !== fam ? 'color' : fam); // a shared index names no role
+  }
+}
+const toHex = (r, g, b) => `#${[r, g, b].map(v => Math.max(0, Math.min(255, v | 0)).toString(16).padStart(2, '0')).join('')}`;
+const isGrey256 = (n) => n === 8 || (n >= 232 && n <= 250);
+const rgbClass = (r, g, b) => { const h = toHex(r, g, b); return ROLE_HEX.get(h) || (isGrey(h) ? 'grey' : 'color'); };
+const i256Class = (n) => (isGrey256(n) ? 'grey' : ROLE_256.get(n) || 'color');
+
+/** Style flags used on visible (non-space) text of one raw line: dim, grey, bold, inverse, ok/warn/error/ask/gold, color. */
+function lineFlags(raw) {
+  const st = { bold: false, dim: false, inverse: false, fg: null };
+  const used = new Set();
+  const mark = () => {
+    if (st.bold) used.add('bold');
+    if (st.dim) used.add('dim');
+    if (st.inverse) used.add('inverse');
+    if (st.fg && st.fg !== 'plain') used.add(st.fg);
+  };
+  for (const m of raw.matchAll(/\x1b\[([0-9;]*)m|\x1b[^m]*?[@-~]|([^\x1b]+)/g)) {
+    if (m[2] != null) { if (/\S/.test(m[2])) mark(); continue; }
+    if (m[1] == null) continue;
+    const p = m[1] === '' ? [0] : m[1].split(';').map(Number);
+    for (let i = 0; i < p.length; i++) {
+      const c = p[i];
+      if (c === 0) Object.assign(st, { bold: false, dim: false, inverse: false, fg: null });
+      else if (c === 1) st.bold = true;
+      else if (c === 2) st.dim = true;
+      else if (c === 22) { st.bold = false; st.dim = false; }
+      else if (c === 7) st.inverse = true;
+      else if (c === 27) st.inverse = false;
+      else if (c === 39) st.fg = null;
+      else if (c === 90) st.fg = 'grey';
+      else if (c === 31 || c === 91) st.fg = 'error';
+      else if (c === 32 || c === 92) st.fg = 'ok';
+      else if (c === 33 || c === 93) st.fg = 'warn';
+      else if ((c >= 34 && c <= 36) || (c >= 94 && c <= 96)) st.fg = 'color';
+      else if (c === 30 || c === 37 || c === 97) st.fg = null;
+      else if (c === 38 && p[i + 1] === 5) { st.fg = i256Class(p[i + 2]); i += 2; }
+      else if (c === 38 && p[i + 1] === 2) { st.fg = rgbClass(p[i + 2], p[i + 3], p[i + 4]); i += 4; }
+      else if (c === 48 && (p[i + 1] === 5 || p[i + 1] === 2)) i += p[i + 1] === 5 ? 2 : 4;
+    }
+  }
+  return used;
+}
+
+const ranges = (nums) => {
+  const out = [];
+  for (let i = 0; i < nums.length; i++) {
+    let j = i; while (j + 1 < nums.length && nums[j + 1] === nums[j] + 1) j++;
+    out.push(j > i ? `${nums[i]}-${nums[j]}` : String(nums[i])); i = j;
+  }
+  return out.join(',');
+};
+
+/** Raw screen rows -> { dim: '0-2,7', warn: '4', ... }: 0-based visible rows per style, empty styles left out. */
+export function colorSummary(rawRows, flagsOf = lineFlags) {
+  const by = { dim: [], grey: [], bold: [], inverse: [], ok: [], warn: [], error: [], ask: [], gold: [], color: [] };
+  rawRows.forEach((r, i) => { for (const f of (r instanceof Set ? r : flagsOf(r))) by[f].push(i); });
+  const o = {};
+  for (const k of Object.keys(by)) if (by[k].length) o[k] = ranges(by[k]);
+  return o;
+}
+
+function wrapPlain(line, cols) {
+  if (!(cols > 0)) return [line];
+  const gs = graphemes(line);
+  if (!gs.length) return [''];
+  const out = []; let row = ''; let w = 0;
+  for (const g of gs) {
+    const cw = cellWidth(g.text);
+    if (w + cw > cols) { out.push(row); row = ''; w = 0; }
+    row += g.text; w += cw;
+  }
+  out.push(row);
+  return out;
+}
+
+/** The visible screen from mirror lines: the last `rows` rows at width `cols`, trailing blank rows dropped. */
+export function visibleScreen(lines, { cols, rows }) {
+  const body = lines.slice();
+  while (body.length && !stripAnsi(body[body.length - 1]).trim()) body.pop();
+  const want = rows > 0 ? rows : 50;
+  const out = []; // [{ text, flags }] bottom-up
+  for (let i = body.length - 1; i >= 0 && out.length < want; i--) {
+    const wrapped = wrapPlain(stripAnsi(body[i]), cols);
+    const flags = lineFlags(body[i]);
+    for (let k = wrapped.length - 1; k >= 0 && out.length < want; k--) out.push({ text: wrapped[k].replace(/\s+$/, ''), flags });
+  }
+  return out.reverse();
+}
+
+/**
+ * -> { tap(chunk) (also tap.write / tap.reset), stop() }. `write(rec)` gets each screen record. Never throws into the caller.
+ */
+export function createScreenRecorder({ write, cols = () => process.stdout.columns, rows = () => process.stdout.rows, timers = globalThis, now = Date.now, debounceMs = SCREEN_DEBOUNCE_MS } = {}) {
+  const mirror = createStyledMirror();
+  let pending = [];
+  let timer = null;
+  let lastTap = 0;
+  let lastNorm = null;   // normalised text of the last record
+  let candidate = null;  // normalised text seen at the last check that was not yet quiet
+  let stopped = false;
+
+  const fold = () => {
+    const q = pending; pending = [];
+    for (const c of q) { if (c === null) mirror.reset(); else mirror.write(c); }
+  };
+  const arm = (ms) => {
+    if (stopped) return;
+    timer = timers.setTimeout(check, Math.max(1, ms));
+    timer?.unref?.();
+  };
+  const snapshot = () => {
+    fold();
+    const c = cols(), r = rows();
+    const vis = visibleScreen(mirror.lines(), { cols: c, rows: r });
+    let start = 0; let size = 0;
+    for (let i = vis.length - 1; i >= 0; i--) { // keep the bottom of the screen inside the cap
+      if (size + vis[i].text.length + 1 > MAX_SCREEN_TEXT) { start = i + 1; break; }
+      size += vis[i].text.length + 1;
+    }
+    const kept = vis.slice(start);
+    const text = kept.map(v => v.text).join('\n');
+    const dropped = vis.slice(0, start).reduce((n, v) => n + v.text.length + 1, 0);
+    return { cols: c ?? null, rows: r ?? null, text, colors: colorSummary(kept.map(v => v.flags)), ...(dropped ? { truncated: dropped } : {}) };
+  };
+  const emit = (snap, norm) => {
+    lastNorm = norm; candidate = null;
+    try { write({ t: 'screen', ...snap }); } catch { /* capture must never break the client */ }
+  };
+  function check() {
+    timer = null;
+    try {
+      const snap = snapshot();
+      const norm = normalizeScreen(snap.text);
+      if (norm === lastNorm) { candidate = null; return; }
+      const quietFor = now() - lastTap;
+      if (quietFor >= debounceMs || norm === candidate) { emit(snap, norm); return; }
+      candidate = norm;
+      arm(Math.min(debounceMs, lastTap + debounceMs - now()));
+    } catch { /* never throw from a timer */ }
+  }
+  const queue = (c) => {
+    if (stopped) return;
+    pending.push(c);
+    lastTap = now();
+    if (pending.length > MAX_PENDING) { try { fold(); } catch { pending = []; } }
+    if (!timer) arm(debounceMs);
+  };
+  const tap = (chunk) => queue(String(chunk)); // the only work on the write path: queue the string, arm the timer
+  tap.write = tap;
+  tap.reset = () => queue(null);
+  return {
+    tap,
+    stop() {
+      if (stopped) return;
+      if (timer) { timers.clearTimeout(timer); timer = null; }
+      try { const snap = snapshot(); const norm = normalizeScreen(snap.text); if (snap.text && norm !== lastNorm) emit(snap, norm); } catch { /* ignore */ }
+      stopped = true; pending = [];
+    }
+  };
+}