quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/suggestCommand.js

@@ -0,0 +1,90 @@
+/**
+ * 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 closing = closingProposal(src);
+  if (closing !== undefined) return closing; // the answer's own closing question names THE command: that one or nothing
+  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;
+  return offerable([...seen][0]);
+}
+
+// Commands that SEND or WRITE something: a mention is never an offer (the model must call terminal_suggest_command).
+export const WRITE_COMMANDS = new Set(['broadcast', 'roar', 'say', 'page', 'ack', 'reply', 'r', 'ask', 'aside', 'afk', 'back', 'observe', 'awaken', 'poke', 'wake', 'nudge', 'ping', 'slap', 'feedback', 'gripe', 'gripe!', 'note', 'dragon', 'wish', 'challenge', 'huh']);
+
+// vetted AND safe to offer from a mention: not a write/send, and no required <arg> left unfilled.
+function offerable(line) {
+  const v = vetSuggestion(line);
+  if (!v.ok) return null;
+  if (WRITE_COMMANDS.has(v.id) || WRITE_COMMANDS.has(line.slice(1).split(/\s+/)[0].toLowerCase())) return null;
+  const entry = findCommandEntry(line.slice(1).split(/\s+/)[0]);
+  const bare = line.trim().split(/\s+/).length === 1;
+  if (bare && /</.test(String(entry?.usage || ''))) return null; // "/ack <broadcast id>" needs its argument
+  return v;
+}
+
+// "Do you want me to run X?" / "Shall I run X?" -> undefined (no such question) | the offer for X | null.
+// X as a slash command is offered when safe; X as a `quox <verb>` CLI line is offered only as the matching read-only slash view.
+function closingProposal(src) {
+  const m = /(?:do you want me to|want me to|would you like me to|shall i|should i|can i)\s+(?:run|try|use|show you)\s+`?([^?`\n]{1,120}?)`?\s*(?:and\b[^?\n]*)?\?\s*$/i.exec(src.trim());
+  if (!m) return undefined;
+  const x = m[1].trim();
+  if (x.startsWith('/')) return offerable(x.replace(/\s+/g, ' '));
+  const cli = /^!?quox\s+([a-z][\w-]*)\s*$/i.exec(x);
+  if (cli) {
+    const slash = '/' + cli[1].toLowerCase();
+    const v = offerable(slash);
+    return v && v.readOnly ? v : null;
+  }
+  return 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 }) };
 }

package/lib/quoxon/textBuffer.js

@@ -18,7 +18,135 @@ const UNDO_LIMIT = 100;
 const PASTE_RE = /\[Pasted text #(\d+) \+\d+ lines\]/g;
 
 export function initialBuffer(text = '') {
-  return { text, cursor: text.length, undo: [], redo: [], pastes: {}, pasteSeq: 0 };
+  return { text, cursor: text.length, anchor: null, undo: [], redo: [], pastes: {}, pasteSeq: 0 };
+}
+
+/**
+ * QUOXON-MOUSE: the composer selection, { from, to } (from < to), or null. A selection is the range between
+ * `anchor` (where a drag started) and the cursor; only the mouse sets an anchor.
+ */
+export function selection(s) {
+  if (s?.anchor == null || s.anchor === s.cursor) return null;
+  return { from: Math.min(s.anchor, s.cursor), to: Math.max(s.anchor, s.cursor) };
+}
+
+/** The word under `idx` for a double-click: a run of non-space characters, or the one space character itself. */
+export function wordAt(text, idx) {
+  const t = String(text);
+  const i = Math.max(0, Math.min(idx, t.length - 1));
+  if (!t.length) return { from: 0, to: 0 };
+  if (/\s/.test(t[i])) return { from: i, to: nextBoundary(t, i) };
+  let a = i; let b = i;
+  while (a > 0 && !/\s/.test(t[a - 1])) a--;
+  while (b < t.length && !/\s/.test(t[b])) b++;
+  return { from: a, to: b };
+}
+
+/** Snap an index onto a grapheme boundary (at or before it). */
+function snap(text, idx) {
+  const i = Math.max(0, Math.min(Number(idx) || 0, text.length));
+  return i === text.length ? i : prevBoundary(text, i + 1);
+}
+
+/** The selected range widened so it never leaves half a paste placeholder behind. */
+function selRange(s, sel) {
+  let { from, to } = sel;
+  PASTE_RE.lastIndex = 0;
+  let m;
+  while ((m = PASTE_RE.exec(s.text))) {
+    const a = m.index, b = a + m[0].length;
+    if (to > a && from < b) { from = Math.min(from, a); to = Math.max(to, b); }
+  }
+  return { from, to };
+}
+
+const EDITS = new Set(['insert', 'newline', 'paste', 'backspace', 'delete', 'deleteWordBack', 'killLineBack', 'killLineForward', 'deleteWordForward']);
+
+/** COMPOSER-EDIT: the selected text, paste placeholders expanded (what Shift selection copies). '' when none. */
+export function selectedText(s) {
+  const sel = selection(s);
+  if (!sel) return '';
+  const { from, to } = selRange(s, sel);
+  return expandPastes({ text: s.text.slice(from, to), pastes: s.pastes || {} });
+}
+
+// ---- COMPOSER-EDIT: words and soft-wrapped rows ------------------------------------------------
+const WORD = /[\p{L}\p{N}_]/u;
+/** Readline backward-word: skip non-word characters, then the word. */
+function wordLeftIndex(t, i) {
+  while (i > 0 && !WORD.test(t[i - 1])) i--;
+  while (i > 0 && WORD.test(t[i - 1])) i--;
+  return i;
+}
+/** Readline forward-word: skip non-word characters, then the word (lands at its end). */
+function wordRightIndex(t, i) {
+  while (i < t.length && !WORD.test(t[i])) i++;
+  while (i < t.length && WORD.test(t[i])) i++;
+  return i;
+}
+/** Remove [from, to), widened so no paste placeholder is left half cut. */
+function cutRange(s, from, to) {
+  if (from >= to) return s;
+  const r = selRange(s, { from, to });
+  return commit(s, { text: s.text.slice(0, r.from) + s.text.slice(r.to), cursor: r.from });
+}
+
+const cellW = (g) => (/[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/u.test(g) || (/\p{Extended_Pictographic}/u.test(g) && (g.codePointAt(0) >= 0x1f000 || g.includes('\uFE0F'))) ? 2 : 1);
+/**
+ * The draft as the rows the terminal shows at `width` cells: [{ start, end }] (UTF-16 indices, end exclusive,
+ * newline not included). Word wrap like Ink's: a word that does not fit starts a new row, spaces hang at the row
+ * end, and a word longer than a row is split hard.
+ */
+export function visualRows(text, width) {
+  const out = [];
+  let o = 0;
+  for (const line of String(text).split('\n')) {
+    if (!(width > 0) || !line.length) { out.push({ start: o, end: o + line.length }); o += line.length + 1; continue; }
+    const tokens = line.match(/\s+|\S+/g);
+    let rowStart = o; let w = 0; let p = o;
+    for (const tok of tokens) {
+      const gs = graphemes(tok);
+      const tw = gs.reduce((n, g) => n + cellW(g.text), 0);
+      if (/^\s/.test(tok) || w + tw <= width) { w += tw; p += tok.length; continue; }
+      if (tw <= width) { out.push({ start: rowStart, end: p }); rowStart = p; w = tw; p += tok.length; continue; }
+      for (const g of gs) { // longer than a row: split it hard
+        const cw = cellW(g.text);
+        if (w + cw > width && w > 0) { out.push({ start: rowStart, end: p }); rowStart = p; w = 0; }
+        w += cw; p += g.text.length;
+      }
+    }
+    out.push({ start: rowStart, end: o + line.length });
+    o += line.length + 1;
+  }
+  return out;
+}
+/** Index of the visual row holding `cursor`. A cursor at a soft break sits at the start of the next row. */
+function rowOf(rows, cursor) {
+  for (let i = rows.length - 1; i >= 0; i--) if (cursor >= rows[i].start) return i;
+  return 0;
+}
+/** COMPOSER-EDIT: is the cursor on the first (`up`) or last (`down`) row the terminal shows? */
+export function atVisualEdge(s, dir, width) {
+  if (!(width > 0)) {
+    return dir === 'up' ? !s.text.slice(0, s.cursor).includes('\n') : !s.text.slice(s.cursor).includes('\n');
+  }
+  const rows = visualRows(s.text, width);
+  const r = rowOf(rows, s.cursor);
+  return dir === 'up' ? r === 0 : r === rows.length - 1;
+}
+function moveVisual(s, dir, width) {
+  const rows = visualRows(s.text, width);
+  const r = rowOf(rows, s.cursor);
+  const t = dir === 'up' ? r - 1 : r + 1;
+  if (t < 0 || t >= rows.length) return s;
+  const col = graphemes(s.text.slice(rows[r].start, s.cursor)).reduce((n, g) => n + cellW(g.text), 0);
+  const row = rows[t];
+  const soft = t + 1 < rows.length && rows[t + 1].start === row.end; // the row breaks softly: its end is the next row's start
+  const gs = graphemes(s.text.slice(row.start, row.end));
+  let at = 0; let idx = row.end;
+  for (const g of gs) { const w = cellW(g.text); if (col < at + w) { idx = row.start + g.index; break; } at += w; }
+  if (soft && idx >= row.end) idx = prevBoundary(s.text, row.end);
+  return { ...s, cursor: idx };
 }
 
 export function graphemes(text) {
@@ -86,6 +214,14 @@ function indexAtLineCol(text, line, col) {
   return start + gs[col].index;
 }
 
+/** First logical line the composer shows (it shows at most `maxLines`, keeping the cursor line in view). */
+export function composerFrom(buf, maxLines = 8) {
+  const n = buf.text.split('\n').length;
+  if (n <= maxLines) return 0;
+  const { line } = lineCol(buf.text, buf.cursor);
+  return Math.min(Math.max(0, line - Math.floor(maxLines / 2)), n - maxLines);
+}
+
 export function normalizeNewlines(t) { return String(t).replace(/\r\n?/g, '\n'); }
 
 /** Build the collapsed form of a paste, or null when it is small enough to inline. */
@@ -94,7 +230,36 @@ export function shouldCollapse(text) {
   return text.length > PASTE_CHAR_LIMIT || lines > PASTE_LINE_LIMIT;
 }
 
-export function bufferReducer(s, a) {
+export function bufferReducer(s0, a) {
+  const sel = selection(s0);
+  const s = s0.anchor == null ? s0 : { ...s0, anchor: null };
+  if (sel && EDITS.has(a.type)) {
+    // QUOXON-MOUSE: Backspace/Delete remove the selection; typing or pasting replaces it. One undo step.
+    const { from, to } = selRange(s, sel);
+    const cut = { ...s, text: s.text.slice(0, from) + s.text.slice(to), cursor: from };
+    if (a.type !== 'insert' && a.type !== 'newline' && a.type !== 'paste') return commit(s, { text: cut.text, cursor: from });
+    const next = baseReducer({ ...cut, undo: [] }, a);
+    return commit(s, { text: next.text, cursor: next.cursor, pastes: next.pastes, pasteSeq: next.pasteSeq });
+  }
+  if (sel && a.type === 'left') return { ...s, cursor: sel.from };
+  if (sel && a.type === 'right') return { ...s, cursor: sel.to };
+  switch (a.type) {
+    case 'extend': { // COMPOSER-EDIT: Shift+movement grows the selection from where it started
+      const anchor = s0.anchor ?? s0.cursor;
+      const moved = baseReducer({ ...s, anchor: null }, { type: a.move, width: a.width });
+      return { ...s, cursor: moved.cursor, anchor: moved.cursor === anchor ? null : anchor };
+    }
+    case 'selectAll': return s.text ? { ...s, anchor: 0, cursor: s.text.length } : s;
+    case 'place': return { ...s, cursor: snap(s.text, a.index) };
+    case 'select': {
+      const anchor = snap(s.text, a.anchor); const cursor = snap(s.text, a.cursor);
+      return { ...s, anchor: anchor === cursor ? null : anchor, cursor };
+    }
+    default: return baseReducer(s, a);
+  }
+}
+
+function baseReducer(s, a) {
   switch (a.type) {
     case 'insert': {
       const t = normalizeNewlines(a.text);
@@ -144,6 +309,14 @@ export function bufferReducer(s, a) {
       if (from === s.cursor) return s;
       return commit(s, { text: s.text.slice(0, from) + s.text.slice(s.cursor), cursor: from });
     }
+    case 'wordLeft': return { ...s, cursor: wordLeftIndex(s.text, s.cursor) };
+    case 'wordRight': return { ...s, cursor: wordRightIndex(s.text, s.cursor) };
+    case 'killLineForward': { // Ctrl+K: to the end of the line; at the end, join the next line
+      const nl = s.text.indexOf('\n', s.cursor);
+      const end = nl === -1 ? s.text.length : (nl === s.cursor ? nl + 1 : nl);
+      return cutRange(s, s.cursor, end);
+    }
+    case 'deleteWordForward': return cutRange(s, s.cursor, wordRightIndex(s.text, s.cursor)); // Alt+D
     case 'left': return { ...s, cursor: prevBoundary(s.text, s.cursor) };
     case 'right': return { ...s, cursor: nextBoundary(s.text, s.cursor) };
     case 'home': return { ...s, cursor: lineCol(s.text, s.cursor).start };
@@ -152,6 +325,7 @@ export function bufferReducer(s, a) {
       return { ...s, cursor: nl === -1 ? s.text.length : nl };
     }
     case 'up': case 'down': {
+      if (a.width > 0) return moveVisual(s, a.type, a.width); // COMPOSER-EDIT: through soft-wrapped rows
       const { line, col } = lineCol(s.text, s.cursor);
       const target = a.type === 'up' ? line - 1 : line + 1;
       const count = s.text.split('\n').length;

package/lib/quoxon/theme.js

@@ -8,6 +8,7 @@
  * Purple is for keys and accents only, never whole sentences.
  */
 import { graphemes } from "./textBuffer.js";
+import { SEMANTIC_DARK, SEMANTIC_LIGHT, stripMarks, MARK } from './palette.js';
 
 export const MIN_COLS = 40;
 
@@ -20,14 +21,18 @@ export const DARK = {
   value: ['#f1f5f9', 255],
   number: ['#38bdf8', 75],
   link: ['#38bdf8', 75],
-  code: ['#06b6d4', 38], codeBg: ['#1f2937', 235], codeRule: ['#155e75', 24],
-  key: ['#a855f7', 135],
-  muted: ['#7d8594', 245],
+  code: ['#2dd4bf', 80], codeBg: ['#1f2937', 235], codeRule: ['#155e75', 24],
+  key: ['#2dd4bf', 80], // a thing you type: the command colour (purple is brand chrome only)
+  muted: ['#bcc8e8', 189],
   ok: ['#4ade80', 78], warn: ['#f59e0b', 214], error: ['#f87171', 210],
+  ask: ['#f472b6', 211], // QUOXON-ASK: "needs you" (every y/N and approval): glyph and keys, bold line
+  gold: ['#d4af37', 178], // the authorisation moment: step-up PIN card frame, filled dots, human-present countdown
   // legacy names, kept so existing call sites read the same
   sky: ['#38bdf8', 75], violet: ['#a855f7', 135], indigo: ['#818cf8', 105], teal: ['#06b6d4', 38],
-  fail: ['#f87171', 210], dim: ['#7d8594', 245], faint: ['#4b5563', 240],
-  text: ['#cbd5e1', 252], input: ['#ffffff', 231], placeholder: ['#9ca3af', 248]
+  fail: ['#f87171', 210], dim: ['#bcc8e8', 189], faint: ['#7c8fe0', 105],
+  text: ['#f1f5f9', 255], input: ['#ffffff', 231], placeholder: ['#bcc8e8', 189],
+  // semantic roles (palette.js)
+  prose: SEMANTIC_DARK.prose, command: SEMANTIC_DARK.command, id: SEMANTIC_DARK.value, brand: SEMANTIC_DARK.brand, quiet: SEMANTIC_DARK.quiet, rule: SEMANTIC_DARK.rule
 };
 export const LIGHT = {
   heading: ['#0369a1', 25],
@@ -37,16 +42,19 @@ export const LIGHT = {
   value: ['#0f172a', 234],
   number: ['#0369a1', 25],
   link: ['#0369a1', 25],
-  code: ['#0e7490', 30], codeBg: ['#ecfeff', 195], codeRule: ['#67e8f9', 117],
-  key: ['#7e22ce', 91],
-  muted: ['#4b5563', 240],
+  code: ['#0f766e', 30], codeBg: ['#ecfeff', 195], codeRule: ['#67e8f9', 117],
+  key: ['#0f766e', 30],
+  muted: ['#3b4f87', 60],
   ok: ['#15803d', 28], warn: ['#b45309', 130], error: ['#b91c1c', 124],
+  ask: ['#be185d', 161],
+  gold: ['#8a6500', 94],
   sky: ['#0369a1', 25], violet: ['#7e22ce', 91], indigo: ['#4338ca', 62], teal: ['#0e7490', 30],
-  fail: ['#b91c1c', 124], dim: ['#4b5563', 240], faint: ['#9ca3af', 248],
-  text: ['#334155', 238], input: ['#0f172a', 234], placeholder: ['#6b7280', 243]
+  fail: ['#b91c1c', 124], dim: ['#3b4f87', 60], faint: ['#7280c8', 104],
+  text: ['#0f172a', 234], input: ['#0f172a', 234], placeholder: ['#3b4f87', 60],
+  prose: SEMANTIC_LIGHT.prose, command: SEMANTIC_LIGHT.command, id: SEMANTIC_LIGHT.value, brand: SEMANTIC_LIGHT.brand, quiet: SEMANTIC_LIGHT.quiet, rule: SEMANTIC_LIGHT.rule
 };
 /** Roles a reader must be able to read: each is held to >= 4.5:1 on its background (tests). */
-export const ROLES = ['heading', 'icon', 'bullet1', 'bullet2', 'bullet3', 'label', 'value', 'number', 'link', 'code', 'key', 'muted', 'ok', 'warn', 'error', 'text', 'placeholder'];
+export const ROLES = ['heading', 'icon', 'bullet1', 'bullet2', 'bullet3', 'label', 'value', 'number', 'link', 'code', 'key', 'muted', 'ok', 'warn', 'error', 'ask', 'gold', 'text', 'placeholder', 'prose', 'command', 'id', 'brand', 'quiet'];
 
 /** Heading gradient stops across the word: sky -> indigo -> violet (light: the -700 shades). */
 export const HEADING_STOPS = { dark: ['#38bdf8', '#6366f1', '#a855f7'], light: ['#0369a1', '#4338ca', '#7e22ce'] };
@@ -59,12 +67,12 @@ export const AGENT_SHADES = {
 /** Model providers in their brand colours (dark, light). Unknown = muted. */
 export const PROVIDER_COLORS = {
   openai: ['#f5f5f5', '#111111'], anthropic: ['#D97757', '#b4532e'], google: ['#4796E3', '#1a62c4'],
-  ollama: ['#e5e7eb', '#4b5563'], mistral: ['#FA520F', '#c2410c'], deepseek: ['#4D6BFE', '#2f4fe0'],
+  ollama: ['#e5e7eb', '#3b4f87'], mistral: ['#FA520F', '#c2410c'], deepseek: ['#4D6BFE', '#2f4fe0'],
   perplexity: ['#20808D', '#1a6b76'], xai: ['#f5f5f5', '#111111'],
   // B5: OpenAI-compatible presets (dark bg shade, light bg shade; all >= 4.5:1 on their background)
   openrouter: ['#6566F1', '#4f46e5'], huggingface: ['#FFD21E', '#8a6500'], groq: ['#F55036', '#c2290f'],
   together: ['#0F6FFF', '#0b57d0'], lmstudio: ['#a78bfa', '#6d28d9'], vllm: ['#30A2FF', '#0b6bb8'],
-  openai_compatible: ['#9ca3af', '#4b5563']
+  openai_compatible: ['#c7d2fe', '#3b4f87']
 };
 /** Protocol trace marks (AEE, AOCL, VOLT, WARD), each its own Q shade (dark, light). */
 export const PROTO_COLORS = {
@@ -187,21 +195,21 @@ export const bulletRole = (depth) => ['bullet1', 'bullet2', 'bullet3'][((depth %
 
 // ---- paint: split a plain line into coloured runs; the characters never change ---------------------
 const GLYPH_ROLE = {
-  '●': 'ok', '✔': 'ok', '◐': 'warn', '○': 'muted', '?': 'muted', '✖': 'error', '⚠': 'warn', '⊘': 'warn',
-  '◉': 'icon', 'Ⓠ': 'icon', '▸': 'key', '⛔': 'warn', '↳': 'icon', '»': 'muted', '·': 'muted', '⬢': 'icon', '⬡': 'muted'
+  '●': 'ok', '✔': 'ok', '◐': 'warn', '○': 'quiet', '?': 'quiet', '✖': 'error', '⚠': 'warn', '⊘': 'warn',
+  '◉': 'icon', 'Ⓠ': 'icon', '▸': 'brand', '⛔': 'warn', '↳': 'icon', '»': 'quiet', '·': 'quiet', '⬢': 'icon', '⬡': 'quiet', '▶': 'ask'
 };
 const KEYS = '(?:(?:Ctrl|Shift|Alt|Cmd|Option)\\+\\S+|Enter|Tab|Esc|Up|Down|Left|Right|Space|Backspace|PgUp|PgDn)';
 const TOKEN = new RegExp([
   '(https?:\\/\\/[^\\s)]+)', // 1 link
   '(\\bquox(?: (?![·])[^\\s·,;)]+)+)', // 2 a quox command
-  '((?<![\\w/])\\/[a-z][\\w-]*)', // 3 slash command
+  '((?<![\\w/])\\/[a-z][\\w-]*(?: (?:--?[a-z][\\w-]*|<[^>\\s]+>|\\[[^\\]\\s]+\\]|\\d+|[\\w-]+(?:\\|[\\w-]+)+))*)', // 3 slash command + its flags/args
   `((?<![\\w+])${KEYS}(?![\\w+]))`, // 4 keyboard key
   '((?<![\\w<])<[^>\\s]+>|\\[[^\\]\\s]+\\])', // 5 placeholder <name> or [args]
   '( · )', // 6 separator
   '((?<![\\w/.-])(?:(?:gpt|claude|gemini|o[134]|mistral|codestral|deepseek|sonar|grok)-[\\w.:-]*\\w|ollama:[\\w.:-]*\\w|OpenAI|openai|Anthropic|anthropic|Claude(?: API)?|Gemini|Ollama|ollama|Mistral|DeepSeek|Perplexity|Grok|xAI)(?![\\w-]))', // 7 provider/model
   '((?<![\\w.#-])\\d+(?:[.,:-]\\d+)*(?:%|ms|s|k|m|h|d|x|KB|MB|GB)?(?![\\w]))' // 8 number
 ].join('|'), 'g');
-const ROLE_OF = [null, 'link', 'code', 'key', 'key', 'muted', 'muted', 'provider', 'number'];
+const ROLE_OF = [null, 'id', 'command', 'command', 'command', 'command', 'quiet', 'provider', 'id'];
 const LETTER_KEY = /^([a-z])(?= (?:approve|deny|open|stop|peek|confirm|edit|retry|cancel|copy|quit)\b)/;
 
 /** Runs of `text` with roles; `base` colours the prose between tokens. Pure. */
@@ -211,6 +219,16 @@ export function paintRuns(text, base) {
   const s = String(text ?? '');
   let i = 0;
   const startsSeg = (at) => at === 0 || s.slice(0, at).endsWith(' · ') || /^\s*$/.test(s.slice(0, at));
+  if (/[⟦⟪]/.test(s)) { // explicit markup: `command` and «value» are atomic spans, the rest is auto-tokenised
+    let j = 0;
+    for (const m of s.matchAll(MARK)) {
+      for (const r of paintRuns(s.slice(j, m.index), base)) push(r.text, r.role);
+      push(m[1] ?? m[2], m[1] !== undefined ? 'command' : 'id');
+      j = m.index + m[0].length;
+    }
+    for (const r of paintRuns(s.slice(j), base)) push(r.text, r.role);
+    return out;
+  }
   for (const m of s.matchAll(TOKEN)) {
     proseRuns(s.slice(i, m.index), base, push, startsSeg(i));
     const g = m.findIndex((x, k) => k > 0 && x !== undefined);
@@ -222,32 +240,47 @@ export function paintRuns(text, base) {
 }
 function proseRuns(seg, base, push, segStart) {
   const k = segStart && seg.match(LETTER_KEY);
-  if (k) { push(k[1], 'key'); seg = seg.slice(1); }
+  if (k) { push(k[1], 'command'); seg = seg.slice(1); }
   push(seg, base);
 }
 
 /**
  * A note/list line as runs: a leading state glyph, then `Label  value` (two spaces) or `label: value`,
- * then tokens. tone: undefined/'dim' (neutral), 'ok', 'warn', 'accent', 'error'.
+ * then tokens. tone: undefined/'dim' (neutral), 'ok', 'warn', 'accent', 'error', 'ask' (a question for the human).
  */
 export function paintLine(text, tone) {
   const s = String(text ?? '');
   const out = [];
-  const neutral = !tone || tone === 'dim';
-  const prose = tone === 'warn' ? 'warn' : tone === 'error' || tone === 'fail' ? 'error' : tone === 'accent' ? 'sky' : null;
-  const m = s.match(/^(\s*)(?:([●✔◐○?✖⚠⊘◉Ⓠ▸⛔↳»·⬢⬡])( ))?(.*)$/u);
+  // The tone colours the GLYPH only. The sentence stays prose, so commands and values inside keep their roles.
+  const TONE_GLYPH = { warn: 'warn', error: 'error', fail: 'error', ok: 'ok', accent: 'brand', ask: 'ask' };
+  // [\s\S]* not .*: a notice can carry a newline (a server error body), and a failed match crashed the TUI
+  // ("m is not iterable", 2026-10-15 03:44 while the collector was down).
+  const m = s.match(/^(\s*)(?:([●✔◐○?✖⚠⊘◉Ⓠ▸⛔↳»·⬢⬡▶])( ))?([\s\S]*)$/u) || [s, '', undefined, undefined, s];
   const [, lead, glyph, gsp, rest0] = m;
   if (lead) out.push({ text: lead, role: undefined });
-  if (glyph) out.push({ text: glyph, role: tone === 'warn' && glyph !== '○' ? 'warn' : GLYPH_ROLE[glyph] }, { text: gsp, role: undefined });
+  if (glyph) out.push({ text: glyph, role: ['ok', 'warn', 'error'].includes(GLYPH_ROLE[glyph]) ? GLYPH_ROLE[glyph] : (TONE_GLYPH[tone] || GLYPH_ROLE[glyph]) }, { text: gsp, role: undefined });
   let rest = rest0;
+  if (tone === 'ask') { // QUOXON-ASK: "▶ reason. question? keys": the keys after the last "? " are the ask colour
+    const q = rest.lastIndexOf('? ');
+    if (q >= 0) { out.push(...paintRuns(rest.slice(0, q + 2), 'prose'), ...paintRuns(rest.slice(q + 2), 'ask')); return out; }
+    out.push(...paintRuns(rest, 'prose')); return out;
+  }
   const lv = rest.match(/^(\S[^·]{0,30}?\S|\S)( {2,})(\S.*)$/) || rest.match(/^([A-Za-z][\w .-]{0,22}:)( )(\S.*)$/);
-  let valueBase = prose || (tone === 'ok' && !glyph ? 'ok' : neutral && !lv && !glyph ? 'muted' : 'text');
+  const valueBase = 'prose';
   if (lv && !/^https?:/.test(lv[1])) {
     const pv = providerOf(lv[1].replace(/\s*\(.*\)$/, ''), null);
     out.push({ text: lv[1], role: pv ? `provider:${pv}` : 'label' }, { text: lv[2], role: undefined });
     rest = lv[3];
-    if (!prose) valueBase = 'value';
   }
   out.push(...paintRuns(rest, valueBase));
   return out;
 }
+
+/** The glyph a bare notice line gets so its tone shows without tinting the sentence. '' for neutral tones. */
+export const TONE_PREFIX = { warn: '⚠ ', error: '✖ ', fail: '✖ ', ok: '✔ ' };
+export const toneText = (text, tone) => {
+  const p = TONE_PREFIX[tone];
+  const t = String(text ?? '');
+  return p && !/^\s*[●✔◐○?✖⚠⊘◉Ⓠ▸⛔↳»·⬢⬡▶] /u.test(t) ? p + t : t;
+};
+export { stripMarks };