quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/qmotion.js

@@ -1,15 +1,17 @@
 /**
  * Ink adaptors for the pure Q frames (qart.js, qglyph.js, qhello.js): the status glyph, the hello intro
- * used by Getting started, and the on-demand Dragon's Eye (/eye). The frame math lives in the pure modules
+ * used by Getting started. The frame math lives in the pure modules
  * so the web face draws the same frames; this file only maps cells to <Text>.
  */
 import React from 'react';
 import { Box, Text, useStdout } from 'ink';
 import { qGlyph, glyphMode, colorDepth } from './qglyph.js';
-import { labSize, qDims, introPlan, eyeCellsAt, EYE_MS, INTRO_MS } from './qart.js';
+import { labSize, qDims, introPlan, INTRO_MS } from './qart.js';
 import { helloCells, helloGradient, helloMs } from './qhello.js';
-import { mono, c, clip } from './theme.js';
+import { mono, c, clip, isLight } from './theme.js';
+import { CLIPS, clipCells, clipCaption, eggCells, EGG_MS } from './qdragonScenes.js';
 import { reducedMotion } from './motion/clock.js';
+import { flySky } from './qdragonFly.js';
 import { FrameContext, useFrame } from './motion/frame.js';
 const isQuiet = () => reducedMotion(); // motion only (NO_COLOR is colour only; QGlyph falls back to the circled Q itself)
 import { termRows } from './term.js';
