rovecode 0.3.3 → 0.4.0-beta.2

package/src/core/intro.ts

@@ -1,266 +0,0 @@
-/** The opening intro: ROVECODE assembles itself in the middle of the terminal.
- *
- *  Four acts, all of them Berkay's picks (2026-09-06). The mark fills in left to right — chosen over a
- *  checklist that ticks itself off and a single progress bar. A hairline frame draws inward from the four
- *  corners until the halves meet — chosen over a shimmer pass and a rain of blocks. The cloud mascot leans
- *  down out of the frame's top line — chosen over raining the letters into place and rising from the
- *  bottom. Then the mark breathes once. Centred on a cleared screen, and it hands over to the session's
- *  card (core/voice.ts).
- *
- *  The CLI holds this screen until the runtime and interface are ready, not merely until their modules
- *  are imported. The CLI waits for both the choreography and the prepared first frame, concurrently.
- *  Fast boots still show the intro (~1.1s); slow boots hold the completed mark with a two-Hz activity line.
- *  Standalone callers can still play the finite animation. Off for pipes, --plain, ROVECODE_INTRO=0
- *  and --no-intro.
- *
- *  It never reads stdin. Someone who starts typing immediately types into the terminal's buffer and the
- *  TUI gets those keys when it begins reading — an intro that swallowed the first keystroke to offer a
- *  skip would cost more than it saved. */
-
-/** ░ ▒ ▓ █ — a letter's brightness as the wave passes over it */
-const RAMP = ["░", "▒", "▓", "█"] as const;
-
-/** ROVECODE, two rows per letter, three columns each. Only the full blocks take the ramp; the halves
- *  (▀ ▄) are the letter's shape and stay put, which is what keeps the word readable at every step. */
-const LETTERS: readonly (readonly [string, string])[] = [
-  ["█▀█", "█▀▄"], // R
-  ["█▀█", "█▄█"], // O
-  ["█ █", "▀▄▀"], // V
-  ["█▀▀", "█▄▄"], // E
-  ["█▀▀", "█▄▄"], // C
-  ["█▀█", "█▄█"], // O
-  ["█▀▄", "█▄▀"], // D
-  ["█▀▀", "█▄▄"], // E
-];
-
-/** columns the mark occupies: three per letter plus the gaps */
-export const MARK_COLS = LETTERS.length * 4 - 1;
-/** the frame sits this many columns clear of the mark on each side */
-const FRAME_PAD = 4;
-/** columns the frame's two horizontal runs cover between them. Kept EVEN so the two halves meet exactly
- *  instead of leaving a one-column gap the eye reads as a mistake. */
-const FRAME_COLS = MARK_COLS + FRAME_PAD * 2 + ((MARK_COLS + FRAME_PAD * 2) % 2);
-/** columns each end of the frame grows per step — 3 makes the draw snappy without skipping */
-const FRAME_GROWTH = 3;
-
-/** The mascot, hanging down from behind the frame's top line — Berkay's pick over the cloud raining the
- *  letters into place and rising from the bottom (2026-09-06).
- *
- *  This is a COPY of SPRITE + FACE from sextant/pet.ts, not an import, and that is deliberate: importing
- *  the sextant module here would pull the panel painter into the boot path of a process that has not
- *  decided to draw panels yet, which is the opposite of the work that made startup cheap. The copy cannot
- *  drift — test/unit/intro.test.ts asserts these rows are identical to the ones the TUI paints, so the
- *  intro's cloud and the session's cloud are the same cloud or the suite fails. */
-const CLOUD_OUTLINE: readonly string[] = [
-  "       ╭────╮     ",
-  "   ╭───╯    ╰──╮  ",
-  "  ╭╯           ╰╮ ",
-  "  │             │ ",
-  "  ╰╮           ╭╯ ",
-  "   ╰───────────╯  ",
-];
-/** the face's columns and rows, copied from pet.ts FACE. Placed by INDEX rather than typed into the art,
- *  so an eye cannot end up one column off the anchor the TUI paints it on — which is exactly what happened
- *  when these rows were written by hand. */
-const FACE_AT = { EYE_L: 6, EYE_R: 12, MOUTH: 9, EYE_ROW: 3, MOUTH_ROW: 4 } as const;
-const CLOUD: readonly string[] = CLOUD_OUTLINE.map((row, r) => {
-  const cells = [...row];
-  if (r === FACE_AT.EYE_ROW) { cells[FACE_AT.EYE_L] = "•"; cells[FACE_AT.EYE_R] = "•"; }
-  if (r === FACE_AT.MOUTH_ROW) cells[FACE_AT.MOUTH] = "◡";
-  return cells.join("");
-});
-export const CLOUD_COLS = 18;
-/** rows of cloud that hang BELOW the frame line once it has fully descended */
-const CLOUD_BODY = CLOUD.length - 1;
-
-/** the four acts, in steps */
-const SWEEP_STEPS = LETTERS.length + RAMP.length - 1;                 // the mark fills in
-const FRAME_STEPS = Math.ceil(FRAME_COLS / 2 / FRAME_GROWTH);          // the corners reach the middle
-const CLOUD_STEPS = CLOUD.length;                                      // the mascot leans over the line
-const BREATHE = [3, 2, 3] as const;                                    // █ ▓ █, once
-export const INTRO_STEPS = SWEEP_STEPS + FRAME_STEPS + CLOUD_STEPS + BREATHE.length;
-/** how long the whole show takes when nothing interrupts it */
-export const INTRO_MS = 1100;
-
-/** the two mark rows at `step`; step 0 is the whole word at its faintest, SWEEP_STEPS is solid. Past the
- *  sweep the mark holds, except for the breath at the very end. */
-export function introFrame(step: number): [string, string] {
-  const breathIx = step - SWEEP_STEPS - FRAME_STEPS - CLOUD_STEPS;
-  const held = breathIx >= 0 ? BREATHE[Math.min(breathIx, BREATHE.length - 1)]! : undefined;
-  const rows: [string, string] = ["", ""];
-  LETTERS.forEach((letter, i) => {
-    const level = held ?? Math.max(0, Math.min(RAMP.length - 1, step - i));
-    const shade = RAMP[level]!;
-    for (const r of [0, 1] as const) rows[r] += (rows[r].length > 0 ? " " : "") + letter[r]!.replaceAll("█", shade);
-  });
-  return rows;
-}
-
-/** How far the cloud has leaned over the top line: 0 before it starts, CLOUD.length when it is all the
- *  way out. It only begins once the frame has closed — one thing happens at a time. */
-export function cloudDescent(step: number): number {
-  return Math.max(0, Math.min(CLOUD.length, step - SWEEP_STEPS - FRAME_STEPS));
-}
-
-/** The cloud's rows that hang BELOW the frame line, padded to a fixed count so the block below never
- *  shifts as it comes down — the mark must not jump while the mascot arrives. */
-export function cloudRows(step: number): string[] {
-  const d = cloudDescent(step);
-  const shown = CLOUD.slice(1, Math.max(0, d));
-  return [...shown, ...Array.from({ length: CLOUD_BODY - shown.length }, () => "")];
-}
-
-/** The cloud's FIRST row is drawn into the frame's top line rather than under it, which is what makes it
- *  read as leaning over the edge instead of floating below it. Spaces in the sprite leave the line
- *  showing through; the sprite's own glyphs cut into it. */
-export function mergeCloudIntoLine(line: string, step: number): string {
-  if (cloudDescent(step) === 0 || line.length === 0) return line;
-  const at = Math.max(0, Math.floor((line.length - CLOUD_COLS) / 2));
-  // always the sprite's FIRST row: it is the cloud's crown, and it stays cut into the line while the body
-  // appears underneath. Advancing it row by row instead made the line show the cloud's underside.
-  const row = CLOUD[0]!;
-  const chars = [...line];
-  [...row].forEach((ch, i) => { if (ch !== " " && at + i < chars.length) chars[at + i] = ch; });
-  return chars.join("");
-}
-
-/** the frame's top and bottom rows at `step`: two runs growing inward from the corners until they meet.
- *  Empty strings before the mark has finished filling in — one thing happens at a time. */
-export function frameRows(step: number): [string, string] {
-  const grown = step - SWEEP_STEPS;
-  if (grown < 0) return ["", ""];
-  const half = Math.min(FRAME_COLS / 2, Math.max(0, grown) * FRAME_GROWTH);
-  if (half === 0) return ["", ""];
-  const run = "─".repeat(Math.max(0, half - 1));   // the corner glyph is the half's first column
-  const gap = Math.max(0, FRAME_COLS - half * 2);
-  const line = (l: string, r: string) => `${l}${run}${" ".repeat(gap)}${run}${r}`;
-  return [line("╭", "╮"), line("╰", "╯")];
-}
-
-export interface IntroOptions {
-  /** where the frames go; injected in tests */
-  write: (s: string) => void;
-  /** false → nothing is written, ever. A pipe is not a screen. */
-  tty: boolean;
-  version?: string;
-  columns?: number;
-  rows?: number;
-  /** CLI loading mode: stay visible after the sequence until finish(), with a low-frequency activity line. */
-  holdUntilReady?: boolean;
-  /** Live terminal dimensions and resize subscription; no stdin is read by the intro. */
-  size?: () => { columns: number; rows: number };
-  onResize?: (paint: () => void) => () => void;
-  /** ms between steps; the default spreads INTRO_STEPS over INTRO_MS */
-  frameMs?: number;
-  setInterval?: (fn: () => void, ms: number) => unknown;
-  clearInterval?: (h: unknown) => void;
-}
-
-/** rows the whole block occupies: frame top (the cloud’s crown cut into it), the cloud’s body, a blank,
- *  the two mark rows, the version, the status line, the frame bottom */
-export const INTRO_ROWS = 7 + (CLOUD.length - 1);
-
-/** Is there room to play it? A terminal too narrow wraps the frame into nonsense; one too short scrolls
- *  its own top away. Both were real — 34×24 overflowed by six columns, 40×10 painted thirteen lines — and
- *  neither is worth degrading the animation for: the session’s card already has a prose form for a small
- *  terminal, and no intro at all is better than a broken one. One row and one column of margin, so the
- *  block is never flush against the edges. */
-export function introFits(columns: number, rows: number): boolean {
-  return columns >= FRAME_COLS + 2 && rows >= INTRO_ROWS + 2;
-}
-
-export interface Intro {
-  /** what the session is doing right now, under the mark; "" clears the line */
-  status: (line: string) => void;
-  /** The mark has actually played through. Does not clear it; slow preparation may still be running. */
-  animationDone: Promise<void>;
-  /** resolves after finish(), or after the finite sequence when holdUntilReady is false */
-  done: Promise<void>;
-  /** cut it short: paint the final state and stop. Safe to call twice, and after `done`. */
-  finish: () => void;
-}
-
-const CLEAR_SCREEN = "\x1b[2J\x1b[H";
-const HIDE_CURSOR = "\x1b[?25l";
-const SHOW_CURSOR = "\x1b[?25h";
-
-/** Play the intro centred on a cleared screen. Off a terminal this is a no-op whose `done` is already
- *  resolved, so callers do not branch — the check lives here, once. */
-export function startIntro(opts: IntroOptions): Intro {
-  const size = opts.size ?? (() => ({ columns: opts.columns ?? 80, rows: opts.rows ?? 24 }));
-  const initial = size();
-  if (!opts.tty || !introFits(initial.columns, initial.rows)) return { status: () => {}, animationDone: Promise.resolve(), done: Promise.resolve(), finish: () => {} };
-  const setI = opts.setInterval ?? setInterval;
-  const clearI = opts.clearInterval ?? ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
-  let step = 0, line = "", ended = false, holding = false, pulse = 0, handle: unknown = null;
-  let paintedSize = initial;
-  let unsubscribe: (() => void) | undefined;
-  let settle: () => void = () => {};
-  const done = new Promise<void>((r) => { settle = r; });
-  let animationSettled: () => void = () => {};
-  const animationDone = new Promise<void>((r) => { animationSettled = r; });
-  const label = (): string => line && holding && !ended ? `${line} ${"·".repeat(pulse + 1)}` : line;
-  const centred = (text: string, cols: number): string => {
-    const clipped = [...text.replace(/\s+/g, " ")].slice(0, Math.max(0, cols - 2)).join("");
-    return " ".repeat(Math.max(0, Math.floor((cols - clipped.length) / 2))) + clipped;
-  };
-  const paint = (): void => {
-    const { columns: cols, rows } = paintedSize = size();
-    if (!introFits(cols, rows)) { opts.write(CLEAR_SCREEN + HIDE_CURSOR); return; }
-    const pad = (width: number): string => " ".repeat(Math.max(0, Math.floor((cols - width) / 2)));
-    const markPad = pad(MARK_COLS), framePad = pad(FRAME_COLS);
-    const cloudPad = framePad + " ".repeat(Math.max(0, Math.floor((FRAME_COLS - CLOUD_COLS) / 2)));
-    const top = "\n".repeat(Math.max(0, Math.floor((rows - INTRO_ROWS) / 2)));
-    const [markTop, markBottom] = introFrame(step);
-    const [frameTop, frameBottom] = frameRows(step);
-    const frameLine = (s: string) => (s.length > 0 ? `${framePad}${s}` : "");
-    opts.write([
-      CLEAR_SCREEN, HIDE_CURSOR, top,
-      `${frameLine(mergeCloudIntoLine(frameTop, step))}\n`,
-      cloudRows(step).map((r) => `${r.length > 0 ? cloudPad + r : ""}\n`).join(""),
-      "\n",
-      `${markPad}${markTop}\n${markPad}${markBottom}\n`,
-      `${centred(opts.version ?? "", cols)}\n`,
-      `${centred(label(), cols)}\n`,
-      `${frameLine(frameBottom)}\n`,
-    ].join(""));
-  };
-  const paintStatus = (): void => {
-    if (ended) return;
-    const s = size();
-    if (s.columns !== paintedSize.columns || s.rows !== paintedSize.rows) { paint(); return; }
-    if (!introFits(s.columns, s.rows)) return;
-    const y = Math.max(0, Math.floor((s.rows - INTRO_ROWS) / 2)) + INTRO_ROWS - 1;
-    const esc = String.fromCharCode(27);
-    // Keep the logo still: slow boots repaint one short status row, not the entire terminal.
-    opts.write(`${esc}[${y};1H${esc}[2K${centred(label(), s.columns)}`);
-  };
-  const end = (): void => {
-    if (ended) return;
-    ended = true;
-    clearI(handle);
-    unsubscribe?.();
-    step = INTRO_STEPS;
-    line = "";
-    paint();
-    opts.write(`${SHOW_CURSOR}${CLEAR_SCREEN}`);
-    animationSettled();
-    settle();
-  };
-
-  paint();
-  unsubscribe = opts.onResize?.(() => { if (!ended) paint(); });
-  handle = setI(() => {
-    if (ended) return;
-    if (step < INTRO_STEPS) { step += 1; paint(); if (step === INTRO_STEPS) animationSettled(); }
-    else if (!opts.holdUntilReady) end();
-    else {
-      clearI(handle);
-      holding = true;
-      paintStatus();
-      handle = setI(() => { pulse = (pulse + 1) % 3; paintStatus(); }, 500);
-    }
-  }, opts.frameMs ?? Math.round(INTRO_MS / INTRO_STEPS));
-
-  return { status: (l: string) => { if (!ended && l !== line) { line = l; paintStatus(); } }, animationDone, done, finish: end };
-}