quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/print.js

@@ -0,0 +1,94 @@
+/**
+ * Headless mode: `quox --print "<prompt>"` sends one turn and exits.
+ * (-p is --profile across quox, so print has no short flag.)
+ * Exit codes: 0 completed, 2 held for approval, 3 interrupted, 4 auth, 5 unconfirmed
+ * (stream closed without turn.finished), 1 other.
+ */
+import { textGate } from './events.js';
+import { streamFields, fallbackNote } from './model.js';
+import { connectOfferFor } from './connect.js';
+
+export const EXIT = { ok: 0, error: 1, approval: 2, interrupted: 3, auth: 4, unconfirmed: 5 };
+
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) return '';
+  let s = '';
+  stream.setEncoding?.('utf8');
+  for await (const chunk of stream) s += chunk;
+  return s;
+}
+
+/** Resolve the prompt: arg wins; absent or "-" reads stdin. */
+export async function resolvePrompt(arg, stdin) {
+  if (arg && arg !== '-') return arg;
+  return (await readStdin(stdin)).replace(/\n+$/, '');
+}
+
+const isAuth = (e) => e?.status === 401 || /valid jwt|service key|unauthor|not authenticated/i.test(e?.message || '');
+const newTurnId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** Runs one turn. out/err are write(string) sinks. Returns the exit code. */
+export async function runPrint({ api, prompt, output = 'text', conversation = null, turnId = newTurnId(), timeoutS = 0, color = false, stopGraceMs = 8000, context = undefined, choice = null, promptProfile = undefined, out, err }) {
+  if (!prompt || !prompt.trim()) { err('quox: empty prompt (pass --print "<prompt>" or pipe it on stdin)\n'); return EXIT.error; }
+  const ctrl = new AbortController();
+  let abandoned = false, graceTimer = null;
+  // A timeout asks the SERVER to stop; only if it cannot (or does not answer in the grace) do we abandon the
+  // local stream, and then we say "abandoned", never "interrupted": the server may still finish the turn.
+  const requestStop = async () => {
+    let r = { ok: false };
+    try { if (api.interrupt) r = await api.interrupt(convo, turnId); } catch { r = { ok: false }; }
+    if (r?.ok) graceTimer = setTimeout(() => { abandoned = true; ctrl.abort(); }, stopGraceMs);
+    else { abandoned = true; ctrl.abort(); }
+  };
+  const timer = timeoutS > 0 ? setTimeout(requestStop, timeoutS * 1000) : null;
+  const t0 = Date.now();
+  const sum = { tools: 0, approvals: 0, receipts: [] };
+  let convo = conversation, doneSession = null, status = null, text = '', sawApproval = false, errorMsg = null, authFail = false;
+  const seen = new Set();
+  let offer = null;
+  let gate = null;
+  try {
+    for await (const ev of api.stream({ turnId, message: prompt, agent: 'quox', conversationId: conversation, context, ...streamFields(choice), ...(promptProfile ? { promptProfile } : {}) }, ctrl.signal)) {
+      if (output === 'json') out(JSON.stringify(ev) + '\n');
+      const fb = fallbackNote(choice, ev);
+      if (fb) err(`quox: ${fb}\n`);
+      if (!offer) offer = connectOfferFor(ev);
+      if (ev.conversation_id) convo = ev.conversation_id;
+      if (ev.session_id) doneSession = ev.session_id; // the server's real id: v1 events only echo the request
+      if (ev.type === 'chunk' || ev.type === 'text.delta' || ev.type === 'turn.started') { const g = textGate(gate, ev); gate = g.st; if (g.append) text += ev.content; }
+      else if (ev.type === 'done' && !text && ev.full_response) text = ev.full_response;
+      else if (ev.type === 'tool.started' && !seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; }
+      else if (ev.type === 'tool.finished') { if (!seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; } if (ev.receipt?.ward_seq != null) sum.receipts.push(ev.receipt.ward_seq); }
+      else if (ev.type === 'approval.requested') { sawApproval = true; sum.approvals++; }
+      else if (ev.type === 'approval.resolved') sawApproval = false;
+      else if (ev.type === 'turn.finished') status = ev.status || 'completed';
+      else if (ev.type === 'error') errorMsg = ev.error || 'stream error';
+    }
+  } catch (e) {
+    if (ctrl.signal.aborted) { status = 'abandoned'; errorMsg = `timed out after ${timeoutS}s; the server was not confirmed stopped`; }
+    else { authFail = isAuth(e); errorMsg = e?.message || String(e); }
+  } finally { if (timer) clearTimeout(timer); clearTimeout(graceTimer); }
+  if (ctrl.signal.aborted && !status) { status = 'abandoned'; errorMsg = errorMsg || `timed out after ${timeoutS}s; the server was not confirmed stopped`; }
+  if (doneSession) convo = doneSession;
+  const serverStopped = abandoned && status === 'abandoned' ? false : status === 'interrupted' ? true : null;
+
+  let code;
+  if (authFail) code = EXIT.auth;
+  else if (sawApproval && status !== 'interrupted' && status !== 'abandoned') { status = status === 'completed' || !status ? 'held_for_approval' : status; code = EXIT.approval; }
+  else if (status === 'completed' && !errorMsg) code = EXIT.ok;
+  else if (status === 'interrupted' || status === 'abandoned') code = EXIT.interrupted;
+  else if (sawApproval) { status = status || 'held_for_approval'; code = EXIT.approval; }
+  else if (!status && !errorMsg) { status = 'unconfirmed'; code = EXIT.unconfirmed; }
+  else code = EXIT.error;
+  if (!status) status = authFail ? 'auth' : 'failed';
+
+  if (output === 'json') {
+    out(JSON.stringify({ type: 'summary', status, turn_id: turnId, conversation_id: convo, duration_ms: Date.now() - t0, server_stopped: serverStopped, ...sum }) + '\n');
+  } else if (text) out(text.endsWith('\n') ? text : text + '\n');
+  if (authFail) err(`Not signed in for chat. Run: quox login -p <profile>\n`);
+  else if (code === EXIT.approval) err('Held for approval: approve it in the dashboard or with `quox` /approvals.\n');
+  else if (code === EXIT.unconfirmed) err('quox: Ended without confirmation from the server\n');
+  else if (errorMsg) err(`quox: ${errorMsg}\n`);
+  if (offer && code !== EXIT.ok) err(`${offer}\n`);
+  return code;
+}

