@mnemahq/cli 0.4.0 → 0.7.0

package/src/render/theme.mjs

@@ -123,9 +123,19 @@ function isWide(cp) {
  * document that ended there. Everywhere that shortens text must say it did.
  */
 export function truncate(s, n) {
-  const plain = strip(s ?? '');
+  const raw = String(s ?? '');
+  const plain = strip(raw);
   if (n <= 0) return '';
-  if (displayWidth(plain) <= n) return plain;
+  // ⭐ 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)) {
@@ -137,12 +147,19 @@ export function truncate(s, n) {
   return `${out}…`;
 }
 
-/** Pad to `n` columns. Plain text in, plain text out — colour afterwards. */
+/**
+ * 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 plain = strip(s ?? '');
-  const gap = n - displayWidth(plain);
-  if (gap <= 0) return plain;
-  return align === 'right' ? ' '.repeat(gap) + plain : plain + ' '.repeat(gap);
+  const raw = String(s ?? '');
+  const gap = n - displayWidth(raw);
+  if (gap <= 0) return raw;
+  return align === 'right' ? ' '.repeat(gap) + raw : raw + ' '.repeat(gap);
 }
 
 /**
@@ -218,10 +235,21 @@ export function link(label, url) {
   return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
 }
 
-/** Status glyphs, used consistently rather than ad hoc per command. */
+/**
+ * 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('✓'),
-  bad: () => c.red('✗'),
-  warn: () => c.yellow('!'),
-  dot: () => c.dim('·'),
+  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 };

package/src/tui/launch.mjs

@@ -0,0 +1,61 @@
+/**
+ * The lazy boundary (t-632).
+ *
+ * ⭐ THIS MODULE IS ONLY EVER REACHED THROUGH `await import()`. That is the whole
+ * design: one seam in cli.mjs, so that inside src/tui/** the imports can be
+ * ordinary static ones rather than dozens of dynamic imports scattered through
+ * components. Nothing outside src/tui/ may import anything in it statically.
+ *
+ * Measured, on this machine:
+ *
+ *     import('ink')       136–141 ms
+ *     mnema --version      59–65 ms
+ *
+ * So a static import would roughly triple the cost of every one-shot command —
+ * and `mnema` runs from capture hooks and shell prompts, not just by hand.
+ *
+ * ⚠️ A TUI THAT CRASHES WITHOUT RESTORING THE TERMINAL IS WORSE THAN NO TUI. Ink
+ * takes the alternate screen and hides the cursor; if the process dies without
+ * unmounting, the user gets back a shell with an invisible cursor and no echo. So
+ * unmount runs from an uncaughtException handler as well as from the normal exit,
+ * and the cursor is shown again explicitly rather than trusting the library to do
+ * it on the way out of an abnormal exit.
+ */
+
+import { render } from 'ink';
+import { html } from './h.mjs';
+import { App } from './app.mjs';
+
+const SHOW_CURSOR = '\x1b[?25h';
+
+export async function startTui(ctx) {
+  const instance = render(html`<${App} ctx=${ctx} />`, {
+    // Ink's own exitOnCtrlC would leave our own key handling out of the loop.
+    exitOnCtrlC: true,
+  });
+
+  const restore = () => {
+    try { instance.unmount(); } catch { /* already gone */ }
+    try { process.stdout.write(SHOW_CURSOR); } catch { /* stream closed */ }
+  };
+
+  const onFatal = (err) => {
+    restore();
+    // Print AFTER restoring, or the message lands on the alternate screen and
+    // vanishes with it — the user sees a crash with no text.
+    process.stderr.write(`\nmnema: ${err?.stack ?? err}\n`);
+    process.exit(1);
+  };
+
+  process.on('uncaughtException', onFatal);
+  process.on('unhandledRejection', onFatal);
+
+  try {
+    await instance.waitUntilExit();
+  } finally {
+    process.off('uncaughtException', onFatal);
+    process.off('unhandledRejection', onFatal);
+    try { process.stdout.write(SHOW_CURSOR); } catch { /* stream closed */ }
+  }
+  return 0;
+}

package/src/tui/screens/briefing.mjs

@@ -0,0 +1,74 @@
+/**
+ * The home screen: what deserves attention (t-632).
+ *
+ * ⚠️ THE COVERAGE CAVEATS RENDER ABOVE THE LIST, and that is not a layout
+ * preference. read-commands.mjs:198 prints them first on purpose: a short findings
+ * list has three quite different causes and only one of them is good news. On a
+ * core build six of the seven finding families cannot produce anything at all, and
+ * `coverage.notice` is the only thing that says so. Put the banner under the list,
+ * where it is off-screen on a short terminal, and the reader concludes "all clear"
+ * from a list that is short because the engine never ran.
+ */
+
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+
+export function Briefing({ ctx, onOpen, focused }) {
+  const { status, data, error, elapsed, at, reload } = useResource('briefing', () =>
+    ctx.call((m) => m.findings.briefing()));
+
+  // Refresh is explicit. See store.mjs: a list that reorders under a moving cursor
+  // means pressing enter on row three opens what is now row four.
+  useInput((input) => { if (input === 'r') reload(); }, { isActive: Boolean(focused) });
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}>
+      <${Text} dimColor>Loading the briefing… ${elapsed > 1 ? `${elapsed}s` : ''}<//>
+    <//>`;
+  }
+
+  if (error && !data) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>r to retry · q to quit<//>
+    <//>`;
+  }
+
+  const b = data ?? {};
+  const p = b.pulse ?? {};
+  const findings = b.findings ?? [];
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box} gap=${3}>
+        <${Text}><${Text} dimColor>projects </>${p.activeProjects ?? 0}<//>
+        <${Text}><${Text} dimColor>problems </><${Text} color=${(p.problemsInActiveProjects ?? 0) > 0 ? 'yellow' : undefined}>${p.problemsInActiveProjects ?? 0}<//><//>
+        <${Text}><${Text} dimColor>spend 7d </>$${p.cost7dUsd ?? 0}<//>
+        <${Text} dimColor>${ago(at)}${status === 'refreshing' ? ' · refreshing' : ''}<//>
+      <//>
+
+      ${b.neverComputed ? html`<${Box} marginTop=${1}><${Text} color="yellow">! The findings engine has never run for this workspace.<//><//>` : null}
+      ${b.coverage?.degraded ? html`<${Box} marginTop=${1}><${Text} color="yellow">! ${b.coverage.notice}<//><//>` : null}
+
+      <${Box} marginTop=${1}>
+        <${Text} bold>Findings<//>
+        <${Text} dimColor>  ${findings.length}<//>
+      <//>
+
+      ${findings.length === 0
+        ? html`<${Text} dimColor>  Nothing surfaced.<//>`
+        : html`<${List}
+            items=${findings.map((f) => ({
+              key: f.id ?? f.headline,
+              left: String(f.kind ?? ''),
+              label: `${f.headline ?? ''}${f.grouped ? ` ×${f.count}` : ''}`,
+            }))}
+            focused=${focused}
+            onSelect=${(i) => onOpen(findings[i])}
+          />`}
+
+      ${error ? html`<${Box} marginTop=${1}><${Text} color="yellow">refresh failed — ${error.message ?? String(error)}<//><//>` : null}
+    <//>`;
+}

