quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/model.js

@@ -0,0 +1,205 @@
+/**
+ * /model: which provider (and optionally which model) the next turns ask the server for.
+ * Pure, apart from the vault list result passed in.
+ *
+ * The choice is a REQUEST: the stream body carries `provider` (and `model`), and the collector's
+ * policy plan (resolveCollectorPolicyPlan) decides. turn.started.provider/model is the truth; when it
+ * differs from what was asked, the client says so once (never a silent fallback).
+ * null choice = auto (no provider in the body; the server's policy picks).
+ *
+ * Availability is the same source as /connect: the org's default QuoxVault credential per provider.
+ * Model ids mirror src/config/modelCatalog.js (openai + anthropic rows); an id not listed is passed
+ * through with a note, the server decides whether it exists.
+ */
+import { PROVIDERS as CONNECT, pickRow, offerText } from './connect.js';
+
+export const CHOICES = [
+  { id: 'openai', provider: 'openai', name: 'OpenAI', vault: 'openai', connect: 'openai', models: ['gpt-5.4', 'gpt-5.4-mini', 'gpt-5.4-nano'] },
+  { id: 'anthropic', provider: 'anthropic', name: 'Claude API', vault: 'anthropic', connect: 'anthropic', models: ['claude-sonnet-4-6', 'claude-opus-4-6', 'claude-haiku-4-5-20251001'] },
+  // B3: served by the chat stream; models are whatever that Ollama has installed (listed by the server).
+  { id: 'ollama', provider: 'ollama', name: 'Ollama', vault: 'ollama', connect: 'ollama', dynamic: true, hint: 'http://<host>:11434', models: [] },
+  // B5: OpenAI-compatible presets. Models come from the provider's own /models (api.compatModels).
+  // hosted: a model is required (listed, never defaulted); selfHosted: the connection default or the first served.
+  ...[
+    ['openrouter', 'OpenRouter', 'openrouter', true, ''], ['huggingface', 'Hugging Face', 'huggingface', true, ''],
+    ['groq', 'Groq', 'groq', true, ''], ['together', 'Together', 'together', true, ''],
+    ['lmstudio', 'LM Studio', 'lmstudio', false, ' http://<host>:1234'], ['vllm', 'vLLM', 'vllm', false, ' http://<host>:8000'],
+    ['custom', 'Custom', 'openai_compatible', false, ' https://<host>/v1']
+  ].map(([id, name, vault, hosted, hint]) => ({ id, provider: id, name, vault, connect: id, dynamic: true, compat: true, hosted, selfHosted: !hosted, hint: hint.trim(), models: [] }))
+];
+const ALIASES = { gpt: 'openai', chatgpt: 'openai', claude: 'anthropic', 'claude-api': 'anthropic', 'anthropic-api': 'anthropic', local: 'ollama', hf: 'huggingface', 'lm-studio': 'lmstudio', 'openai-compatible': 'custom', openai_compatible: 'custom', default: 'auto', policy: 'auto' };
+const byProvider = (p) => CHOICES.find(c => c.provider === p) || null;
+
+/** Stored or flag value -> { provider, model? } | null. Only the two known fields survive. */
+export function normChoice(v) {
+  if (!v || typeof v !== 'object' || typeof v.provider !== 'string' || !byProvider(v.provider)) return null;
+  const out = typeof v.model === 'string' && v.model.trim() ? { provider: v.provider, model: v.model.trim() } : { provider: v.provider };
+  // B3/B5: the Ollama / self-hosted host, for the status line before the first turn (turn.started.endpoint wins after).
+  if ((v.provider === 'ollama' || byProvider(v.provider).selfHosted) && typeof v.host === 'string' && v.host.trim()) out.host = v.host.trim().slice(0, 120);
+  // D3: prompt profile (compact | full); absent = the server default (compact on ollama / local presets, full elsewhere).
+  if (PROFILES.includes(v.profile)) out.profile = v.profile;
+  return out;
+}
+
+export const PROFILES = ['compact', 'full'];
+
+/** "/model <provider> [model] [compact|full]" text -> { ok:true, choice } (choice null = auto) | { ok:false, error }. */
+export function parseModelArg(arg) {
+  const words = String(arg || '').trim().split(/\s+/).filter(Boolean);
+  const profile = words.length > 1 && PROFILES.includes(String(words[words.length - 1]).toLowerCase()) ? words.pop().toLowerCase() : null;
+  const [rawName, model] = words;
+  const n = String(rawName || '').toLowerCase();
+  const id = ALIASES[n] || n;
+  if (id === 'auto') return { ok: true, choice: null };
+  const c = CHOICES.find(x => x.id === id);
+  if (!c) return { ok: false, error: `No provider called "${rawName}". Use ${CHOICES.map(x => x.id).join(', ')} or auto (/model lists them).` };
+  const choice = model ? { provider: c.provider, model } : { provider: c.provider };
+  if (profile) choice.profile = profile;
+  return { ok: true, choice };
+}
+
+/** -> 'connected' | 'stored' | 'missing' | 'unknown' (+ the row) for one choice. */
+function availability(res, c) {
+  if (!res || !res.ok || !Array.isArray(res.rows)) return { state: 'unknown' };
+  const { def, any } = pickRow(res.rows, c.vault);
+  if (def) return { state: 'connected', row: def };
+  if (any) return { state: 'stored', row: any };
+  return { state: 'missing' };
+}
+
+const same = (a, b) => (a?.provider || null) === (b?.provider || null);
+
+/** -> [[text, tone?]] lines for /model. */
+export function modelLines(res, current) {
+  const out = [['Model for your next turns (the server decides; turn.started shows what ran):']];
+  const mark = (on) => (on ? '▸' : ' ');
+  out.push([`${mark(!current)} auto  server policy picks the provider and model · /model auto`]);
+  for (const c of CHOICES) {
+    const a = availability(res, c);
+    const picked = same(current, c);
+    const sel = picked && current.model ? ` · using ${current.model}` : '';
+    if (c.served === false) {
+      out.push([`${mark(picked)} ${c.name}  ${a.state === 'connected' ? 'connected, but ' : ''}not served by the chat stream yet`]);
+      continue;
+    }
+    if (c.dynamic) {
+      if (a.state === 'connected') out.push([`${mark(picked)} ● ${c.name}  connected · ${a.row.label || a.row.id}${sel} · /model ${c.id} lists its ${c.compat ? '' : 'installed '}models`, 'ok']);
+      else if (a.state === 'stored') out.push([`${mark(picked)} ◐ ${c.name}  stored but not the default · quox vault set-default ${a.row.id}`, 'warn']);
+      else if (a.state === 'missing') out.push([`${mark(picked)} ○ ${c.name}  not connected · /connect ${c.connect}${c.hint ? ` ${c.hint}` : ''}`]);
+      else out.push([`${mark(picked)} ? ${c.name}  unknown (vault not readable)${sel}`, 'warn']);
+      continue;
+    }
+    const models = c.models.join(', ');
+    if (a.state === 'connected') out.push([`${mark(picked)} ● ${c.name}  connected${sel} · /model ${c.id} [${models}]`, 'ok']);
+    else if (a.state === 'stored') out.push([`${mark(picked)} ◐ ${c.name}  stored but not the default · quox vault set-default ${a.row.id}`, 'warn']);
+    else if (a.state === 'missing') out.push([`${mark(picked)} ○ ${c.name}  not connected · /connect ${c.connect}`]);
+    else out.push([`${mark(picked)} ? ${c.name}  unknown (vault not readable)${sel}`, 'warn']);
+  }
+  out.push(['  ? Claude (subscription)  dev-only · reached via auto or anthropic when no Claude API key is stored; no status route']);
+  if (!res?.ok) out.push([`  could not read the vault: ${res?.error || 'no answer'}`, 'warn']);
+  return out;
+}
+
+/**
+ * The /model <arg> decision. -> { ok, choice?, text, tone? }. A provider the vault says is not usable is
+ * refused (with the /connect offer), never quietly swapped for another.
+ */
+export function selectModel(res, arg) {
+  const p = parseModelArg(arg);
+  if (!p.ok) return { ok: false, text: p.error, tone: 'warn' };
+  if (!p.choice) return { ok: true, choice: null, text: 'Model: auto. The server policy picks the provider and model.', tone: 'ok' };
+  const c = byProvider(p.choice.provider);
+  if (c.served === false) return { ok: false, text: `${c.name} is not served by the chat stream yet, so I can't use it here. /model lists what can.`, tone: 'warn' };
+  const a = availability(res, c);
+  if (c.dynamic && a.state === 'missing') return { ok: false, text: `${c.name} isn't connected, so I can't use it yet. Connect it: /connect ${c.connect}${c.hint ? ` ${c.hint}` : ''}`, tone: 'warn' };
+  if (a.state === 'missing') return { ok: false, text: offerText(CONNECT[c.connect]), tone: 'warn' };
+  if (a.state === 'stored') return { ok: false, text: `${c.name} has a key stored, but not as the org default, so the server will not use it. Fix: quox vault set-default ${a.row.id}`, tone: 'warn' };
+  const label = p.choice.model ? `${c.id} ${p.choice.model}` : c.id;
+  const extra = p.choice.model && !c.dynamic && !c.models.includes(p.choice.model) ? ` ${p.choice.model} is not in this client's list; the server decides whether it exists.` : '';
+  if (a.state === 'unknown') return { ok: true, choice: p.choice, text: `Model: ${label}. Could not confirm ${c.name} is connected (vault not readable); the server will say if it is not.${extra}`, tone: 'warn' };
+  return { ok: true, choice: p.choice, text: `Model: ${label}. Your next turns ask for it.${extra}`, tone: extra ? 'warn' : 'ok' };
+}
+
+/**
+ * B3: /model ollama [model] against the server's installed-model list (res from api.ollamaModels()).
+ * -> { ok, choice?, text, tone, rows? } ; rows = the installed list to show.
+ */
+export function selectOllamaModel(res, model) {
+  if (!res?.ok) {
+    if (res?.error === 'not_connected') return { ok: false, text: 'Ollama is not connected. /connect ollama http://<host>:11434', tone: 'warn' };
+    const why = res?.message || res?.error || 'no answer';
+    return model
+      ? { ok: true, choice: { provider: 'ollama', model }, text: `Model: ollama ${model}. Could not list Ollama's models (${why}); the server will say if it is missing.`, tone: 'warn' }
+      : { ok: false, text: `Could not list Ollama's models: ${why}`, tone: 'warn' };
+  }
+  const models = Array.isArray(res.models) ? res.models : [];
+  const names = models.map(m => m.name);
+  const host = res.host || null;
+  const withHost = (c) => (host ? { ...c, host } : c);
+  if (!model) {
+    const def = res.default_model || names[0] || null;
+    if (!def) return { ok: false, text: `Ollama at ${host} has no models installed. On that machine run: ollama pull qwen2.5`, tone: 'warn' };
+    return { ok: true, choice: withHost({ provider: 'ollama' }), text: `Model: Ollama · ${host} · ${def} (the connection's default). Installed models below; pick one with /model ollama <model>.`, tone: 'ok', models, current: def };
+  }
+  const hit = names.includes(model) ? model : (names.includes(`${model}:latest`) ? `${model}:latest` : null);
+  if (!hit) return { ok: false, text: `${model} is not installed on ${host}. On that machine run: ollama pull ${model}`, tone: 'warn', models };
+  return { ok: true, choice: withHost({ provider: 'ollama', model: hit }), text: `Model: Ollama · ${host} · ${hit}. Your next turns ask for it.`, tone: 'ok' };
+}
+
+/** One compat row of a /models list: id (strings pass through). */
+const modelId = (m) => (typeof m === 'string' ? m : m?.id);
+
+/**
+ * B5: /model <preset> [model] against the provider's own /models (res from api.compatModels(preset)).
+ * Hosted presets never default a model: with none given the list is shown and no choice is set.
+ * -> { ok, choice?, text, tone, models?, current? }
+ */
+export function selectCompatModel(res, presetId, model) {
+  const c = byProvider(presetId);
+  const connectCmd = `/connect ${c.connect}${c.hint ? ` ${c.hint}` : ''}`;
+  if (!res?.ok) {
+    if (res?.error === 'not_connected') return { ok: false, text: `${c.name} is not connected. ${connectCmd}`, tone: 'warn' };
+    const why = res?.message || res?.error || 'no answer';
+    return model
+      ? { ok: true, choice: { provider: c.provider, model }, text: `Model: ${c.id} ${model}. Could not list ${c.name}'s models (${why}); the server will say if it is missing.`, tone: 'warn' }
+      : { ok: false, text: `Could not list ${c.name}'s models: ${why}`, tone: 'warn' };
+  }
+  const models = Array.isArray(res.models) ? res.models : [];
+  const ids = models.map(modelId).filter(Boolean);
+  const host = c.selfHosted ? (res.host || null) : null;
+  const withHost = (ch) => (host ? { ...ch, host } : ch);
+  if (!model) {
+    if (c.hosted) return { ok: false, text: `${c.name} needs a model. Pick one with /model ${c.id} <model>${ids.length ? ' (listed below)' : ''}.`, tone: 'warn', models };
+    const def = res.default_model || ids[0] || null;
+    if (!def) return { ok: false, text: `${c.name} at ${host} serves no models yet.`, tone: 'warn' };
+    return { ok: true, choice: withHost({ provider: c.provider }), text: `Model: ${c.name} · ${host} · ${def} (the connection's default). Models below; pick one with /model ${c.id} <model>.`, tone: 'ok', models, current: def };
+  }
+  if (ids.length && !ids.includes(model)) return { ok: false, text: `${model} is not served by ${host || c.name}. Models below.`, tone: 'warn', models };
+  if (!ids.length) return { ok: true, choice: withHost({ provider: c.provider, model }), text: `Model: ${c.id} ${model}. ${c.name} listed no models; the server will say if it is missing.`, tone: 'warn' };
+  return { ok: true, choice: withHost({ provider: c.provider, model }), text: `Model: ${c.name}${host ? ` · ${host}` : ''} · ${model}. Your next turns ask for it.`, tone: 'ok' };
+}
+
+/** Status-line text: what the server said it ran, else what is selected; null for auto before any turn (keeps the line short). */
+export function modelLabel(ctx, choice) {
+  if (ctx?.model && ctx.provider === 'ollama') return `Ollama · ${ctx.endpoint || choice?.host || '?'} · ${ctx.model}`;
+  const cc = ctx?.provider ? byProvider(ctx.provider) : null;
+  if (ctx?.model && cc?.compat) return cc.hosted ? `${cc.name} · ${ctx.model}` : `${cc.name} · ${ctx.endpoint || choice?.host || '?'} · ${ctx.model}`;
+  if (ctx?.model) return ctx.provider ? `${ctx.provider} ${ctx.model}` : ctx.model;
+  if (!choice) return null;
+  if (choice.provider === 'ollama') return `Ollama · ${choice.host || '?'} · ${choice.model || 'default model'}`;
+  const ch = byProvider(choice.provider);
+  if (ch?.compat) return ch.hosted ? `${ch.name} · ${choice.model || 'pick a model'}` : `${ch.name} · ${choice.host || '?'} · ${choice.model || 'default model'}`;
+  return choice.model ? `${choice.provider} ${choice.model}` : choice.provider;
+}
+
+/** One line when turn.started shows the server ran something other than what was asked; else null. */
+export function fallbackNote(choice, ev) {
+  if (!choice || !ev || ev.type !== 'turn.started' || !ev.provider) return null;
+  const ran = `${ev.provider}${ev.model ? ` ${ev.model}` : ''}`;
+  if (ev.provider !== choice.provider) return `You asked for ${choice.provider}; the server ran ${ran} (its policy or a fallback). /model shows what is connected.`;
+  if (choice.model && ev.model && ev.model !== choice.model) return `You asked for ${choice.model}; the server ran ${ran}.`;
+  return null;
+}
+
+/** Fields for the stream body. */
+export const streamFields = (choice) => (choice ? { provider: choice.provider, ...(choice.model ? { model: choice.model } : {}), ...(choice.profile ? { promptProfile: choice.profile } : {}) } : {});

