quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/slotFormat.js

@@ -0,0 +1,195 @@
+/**
+ * SLOT-RUN A (owner 2026-10-16, about a slot message that arrived as a wrapped wall of text around a long
+ * shell command: "messy needs a format, structure, styling"). Incoming slot message bodies render light
+ * markdown: paragraphs, - bullets, **bold**, `inline code` and fenced blocks.
+ *
+ * Code is never wrapped mid-token. A long inline command is lifted into its own block; a block line that does
+ * not fit breaks ONLY at unquoted whitespace and ends in " \" (shell line continuation), so a copied block is
+ * still the same command. A single token longer than the row hard-breaks with a visible " ↩".
+ *
+ * Pure layout: rows of segments { t, role, bold? }. render.js paints them; no grey roles (owner rule).
+ */
+import { graphemes } from './textBuffer.js';
+
+export const CONT = ' \\';
+export const HARD = ' ↩';
+export const GUTTER = '│ ';
+export const LONG_INLINE = 32; // an inline code span longer than this gets its own block
+
+const len = (s) => graphemes(String(s)).length;
+
+/** Where a line may break: unquoted, unescaped whitespace before any unquoted # comment. */
+function safeBreaks(chars) {
+  const safe = new Array(chars.length).fill(false);
+  let q = null; let comment = false;
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i];
+    if (comment) continue;
+    if (q === "'") { if (ch === "'") q = null; continue; }
+    if (q === '"') { if (ch === '\\') i++; else if (ch === '"') q = null; continue; }
+    if (ch === '\\') { i++; continue; }
+    if (ch === "'" || ch === '"') { q = ch; continue; }
+    if (ch === '#' && (i === 0 || /\s/.test(chars[i - 1]))) { comment = true; continue; }
+    if (/\s/.test(ch)) safe[i] = true;
+  }
+  return safe;
+}
+
+/** One command line as rows of at most `width` columns. Continuation rows are indented two spaces. */
+export function wrapShell(line, width) {
+  const w = Math.max(12, width);
+  const chars = [...String(line)];
+  if (chars.length <= w) return [chars.join('')];
+  const safe = safeBreaks(chars);
+  const out = [];
+  let start = 0;
+  for (;;) {
+    const indent = out.length ? '  ' : '';
+    const avail = w - indent.length;
+    if (chars.length - start <= avail) { out.push(indent + chars.slice(start).join('')); break; }
+    const lim = avail - CONT.length;
+    let cut = -1;
+    for (let i = start + lim; i > start; i--) if (safe[i]) { cut = i; break; }
+    if (cut > start) {
+      out.push(indent + chars.slice(start, cut).join('').replace(/\s+$/, '') + CONT);
+      start = cut;
+      while (start < chars.length && safe[start]) start++;
+    } else {
+      const n = avail - HARD.length;
+      out.push(indent + chars.slice(start, start + n).join('') + HARD);
+      start += n;
+    }
+  }
+  return out;
+}
+
+/** Inline runs of one line: plain text, **bold**, `code`. */
+function inlineRuns(text) {
+  const out = [];
+  const re = /(`+)([^`]+?)\1|\*\*([^*]+?)\*\*/g;
+  let last = 0; let m;
+  const s = String(text);
+  while ((m = re.exec(s))) {
+    if (m.index > last) out.push({ kind: 'text', t: s.slice(last, m.index) });
+    if (m[1]) out.push({ kind: 'code', t: m[2].trim() });
+    else out.push({ kind: 'bold', t: m[3] });
+    last = m.index + m[0].length;
+  }
+  if (last < s.length) out.push({ kind: 'text', t: s.slice(last) });
+  return out;
+}
+
+/** Block structure: code (fenced, `$ ` lines, long inline spans), bullets, paragraphs, gaps. */
+function blocks(text) {
+  const src = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  const push = (b) => {
+    if (b.type === 'gap' && (!out.length || out[out.length - 1].type === 'gap')) return;
+    out.push(b);
+  };
+  for (let i = 0; i < src.length; i++) {
+    const line = src[i];
+    const fence = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      const lines = [];
+      for (i++; i < src.length && !src[i].trim().startsWith(fence[1]); i++) lines.push(src[i]);
+      push({ type: 'code', lines });
+      continue;
+    }
+    if (/^\s*\$ \S/.test(line)) {
+      const prev = out[out.length - 1];
+      if (prev?.type === 'code' && prev.dollar) prev.lines.push(line.trim()); else push({ type: 'code', lines: [line.trim()], dollar: true });
+      continue;
+    }
+    if (!line.trim()) { push({ type: 'gap' }); continue; }
+    const bullet = /^\s*(?:[-*•]|(\d+[.)]))\s+(.*)$/.exec(line);
+    const heading = /^\s*#{1,6}\s+(.*)$/.exec(line);
+    const kind = bullet ? 'bullet' : 'para';
+    const body = bullet ? bullet[2] : heading ? `**${heading[1]}**` : line;
+    const mark = bullet ? (bullet[1] ? `${bullet[1]} ` : '• ') : '';
+    // A long inline command is lifted out into its own block between the prose around it.
+    let pending = [];
+    let first = true;
+    const flush = () => {
+      if (!pending.length) return;
+      if (pending.some(r => r.kind !== 'text' || r.t.trim())) push({ type: kind, runs: pending, mark: first ? mark : (mark ? '  ' : '') });
+      first = false; pending = [];
+    };
+    for (const r of inlineRuns(body)) {
+      if (r.kind === 'code' && len(r.t) > LONG_INLINE) { flush(); push({ type: 'code', lines: [r.t] }); first = false; }
+      else pending.push(r);
+    }
+    flush();
+  }
+  while (out.length && out[out.length - 1].type === 'gap') out.pop();
+  return out;
+}
+
+/** Word-wrap inline runs to `width`; code spans are unbreakable atoms (hard-split only if wider than the row). */
+function wrapRuns(runs, width, role, prefix) {
+  const atoms = [];
+  for (const r of runs) {
+    if (r.kind === 'code') { atoms.push({ t: r.t, role: 'code', sp: /^\s/.test(r.t) }); continue; }
+    const parts = r.t.split(/(\s+)/);
+    for (const p of parts) {
+      if (!p) continue;
+      if (/^\s+$/.test(p)) { atoms.push({ space: true }); continue; }
+      atoms.push({ t: p, role, bold: r.kind === 'bold' || undefined });
+    }
+  }
+  const rows = [];
+  let cur = []; let w = 0; let gap = false;
+  const ind = len(prefix);
+  const room = Math.max(8, width - ind);
+  const add = (seg) => {
+    const last = cur[cur.length - 1];
+    if (last && last.role === seg.role && last.bold === seg.bold) last.t += seg.t; else cur.push({ ...seg });
+  };
+  const newRow = () => { rows.push(cur); cur = []; w = 0; };
+  for (const a of atoms) {
+    if (a.space) { gap = true; continue; }
+    const sep = cur.length && gap ? 1 : 0; // runs that touch (`a`**b**) stay touching
+
+    let t = a.t;
+    if (w + sep + len(t) > room && cur.length) newRow();
+    else if (sep) { add({ t: ' ', role, bold: undefined }); w += 1; }
+    while (len(t) > room) { const g = graphemes(t); add({ t: g.slice(0, room - w).join(''), role: a.role, bold: a.bold }); t = g.slice(room - w).join(''); newRow(); }
+    add({ t, role: a.role, bold: a.bold }); w += len(t);
+    gap = false;
+  }
+  if (cur.length) rows.push(cur);
+  return rows.map((r, i) => (prefix ? [{ t: i === 0 ? prefix : ' '.repeat(ind), role: 'bullet1' }, ...r] : r));
+}
+
+/** A code block's rows: gutter, the code, and the continuation marker in the label colour. */
+export function codeRows(lines, width) {
+  const rows = [];
+  for (const line of lines) {
+    for (const piece of wrapShell(line, Math.max(12, width - len(GUTTER)))) {
+      const mk = piece.endsWith(CONT) ? CONT : piece.endsWith(HARD) ? HARD : '';
+      const body = mk ? piece.slice(0, -mk.length) : piece;
+      rows.push([{ t: GUTTER, role: 'label' }, { t: body || ' ', role: 'code' }, ...(mk ? [{ t: mk, role: 'label' }] : [])]);
+    }
+  }
+  return rows;
+}
+
+/** The body of a slot message as rows of segments, at most `width` columns each. */
+export function formatSlotBody(text, width, { role = 'text' } = {}) {
+  const rows = [];
+  for (const b of blocks(text)) {
+    if (b.type === 'gap') rows.push([]);
+    else if (b.type === 'code') rows.push(...codeRows(b.lines, width));
+    else rows.push(...wrapRuns(b.runs, width, role, b.mark));
+  }
+  return rows;
+}
+
+/** Plain text of each row (tests, NO_COLOR). */
+export const rowsText = (rows) => rows.map(r => r.map(s => s.t).join(''));
+
+/** A short plain one-liner keeps the chat shape: on the header line after the time. */
+export function inlineable(text, room) {
+  const t = String(text ?? '');
+  return !/[\n`]|\*\*/.test(t) && !/^\s*(?:[-*•]\s|\d+[.)]\s|\$ |#{1,6}\s)/.test(t) && len(t) <= room;
+}

package/lib/quoxon/slotRun.js

@@ -0,0 +1,131 @@
+/**
+ * SLOT-RUN B (owner 2026-10-16: "if its a request to run the command, let me just say yes"). A slot message may
+ * carry ONE command for the human to run here (`quox slot say <slot> --run '<command>' "<why>"`, stored by the
+ * collector as the message's `run` field, never executed server-side).
+ *
+ * The TUI shows it with the shared ask: "▶ SENDER asks you to run this here: why", the FULL command in a code
+ * block (wrapped, never truncated: this is a confirm-what-you-see boundary), then "Run it? y/N/c". y hands the
+ * terminal over (like /restart: the user's own shell, stdio inherited, so OTP and login prompts work), then
+ * the TUI resumes and prints the exit code.
+ *
+ * Rules (non-negotiable): never auto-run; only from a verified sender (author_identity) in this org, otherwise
+ * shown but refused; one command; the ask expires after RUN_TTL_MS; never through the model (no turn, never a
+ * terminal_suggest_command offer); secret-shaped or destructive commands need "run" typed instead of y.
+ */
+import { spawnSync } from 'node:child_process';
+import { askText, askAnswer } from './ask.js';
+import { looksLikeKey } from './connect.js';
+import { resolveCliSlash } from './slash/cliCommand.js';
+import { tokenize } from './bang.js';
+import { codeRows } from './slotFormat.js';
+import { graphemes } from './textBuffer.js';
+import { TERMINAL_RESTORE } from './slash/restart.js';
+import { PASTE_ON } from './keys.js';
+
+export const RUN_TTL_MS = 10 * 60 * 1000;
+export const RUN_MAX_LEN = 2000;
+// Same rule as the collector (devSlotMessagesStore validateRunCommand): one line, nothing that can make the
+// screen differ from what runs (control/ESC/CR, bidi overrides, zero-width, line separators).
+const RUN_BAD_RE = /[\u0000-\u001f\u007f\u0080-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/;
+
+/** -> null (no run request) | { id, cmd, why, who, runnable, refuse, danger, expiresAt }. */
+export function runRequest(m, { orgId = null, now = Date.now() } = {}) {
+  if (!m || m.run === undefined || m.run === null || m.run === '') return null;
+  const cmd = String(m.run);
+  const who = String(m.from || m.author_identity || 'someone').replace(/\s*\(.*$/, '').trim() || 'someone';
+  let refuse = null;
+  if (!m.author_identity) refuse = `${who} is not a verified sender, so this window will not run it`;
+  else if (orgId && m.org_id && m.org_id !== orgId) refuse = `it came from another org, so this window will not run it`;
+  else if (cmd.length > RUN_MAX_LEN || !cmd.trim() || RUN_BAD_RE.test(cmd)) refuse = 'it is not one plain command on one line, so this window will not run it';
+  return { id: m.id || null, cmd, why: String(m.text ?? '').trim(), who, runnable: !refuse, refuse, danger: refuse ? null : runDanger(cmd), expiresAt: now + RUN_TTL_MS };
+}
+
+// Destructive shell shapes (the bang runner has no shell danger list of its own; these are the ones that cost
+// real work to undo). Matching one means "type run", never a refusal: it is the human's machine.
+const DESTRUCTIVE = [
+  /(^|[\s;&|(])rm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)*-[a-zA-Z]*[rRf]/, /(^|[\s;&|(])sudo\s/, /(^|[\s;&|(])doas\s/,
+  /(^|[\s;&|(])mkfs(\.\w+)?\s/, /(^|[\s;&|(])dd\s+[^|;&]*\bof=/, />\s*\/dev\/(sd|nvme|hd|vd|disk)/,
+  /\|\s*(sudo\s+)?(ba|z|da|k)?sh\b/, /\bgit\s+push\b[^|;&]*\s(--force\b|-f\b|--force-with-lease\b|--delete\b)/,
+  /\bgit\s+reset\s+--hard\b/, /\bgit\s+clean\s+-[a-zA-Z]*f/, /\bchmod\s+-R\b/, /\bchown\s+-R\b/,
+  /:\(\)\s*\{/, /(^|[\s;&|(])(shutdown|reboot|halt|poweroff)\b/, /\bdrop\s+(table|database)\b/i, /\bdocker\s+(system\s+prune|volume\s+rm)\b/,
+];
+
+/** null when y is enough; otherwise the reason "run" must be typed. Reuses the bang secret check and the quox CLI leaf policy. */
+export function runDanger(cmd) {
+  const c = String(cmd || '');
+  if (looksLikeKey(c)) return 'It contains something that looks like a key or token';
+  const words = tokenize(c);
+  if (words[0] === 'quox' || words[0] === 'q') {
+    const hit = resolveCliSlash(`/${words[1] || ''}`, words.slice(2).map(w => (/[\s"']/.test(w) ? JSON.stringify(w) : w)).join(' '));
+    if (hit?.cls === 'never') return `${hit.display} is a never-from-chat quox command`;
+  }
+  if (DESTRUCTIVE.some(re => re.test(c))) return /(^|[\s;&|(])(sudo|doas)\s/.test(c) ? 'It runs as root' : 'It looks destructive';
+  return null;
+}
+
+/** 'run' | 'needs-run' (y on a dangerous one) | 'no' | 'chat' | 'command'. */
+export function runAnswer(text, req) {
+  const t = String(text ?? '').trim();
+  if (/^run$/i.test(t)) return 'run';
+  const a = askAnswer(t);
+  if (a === 'yes') return req?.danger ? 'needs-run' : 'run';
+  return a;
+}
+
+const len = (s) => graphemes(String(s)).length;
+function wrapWords(text, width) {
+  const out = []; let line = '';
+  for (const w of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && len(line) + 1 + len(w) > width) { out.push(line); line = w; } else line = line ? `${line} ${w}` : w;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+/** The ask as rows of segments (render.js paints them; slotFormat rows shape). */
+export function runAskRows(req, width) {
+  const w = Math.max(20, width);
+  const head = askText(`${req.who} asks you to run this here:`, { keys: '' }) + (req.why ? ` ${req.why}` : '');
+  const rows = wrapWords(head, w).map((l, i) => [{ t: i ? `  ${l}` : l, role: 'ask', bold: true }]);
+  // wrapWords may push an indented continuation over the width: re-wrap continuations at w - 2
+  const fixed = [];
+  for (const r of rows) { if (len(r[0].t) <= w) fixed.push(r); else for (const p of wrapWords(r[0].t, w - 2)) fixed.push([{ t: `  ${p}`, role: 'ask', bold: true }]); }
+  fixed.push(...codeRows([req.cmd], w));
+  let last;
+  if (!req.runnable) last = { t: `✖ Not offered: ${req.refuse}. Copy it yourself only if you trust it.`, role: 'warn' };
+  else if (req.danger) last = { t: askText('Type run to run it, n to skip?', { keys: 'run/N/c', reason: req.danger }), role: 'ask', bold: true };
+  else last = { t: askText('Run it?'), role: 'ask', bold: true };
+  for (const l of wrapWords(last.t, w)) fixed.push([{ ...last, t: l }]);
+  return fixed;
+}
+
+/**
+ * Run the command in the user's own shell with the terminal handed over (stdio inherited), then take it back.
+ * The live frame is cleared first and padded after, so the TUI redraws below the command's output instead of
+ * over it. -> { code, signal, ms } | { error, ms }.
+ */
+export function handOverRun({ cmd, file = null, args = null, env = process.env, cwd = process.cwd(), stdout = null, setRawMode = null, spawn = spawnSync, shell, now = Date.now, resume = '' }) {
+  const tty = Boolean(stdout?.isTTY);
+  const rows = tty ? Math.max(0, Number(stdout.frameRows) || 0) : 0;
+  const put = (s) => { try { stdout.write(Buffer.from(s)); } catch { /* closed */ } };
+  if (tty) put(`\r${rows ? `\x1b[${rows}A` : ''}\x1b[J${TERMINAL_RESTORE}`);
+  try { setRawMode?.(false); } catch { /* not a tty */ }
+  const t0 = now();
+  let r;
+  try { // file + args (BANG-TTY: !quox runs this binary's argv) or a shell command line
+    r = file ? spawn(file, args || [], { stdio: 'inherit', cwd, env }) : spawn(shell || env.SHELL || '/bin/sh', ['-lc', cmd], { stdio: 'inherit', cwd, env });
+  } catch (e) { r = { error: e }; }
+  const ms = now() - t0;
+  try { setRawMode?.(true); } catch { /* not a tty */ }
+  if (tty) put(`\n${'\n'.repeat(rows)}${PASTE_ON}${resume}`); // resume: mouse tracking back on when /mouse on (QUOXON-MOUSE)
+  if (r?.error) return { error: `${r.error.code || 'failed'}: ${r.error.message}`, ms };
+  return { code: r?.status ?? null, signal: r?.signal || null, ms };
+}
+
+/** The footer after a hand-over run. */
+export function runFooter(r) {
+  const secs = `${(r.ms / 1000).toFixed(1)}s`;
+  if (r.error) return `Could not start it: ${r.error}`;
+  if (r.signal) return `killed by ${r.signal} · ${secs}`;
+  return `exit ${r.code} · ${secs}`;
+}

package/lib/quoxon/sound/mapping.js

@@ -78,8 +78,9 @@ export function soundForEvent(prev, action, ctx = {}) {
   const now = ctx.now ?? action?.now ?? 0;
   if (!prev || !action) return null;
   // An approval card appeared (stream event or inbox poll).
-  if (next.approvals?.length > (prev.approvals?.length || 0)) return 'hitl';
+  if (next.approvals?.length > (prev.approvals?.length || 0) || next.waiting?.length > (prev.waiting?.length || 0)) return 'hitl'; // a card, or another session's notice
   if (action.type === 'approval.result') return action.outcome === 'failed' ? 'denied' : null;
+  if (action.type === 'stepup.result') return action.ok ? 'success' : 'denied'; // QUOXON-STEPUP: reuse the existing cues
   if (action.type !== 'event' || !action.ev) return null;
   const ev = action.ev;
   switch (ev.type) {

package/lib/quoxon/stray.js

@@ -0,0 +1,22 @@
+/**
+ * TUI-INPUT: a letter then "/" ("n/help") is a card answer that leaked into the composer ahead of a command.
+ * Pure: -> { letter, command } when the text looks like that and the rest names a known slash command, else null.
+ * (Ordinary "w/o", "b/c" or "and/or" never match: the word after the slash must be a command.)
+ */
+export function strayCardAnswer(text, names = []) {
+  const t = String(text ?? '').trim();
+  const m = /^([a-z])\/([a-z][\w-]*)(?=\s|$)/i.exec(t);
+  if (!m) return null;
+  if (!names.includes(`/${m[2].toLowerCase()}`)) return null;
+  return { letter: m[1].toLowerCase(), command: t.slice(1) };
+}
+
+/** The one-line question (askText adds the y/N/c keys). */
+export const strayQuestion = (s) => `Did you mean ${s.command.split(/\s+/)[0]}? (the '${s.letter}' looks like a stray card answer)`;
+
+/** True when the same message is already queued, steered or waiting for the server. */
+export function alreadyQueued(text, { pending = [], steering = [], waiting = null } = {}) {
+  const t = String(text ?? '').trim();
+  if (!t) return false;
+  return [...pending, ...steering].some(p => String(p.text ?? '').trim() === t) || String(waiting?.text ?? '').trim() === t;
+}

package/lib/quoxon/suggestCommand.js

@@ -0,0 +1,59 @@
+/**
+ * The assistant can hand the TUI a slash command for things only the terminal can do (attach a slot, join a room,
+ * open a view). The TUI is the authority: only an active registry command, never a `!` shell, never the commands the
+ * human must type (approvals, grants, session end, sign-in). The offer is "Run /slot hitl? y/N"; y runs it through the
+ * normal command path so every existing guard applies. A read-only view may run without asking when the user's
+ * ask was explicit.
+ */
+import { findCommandEntry } from './commands.js';
+
+// Commands that need the human's own typing: never offered, never run from a model suggestion.
+export const HUMAN_TYPED = new Set(['approve', 'yestoall', 'deny', 'authorise', 'authorize', 'authenticate', 'override', 'restart', 'quit', 'exit', 'login']);
+// Pure views, no effect: may run without asking when explicit, and only with no arguments.
+export const READ_ONLY_VIEWS = new Set(['approvals', 'mind', 'which', 'context', 'rooms', 'active', 'slots']);
+
+/** -> { ok: true, line, id, readOnly } | { ok: false, reason } */
+export function vetSuggestion(raw) {
+  const line = typeof raw === 'string' ? raw.trim() : '';
+  if (!line) return { ok: false, reason: 'empty' };
+  if (/[\r\n]/.test(line) || line.length > 120) return { ok: false, reason: 'not a single short line' };
+  if (!line.startsWith('/') || line.startsWith('//')) return { ok: false, reason: 'only slash commands can be suggested' };
+  const word = line.slice(1).split(/\s+/)[0];
+  const entry = findCommandEntry(word);
+  if (!entry || entry.kind !== 'command' || entry.status !== 'active') return { ok: false, reason: `/${word} is not a command here` };
+  if (HUMAN_TYPED.has(entry.id) || HUMAN_TYPED.has(word.toLowerCase())) return { ok: false, reason: `/${word} must be typed by you` };
+  const bare = line.slice(1 + word.length).trim() === '';
+  return { ok: true, line, id: entry.id, readOnly: READ_ONLY_VIEWS.has(entry.id) && bare };
+}
+
+/**
+ * Safety net (owner 2026-10-15 "STOP TELLING ME TO RUN COMMANDS"): the answer text named a command instead of the
+ * model calling terminal_suggest_command. Exactly ONE distinct slash command in backticks that passes vetSuggestion
+ * -> that vetted suggestion; none, two or more distinct, or a human-typed one (/approve, /restart...) -> null.
+ */
+export function namedCommand(text) {
+  const src = String(text || '');
+  const seen = new Set();
+  for (const m of src.matchAll(/`(\/[a-z][^`\n]{0,118})`/gi)) {
+    if (mentionsAPath(src, m.index, m[0].length, m[1])) continue; // `/health` the endpoint is not /health the command
+    seen.add(m[1].trim().replace(/\s+/g, ' '));
+  }
+  if (seen.size !== 1) return null;
+  const v = vetSuggestion([...seen][0]);
+  return v.ok ? v : null;
+}
+
+// A URL path, not a command (owner live 05:26: "the `/health` endpoint is erroring" offered "Run /health?").
+const PATHY = /\b(endpoints?|paths?|routes?|urls?|uris?|ports?|curl|wget|https?|localhost)\b|:\d{2,5}\b/i;
+const VERBS = /\b(GET|POST|PUT|PATCH|DELETE|HEAD)\b/; // upper-case only: "to get a view" is not an HTTP verb
+function mentionsAPath(src, at, len, inner) {
+  const first = String(inner).trim().split(/\s+/)[0];
+  if (/^\/[^/]*\//.test(first)) return true; // /api/x or /health/ready: a longer path
+  const sentence = (from, dir) => { // the same sentence, up to 40 characters away
+    const t = dir < 0 ? src.slice(Math.max(0, from - 40), from) : src.slice(from, from + 40);
+    const parts = t.split(/[.!?\n]/);
+    return dir < 0 ? parts[parts.length - 1] : parts[0];
+  };
+  const near = sentence(at, -1) + ' ' + sentence(at + len, 1);
+  return PATHY.test(near) || VERBS.test(near);
+}

package/lib/quoxon/term.js

@@ -1,3 +1,5 @@
+import { graphemes } from './textBuffer.js';
+import { createScreenMirror, MOUSE_ON, MOUSE_OFF, DSR } from './mouse.js';
 /**
  * The terminal as Ink sees it.
  *
@@ -12,9 +14,16 @@
  * repaint checks read stdout.rows). The app reads the real height from termRows() and keeps its live
  * region shorter than the screen itself (app.js), so log-update can always erase it.
  */
-export function inkStdout(out) {
+export function inkStdout(out, { tap = null } = {}) {
   if (!out || out.__quoxInk) return out;
-  const diff = out.isTTY ? createLineDiff() : null;
+  // QUOXON-MOUSE: what Ink has drawn, as plain lines, for click hit-testing (mouse.js). Fed the same writes.
+  const mirror = out.isTTY ? createScreenMirror({ columns: () => out.columns }) : null;
+  // SCREEN-FRAMES: the same feed goes to the screen recorder's tap (screenFrames.js), which only queues it.
+  const feed = mirror && tap ? {
+    write: (c) => { mirror.write(c); try { tap.write(c); } catch { /* never break a frame */ } },
+    reset: () => { mirror.reset(); try { tap.reset(); } catch { /* ignore */ } }
+  } : mirror;
+  const diff = out.isTTY ? createLineDiff({ columns: () => out.columns, mirror: feed }) : null;
   // One frame = one write: Ink brackets each frame in separate synchronized-update writes (?2026h ... ?2026l);
   // they are held and sent together with the (diffed) frame, and a frame that changed nothing sends nothing.
   // A write that sends nothing (or is held for the frame) must still call its callback: Ink's unmount waits
@@ -44,7 +53,9 @@ export function inkStdout(out) {
       if (prop === 'write' && write) return write;
       if (prop === 'rows') return Infinity;
       if (prop === 'termRows') return target.rows;
+      if (prop === 'frameRows') { const n = diff?.rows(); return n == null ? null : Math.min(n, Math.max(0, (target.rows || n + 1) - 1)); }
       if (prop === '__quoxInk') return true;
+      if (prop === 'screen') return mirror;
       const v = Reflect.get(target, prop, target);
       return typeof v === 'function' ? v.bind(target) : v;
     },
@@ -69,16 +80,34 @@ export function termRows(stdout) {
  * through untouched and resets the diff, so the next frame is drawn in full. Cursor moves never scroll.
  * (Ink's own incrementalRendering was tried first and duplicates lines on the dropped-text replay.)
  */
+const ANSI_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const visibleWidth = (line) => graphemes(String(line).replace(ANSI_RE, '')).length;
 const FRAME_RE = /^((?:\x1b\[2K\x1b\[1A)*\x1b\[2K\x1b\[G)([\s\S]*)$/;
 const SYNC_ON = '\x1b[?2026h', SYNC_OFF = '\x1b[?2026l';
-const TRANSPARENT = new Set(['\x1b[?2026h', '\x1b[?2026l', '\x1b[?25l', '\x1b[?25h', '']);
-export function createLineDiff() {
+const TRANSPARENT = new Set(['\x1b[?2026h', '\x1b[?2026l', '\x1b[?25l', '\x1b[?25h', '', MOUSE_ON, MOUSE_OFF, DSR]); // + QUOXON-MOUSE mode switches and the click's cursor query
+export function createLineDiff({ columns = () => null, mirror = null } = {}) {
   let prev = null; // lines of the last frame, trailing '' included
+  const bodyLines = (body) => (body && body.endsWith('\n') && !body.includes('\x1b[2J') ? body.split('\n') : null);
   const diff = (chunk) => {
-    if (TRANSPARENT.has(chunk)) return chunk; // synchronized-update brackets and cursor hide/show around a frame
+    if (TRANSPARENT.has(chunk)) return chunk;
+    mirror?.write(chunk); // synchronized-update brackets and cursor hide/show around a frame
     const m = FRAME_RE.exec(chunk);
-    if (!m || !m[2].endsWith('\n') || m[2].includes('\x1b[2J')) { prev = null; return chunk; }
+    // Not an erase+frame: a frame Ink drew after clearing (no erase prefix), static history, or something else.
+    // The last such write before the next erase is the frame on screen (Ink writes static output, then the frame).
+    if (!m) { prev = bodyLines(chunk); return chunk; }
     const erased = (m[1].match(/\x1b\[2K/g) || []).length;
+    const cols = columns();
+    if (prev && cols > 0) {
+      // R3 D2: after a resize the terminal has reflowed the old frame (a narrower screen wraps each line onto more
+      // rows), and Ink's erase counts lines, not rows: ghost composers, or history reprinted to cover them. Count
+      // the rows the frame really occupies at this width; when that differs, go to its top and clear down.
+      const rows = prev.slice(0, -1).reduce((n, l) => n + Math.max(1, Math.ceil(visibleWidth(l) / cols)), 0);
+      if (rows !== erased - 1) {
+        prev = bodyLines(m[2]);
+        return `\r${rows ? `\x1b[${rows}A` : ''}\x1b[J${m[2]}`;
+      }
+    }
+    if (!m[2].endsWith('\n') || m[2].includes('\x1b[2J')) { prev = null; return chunk; }
     const next = m[2].split('\n');
     if (!prev || erased !== prev.length || next.length !== prev.length || next.length < 2) { prev = next; return chunk; }
     const body = next.length - 1;
@@ -92,15 +121,21 @@ export function createLineDiff() {
     prev = next;
     return changed ? out : '';
   };
-  diff.reset = () => { prev = null; };
+  diff.reset = () => { prev = null; mirror?.reset(); };
+  /** Rows the live frame occupies on screen (wrapped at the current width), or null when unknown. SLOT-RUN hand-over. */
+  diff.rows = () => {
+    if (!prev) return null;
+    const cols = columns();
+    return prev.slice(0, -1).reduce((n, l) => n + (cols > 0 ? Math.max(1, Math.ceil(visibleWidth(l) / cols)) : 1), 0);
+  };
   return diff;
 }
 
 /**
  * Ink render options for the interactive client. Standard rendering (Ink's incrementalRendering duplicated lines on
- * the dropped-text replay); the stdout proxy line-diffs same-height frames instead. Never mouse tracking, never the
- * alternate screen: native selection keeps working.
+ * the dropped-text replay); the stdout proxy line-diffs same-height frames instead. Never the alternate screen, and
+ * no mouse tracking unless the user turns it on (/mouse on, QUOXON-MOUSE): native selection keeps working by default.
  */
-export function inkRenderOptions(stdout) {
-  return { exitOnCtrlC: false, stdout: inkStdout(stdout) };
+export function inkRenderOptions(stdout, { tap = null } = {}) {
+  return { exitOnCtrlC: false, stdout: inkStdout(stdout, { tap }) };
 }