package/src/tui/screens/finding.mjs

@@ -0,0 +1,53 @@
+/**
+ * One finding, in full (t-632).
+ *
+ * ⚠️ THE HEADLINE IS A SUMMARY, AND A SUMMARY OF A FINDING IS EXACTLY WHERE A
+ * NUMBER LOSES ITS CAVEATS. "0 of 1238 decisions turned into work" reads as an
+ * indictment until you know the window is 90 days and the engine only sees
+ * decisions that were recorded. So the detail view shows what the engine actually
+ * had — subject, evidence, window — rather than restating the headline larger.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+
+const Row = ({ label, children }) => html`
+  <${Box}>
+    <${Text} dimColor>${String(label).padEnd(10)}  <//>
+    <${Text}>${children}<//>
+  <//>`;
+
+export function Finding({ finding }) {
+  if (!finding) {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Nothing selected.<//><//>`;
+  }
+
+  const evidence = finding.evidence ?? finding.subjects ?? [];
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${finding.headline ?? '(no headline)'}<//>
+      <${Box} flexDirection="column" marginTop=${1}>
+        ${html`<${Row} label="kind">${finding.kind ?? '—'}<//>`}
+        ${finding.grouped ? html`<${Row} label="grouped">${finding.count} occurrences<//>` : null}
+        ${finding.severity ? html`<${Row} label="severity">${finding.severity}<//>` : null}
+        ${finding.window ? html`<${Row} label="window">${finding.window}<//>` : null}
+      <//>
+
+      ${finding.detail
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${finding.detail}<//><//>`
+        : null}
+
+      ${Array.isArray(evidence) && evidence.length
+        ? html`
+          <${Box} flexDirection="column" marginTop=${1}>
+            <${Text} bold>Evidence<//>
+            ${evidence.slice(0, 8).map((e, i) => html`
+              <${Text} key=${i} dimColor>  ${typeof e === 'string' ? e : (e.label ?? e.title ?? JSON.stringify(e))}<//>`)}
+            ${evidence.length > 8
+              ? html`<${Text} dimColor>  … ${evidence.length - 8} more — mnema briefing --json<//>`
+              : null}
+          <//>`
+        : html`<${Box} marginTop=${1}><${Text} dimColor>No evidence rows came back with this finding.<//><//>`}
+    <//>`;
+}

package/src/tui/store.mjs

@@ -0,0 +1,65 @@
+/**
+ * Fetching, for the TUI (t-632).
+ *
+ * Hand-rolled rather than a data library: the requirements are small, and a
+ * dependency here would land on the lazy side of the boundary but still be
+ * installed for every user of the package.
+ *
+ * ⚠️ THE ELAPSED CLOCK ONLY TICKS WHILE LOADING. An interval that runs whenever
+ * the component is mounted re-renders the whole tree ten times a second forever,
+ * which on a terminal means a visible flicker and a pegged CPU on an idle screen.
+ *
+ * ⚠️ AND IT DOES NOT POLL. A list that reorders itself under a moving cursor is
+ * hostile — you press enter on what was row three and open what is now row four.
+ * Load on mount, show how stale it is, refresh on `r`.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export function useResource(key, fetcher) {
+  const [state, setState] = useState({ status: 'loading', data: null, error: null, at: null });
+  const [elapsed, setElapsed] = useState(0);
+  const [nonce, setNonce] = useState(0);
+  const alive = useRef(true);
+
+  useEffect(() => () => { alive.current = false; }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    setState((s) => ({ ...s, status: s.data ? 'refreshing' : 'loading', error: null }));
+    setElapsed(0);
+    Promise.resolve()
+      .then(fetcher)
+      .then((data) => {
+        if (cancelled || !alive.current) return;
+        setState({ status: 'ready', data, error: null, at: Date.now() });
+      })
+      .catch((error) => {
+        if (cancelled || !alive.current) return;
+        // ⚠️ KEEP THE OLD DATA. A failed refresh should not blank a screen the
+        // user is reading; it should say the refresh failed.
+        setState((s) => ({ status: 'error', data: s.data, error, at: s.at }));
+      });
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, nonce]);
+
+  useEffect(() => {
+    if (state.status !== 'loading' && state.status !== 'refreshing') return undefined;
+    const t = setInterval(() => setElapsed((n) => n + 1), 1000);
+    return () => clearInterval(t);
+  }, [state.status]);
+
+  const reload = useCallback(() => setNonce((n) => n + 1), []);
+  return { ...state, elapsed, reload };
+}
+
+/** "3m ago" — so a screen that is not polling still says how old it is. */
+export function ago(at) {
+  if (!at) return '';
+  const s = Math.floor((Date.now() - at) / 1000);
+  if (s < 5) return 'just now';
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  return `${Math.floor(s / 3600)}h ago`;
+}