quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/modelPrefs.js

@@ -0,0 +1,345 @@
+/**
+ * QUOXON-FW6: model favourites and the default model. Pure helpers plus one quiet live-list reader.
+ *
+ * The preference is { favourites: [{ provider, model }], default: { provider, model } | null }.
+ * `provider` is a /model provider id (openai, anthropic, claude-cli, ollama, a compat preset).
+ * Persistence is the caller's (api.modelPrefs / api.setModelPrefs: the user's server-side
+ * preferences, with the profile as a cache). There is no model list in this file: ids come from
+ * the provider's own live list (liveModels) or from what the user typed. A typed id that is not on
+ * the live list is kept with a warning, never refused.
+ */
+import { CHOICES, CLAUDE_FAMILIES, providerId } from './model.js';
+
+export const MAX_FAVS = 20;
+const nameOf = (id) => CHOICES.find((c) => c.id === id)?.name || id;
+
+const cleanOne = (v) => {
+  const provider = providerId(v?.provider);
+  const model = typeof v?.model === 'string' ? v.model.trim().slice(0, 200) : '';
+  return provider && model && !/\s/.test(model) ? { provider, model } : null;
+};
+export const sameModel = (a, b) =>
+  Boolean(a && b) && a.provider === b.provider && a.model === b.model;
+
+/** Anything stored or received -> a clean prefs object (bad rows dropped, duplicates removed). */
+export function normPrefs(v) {
+  const favs = [];
+  for (const f of Array.isArray(v?.favourites) ? v.favourites : []) {
+    const c = cleanOne(f);
+    if (c && !favs.some((x) => sameModel(x, c)) && favs.length < MAX_FAVS) favs.push(c);
+  }
+  return { favourites: favs, default: cleanOne(v?.default) };
+}
+
+export const label = (m) => `${m.provider} ${m.model}`;
+
+/** -> { prefs, added, text, tone }. */
+export function addFav(prefs, provider, model) {
+  const c = cleanOne({ provider, model });
+  if (!c)
+    return { prefs, added: false, text: 'Usage: /model fav add <provider> <model>', tone: 'warn' };
+  const at = prefs.favourites.findIndex((f) => sameModel(f, c));
+  if (at >= 0)
+    return {
+      prefs,
+      added: false,
+      text: `${label(c)} is already favourite ${at + 1}.`,
+      tone: 'plain',
+    };
+  if (prefs.favourites.length >= MAX_FAVS)
+    return {
+      prefs,
+      added: false,
+      text: `You have ${MAX_FAVS} favourites already. /model fav rm <n> makes room.`,
+      tone: 'warn',
+    };
+  const next = { ...prefs, favourites: [...prefs.favourites, c] };
+  const n = next.favourites.length;
+  return {
+    prefs: next,
+    added: true,
+    text: `Added ${label(c)} as favourite ${n}. /model ${n} switches to it.`,
+    tone: 'ok',
+  };
+}
+
+/**
+ * ref = a 1-based number, or a model id (exact, "provider model", "provider/model", or a
+ * unique substring).
+ */
+export function rmFav(prefs, ref) {
+  const q = String(ref ?? '')
+    .trim()
+    .toLowerCase();
+  const favs = prefs.favourites;
+  if (!q) return { prefs, removed: null, text: 'Usage: /model fav rm <n|model>', tone: 'warn' };
+  let idx = -1;
+  if (/^\d+$/.test(q)) idx = Number(q) - 1;
+  else {
+    const exact = favs
+      .map((f, i) => i)
+      .filter(
+        (i) =>
+          favs[i].model.toLowerCase() === q ||
+          label(favs[i]).toLowerCase() === q ||
+          `${favs[i].provider}/${favs[i].model}`.toLowerCase() === q,
+      );
+    const part = favs.map((f, i) => i).filter((i) => favs[i].model.toLowerCase().includes(q));
+    const hits = exact.length ? exact : part;
+    if (hits.length > 1)
+      return {
+        prefs,
+        removed: null,
+        text:
+          `"${ref}" matches ${hits.map((i) => `${i + 1} ${label(favs[i])}`).join(', ')}. ` +
+          'Use the number.',
+        tone: 'warn',
+      };
+    idx = hits.length ? hits[0] : -1;
+  }
+  if (idx < 0 || idx >= favs.length)
+    return {
+      prefs,
+      removed: null,
+      text: favs.length
+        ? `No favourite "${ref}". /model fav lists them.`
+        : 'You have no favourites yet. /model fav add <provider> <model>',
+      tone: 'warn',
+    };
+  const removed = favs[idx];
+  return {
+    prefs: { ...prefs, favourites: favs.filter((_, i) => i !== idx) },
+    removed,
+    text: `Removed ${label(removed)}. The numbers after it moved up by one.`,
+    tone: 'ok',
+  };
+}
+
+export function setDefault(prefs, provider, model) {
+  const c = cleanOne({ provider, model });
+  if (!c)
+    return { prefs, ok: false, text: 'Usage: /model default <provider> <model>', tone: 'warn' };
+  return {
+    prefs: { ...prefs, default: c },
+    ok: true,
+    text:
+      `Default model: ${label(c)}. New sessions start on it when ${nameOf(c.provider)} is ` +
+      `connected. /model ${label(c)} uses it now.`,
+    tone: 'ok',
+  };
+}
+export const clearDefault = (prefs) => ({
+  prefs: { ...prefs, default: null },
+  text: 'Default model cleared. New sessions use the last choice, else the server policy.',
+  tone: 'ok',
+});
+
+/** Toggle one model in the favourites -> { prefs, added }. */
+export function toggleFav(prefs, m) {
+  const i = prefs.favourites.findIndex((f) => sameModel(f, m));
+  if (i >= 0)
+    return {
+      prefs: { ...prefs, favourites: prefs.favourites.filter((_, k) => k !== i) },
+      added: false,
+    };
+  return {
+    prefs: {
+      ...prefs,
+      favourites: [...prefs.favourites, { provider: m.provider, model: m.model }].slice(
+        0,
+        MAX_FAVS,
+      ),
+    },
+    added: true,
+  };
+}
+
+/** /model fav lines. `current` = the stored choice ({ provider, model?, via? }) or null. */
+export function favLines(prefs, currentKey = null) {
+  if (!prefs.favourites.length)
+    return [
+      [
+        'No favourites yet. Add one: /model fav add <provider> <model> ' +
+          '(or open /model and press f)',
+      ],
+    ];
+  const out = [['Favourite models (/model <n> switches):']];
+  prefs.favourites.forEach((f, i) => {
+    const marks = [
+      currentKey && sameModel(f, currentKey) ? 'current' : null,
+      prefs.default && sameModel(f, prefs.default) ? 'default' : null,
+    ].filter(Boolean);
+    out.push([`  ${i + 1}  ${label(f)}${marks.length ? `  (${marks.join(', ')})` : ''}`, 'plain']);
+  });
+  out.push([
+    prefs.default
+      ? `Default: ${label(prefs.default)}`
+      : 'No default model set. /model default <provider> <model>',
+  ]);
+  return out;
+}
+
+const FAV_WORDS = new Set(['fav', 'favs', 'favourite', 'favourites', 'favorite', 'favorites']);
+const SUBS_ONE = { list: 'list', status: 'list' };
+
+/**
+ * The words after /model -> what to do. kinds: chooser list use fav-list fav-add fav-rm
+ * default-show default-set default-clear error pass.
+ */
+export function parseModelSub(arg) {
+  const w = String(arg || '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!w.length) return { kind: 'chooser' };
+  const first = w[0].toLowerCase();
+  if (SUBS_ONE[first] && w.length === 1) return { kind: SUBS_ONE[first] };
+  if (/^\d+$/.test(first) && w.length === 1) return { kind: 'use', n: Number(first) };
+  if (FAV_WORDS.has(first)) {
+    const sub = (w[1] || '').toLowerCase();
+    if (!sub) return { kind: 'fav-list' };
+    if (/^\d+$/.test(sub) && w.length === 2) return { kind: 'use', n: Number(sub) };
+    if (sub === 'add') {
+      if (w.length !== 4)
+        return {
+          kind: 'error',
+          text:
+            'Usage: /model fav add <provider> <model>   ' +
+            'e.g. /model fav add openai gpt-5.6-terra',
+        };
+      return { kind: 'fav-add', provider: w[2], model: w[3] };
+    }
+    if (['rm', 'remove', 'del', 'delete'].includes(sub))
+      return w.length < 3
+        ? { kind: 'error', text: 'Usage: /model fav rm <n|model>' }
+        : { kind: 'fav-rm', ref: w.slice(2).join(' ') };
+    return {
+      kind: 'error',
+      text: 'Usage: /model fav [add <provider> <model> | rm <n|model> | <n>]',
+    };
+  }
+  if (first === 'default') {
+    if (w.length === 1) return { kind: 'default-show' };
+    if (w.length === 2 && ['clear', 'none', 'off', 'unset'].includes(w[1].toLowerCase()))
+      return { kind: 'default-clear' };
+    if (w.length === 3) return { kind: 'default-set', provider: w[1], model: w[2] };
+    return { kind: 'error', text: 'Usage: /model default [<provider> <model> | clear]' };
+  }
+  return { kind: 'pass' };
+}
+
+/**
+ * A provider's list response (the shape differs per provider) -> ids, newest first as the
+ * server gave them.
+ */
+export function idsOf(choiceId, res) {
+  if (choiceId === 'claude-cli') return [...CLAUDE_FAMILIES];
+  if (!res?.ok || !Array.isArray(res.models)) return [];
+  const raw =
+    choiceId === 'ollama'
+      ? res.models.map((m) => (typeof m === 'string' ? m : m?.name))
+      : res.models.map((m) => (typeof m === 'string' ? m : m?.id));
+  return raw.filter((x) => typeof x === 'string' && x);
+}
+
+/**
+ * The live model ids for one provider, never throws. -> { ok, ids, def }. ok=false means
+ * "could not list" (the caller decides how quiet to be); ids is [] then.
+ */
+export async function liveModels(api, id, { refresh = false } = {}) {
+  try {
+    if (id === 'claude-cli') return { ok: true, ids: [...CLAUDE_FAMILIES], def: null };
+    const row = CHOICES.find((c) => c.id === id);
+    if (!row) return { ok: false, ids: [], def: null };
+    let res = null;
+    if (id === 'ollama') res = await api.ollamaModels?.();
+    else if (row.compat) res = await api.compatModels?.(id);
+    else if (row.discover)
+      res = await api.providerModels?.(row.provider, refresh ? { refresh: true } : undefined);
+    if (!res?.ok) return { ok: false, ids: [], def: null };
+    return { ok: true, ids: idsOf(id, res), def: res.default_model || null };
+  } catch {
+    return { ok: false, ids: [], def: null };
+  }
+}
+
+/**
+ * Typed id vs the live list -> { model, known: true|false|null, note? }. null = no list to
+ * check against.
+ */
+export function checkModelId(ids, typed, providerName = '') {
+  if (!ids?.length) return { model: typed, known: null };
+  if (ids.includes(typed)) return { model: typed, known: true };
+  const ci =
+    ids.find((i) => i.toLowerCase() === typed.toLowerCase()) ||
+    ids.find((i) => i === `${typed}:latest`);
+  if (ci) return { model: ci, known: true };
+  return {
+    model: typed,
+    known: false,
+    note:
+      `${typed} is not on ${providerName || 'the provider'}'s live list right now; ` +
+      'kept as typed in case it is new.',
+  };
+}
+
+/* ---- the /model chooser ---------------------------------------------------------- */
+
+/**
+ * Selectable items, in display order: favourites first (numbered by their place in the full
+ * list; ones on a provider that is not connected are left out), then each connected provider's
+ * models.
+ * groups: [{ id, name, ids, note? }] for CONNECTED providers only.
+ */
+export function chooserItems(prefs, groups) {
+  const connected = new Set(groups.map((g) => g.id));
+  const items = [];
+  prefs.favourites.forEach((f, i) => {
+    if (connected.has(f.provider))
+      items.push({ kind: 'fav', n: i + 1, provider: f.provider, model: f.model });
+  });
+  for (const g of groups) {
+    if (!g.ids.length)
+      items.push({
+        kind: 'provider',
+        provider: g.id,
+        model: null,
+        name: g.name,
+        note: g.note || 'no model list; the server picks',
+      });
+    else
+      for (const id of g.ids)
+        items.push({ kind: 'model', provider: g.id, model: id, name: g.name });
+  }
+  return items;
+}
+
+/**
+ * One picker row ({ key, text, note? }) for an item. `current` = { provider, model } of the
+ * stored choice, or null.
+ */
+export function chooserRow(item, prefs, current) {
+  if (item.kind === 'provider')
+    return { key: item.provider, text: item.name, note: item.note, dim: false };
+  const here = current && current.model ? sameModel(current, item) : false;
+  const marks = [
+    here ? 'current' : null,
+    prefs.default && sameModel(prefs.default, item) ? 'default' : null,
+    item.kind === 'model' && prefs.favourites.some((f) => sameModel(f, item)) ? '★' : null,
+  ].filter(Boolean);
+  const body = item.kind === 'fav' ? label(item) : item.model;
+  return {
+    key: item.kind === 'fav' ? `★ ${item.n}` : item.provider,
+    text: body + (marks.length ? `   ${marks.join(' · ')}` : ''),
+  };
+}
+
+/**
+ * The stored choice as { provider: <CHOICES id>, model } for marking; null when it carries no
+ * model.
+ */
+export function currentKey(choice, idOf) {
+  if (!choice?.model) return null;
+  const provider = idOf(choice);
+  return provider ? { provider, model: choice.model } : null;
+}

package/lib/quoxon/motion/clock.js

@@ -6,6 +6,7 @@
  *
  * Demand shapes: { every: ms } (repeat while declared) or { at: epochMs } (one wake at that time).
  */
+import { normaliseLevel } from './level.js';
 export const FRAME_MS = 83; // ~12 fps for anything that moves
 export const SECOND_MS = 1000;
 
@@ -49,8 +50,8 @@ export class Clock {
   get armed() { return this.id != null; }
 }
 
-/** Motion is decoration: off under QUOX_REDUCED_MOTION=1, QUOX_TUI_LITE, or when not on a real terminal. Colour is separate (NO_COLOR). */
-export const reducedMotion = (env = process.env) => env.QUOX_REDUCED_MOTION === '1' || Boolean(env.QUOX_TUI_LITE);
+/** Motion is decoration: off at the quiet level (QUOX_MOTION=quiet, QUOX_REDUCED_MOTION=1, QUOX_TUI_LITE), or when not on a real terminal. Colour is separate (NO_COLOR). */
+export const reducedMotion = (env = process.env) => env.QUOX_REDUCED_MOTION === '1' || Boolean(env.QUOX_TUI_LITE) || normaliseLevel(env.QUOX_MOTION) === 'quiet';
 export const motionAllowed = (isTTY, env = process.env) => Boolean(isTTY) && !reducedMotion(env);
 
 /**

package/lib/quoxon/motion/level.js

@@ -0,0 +1,91 @@
+/**
+ * Motion levels (CLI-QUOX F3). One setting, four steps, chosen in /config or with QUOX_MOTION:
+ *
+ *   quiet       static except the elapsed timer (the old "reduced motion"; QUOX_REDUCED_MOTION=1 still means it)
+ *   calm        the default: exactly what shipped before levels (Orbit & Lock, the status Q, reveals, the ring)
+ *   expressive  calm, plus a short ignition glow when a tool row starts and a handoff dot while delegating
+ *   cinematic   expressive, plus the dragon: it greets you after Orbit & Lock on every launch, and plays a mood
+ *               for approvals (wide eyes, amber glint), success (a wink) and failure (a puff of smoke)
+ *
+ * Pure: no process access except through the env argument, no timers. The frame helpers return cells
+ * { ch, rgb } like every other motion module, so the terminal and the web draw them the same way.
+ */
+export const LEVELS = ['quiet', 'calm', 'expressive', 'cinematic'];
+export const DEFAULT_LEVEL = 'calm';
+
+/** A saved or typed value -> a level, or null. The pre-levels values map across: full = calm, reduced = quiet. */
+export function normaliseLevel(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  if (s === 'full') return 'calm';
+  if (s === 'reduced') return 'quiet';
+  return LEVELS.includes(s) ? s : null;
+}
+
+/** The level in force. QUOX_REDUCED_MOTION=1 and QUOX_TUI_LITE always mean quiet (accessibility wins). */
+export function motionLevel(env = process.env) {
+  if (env.QUOX_REDUCED_MOTION === '1' || env.QUOX_TUI_LITE) return 'quiet';
+  return normaliseLevel(env.QUOX_MOTION) || DEFAULT_LEVEL;
+}
+
+export const atLeast = (level, min) => LEVELS.indexOf(normaliseLevel(level) || DEFAULT_LEVEL) >= LEVELS.indexOf(min);
+
+/** What each level turns on. launchEgg: the rare dragon greeting on launch (cinematic greets every time instead). */
+export function levelFeatures(level) {
+  const l = normaliseLevel(level) || DEFAULT_LEVEL;
+  return {
+    animate: l !== 'quiet',
+    ignition: atLeast(l, 'expressive'),
+    handoff: atLeast(l, 'expressive'),
+    introDragon: l === 'cinematic',
+    moods: l === 'cinematic',
+    launchEgg: l === 'calm' || l === 'expressive',
+  };
+}
+
+const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
+
+// ---- tool-row ignition glow --------------------------------------------------------------------------------
+export const IGNITION_MS = 700;
+/** Glow 0..1 at ms since a tool row started running: up in 80 ms, then an eased fall to 0 at IGNITION_MS. */
+export function ignitionGlow(age) {
+  if (!(age > 0) || age >= IGNITION_MS) return 0;
+  if (age <= 80) return age / 80;
+  const u = (age - 80) / (IGNITION_MS - 80);
+  return (1 - u) ** 2;
+}
+
+// ---- handoff dot -------------------------------------------------------------------------------------------
+export const HANDOFF_MS = 900;
+const SKY = [56, 189, 248], VIOLET = [168, 85, 247], DIM = [58, 66, 82];
+const mix = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+/**
+ * The handoff track at t ms: n cells, a bright dot travelling from Quox (left) to the agent it is handing to
+ * (right) once every HANDOFF_MS, with one fading cell behind it. The dot shifts sky to violet as it goes.
+ * still: the dot rests at the target (reduced motion never calls this, but a frozen frame must read right).
+ */
+export function handoffFrame(t, n = 6, { mono = false, still = false } = {}) {
+  const u = still ? 0.999 : (((t % HANDOFF_MS) + HANDOFF_MS) % HANDOFF_MS) / HANDOFF_MS;
+  const at = Math.min(n - 1, Math.floor(u * n));
+  return Array.from({ length: n }, (_, i) => {
+    const pos = n > 1 ? i / (n - 1) : 1;
+    if (i === at) return { ch: '●', rgb: mono ? null : mix(SKY, VIOLET, pos) };
+    if (i === at - 1 && !still) return { ch: '•', rgb: mono ? null : mix(DIM, mix(SKY, VIOLET, pos), 0.55) };
+    return { ch: '·', rgb: mono ? null : mix(DIM, SKY, 0.25 * clamp(pos)) };
+  });
+}
+
+// ---- dragon moods (cinematic) ------------------------------------------------------------------------------
+const FAILED_TURN = new Set(['failed', 'unconfirmed']); // the same reading as the sound earcons (sound/mapping.js)
+/**
+ * prevState + action + nextState -> the mood the dragon should play, or null. Only accepted state CHANGES
+ * count: an approval card appearing (waiting), a running turn finishing (success / failure). An interrupted
+ * turn is the human pressing Esc: no reaction.
+ */
+export function moodForEvent(prev, action, next) {
+  if (!prev || !action || !next) return null;
+  if ((next.approvals?.length || 0) > (prev.approvals?.length || 0)) return 'waiting';
+  if (action.type !== 'event' || action.ev?.type !== 'turn.finished' || !prev.turn) return null;
+  const status = action.ev.status || 'completed';
+  if (FAILED_TURN.has(status)) return 'failure';
+  return status === 'completed' ? 'success' : null;
+}

package/lib/quoxon/mouse.js

@@ -0,0 +1,211 @@
+/**
+ * QUOXON-MOUSE (owner 2026-10-15: "when I click on '◆ QLOOP-ENGINE' enter /say [slot]", "select a chunk of text I
+ * typed and delete it"). Optional, OFF by default: mouse tracking makes the terminal send clicks to Quox, so
+ * selecting or copying text then needs Shift+drag in most terminals (said when it is turned on).
+ *
+ * Pure parts only (the app wires them):
+ * - MOUSE_ON / MOUSE_OFF: SGR button tracking with drag (1000 + 1002 + 1006). Never any-motion (1003).
+ * - createScreenMirror: what Ink has put on the screen, as plain lines. Fed every string Ink writes (term.js), it
+ *   models exactly Ink's output: text, newlines, eraseLines (frame repaints) and clear-terminal. The live frame is
+ *   the last write; everything above it is static history. Wrapping is applied at the current width when read, so
+ *   a resize reflows it the way the terminal does.
+ * - screenHit: a click's screen row -> the mirror line under it. Rows are counted up from the cursor (which Ink
+ *   always leaves on the line after the frame), read with a cursor position report (DSR) at click time, so the
+ *   map holds whether the frame sits at the bottom of a full screen or halfway down a fresh one.
+ * - classifyClick: what that line is (a ◆ sender, a card's answer key label, the shared ask's y/N/c).
+ * - composerIndexAt: a click in the composer rows -> a buffer index, through Ink's word wrap.
+ */
+import { graphemes, composerFrom } from './textBuffer.js';
+
+export const MOUSE_ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+export const MOUSE_OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+export const DSR = '\x1b[6n';
+/** Two presses on the same cell within this window are a double-click. */
+export const DOUBLE_MS = 400;
+/** How long a click waits for the terminal's cursor report before it is dropped. */
+export const DSR_TIMEOUT_MS = 400;
+
+export function mouseOnNote() {
+  return 'Mouse on. Click a ◆ sender to reply, click a card\'s y / n / c to answer, click or drag in your draft to place the cursor or select (Backspace deletes, typing replaces, double-click selects a word). While it is on your terminal sends clicks and the wheel to Quox: hold Shift to select or copy text (Option on macOS Terminal and iTerm2), and use Shift+wheel or the scrollbar to scroll back. /mouse off returns all of it.';
+}
+
+// ---- cell widths --------------------------------------------------------------------------------
+const WIDE = /\p{Extended_Pictographic}/u;
+const EAW = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/u;
+/** Terminal cells one grapheme takes: 2 for emoji presentation and East Asian wide, else 1. */
+export function cellWidth(g) {
+  const cp = g.codePointAt(0);
+  if (EAW.test(g)) return 2;
+  if (WIDE.test(g) && (cp >= 0x1f000 || g.includes('️'))) return 2;
+  return 1;
+}
+const cellsOf = (s) => graphemes(String(s)).reduce((n, x) => n + cellWidth(x.text), 0);
+/** Grapheme index in `gs` covering 0-based cell `col` (gs.length when past the end). */
+function cellToIndex(gs, col) {
+  let at = 0;
+  for (let i = 0; i < gs.length; i++) { const w = cellWidth(gs[i].text); if (col < at + w) return i; at += w; }
+  return gs.length;
+}
+/** 1-based start cell of grapheme index `i`. */
+function indexToCell(gs, i) { let at = 1; for (let k = 0; k < i && k < gs.length; k++) at += cellWidth(gs[k].text); return at; }
+
+// ---- screen mirror ------------------------------------------------------------------------------
+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/;
+
+/** Wrap one plain line into rows of at most `cols` cells (what the terminal shows). */
+function wrapRows(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;
+}
+
+export function createScreenMirror({ columns = () => null, cap = 3000 } = {}) {
+  let lines = ['']; // logical lines; the last one is the cursor line
+  let frameLen = 0; // logical lines written by the last write (the live frame, once Ink has written it)
+  const append = (text) => {
+    const parts = text.replace(ANSI_RE, '').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 parts.length - 1;
+  };
+  const m = {
+    /** One string Ink wrote, before any diffing. */
+    write(chunk) {
+      let s = String(chunk);
+      const clear = s.search(CLEAR_RE);
+      if (clear >= 0) {
+        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 = ['']; frameLen = 0;
+      }
+      const e = ERASE_RE.exec(s);
+      if (e) {
+        const n = (e[1].match(/\x1b\[2K/g) || []).length;
+        const drop = Math.min(n - 1, lines.length - 1);
+        lines.length -= drop;
+        lines[lines.length - 1] = '';
+        s = s.slice(e[1].length);
+      }
+      const plain = s.replace(ANSI_RE, '');
+      if (!plain) return;
+      const rows = append(s);
+      if (rows > 0) frameLen = rows;
+    },
+    /** Test helper: Ink repainting its frame as these lines. */
+    frame(fl) { m.write(`\x1b[2K\x1b[G${fl.join('\n')}\n`); },
+    /** Raw output we cannot place (a hand-over, a child on the terminal): forget what is above. */
+    reset() { lines = ['']; frameLen = 0; },
+    /** -> { rows, frameStart, staticRows, frameRows }: wrapped at the current width, cursor line excluded. */
+    snapshot() {
+      const cols = columns();
+      const body = lines.slice(0, -1);
+      const fl = Math.min(frameLen, body.length);
+      const stat = body.slice(0, body.length - fl).flatMap(l => wrapRows(l, cols));
+      const fr = body.slice(body.length - fl).flatMap(l => wrapRows(l, cols));
+      return { rows: [...stat, ...fr], frameStart: stat.length, staticRows: stat, frameRows: fr };
+    }
+  };
+  return m;
+}
+
+/** A click at 1-based (x, y) with the cursor on screen row `cursorRow` -> the line under it, or null. */
+export function screenHit(snap, cursorRow, x, y) {
+  if (!snap || !(cursorRow > 0)) return null;
+  const idx = snap.rows.length - (cursorRow - y);
+  if (y >= cursorRow || idx < 0 || idx >= snap.rows.length) return null;
+  return {
+    text: snap.rows[idx], col: x, inFrame: idx >= snap.frameStart,
+    frameRow: idx - snap.frameStart, frameLines: snap.rows.slice(snap.frameStart), rowsBelow: snap.rows.slice(idx + 1)
+  };
+}
+
+// ---- what was clicked ---------------------------------------------------------------------------
+const SENDER_RE = /^\s*◆ (\S+)( \(no reply address\))?/;
+const CARD_KEY_RE = /(?<![\w/])([ync]) (approve|deny|chat|yes)(?![\w])/g;
+const ASK_KEYS_RE = /(?<![\w/])(y|run)\/(N)\/(c)\s*$/;
+const isAskRow = (r) => /^\s*▶ /.test(r) && (ASK_KEYS_RE.test(r) || /\b[ync] (approve|deny|chat)\b/.test(r));
+
+/**
+ * -> { kind: 'sender', slot, who? } | { kind: 'key', key: 'y'|'n'|'c'|'run', source: 'approval'|'ask' } | null.
+ * A key needs the click ON its label. A card's labels count only in the live frame (a card is never answered from
+ * scrollback); an ask's y/N/c only when no newer ask sits below it on screen.
+ */
+export function classifyClick(hit) {
+  if (!hit || typeof hit.text !== 'string') return null;
+  const t = hit.text;
+  const gs = graphemes(t);
+  const s = SENDER_RE.exec(t);
+  if (s) return s[2] ? { kind: 'sender', slot: null, who: s[1] } : { kind: 'sender', slot: s[1].toLowerCase() };
+  const within = (from, len) => {
+    const gi = graphemes(t.slice(0, from)).length;
+    const a = indexToCell(gs, gi); const b = a + cellsOf(t.slice(from, from + len));
+    return hit.col >= a && hit.col < b;
+  };
+  if (hit.inFrame) {
+    CARD_KEY_RE.lastIndex = 0;
+    let m;
+    while ((m = CARD_KEY_RE.exec(t))) if (within(m.index, m[0].length)) return { kind: 'key', key: m[1], source: 'approval' };
+  }
+  const k = ASK_KEYS_RE.exec(t);
+  if (k && /^\s*▶ /.test(t)) {
+    if ((hit.rowsBelow || []).some(isAskRow)) return null;
+    const base = k.index + k[0].indexOf(k[1]);
+    const yPos = base, nPos = yPos + k[1].length + 1, cPos = nPos + 2;
+    if (within(yPos, k[1].length)) return { kind: 'key', key: k[1] === 'run' ? 'run' : 'y', source: 'ask' };
+    if (within(nPos, 1)) return { kind: 'key', key: 'n', source: 'ask' };
+    if (within(cPos, 1)) return { kind: 'key', key: 'c', source: 'ask' };
+  }
+  return null;
+}
+
+// ---- the composer -------------------------------------------------------------------------------
+const isRule = (r) => /^\s*─/.test(r || '');
+const isPrompt = (r) => /^› /.test(r || '') || r === '›';
+
+/**
+ * A click on frame row `row` (0-based), 1-based column `col` -> the buffer index under it, or null when the row is
+ * not one of the composer's. The composer is the "› " row right under a rule, down to the next rule.
+ */
+export function composerIndexAt(frameLines, row, col, buf) {
+  let top = -1;
+  for (let i = frameLines.length - 1; i >= 1; i--) if (isPrompt(frameLines[i]) && isRule(frameLines[i - 1])) { top = i; break; }
+  if (top < 0 || row < top) return null;
+  let bottom = top;
+  while (bottom < frameLines.length && !isRule(frameLines[bottom])) bottom++;
+  if (row >= bottom) return null;
+  if (!buf.text) return 0;
+  const lines = buf.text.split('\n');
+  const starts = []; { let o = 0; for (const l of lines) { starts.push(o); o += l.length + 1; } }
+  const from = composerFrom(buf);
+  let r = top;
+  for (let li = from; li < lines.length && r < bottom; li++) {
+    const T = graphemes(lines[li]);
+    let p = 0; let first = true;
+    const rest = () => T.slice(p).some(g => !/\s/.test(g.text)); // trailing spaces never take a row of their own
+    while (r < bottom && (first || rest())) {
+      const R = graphemes(String(frameLines[r]).replace(/\s+$/, '')).slice(2);
+      while (!first && p < T.length && /\s/.test(T[p].text) && R.length && !/\s/.test(R[0].text)) p++;
+      const take = Math.min(R.length, T.length - p);
+      if (r === row) {
+        const gi = Math.min(T.length, p + Math.min(cellToIndex(R, Math.max(0, col - 3)), take));
+        return starts[li] + (gi < T.length ? T[gi].index : lines[li].length);
+      }
+      p += Math.max(take, 0); r++; first = false;
+      if (take <= 0) break;
+    }
+  }
+  return buf.text.length;
+}
+