quoxcli 0.2.0 → 0.4.0

package/vendor/dragonlab/vendor/quox-dragon/qart.js

@@ -0,0 +1,348 @@
+/**
+ * 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. 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, bg? }` (rgb null = default colour; bg, when
+ * present, a background colour: the dragon's eyes in qdragon.js use it). 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, bg = false) => `\x1b[${bg ? 48 : 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. A cell may
+ * also carry `bg` (the dragon's eyes are quadrant blocks with a foreground AND a background colour); a
+ * background run is closed with a reset before the next cell without one, so it never bleeds. Cells without
+ * bg render exactly as they always have.
+ */
+export function cellsToAnsi(rows) {
+  return rows.map((row) => {
+    let s = '', last = '', lastBg = '';
+    for (const c of row) {
+      const b = c.bg ? sgr(c.bg, true) : '';
+      if (lastBg && !b) { s += RESET; last = ''; lastBg = ''; }
+      if (c.rgb) { const e = sgr(c.rgb); if (e !== last) { s += e; last = e; } }
+      else if (last && c.ch !== ' ') { s += RESET; last = ''; if (lastBg) lastBg = ''; }
+      if (b && b !== lastBg) { s += b; lastBg = b; }
+      s += c.ch;
+    }
+    return s + (last || lastBg ? 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);
+}
+
+// ---- 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 the settled Q. Returns { ms, at(t) -> cells }. Callers drive t
+ * from their own clock.
+ */
+export function introPlan(size, opts = {}) {
+  return {
+    ms: INTRO_MS,
+    at(t) {
+      if (t < INTRO_MS) return orbitCellsAt(size, t, opts);
+      return qCells(size, opts);
+    },
+  };
+}

package/vendor/dragonlab/vendor/quox-dragon/qeyes.js

@@ -0,0 +1,213 @@
+// Quox eyes (canonical source: quox cli/lib/quoxon/qeyes.js; the cli.quox.ai site vendors this file as is).
+// Two friendly cartoon eyes in the Q's own terminal cell pipeline, so the web (cellsToHTML) and the
+// terminal (cellsToAnsi) draw identical eyes. Two techniques, both terminal-safe:
+//   dots    Braille dots (the Q's own particles): a closed disc of white dots, a pupil of UNLIT dots (the
+//           background shows through, so it reads black), a 2x2 dot glint, and a 2-dot arc when closed.
+//   blocks  Unicode quadrant blocks with a foreground AND a background colour (as qdragon's eye layer).
+// Plus motion as pure functions of time: blink, look around, idle (eyeState).
+//
+// PURE AND PORTABLE: no DOM, no timers, no Node APIs. A function of (geometry, state) or (mode, t).
+// The left eye is computed once and the right eye is the same eye TRANSLATED (both centres snapped to even
+// dots, so both sit on the same Braille cell phase): the two always match, and both pupils look the same way.
+// Compositing is per cell: a cell inside an eye's footprint is drawn from the eye layer only, so a Q dot never
+// shares a cell (and its one colour) with an eye. The Q itself is never redrawn.
+//
+// Geometry is the Q's own unit space (qart.js): y 0..1 down the Q, x 0..0.82, the bowl's axis at x 0.41.
+
+const AXIS = 0.41;
+const BR = [[0x1, 0x8], [0x2, 0x10], [0x4, 0x20], [0x40, 0x80]];
+const QUAD = [' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛', '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█'];
+export const EYE_WHITE = [255, 255, 255]; // pure white (owner: whiter whites)
+export const EYE_PUPIL = [10, 12, 18];
+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); };
+
+/**
+ * The owner's pick ("big and googly"). r, sep, y in Q units. pupil: pupil radius as a share of r. rest: where the
+ * pupils rest (gaze -1..1; a little down reads as "looking at you"). rim: the least white (dots) kept round the
+ * pupil at every gaze. glint: the 2x2 glint's offset from the pupil centre, as a share of the pupil radius (out
+ * towards the upper left, near the pupil's edge, so it reads as a highlight and not a bullseye). sag: closed lid.
+ */
+export const GOOGLY = { r: 0.104, sep: 0.124, y: 0.53, ox: 0.95, oy: 1.02, pupil: 0.46, rest: [0, 1], rim: 2, glint: 0.62, sag: 0.34 };
+/** Variant A of the bullseye fix (rejected by screenshot: the thinner rim still read as a donut). */
+export const GOOGLY_A = { ...GOOGLY, pupil: 0.52 };
+/** The v2 dots (before the bullseye fix): smaller pupil, glint near its centre. Kept for comparison. */
+export const GOOGLY_V2 = { ...GOOGLY, pupil: 0.43, glint: 0.45, rest: [0, 0.6] };
+
+function centres(geo, v) {
+  const R = v.r * geo.Hq, axis = 2 * Math.round((geo.ox + AXIS * geo.Hq) / 2), cy = (geo.oy ?? 0) + v.y * geo.Hq;
+  const cxL = axis - 2 * Math.ceil((v.sep * geo.Hq) / 2);
+  return { R, cy, cxL, shift: 2 * (axis - cxL) }; // right eye = left eye + shift (an even number of dots)
+}
+
+/** The left eye in dot units: f(x, y) -> 0 none | 1 white | 2 pupil | 3 glint, for an open eye. */
+function eyeShape(cx, cy, R, v, open, gx, gy) {
+  const rx = R * v.ox, ry = R * v.oy, pr = R * v.pupil;
+  const lidY = cy - ry + (1 - open) * 2 * ry * 0.92; // the upper lid: everything above it is closed
+  // the pupil travels inside the white, shrunk by its radius plus the rim, and snaps to whole dots
+  const ax = Math.max(0, rx - pr - v.rim), ay = Math.max(0, ry - pr - v.rim), n = Math.hypot(gx, gy), s = n > 1 ? 1 / n : 1;
+  const px = cx + Math.trunc(gx * s * ax), py = cy + Math.trunc(gy * s * ay); // truncate: never into the rim
+  const glint = pr >= 2.6, g = pr * v.glint * 0.75, gx0 = Math.round(px - g), gy0 = Math.round(py - g); // up-left, a dark dot clear of the rim
+  return (x, y) => {
+    if (((x - cx) / rx) ** 2 + ((y - cy) / ry) ** 2 > 1 || y < lidY) return 0;
+    if (y < lidY + 2) return 1; // the lid's edge: a 2-dot white line
+    if (Math.hypot(x - px, y - py) > pr) return 1;
+    if (glint && Math.floor(x) >= gx0 && Math.floor(x) <= gx0 + 1 && Math.floor(y) >= gy0 && Math.floor(y) <= gy0 + 1) return 3;
+    return 2;
+  };
+}
+/** The closed lid's centre line y(x) (an arc bowed upwards, like a shut lid; owner flipped it from a smile) and its half-width, in dot units. */
+function lid(cx, cy, R, v) {
+  const w = R * v.ox * 0.88, d = R >= 6 ? R * v.sag : 0.6, y0 = cy - d / 2;
+  return { n: Math.round(w), y: (x) => { const u = (x - cx) / w; return y0 + d * u * u; } };
+}
+
+/** Footprint: the cells each eye owns (its white ellipse plus a little margin), as a Uint8Array cols*rows. */
+function footprint(geo, v) {
+  const { R, cy, cxL, shift } = centres(geo, v), foot = new Uint8Array(geo.cols * geo.rows);
+  for (const cx of [cxL, cxL + shift]) for (let r = 0; r < geo.rows; r++) for (let c = 0; c < geo.cols; c++) {
+    const x = c * 2 + 1, y = r * 4 + 2;
+    if (((x - cx) / (R * v.ox + 0.4)) ** 2 + ((y - cy) / (R * v.oy + 0.4)) ** 2 <= 1) foot[r * geo.cols + c] = 1;
+  }
+  return foot;
+}
+const gaze = (state, v) => [state.gx ?? v.rest[0], state.gy ?? v.rest[1]];
+
+// ---- dots ---------------------------------------------------------------------------------------------------
+/** Lit dots of both eyes on the W x H dot grid (Uint8Array, 1 = lit). state: { open 0..1, gx, gy -1..1 }. */
+export function eyeDots(geo, state = {}, v = GOOGLY) {
+  const W = geo.cols * 2, H = geo.rows * 4, lit = new Uint8Array(W * H);
+  const { R, cy, cxL, shift } = centres(geo, v), open = clamp(state.open ?? 1);
+  const set = (x, y) => { for (const xx of [x, x + shift]) if (xx >= 0 && y >= 0 && xx < W && y < H) lit[y * W + xx] = 1; };
+  if (open < 0.15) {
+    const L = lid(cxL, cy, R, v); // one clean arc, 2 dots thick, symmetric about the eye centre
+    for (let x = cxL - L.n; x < cxL + L.n; x++) { const y = Math.round(L.y(x + 0.5) - 0.5); set(x, y); set(x, y + 1); }
+    return lit;
+  }
+  const [gx, gy] = gaze(state, v), f = eyeShape(cxL, cy, R, v, open, gx, gy);
+  for (let y = Math.floor(cy - R * 2); y <= Math.ceil(cy + R * 2); y++) for (let x = Math.floor(cxL - R * 2); x <= Math.ceil(cxL + R * 2); x++) {
+    const k = f(x + 0.5, y + 0.5);
+    if (k === 1 || k === 3) set(x, y);
+  }
+  return lit;
+}
+
+/** The dot eye layer: rows of cells (null = no eye here). */
+export function eyeCells(geo, state, v = GOOGLY) {
+  const W = geo.cols * 2, lit = eyeDots(geo, state, v), foot = footprint(geo, v), rows = [];
+  for (let r = 0; r < geo.rows; r++) {
+    const row = [];
+    for (let c = 0; c < geo.cols; c++) {
+      let bits = 0;
+      for (let dy = 0; dy < 4; dy++) for (let dx = 0; dx < 2; dx++) if (lit[(r * 4 + dy) * W + c * 2 + dx]) bits |= BR[dy][dx];
+      row.push(bits ? { ch: String.fromCharCode(0x2800 + bits), rgb: EYE_WHITE } : foot[r * geo.cols + c] ? { ch: ' ', rgb: null } : null);
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+// ---- blocks (reference) -------------------------------------------------------------------------------------
+/** The block eye layer: 2x2 quadrant pixels per cell (a pixel is 1 dot wide, 2 tall), fg + bg colours. */
+export function blockEyeCells(geo, state = {}, v = GOOGLY) {
+  const PW = geo.cols * 2, PH = geo.rows * 2, px = new Uint8Array(PW * PH); // 0 none, 1 white, 2 pupil
+  const { R, cy, cxL, shift } = centres(geo, v), open = clamp(state.open ?? 1);
+  const put = (x, y, k) => { for (const xx of [x, x + shift]) if (xx >= 0 && y >= 0 && xx < PW && y < PH) px[y * PW + xx] = k; };
+  if (open < 0.15) {
+    const L = lid(cxL, cy, R, v);
+    for (let x = cxL - L.n; x < cxL + L.n; x++) put(x, Math.floor(L.y(x + 0.5) / 2), 1);
+  } else {
+    const [gx, gy] = gaze(state, v), f = eyeShape(cxL, cy, R, { ...v, pupil: 0.43 }, open, gx, gy), small = R < 6;
+    for (let y = Math.floor((cy - R * 2) / 2); y <= Math.ceil((cy + R * 2) / 2); y++) for (let x = Math.floor(cxL - R * 2); x <= Math.ceil(cxL + R * 2); x++) {
+      const k = f(x + 0.5, y * 2 + 1);
+      if (k) put(x, y, k === 3 ? 1 : k === 2 && small ? 1 : k);
+    }
+    if (small) { const pr0 = Math.round(cy / 2); for (const x of [cxL - 1, cxL]) for (const y of [pr0 - 1, pr0]) put(x, y, 2); }
+  }
+  const foot = footprint(geo, v), rows = [];
+  for (let r = 0; r < geo.rows; r++) {
+    const row = [];
+    for (let c = 0; c < geo.cols; c++) {
+      const q = [px[(r * 2) * PW + c * 2], px[(r * 2) * PW + c * 2 + 1], px[(r * 2 + 1) * PW + c * 2], px[(r * 2 + 1) * PW + c * 2 + 1]];
+      if (!q.some((k) => k)) { row.push(foot[r * geo.cols + c] ? { ch: ' ', rgb: null } : null); continue; }
+      let m = 0; q.forEach((k, i) => { if (k === 1) m |= 1 << i; });
+      if (q.includes(1)) row.push({ ch: QUAD[m], rgb: EYE_WHITE, bg: q.includes(2) ? EYE_PUPIL : null });
+      else row.push({ ch: '█', rgb: EYE_PUPIL });
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+// ---- motion: pure functions of time ---------------------------------------------------------------------------
+export const BLINK_MS = 200;
+/** Lid openness u ms into a blink: shut in 70 ms, held 40, open again by 200. */
+export function blinkOpen(u) {
+  if (u < 0 || u >= BLINK_MS) return 1;
+  if (u < 70) return 1 - smooth(u / 70);
+  if (u < 110) return 0;
+  return smooth((u - 110) / 90);
+}
+const hash = (n) => { let x = Math.imul((n | 0) ^ 0x9e3779b9, 0x85ebca6b); x ^= x >>> 13; x = Math.imul(x, 0xc2b2ae35); x ^= x >>> 16; return (x >>> 0) / 4294967296; };
+// keyframes [[ms, [gx, gy]], ...], eased between neighbours, held at the ends
+function gazeKf(t, keys) {
+  if (t <= keys[0][0]) return keys[0][1];
+  for (let i = 0; i < keys.length - 1; i++) {
+    const [t0, a] = keys[i], [t1, b] = keys[i + 1];
+    if (t < t1) { const e = smooth((t - t0) / (t1 - t0)); return [a[0] + (b[0] - a[0]) * e, a[1] + (b[1] - a[1]) * e]; }
+  }
+  return keys[keys.length - 1][1];
+}
+const REST = GOOGLY.rest;
+/** Look around: centre, left, right, up, down, centre; 260 ms moves, 600 ms holds. */
+export const LOOK_KEYS = (() => {
+  const pts = [REST, [-1, 0.2], [1, 0.2], [0, -1], [0, 1], REST], keys = [];
+  let t = 0;
+  for (const p of pts) { keys.push([t, p]); t += 600; keys.push([t, p]); t += 260; }
+  return keys;
+})();
+export const LOOK_MS = LOOK_KEYS[LOOK_KEYS.length - 1][0] + 400;
+
+/**
+ * The eyes' state at t ms for a mode: 'open' | 'closed' | 'blink' | 'look' | 'idle'. Returns { open, gx, gy }.
+ *   blink  a blink every 1.6 s; every third one is a double blink.
+ *   look   the look-around loop (LOOK_KEYS).
+ *   idle   blinks every 2.6 to 5 s (one in five a double), and now and then a glance that holds and returns.
+ */
+export function eyeState(mode, t) {
+  if (mode === 'closed') return { open: 0, gx: REST[0], gy: REST[1] };
+  if (mode === 'open' || t < 0) return { open: 1, gx: REST[0], gy: REST[1] };
+  if (mode === 'blink') {
+    const k = Math.floor(t / 1600), u = t - k * 1600;
+    return { open: Math.min(blinkOpen(u - 300), k % 3 === 2 ? blinkOpen(u - 560) : 1), gx: REST[0], gy: REST[1] };
+  }
+  if (mode === 'look') { const [gx, gy] = gazeKf(t % LOOK_MS, LOOK_KEYS); return { open: 1, gx, gy }; }
+  // idle: a seeded schedule of events, each 2.6 to 5 s long, so any t maps to the same frame
+  let start = 0, i = 0;
+  for (;;) { const len = 2600 + hash(i * 7 + 1) * 2400; if (t < start + len) break; start += len; i++; if (i > 100000) break; }
+  const u = t - start, len = 2600 + hash(i * 7 + 1) * 2400;
+  let open = 1, g = REST;
+  if (hash(i * 7 + 2) < 0.4) {
+    // a glance: move in 240 ms, hold, come back before the event ends
+    const dir = [[-1, 0.2], [1, 0.2], [-0.8, -0.7], [0.8, -0.7], [0, 1]][Math.floor(hash(i * 7 + 3) * 5)];
+    g = gazeKf(u, [[300, REST], [540, dir], [540 + 900, dir], [540 + 900 + 260, REST]]);
+  }
+  const b = len - 700; // the blink near the end of each event
+  open = Math.min(blinkOpen(u - b), hash(i * 7 + 4) < 0.2 ? blinkOpen(u - b - 260) : 1);
+  return { open, gx: g[0], gy: g[1] };
+}
+
+// ---- compose ------------------------------------------------------------------------------------------------
+/** Composite: eye cells over base cells (same grid). Base cells are untouched wherever the eye layer is null. */
+export function overlay(base, eyes) {
+  return base.map((row, r) => row.map((cell, c) => (eyes[r] && eyes[r][c]) || cell));
+}
+const layer = (style) => (style === 'blocks' ? blockEyeCells : eyeCells);
+/** Eyes for the settled qart Q, given its mask ({ W, H, ox } from qMask). style: 'dots' | 'blocks'. */
+export function eyesForQ(mask, state, v = GOOGLY, style = 'dots') {
+  return layer(style)({ cols: mask.W / 2, rows: mask.H / 4, ox: mask.ox, Hq: mask.H }, state, v);
+}
+/** Eyes for a qdragon layout ({ cols, rows, qx0, qy0, H }). */
+export function eyesForDragon(L, state, v = GOOGLY, style = 'dots') {
+  return layer(style)({ cols: L.cols, rows: L.rows, ox: L.qx0, oy: L.qy0, Hq: L.H }, state, v);
+}