package/lib/quoxon/motion/clock.js

@@ -0,0 +1,69 @@
+/**
+ * The motion engine's one clock (CLI-QUOX motion). Every animation and every visible tick in the client
+ * (activity word decode, Q state colour, elapsed timer, roster clock, composer ring, drop-in reveals, intro,
+ * approval arming) declares a DEMAND each render; the clock keeps exactly one timer armed for the soonest
+ * demand and none at all when nothing asks. Idle is still: no timers, no renders.
+ *
+ * Demand shapes: { every: ms } (repeat while declared) or { at: epochMs } (one wake at that time).
+ */
+export const FRAME_MS = 83; // ~12 fps for anything that moves
+export const SECOND_MS = 1000;
+
+/** Delay until the next wake for these demands, or null when nothing is waiting. Pure. */
+export function nextDelay(demands, now) {
+  let best = null;
+  for (const d of demands || []) {
+    if (!d) continue;
+    let ms = null;
+    if (Number.isFinite(d.every) && d.every > 0) {
+      // second ticks align to the wall-clock second so "3s" changes when a second actually passes
+      ms = d.every >= SECOND_MS && Number.isFinite(d.since) ? d.every - ((now - d.since) % d.every) : d.every;
+    } else if (Number.isFinite(d.at)) ms = Math.max(0, d.at - now);
+    if (ms != null && (best == null || ms < best)) best = ms;
+  }
+  return best == null ? null : Math.max(1, Math.round(best));
+}
+
+export class Clock {
+  constructor(onTick, timers = { setTimeout, clearTimeout }) {
+    this.onTick = onTick; this.timers = timers; this.id = null; this.dueAt = null; this.stopped = false;
+    this.ticks = 0; this.lastTickAt = null;
+  }
+  /** Re-arm for the given demands (called after every render). Keeps the timer when it is already due sooner or equal. */
+  schedule(demands, now = Date.now()) {
+    if (this.stopped) return null;
+    const d = nextDelay(demands, now);
+    if (d == null) { this.cancel(); return null; }
+    const due = now + d;
+    if (this.id != null && this.dueAt != null && this.dueAt <= due + 2) return this.dueAt - now;
+    this.cancel();
+    this.dueAt = due;
+    this.id = this.timers.setTimeout(() => {
+      this.id = null; this.dueAt = null; this.ticks++; this.lastTickAt = Date.now();
+      if (!this.stopped) this.onTick();
+    }, d);
+    return d;
+  }
+  cancel() { if (this.id != null) this.timers.clearTimeout(this.id); this.id = null; this.dueAt = null; }
+  stop() { this.stopped = true; this.cancel(); }
+  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);
+export const motionAllowed = (isTTY, env = process.env) => Boolean(isTTY) && !reducedMotion(env);
+
+/**
+ * Frame source: the clock's ticks fan out to the animated leaves only (Working, the composer ring, items that
+ * are revealing), so a frame re-renders those components instead of the whole app. get() is the frame time.
+ */
+export function createFrames(now = Date.now()) {
+  let t = now;
+  const subs = new Set();
+  return {
+    get: () => t,
+    subscribe: (fn) => { subs.add(fn); return () => subs.delete(fn); },
+    emit(at = Date.now()) { t = at; for (const fn of [...subs]) fn(); },
+    get size() { return subs.size; }
+  };
+}

