quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/gallery.js

@@ -0,0 +1,223 @@
+/**
+ * `quox motion`: the product version of the animation lab (~/quoxon-work/intro/lab). Plays every Q motion
+ * with a caption: Orbit & Lock, Portal, Particle collapse, the Dragon's Eye, the perpetual status Q in its
+ * four states, the hello, the composer ring and the reveal effects. No server, no account, nothing sent.
+ *
+ * Scenes are pure: galleryScenes() returns { id, title, caption, ms, frame(t) -> ANSI lines }. runGallery()
+ * is the only part that touches a terminal (cursor, timers, signals).
+ */
+import {
+  labSize, orbitCellsAt, portalCellsAt, particleCellsAt, eyeCellsAt, cellsToAnsi, qCells,
+  INTRO_MS, PORTAL_MS, EYE_MS, SKY, VIOLET, AMBER,
+} from './qart.js';
+import { qGlyph, glyphAnsi, GLYPH_STATES } from './qglyph.js';
+import { helloCells, helloAnsi, helloGradient, helloMs } from './qhello.js';
+
+const RESET = '\x1b[0m';
+const fg = (rgb) => `\x1b[38;2;${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v)))).join(';')}m`;
+const mix = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
+const DIM = [58, 66, 82], MUTED = [120, 132, 150], TXT = [226, 232, 240], TEAL = [6, 182, 212];
+const GREEN = [34, 197, 94], WHITE = [255, 255, 255];
+const paint = (s, rgb, mono) => (mono || !rgb ? s : fg(rgb) + s + RESET);
+
+// ---- composer ring (lab rules.mjs: the website's conic border as one light ring over the two rules) ------
+const PAL = { work: [SKY, VIOLET, TEAL], wait: [AMBER, [0xea, 0x58, 0x0c], [0xb4, 0x53, 0x09]] };
+const STOPS = [[0, 0, 0.85], [0.35, 1, 0.8], [0.6, 0, 0], [0.85, 2, 0.55], [1, 0, 0.85]];
+function ringAt(u, w) {
+  let i = 0; while (i < STOPS.length - 2 && u > STOPS[i + 1][0]) i++;
+  const [p0, c0, a0] = STOPS[i], [p1, c1, a1] = STOPS[i + 1], t = (u - p0) / (p1 - p0 || 1);
+  const col = (c) => mix(PAL.work[c], PAL.wait[c], w);
+  const A = a0 + (a1 - a0) * t;
+  const pm = mix(col(c0).map((v) => v * a0), col(c1).map((v) => v * a1), t);
+  return [A ? pm.map((v) => v / A) : col(c0), A];
+}
+const RING_SEG = [['idle', 0.8], ['work', 3.2], ['settle', 0.4], ['idle', 0.6], ['wait', 2.2], ['settle', 0.4]];
+export const RING_MS = RING_SEG.reduce((a, s) => a + s[1], 0) * 1000;
+/** Ring state at t ms, integrated at 60 Hz from 0 (deterministic). { angle, k, w, mode } */
+export function ringState(t) {
+  let angle = 0, k = 0, w = 0, mode = 'idle', settleFrom = { om: 144 }, om = 0, prev = 'idle';
+  const T = t / 1000, dt = 1 / 60;
+  for (let s = 0; s < T; s += dt) {
+    let acc = 0, si = 0;
+    while (si < RING_SEG.length - 1 && acc + RING_SEG[si][1] <= s) acc += RING_SEG[si++][1];
+    const [m, dur] = RING_SEG[si], p = clamp((s - acc) / dur);
+    if (m === 'settle' && prev !== 'settle') settleFrom = { om };
+    mode = m; prev = m;
+    let wt = 0;
+    if (m === 'work') { om = 144; k = Math.min(1, k + dt / 0.15); wt = 0; }
+    else if (m === 'wait') { om = 144 * 0.3; k = Math.min(1, k + dt / 0.15); wt = 1; }
+    else if (m === 'settle') { om = settleFrom.om * (1 - p) ** 2; k = 1 - p * p * (3 - 2 * p); wt = w; }
+    else { om = 0; k = 0; w = 0; }
+    if (m !== 'idle') w += (wt - w) * Math.min(1, dt / 0.2);
+    angle = (angle + om * dt) % 360;
+  }
+  return { angle, k, w, mode };
+}
+/** The two composer rules at ring state st, W columns wide. */
+export function ringLines(W, st, mono = false) {
+  const line = (top) => {
+    let s = '', last = '';
+    const base = top ? mix(DIM, SKY, 0.75) : DIM;
+    for (let x = 0; x < W; x++) {
+      let rgb = base;
+      if (st.k > 0) {
+        const pos = top ? (x + 0.5) / (2 * W) : (W + (W - 1 - x) + 0.5) / (2 * W);
+        const u = (((pos - st.angle / 360) % 1) + 1) % 1;
+        const [c, a] = ringAt(u, st.w);
+        rgb = mix(base, mix(DIM, c, a), st.k);
+      }
+      if (!mono) { const e = fg(rgb); if (e !== last) { s += e; last = e; } }
+      s += '─';
+    }
+    return s + (mono ? '' : RESET);
+  };
+  const label = { idle: 'idle', work: 'working', wait: 'waiting for approval', settle: 'done' }[st.mode];
+  return [line(true), paint('› ', SKY, mono) + paint('Ask Quox anything…', MUTED, mono), line(false), paint(`ring: ${label}`, MUTED, mono)];
+}
+
+// ---- reveal effects (lab fx.mjs, the reveals that ship in the client) ------------------------------------
+const decodeLine = (text, t, f, mono, perChar = 14) => helloAnsi(helloCells(text, t, { fg: f, mono, perChar }));
+/** fx at t ms: a tool row settles, an answer drops in, an approval card arms, a receipt seals, ProofFlow lights. */
+export function fxLines(t, W, mono = false) {
+  const out = [];
+  const at = (s) => t - s;
+  // tool row (0 ms): spinner while running, then a flash to ✔ and the result decodes in
+  const L = at(0), SETTLE = 900;
+  const head = L < SETTLE ? paint('◐◓◑◒'[Math.floor(t / 125) % 4], SKY, mono) : paint('✔', L < SETTLE + 120 ? WHITE : GREEN, mono);
+  out.push(head + decodeLine(' SEO │ summary │ ', L, (i, ch) => (ch === '│' ? DIM : i < 5 ? TEAL : MUTED), mono) + (L < SETTLE ? paint('…', MUTED, mono) : decodeLine('30 crawls · 2.4s', L - SETTLE, TXT, mono)));
+  out.push('');
+  // answer (1400 ms): lines drop in one by one, first chars decode, afterglow behind
+  const ans = ['Crawls finished with no blocking errors this week.', 'Impressions are up 8 percent; 3 pages moved into the top ten.'];
+  ans.forEach((ln, k) => { const s = at(1400 + k * 110); out.push(s < -140 ? '' : '  ' + decodeLine(ln.slice(0, W - 4), s, TXT, mono, 6)); });
+  out.push('');
+  // approval card (2600 ms): amber rule draws in, title decodes, 300 ms arming, then ready
+  const A = at(2600), iw = Math.min(W - 4, 50), draw = clamp(A / 250), n = Math.round(draw * (iw + 2));
+  const rule = (a, b) => (A <= 0 ? '' : paint([...(a + '─'.repeat(iw) + b)].slice(0, n).join(''), AMBER, mono));
+  out.push(rule('╭', '╮'));
+  const armed = clamp((A - 400) / 300), ready = A >= 700;
+  out.push(A > 100 ? paint('│ ', AMBER, mono) + decodeLine('Send the weekly SEO report?', A - 100, TXT, mono) : '');
+  out.push(A > 100 ? paint('│ ', AMBER, mono) + paint('[ Approve ]', ready ? AMBER : DIM, mono) + '  ' + paint('[ Deny ]', ready ? MUTED : DIM, mono) + '  ' + paint(ready ? 'ready ' : 'arming', ready ? GREEN : AMBER, mono) + ' ' + paint([...'▰▰▰▰▰▰'].map((c, i) => (ready || i < Math.floor(armed * 6) ? '▰' : '▱')).join(''), ready ? GREEN : AMBER, mono) : '');
+  out.push(rule('╰', '╯'));
+  out.push('');
+  // receipt seal (3800 ms): text resolves, the seal settles with a one-frame glint
+  const R = at(3800), seq = ['·', '○', '◌', '◎'];
+  const seal = R < 0 ? ' ' : R < 400 ? paint(seq[Math.floor(R / 70) % 4], mix(DIM, TEAL, clamp(R / 400)), mono) : paint('◉', R < 460 ? WHITE : TEAL, mono);
+  out.push(R < -140 ? '' : seal + decodeLine(' WARD │ witnessed · seq 393', R, (i, ch) => (ch === '│' ? DIM : i < 5 ? TEAL : TXT), mono));
+  // ProofFlow (4600 ms): AEE > AOCL > TOOL > WARD light up in sequence; completed ones stay still
+  const P = at(4600);
+  out.push(P < 0 ? '' : paint('proof  ', MUTED, mono) + ['AEE', 'AOCL', 'TOOL', 'WARD'].map((nm, i) => { const d = P - i * 120; return paint(nm, d < 0 ? DIM : d < 100 ? WHITE : SKY, mono); }).join(paint(' ─▸ ', mix(DIM, SKY, 0.8), mono)));
+  out.push('');
+  // closing line (5400 ms)
+  const C = at(5400);
+  out.push(C < -140 ? '' : decodeLine('Thought for 12s · 1.4k tokens · $0.02', C, (i, ch) => (ch === '·' ? DIM : MUTED), mono));
+  return out;
+}
+export const FX_MS = 6600;
+
+// ---- scenes ------------------------------------------------------------------------------------------------
+const STATE_WORD = { resting: 'Ready', working: 'Thinking…', waiting: 'Waiting for approval', failing: 'Failed' };
+const STATE_TAG = { resting: 'resting: slow breathing glow', working: 'working: the gradient flows through it', waiting: 'waiting: amber pulse', failing: 'failing: a red flash, then steady red' };
+const STATE_RGB = { resting: SKY, working: SKY, waiting: AMBER, failing: [239, 68, 68] };
+export const PERP_MS = 2600;
+
+/**
+ * The gallery's scenes for a terminal. narrow forces the 40-column layout (the compact particle Q).
+ * Each scene: { id, title, caption, ms, frame(t, { mono }) -> string[] }.
+ */
+export function galleryScenes({ cols = 100, rows = 30, narrow = false } = {}) {
+  const W = narrow ? 40 : cols;
+  const size = narrow ? 'small' : labSize(W, rows);
+  const big = size === 'small' ? 'small' : size;
+  const art = (cells) => cellsToAnsi(cells);
+  const hello = "Hi, I'm Quox.";
+  return [
+    { id: 'orbit', title: 'Orbit & Lock', caption: size === 'small' ? 'the compact Q: particles circle, then collapse into the mark (the intro under 60 columns)' : 'particles swirl on a ring with trailing drag, then lock into the Q in an angular wave; horns grow out, the tail sweeps in last (the intro)', ms: INTRO_MS + 300,
+      frame: (t, o) => art(orbitCellsAt(big, t, { color: !o.mono })) },
+    { id: 'portal', title: 'Portal', caption: 'a ring spins edge-on and opens; the Q fills in from the opening, the tail sweeps in last', ms: PORTAL_MS + 600,
+      frame: (t, o) => art(portalCellsAt(big, t, { color: !o.mono })) },
+    { id: 'particle', title: 'Particle collapse', caption: 'density rises on a circle, then collapses into the compact Q', ms: 1100 + 500,
+      frame: (t, o) => art(particleCellsAt('small', t, { color: !o.mono })) },
+    { id: 'eye', title: "The Dragon's Eye", caption: 'a slit-pupil eye opens in the bowl, blinks once, and dissolves back into the Q (/eye; rarely on launch)', ms: EYE_MS + 500,
+      frame: (t, o) => art(eyeCellsAt(big, t, { color: !o.mono })) },
+    { id: 'hello', title: 'Hello', caption: 'the Q locks, then says hello: the line decodes in from katakana with a short afterglow', ms: INTRO_MS + helloMs(hello) + 600,
+      frame: (t, o) => {
+        const q = art(t < INTRO_MS ? orbitCellsAt(big, t, { color: !o.mono }) : qCells(big, { color: !o.mono }));
+        const line = helloAnsi(helloCells(hello, t - INTRO_MS, { fg: helloGradient(hello), mono: o.mono }));
+        if (W < 60) return [...q, '', line];
+        const mid = Math.floor(q.length / 2);
+        return q.map((l, i) => (i === mid ? l + '  ' + line : l));
+      } },
+    { id: 'perpetual', title: 'The perpetual Q', caption: 'the status glyph carries state in colour alone, one fixed shape: resting breathes, working flows sky to violet to teal, waiting pulses amber, failing flashes red', ms: PERP_MS * 4,
+      frame: (t, o) => {
+        const i = Math.min(3, Math.floor(t / PERP_MS)), st = GLYPH_STATES[i], tt = t - i * PERP_MS;
+        return GLYPH_STATES.map((s, k) => {
+          const g = qGlyph(s, k === i ? tt : 0, { mono: o.mono, quiet: k !== i, since: 0 });
+          const word = paint(STATE_WORD[s], k === i ? STATE_RGB[s] : DIM, o.mono);
+          const tag = W >= 70 ? '   ' + paint(STATE_TAG[s], k === i ? MUTED : DIM, o.mono) : '';
+          return (k === i ? '› ' : '  ') + glyphAnsi(g) + ' ' + word + tag;
+        }).concat(['', '  ' + paint(`now: ${st}`, MUTED, o.mono)]);
+      } },
+    { id: 'ring', title: 'The composer ring', caption: 'the two composer rules become one light ring while Quox works; amber while it waits for you', ms: RING_MS,
+      frame: (t, o) => ringLines(Math.min(W - 2, 72), ringState(t), o.mono) },
+    { id: 'fx', title: 'Reveal effects', caption: 'tool row, answer drop-in, approval arming, receipt seal, ProofFlow, closing line', ms: FX_MS,
+      frame: (t, o) => fxLines(t, Math.min(W - 2, 78), o.mono) },
+  ];
+}
+export const SCENE_IDS = ['orbit', 'portal', 'particle', 'eye', 'hello', 'perpetual', 'ring', 'fx'];
+
+// ---- runner (the only impure part) ---------------------------------------------------------------------------
+const visible = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');  // eslint-disable-line no-control-regex
+const width = (s) => [...visible(s)].length;
+
+/** One full screen for a scene frame: title + caption on top, the frame centred under it. */
+export function screenFor(scene, t, { cols, mono, index, total }) {
+  const lines = scene.frame(t, { mono });
+  const head = paint(`[${index + 1}/${total}] ${scene.title}`, SKY, mono);
+  const cap = wrap(scene.caption, Math.max(20, cols - 2)).map((l) => paint(l, MUTED, mono));
+  const w = Math.max(0, ...lines.map(width));
+  const left = ' '.repeat(Math.max(0, Math.floor((cols - w) / 2)));
+  return [head, ...cap, '', ...lines.map((l) => left + l)];
+}
+function wrap(s, n) { const o = []; let l = ''; for (const w of s.split(' ')) { if ((l + ' ' + w).trim().length > n) { o.push(l); l = w; } else l = (l + ' ' + w).trim(); } if (l) o.push(l); return o; }
+
+export async function runGallery({ out = process.stdout, env = process.env, only = [], narrow = false, slow = false, mono: monoFlag = false } = {}) {
+  const cols = narrow ? 40 : Math.max(40, out.columns || 100), rows = out.rows || 30;
+  const mono = monoFlag || Boolean(env.NO_COLOR) || env.TERM === 'dumb';
+  const still = env.QUOX_REDUCED_MOTION === '1' || !out.isTTY;
+  const all = galleryScenes({ cols, rows, narrow });
+  const bad = only.filter((n) => !SCENE_IDS.includes(n));
+  if (bad.length) throw new Error(`unknown motion: ${bad.join(', ')} (one of ${SCENE_IDS.join(', ')})`);
+  const scenes = only.length ? all.filter((s) => only.includes(s.id)) : all;
+  if (still) {
+    // Reduced motion or piped: every scene's settled frame, printed once.
+    scenes.forEach((s, i) => out.write(screenFor(s, s.ms, { cols, mono, index: i, total: scenes.length }).join('\n') + '\n\n'));
+    return;
+  }
+  const SLOW = slow ? 3 : 1;
+  let restored = false;
+  const restore = () => { if (!restored) { restored = true; out.write(RESET + '\x1b[?25h\n'); } };
+  const onSig = () => { restore(); process.exit(130); };
+  process.once('SIGINT', onSig); process.once('SIGTERM', onSig);
+  out.write('\x1b[?25l');
+  try {
+    for (let i = 0; i < scenes.length; i++) {
+      const s = scenes[i];
+      out.write('\x1b[2J\x1b[H');
+      const t0 = performance.now();
+      for (let n = 0; ; n++) {
+        const t = (performance.now() - t0) / SLOW;
+        const done = t >= s.ms;
+        const lines = screenFor(s, done ? s.ms : t, { cols, mono, index: i, total: scenes.length });
+        out.write('\x1b[?2026h\x1b[H' + lines.map((l) => l + '\x1b[K').join('\n') + '\x1b[J\x1b[?2026l');
+        if (done) break;
+        const wait = t0 + (n + 1) * (1000 / 30) - performance.now();
+        if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+      }
+      await new Promise((r) => setTimeout(r, 700 * SLOW));
+    }
+  } finally {
+    process.off('SIGINT', onSig); process.off('SIGTERM', onSig);
+    restore();
+  }
+}

