quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/qhello.js

@@ -0,0 +1,58 @@
+/**
+ * The Q says hello: "Hi, I'm Quox." decoded in beside the mark (CLI-QUOX, lab fx "decode").
+ *
+ * Characters resolve left to right; just ahead of the edge they flicker as half-width katakana, just behind
+ * it a faint phosphor afterglow fades. The final text is always plain and readable. PURE AND PORTABLE: no
+ * Ink, no process, no timers; t is ms since the line started. Output cells { ch, rgb, bold } so the CLI and
+ * the web face (web/qface.js) draw the same frames.
+ */
+
+// Same curated half-width katakana as indicator.js SCRAMBLE_GLYPHS: one cell each, none reads as Latin.
+export const KANA = 'ｱｳｶｷｸｹｺｻﾀﾁﾂﾇﾊﾋﾎﾏﾐﾑﾒﾗ';
+export const LEAD_MS = 140, GLOW_MS = 700;
+const SKY = [56, 189, 248];
+const DIM = [58, 66, 82], TXT = [226, 232, 240], GLOWC = [110, 231, 183];
+const mix = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+const clamp = (x) => Math.max(0, Math.min(1, x));
+const hash = (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; };
+
+/** How long a line of n characters takes to settle (decode plus afterglow). */
+export const helloMs = (text, perChar = 28) => Math.max(1, [...String(text)].length - 1) * perChar + GLOW_MS;
+
+/**
+ * Decode frame of `text` at t ms. fg: rgb for the settled text (default near-white), or a function
+ * (i, ch) -> rgb (a gradient). mono: no colour (glyph flicker stays: motion is not colour).
+ * Returns [{ ch, rgb, bold }], always text.length cells; blanks are ' ' (never shifting the line).
+ */
+export function helloCells(text, t, { perChar = 28, fg = TXT, mono = false, salt = 7 } = {}) {
+  const chars = [...String(text)];
+  const fgAt = typeof fg === 'function' ? fg : () => fg;
+  return chars.map((ch, i) => {
+    if (ch === ' ') return { ch, rgb: null, bold: false };
+    const dt = t - i * perChar;
+    if (dt < -LEAD_MS) return { ch: ' ', rgb: null, bold: false };
+    if (dt < 0) {
+      const b = Math.floor(t / 33);
+      const k = KANA[Math.floor(hash(i, b, salt) * KANA.length)];
+      return { ch: k, rgb: mono ? null : mix(DIM, SKY, 0.35 + 0.65 * hash(i, b + 7, salt)), bold: false };
+    }
+    const g = dt < GLOW_MS ? (1 - dt / GLOW_MS) ** 1.6 : 0;
+    return { ch, rgb: mono ? null : mix(fgAt(i, ch), GLOWC, 0.5 * g), bold: !mono && (dt < 50 || g > 0.55) };
+  });
+}
+
+/** Is the line fully settled (plain text, no glow) at t? */
+export const helloSettled = (text, t, perChar = 28) => t >= helloMs(text, perChar);
+
+/** The settled text's gradient (sky to violet across the line), for callers that want the brand look. */
+export const helloGradient = (text) => {
+  const n = Math.max(1, [...String(text)].length - 1);
+  return (i) => mix([56, 189, 248], [168, 85, 247], clamp(i / n));
+};
+
+/** Cells -> truecolor ANSI string (bold where marked). */
+export function helloAnsi(cells) {
+  let s = '';
+  for (const c of cells) s += (c.bold ? '\x1b[1m' : '') + (c.rgb ? `\x1b[38;2;${c.rgb.join(';')}m` : '') + c.ch + (c.rgb || c.bold ? '\x1b[0m' : '');
+  return s;
+}

package/lib/quoxon/qmotion.js

@@ -0,0 +1,111 @@
+/**
+ * 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
+ * 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 { helloCells, helloGradient, helloMs } from './qhello.js';
+import { mono, c, clip } from './theme.js';
+import { reducedMotion } from './motion/clock.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';
+
+const h = React.createElement;
+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 = ''; };
+  for (const cl of cells) {
+    const cc = rgbS(cl.rgb), b = Boolean(cl.bold);
+    if (cc !== col || b !== bold) { flush(); col = cc; bold = b; }
+    run += cl.ch;
+  }
+  flush();
+  return out;
+}
+
+let envCache = null;
+const envGlyph = () => (envCache ??= { mode: glyphMode(process.env), depth: colorDepth(process.env) });
+
+/**
+ * The status glyph: the perpetual Q for a state at ms (sample it from the shared clock, ~12 fps). One fixed
+ * shape; only its colour moves. since: when the state began (failing flashes from there). Ⓠ under NO_COLOR.
+ */
+export function QGlyph({ state = 'working', ms = Date.now(), since = null, quiet = isQuiet() }) {
+  const { mode, depth } = envGlyph();
+  const g = qGlyph(state, ms, { mono: mono(), quiet, mode, depth, since });
+  return h(Text, { bold: true }, ...cellNodes(g.cells, 'g'));
+}
+
+// ---- 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);
+
+/**
+ * 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.
+ */
+export function HelloIntro({ item, cols, rows, t = Infinity, eye = false, text = HELLO }) {
+  const { stdout } = useStdout();
+  const size = labSize(cols, rows ?? termRows(stdout) ?? 40);
+  const color = !mono();
+  const helloAt = t - INTRO_MS;
+  const plan = introPlan(size, { color });
+  let cells;
+  if (eye && helloAt >= helloMs(text)) cells = eyeCellsAt(size, helloAt - helloMs(text), { color });
+  else cells = plan.at(Math.min(t, INTRO_MS));
+  const wide = cols >= 60;
+  const w = qDims(size).cols;
+  const hello = helloCells(text, Number.isFinite(helloAt) ? Math.max(-1000, helloAt) : 1e9, { fg: helloGradient(text), mono: !color });
+  const info = h(Box, { flexDirection: 'column', justifyContent: 'center', marginLeft: wide ? 2 : 0, marginTop: wide ? 0 : 1 },
+    h(Text, { bold: true }, ...cellNodes(hello, 'h')),
+    h(Text, { color: c('dim') }, clip(item?.text || '', cols - (wide ? w + 4 : 2))));
+  return h(Box, { flexDirection: wide ? 'row' : 'column', marginBottom: 1 },
+    h(Box, { flexDirection: 'column' }, ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `r${k}-`)))),
+    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);
+
+/**
+ * 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.
+ */
+export function EyeLive({ cols, rows }) {
+  const { stdout } = useStdout();
+  const onClock = React.useContext(FrameContext) != null; // inside the app: the shared clock drives the frames
+  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(() => {
+    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);
+    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);
+}