quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/qdragonScenes.js

@@ -0,0 +1,282 @@
+/**
+ * Dragon scenes: pure timelines t (ms) -> { pose, eyes, caption }. No timers, no I/O (portable to the web).
+ * ONE dragon everywhere (v8): googly dot eyes (qeyes.js), a smile that opens to talk, pink cheeks, dim bat wings,
+ * a spade tail with spines, fire from the mouth. /dragon (the pick), /dragon classic, hero and fire, the cinematic
+ * moods, the greeting and /dragon-fly are all this dragon; moods are shown through the eyes and the smile only.
+ */
+import { restPose, kf, hash, clamp, smooth, dragonLayout, renderDragon } from './qdragon.js';
+import { eyesForDragon, eyeState, blinkOpen, overlay, GOOGLY } from './qeyes.js';
+
+const TAU = Math.PI * 2;
+
+// ---- the pick: googly dot eyes, sway sway sway whip, then fire from the mouth (ported from cli.quox.ai) -------
+// The same pure functions the website lab plays (src/components/lab/dragon/dragonlab.js pickCells), so the CLI
+// and the web draw the same frames. Eyes are qeyes.js Braille dots (Dots v3), laid over the dragon by composeCells:
+// they are the dragon's only eyes.
+export const SWAY_MS = TAU / 0.0068; // one sway cycle (about 924 ms)
+export const PICK = { sway: 3 * SWAY_MS, whip: 950, fire: 2500, rest: 700 };
+export const PICK_EYES = 'dots';
+export const PICK_MS = PICK.sway + PICK.whip + PICK.fire + PICK.rest;
+/** Which phase of the pick t (ms) falls in: 'sway' | 'whip' | 'fire' | 'rest'. */
+export function pickPhase(t) {
+  const c = ((t % PICK_MS) + PICK_MS) % PICK_MS, w0 = PICK.sway, f0 = w0 + PICK.whip, r0 = f0 + PICK.fire;
+  return c < w0 ? 'sway' : c < f0 ? 'whip' : c < r0 ? 'fire' : 'rest';
+}
+/** The eyes at t: shut (open 0) while it breathes, otherwise the idle blinks and glances. */
+export function pickEyeState(t) {
+  const c = ((t % PICK_MS) + PICK_MS) % PICK_MS, ft = c - PICK.sway - PICK.whip;
+  return pickPhase(t) === 'fire' && ft > 120 && ft < 1500 ? { open: 0 } : eyeState('idle', t);
+}
+/** The dragon's pose (no quadrant eyes) at absolute time t. */
+export function pickPose(t) {
+  const p = restPose(), c = ((t % PICK_MS) + PICK_MS) % PICK_MS;
+  p.tail.len = 1.55; p.tail.k = 3.2; p.tail.phase = t * 0.0068;
+  const w0 = PICK.sway, f0 = w0 + PICK.whip, r0 = f0 + PICK.fire;
+  if (c < w0) p.tail.amp = 0.6 + 1.6 * smooth(c / 350);
+  else if (c < f0) {
+    const u = (c - w0) / PICK.whip, crack = smooth(u / 0.2) * (1 - smooth((u - 0.35) / 0.55));
+    p.tail.amp = 2.2 + 2.8 * crack; p.tail.phase += crack * 4; p.tail.k = 3.2 + 2.8 * crack; p.tail.curl = 0.8 * crack;
+  } else if (c < r0) {
+    const ft = c - f0;
+    p.tail.amp = 2.2 - 1.6 * smooth(ft / 600);
+    p.mouth = smooth(ft / 160) * (1 - smooth((ft - 1500) / 500));
+    p.fire = { t: ft, dur: 1300, seed: 3 };
+  } else p.tail.amp = 0.6;
+  return p;
+}
+const EYES2 = GOOGLY; // the owner's eyes, unchanged: every scene, mood, greeting and the flight use them
+const INK = [30, 41, 59]; // eye ink on the light theme (white would vanish on a light page)
+/**
+ * The pick at t ms. opts: style ('dots'), theme, mono (NO_COLOR: no colour), still (reduced motion: the settled
+ * dragon, eyes open, no tail motion, no fire). Cells are { ch, rgb, bg } like every other clip.
+ */
+export function pickCells(t, cols = 64, style = PICK_EYES, { theme = 'dark', mono = false, still = false, size, lm, mouthSide = 'right', talk } = {}) {
+  const L = dragonLayout(cols, { size, lm });
+  let pose, eyes;
+  if (still) { pose = restPose(); eyes = eyeState('open', 0); }
+  else if (talk) { pose = talkPose(t, talk); eyes = eyeState('idle', t); } // talking: the pick's calm sway, the mouth working, no fire
+  else { pose = pickPose(t); eyes = pickEyeState(t); }
+  pose.mouthSide = mouthSide;
+  return composeCells(pose, eyes, L, style, { theme, mono, t });
+}
+/** Body (renderDragon) with the Braille googly eyes laid over it: the one way a dragon frame is made. */
+export function composeCells(pose, eyes, L, style, { theme, mono, t }) {
+  const body = renderDragon(pose, L, { mono, t, theme });
+  const layer = eyesForDragon(L, eyes, EYES2, style).map((row) => row.map((c) => c && {
+    ch: c.ch, bg: null, rgb: !c.rgb || mono ? null : theme === 'light' ? INK : c.rgb,
+  }));
+  return overlay(body, layer);
+}
+/** How open the mouth is at t while it talks: 0..1, a deterministic syllable cadence (about 6 a second, with the odd pause). */
+export const TALK_SYLLABLE_MS = 160;
+export function talkOpen(t) {
+  const k = Math.floor(t / TALK_SYLLABLE_MS), u = (t - k * TALK_SYLLABLE_MS) / TALK_SYLLABLE_MS;
+  if (hash(k * 5 + 3) < 0.14) return 0; // a pause between words
+  return (0.45 + 0.55 * hash(k * 7 + 11)) * Math.sin(Math.PI * u) ** 0.8;
+}
+/** The pose while it talks: calm tail sway, the mouth open by `talk` (a 0..1 number, or true for the cadence), no fire, no glow. */
+export function talkPose(t, talk = true) {
+  const p = restPose();
+  p.tail.len = 1.55; p.tail.k = 3.2; p.tail.phase = t * 0.0068; p.tail.amp = 0.6;
+  p.mouth = 0; p.smile = typeof talk === 'number' ? clamp(talk) : talkOpen(t);
+  return p;
+}
+/** pickCells with the mouth talking and no fire: talkCells(t, cols, style, { mouthSide }) . */
+export const talkCells = (t, cols = 64, style = PICK_EYES, opts = {}) => pickCells(t, cols, style, { ...opts, talk: opts.talk || true });
+
+// ---- sleep: the screensaver dragon (eyes closed, a slow minimal sway, a breath of z; no whip, no fire) -------
+export const SLEEP_Z = [' ', 'z', 'z z', 'z z Z'];
+/** The z that drifts up with each slow breath at t ms (4.8 s cycle). */
+export const sleepZ = (t) => SLEEP_Z[Math.floor((((t % 4800) + 4800) % 4800) / 1200)];
+/** The sleeping pose at t ms: tail barely swaying (amp 0.1 vs the pick's 0.6), eyes shut, mouth closed, no fire. */
+export function sleepPose(t, { still = false } = {}) {
+  const p = restPose();
+  p.fire = null; p.mouth = 0;
+  if (!still) { p.tail.len = 1.4; p.tail.k = 2.6; p.tail.phase = t * 0.0011; p.tail.amp = 0.1; }
+  const z = still ? 'z' : sleepZ(t);
+  if (z.trim()) p.label = { text: z, rgb: [186, 230, 253] };
+  return p;
+}
+/** Sleeping dragon cells: sleepCells(t, cols, style, { theme, mono, still, size, lm }). Eyes are always shut. */
+export function sleepCells(t, cols = 64, style = PICK_EYES, { theme = 'dark', mono = false, still = false, size, lm } = {}) {
+  const L = dragonLayout(cols, { size, lm });
+  return composeCells(sleepPose(t, { still }), eyeState('closed', 0), L, style, { theme, mono, t });
+}
+
+// ---- the hero: talk on the right, sway sway sway whip, the mouth moves left, fire leftwards (cli.quox.ai hero) ---
+export const HERO_TALK_MS = 1400, HERO_MOVE_MS = 450;
+export const heroMs = (talkMs = HERO_TALK_MS) => talkMs + PICK.sway + PICK.whip + HERO_MOVE_MS + PICK.fire + PICK.rest;
+export const HERO_MS = heroMs();
+/** Hero timeline: 'talk' | 'sway' | 'whip' | 'move' | 'fire' | 'rest'. Loops on heroMs(talkMs). */
+export function heroPhase(t, { talkMs = HERO_TALK_MS } = {}) {
+  const T = heroMs(talkMs), c = ((t % T) + T) % T;
+  const a = talkMs, b = a + PICK.sway, d = b + PICK.whip, e = d + HERO_MOVE_MS, f = e + PICK.fire;
+  return c < a ? 'talk' : c < b ? 'sway' : c < d ? 'whip' : c < e ? 'move' : c < f ? 'fire' : 'rest';
+}
+/** The hero's pose and eye state at t. The tail keeps swaying through the move; fire comes from the left mouth. */
+function heroFrame(t, talkMs) {
+  const fr = heroFrame0(t, talkMs);
+  fr.pose.flap = 0.12 * Math.sin(t * 0.0068 * 0.5); // the wings keep a gentle beat
+  return fr;
+}
+function heroFrame0(t, talkMs) {
+  const T = heroMs(talkMs), c = ((t % T) + T) % T, ph = heroPhase(t, { talkMs });
+  const w0 = PICK.sway, f0 = w0 + PICK.whip;
+  if (ph === 'talk') return { pose: talkPose(t, true), eyes: eyeState('idle', t) };
+  // pick time pt: 0 at the start of the sway; frozen at the end of the whip during the move
+  const base = c - talkMs, pt = ph === 'move' ? f0 - 1 : ph === 'fire' || ph === 'rest' ? base - HERO_MOVE_MS : base;
+  const pose = pickPose(pt);
+  pose.tail.phase += (t - pt) * 0.0068; // the sway never stutters at the seams
+  pose.fire = ph === 'fire' && pt > f0 ? pose.fire : null;
+  pose.mouthSide = ph === 'move' ? (c - talkMs - w0 - PICK.whip < HERO_MOVE_MS / 2 ? 'right' : 'left') : ph === 'fire' || ph === 'rest' ? 'left' : 'right';
+  if (ph === 'move') pose.mouth = 0;
+  // v2: the face turns left (mouth and cheeks slide, eyes look left), then the mouth opens wide to breathe
+  const u = ph === 'move' ? smooth((c - talkMs - w0 - PICK.whip) / HERO_MOVE_MS) : ph === 'fire' ? 1 : ph === 'rest' ? 1 - smooth((c - talkMs - w0 - PICK.whip - HERO_MOVE_MS - PICK.fire) / PICK.rest) : 0;
+  pose.faceX = -0.06 * u;
+  if (ph === 'fire') pose.smile = pose.mouth; // the mouth opens wide to breathe
+  pose.mouth = 0;
+  const ft = pt - f0;
+  if (ph === 'move') return { pose, eyes: { ...eyeState('idle', t), gx: -1 * u, gy: 0.4 } };
+  return { pose, eyes: ph === 'fire' && ft > 120 && ft < 1500 ? { open: 0 } : eyeState('idle', t) };
+}
+/**
+ * The hero at t ms (cli.quox.ai): the mouth on the right talks (no fire) for talkMs, then the tail sways three times
+ * and whips, the mouth moves to the left and the dragon breathes fire leftwards, eyes shut. The Q needs room on its
+ * left for the fire: lm defaults to as much margin as cols allow. still: eyes open, mouth closed, no fire.
+ */
+export function heroCells(t, cols = 64, style = PICK_EYES, { talkMs = HERO_TALK_MS, theme = 'dark', mono = false, still = false, size, lm } = {}) {
+  if (lm === undefined) { const L0 = dragonLayout(cols, { size }); lm = Math.max(L0.qx0 / 2, Math.min(Math.ceil(L0.H * 1.25 / 2) + 4, Math.floor((cols * 2 - L0.qw) / 2) - 2)); }
+  const L = dragonLayout(cols, { size, lm });
+  if (still) return composeCells(restPose(), eyeState('open', 0), L, style, { theme, mono, t: 0 });
+  const { pose, eyes } = heroFrame(t, talkMs);
+  return composeCells(pose, eyes, L, style, { theme, mono, t });
+}
+const HERO_CAP = { talk: 'talking', sway: 'tail sway', whip: 'tail whip', move: 'the mouth moves to the left', fire: 'fire breath to the left, eyes shut', rest: 'settle' };
+
+// ---- moods: the same dragon, expressed through the eyes and the smile only ----------------------------------------
+export const MOODS = ['waiting', 'success', 'failure', 'greeting'];
+const GREETING = "Hi, I'm Quox!";
+const MOOD_NOTE = {
+  waiting: 'waiting: eyes wide on you, a slow look about, a patient blink',
+  success: 'success: a blink, then happy closed eyes and a big smile',
+  failure: 'failure: the eyes sink and look away, the smile turns down',
+  greeting: 'greeting: eyes open, look at you, a blink, the smile says hi',
+};
+const greetCells = (text, t) => {
+  const n = Math.floor(clamp(t / 45, 0, text.length));
+  return [...text].map((ch, i) => ({ ch: i < n ? ch : ' ', rgb: [56 + (168 - 56) * (i / (text.length - 1)), 189 + (85 - 189) * (i / (text.length - 1)), 248 + (247 - 248) * (i / (text.length - 1))].map(Math.round) }));
+};
+/** The calm base every mood sits on: the pick's easy tail sway, wings gently flapping, smile closed. */
+function calmPose(t) {
+  const p = talkPose(t, 0);
+  p.flap = 0.12 * Math.sin(t * 0.0068 * 0.5);
+  return p;
+}
+/** A mood at t ms since it began: { pose, eyes, caption }. still: the static representative form. */
+export function moodFrame(mood, t, { still = false } = {}) {
+  const p = calmPose(still ? 0 : t);
+  let eyes = eyeState('open', 0);
+  switch (mood) {
+    case 'waiting': {
+      const u = still ? 0 : t;
+      eyes = { open: still ? 1 : blinkOpen((u % 2600) - 2200), gx: still ? 0 : 0.55 * Math.sin(u / 1500), gy: 0.55 };
+      break;
+    }
+    case 'success': {
+      const shut = still || (t >= 1100 && t < 3300);
+      eyes = { open: shut ? 0 : blinkOpen(t - 450), gx: 0, gy: 1 };
+      p.smile = still ? 0.9 : kf(t, [[1000, 0], [1400, 0.9], [3000, 0.9], [3400, 0]]);
+      break;
+    }
+    case 'failure': {
+      const k = still ? 1 : kf(t, [[0, 0], [350, 1]]);
+      eyes = { open: 1 - 0.45 * k, gx: -0.7 * k, gy: 1 };
+      p.frown = k > 0.5 ? 1 : 0;
+      break;
+    }
+    case 'greeting': {
+      eyes = { open: still ? 1 : kf(t, [[0, 0], [450, 1]]) * Math.min(blinkOpen(t - 1700), blinkOpen(t - 1960)), gx: 0, gy: 1 };
+      p.smile = still ? 0 : t > 700 && t < 1700 ? talkOpen(t) : 0;
+      p.label = { cells: greetCells(GREETING, still ? 1e9 : t - 400) };
+      break;
+    }
+    default: throw new Error(`unknown dragon mood: ${mood}`);
+  }
+  return { pose: p, eyes, caption: MOOD_NOTE[mood] };
+}
+
+// ---- client clips (CLI-QUOX F3) ---------------------------------------------------------------------------
+
+/** Where the fire clip starts inside the hero: just before the face turns left. */
+const FIRE_OFFSET = HERO_TALK_MS + PICK.sway + PICK.whip;
+const FIRE_MS = HERO_MOVE_MS + PICK.fire + PICK.rest;
+const heroClipFrame = (t, offset = 0) => { const tt = t + offset; return { ...heroFrame(tt, HERO_TALK_MS), caption: HERO_CAP[heroPhase(tt)] }; };
+/** The hero: talk, sway sway sway whip, the face turns left, fire from the mouth, settle. /dragon, classic and the pick all play it. */
+const heroClip = {
+  dur: HERO_MS,
+  at: (t) => heroClipFrame(t),
+  still: () => ({ pose: restPose(), eyes: eyeState('open', 0), caption: 'the dragon (static form)' }),
+  cells: (t, cols, o) => heroCells(t, cols, PICK_EYES, o),
+  width: 100, title: 'The dragon',
+  caption: 'googly dot eyes, a smile that talks; the tail sways and whips, then the face turns left and the dragon breathes fire from its mouth, eyes squeezed shut (/dragon)',
+};
+/** /dragon fire: the hero's last act on its own: the face turns left, fire from the mouth, settle. */
+const fireClip = {
+  dur: FIRE_MS,
+  at: (t) => heroClipFrame(t, FIRE_OFFSET),
+  still: heroClip.still,
+  cells: (t, cols, o) => heroCells(t + FIRE_OFFSET, cols, PICK_EYES, o),
+  width: 100, title: 'Fire',
+  caption: 'the face turns left and the dragon breathes fire from its mouth, eyes squeezed shut (/dragon fire)',
+};
+/** A mood as a short vignette (cinematic level only). No label unless asked: the status line already says what happened. */
+const moodClip = (mood, dur, width, title, caption, label = false) => ({
+  dur, width, title, caption,
+  at(t) { const fr = moodFrame(mood, t); if (!label) fr.pose.label = null; return fr; },
+  still() { const fr = moodFrame(mood, 0, { still: true }); if (!label) fr.pose.label = null; return fr; },
+});
+
+/**
+ * Everything the client plays, by name. width = the frame the clip wants (the hero and fire need room to the left
+ * for the fire; moods are compact). pick and idle (/dragon, /dragon classic) are the hero itself: no separate designs.
+ */
+export const CLIPS = {
+  hero: heroClip,
+  pick: heroClip,
+  idle: heroClip,
+  fire: fireClip,
+  waiting: moodClip('waiting', 2500, 40, 'Mood: waiting', 'waiting for your approval: eyes wide on you (cinematic motion)'),
+  success: moodClip('success', 2300, 40, 'Mood: success', 'done: a blink, then happy eyes and a big smile (cinematic motion)'),
+  failure: moodClip('failure', 2200, 40, 'Mood: failure', 'failed: the eyes sink and look away, the smile turns down (cinematic motion)'),
+  greeting: moodClip('greeting', 2600, 64, 'Mood: greeting', 'hello: the eyes open, look at you, blink, the smile says hi (the cinematic intro)', true),
+};
+export const CLIP_NAMES = Object.keys(CLIPS);
+/** The moods the app plays at the cinematic level, keyed by what happened. */
+export const MOOD_CLIPS = ['waiting', 'success', 'failure', 'greeting'];
+
+/**
+ * Cells of a clip at t ms: rows of { ch, rgb, bg }. opts: cols (the room there is), theme 'dark' | 'light',
+ * mono (NO_COLOR: shapes only), still (reduced motion: the static form), size / lm (force a layout), label (false:
+ * no words in the frame).
+ */
+export function clipCells(name, t, { cols = 100, theme = 'dark', mono = false, still = false, size, lm, label = true } = {}) {
+  const c = CLIPS[name];
+  if (!c) throw new Error(`unknown dragon clip: ${name}`);
+  const L = dragonLayout(Math.max(size ? 8 : 40, Math.min(cols, c.width)), { size, lm }); // a forced size (the intro) may be narrower than 40
+  const tt = Math.max(0, Math.min(t, c.dur));
+  if (c.cells) return c.cells(tt, L.cols, { theme, mono, still, size, lm });
+  const fr = still ? c.still() : c.at(tt);
+  if (!label) fr.pose.label = null; // the intro has its own words beside the art
+  return composeCells(fr.pose, fr.eyes, L, PICK_EYES, { theme, mono, t: tt });
+}
+/** The caption of a clip at t (what the dragon is doing now). */
+export const clipCaption = (name, t) => CLIPS[name].at(Math.max(0, Math.min(t, CLIPS[name].dur))).caption;
+
+// ---- the launch egg: the v8 dragon's googly-eye greeting beside the settled Q ------------------------------
+import { qDims } from './qart.js';
+export const EGG_MS = CLIPS.greeting.dur;
+/** The egg at t ms (after the Q has settled): the v8 dragon opens its googly eyes, looks, blinks and smiles, at the Q's size. */
+export function eggCells(size, t, { color = true, theme = 'dark' } = {}) {
+  const L = dragonLayout(qDims(size).cols + 6, { size, lm: 0 });
+  return clipCells('greeting', t, { cols: L.cols, size, lm: 0, theme, mono: !color, label: false });
+}

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