package/lib/quoxon/indicator.js

@@ -0,0 +1,193 @@
+/**
+ * Perpetual status indicator model (CLI-QUOX): a one-cell Q whose COLOUR carries state.
+ *   resting  dim sky, slow breathing        working  sky <-> violet shimmer (katakana rain beside it)
+ *   waiting  amber pulse (needs approval)   failing  red, static
+ * The glyph is Ⓠ (U+24C0, the documented Quox stand-in): compared in xterm.js against `◖Q`, `Q` and `◖Q◗`
+ * it was the only one that reads as a Q at a glance in every colour; the bare Q is lost beside text and
+ * the half-circle forms look like a bullet. Pure functions, tick t advances every 120 ms.
+ */
+export const Q_GLYPH = 'Ⓠ';
+export const STATES = ['resting', 'working', 'waiting', 'failing'];
+const SKY = [56, 189, 248], VIOLET = [168, 85, 247], AMBER = [245, 158, 11], RED = [239, 68, 68];
+const mix = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+const tri = (t, period) => { const k = (t % period) / period; return k < 0.5 ? k * 2 : 2 - k * 2; };
+
+/** working / waiting / failing from what the app knows; Working is only mounted while a turn runs. */
+export function indicatorState(activity, failing = false) {
+  if (failing) return 'failing';
+  if (/^waiting for approval/i.test(String(activity || ''))) return 'waiting';
+  return 'working';
+}
+
+/** rgb for the Q at tick t. quiet (reduced motion) freezes the animation at a representative colour. */
+export function qColor(state, t = 0, quiet = false) {
+  switch (state) {
+    case 'resting': return mix([40, 70, 90], SKY, quiet ? 0.5 : 0.25 + 0.5 * tri(t, 20));
+    case 'waiting': return mix([120, 76, 6], AMBER, quiet ? 1 : 0.3 + 0.7 * tri(t, 10));
+    case 'failing': return RED;
+    default: return mix(SKY, VIOLET, quiet ? 0.5 : tri(t, 16));
+  }
+}
+
+/** The word shown for a state when the activity text is not the whole story. */
+export function stateWord(state, activity) {
+  if (state === 'failing') return 'Failed';
+  if (state === 'resting') return 'Ready';
+  const a = String(activity || '').replace(/[.…\s]+$/u, '');
+  return !a || a === 'Working' ? 'Thinking' : a;
+}
+
+/** 842 -> "842", 1234 -> "1.2k", 12400 -> "12k". */
+export function fmtTokens(n) {
+  n = Math.max(0, Math.round(Number(n) || 0));
+  if (n < 1000) return String(n);
+  const k = n / 1000;
+  return k < 10 ? `${k.toFixed(1).replace(/\.0$/, '')}k` : `${Math.round(k)}k`;
+}
+
+/** USD for the closing line: undefined (omit) when absent, zero or not a number; never invented. */
+export function fmtCost(usd) {
+  const v = Number(usd);
+  if (!Number.isFinite(v) || v <= 0) return null;
+  return `$${v < 0.01 ? v.toFixed(4) : v.toFixed(2)}`;
+}
+
+/**
+ * Normalise a server usage object. Real numbers only: { tokens, cost } with null for anything missing.
+ * tokens = output tokens (what streamed back); falls back to input+output only when no split is given.
+ */
+export function normUsage(u, doneCost) {
+  const o = (u && typeof u === 'object') ? u : {};
+  const out = o.output_tokens ?? o.completion_tokens;
+  const inp = o.input_tokens ?? o.prompt_tokens;
+  const total = o.total_tokens;
+  const tokens = Number.isFinite(Number(out)) && out != null ? Number(out)
+    : Number.isFinite(Number(total)) && total != null ? Number(total)
+    : Number.isFinite(Number(inp)) && inp != null ? Number(inp) : null;
+  const cost = Number(o.cost_usd ?? doneCost);
+  return { tokens, cost: Number.isFinite(cost) && cost > 0 ? cost : null, real: tokens != null };
+}
+
+/** Live token figure: the real number once the server reported it, else an estimate from received text (~chars/4). */
+export function turnTokens(turn) {
+  if (!turn) return 0;
+  if (turn.usage?.real) return turn.usage.tokens;
+  return Math.ceil((turn.chars || 0) / 4);
+}
+
+/**
+ * Glyphs that stand in for letters while the word "decrypts" (owner 2026-10-12: far more variety). Half-width
+ * katakana only: one cell each, the width of a Latin letter, so the word never jitters. 42 of them: the whole
+ * U+FF66..U+FF9D block minus forms that read as a Latin letter, digit, bracket or bare box/stroke in DejaVu
+ * Sans Mono fallback (ｪｴ like I/E, ｭｮﾕﾖ boxes, ﾆ "=", ﾉ "/", ﾌ "7", ﾍ "^", ﾘ "U", ﾚ "L", ﾛ a box, ｰ a dash)
+ * and the voiced marks ﾞ ﾟ.
+ */
+export const SCRAMBLE_GLYPHS = 'ｦｧｨｩｫｬｯｱｲｳｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾇﾈﾊﾋﾎﾏﾐﾑﾒﾓﾔﾗﾙﾜﾝ';
+
+/** Deterministic hash in [0,1). */
+const hsh = (a, b, c = 0) => { let x = (a * 374761393 + b * 668265263 + c * 2147483647) | 0; x = Math.imul(x ^ (x >>> 13), 1274126177); return ((x ^ (x >>> 16)) >>> 0) / 4294967296; };
+
+/** Per-cell flicker period (ms), 60..180, so cells never pulse in lockstep. */
+export const cellPeriod = (i, seed = 0) => 60 + Math.floor(hsh(i, 911, seed) * 121);
+export const SCRAMBLE_CHANCE = 0.5; // x mean cascade 3/5 of an episode -> ~30% of letters scrambled at any time
+const EPISODE = 5;                  // an episode is 5 flicker periods: a cascade of 2..4 glyphs, then the letter
+const FLASH_MS = 90;                 // one frame of bright flash when a cell resolves
+
+/**
+ * Glyph for cell i in flicker bucket k. Even and odd buckets draw from disjoint halves of the set, so a cell
+ * never shows the same glyph twice in a row.
+ */
+export function cellGlyph(i, k, seed = 0) {
+  const half = Math.floor(SCRAMBLE_GLYPHS.length / 2);
+  const odd = ((k % 2) + 2) % 2;
+  return SCRAMBLE_GLYPHS[odd * half + Math.floor(hsh(i, k, seed) * half)];
+}
+
+/**
+ * The activity word at time `now` (ms): "Matrix rain through the word". Pure. Returns [{ ch, glyph, flash }].
+ *   decode-in: a word that just changed (at `since`) resolves left to right over DECODE_MS (unresolved = glyph)
+ *   steady:    each letter runs its own clock (cellPeriod); per episode of 4 periods it is either plain or
+ *              cascades through 2..4 different glyphs and resolves with one bright flash frame
+ * Spaces are never scrambled; every cell is one column, so the width never changes.
+ */
+export function wordFrame(word, now, { since = -Infinity, seed = 0 } = {}) {
+  const chars = [...String(word)];
+  const letters = chars.filter(ch => ch.trim()).length;
+  let li = -1;
+  return chars.map((ch, i) => {
+    if (!ch.trim()) return { ch, glyph: false, flash: false };
+    li++;
+    const P = cellPeriod(i, seed), phase = Math.floor(hsh(i, 313, seed) * P * EPISODE);
+    const tt = now + phase, k = Math.floor(tt / P);
+    const decodeAt = since + ((li + 1) / letters) * DECODE_MS;
+    if (now < decodeAt) return { ch: cellGlyph(i, k, seed), glyph: true, flash: false };
+    if (now - decodeAt < FLASH_MS) return { ch, glyph: false, flash: true }; // resolve flash on decode-in too
+    if (now < since + DECODE_MS + 200) return { ch, glyph: false, flash: false }; // a fresh word reads cleanly first
+    const E = Math.floor(k / EPISODE), pos = k - E * EPISODE;
+    const cascade = (e) => (hsh(i, e, seed + 17) < SCRAMBLE_CHANCE ? 2 + Math.floor(hsh(i, e, seed + 29) * 3) : 0);
+    const m = cascade(E);
+    if (pos < m) return { ch: cellGlyph(i, k, seed), glyph: true, flash: false };
+    const resolvedAt = (E * EPISODE + m) * P;
+    if (m > 0 && pos === m && tt - resolvedAt < Math.min(P, FLASH_MS)) return { ch, glyph: false, flash: true };
+    return { ch, glyph: false, flash: false };
+  });
+}
+
+/** Gradient stops per state for the coloured word (same families as the composer ring). */
+export const WORD_PALETTES = {
+  working: [SKY, VIOLET, [6, 182, 212]],
+  writing: [[34, 197, 94], [74, 222, 128], [20, 184, 166]],
+  waiting: [AMBER, [234, 88, 12], [251, 191, 36]],
+  failing: [RED, RED, RED],
+};
+/**
+ * Colour of a word cell: one gradient sweeping across the word over time (~1.6 s per pass). Resolved letters
+ * are slightly brighter than glyphs; a flash is near white. quiet (reduced motion) freezes the sweep.
+ */
+export function wordColor(state, i, n, now, kind = 'letter', quiet = false) {
+  const pal = WORD_PALETTES[state] || WORD_PALETTES.working;
+  const u = ((((n > 1 ? i / (n - 1) : 0) * 0.65 - (quiet ? 0 : now / 1600)) % 1) + 1) % 1;
+  const x = u * pal.length, a = Math.floor(x) % pal.length, b = (a + 1) % pal.length;
+  const base = mix(pal[a], pal[b], x - Math.floor(x));
+  if (kind === 'flash') return mix(base, [255, 255, 255], 0.7);
+  if (kind === 'glyph') return mix(base, [30, 36, 48], 0.28);
+  return mix(base, [255, 255, 255], 0.12);
+}
+
+/**
+ * Previous model (kept for the drop-in reveal and existing callers): one frame with a random 30-45% of the
+ * letter positions scrambled. Returns [{ ch, glyph }]. rand is injectable for tests.
+ */
+export function scrambleFrame(word, rand = Math.random) {
+  const chars = [...String(word)];
+  const idx = chars.map((c, i) => (c.trim() ? i : -1)).filter((i) => i >= 0);
+  const chosen = new Set();
+  if (idx.length > 1) {
+    const k = Math.min(idx.length - 1, Math.max(1, Math.round(idx.length * (0.3 + 0.15 * rand()))));
+    const pool = [...idx];
+    while (chosen.size < k) chosen.add(pool.splice(Math.floor(rand() * pool.length), 1)[0]);
+  }
+  return chars.map((ch, i) => (chosen.has(i) ? { ch: SCRAMBLE_GLYPHS[Math.floor(rand() * SCRAMBLE_GLYPHS.length)], glyph: true } : { ch, glyph: false }));
+}
+/** Shimmer colour for the glyph at position i, tick t (sky to violet). */
+export const glyphColor = (i, t) => mix(SKY, VIOLET, tri(t + i * 2, 16));
+
+export const DECODE_MS = 300;
+/**
+ * A word that just changed decodes in: letters resolve left to right over DECODE_MS. Unresolved positions
+ * are always glyphs; resolved ones follow the normal 30-45% scramble. progress 0..1 (>=1 = steady state).
+ */
+export function decodeFrame(word, progress, rand = Math.random) {
+  const base = scrambleFrame(word, rand);
+  if (progress >= 1) return base;
+  const n = base.filter((g) => g.ch.trim()).length;
+  let seen = 0;
+  const revealed = Math.floor(clamp01(progress) * n);
+  return base.map((g) => {
+    if (!g.ch.trim()) return g;
+    const i = seen++;
+    if (i < revealed) return g;
+    return g.glyph ? g : { ch: SCRAMBLE_GLYPHS[Math.floor(rand() * SCRAMBLE_GLYPHS.length)], glyph: true };
+  });
+}
+const clamp01 = (x) => Math.max(0, Math.min(1, x));