@@ -20,11 +22,11 @@ const rgbS = (rgb) => (rgb ? `rgb(${rgb.join(',')})` : undefined);
 /** Runs of same-coloured cells -> one <Text> each (keeps Ink's per-frame tokenising cheap). */
 export function cellNodes(cells, keyBase = 'c') {
   const out = [];
-  let run = '', col, bold = false, k = 0;
-  const flush = () => { if (run) out.push(h(Text, { key: `${keyBase}${k++}`, color: col, bold }, run)); run = ''; };
+  let run = '', col, bg, bold = false, k = 0;
+  const flush = () => { if (run) out.push(h(Text, { key: `${keyBase}${k++}`, color: col, backgroundColor: bg, bold }, run)); run = ''; };
   for (const cl of cells) {
-    const cc = rgbS(cl.rgb), b = Boolean(cl.bold);
-    if (cc !== col || b !== bold) { flush(); col = cc; bold = b; }
+    const cc = rgbS(cl.rgb), bb = rgbS(cl.bg), b = Boolean(cl.bold); // bg: the dragon's quadrant-block eyes
+    if (cc !== col || bb !== bg || b !== bold) { flush(); col = cc; bg = bb; bold = b; }
     run += cl.ch;
   }
   flush();
@@ -47,12 +49,12 @@ export function QGlyph({ state = 'working', ms = Date.now(), since = null, quiet
 // ---- hello intro (Getting started) ----------------------------------------------------------------------
 import { HELLO } from './onboarding/copy.js';
 export { HELLO };
-/** Total ms of the hello intro: Orbit & Lock, the greeting decode, then (egg) the Dragon's Eye. */
-export const helloIntroMs = ({ eye = false, text = HELLO } = {}) => INTRO_MS + helloMs(text) + (eye ? EYE_MS + 400 : 0);
+/** Total ms of the hello intro: Orbit & Lock, the greeting decode, then (egg) the dragon's googly-eye greeting. */
+export const helloIntroMs = ({ eye = false, text = HELLO } = {}) => INTRO_MS + helloMs(text) + (eye ? EGG_MS + 400 : 0);
 
 /**
  * The Q, then the Q says hello beside it. t: ms since the intro started (Infinity = settled). The greeting
- * decodes in once the Q has locked; the eye (launch egg) plays after the greeting has landed.
+ * decodes in once the Q has locked; the egg (the dragon's googly-eye greeting) plays after the greeting has landed.
  */
 export function HelloIntro({ item, cols, rows, t = Infinity, eye = false, text = HELLO }) {
   const { stdout } = useStdout();
@@ -61,7 +63,7 @@ export function HelloIntro({ item, cols, rows, t = Infinity, eye = false, text =
   const helloAt = t - INTRO_MS;
   const plan = introPlan(size, { color });
   let cells;
-  if (eye && helloAt >= helloMs(text)) cells = eyeCellsAt(size, helloAt - helloMs(text), { color });
+  if (eye && helloAt >= helloMs(text)) cells = eggCells(size, helloAt - helloMs(text), { color, theme: isLight() ? 'light' : 'dark' });
   else cells = plan.at(Math.min(t, INTRO_MS));
   const wide = cols >= 60;
   const w = qDims(size).cols;
@@ -74,38 +76,74 @@ export function HelloIntro({ item, cols, rows, t = Infinity, eye = false, text =
     info);
 }
 
-// ---- /eye: the Dragon's Eye on demand --------------------------------------------------------------------
-const listeners = new Set();
-let eyeStart = null;
-/** Ask the live <EyeLive/> to play the eye now. Returns true (the command was handled). */
-export function playEye(now = Date.now()) { eyeStart = now; for (const fn of listeners) fn(); return true; }
-export const eyePlaying = (now = Date.now()) => eyeStart != null && now - eyeStart < EYE_MS + 400;
-/** How long the eye shows (reduced motion: a still eye for 2 s). The app's shared clock frames it while true. */
-export const eyeActive = (now = Date.now(), quiet = isQuiet()) => eyeStart != null && now - eyeStart < (quiet ? 2000 : EYE_MS + 400);
+// ---- /dragon: the living dragon on demand (and the cinematic moods) ---------------------------------------
+const dragonListeners = new Set();
+let dragonNow = null; // { clip, start }
+export const DRAGON_STILL_MS = 2000;
+/** Play a dragon clip now ('pick' for /dragon, 'idle' for /dragon classic (both the hero), 'fire' for /dragon fire, or a mood). Returns true. */
+export function playDragon(clip = 'pick', now = Date.now()) {
+  if (!CLIPS[clip]) return false;
+  dragonNow = { clip, start: now };
+  for (const fn of dragonListeners) fn();
+  return true;
+}
+/** The clip playing at `now`, or null. Reduced motion or NO_COLOR: a still dragon for DRAGON_STILL_MS. */
+export function dragonPlaying(now = Date.now(), still = isQuiet() || mono()) {
+  if (!dragonNow) return null;
+  const span = still ? DRAGON_STILL_MS : CLIPS[dragonNow.clip].dur + 300;
+  return now - dragonNow.start < span ? { ...dragonNow, t: now - dragonNow.start, still } : null;
+}
+export const dragonActive = (now = Date.now(), still) => dragonPlaying(now, still) != null;
+/** Test hook: forget any clip in flight. */
+export const resetDragon = () => { dragonNow = null; };
 
 /**
- * Mounted once in the live region; renders nothing until /eye. Then the Q opens its eye, blinks once and
- * dissolves, and the component goes back to nothing (it never enters history). Its timer runs only while
- * the eye plays. Reduced motion: a still open eye for two seconds.
+ * Mounted once in the live region; renders nothing until /dragon (or a cinematic mood). The clip plays in the
+ * live region and never enters history. Short terminals (under 32 rows) get the compact dragon. Reduced
+ * motion or NO_COLOR: the static dragon (shapes only under NO_COLOR) for two seconds.
  */
-export function EyeLive({ cols, rows }) {
+/**
+ * TUI-UX #5 (shared with the /mirror guard): the full dragon is 25 rows and the live region also carries the margin, caption,
+ * composer and status rows (about 12). When that total reaches the terminal height Ink wipes the whole screen on every frame,
+ * so the dragon only goes full size when it clearly fits; otherwise the 15-row dragon plays.
+ */
+export const DRAGON_FULL_MIN_ROWS = 40;
+export const dragonTall = (rows) => rows >= DRAGON_FULL_MIN_ROWS;
+
+export function DragonLive({ cols, rows }) {
   const { stdout } = useStdout();
-  const onClock = React.useContext(FrameContext) != null; // inside the app: the shared clock drives the frames
+  const onClock = React.useContext(FrameContext) != null;
   useFrame();
   const [, bump] = React.useState(0);
-  React.useEffect(() => { const fn = () => bump((x) => x + 1); listeners.add(fn); return () => listeners.delete(fn); }, []);
-  const quiet = isQuiet();
-  const playing = eyeStart != null && Date.now() - eyeStart < (quiet ? 2000 : EYE_MS + 400);
+  React.useEffect(() => { const fn = () => bump((x) => x + 1); dragonListeners.add(fn); return () => dragonListeners.delete(fn); }, []);
+  const now = Date.now();
+  const p = dragonPlaying(now);
   React.useEffect(() => {
-    if (!playing || onClock) return undefined; // standalone only (no shared clock): its own bounded timer
-    const id = setInterval(() => { bump((x) => x + 1); if (Date.now() - eyeStart >= (quiet ? 2000 : EYE_MS + 400)) clearInterval(id); }, quiet ? 500 : 50);
+    if (!p || onClock) return undefined; // standalone only (no shared clock): its own bounded timer
+    const id = setInterval(() => { bump((x) => x + 1); if (!dragonActive()) clearInterval(id); }, p.still ? 500 : 40);
     return () => clearInterval(id);
-  }, [playing, quiet, onClock]);
-  if (!playing) return null;
-  const size = labSize(cols, rows ?? termRows(stdout) ?? 40);
-  const t = quiet ? EYE_MS * 0.42 : Date.now() - eyeStart;
-  const cells = eyeCellsAt(size, t, { color: !mono() });
-  return h(Box, { flexDirection: 'row', marginTop: 1 },
-    h(Box, { flexDirection: 'column' }, ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `e${k}-`)))),
-    cols >= 60 ? h(Box, { marginLeft: 2, flexDirection: 'column', justifyContent: 'center' }, h(Text, { color: c('dim') }, "the Dragon's Eye")) : null);
+  }, [Boolean(p), p?.still, onClock]);
+  if (!p) return null;
+  const tall = dragonTall(rows ?? termRows(stdout) ?? 40);
+  const cells = clipCells(p.clip, p.t, { cols, theme: isLight() ? 'light' : 'dark', mono: mono(), still: p.still, size: tall ? undefined : 'mid' });
+  const caption = p.still ? 'the dragon' : clipCaption(p.clip, p.t);
+  return h(Box, { flexDirection: 'column', marginTop: 1 },
+    ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `d${k}-`))),
+    h(Text, { color: c('dim') }, clip(caption, Math.max(10, cols - 2))));
+}
+
+/** Rows the 15-row dragon clips need besides the chrome: the clip, its caption and the margin above it. */
+export const CLIP_ROWS = 17;
+/** Does an explicit /dragon <clip> fit? { ok } or { ok:false, note } (one line, never silent). Unknown size (null rows) is ok. */
+export function clipRoom(clipName, rows, chromeH = 10) {
+  if (!rows) return { ok: true };
+  const need = CLIP_ROWS + chromeH + 2;
+  return rows >= need ? { ok: true } : { ok: false, note: `${clipName} needs ${need} rows, you have ${rows}. Make the window taller.` };
+}
+/** Does /dragon-fly fit? Same shape as clipRoom; the smallest sky is 12 rows. */
+export function flyRoom(rows, chromeH = 10) {
+  if (!rows) return { ok: true };
+  if (flySky(rows, chromeH).fits) return { ok: true };
+  const need = 12 + 1 + chromeH + 2;
+  return { ok: false, note: `fly needs ${need} rows, you have ${rows}. Make the window taller.` };
 }