package/lib/quoxon/qart.js

@@ -0,0 +1,379 @@
+/**
+ * The horned Q as Braille art, and every motion the owner reviewed in the lab (~/quoxon-work/intro/lab):
+ * Orbit & Lock (the intro), Portal, Particle collapse, and the Dragon's Eye. CLI-QUOX.
+ *
+ * PURE AND PORTABLE on purpose: no Ink, no process, no timers, no terminal APIs. Inputs are size, progress
+ * (or ms), state and seed; the core output is rows of cells `{ ch, rgb }` (rgb null = default colour). The
+ * same module renders in the terminal (cellsToAnsi) and in a browser (web/qface.js), which is how the Q
+ * becomes the face of the app on cli.quox.ai as well as in the CLI.
+ *
+ * The Q is rasterised from a small vector description (ring bowl, tapered tail, two curved horns) at the
+ * dot resolution of the target size, so every size has a smooth bowl instead of a scaled bitmap. Each dot
+ * knows which part it belongs to (bowl, tail, horn) and how far along that part it sits, which is what the
+ * tail sweep, the horn glint and the portal reveal key off.
+ */
+
+export const SKY = [56, 189, 248];
+export const VIOLET = [168, 85, 247];
+export const AMBER = [245, 158, 11];
+export const RED = [239, 68, 68];
+const TAU = Math.PI * 2;
+const ASPECT = 0.82; // silhouette width / height, in square dots
+
+// size -> dot height. A Braille cell is 2 dots wide and 4 tall, so rows = H / 4.
+// small is the lab's compact particle Q (under 60 cols); large/mid are the intro sizes.
+export const SIZES = { large: 72, mid: 44, small: 24 };
+
+/** Pick the Q size for a terminal. Under 60 cols the caller uses the half-block compact Q instead. */
+export function qSize(cols, rows) {
+  if (cols < 60) return 'compact';
+  return cols >= 100 && rows >= 30 ? 'large' : 'mid';
+}
+
+/** Lab parity sizing: under 60 cols (or under 12 rows) the lab's compact particle Q, never a half-block. */
+export function labSize(cols, rows) {
+  if (cols < 60 || rows < 12) return 'small';
+  return qSize(cols, rows);
+}
+
+export function qDims(size) {
+  const H = SIZES[size];
+  const cells = Math.ceil((H * ASPECT) / 2);
+  return { H, W: cells * 2, cols: cells, rows: H / 4 };
+}
+
+// ---- silhouette (unit space: y 0..1 top to bottom, x 0..ASPECT) -----------------------------------
+const distSeg = (px, py, ax, ay, bx, by) => {
+  const dx = bx - ax, dy = by - ay;
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)));
+  return [Math.sqrt((px - (ax + dx * t)) ** 2 + (py - (ay + dy * t)) ** 2), t];
+};
+const bez = (a, b, c, t) => [(1 - t) ** 2 * a[0] + 2 * (1 - t) * t * b[0] + t * t * c[0], (1 - t) ** 2 * a[1] + 2 * (1 - t) * t * b[1] + t * t * c[1]];
+
+export const BOWL = { cx: ASPECT / 2, cy: 0.6, rx: 0.4, ry: 0.385, w: 0.118 };
+// Each horn is a quadratic curve, thick at the base and tapering to a point: out and up like a bull's.
+// The right horn is the exact mirror of the left about the bowl's axis (it was hand-tuned and its tip had
+// drifted to y 0.0 against the left's 0.03, which read as a thin stalk next to a solid horn).
+const LEFT_HORN = { a: [0.2, 0.29], b: [-0.02, 0.27], c: [0.02, 0.03], r0: 0.048 };
+const mirrorX = (p) => [ASPECT - p[0], p[1]];
+const HORNS = [LEFT_HORN, { a: mirrorX(LEFT_HORN.a), b: mirrorX(LEFT_HORN.b), c: mirrorX(LEFT_HORN.c), r0: LEFT_HORN.r0 }];
+const HORN_PTS = HORNS.map((hn) => Array.from({ length: 24 }, (_, i) => ({ p: bez(hn.a, hn.b, hn.c, i / 23), t: i / 23, r0: hn.r0 })));
+const TAIL = { a: [0.4, 0.69], b: [0.79, 0.985], r0: 0.07, r1: 0.04 };
+
+/** Which part of the Q a unit point is in: null, or { part: 'bowl'|'tail'|'horn', t } (t = 0 base .. 1 tip). */
+function partAt(x, y) {
+  const [d, t] = distSeg(x, y, ...TAIL.a, ...TAIL.b);
+  const inTail = d <= TAIL.r0 + (TAIL.r1 - TAIL.r0) * t;
+  const dx = (x - BOWL.cx) / BOWL.rx, dy = (y - BOWL.cy) / BOWL.ry;
+  const e = Math.sqrt(dx ** 2 + dy ** 2);
+  const inner = 1 - BOWL.w / ((BOWL.rx + BOWL.ry) / 2);
+  if (e <= 1 && e >= inner) return { part: inTail && t > 0.45 ? 'tail' : 'bowl', t: inTail ? t : 0 };
+  if (inTail) return { part: 'tail', t };
+  if (y > 0.34) return null;
+  for (const pts of HORN_PTS) for (const q of pts) if (Math.sqrt((x - q.p[0]) ** 2 + (y - q.p[1]) ** 2) <= q.r0 * (1 - q.t * 0.93) + 0.004) return { part: 'horn', t: q.t };
+  return null;
+}
+
+const maskCache = new Map();
+/**
+ * Boolean mask of the Q silhouette at a size: { W, H, ox, on(x, y), dots: [{ x, y, part, t }] }.
+ * ox is the left offset of the silhouette inside the cell grid (dots).
+ */
+export function qMask(size) {
+  if (maskCache.has(size)) return maskCache.get(size);
+  const { W, H } = qDims(size);
+  const ox = (W - H * ASPECT) / 2; // the Q's axis sits exactly on the grid centre, so the mask mirrors dot for dot
+  const dots = [];
+  const grid = new Uint8Array(W * H);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    // 2x2 supersample for clean edges
+    let n = 0;
+    for (const [sx, sy] of [[0.25, 0.25], [0.75, 0.25], [0.25, 0.75], [0.75, 0.75]]) if (partAt((x - ox + sx) / H, (y + sy) / H)) n++;
+    if (n >= 2) {
+      grid[y * W + x] = 1;
+      const p = partAt((x - ox + 0.5) / H, (y + 0.5) / H) || { part: 'bowl', t: 0 };
+      dots.push({ x, y, part: p.part, t: p.t });
+    }
+  }
+  const m = { W, H, ox, on: (x, y) => grid[y * W + x] === 1, dots };
+  maskCache.set(size, m);
+  return m;
+}
+
+// ---- intensity field -> cells -> text -----------------------------------------------------------------
+const BR = [[0x1, 0x8], [0x2, 0x10], [0x4, 0x20], [0x40, 0x80]];
+const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
+const smooth = (e) => { e = clamp(e); return e * e * (3 - 2 * e); };
+const lerp = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+const RESET = '\x1b[0m';
+
+/** A field of dot intensities. 0 = off, 1 = the settled Q, > 1 = a flash (pushes towards white). */
+export function makeField(W, H) {
+  const v = new Float32Array(W * H);
+  return {
+    W, H, v,
+    set(x, y, val) {
+      x = Math.round(x); y = Math.round(y);
+      if (x < 0 || y < 0 || x >= W || y >= H) return;
+      const i = y * W + x; if (val > v[i]) v[i] = val;
+    },
+  };
+}
+
+/**
+ * Turn a field into rows of cells { ch, rgb }. rgb is null for blanks and in mono.
+ *   color false (mono): shapes only, dim dots (< 0.35) are dropped, as in the lab.
+ *   quant true (terminal default): 4 hue bands x 6 brightness levels, so SGR runs stay long (Ink tokenising
+ *     a per-cell colour was ~100 ms a frame); trails keep their own levels so the drag still reads.
+ *   quant false (web): the lab's continuous shade, every cell its own colour.
+ *   tint: one rgb for every cell instead of the sky to violet gradient (amber, red, ...).
+ */
+export function fieldToCells(field, { color = true, quant = true, tint = null } = {}) {
+  const { W, H, v } = field;
+  const thr = color ? 0.04 : 0.35;
+  const cols = W / 2, rows = H / 4, out = [];
+  for (let cy = 0; cy < rows; cy++) {
+    const row = [];
+    for (let cx = 0; cx < cols; cx++) {
+      let bits = 0, m = 0;
+      for (let dy = 0; dy < 4; dy++) for (let dx = 0; dx < 2; dx++) {
+        const val = v[(cy * 4 + dy) * W + cx * 2 + dx];
+        if (val > thr) { bits |= BR[dy][dx]; if (val > m) m = val; }
+      }
+      if (!bits) { row.push({ ch: ' ', rgb: null }); continue; }
+      let rgb = null;
+      if (color) {
+        if (quant) {
+          const base = tint || lerp(SKY, VIOLET, (Math.min(3, Math.floor((cx / cols) * 4)) + 0.5) / 4);
+          const [lum, fl] = m > 1.5 ? [1, 0.85] : m > 1.05 ? [1, 0.45] : m >= 0.95 ? [1, 0] : m > 0.6 ? [0.72, 0] : m > 0.38 ? [0.48, 0] : [0.3, 0];
+          rgb = base.map((c) => Math.round(c * lum + (255 - c * lum) * fl));
+        } else {
+          const base = tint || lerp(SKY, VIOLET, cols > 1 ? cx / (cols - 1) : 0);
+          const f = 0.28 + 0.72 * Math.min(1, m), fl = clamp(m - 1);
+          rgb = base.map((c) => { c *= f; return Math.round(c + (255 - c) * fl * 0.9); });
+        }
+      }
+      row.push({ ch: String.fromCharCode(0x2800 + bits), rgb });
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+const sgr = (rgb) => `\x1b[38;2;${rgb.map((x) => Math.max(0, Math.min(255, Math.round(x)))).join(';')}m`;
+/** Cells -> ANSI lines (truecolor SGR, one escape per colour run). Mono cells carry no SGR at all. */
+export function cellsToAnsi(rows) {
+  return rows.map((row) => {
+    let s = '', last = '';
+    for (const c of row) {
+      if (c.rgb) { const e = sgr(c.rgb); if (e !== last) { s += e; last = e; } }
+      else if (last && c.ch !== ' ') { s += RESET; last = ''; }
+      s += c.ch;
+    }
+    return s + (last ? RESET : '');
+  });
+}
+/** Cells -> plain text lines. */
+export const cellsToText = (rows) => rows.map((r) => r.map((c) => c.ch).join(''));
+
+const rng = (seed) => () => { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+
+// ---- the settled Q ------------------------------------------------------------------------------------
+/** Cells of the settled Q. */
+export function qCells(size, opts = {}) {
+  const m = qMask(size), f = makeField(m.W, m.H);
+  for (const d of m.dots) f.v[d.y * m.W + d.x] = 1;
+  return fieldToCells(f, opts);
+}
+/** Rows of text for the settled Q (identical to orbitFrame(size, 1)). */
+export function qLines(size, { color = true } = {}) { return cellsToAnsi(qCells(size, { color })); }
+
+// ---- 1: Orbit & Lock (and 3: Particle collapse) ---------------------------------------------------------
+/** The intro's whole budget, ms. Orbit runs ORBIT_MS of it; the rest holds the finished mark. */
+export const INTRO_MS = 900;
+export const ORBIT_MS = 820;
+const FLASH_MS = 170;
+// Lab parameters, verbatim (lab.mjs build()): orbit for large/mid, particle for the compact Q.
+const SWARM = {
+  orbit: { band: 0.3, appearMax: 0.08, lockStart: 0.42, lockSpan: 0.2, lockLen: 0.2, byAngle: true, spin: [0.5, 5] },
+  particle: { band: 0.05, appearMax: 0.5, lockStart: 0.55, lockSpan: 0.12, lockLen: 0.2, byAngle: false, spin: [1.2, 2.5] },
+};
+
+const swarmCache = new Map();
+function swarm(size, kind, seed) {
+  const key = `${size}:${kind}:${seed}`;
+  if (swarmCache.has(key)) return swarmCache.get(key);
+  const P = SWARM[kind], m = qMask(size), R = rng(seed + m.H);
+  const cx = m.W / 2, cy = m.H / 2, Rmax = Math.min(m.W, m.H) / 2 - 1.5;
+  const parts = m.dots.map((d) => ({
+    tx: d.x, ty: d.y, part: d.part, pt: d.t, ang: Math.atan2(d.y - cy, d.x - cx), th0: R() * TAU,
+    rho: Rmax - Rmax * P.band * R() ** 2, w: 0.85 + 0.3 * R(), ap: R() * P.appearMax, rnd: R(),
+  }));
+  const key2 = (p) => (P.byAngle ? p.ang : p.rnd);
+  [...parts].sort((a, b) => key2(a) - key2(b)).forEach((p, i) => { p.s = P.lockStart + P.lockSpan * (i / (parts.length - 1)); });
+  // Tail sweep: the tail is the last stroke to land, base to tip, so the Q finishes with a flourish.
+  // Horns land tip-last, so each horn grows out of the bowl with its flash travelling up to the point.
+  const end = P.lockStart + P.lockSpan;
+  for (const p of parts) {
+    if (p.part === 'tail') p.s = end - 0.06 + 0.08 * p.pt;
+    else if (p.part === 'horn') p.s = Math.min(p.s, end - 0.1) + 0.05 * p.pt;
+  }
+  const r = { P, parts, cx, cy };
+  swarmCache.set(key, r);
+  return r;
+}
+
+/**
+ * The swarm field at t ms. Each particle draws a head plus two trail samples that lag along its path; the
+ * lag grows with speed (0.09 * (1 + 2u) rad), which is the "drag" in the lab: fast particles smear.
+ */
+function swarmField(size, t, { kind = 'orbit', dur = ORBIT_MS, seed = 11 } = {}) {
+  const m = qMask(size), { P, parts, cx, cy } = swarm(size, kind, seed), f = makeField(m.W, m.H);
+  const u = t / dur, settled = t > dur + FLASH_MS + 300;
+  const ph = TAU * (P.spin[0] * u + P.spin[1] * u * u);
+  for (const p of parts) {
+    const e = settled ? 1 : smooth((u - p.s) / P.lockLen);
+    if (e >= 1) {
+      const lt = (u - (p.s + P.lockLen)) * dur;
+      f.set(p.tx, p.ty, settled ? 1 : 1 + Math.max(0, 1 - lt / FLASH_MS) * 0.9);
+      continue;
+    }
+    if (u < p.ap) continue;
+    const fade = Math.min(1, ((u - p.ap) * dur) / 90);
+    for (let k = 0; k < 3; k++) {
+      const th = p.th0 + (ph - k * 0.09 * (1 + 2 * u)) * p.w;
+      const x = cx + p.rho * Math.cos(th), y = cy + p.rho * Math.sin(th);
+      f.set(x + (p.tx - x) * e, y + (p.ty - y) * e, (k === 0 ? 0.9 : k === 1 ? 0.5 : 0.28) * fade + (e > 0 && k === 0 ? 0.4 * e : 0));
+    }
+  }
+  return f;
+}
+
+/** Orbit & Lock cells at t ms (0..INTRO_MS; >= INTRO_MS is the settled Q). small plays the particle collapse. */
+export function orbitCellsAt(size, t, opts = {}) {
+  if (t >= INTRO_MS) return qCells(size, opts);
+  const kind = size === 'small' ? 'particle' : 'orbit';
+  return fieldToCells(swarmField(size, t, { kind, dur: kind === 'particle' ? INTRO_MS - 60 : ORBIT_MS, seed: opts.seed ?? 11 }), opts);
+}
+
+/**
+ * One frame of Orbit & Lock at progress 0..1 of INTRO_MS (lab timing: 820 ms orbit, all locks done by
+ * 672 ms, the last flashes fade by ~840 ms). progress >= 1 is exactly the settled Q.
+ */
+export function orbitFrame(size, progress, { color = true } = {}) {
+  if (progress >= 1) return qLines(size, { color });
+  return cellsToAnsi(orbitCellsAt(size, progress * INTRO_MS, { color }));
+}
+
+/** Particle collapse at t ms of `dur` (the lab's compact variant, any size). */
+export function particleCellsAt(size, t, opts = {}) {
+  const dur = opts.dur ?? 1100;
+  if (t >= dur + FLASH_MS + 300) return qCells(size, opts);
+  return fieldToCells(swarmField(size, t, { kind: 'particle', dur, seed: opts.seed ?? 12 }), opts);
+}
+
+// ---- 2: Portal -------------------------------------------------------------------------------------------
+export const PORTAL_MS = 1000;
+const portalCache = new Map();
+function portalModel(size) {
+  if (portalCache.has(size)) return portalCache.get(size);
+  const m = qMask(size), H = m.H;
+  const ccx = m.ox + BOWL.cx * H, ccy = BOWL.cy * H, ringR = 0.3 * H, revR = 0.42 * H;
+  const phiAt = (u) => (u < 0.3 ? (Math.PI / 2) * smooth(u / 0.3) : u < 0.7 ? Math.PI / 2 + (Math.PI / 2) * smooth((u - 0.3) / 0.4) : Math.PI);
+  const pts = m.dots.map((d) => {
+    // The tail sweeps in last, base to tip (lab: rt 0.74 .. 0.94 along the tail).
+    if (d.part === 'tail') return { ...d, rt: 0.74 + 0.2 * d.t };
+    let rt = 0.74 + 0.1 * (d.y / H);
+    for (let u = 0.3; u <= 0.7; u += 0.004) {
+      const w = Math.max(0.02, Math.abs(Math.cos(phiAt(u))));
+      if (((d.x - ccx) / (revR * w)) ** 2 + ((d.y - ccy) / revR) ** 2 <= 1) { rt = u; break; }
+    }
+    return { ...d, rt };
+  });
+  const r = { m, ccx, ccy, ringR, phiAt, pts };
+  portalCache.set(size, r);
+  return r;
+}
+
+/** Portal at t ms: a ring spins in 3D (circle, edge-on line, open), the Q fills from the opening, tail last. */
+export function portalCellsAt(size, t, opts = {}) {
+  const { m, ccx, ccy, ringR, phiAt, pts } = portalModel(size), f = makeField(m.W, m.H);
+  const dur = PORTAL_MS, u = t / dur, settled = t > dur + 500, phi = phiAt(Math.min(u, 1));
+  if (settled) return qCells(size, opts);
+  const alpha = Math.min(1, u / 0.1) * (1 - clamp((u - 0.68) / 0.12));
+  if (alpha > 0) {
+    const w = Math.cos(phi), n = Math.round(ringR * 24);
+    for (let i = 0; i < n; i++) {
+      const th = (i / n) * TAU, z = Math.cos(th) * Math.sin(phi);
+      f.set(ccx + ringR * Math.cos(th) * w, ccy + ringR * Math.sin(th), alpha * (0.62 + 0.38 * z));
+    }
+    if (Math.abs(w) < 0.12) for (let yy = -ringR; yy <= ringR; yy++) f.set(ccx, ccy + yy, alpha * 1.15);
+  }
+  for (const p of pts) if (u >= p.rt) f.set(p.x, p.y, 1 + Math.max(0, 1 - ((u - p.rt) * dur) / 150) * 0.7);
+  return fieldToCells(f, opts);
+}
+
+// ---- 5: Dragon's Eye -------------------------------------------------------------------------------------
+export const EYE_MS = 2800;
+/** Lid openness 0..1 over the eye's progress u: open, hold, one blink, hold, close (lab timings). */
+export function eyeOpenAt(u) {
+  if (u < 0.12) return 0;
+  if (u < 0.34) return smooth((u - 0.12) / 0.22);
+  if (u < 0.5) return 1;
+  if (u < 0.58) return 1 - smooth((u - 0.5) / 0.08);
+  if (u < 0.68) return smooth((u - 0.58) / 0.1);
+  if (u < 0.86) return 1;
+  if (u < 0.96) return 1 - smooth((u - 0.86) / 0.1);
+  return 0;
+}
+
+/**
+ * The Dragon's Eye at t ms: a slit-pupil eye opens in the bowl, blinks once, and dissolves back into the Q
+ * with a flash. The Q dims while the eye is open so the eye reads. t >= EYE_MS + 400 is the settled Q.
+ */
+export function eyeCellsAt(size, t, opts = {}) {
+  if (t >= EYE_MS + 400 || t < 0) return qCells(size, opts);
+  const m = qMask(size), H = m.H, f = makeField(m.W, m.H), u = t / EYE_MS, k = eyeOpenAt(u), big = H >= 40;
+  const ecx = m.ox + BOWL.cx * H, ecy = 0.51 * H, ew = 0.2 * H * ASPECT + 0.5, eh = 0.155 * H;
+  const back = u > 0.94 ? 1 + (1 - clamp((u - 0.94) / 0.06)) * 0.8 : 1;
+  const qv = u < 0.12 ? 0.55 + 0.45 * smooth(u / 0.12) : 0.75 + 0.25 * (1 - k);
+  for (const d of m.dots) f.set(d.x, d.y, back > 1 ? back : (k > 0.02 && d.part === 'tail' && d.t < 0.4 ? qv * 0.6 : qv));
+  if (k > 0.02) {
+    for (let dx = -ew; dx <= ew + 1e-6; dx += 0.5) {
+      const hh = k * eh * Math.sqrt(Math.max(0, 1 - (dx / ew) ** 2));
+      f.set(ecx + dx, ecy - hh, 1.05); f.set(ecx + dx, ecy + hh, 1.05);
+      if (big && hh > 1.2 && Math.abs(dx) < ew * 0.8) for (let yy = -hh + 1; yy < hh; yy += 1) f.set(ecx + dx, ecy + yy, 0.18);
+    }
+    const dil = 0.8 + 0.25 * Math.sin(u * 14), pw = (big ? H / 36 : 0.6) * dil;
+    for (let dx = -pw; dx <= pw; dx++) for (let yy = -k * eh * 0.92; yy <= k * eh * 0.92; yy += 0.5) f.set(ecx + dx, ecy + yy, 1.7);
+    if (big) { f.set(ecx - ew, ecy, 1.05); f.set(ecx + ew, ecy, 1.05); }
+  }
+  return fieldToCells(f, opts);
+}
+
+// ---- resting --------------------------------------------------------------------------------------------
+export const BREATH_MS = 2400;
+/** The settled Q breathing gently (idle on the web face): brightness 0.82 .. 1 over BREATH_MS. */
+export function restCellsAt(size, t, opts = {}) {
+  const m = qMask(size), f = makeField(m.W, m.H);
+  const g = 0.82 + 0.18 * (0.5 + 0.5 * Math.sin((t / BREATH_MS) * TAU - Math.PI / 2));
+  for (const d of m.dots) f.v[d.y * m.W + d.x] = g;
+  return fieldToCells(f, opts);
+}
+
+// ---- intro plan ------------------------------------------------------------------------------------------
+/**
+ * The intro as one timeline: Orbit & Lock, then (when the launch egg fires or the cinematic level asks) the
+ * Dragon's Eye on the settled Q. Returns { ms, at(t) -> cells }. Callers drive t from their own clock.
+ */
+export function introPlan(size, { eye = false, ...opts } = {}) {
+  const ms = INTRO_MS + (eye ? EYE_MS + 400 : 0);
+  return {
+    ms,
+    at(t) {
+      if (t < INTRO_MS) return orbitCellsAt(size, t, opts);
+      if (eye) return eyeCellsAt(size, t - INTRO_MS, opts);
+      return qCells(size, opts);
+    },
+  };
+}

package/lib/quoxon/qglyph.js

@@ -0,0 +1,143 @@
+/**
+ * The perpetual Q: the status glyph that carries state (CLI-QUOX, lab variant "perpetual").
+ *
+ * ONE fixed shape, a two-cell Braille Q (4 x 4 dots: bowl, counter, tail). It never swaps frames; all of
+ * its life is smooth colour (owner, 2026-10-12: "our icons could animate the colour but stay the same icon.
+ * Smoother."). Colours are interpolated in OKLab so transitions stay even to the eye:
+ *   resting  the Q gradient (sky to violet across the two cells), slow breathing brightness (2.4 s)
+ *   working  sky > indigo > violet > teal flowing through the cells (1.6 s a cycle)
+ *   waiting  amber, slow pulse (1.2 s)
+ *   failing  a red flash (from `since`, 600 ms), then steady red
+ * Meant to be sampled at ~12 fps from the shared motion clock. depth '256' steps the colour less often
+ * (every 250 ms) and snaps it to the xterm 256 palette, so a 256-colour terminal does not shimmer.
+ * Under mono (NO_COLOR) or where Braille does not render two cells wide, it falls back to Ⓠ.
+ *
+ * PURE AND PORTABLE: no Ink, no process, no timers. Output cells { ch, rgb } plus the joined text and a
+ * representative colour, so the terminal (Ink, raw ANSI) and the web face (web/qface.js) draw the same.
+ */
+
+export const GLYPH_STATES = ['resting', 'working', 'waiting', 'failing'];
+export const FALLBACK = 'Ⓠ';
+const SKY = [56, 189, 248], INDIGO = [99, 102, 241], VIOLET = [168, 85, 247], TEAL = [6, 182, 212];
+const AMBER = [245, 158, 11], RED = [239, 68, 68];
+const TAU = Math.PI * 2;
+const wave = (t, period) => 0.5 + 0.5 * Math.sin((t / period) * TAU - Math.PI / 2); // 0 at t=0, 1 at half
+
+// ---- OKLab (Björn Ottosson), for perceptually even blends --------------------------------------------
+const toLin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const toSrgb = (c) => Math.round(255 * Math.max(0, Math.min(1, c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)));
+export function oklab([r, g, b]) {
+  const [R, G, B] = [toLin(r), toLin(g), toLin(b)];
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
+}
+export function fromOklab([L, a, b]) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3, m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3, s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [toSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), toSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), toSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)];
+}
+/** Blend two sRGB colours in OKLab. */
+export const mixOk = (a, b, t) => { const A = oklab(a), B = oklab(b); return fromOklab(A.map((v, i) => v + (B[i] - v) * t)); };
+/** Scale lightness in OKLab (k < 1 darker), keeping hue. */
+const dimOk = (rgb, k) => { const [L, a, b] = oklab(rgb); return fromOklab([L * k, a * k, b * k]); };
+/** A point on a closed OKLab gradient through `stops` at phase p (0..1, wraps). */
+export function cycleOk(stops, p) {
+  const n = stops.length, x = (((p % 1) + 1) % 1) * n, i = Math.floor(x);
+  const t = x - i, e = t * t * (3 - 2 * t); // eased between stops: no visible kinks
+  return mixOk(stops[i], stops[(i + 1) % n], e);
+}
+
+// ---- the fixed shape ----------------------------------------------------------------------------------
+//   .##.
+//   #..#
+//   #.##
+//   .###
+export const DOTS = ['.##.', '#..#', '#.##', '.###'];
+const BR = [[0x1, 0x8], [0x2, 0x10], [0x4, 0x20], [0x40, 0x80]];
+export const SHAPE = [0, 1].map((cx) => {
+  let bits = 0;
+  for (let y = 0; y < 4; y++) for (let dx = 0; dx < 2; dx++) if (DOTS[y][cx * 2 + dx] === '#') bits |= BR[y][dx];
+  return String.fromCharCode(0x2800 + bits);
+}).join('');
+
+export const BREATH_MS = 2400, FLOW_MS = 1600, PULSE_MS = 1200, FLASH_MS = 600, STEP_256_MS = 250;
+const FLOW = [SKY, INDIGO, VIOLET, TEAL];
+
+/** The two cell colours for a state at t ms. since: when the state began (failing flashes from there). */
+export function glyphColors(state, t = 0, { quiet = false, since = null } = {}) {
+  switch (state) {
+    case 'working': {
+      // The gradient flows left to right through the two cells: cell 1 is a quarter cycle behind cell 0.
+      const p = quiet ? 0.1 : t / FLOW_MS;
+      return [cycleOk(FLOW, p), cycleOk(FLOW, p - 0.25)];
+    }
+    case 'waiting': {
+      const k = quiet ? 1 : 0.45 + 0.55 * wave(t, PULSE_MS);
+      return [dimOk(AMBER, k), dimOk(AMBER, k)];
+    }
+    case 'failing': {
+      const dt = since == null || quiet ? Infinity : t - since;
+      const f = dt >= 0 && dt < FLASH_MS ? 1 - dt / FLASH_MS : 0; // the flash: red lifted towards white, easing out
+      const c = f > 0 ? mixOk(RED, [255, 236, 236], f * f) : RED;
+      return [c, c];
+    }
+    default: {
+      const k = quiet ? 0.9 : 0.62 + 0.38 * wave(t, BREATH_MS);
+      return [dimOk(SKY, k), dimOk(mixOk(SKY, VIOLET, 0.85), k)];
+    }
+  }
+}
+
+/** Nearest xterm 256-colour cube entry, returned as rgb (so callers keep one colour type). */
+export function to256(rgb) {
+  const lv = [0, 95, 135, 175, 215, 255];
+  const near = (v) => lv.reduce((a, x) => (Math.abs(x - v) < Math.abs(a - v) ? x : a), 0);
+  return rgb.map(near);
+}
+
+/**
+ * Does this terminal draw the Braille glyph? Pure: pass the env and, if you have one, a width measurer
+ * (string-width). Braille is skipped under NO_COLOR (mono), TERM=dumb or linux (the VT console font has no
+ * Braille), QUOX_GLYPH=circled, or when two Braille cells measure wider than 2.
+ */
+export function glyphMode(env = {}, measure = null) {
+  if (env.NO_COLOR || env.TERM === 'dumb' || env.TERM === 'linux' || env.QUOX_GLYPH === 'circled') return 'circled';
+  if (measure && measure('⣿⣿') !== 2) return 'circled';
+  return 'braille';
+}
+
+/** Colour depth from the env: 'truecolor' | '256' | '16'. Pure. */
+export function colorDepth(env = {}) {
+  if (/truecolor|24bit/i.test(env.COLORTERM || '')) return 'truecolor';
+  if (/256/.test(env.TERM || '')) return '256';
+  return env.TERM ? '16' : 'truecolor';
+}
+
+/**
+ * One frame of the status glyph.
+ *   state  resting | working | waiting | failing
+ *   t      ms (any monotonic clock); since: ms when the state began (for the failing flash)
+ *   opts   { mono, quiet (reduced motion: still colour), mode: 'braille' | 'circled', depth: 'truecolor' | '256' }
+ * Returns { text, cells: [{ ch, rgb }], rgb, width }. The text is always the same for a mode: only colour moves.
+ */
+export function qGlyph(state, t = 0, { mono = false, quiet = false, mode = 'braille', depth = 'truecolor', since = null } = {}) {
+  const st = GLYPH_STATES.includes(state) ? state : 'working';
+  const tt = depth === '256' ? Math.floor(t / STEP_256_MS) * STEP_256_MS : t;
+  let cols = mono ? [null, null] : glyphColors(st, tt, { quiet, since });
+  if (depth === '256' && !mono) cols = cols.map(to256);
+  if (mono || mode !== 'braille') {
+    const rgb = mono ? null : cols[0];
+    return { text: FALLBACK, cells: [{ ch: FALLBACK, rgb }], rgb, width: 1 };
+  }
+  const cells = [...SHAPE].map((ch, i) => ({ ch, rgb: cols[i] }));
+  return { text: SHAPE, cells, rgb: cols[0], width: 2 };
+}
+
+/** The settled glyph (no motion): what a static surface shows. */
+export const glyphStill = (state = 'resting', opts = {}) => qGlyph(state, 0, { ...opts, quiet: true });
+
+/** Truecolor ANSI for a frame (raw terminal use: gallery). */
+export function glyphAnsi(g) {
+  return g.cells.map((c) => (c.rgb ? `\x1b[38;2;${c.rgb.join(';')}m${c.ch}` : c.ch)).join('') + (g.cells.some((c) => c.rgb) ? '\x1b[0m' : '');
+}