@mnemahq/cli 0.3.1 → 0.7.0

package/src/render/pick.mjs

@@ -0,0 +1,131 @@
+/**
+ * Choose from a list without copying an id (t-631).
+ *
+ * ⭐ THE CLI KEPT ASKING FOR THINGS IT COULD OFFER. `mnema doc` with no argument
+ * printed "Usage: mnema doc <id>" — so the actual workflow was: run `mnema docs`,
+ * read a truncated title, select eight hex characters with the mouse, paste. Every
+ * id in this CLI is a UUID prefix that nobody can hold in their head, and the list
+ * command already knows all of them.
+ *
+ * ⚠️ RAW MODE IS THE DANGEROUS PART, and the danger is entirely in the exits. A
+ * process that leaves the terminal in raw mode with the cursor hidden hands back a
+ * shell where typing shows nothing and Ctrl-C does not work — the user's next move
+ * is to close the window. So there is exactly ONE restore path here, every exit
+ * goes through it, and it is also wired to SIGINT and to process exit. This is the
+ * single most damaging thing a terminal UI can get wrong, and it is worth more care
+ * than the feature itself.
+ */
+
+import { c, truncate, width } from './theme.mjs';
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+const CLEAR = '\x1b[K';
+
+/** How many rows to show at once. Longer lists scroll within this window. */
+const WINDOW = 10;
+
+/**
+ * @param items  [{ label, hint }]
+ * @returns the chosen index, or null if cancelled / not interactive
+ */
+export function pick(items, { title = 'Select', stream = process.stderr, input = process.stdin } = {}) {
+  // Not interactive: there is nothing to drive the selection with. Returning null
+  // rather than hanging on a stdin that will never produce a keypress.
+  if (!items.length || !input.isTTY || !stream.isTTY || typeof input.setRawMode !== 'function') {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let top = 0;
+    let drawn = 0;
+    let finished = false;
+
+    const paint = () => {
+      // Move back over what we drew last time, clearing as we go.
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      const w = width();
+      const lines = [];
+      lines.push(`${c.bold(title)}  ${c.dim('↑↓ move · enter select · esc cancel')}`);
+      const view = items.slice(top, top + WINDOW);
+      for (let i = 0; i < view.length; i += 1) {
+        const idx = top + i;
+        const on = idx === cursor;
+        const label = truncate(view[i].label ?? '', w - 6);
+        // ⚠️ Colour AFTER truncation — the ordering rule from t-628. Truncating a
+        // coloured string cuts inside the escape and leaves the terminal stuck in
+        // whatever attribute was open.
+        lines.push(on ? `${c.cyan('❯')} ${c.bold(label)}` : `  ${c.dim(label)}`);
+      }
+      if (items.length > WINDOW) {
+        lines.push(c.dim(`  ${cursor + 1}/${items.length}`));
+      }
+      stream.write(lines.map((l) => `${CLEAR}${l}`).join('\n') + '\n');
+      drawn = lines.length;
+    };
+
+    // ⭐ ONE restore path. Every exit — enter, esc, Ctrl-C, an unexpected throw,
+    // the process dying — comes through here, and it is idempotent.
+    const restore = () => {
+      if (finished) return;
+      finished = true;
+      try { input.setRawMode(false); } catch { /* already closed */ }
+      input.pause();
+      input.removeListener('data', onData);
+      process.removeListener('SIGINT', onSigint);
+      process.removeListener('exit', restore);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      for (let i = 0; i < drawn; i += 1) stream.write(`${CLEAR}\n`);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      stream.write(SHOW);
+    };
+
+    function onSigint() {
+      restore();
+      // Exit the way an unhandled Ctrl-C would, so shells see the right status.
+      process.exit(130);
+    }
+
+    // Named constants, because a literal control byte pasted into source is
+    // invisible in a diff and unreadable in a comparison.
+    const CTRL_C = '\u0003';
+    const CTRL_D = '\u0004';
+    const ESC = '\u001b';
+    const UP = '\u001b[A';
+    const DOWN = '\u001b[B';
+    const PGUP = '\u001b[5~';
+    const PGDN = '\u001b[6~';
+
+    function onData(buf) {
+      const s = buf.toString('utf8');
+      // ⚠️ In raw mode Ctrl-C is DATA, not a signal — nothing else handles it.
+      if (s === CTRL_C) { onSigint(); return; }
+      if (s === CTRL_D || s === ESC || s === 'q') { restore(); resolve(null); return; }
+      if (s === '\r' || s === '\n') { restore(); resolve(cursor); return; }
+
+      let moved = 0;
+      if (s === UP || s === 'k') moved = -1;
+      else if (s === DOWN || s === 'j') moved = 1;
+      else if (s === PGUP) moved = -WINDOW;
+      else if (s === PGDN) moved = WINDOW;
+      else if (s === 'g') { cursor = 0; top = 0; paint(); return; }
+      else if (s === 'G') { cursor = items.length - 1; top = Math.max(0, items.length - WINDOW); paint(); return; }
+      if (!moved) return;
+
+      cursor = Math.min(items.length - 1, Math.max(0, cursor + moved));
+      if (cursor < top) top = cursor;
+      if (cursor >= top + WINDOW) top = cursor - WINDOW + 1;
+      paint();
+    }
+
+    stream.write(HIDE);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding('utf8');
+    input.on('data', onData);
+    process.on('SIGINT', onSigint);
+    process.on('exit', restore);
+    paint();
+  });
+}

