jaitus 0.3.0

package/src/tui/markdown.js

@@ -0,0 +1,280 @@
+// ─── Markdown, rendered ─────────────────────────────────────────────────────────
+//
+// Models write markdown whether or not anyone asked them to. Printing it raw puts
+// `**` and triple backticks on screen as literal characters, which is the single most
+// obvious tell that a terminal agent is showing you a string rather than an answer.
+//
+// This is a block parser, not a regex pass, because the two cases that matter most —
+// fenced code and tables — cannot be recognised a line at a time without knowing
+// whether a fence is currently open. Inline styling is a regex pass, which is fine:
+// the worst failure there is an asterisk that stays visible.
+//
+// Output is rows of spans already wrapped to `width`, so the transcript can count rows
+// for scrolling without re-measuring anything.
+
+import { palette } from './theme.js';
+import { highlightLine, isKnownLanguage } from './highlight.js';
+import { wrapRow, stringWidth, truncateRow } from './ansi.js';
+
+// Classic consoles render box-drawing and block glyphs as tofu; every decorative
+// character here therefore has a plain twin, chosen per call because the device probe
+// can set JAITUS_ASCII after this module has loaded.
+const ascii = () => process.env.JAITUS_ASCII === '1';
+const g = (uni, plainText) => (ascii() ? plainText : uni);
+
+const FENCE = /^\s{0,3}(`{3,}|~{3,})\s*([\w+#.-]*)\s*$/;
+const HEADING = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const RULE = /^\s{0,3}([-*_])(\s*\1){2,}\s*$/;
+const BULLET = /^(\s*)([-*+])\s+(.*)$/;
+const ORDERED = /^(\s*)(\d{1,3})[.)]\s+(.*)$/;
+const TASK = /^\[([ xX~-])\]\s+(.*)$/;
+const QUOTE = /^\s{0,3}>\s?(.*)$/;
+const TABLE_ROW = /^\s*\|(.+)\|\s*$/;
+const TABLE_SEP = /^\s*\|?[\s:-]*-[\s:|-]*\|?\s*$/;
+
+/**
+ * Inline markup → spans.
+ *
+ * One pass over the alternation rather than nested replaces, so `` `a **b** c` `` keeps
+ * the asterisks inside the code span instead of bolding them: whichever construct opens
+ * first wins the region, which is also what every markdown renderer does.
+ */
+export function inlineSpans(text, base = {}) {
+  const p = palette();
+  const src = String(text ?? '');
+  const spans = [];
+  const pattern = /(\*\*\*|___)(?=\S)([\s\S]*?\S)\1|(\*\*|__)(?=\S)([\s\S]*?\S)\3|(\*|_)(?=\S)([^*_\n]*?\S)\5|`([^`\n]+)`|~~(?=\S)([\s\S]*?\S)~~|\[([^\]\n]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)|(\bhttps?:\/\/[^\s<>()]+)/g;
+  let last = 0;
+
+  for (let m = pattern.exec(src); m; m = pattern.exec(src)) {
+    if (m.index > last) spans.push({ t: src.slice(last, m.index), ...base });
+    if (m[2] !== undefined) spans.push(...inlineSpans(m[2], { ...base, bold: true, italic: true }));
+    else if (m[4] !== undefined) spans.push(...inlineSpans(m[4], { ...base, bold: true }));
+    else if (m[6] !== undefined) spans.push(...inlineSpans(m[6], { ...base, italic: true }));
+    else if (m[7] !== undefined) spans.push({ t: m[7], color: p.tealSoft, backgroundColor: p.raised });
+    else if (m[8] !== undefined) spans.push(...inlineSpans(m[8], { ...base, strikethrough: true, dimColor: true }));
+    else if (m[9] !== undefined) {
+      // The label carries the meaning; the target is shown dim so it can be copied
+      // without competing with the sentence it sits in.
+      spans.push(...inlineSpans(m[9] || m[10], { ...base, color: p.blue, underline: true }));
+      if (m[9]) spans.push({ t: ` (${m[10]})`, color: p.dim });
+    } else if (m[11] !== undefined) spans.push({ t: m[11], color: p.blue, underline: true });
+    last = m.index + m[0].length;
+  }
+  if (last < src.length) spans.push({ t: src.slice(last), ...base });
+  return spans.length ? spans : (src ? [{ t: src, ...base }] : []);
+}
+
+/**
+ * Markdown → wrapped rows.
+ *
+ * `width` is the usable text width; the caller has already subtracted its own padding.
+ * `compact` drops the blank line between blocks — used for the live streaming view,
+ * where vertical space is at more of a premium than breathing room.
+ */
+export function renderMarkdown(text, width, { compact = false } = {}) {
+  const p = palette();
+  const w = Math.max(16, width | 0);
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const rows = [];
+  const blank = () => { if (rows.length && rows[rows.length - 1].length) rows.push([]); };
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // ── fenced code ────────────────────────────────────────────────────────────
+    const fence = FENCE.exec(line);
+    if (fence) {
+      const marker = fence[1][0];
+      const language = fence[2] || '';
+      const body = [];
+      i += 1;
+      while (i < lines.length) {
+        const close = FENCE.exec(lines[i]);
+        if (close && close[1][0] === marker && close[1].length >= fence[1].length) { i += 1; break; }
+        body.push(lines[i]);
+        i += 1;
+      }
+      if (!compact) blank();
+      rows.push(...codeBlock(body, language, w));
+      if (!compact) rows.push([]);
+      continue;
+    }
+
+    // ── table ──────────────────────────────────────────────────────────────────
+    if (TABLE_ROW.test(line) && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1])) {
+      const block = [];
+      while (i < lines.length && TABLE_ROW.test(lines[i])) { block.push(lines[i]); i += 1; }
+      if (!compact) blank();
+      rows.push(...table(block, w));
+      if (!compact) rows.push([]);
+      continue;
+    }
+
+    // ── heading ────────────────────────────────────────────────────────────────
+    const heading = HEADING.exec(line);
+    if (heading) {
+      const level = heading[1].length;
+      const color = level === 1 ? p.brand : level === 2 ? p.tealSoft : p.text;
+      if (!compact) blank();
+      const content = inlineSpans(heading[2].replace(/\s+#+\s*$/, ''), { color, bold: level <= 3 });
+      for (const row of wrapRow(content, w)) rows.push(row);
+      if (level <= 2) {
+        const ruleWidth = Math.min(w, Math.max(8, contentWidth(content)));
+        rows.push([{ t: (level === 1 ? g('━', '=') : g('─', '-')).repeat(ruleWidth), color: level === 1 ? p.brandDeep : p.line }]);
+      }
+      i += 1;
+      continue;
+    }
+
+    // ── horizontal rule ────────────────────────────────────────────────────────
+    if (RULE.test(line)) { rows.push([{ t: g('─', '-').repeat(w), color: p.line }]); i += 1; continue; }
+
+    // ── blockquote ─────────────────────────────────────────────────────────────
+    const quote = QUOTE.exec(line);
+    if (quote) {
+      const body = [];
+      while (i < lines.length && QUOTE.test(lines[i])) { body.push(QUOTE.exec(lines[i])[1]); i += 1; }
+      if (!compact) blank();
+      for (const inner of renderMarkdown(body.join('\n'), w - 2, { compact: true })) {
+        rows.push([{ t: g('▏ ', '| '), color: p.teal }, ...inner]);
+      }
+      if (!compact) rows.push([]);
+      continue;
+    }
+
+    // ── lists ──────────────────────────────────────────────────────────────────
+    const bullet = BULLET.exec(line);
+    const ordered = !bullet && ORDERED.exec(line);
+    if (bullet || ordered) {
+      while (i < lines.length) {
+        const b = BULLET.exec(lines[i]);
+        const o = !b && ORDERED.exec(lines[i]);
+        if (!b && !o) break;
+        const depth = Math.min(3, Math.floor(((b || o)[1] || '').replace(/\t/g, '  ').length / 2));
+        const pad = '  '.repeat(depth);
+        let content = (b || o)[3];
+        const task = b && TASK.exec(content);
+        const done = !!task && /[xX]/.test(task[1]);
+        let marker;
+        if (task) {
+          marker = { t: done ? g('✔ ', '[x] ') : g('○ ', '[ ] '), color: done ? p.green : p.dim };
+          content = task[2];
+        } else if (b) {
+          marker = { t: `${(ascii() ? ['-', '*', '+'] : ['•', '◦', '▪'])[depth % 3]} `, color: p.brand };
+        } else {
+          marker = { t: `${o[2]}. `, color: p.brand };
+        }
+        i += 1;
+        // A list item may run over several source lines. Markdown joins the
+        // continuation into the same item; treating each line separately is what
+        // produced a stray blank and a lost indent under every wrapped bullet.
+        while (i < lines.length && lines[i].trim()
+          && !BULLET.test(lines[i]) && !ORDERED.test(lines[i])
+          && !FENCE.test(lines[i]) && !HEADING.test(lines[i]) && !RULE.test(lines[i]) && !QUOTE.test(lines[i])) {
+          content += ` ${lines[i].trim()}`;
+          i += 1;
+        }
+        const head = [{ t: pad }, marker];
+        const body = inlineSpans(content, done ? { dimColor: true, strikethrough: true } : {});
+        const indent = pad + ' '.repeat(stringWidth(marker.t));
+        rows.push(...wrapRow([...head, ...body], w, indent));
+      }
+      if (!compact) rows.push([]);
+      continue;
+    }
+
+    // ── blank ──────────────────────────────────────────────────────────────────
+    if (!line.trim()) { blank(); i += 1; continue; }
+
+    // ── paragraph ──────────────────────────────────────────────────────────────
+    const para = [];
+    while (i < lines.length && lines[i].trim()
+      && !FENCE.test(lines[i]) && !HEADING.test(lines[i]) && !RULE.test(lines[i])
+      && !QUOTE.test(lines[i]) && !BULLET.test(lines[i]) && !ORDERED.test(lines[i])) {
+      para.push(lines[i].trim());
+      i += 1;
+    }
+    for (const row of wrapRow(inlineSpans(para.join(' ')), w)) rows.push(row);
+    if (!compact) rows.push([]);
+  }
+
+  while (rows.length && !rows[rows.length - 1].length) rows.pop();
+  return rows;
+}
+
+const contentWidth = (spans) => spans.reduce((sum, s) => sum + stringWidth(s.t), 0);
+
+/**
+ * A fenced block: a language tag, a tinted body, and a left gutter that makes the code
+ * a distinct object on the page without the cost of a full border (which would eat two
+ * more columns of an already narrow terminal, and looks wrong when the code overflows).
+ */
+function codeBlock(body, language, width) {
+  const p = palette();
+  const rows = [];
+  const gutter = { t: g('▐ ', '| '), color: p.tealDeep };
+  const label = language && isKnownLanguage(language) ? language : language || '';
+  const inner = Math.max(8, width - 2);
+
+  rows.push([
+    { t: g('▛', '+'), color: p.tealDeep },
+    { t: label ? `${g('─', '-')} ${label} ` : g('─', '-'), color: p.dim },
+    { t: g('─', '-').repeat(Math.max(0, width - 2 - (label ? label.length + 3 : 1))), color: p.lineSoft },
+  ]);
+
+  let state = {};
+  const lines = body.length ? body : [''];
+  for (const raw of lines) {
+    const result = highlightLine(raw.replace(/\t/g, '  '), label, state);
+    state = result.state;
+    const spans = result.spans.length ? result.spans : [{ t: '' }];
+    // Code is not prose: wrapping it on spaces would move a token onto a line where it
+    // does not belong. Long lines are cut with a marker instead, which is honest about
+    // there being more and keeps the block rectangular.
+    rows.push([gutter, ...truncateRow(spans, inner, g('›', '>'))]);
+  }
+  rows.push([{ t: g('▙', '+'), color: p.tealDeep }, { t: g('─', '-').repeat(Math.max(0, width - 2)), color: p.lineSoft }]);
+  return rows;
+}
+
+/** A pipe table, measured on visible width and clipped to fit the terminal. */
+function table(block, width) {
+  const p = palette();
+  const cells = block
+    .filter((line) => !TABLE_SEP.test(line))
+    .map((line) => TABLE_ROW.exec(line)[1].split('|').map((cell) => cell.trim()));
+  if (!cells.length) return [];
+
+  const columns = Math.max(...cells.map((row) => row.length));
+  const widths = Array.from({ length: columns }, (_, i) =>
+    Math.max(1, ...cells.map((row) => stringWidth(row[i] || ''))));
+
+  // Shrink the widest column until the table fits rather than letting it overflow.
+  const overhead = (columns - 1) * 3;
+  let total = widths.reduce((a, b) => a + b, 0) + overhead;
+  while (total > width && Math.max(...widths) > 4) {
+    const widest = widths.indexOf(Math.max(...widths));
+    widths[widest] -= 1;
+    total -= 1;
+  }
+
+  const rows = [];
+  cells.forEach((row, index) => {
+    const header = index === 0;
+    const spans = [];
+    for (let col = 0; col < columns; col++) {
+      if (col) spans.push({ t: g(' │ ', ' | '), color: p.line });
+      const content = truncateRow(inlineSpans(row[col] || '', header ? { bold: true, color: p.tealSoft } : {}), widths[col]);
+      spans.push(...content);
+      const gap = widths[col] - contentWidth(content);
+      if (gap > 0) spans.push({ t: ' '.repeat(gap) });
+    }
+    rows.push(spans);
+    if (header) {
+      rows.push(widths.flatMap((w, col) => (col ? [{ t: g('─┼─', '-+-'), color: p.line }, { t: g('─', '-').repeat(w), color: p.line }] : [{ t: g('─', '-').repeat(w), color: p.line }])));
+    }
+  });
+  return rows;
+}

package/src/tui/mouse.js

@@ -0,0 +1,125 @@
+// ─── Mouse ──────────────────────────────────────────────────────────────────────
+//
+// Ink has no mouse support, so this is the whole of it: turn the terminal's reporting
+// on, recognise the sequences when they arrive through the ordinary key handler, and
+// turn it off again on the way out.
+//
+// Two things make that safe to do:
+//
+//   • **SGR extended mode (1006) or nothing.** The original X10 encoding packs the
+//     coordinates into single bytes offset by 32, so it cannot report a click past
+//     column 223 — on a wide terminal the right-hand half of the screen silently stops
+//     responding. Every terminal worth enabling this for has supported 1006 for a
+//     decade; the ones that do not simply get no mouse, which is the honest outcome.
+//   • **The sequences arrive as ordinary input.** Ink's key parser does not recognise
+//     them, so it hands them through as a plain string with the leading escape stripped.
+//     That is lucky rather than designed, and it is why the guard below runs before
+//     anything can insert them into the composer — without it, scrolling the wheel types
+//     `[<64;10;5M` into your prompt.
+//
+// Enabling mouse reporting takes over the terminal's own text selection. That is a real
+// cost, not a detail: people select and copy out of a terminal constantly. Hold Shift to
+// get the native behaviour back in every terminal that supports this, and `/mouse off`
+// turns it off for good.
+
+// Button-event tracking (1002) rather than any-event (1003): 1003 reports every pixel of
+// pointer motion, which on a busy screen is thousands of writes a second for information
+// nothing here uses.
+const ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+const OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+
+// Ink strips the leading escape, so both spellings have to match.
+const SGR = /^\x1b?\[<(\d+);(\d+);(\d+)([Mm])$/;
+
+// The X10 encoding: `CSI M` followed by three raw bytes. A terminal that does not
+// understand the 1006 request still honours 1000 and reports in this form — and those
+// bytes are unprintable garbage that would otherwise be typed into the composer. It is
+// recognised only to be swallowed: its coordinates top out at column 223, which makes
+// it useless for anything but ignoring.
+const X10 = /^\x1b?\[M[\s\S]{3}$/;
+
+/** True once, per process: never write the disable sequence for something never enabled. */
+let enabled = false;
+
+export function enableMouse(stream = process.stdout) {
+  if (enabled || !stream?.isTTY) return false;
+  try { stream.write(ON); enabled = true; } catch { /* not a real terminal */ }
+  return enabled;
+}
+
+export function disableMouse(stream = process.stdout) {
+  if (!enabled) return;
+  try { stream.write(OFF); } catch { /* going away anyway */ }
+  enabled = false;
+}
+
+export const mouseEnabled = () => enabled;
+
+/**
+ * One input string → a mouse event, or null.
+ *
+ * The button field is a bitfield: the low two bits are which button, bit 5 (32) means
+ * the pointer was moving with a button held, and bit 6 (64) means the wheel. Shift, Alt
+ * and Ctrl ride in bits 2–4 and are reported so a Shift-click can mean something
+ * different from a click.
+ */
+export function parseMouse(input) {
+  const m = SGR.exec(String(input ?? ''));
+  if (!m) return null;
+  const code = Number(m[1]);
+  const x = Number(m[2]);
+  const y = Number(m[3]);
+  const pressed = m[4] === 'M';
+
+  const wheel = (code & 64) !== 0;
+  const motion = (code & 32) !== 0;
+  const button = code & 3;
+
+  return {
+    x,
+    y,
+    shift: (code & 4) !== 0,
+    meta: (code & 8) !== 0,
+    ctrl: (code & 16) !== 0,
+    // A wheel "button" of 0 is up and 1 is down; 2 and 3 are horizontal tilt, which is
+    // reported so a future horizontal scroll has somewhere to go rather than being
+    // silently read as a vertical one.
+    kind: wheel
+      ? (button === 0 ? 'wheelUp' : button === 1 ? 'wheelDown' : button === 2 ? 'wheelLeft' : 'wheelRight')
+      : motion ? 'drag'
+        : pressed ? 'down' : 'up',
+    button: wheel ? null : button === 0 ? 'left' : button === 1 ? 'middle' : button === 2 ? 'right' : null,
+  };
+}
+
+/** Does this input look like a mouse report we should swallow rather than type? */
+export const isMouse = (input) => {
+  const s = String(input ?? '');
+  return SGR.test(s) || X10.test(s);
+};
+
+/**
+ * A hit map for one frame.
+ *
+ * The layout is computed in one place, so the regions can be computed there too rather
+ * than measured afterwards. Rows and columns are 1-based to match what the terminal
+ * reports, and later registrations win — which is what makes an overlay's buttons
+ * reachable while the header underneath it is not.
+ */
+export function createHitMap() {
+  let regions = [];
+  return {
+    reset() { regions = []; },
+    add(region) { if (region && region.action) regions.push(region); },
+    /** The topmost region containing this cell, or null. */
+    at(x, y) {
+      for (let i = regions.length - 1; i >= 0; i--) {
+        const r = regions[i];
+        if (x >= r.x1 && x <= r.x2 && y >= r.y1 && y <= r.y2) return r;
+      }
+      return null;
+    },
+    get size() { return regions.length; },
+    all() { return regions.slice(); },
+  };
+}

package/src/tui/theme.js

@@ -0,0 +1,201 @@
+// ─── The palette ────────────────────────────────────────────────────────────────
+//
+// Every colour the app view draws comes from here as a hex string, because Ink takes
+// hex directly and downsamples for terminals that cannot do truecolor. Naming them by
+// ROLE rather than by hue is what makes a second theme a data change instead of a
+// rewrite: nothing downstream asks for "orange", it asks for `brand`.
+//
+// The two-tone identity is the site's: coral leads, teal answers. Red and amber are
+// kept strictly semantic — a failure and a warning — so a screen with no red on it is
+// a screen with nothing wrong, which is a property worth having.
+
+import { themeName } from '../ui.js';
+
+const DARK = {
+  name: 'dark',
+  bg: '#0b0f14',
+  surface: '#11161e',
+  raised: '#18202b',
+  sunken: '#080c11',
+  line: '#212c3a',
+  lineSoft: '#161f2a',
+  text: '#e6edf3',
+  muted: '#93a4b8',
+  dim: '#5d6e82',
+  faint: '#3a4757',
+  brand: '#ff6b4a',
+  brandSoft: '#ffa285',
+  brandDeep: '#c94a2e',
+  teal: '#20a898',
+  tealSoft: '#63dccc',
+  tealDeep: '#0f7a6e',
+  green: '#3fb950',
+  yellow: '#d9a441',
+  red: '#ff6b6b',
+  redDeep: '#a83232',
+  purple: '#b392f0',
+  blue: '#5aa9ff',
+  cyan: '#56d4dd',
+  // Syntax
+  synKeyword: '#ff8fa3',
+  synString: '#9ae6a0',
+  synNumber: '#f0b86e',
+  synComment: '#5d6e82',
+  synFunc: '#7cc5ff',
+  synType: '#e3c078',
+  synPunct: '#93a4b8',
+  // Diff
+  addFg: '#7ee787',
+  addBg: '#0d2a14',
+  delFg: '#ff9f9f',
+  delBg: '#2d1113',
+  hunkFg: '#7cc5ff',
+};
+
+const LIGHT = {
+  ...DARK,
+  name: 'light',
+  bg: '#fbf9f6',
+  surface: '#ffffff',
+  raised: '#f3efe9',
+  sunken: '#efe9e1',
+  line: '#d9d0c4',
+  lineSoft: '#e7e0d6',
+  text: '#1a222c',
+  muted: '#5a6673',
+  dim: '#83909e',
+  faint: '#aab4bf',
+  brand: '#c8431f',
+  brandSoft: '#e4724f',
+  brandDeep: '#8f2c11',
+  teal: '#0f7a6e',
+  tealSoft: '#2ba394',
+  tealDeep: '#0a574e',
+  green: '#1a7f37',
+  yellow: '#8a6100',
+  red: '#c0392b',
+  redDeep: '#8a2520',
+  purple: '#6f42c1',
+  blue: '#0a58ca',
+  cyan: '#0b7285',
+  synKeyword: '#a8265c',
+  synString: '#1a7f37',
+  synNumber: '#8a4b00',
+  synComment: '#83909e',
+  synFunc: '#0a58ca',
+  synType: '#7a5200',
+  synPunct: '#5a6673',
+  addFg: '#116329',
+  addBg: '#e2f6e6',
+  delFg: '#a40e26',
+  delBg: '#fbe6e8',
+  hunkFg: '#0a58ca',
+};
+
+const OCEAN = {
+  ...DARK,
+  name: 'ocean',
+  bg: '#04141a',
+  surface: '#082028',
+  raised: '#0d2d37',
+  line: '#17414d',
+  lineSoft: '#0f2f39',
+  text: '#e4f5f2',
+  muted: '#8fbdb8',
+  dim: '#5b8b88',
+  faint: '#36605e',
+  brand: '#ff7a5c',
+  brandSoft: '#ffb39d',
+  teal: '#2fd4bd',
+  tealSoft: '#7df0e0',
+};
+
+// Blue leads instead of coral: deuteranopia and protanopia both keep red/orange and
+// green apart poorly, and a UI whose primary accent is orange loses its whole voice.
+const DALTONIZED = {
+  ...DARK,
+  name: 'daltonized',
+  brand: '#5aa9ff',
+  brandSoft: '#9ecbff',
+  brandDeep: '#2b6cb0',
+  teal: '#d9a441',
+  tealSoft: '#f0c97a',
+  green: '#5aa9ff',
+  addFg: '#9ecbff',
+  addBg: '#0d1e2e',
+  delFg: '#f0c97a',
+  delBg: '#2a2210',
+  synString: '#9ecbff',
+  synKeyword: '#f0c97a',
+};
+
+const THEMES = { dark: DARK, light: LIGHT, ocean: OCEAN, daltonized: DALTONIZED };
+
+/**
+ * A "high contrast" flag rather than a fifth theme: it lifts text off the ground and
+ * drops every decorative mid-tone onto the text colour, which is the only change that
+ * matters for someone who cannot read #5d6e82 on #0b0f14.
+ */
+function contrastify(palette) {
+  return {
+    ...palette,
+    text: palette.name === 'light' ? '#000000' : '#ffffff',
+    muted: palette.name === 'light' ? '#2b3440' : '#d6dee7',
+    dim: palette.name === 'light' ? '#4a5563' : '#aab8c6',
+    faint: palette.name === 'light' ? '#6b7684' : '#8797a8',
+    line: palette.name === 'light' ? '#8d8477' : '#5a6878',
+  };
+}
+
+let cached = null;
+
+/** The active palette. Re-read after /theme; cheap enough to call per render. */
+export function palette() {
+  const name = themeName();
+  const high = process.env.JAITUS_HIGH_CONTRAST === '1';
+  const key = `${name}:${high}`;
+  if (cached?.key === key) return cached.value;
+  const base = THEMES[name] || DARK;
+  const value = high ? contrastify(base) : base;
+  cached = { key, value };
+  return value;
+}
+
+export function resetPalette() { cached = null; }
+
+export const THEME_NAMES = Object.keys(THEMES);
+
+/**
+ * Blend two hex colours. Used for gradients and for the animated sweeps — computing
+ * the stops rather than listing them means a gradient is defined once and works at
+ * any width, including a wordmark that has to survive an 80-column terminal.
+ */
+export function mix(a, b, t) {
+  const pa = hex(a);
+  const pb = hex(b);
+  const k = Math.max(0, Math.min(1, t));
+  const ch = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * k);
+  return `#${[ch(0), ch(1), ch(2)].map((n) => n.toString(16).padStart(2, '0')).join('')}`;
+}
+
+function hex(value) {
+  const s = String(value).replace('#', '');
+  const full = s.length === 3 ? s.split('').map((ch) => ch + ch).join('') : s;
+  return [parseInt(full.slice(0, 2), 16), parseInt(full.slice(2, 4), 16), parseInt(full.slice(4, 6), 16)];
+}
+
+/** `steps` evenly spaced colours from `a` to `b`, inclusive of both ends. */
+export function ramp(a, b, steps) {
+  if (steps <= 1) return [a];
+  return Array.from({ length: steps }, (_, i) => mix(a, b, i / (steps - 1)));
+}
+
+/**
+ * A colour ramp that runs a → b → a, so a sweep across it returns to where it started
+ * and the loop has no visible seam. Every moving gradient in the app uses this.
+ */
+export function pingPong(a, b, steps) {
+  const half = Math.max(2, Math.ceil(steps / 2));
+  const up = ramp(a, b, half);
+  return [...up, ...up.slice(1, -1).reverse()];
+}