package/lib/quoxon/motion/color.js

@@ -0,0 +1,35 @@
+/** Colour helpers for the motion engine: rgb triples, mixing, hex parsing. Pure. */
+export const hexRgb = (hex) => {
+  const m = String(hex || '').replace('#', '');
+  const v = m.length === 3 ? m.split('').map((x) => x + x).join('') : m;
+  return [0, 2, 4].map((i) => parseInt(v.slice(i, i + 2), 16) || 0);
+};
+export const mix = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+export const clamp01 = (x) => Math.max(0, Math.min(1, x));
+export const rgbStr = (rgb) => `rgb(${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v)))).join(',')})`;
+export const smooth = (x) => { const t = clamp01(x); return t * t * (3 - 2 * t); };
+/** Deterministic hash in [0,1) so a frame is reproducible from (cell, time bucket, salt). */
+export function hash3(a, b, c) {
+  let h = (a * 374761393 + b * 668265263 + c * 2147483647) | 0;
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+
+// ---- perceptual interpolation (OKLab) --------------------------------------------------------------
+const toLin = (v) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const toSrgb = (c) => { const v = c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055; return Math.max(0, Math.min(255, v * 255)); };
+export function rgbToOklab([r, g, b]) {
+  const R = toLin(r), G = toLin(g), B = 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 oklabToRgb([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)];
+}
+/** Mix two rgb colours in OKLab (perceptually even: no muddy midpoint). */
+export const mixOk = (a, b, t) => { const A = rgbToOklab(a), B = rgbToOklab(b); return oklabToRgb(A.map((v, i) => v + (B[i] - v) * t)); };
+/** A smooth 0..1 pulse with period `ms` (cosine ease, no hard edges). */
+export const pulse01 = (now, ms = 1200) => 0.5 - 0.5 * Math.cos((2 * Math.PI * (now % ms)) / ms);

package/lib/quoxon/motion/frame.js

@@ -0,0 +1,14 @@
+/** React side of the frame source: a context plus a hook that re-renders the caller on every clock frame. */
+import React from 'react';
+
+export const FrameContext = React.createContext(null);
+const noop = () => () => {};
+/**
+ * Re-render the caller on every clock frame and return the current time (ms). The wall clock, not the frame
+ * stamp, so a render caused by anything else is never stale. Outside a provider it returns `fallback`.
+ */
+export function useFrame(fallback) {
+  const frames = React.useContext(FrameContext);
+  React.useSyncExternalStore(frames ? frames.subscribe : noop, frames ? frames.get : () => 0);
+  return frames ? Date.now() : (fallback ?? Date.now());
+}

package/lib/quoxon/motion/reveal.js

@@ -0,0 +1,54 @@
+/**
+ * Drop-in reveals (lab prototype `quox-intro-lab fx`): when an item lands in the live region its text decodes
+ * in left to right. Just ahead of the resolving edge (LEAD) cells flicker as curated half-width katakana;
+ * further ahead they are blank; just behind it a phosphor afterglow tints the real character and fades.
+ * Decorative only: every cell is the real character once the reveal ends, widths are identical every frame
+ * (a katakana or blank stands only in a one-column cell; wide graphemes are never replaced by a glyph).
+ * Pure: (text, elapsed seconds, timing) -> cells.
+ */
+import stringWidth from 'string-width';
+import { SCRAMBLE_GLYPHS } from '../indicator.js';
+import { hash3 } from './color.js';
+import { graphemes } from '../textBuffer.js';
+
+export const LEAD = 0.14;
+/** Timings (seconds). row: tool rows, strongest. dim: grey lines (closing line, notes); short glow, never bold. */
+export const TIMING = {
+  row: { dur: 0.28, glow: 0.7, bold: true },
+  dim: { dur: 0.4, glow: 0.15, bold: false },
+  title: { dur: 0.3, glow: 0.35, bold: true },
+  roster: { dur: 0.3, glow: 0.3, bold: false },
+  settle: { dur: 0.2, glow: 0.5, bold: true },
+};
+export const revealSpan = (t) => t.dur + t.glow; // seconds from start until every cell is plain
+const KEEP = new Set([' ', '│', '─']); // structure only: a '·' separator arrives with its text, never floats ahead of it
+const TEXTISH = /^[\p{L}\p{N}\p{P}]+$/u;
+
+/**
+ * Cells for `text` at `elapsed` seconds since the reveal started.
+ * Each cell: { ch, kind: 'plain'|'kana'|'blank'|'glow', g (glow 0..1), bold }.
+ * offset/total let several segments of one row share one sweeping edge.
+ */
+export function revealCells(text, elapsed, timing = TIMING.row, { offset = 0, total = null, salt = 1 } = {}) {
+  const gs = graphemes(String(text ?? '')).map((g) => g.text);
+  const n = total ?? gs.length;
+  const bucket = Math.floor(elapsed * 30);
+  return gs.map((ch, j) => {
+    const i = offset + j;
+    // Only text decodes: letters, digits, punctuation. Icons and symbols (◐ ✔ ⚠ ⛓ ◉ …) never swap glyphs (owner 2026-10-12).
+    if (KEEP.has(ch) || !TEXTISH.test(ch)) return { ch, kind: 'plain', g: 0, bold: false };
+    const r = n > 1 ? (i / (n - 1)) * timing.dur : 0;
+    const dt = elapsed - r;
+    const w = stringWidth(ch);
+    if (dt < 0) {
+      if (w !== 1) return { ch: ' '.repeat(Math.max(1, w)), kind: 'blank', g: 0, bold: false };
+      if (dt < -LEAD) return { ch: ' ', kind: 'blank', g: 0, bold: false };
+      return { ch: SCRAMBLE_GLYPHS[Math.floor(hash3(i, bucket, salt) * SCRAMBLE_GLYPHS.length)], kind: 'kana', g: hash3(i, bucket + 7, salt), bold: false };
+    }
+    const g = timing.glow > 0 && dt < timing.glow ? (1 - dt / timing.glow) ** 1.6 : 0;
+    return g > 0 ? { ch, kind: 'glow', g, bold: Boolean(timing.bold) && (dt < 0.05 || g > 0.55) } : { ch, kind: 'plain', g: 0, bold: false };
+  });
+}
+
+/** True when the reveal has fully ended (all cells plain). */
+export const revealDone = (elapsed, timing) => elapsed >= revealSpan(timing);

package/lib/quoxon/motion/ring.js

@@ -0,0 +1,79 @@
+/**
+ * Composer ring (owner-approved lab prototype `quox-intro-lab rules`, plus the green writing sweep from
+ * `quox-intro-lab fx`). The two composer rules are one light ring: top rule left to right is the first half
+ * of the perimeter, bottom rule right to left the second. The gradient is the quox.ai panel ring:
+ * conic(cyan .85, purple .8 @35%, transparent @60%, teal .55 @85%, cyan .85). ~1 revolution / 2.5 s.
+ * Modes: work (cyan/purple), write (greens, while answer text streams), wait (slower amber, approval held).
+ * When the turn ends the sweep eases to a stop over ~400 ms. Pure state stepping; no timers here.
+ */
+import { mix, smooth, hexRgb } from './color.js';
+
+export const PALS = {
+  work: [[0x38, 0xbd, 0xf8], [0xa8, 0x55, 0xf7], [0x06, 0xb6, 0xd4]],
+  write: [[0x22, 0xc5, 0x5e], [0x4a, 0xde, 0x80], [0x16, 0xa3, 0x4a]],
+  wait: [[0xf5, 0x9e, 0x0b], [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]];
+export const DIM = [58, 66, 82];
+export const OMEGA = 360 / 2.5;             // deg/s while working
+export const SPEED = { work: 1, write: 1, wait: 0.3 };
+export const SETTLE_S = 0.4, RAMP_S = 0.15, BLEND_S = 0.2;
+
+export const initialRing = () => ({ phase: 'idle', angle: 0, k: 0, om: 0, wt: { work: 1, write: 0, wait: 0 }, at: null, settleAt: null, from: null });
+
+/** Colour + alpha of the ring at perimeter position u in [0,1) for palette weights wt. */
+export function ringAt(u, wt) {
+  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];
+  const t = (u - p0) / (p1 - p0 || 1);
+  const col = (c) => [0, 1, 2].map((ch) => wt.work * PALS.work[c][ch] + wt.write * PALS.write[c][ch] + wt.wait * PALS.wait[c][ch]);
+  const A = a0 + (a1 - a0) * t;
+  const pm = mix(col(c0).map((v) => v * a0), col(c1).map((v) => v * a1), t); // premultiplied: the clear stop does not tint
+  return [A ? pm.map((v) => v / A) : col(c0), A];
+}
+
+/**
+ * Advance the ring to time `now` (ms). active = a turn is running; mode = 'work' | 'write' | 'wait'.
+ * Returns a new state; `animating` tells the clock whether frames are still wanted.
+ */
+export function ringStep(prev, { active, mode = 'work', now }) {
+  const s = { ...(prev || initialRing()), wt: { ...(prev || initialRing()).wt } };
+  const dt = s.at == null ? 0 : Math.max(0, Math.min(0.25, (now - s.at) / 1000));
+  s.at = now;
+  if (active) {
+    if (s.phase !== 'run') s.phase = 'run';
+    s.om = OMEGA * (SPEED[mode] ?? 1);
+    s.k = Math.min(1, s.k + dt / RAMP_S);
+    for (const m of Object.keys(s.wt)) s.wt[m] += ((m === mode ? 1 : 0) - s.wt[m]) * Math.min(1, dt / BLEND_S);
+  } else if (s.phase === 'run') {
+    s.phase = 'settle'; s.settleAt = now; s.from = { om: s.om, k: s.k };
+  }
+  if (s.phase === 'settle') {
+    const p = (now - s.settleAt) / 1000 / SETTLE_S;
+    if (p >= 1) { s.phase = 'idle'; s.k = 0; s.om = 0; } else { s.om = s.from.om * (1 - p) ** 2; s.k = s.from.k * (1 - smooth(p)); }
+  }
+  s.angle = (s.angle + s.om * dt) % 360;
+  return s;
+}
+export const ringAnimating = (s) => Boolean(s) && s.phase !== 'idle';
+
+/** Per-cell rgb for one rule of `cols` cells. base = the rule's static colour (hex or rgb). Pure. */
+export function ruleColors(cols, top, s, base) {
+  const b = Array.isArray(base) ? base : hexRgb(base);
+  const out = new Array(cols);
+  for (let x = 0; x < cols; x++) {
+    if (!s || s.k <= 0) { out[x] = b; continue; }
+    const pos = top ? (x + 0.5) / (2 * cols) : (cols + (cols - 1 - x) + 0.5) / (2 * cols);
+    const u = (((pos - s.angle / 360) % 1) + 1) % 1;
+    const [c, a] = ringAt(u, s.wt);
+    out[x] = mix(b, mix(DIM, c, a), s.k);
+  }
+  return out;
+}
+
+/** Which ring mode a live turn is in, from what the client actually knows. */
+export function ringMode({ approvals = 0, act = null } = {}) {
+  if (approvals > 0 || act?.tone === 'wait') return 'wait';
+  if (act?.word === 'Writing') return 'write';
+  return 'work';
+}

package/lib/quoxon/objects/agent.js

@@ -0,0 +1,61 @@
+/**
+ * E4 agent card. Sources: the shipped assistant identity (name, tagline), the org agent record
+ * (description, status, model when its config carries one), the collector's agent -> tools map
+ * (GET /api/v1/tools/agents), slots (GET /api/v1/slots: a slot named after the agent, or assigned
+ * to it), and the agent's last AEE envelope (GET /aee/query?from=agent.<id>&limit=1) with its WARD
+ * receipt when verify-receipt answered. There is no per-agent model in the shipped config (models
+ * are routed per turn), so the model row appears only when the server record names one.
+ */
+import { seg, fit, ago, short, boxWidth } from './model.js';
+import { providerOf } from '../theme.js';
+
+/** The model an org agent record names, if any: config_json.{model,provider}. */
+export function modelOf(record) {
+  let cfg = record?.config_json ?? record?.config ?? null;
+  if (typeof cfg === 'string') { try { cfg = JSON.parse(cfg); } catch { cfg = null; } }
+  const model = cfg?.model || cfg?.llm?.model || null;
+  const provider = cfg?.provider || cfg?.llm?.provider || null;
+  return model || provider ? { model, provider } : null;
+}
+
+/** A slot belongs to an agent when it is named after it or assigned to it. */
+export function slotFor(slots, id) {
+  const n = String(id || '').toLowerCase();
+  return (slots || []).find(s => String(s.name || '').toLowerCase() === n || String(s.assigned_to || '').toLowerCase() === n) || null;
+}
+
+/**
+ * d: { id, name, tagline, description, status, record, tools: [] | null, slot, last: envelope | null,
+ *      lastErr, receipt: { ok, result } | null, now }
+ */
+export function agentCard(d, cols) {
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 72), inner = w - 4, nw = w < 56;
+  const nm = String(d.name || d.id || 'agent');
+  const tag = d.tagline ? (nw ? '' : ` · ${d.tagline}`) : '';
+  const right = d.slot ? (nw ? `slot ${d.slot.name}` : `slot ${d.slot.name} · ${d.slot.state || 'unknown'}`) : '';
+  const rows = [];
+  const L = (label, value, role = 'value') => [seg(label.padEnd(6), 'muted'), ...(Array.isArray(value) ? value : [seg(fit(value, inner - 6), role)])];
+  if (d.description) rows.push(L('role', d.description));
+  if (d.status && d.status !== 'active') rows.push(L('state', d.status, 'warn'));
+  const m = modelOf(d.record);
+  if (m) {
+    const p = providerOf(m.provider, m.model);
+    rows.push(L('model', [seg(fit(m.model || m.provider, inner - 6), p ? `provider:${p}` : 'value')]));
+  }
+  if (Array.isArray(d.tools)) rows.push(L('tools', d.tools.length ? `${d.tools.length}: ${d.tools.join(', ')}` : 'none assigned'));
+  else if (d.toolsErr) rows.push(L('tools', `could not read (${d.toolsErr})`, 'warn'));
+  if (d.slot?.holder_session && d.slot.state === 'held') rows.push(L('held', `by ${d.slot.holder_session}${d.slot.last_heartbeat_at ? ` · heartbeat ${ago(d.slot.last_heartbeat_at, now)} ago` : ''}`, 'muted'));
+  if (d.last) {
+    const what = d.last.payload?.tool_name || d.last.intent || 'action';
+    const when = d.last.ts ? `${ago(d.last.ts, now)} ago` : '';
+    const r = d.receipt?.ok ? d.receipt.result : null;
+    if (r?.status === 'WITNESSED') rows.push(L('last', [seg('◉ ', 'proto:ward'), seg(fit(`${what} · WARD seq ${r.entry?.seq} witnessed · ${when}`, inner - 8), 'muted')]));
+    else {
+      const w8 = r?.status === 'NOT_WITNESSED' ? 'not witnessed yet' : r?.status === 'UNTIPPED' ? `WARD seq ${r.entry?.seq}, no signed tip yet` : d.receipt && !d.receipt.ok ? 'WARD did not answer' : 'witness not checked';
+      rows.push(L('last', [seg('· ', 'muted'), seg(fit(`${what} · ${w8} · ${when} · ${short(d.last.id, 14)}`, inner - 8), 'muted')]));
+    }
+  } else if (d.lastErr) rows.push(L('last', `could not read (${d.lastErr})`, 'warn'));
+  else rows.push(L('last', 'no recorded action', 'muted'));
+  return { box: { width: w, title: `● ${nm.toUpperCase()}${tag}`, titleRole: `agent:${d.id || nm}`, right, rightRole: 'muted', border: 'violet' }, rows };
+}