package/lib/quoxon/intent.js

@@ -0,0 +1,41 @@
+/**
+ * Local intent hints. When a message is plainly a client command in words, the turn is NOT intercepted
+ * (the model still answers); the client only prints one dim `tip: /command` line above the answer.
+ * Exact, anchored patterns on the whole message: anything with extra words is ordinary chat.
+ */
+const WORD = '([A-Za-z0-9][\\w.-]{0,39})';
+// Questions answered by a local panel (/context, /cost, /status): the panel prints above the answer.
+const PANELS = [
+  [/^(?:how much (?:of (?:the|my|our) )?context (?:have (?:we|i) used|has been used|is (?:used|left)|are we using|am i using|do (?:we|i) have left)|what(?:'s| is) (?:the|my|our) context(?: usage)?|context usage)$/i, '/context'],
+  [/^(?:what(?:'s| is) (?:this|it) costing(?: (?:me|us))?|how much (?:has|did) (?:this|it) cost(?: (?:me|us))?(?: so far)?|how much (?:have (?:i|we)|am i|are we) spen(?:t|ding)(?: so far)?|what(?:'s| is| has been) (?:the|my|our) (?:cost|spend|usage)(?: so far)?)$/i, '/cost'],
+  [/^(?:what(?:'s| is) my status|what(?:'s| is) the status|show (?:me )?my status|status)$/i, '/status']
+];
+function PANEL_RULES() { return PANELS.map(([re, cmd]) => [re, () => cmd]); }
+
+const RULES = [
+  [new RegExp(`^attach(?: me)?(?: to)? ${WORD}$`, 'i'), (m) => `/attach ${m[1]}`],
+  [/^rename (?:this|the|my) (?:session|conversation|chat) (?:to|as) ([\w.-]+(?: [\w.-]+){0,2})$/i, (m) => m[1].split(' ').some(w => /^(and|then|but|so|please)$/i.test(w)) ? null : `/rename ${m[1]}`],
+  [/^(?:what(?:'s| is) running|what is running now)$/i, () => '/roster'],
+  [/^(?:show|list|open) (?:my |the )?(?:pending )?approvals$/i, () => '/approvals'],
+  [/^(?:what(?:'s| is)|show me what(?:'s| is)) (?:waiting|pending) (?:for )?(?:my )?approval$/i, () => '/approvals'],
+  [/^detach(?: from (?:the )?agent)?$/i, () => '/detach'],
+  [/^(?:start )?(?:a )?new conversation$/i, () => '/new'],
+  [/^(?:please )?(?:compact|summari[sz]e and compact|compress) (?:this|the|our|my) (?:conversation|chat|session|context)(?: please)?$/i, () => '/compact'],
+  ...PANEL_RULES()
+];
+
+/** -> `tip: /attach seer` or null. */
+export function intentHint(text) {
+  const t = String(text || '').trim().replace(/[.?!]+$/, '').trim();
+  if (!t || t.includes('\n') || t.startsWith('/')) return null;
+  for (const [re, fmt] of RULES) { const m = re.exec(t); const r = m && fmt(m); if (r) return `tip: ${r}`; }
+  return null;
+}
+
+/** -> '/context' | '/cost' | '/status' when the message asks a question a local panel answers, else null. */
+export function intentPanel(text) {
+  const t = String(text || '').trim().replace(/[.?!]+$/, '').trim();
+  if (!t || t.includes('\n') || t.startsWith('/')) return null;
+  for (const [re, cmd] of PANELS) if (re.test(t)) return cmd;
+  return null;
+}

package/lib/quoxon/keys.js

@@ -0,0 +1,121 @@
+/**
+ * Raw stdin tokeniser for the QUOXON composer. We own input parsing (instead of
+ * Ink's useInput) because we need bracketed paste, Shift+Enter, Ctrl+_ and a
+ * paste-burst heuristic, none of which Ink 6 exposes.
+ *
+ * parseChunk(chunk, state) -> { events, state }
+ * Events: { type: 'text', text } | { type: 'paste', text } | { type: 'key', name, ctrl?, alt? } | { type: 'focus', focused }
+ */
+
+export const PASTE_ON = '\x1b[?2004h';
+export const PASTE_OFF = '\x1b[?2004l';
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+
+export const initialKeyState = () => ({ inPaste: false, pasteBuf: '', partial: '' });
+/** Time after which a dangling paste start / partial marker is flushed (app owns the timer). */
+export const PASTE_DANGLING_MS = 1500;
+/** Non-bracketed input arriving within this many ms of the previous chunk is a paste burst. */
+export const BURST_MS = 20;
+
+/** True when the key state holds something a timer must eventually flush. */
+export const hasDangling = (st) => Boolean(st?.inPaste || st?.partial);
+
+/**
+ * Flush a dangling paste start or half marker after a timeout. Buffered paste text becomes a PASTE
+ * event (inserted, never submitted); a half marker is dropped. Never produces Enter.
+ */
+export function flushDangling(state) {
+  const events = [];
+  if (state?.inPaste && state.pasteBuf) {
+    let t = state.pasteBuf;
+    for (let n = Math.min(PASTE_END.length - 1, t.length); n > 0; n--) { if (t.endsWith(PASTE_END.slice(0, n))) { t = t.slice(0, -n); break; } }
+    if (t) events.push({ type: 'paste', text: t });
+  }
+  return { events, state: initialKeyState() };
+}
+
+const CSI_KEYS = {
+  '\x1b[A': 'up', '\x1b[B': 'down', '\x1b[C': 'right', '\x1b[D': 'left',
+  '\x1bOA': 'up', '\x1bOB': 'down', '\x1bOC': 'right', '\x1bOD': 'left',
+  '\x1b[H': 'home', '\x1b[F': 'end', '\x1bOH': 'home', '\x1bOF': 'end',
+  '\x1b[1~': 'home', '\x1b[4~': 'end', '\x1b[7~': 'home', '\x1b[8~': 'end',
+  '\x1b[3~': 'delete', '\x1b[Z': 'shift-tab',
+  '\x1b[13;2u': 'shift-enter', '\x1b[27;2;13~': 'shift-enter', '\x1b\r': 'shift-enter', '\x1b\n': 'shift-enter',
+  '\x1b[1;5D': 'word-left', '\x1b[1;5C': 'word-right', '\x1b[1;3D': 'word-left', '\x1b[1;3C': 'word-right'
+};
+const CSI_LIST = Object.keys(CSI_KEYS).sort((a, b) => b.length - a.length);
+
+const CTRL = {
+  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g',
+  '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x15': 'kill-line', '\x17': 'delete-word',
+  '\x1f': 'undo', '\x19': 'redo', '\x0a': 'newline', '\x7f': 'backspace', '\x08': 'backspace',
+  '\r': 'enter', '\t': 'tab', '\x02': 'left', '\x06': 'right'
+};
+
+export function parseChunk(chunk, state = initialKeyState()) {
+  const events = [];
+  let s = String(chunk);
+  let st = { partial: '', ...state };
+  if (st.partial) { s = st.partial + s; st.partial = ''; }
+
+  while (s.length) {
+    if (st.inPaste) {
+      // search the joined buffer so an end marker split across chunks is still found
+      const buf = st.pasteBuf + s;
+      const end = buf.indexOf(PASTE_END);
+      if (end === -1) { st.pasteBuf = buf; s = ''; break; }
+      events.push({ type: 'paste', text: buf.slice(0, end) });
+      st = { inPaste: false, pasteBuf: '', partial: '' };
+      s = buf.slice(end + PASTE_END.length);
+      continue;
+    }
+    if (s.startsWith(PASTE_START)) { st = { inPaste: true, pasteBuf: '', partial: '' }; s = s.slice(PASTE_START.length); continue; }
+    // a half-received start marker (ESC [ 2 0 ...): hold it for the next chunk, never read it as Esc + text
+    if (s.length >= 2 && s.length < PASTE_START.length && PASTE_START.startsWith(s)) { st.partial = s; s = ''; break; }
+    if (s === '\x1b') { events.push({ type: 'key', name: 'escape' }); s = ''; continue; }
+    if (s[0] === '\x1b') {
+      // Focus reporting (CSI ?1004h, enabled by sound/index.js): CSI I = focus in, CSI O = focus out.
+      if (s.startsWith('\x1b[I') || s.startsWith('\x1b[O')) { events.push({ type: 'focus', focused: s[2] === 'I' }); s = s.slice(3); continue; }
+      const hit = CSI_LIST.find(k => s.startsWith(k));
+      if (hit) { events.push({ type: 'key', name: CSI_KEYS[hit] }); s = s.slice(hit.length); continue; }
+      // Unknown escape sequence: swallow ESC [ ... final byte, or a bare ESC+char (alt-x).
+      const m = /^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(s) || /^\x1bO./.exec(s);
+      if (m) { s = s.slice(m[0].length); continue; }
+      if (s.length >= 2) { events.push({ type: 'key', name: 'escape' }); s = s.slice(1); continue; }
+    }
+    // Plain run: printable text up to the next control char.
+    // Burst heuristic: text plus newlines delivered in ONE chunk, with content after
+    // the first newline, is a paste (terminal without bracketed paste), not typing.
+    const run = /^[^\x00-\x1f\x7f]+/.exec(s);
+    if (run) { events.push({ type: 'text', text: run[0] }); s = s.slice(run[0].length); continue; }
+    const c = s[0];
+    if (CTRL[c]) { events.push({ type: 'key', name: CTRL[c] }); }
+    s = s.slice(1);
+  }
+  return { events: coalesceBurst(events), state: st };
+}
+
+/**
+ * If a chunk produced text and then an Enter/newline FOLLOWED by more text, it is
+ * a non-bracketed paste: fold it into one paste event. A trailing single Enter
+ * (text then Enter at the end) stays as text + enter so fast typing still submits.
+ */
+function coalesceBurst(events) {
+  const hasInner = events.some((e, i) =>
+    e.type === 'key' && (e.name === 'enter' || e.name === 'newline') && i > 0 && i < events.length - 1 &&
+    events.slice(i + 1).some(x => x.type === 'text'));
+  if (!hasInner) return events;
+  let text = '';
+  const rest = [];
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i];
+    if (e.type === 'text') text += e.text;
+    else if (e.type === 'key' && (e.name === 'enter' || e.name === 'newline')) {
+      // a trailing Enter after the burst is a submit, not part of the paste
+      if (i === events.length - 1) rest.push(e); else text += '\n';
+    } else if (e.type === 'key' && e.name === 'tab') text += '\t';
+    else rest.push(e);
+  }
+  return [{ type: 'paste', text }, ...rest];
+}