package/src/render/theme.mjs

@@ -0,0 +1,255 @@
+/**
+ * The CLI's presentation primitives (t-628).
+ *
+ * ⭐ COLOUR WAS UNCONDITIONAL, WHICH IS THE BUG UNDER THE BUG. util.mjs's `c`
+ * helper emitted `\x1b[Nm…\x1b[0m` with no isTTY check, no NO_COLOR, no
+ * FORCE_COLOR anywhere in the package — so `mnema tasks | less` and
+ * `mnema docs > out.txt` both contained raw escape bytes, and nothing in the CLI
+ * had any idea how wide the terminal was. Eleven separate hard-coded `padEnd`
+ * widths disagreed with each other because there was nothing to agree with.
+ *
+ * This is the one module that knows about the terminal. Everything above it asks
+ * questions ("how wide?", "truncate this") instead of writing escapes.
+ *
+ * ⚠️ THE ORDERING RULE THAT MUST NOT BREAK: pad and truncate the PLAIN string,
+ * then colour it. Alignment is correct in the current CLI only because every call
+ * site happens to do this by hand — `id.padEnd(8)` before `c.cyan(...)`. An
+ * escape sequence is zero columns wide but many characters long, so padding a
+ * coloured string pads by the wrong amount and the column silently drifts. Every
+ * helper here takes plain text and returns coloured text; none of them accepts
+ * pre-coloured input.
+ */
+
+/**
+ * ⚠️ THREE SIGNALS, IN THIS ORDER, and the order is the convention every other
+ * CLI follows: an explicit FORCE_COLOR wins, then NO_COLOR (https://no-color.org
+ * — presence alone counts, whatever the value), then whether stdout is a real
+ * terminal. Reading isTTY first would make FORCE_COLOR useless in exactly the
+ * case people set it: piping into something that renders colour itself.
+ */
+function detectColour() {
+  const env = process.env;
+  // ⚠️ AN EMPTY STRING IS "UNSET", NOT "ON". `FORCE_COLOR=` in a shell sets the
+  // variable to '' — and reading that as force-on made `NO_COLOR=1 FORCE_COLOR= …`
+  // emit colour anyway, which is precisely the combination someone types when
+  // they are trying hard to turn it off. Caught by the verification run, not by
+  // reading the code.
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '') {
+    return force !== '0' && force !== 'false';
+  }
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false;
+  if (env.TERM === 'dumb') return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+let colourEnabled = detectColour();
+
+/** Test seam. Production code never calls this. */
+export function setColour(on) { colourEnabled = on; }
+export function colourOn() { return colourEnabled; }
+
+const wrap = (open) => (s) => (colourEnabled ? `\x1b[${open}m${s}\x1b[0m` : String(s));
+
+/**
+ * Same six names the old `c` helper had, so the migration is a rename rather
+ * than a rewrite, plus the two the redesign needs.
+ */
+export const c = {
+  dim: wrap(2),
+  bold: wrap(1),
+  red: wrap(31),
+  green: wrap(32),
+  yellow: wrap(33),
+  cyan: wrap(36),
+  blue: wrap(34),
+  magenta: wrap(35),
+};
+
+/** Strip escapes — needed to measure anything that may already be coloured. */
+export function strip(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/**
+ * How many terminal columns a string occupies.
+ *
+ * ⚠️ NOT `.length`. The old `trunc()` measured UTF-16 code units, which is wrong
+ * three separate ways: a CJK ideograph is one unit but two columns, an emoji is
+ * two units and two columns, and a combining accent is one unit and zero columns.
+ * A list of Japanese doc titles came out visibly ragged.
+ *
+ * Uses Intl.Segmenter to walk graphemes so a family emoji or a flag counts once.
+ * It has been in Node since 16, and this package requires 18.
+ */
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+
+export function displayWidth(s) {
+  const plain = strip(s);
+  let w = 0;
+  for (const { segment } of segmenter.segment(plain)) {
+    const cp = segment.codePointAt(0);
+    if (cp === undefined) continue;
+    // Zero-width: combining marks, ZWJ, variation selectors, control chars.
+    if (cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x0300 && cp <= 0x036f)) continue;
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0)) continue;
+    w += isWide(cp) ? 2 : 1;
+  }
+  return w;
+}
+
+/** East Asian Wide + Fullwidth ranges, plus the emoji blocks that render double. */
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f)     // Hangul Jamo
+    || (cp >= 0x2e80 && cp <= 0xa4cf)  // CJK radicals … Yi
+    || (cp >= 0xac00 && cp <= 0xd7a3)  // Hangul syllables
+    || (cp >= 0xf900 && cp <= 0xfaff)  // CJK compatibility ideographs
+    || (cp >= 0xfe30 && cp <= 0xfe6f)  // CJK compatibility forms
+    || (cp >= 0xff00 && cp <= 0xff60)  // Fullwidth forms
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f64f) // emoji
+    || (cp >= 0x1f900 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd) // CJK ext B+
+  );
+}
+
+/**
+ * Truncate to `n` COLUMNS, with an ellipsis when it actually cut something.
+ *
+ * ⚠️ THE ELLIPSIS IS NOT DECORATION. `search` used to `slice(0, 140)` with no
+ * marker, so a preview that stopped mid-sentence was indistinguishable from a
+ * document that ended there. Everywhere that shortens text must say it did.
+ */
+export function truncate(s, n) {
+  const raw = String(s ?? '');
+  const plain = strip(raw);
+  if (n <= 0) return '';
+  // ⭐ IF IT FITS, HAND BACK WHAT WE WERE GIVEN — escapes and all. Unconditionally
+  // returning the stripped string is why `c.bold(user_code)` rendered plain in the
+  // login block and `c.red('not linked')` renders plain in `status`: the caller
+  // coloured it, this measured it, and the colour was silently thrown away.
+  //
+  // ⚠️ WHEN IT MUST CUT, THE COLOUR STILL GOES. Slicing inside an SGR run leaves
+  // the terminal stuck in whatever attribute was open, which is worse than a plain
+  // string. So: preserved when whole, dropped when cut — and the fix for a long
+  // coloured value is to pass plain text plus a style function, as table() wants.
+  if (displayWidth(plain) <= n) return raw;
+  let out = '';
+  let w = 0;
+  for (const { segment } of segmenter.segment(plain)) {
+    const sw = displayWidth(segment);
+    if (w + sw > n - 1) break;
+    out += segment;
+    w += sw;
+  }
+  return `${out}…`;
+}
+
+/**
+ * Pad to `n` columns.
+ *
+ * Measures with escapes stripped and pads the ORIGINAL, so a pre-coloured cell
+ * keeps its colour and still lands in the right column. Padding is whitespace
+ * outside the SGR run, so there is nothing unsafe about it — unlike truncation,
+ * which has to cut and therefore cannot preserve an open attribute.
+ */
+export function pad(s, n, align = 'left') {
+  const raw = String(s ?? '');
+  const gap = n - displayWidth(raw);
+  if (gap <= 0) return raw;
+  return align === 'right' ? ' '.repeat(gap) + raw : raw + ' '.repeat(gap);
+}
+
+/**
+ * Usable terminal width.
+ *
+ * COLUMNS is honoured because that is how a user (and every test) says "pretend
+ * the terminal is this wide" for something that is not a TTY. Clamped low so a
+ * 20-column terminal degrades rather than producing negative padding, and high so
+ * a maximised 4K window does not stretch a two-column list across 400 characters.
+ */
+export function width() {
+  const raw = Number(process.env.COLUMNS) || process.stdout.columns || 80;
+  return Math.max(40, Math.min(raw, 120));
+}
+
+/**
+ * Render aligned rows from `[{ cells: [...], style?: [...] }]`.
+ *
+ * ⭐ REPLACES ELEVEN HAND-PICKED padEnd WIDTHS. Column widths are measured from
+ * the content, then the LAST column absorbs whatever is left so a long title
+ * truncates instead of wrapping and destroying the alignment of every row under
+ * it. `style` is applied per cell AFTER padding, preserving the ordering rule at
+ * the top of this file.
+ */
+export function table(rows, { indent = 2, gap = 2, max = width() } = {}) {
+  if (!rows.length) return [];
+  const cols = Math.max(...rows.map((r) => r.cells.length));
+  const widths = [];
+  for (let i = 0; i < cols; i += 1) {
+    widths[i] = Math.max(...rows.map((r) => displayWidth(r.cells[i] ?? '')));
+  }
+  // Everything except the final column is fixed; the final column gets the rest.
+  const fixed = indent + widths.slice(0, -1).reduce((a, b) => a + b + gap, 0);
+  widths[cols - 1] = Math.max(8, max - fixed);
+
+  return rows.map((r) => {
+    const parts = r.cells.map((cell, i) => {
+      const isLast = i === cols - 1;
+      const text = isLast ? truncate(cell ?? '', widths[i]) : pad(cell ?? '', widths[i]);
+      const style = r.style?.[i];
+      // Trailing cell is not padded — a padded last column leaves invisible
+      // whitespace that shows up when someone copies a row out of the terminal.
+      const sized = isLast ? text : text;
+      return style ? style(sized) : sized;
+    });
+    return ' '.repeat(indent) + parts.join(' '.repeat(gap)).replace(/\s+$/, '');
+  });
+}
+
+/**
+ * One heading grammar.
+ *
+ * ⚠️ THE OLD CLI HAD FOUR: product-prefixed ("Mnema status"), noun + count
+ * ("Server sessions (7)"), count-first ("12 task(s)"), and bare noun ("Pulse").
+ * Nothing was wrong with any one of them; having four made the output read as
+ * four different programs.
+ */
+export function section(title, meta) {
+  const left = c.bold(title);
+  if (!meta) return left;
+  const room = width() - displayWidth(title) - displayWidth(meta) - 2;
+  return room > 0 ? `${left}${' '.repeat(room)}${c.dim(meta)}` : `${left}  ${c.dim(meta)}`;
+}
+
+/**
+ * A terminal hyperlink (OSC 8), degrading to plain text where unsupported.
+ *
+ * ⚠️ NOT EMITTED WHEN COLOUR IS OFF. The same detection covers both: if stdout is
+ * a pipe, an OSC 8 sequence is corruption in the consumer's data, not a link.
+ */
+export function link(label, url) {
+  if (!colourEnabled) return `${label} (${url})`;
+  return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
+
+/**
+ * Status glyphs, used consistently rather than ad hoc per command.
+ *
+ * ⚠️ TWO FORMS ON PURPOSE. `mark.*` returns a COLOURED glyph for direct printing;
+ * `glyph.*` is the plain character, for anything that will be measured or padded.
+ * Passing `mark.ok()` into table() silently loses the colour — pad() strips escapes
+ * to measure, exactly as the ordering rule at the top of this file requires — so a
+ * table wants the plain glyph plus a style function, not a pre-coloured cell.
+ * I hit this myself the first time I wrote the doctor list.
+ */
+export const glyph = { ok: '✓', bad: '✗', warn: '!', dot: '·' };
+
+export const mark = {
+  ok: () => c.green(glyph.ok),
+  bad: () => c.red(glyph.bad),
+  warn: () => c.yellow(glyph.warn),
+  dot: () => c.dim(glyph.dot),
+};

package/src/render/wait.mjs

@@ -0,0 +1,96 @@
+/**
+ * Showing that something is still happening (t-631).
+ *
+ * ⭐ THE LOGIN GREW A DOT PER POLL. `mnema login` wrote one '.' every `interval`
+ * seconds — 5s by default against a code that lives 10 minutes, so up to 120 dots.
+ * They wrap. On an 80-column terminal the second line of dots pushes the
+ * `user_code` off the top, and the code is THE ONE THING the user has to read. A
+ * progress indicator that destroys the information it is decorating is worse than
+ * no progress indicator.
+ *
+ * ⚠️ AND IT COULD NOT CLEAN UP AFTER ITSELF. Success did:
+ *
+ *     process.stdout.write('\r' + ' '.repeat(40) + '\r')
+ *
+ * Forty spaces, against a line that is 23 characters plus every dot written since.
+ * Past the fortieth character the residue simply stayed on screen. `\x1b[K` clears
+ * from the cursor to the end of the line and cannot be off by a count.
+ *
+ * A spinner redraws ONE line in place, so the code above it stays put however long
+ * the wait runs.
+ */
+
+import { c } from './theme.mjs';
+
+const BRAILLE = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const ASCII = ['-', '\\', '|', '/'];
+
+/**
+ * ⚠️ NOT EVERY TERMINAL HAS THE BRAILLE BLOCK. Where it is missing the frame
+ * renders as a replacement box that flickers once a tick, which looks broken
+ * rather than busy. Locale is the only signal available without querying the
+ * terminal, so an ASCII fallback is the honest default when it is not UTF-8.
+ */
+function frames() {
+  const enc = `${process.env.LC_ALL ?? ''}${process.env.LC_CTYPE ?? ''}${process.env.LANG ?? ''}`;
+  return /UTF-?8/i.test(enc) ? BRAILLE : ASCII;
+}
+
+const CLEAR_LINE = '\r\x1b[K';
+
+/**
+ * A single self-redrawing line.
+ *
+ * `stream` defaults to stderr so a spinner never lands in piped DATA — the same
+ * rule `doctor` needed in t-630, where "… checking connectivity" was being
+ * captured into `report.txt` as though it were part of the report.
+ *
+ * ⚠️ NO-OP ON A NON-TTY, and that is not merely tidy. Writing \r frames into a log
+ * file produces one enormous unreadable line, and into a CI transcript, thousands.
+ */
+export function spinner(label, { stream = process.stderr, interval = 100 } = {}) {
+  const live = Boolean(stream.isTTY);
+  const startedAt = Date.now();
+  let i = 0;
+  let timer = null;
+  let text = label;
+  const f = frames();
+
+  const elapsed = () => {
+    const s = Math.round((Date.now() - startedAt) / 1000);
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
+  };
+
+  const draw = () => {
+    stream.write(`${CLEAR_LINE}  ${c.cyan(f[i % f.length])} ${text} ${c.dim(elapsed())}`);
+    i += 1;
+  };
+
+  if (live) {
+    draw();
+    timer = setInterval(draw, interval);
+    // Do not hold the process open just to animate.
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  return {
+    /** Change the message without losing the line or the elapsed clock. */
+    update(next) {
+      text = next;
+      if (live) draw();
+    },
+    /**
+     * Erase the line and optionally print something in its place.
+     *
+     * ⚠️ ALWAYS ERASES, even when it was never drawn, because a caller that has to
+     * remember whether the terminal was live will eventually forget.
+     */
+    stop(finalLine) {
+      if (timer) clearInterval(timer);
+      if (live) stream.write(CLEAR_LINE);
+      if (finalLine) stream.write(`${finalLine}\n`);
+    },
+    elapsed,
+    live,
+  };
+}

package/src/tui/app.mjs

@@ -0,0 +1,89 @@
+/**
+ * The shell: header, screen stack, key map, error panel (t-632).
+ *
+ * ⚠️ A STACK, NOT A ROUTER, and `esc` pops it. But the top-level screen keys
+ * REPLACE the root rather than pushing, so mashing keys cannot build a
+ * forty-deep stack that takes forty escapes to unwind.
+ *
+ * ⚠️ AUTH IS A TAKEOVER, NOT A PANEL. Every screen needs a credential, so an
+ * AuthError leaves nothing usable behind it. And the device flow deliberately does
+ * NOT run inside Ink: it needs its own stdout and a browser, and it would fight
+ * the render loop for the terminal. Pressing `l` quits cleanly and prints the
+ * command to run — which is honest about what is about to happen, rather than
+ * appearing to log in and then redrawing over the code the user has to read.
+ */
+
+import { useState, useMemo } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { html } from './h.mjs';
+import { Briefing } from './screens/briefing.mjs';
+import { Finding } from './screens/finding.mjs';
+
+const HOME = { name: 'briefing' };
+
+export function App({ ctx }) {
+  const { exit } = useApp();
+  const [stack, setStack] = useState([HOME]);
+  const [fatal, setFatal] = useState(null);
+
+  // ⭐ THE AUTH TAKEOVER HAS TO BE WIRED, not merely rendered. Every screen fetches
+  // through this wrapper, so an AuthError anywhere flips the whole app to the
+  // signed-out state instead of each screen showing its own red line for the same
+  // single cause. Matched on constructor NAME: the SDK's errors can cross a module
+  // realm here (the TUI is loaded by a dynamic import) and instanceof is unreliable
+  // across realms.
+  const wrapped = useMemo(() => ({
+    ...ctx,
+    call: async (fn) => {
+      try {
+        return await ctx.call(fn);
+      } catch (e) {
+        if (e?.constructor?.name === 'AuthError' || e?.code === 'unauthorized') {
+          setFatal({ kind: 'auth', message: e.message ?? 'That credential is not valid.' });
+        }
+        throw e;
+      }
+    },
+  }), [ctx]);
+
+  const top = stack[stack.length - 1];
+  const push = (screen) => setStack((s) => [...s, screen]);
+  const pop = () => setStack((s) => (s.length > 1 ? s.slice(0, -1) : s));
+
+  useInput((input, key) => {
+    if (input === 'q' || (key.ctrl && input === 'c')) { exit(); return; }
+    if (key.escape) { pop(); return; }
+    if (fatal?.kind === 'auth' && input === 'l') { exit(); return; }
+  });
+
+  if (fatal?.kind === 'auth') {
+    return html`
+      <${Box} flexDirection="column" paddingX=${1}>
+        <${Text} color="red" bold>Not signed in<//>
+        <${Text} dimColor>${fatal.message}<//>
+        <${Box} marginTop=${1}><${Text}>Press <${Text} bold>l<//> to quit and run <${Text} bold>mnema login<//><//><//>
+      <//>`;
+  }
+
+  const body = top.name === 'briefing'
+    ? html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`
+    : html`<${Finding} finding=${top.finding} />`;
+
+  return html`
+    <${Box} flexDirection="column">
+      <${Box} paddingX=${1}>
+        <${Text} bold color="cyan">mnema<//>
+        <${Text} dimColor>  ${ctx.workspaceName ?? ctx.workspaceId ?? ''}<//>
+        ${ctx.plan ? html`<${Text} dimColor>  ${ctx.plan}<//>` : null}
+        ${ctx.edition === 'core' ? html`<${Text} dimColor>  core<//>` : null}
+      <//>
+      ${body}
+      <${Box} paddingX=${1} marginTop=${1}>
+        <${Text} dimColor>${top.name === 'briefing'
+          ? '↑↓ move · enter open · r refresh · q quit'
+          : 'esc back · q quit'}<//>
+      <//>
+    <//>`;
+}
+
+export { HOME };

package/src/tui/components/list.mjs

@@ -0,0 +1,57 @@
+/**
+ * One selectable list, used by every screen (t-632).
+ *
+ * ⚠️ ONE KEYBOARD MODEL, DEFINED ONCE. The fastest way to make a TUI feel
+ * unfinished is for two lists to disagree about whether k moves up.
+ *
+ * The visible window scrolls rather than the list growing without bound: a
+ * terminal has a fixed height, and a 40-row findings list drawn in full pushes the
+ * header and the caveat banner off the top — the same failure the login dot line
+ * had, where the progress indicator destroyed the information it decorated.
+ */
+
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+
+export function List({ items, focused = true, height = 10, onSelect }) {
+  const [cursor, setCursor] = useState(0);
+  const [top, setTop] = useState(0);
+
+  const move = (delta) => {
+    const next = Math.min(items.length - 1, Math.max(0, cursor + delta));
+    setCursor(next);
+    if (next < top) setTop(next);
+    if (next >= top + height) setTop(next - height + 1);
+  };
+
+  useInput((input, key) => {
+    if (key.upArrow || input === 'k') move(-1);
+    else if (key.downArrow || input === 'j') move(1);
+    else if (input === 'g') { setCursor(0); setTop(0); }
+    else if (input === 'G') { setCursor(items.length - 1); setTop(Math.max(0, items.length - height)); }
+    else if (key.return && onSelect) onSelect(cursor);
+  }, { isActive: Boolean(focused) && items.length > 0 });
+
+  const view = items.slice(top, top + height);
+  const leftWidth = Math.max(0, ...items.map((i) => (i.left ?? '').length));
+
+  return html`
+    <${Box} flexDirection="column">
+      ${view.map((item, i) => {
+        const idx = top + i;
+        const on = idx === cursor && focused;
+        return html`
+          <${Box} key=${item.key ?? idx}>
+            <${Text} color=${on ? 'cyan' : undefined}>${on ? '❯ ' : '  '}<//>
+            ${item.left !== undefined
+              ? html`<${Text} dimColor>${item.left.padEnd(leftWidth)}  <//>`
+              : null}
+            <${Text} bold=${on} dimColor=${!on}>${item.label}<//>
+          <//>`;
+      })}
+      ${items.length > height
+        ? html`<${Text} dimColor>  ${cursor + 1}/${items.length}<//>`
+        : null}
+    <//>`;
+}

package/src/tui/h.mjs

@@ -0,0 +1,23 @@
+/**
+ * JSX-shaped syntax without a build step (t-632).
+ *
+ * htm bound to React.createElement gives tagged-template markup that parses at
+ * runtime and caches per call site, so `.mjs` files stay directly runnable:
+ *
+ *     html`<${Box} flexDirection="column"><${Text}>hi<//><//>`
+ *
+ * ⚠️ THIS IS THE LEAST-BAD OPTION, NOT A GOOD ONE. It reads worse than JSX, and
+ * every Ink example on the internet needs translating to it. The alternative was
+ * adding esbuild, which would end this package's no-build-step property — src/ is
+ * published verbatim, `files` needs no dist entry, and `node --check` over src is
+ * the whole typecheck. That property is worth more than nicer syntax.
+ *
+ * ⚠️ AND THE CLOSING TAG IS `<//>`, not `</Box>`. Getting it wrong is a runtime
+ * parse error rather than a compile error, which is the real cost of no build.
+ */
+
+import React from 'react';
+import htm from 'htm';
+
+export const html = htm.bind(React.createElement);
+export { React };