package/lib/quoxon/objects/crystal.js

@@ -0,0 +1,100 @@
+/**
+ * E3 Crystal eligibility, computed from a workflow's REAL execution history against quoxflow's
+ * crystalliser gate. There is no read-only eligibility route (POST /api/skills/from-execution is the
+ * check AND the crystallisation, a write), so the rule is ported here verbatim from
+ * quoxflow/src/pipeline/crystalliser.ts (analyseExecutionHistory + extractVariables):
+ *   >= 3 executions, >= 80% success, and every successful run follows one action sequence.
+ * Input mirrors that route's legacy path: completed + failed executions; a run's action log is
+ * output.action_log when the run recorded one, else the workflow definition's nodes (the route's
+ * synthetic log). The quoxflow route also reads its own execution-history table, which this
+ * client cannot see, so the card says what it counted.
+ */
+import { seg, fit, short, boxWidth, plural } from './model.js';
+
+export const MIN_EXECUTIONS = 3;
+export const MIN_SUCCESS_RATE = 0.8;
+
+/** crystalliser.ts analyseExecutionHistory, same order of checks and same reasons. */
+export function analyseExecutionHistory(executions) {
+  const count = executions.length;
+  const successCount = executions.filter(e => e.success).length;
+  const successRate = count > 0 ? successCount / count : 0;
+  if (count < MIN_EXECUTIONS) return { ready: false, reason: `Insufficient executions (${count}/${MIN_EXECUTIONS} required)`, confidence: 0, executionCount: count, successRate };
+  if (successRate < MIN_SUCCESS_RATE) return { ready: false, reason: `Low success rate (${(successRate * 100).toFixed(0)}% < ${MIN_SUCCESS_RATE * 100}% required)`, confidence: 0, executionCount: count, successRate };
+  const signatures = new Set(executions.filter(e => e.success).map(e => e.actionLog.map(a => a.action).join(',')));
+  if (signatures.size > 1) return { ready: false, reason: `Inconsistent action structure across runs (${signatures.size} different patterns)`, confidence: 0, executionCount: count, successRate };
+  const confidence = Math.min(Math.min(count / 10, 1) * 0.3 + successRate * 0.5 + 0.2, 1.0);
+  return { ready: true, confidence, executionCount: count, successRate };
+}
+
+/** crystalliser.ts extractVariables: params that vary between successful runs, by action position. */
+export function extractVariables(executions) {
+  const ok = executions.filter(e => e.success && e.actionLog.length > 0);
+  if (ok.length < 2) return [];
+  const vars = [];
+  ok[0].actionLog.forEach((first, idx) => {
+    for (const key of Object.keys(first.params || {})) {
+      const values = ok.map(e => e.actionLog[idx]?.params?.[key]).filter(v => v !== undefined);
+      if (new Set(values.map(v => JSON.stringify(v))).size > 1) vars.push({ name: key, values });
+    }
+  });
+  return vars;
+}
+
+/** Real executions (+ optional definition) -> crystalliser ExecutionRecords. */
+export function toRecords(executions, def) {
+  const synthetic = Array.isArray(def?.nodes) ? def.nodes.map(n => ({ action: n.type, params: n.config ?? n.data ?? {} })) : null;
+  return executions
+    .filter(e => e && (e.status === 'completed' || e.status === 'failed'))
+    .map(e => {
+      const log = Array.isArray(e.output?.action_log) ? e.output.action_log.map(a => ({ action: a.action, params: a.params || {} })) : synthetic;
+      return { id: e.id, success: e.status === 'completed', actionLog: log || [], logKnown: Array.isArray(e.output?.action_log) };
+    });
+}
+
+/** Successful runs still needed so both the count and the rate pass (consecutive successes from now). */
+export function runsNeeded(count, successes) {
+  for (let k = 0; k < 10000; k++) {
+    const n = count + k, s = successes + k;
+    if (n >= MIN_EXECUTIONS && s / n >= MIN_SUCCESS_RATE) return k;
+  }
+  return null;
+}
+
+/**
+ * d: { workflow: { id, name }, executions: [...completed and failed], def }
+ * -> view { box, rows }
+ */
+export function crystalCard(d, cols) {
+  const w = boxWidth(cols, 66), inner = w - 4, nw = w < 58;
+  const wf = d.workflow || {};
+  const recs = toRecords(d.executions || [], d.def);
+  const a = analyseExecutionHistory(recs);
+  const n = recs.length, s = recs.filter(r => r.success).length;
+  const pct = n ? Math.round((s / n) * 100) : 0;
+  const okRuns = recs.filter(r => r.success);
+  const sigs = new Set(okRuns.map(r => r.actionLog.map(x => x.action).join(',')));
+  const unknownLogs = okRuns.some(r => !r.logKnown);
+  const rows = [];
+  const check = (pass, name, value) => [seg(pass === null ? '○' : pass ? '✔' : '✖', pass === null ? 'faint' : pass ? 'ok' : 'warn'), seg(' '), seg(name.padEnd(nw ? 10 : 14), pass === null ? 'muted' : 'value'), seg(fit(value, inner - (nw ? 12 : 16)), 'muted')];
+  rows.push(check(n >= MIN_EXECUTIONS, 'runs', nw ? `${n} (needs ≥ ${MIN_EXECUTIONS})` : `${n}`.padEnd(11) + `needs ≥ ${MIN_EXECUTIONS}`));
+  rows.push(check(n ? s / n >= MIN_SUCCESS_RATE : false, nw ? 'success' : 'success rate', nw ? `${pct}% ${s}/${n} (≥ 80%)` : `${pct}%  ${s}/${n}  needs ≥ 80%`));
+  if (!okRuns.length) rows.push(check(null, 'structure', 'no successful run to compare'));
+  else if (unknownLogs && sigs.size === 1) rows.push(check(true, 'structure', nw ? `${okRuns.length}/${okRuns.length} same steps` : `${okRuns.length}/${okRuns.length} same steps (definition, no run log)`));
+  else rows.push(check(sigs.size === 1, 'structure', sigs.size === 1 ? (nw ? `${okRuns.length}/${okRuns.length} identical` : `${okRuns.length}/${okRuns.length} runs, identical action sequence`) : `${sigs.size} different action patterns`));
+  const vars = a.ready ? extractVariables(recs) : [];
+  if (a.ready) rows.push(check(true, 'variables', vars.length ? `${vars.map(v => v.name).join(', ')}${nw ? '' : ' (vary between runs)'}` : 'none vary between runs'));
+
+  const crystal = (d.executions || []).find(e => e?.output?.crystal_id);
+  let verdict;
+  if (crystal) verdict = [seg(fit(`Already runs as Crystal ${short(crystal.output.crystal_id, 10)}${crystal.output.execution_mode ? ` (${crystal.output.execution_mode} replay)` : ''}`, inner), 'teal', true)];
+  else if (a.ready) verdict = [seg(nw ? 'Eligible · meets the gate' : 'Eligible · meets the crystalliser gate', 'teal', true)];
+  else if (/Inconsistent/.test(a.reason || '')) verdict = [seg(fit(`Not eligible: runs follow ${sigs.size} different action patterns`, inner), 'warn', true)];
+  else {
+    const k = runsNeeded(n, s);
+    verdict = [seg(fit(k == null ? `Not eligible yet: ${a.reason}` : `Not eligible yet: needs ${plural(k, 'more successful run')}`, inner), 'warn', true)];
+  }
+  rows.push(verdict);
+  rows.push([seg(fit(nw ? `from ${plural(n, 'recorded run')}` : `from ${plural(n, 'recorded run')} · quoxflow's rule, ≤ 500 per status`, inner), 'faint')]);
+  return { box: { width: w, title: nw ? 'Crystal candidate' : `Crystal candidate · ${wf.name || wf.id || ''}`, right: '', border: 'teal' }, rows, analysis: a };
+}