quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/modelPrefs.js

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

package/lib/quoxon/motion/clock.js

@@ -0,0 +1,70 @@
+/**
+ * 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).
+ */
+import { normaliseLevel } from './level.js';
+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 at the quiet level (QUOX_MOTION=quiet, QUOX_REDUCED_MOTION=1, QUOX_TUI_LITE), or when not on a real terminal. Colour is separate (NO_COLOR). */
+export const reducedMotion = (env = process.env) => env.QUOX_REDUCED_MOTION === '1' || Boolean(env.QUOX_TUI_LITE) || normaliseLevel(env.QUOX_MOTION) === 'quiet';
+export const motionAllowed = (isTTY, env = process.env) => Boolean(isTTY) && !reducedMotion(env);
+
+/**
+ * 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/level.js

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

package/lib/quoxon/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);