@modelstatus/cli 0.1.1 → 0.1.25

package/src/tui/ui.js

@@ -1,28 +1,112 @@
 import React from "react";
-import { Text } from "ink";
+import { Box, Text, Spacer } from "ink";
 
 export const h = React.createElement;
 
+/* ===========================================================================
+ * LLM Status TUI design system. Single source of truth for tokens + the shared
+ * components every view composes from. See the redesign spec: a marketing-grade
+ * windowed console. Two ink facts this file is built on (verified in ink@5.2.1):
+ *   - A <Box> backgroundColor paints NOTHING. Background is honored ONLY on
+ *     <Text>. So a full-width highlighted row threads the same backgroundColor
+ *     into EVERY child <Text> (gutters included) and pads to the exact width.
+ *   - Per-edge border flags (borderTop:false / borderBottom:false) work, giving
+ *     clean left/right rails — the window-chrome technique.
+ * ======================================================================== */
+
+// ASCII / no-background fallback for dumb terminals (or MM_ASCII=1). Read once.
+const ASCII = process.env.MM_ASCII === "1" || process.env.TERM === "dumb";
+const BG_ON = !ASCII && process.env.NO_COLOR == null;
+
+// ---- Palette --------------------------------------------------------------
+export const C = {
+  BG: "#0b0f14",
+  BG_ELEV: "#11161d",
+  BG_ROW: "#161c25",
+  BG_ROW_SEL: "#13202a",
+  BORDER: "#243042",
+  BORDER_ACCENT: "#22d3ee",
+  FG: "#e6edf3",
+  FG_DIM: "#8b98a5",
+  FG_FAINT: "#5b6673",
+  FG_STRONG: "#f9fafb",
+  ACCENT: "#22d3ee",
+  ACCENT_INK: "#06181d",
+  ACCENT_DK: "#0e7490",
+  BLUE: "#60a5fa",
+};
+
+export const LIGHT = { red: "#ff5f56", yellow: "#ffbd2e", green: "#27c93f" };
+
+// ---- Glyphs (with ASCII fallback) -----------------------------------------
+const G_UNICODE = {
+  ok: "●", deprecating: "◐", retiring: "▲", retired: "×", custom: "○",
+  selOn: "●", selOff: "○", rail: "▎", spark: "✦", warn: "⚠", repl: "→",
+  crit: "⚑", check: "✓", cross: "×", dot: "·", bullet: "•", caret: "›", pause: "⏸",
+};
+const G_ASCII = {
+  ok: "o", deprecating: "%", retiring: "^", retired: "x", custom: ".",
+  selOn: "*", selOff: ".", rail: "|", spark: "*", warn: "!", repl: "->",
+  crit: "!", check: "OK", cross: "x", dot: ".", bullet: "*", caret: ">", pause: "||",
+};
+export const GLYPH = ASCII ? G_ASCII : G_UNICODE;
+
+// ---- Health spine ---------------------------------------------------------
 export const HEALTH_COLOR = {
-  ok: "green",
-  deprecating: "yellow",
-  retiring: "magenta",
-  retired: "red",
-  custom: "gray",
+  ok: "#16a34a",
+  deprecating: "#d97706",
+  retiring: "#ea580c",
+  retired: "#dc2626",
+  custom: "#9ca3af",
 };
 export const HEALTH_GLYPH = {
-  ok: "●",
-  deprecating: "●",
-  retiring: "▲",
-  retired: "■",
-  custom: "○",
+  ok: GLYPH.ok,
+  deprecating: GLYPH.deprecating,
+  retiring: GLYPH.retiring,
+  retired: GLYPH.retired,
+  custom: GLYPH.custom,
 };
-
-export const healthColor = (hh) => HEALTH_COLOR[hh] || "white";
+export const healthColor = (hh) => HEALTH_COLOR[hh] || C.FG;
 export const healthGlyph = (hh) => HEALTH_GLYPH[hh] || "·";
 
-/** Truncate + pad to a fixed width for column alignment. */
+// ---- Spinner / ticks ------------------------------------------------------
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export function useInterval(fn, ms) {
+  const ref = React.useRef(fn);
+  ref.current = fn;
+  React.useEffect(() => {
+    if (ms == null) return undefined;
+    const t = setInterval(() => ref.current(), ms);
+    return () => clearInterval(t);
+  }, [ms]);
+}
+
+export function useTick(ms = 80, running = true) {
+  const [tick, setTick] = React.useState(0);
+  useInterval(() => setTick((t) => t + 1), running ? ms : null);
+  return tick;
+}
+
+// ---- String helpers -------------------------------------------------------
+export const fmtNum = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+
+/** Truncate+pad to a fixed width (hard slice, no ellipsis). */
 export const cell = (s, w) => String(s ?? "").slice(0, w).padEnd(w);
+/** Right-ellipsis: keep the head, drop the tail (slugs, names). */
+export const cellE = (s, w) => {
+  s = String(s ?? "");
+  return (s.length > w ? s.slice(0, w - 1) + "…" : s).padEnd(w);
+};
+/** Left-ellipsis: keep the tail (file:line — the :line stays visible). */
+export const cellL = (s, w) => {
+  s = String(s ?? "");
+  return (s.length > w ? "…" + s.slice(-(w - 1)) : s).padEnd(w);
+};
+/** Right-align pad. */
+export const rpad = (s, w) => String(s ?? "").padStart(w);
+
+export const clampCursor = (i, len) => (len <= 0 ? 0 : Math.max(0, Math.min(len - 1, i)));
 
 /** Data-fetching hook: { loading, data, error, reload, setData }. */
 export function useAsync(fn, deps = []) {
@@ -43,5 +127,566 @@ export function useAsync(fn, deps = []) {
   return { ...state, reload, setData: (data) => setState((s) => ({ ...s, data })) };
 }
 
-/** Clamp a cursor index into [0, len). */
-export const clampCursor = (i, len) => (len <= 0 ? 0 : Math.max(0, Math.min(len - 1, i)));
+// ---- Relative retirement time --------------------------------------------
+/** retires_date → { text, color, bold }; text is ≤7 chars by construction. */
+export function relativeTime(retiresDate, today = new Date()) {
+  if (!retiresDate) return { text: "", color: C.FG_FAINT, bold: false };
+  const t = new Date(retiresDate).getTime();
+  if (Number.isNaN(t)) return { text: "", color: C.FG_FAINT, bold: false };
+  const d = Math.round((t - today.getTime()) / 86_400_000);
+  let text;
+  if (d < 0) {
+    const abs = Math.abs(d);
+    if (abs < 60) text = `${abs}d ago`;
+    else if (abs < 365) text = `${Math.round(abs / 30)}mo ago`;
+    else text = `${Math.round(abs / 365)}y ago`;
+  } else if (d < 14) text = `in ${d}d`;
+  else if (d < 60) text = `in ${Math.ceil(d / 7)}w`;
+  else if (d < 365) text = `in ${Math.round(d / 30)}mo`;
+  else text = `in ${Math.round(d / 365)}y`;
+  text = text.slice(0, 8); // width safety (rel column is 8)
+  // Urgency ramp.
+  let color = C.FG_FAINT;
+  let bold = false;
+  if (d < 0) color = "#dc2626";
+  else if (d <= 7) { color = "#ea580c"; bold = true; }
+  else if (d <= 14) { color = "#f59e0b"; bold = true; }
+  else if (d <= 90) color = "#d97706";
+  else color = C.FG_FAINT;
+  return { text, color, bold };
+}
+
+/** env → { text, color }. */
+export function envTag(env) {
+  const e = String(env || "");
+  const color = e === "prod" ? C.ACCENT : e === "staging" ? "#a78bfa" : C.FG_FAINT;
+  return { text: e, color };
+}
+
+// ===========================================================================
+// Window chrome
+// ===========================================================================
+
+/** Top border with a centered accent title:  ╭──  title  ──╮  (width = outer). */
+export function topRule(title, width) {
+  const inner = Math.max(0, width - 2);
+  const t = ` ${title} `;
+  const dash = Math.max(0, inner - t.length);
+  const left = Math.floor(dash / 2);
+  const right = dash - left;
+  return h(
+    Box,
+    { flexDirection: "row" },
+    h(Text, { color: C.BORDER }, "╭" + "─".repeat(left)),
+    h(Text, { color: C.ACCENT, bold: true }, t.slice(0, inner)),
+    h(Text, { color: C.BORDER }, "─".repeat(right) + "╮"),
+  );
+}
+
+export function bottomRule(width) {
+  return h(Text, { color: C.BORDER }, "╰" + "─".repeat(Math.max(0, width - 2)) + "╯");
+}
+
+/** Bordered window: titled top rule, side-railed body, bottom rule. */
+export function Window({ title, width, children }) {
+  return h(
+    Box,
+    { flexDirection: "column", width },
+    topRule(title, width),
+    h(
+      Box,
+      {
+        borderStyle: "round",
+        borderTop: false,
+        borderBottom: false,
+        borderColor: C.BORDER,
+        paddingX: 1,
+        flexDirection: "column",
+        width,
+      },
+      children,
+    ),
+    bottomRule(width),
+  );
+}
+
+/** The three macOS traffic-light dots — first interior row. */
+export function TrafficLights() {
+  return h(
+    Box,
+    { flexDirection: "row" },
+    h(Text, { color: LIGHT.red }, "●"),
+    h(Text, {}, " "),
+    h(Text, { color: LIGHT.yellow }, "●"),
+    h(Text, {}, " "),
+    h(Text, { color: LIGHT.green }, "●"),
+  );
+}
+
+// Short labels so seven tabs + chip fit 80 cols. Number is always the hotkey.
+const TAB_ABBR = { "What's New": "New", Inventory: "Inv", Account: "Acct" };
+
+/** Top tab strip with the account/plan chip pushed right. */
+export function TabStrip({ idx, tabs, account, plan, version }) {
+  const segs = tabs.map((v, i) => {
+    const label = TAB_ABBR[v.label] || v.label;
+    const txt = ` ${i + 1} ${label} `;
+    return i === idx
+      ? h(Text, { key: v.key, backgroundColor: BG_ON ? C.ACCENT : undefined, color: BG_ON ? C.ACCENT_INK : C.ACCENT, bold: true }, txt)
+      : h(Text, { key: v.key, color: C.FG_FAINT }, txt);
+  });
+  const right = [];
+  if (version) right.push(h(Text, { key: "v", color: C.BLUE, bold: true }, ` v${version}`));
+  if (account) right.push(h(Text, { key: "a", color: C.FG_DIM }, ` ${account}`));
+  if (plan && plan !== "free") right.push(h(Text, { key: "p", backgroundColor: BG_ON ? "#16a34a" : undefined, color: BG_ON ? C.ACCENT_INK : "#16a34a", bold: true }, " PRO "));
+  else if (plan === "free") right.push(h(Text, { key: "p", color: C.FG_FAINT }, " free "));
+  return h(Box, { flexDirection: "row" }, ...segs, h(Spacer, null), ...right);
+}
+
+/** Smaller in-view sub-tabs (whatsnew / alerts). */
+export function SubTabs({ idx, tabs }) {
+  return h(
+    Box,
+    { flexDirection: "row" },
+    ...tabs.map((t, i) =>
+      h(
+        Text,
+        { key: t, backgroundColor: i === idx && BG_ON ? C.ACCENT : undefined, color: i === idx ? (BG_ON ? C.ACCENT_INK : C.ACCENT) : C.FG_FAINT, bold: i === idx },
+        ` ${t} `,
+      ),
+    ),
+    h(Text, { color: C.FG_FAINT }, "   ←→ switch"),
+  );
+}
+
+// ===========================================================================
+// List rows + cursor highlight (the load-bearing component)
+// ===========================================================================
+
+/**
+ * One list row, full inner width. `cells` = [{ text, color, bold? }] already
+ * padded to their column widths. When `active`, a subtle bg wash + an accent
+ * rail mark the cursor; bg is threaded into EVERY child Text (incl. the filler)
+ * because Box bg is a no-op in ink. `selected` deepens the wash.
+ */
+export function ListRow({ active, selected, cells, width }) {
+  const bg = active && BG_ON ? (selected ? C.BG_ROW_SEL : C.BG_ROW) : undefined;
+  const rail = active ? { text: GLYPH.rail, color: C.ACCENT } : { text: " ", color: C.FG };
+  const all = [rail, ...cells];
+  const used = all.reduce((n, c) => n + c.text.length, 0);
+  if (used < width) all.push({ text: " ".repeat(width - used), color: C.FG });
+  return h(
+    Text,
+    { wrap: "truncate" },
+    ...all.map((c, i) => h(Text, { key: i, color: c.color, bold: c.bold, backgroundColor: bg }, c.text)),
+  );
+}
+
+// ===========================================================================
+// Status bar + health legend
+// ===========================================================================
+
+/** counts → [{text,color}] legend segments, all states in fixed order, zeros dimmed. */
+export function legendSegments(counts = {}) {
+  const order = ["ok", "deprecating", "retiring", "retired"];
+  const segs = [];
+  order.forEach((k, i) => {
+    const n = counts[k] || 0;
+    const color = n > 0 ? HEALTH_COLOR[k] : C.FG_FAINT;
+    if (i > 0) segs.push({ text: "  ", color: C.FG_FAINT });
+    segs.push({ text: `${HEALTH_GLYPH[k]} ${n}`, color });
+  });
+  if (counts.custom > 0) {
+    segs.push({ text: "  ", color: C.FG_FAINT });
+    segs.push({ text: `${HEALTH_GLYPH.custom} ${counts.custom}`, color: HEALTH_COLOR.custom });
+  }
+  return segs;
+}
+
+/**
+ * Pinned status strip. `segsLeft` / `segsRight` are [{text,color,bold?}]. The
+ * middle gap is filled with bg-colored spaces so the strip reads as one
+ * continuous bar (Box bg / space-between won't fill it — verified).
+ */
+export function StatusBar({ segsLeft = [], segsRight = [], width }) {
+  const bg = BG_ON ? C.BG_ELEV : undefined;
+  const len = (segs) => segs.reduce((n, s) => n + s.text.length, 0);
+  const fill = Math.max(1, width - len(segsLeft) - len(segsRight));
+  const all = [...segsLeft, { text: " ".repeat(fill), color: C.FG_FAINT }, ...segsRight];
+  return h(
+    Text,
+    { wrap: "truncate" },
+    ...all.map((s, i) => h(Text, { key: i, color: s.color, bold: s.bold, backgroundColor: bg }, s.text)),
+  );
+}
+
+// ===========================================================================
+// Keybar
+// ===========================================================================
+
+export function KeyCap({ k, label }) {
+  return h(
+    Box,
+    { flexDirection: "row" },
+    h(Text, { backgroundColor: BG_ON ? C.BG_ELEV : undefined, color: C.ACCENT, bold: true }, ` ${k} `),
+    h(Text, { color: C.FG_DIM }, ` ${label}`),
+  );
+}
+
+/** Single-line keybar; always shows `q quit`, dropping earlier keys with `…`
+ * when the row overflows (so quit is never the casualty of truncation). */
+export function KeyBar({ keys, width }) {
+  const SEP = 2;
+  const capW = (it) => it.k.length + 2 + 1 + it.label.length; // " k " + " label"
+  const budget = width - capW({ k: "q", label: "quit" }) - SEP; // reserve room for q quit
+  const out = [];
+  let used = 0;
+  let dropped = false;
+  for (const item of keys) {
+    const w = capW(item) + (out.length ? SEP : 0);
+    if (used + w > budget) { dropped = true; break; }
+    if (out.length) out.push(h(Text, { key: `s${out.length}`, color: C.FG }, "  "));
+    out.push(h(KeyCap, { key: item.k, k: item.k, label: item.label }));
+    used += w;
+  }
+  if (dropped) out.push(h(Text, { key: "more", color: C.FG_FAINT }, " … "));
+  else if (out.length) out.push(h(Text, { key: "sq", color: C.FG }, "  "));
+  out.push(h(KeyCap, { key: "q", k: "q", label: "quit" }));
+  return h(Box, { flexDirection: "row" }, ...out);
+}
+
+// ===========================================================================
+// State helpers
+// ===========================================================================
+
+/** kind ∈ loading|scanning|done|error → leading glyph + colored text, one row. */
+export function StateLine({ kind, text, spin }) {
+  if (kind === "done") return h(Text, {}, h(Text, { color: "#16a34a" }, ` ${GLYPH.check} `), h(Text, { color: C.FG_DIM }, text));
+  if (kind === "error") return h(Text, {}, h(Text, { color: "#dc2626" }, ` ${GLYPH.cross} `), h(Text, { color: "#dc2626" }, text));
+  // loading / scanning
+  return h(Text, {}, h(Text, { color: C.ACCENT }, ` ${spin ?? SPINNER[0]} `), h(Text, { color: C.FG_DIM }, text));
+}
+
+/** Centered empty/onboarding card framed by faint rules. */
+export function EmptyCard({ icon = GLYPH.spark, title, lines = [], width }) {
+  const rule = "─".repeat(Math.max(8, Math.min(width - 2, 60)));
+  return h(
+    Box,
+    { flexDirection: "column", paddingX: 1 },
+    h(Text, { color: C.FG_FAINT }, rule),
+    h(Text, {}, ""),
+    h(Text, {}, h(Text, { color: C.ACCENT, bold: true }, `${icon} `), h(Text, { color: C.FG }, title)),
+    ...lines.map((l, i) => h(Text, { key: i, color: C.FG_DIM }, `  ${l}`)),
+    h(Text, {}, ""),
+    h(Text, { color: C.FG_FAINT }, rule),
+  );
+}
+
+// ===========================================================================
+// SweepBar — indeterminate progress (shared by Local + Scan streaming)
+// ===========================================================================
+
+/** Bouncing cyan-ramp bar; we don't know the total file count, so no fake %. */
+export function SweepBar({ tick, width = 22 }) {
+  const span = width * 2 - 2;
+  const head = span > 0 ? tick % span : 0;
+  const pos = head < width ? head : span - head;
+  const cells = [];
+  for (let i = 0; i < width; i++) {
+    const d = pos - i;
+    if (d === 0) cells.push(h(Text, { key: i, color: "#67e8f9" }, "█"));
+    else if (d === 1 || d === -1) cells.push(h(Text, { key: i, color: C.ACCENT }, "▓"));
+    else if (d === 2 || d === -2) cells.push(h(Text, { key: i, color: C.ACCENT_DK }, "▒"));
+    else cells.push(h(Text, { key: i, color: C.FG_FAINT }, "░"));
+  }
+  return h(Box, {}, ...cells);
+}
+
+// ===========================================================================
+// Layout authority — single place that decides column widths for `W` inner cols
+// ===========================================================================
+
+/** Scan/list column widths derived from inner width W (reference W=78).
+ * Columns: rail(1) sel(1) ·g· health(1) ·g· slug ·g· loc ·g· env(5) ·g· rel(8).
+ * Non-var fields = rail+sel+health+env = 8; gutters = 5 (4 when loc dropped). */
+export function layout(W) {
+  const rel = 8;
+  let slug = 34;
+  let loc = 23;
+  const total = () => 8 + (loc > 0 ? 5 : 4) + slug + loc + rel;
+  if (W < 72) loc = 0;
+  while (total() > W && slug > 18) slug--;
+  while (total() > W && loc > 12) loc--;
+  return { slug, loc, env: 5, rel, dropLoc: loc === 0 };
+}
+
+// ===========================================================================
+// Interactive list kit — cursor/scroll + "/" search (shared by list views)
+// ===========================================================================
+
+/** Cursor + scroll window over a list of `length` items, `pageSize` visible.
+ * Stays in range when the list shrinks (e.g. a search filter). */
+export function useCursorList(length, pageSize) {
+  const [cursor, setCursor] = React.useState(0);
+  React.useEffect(() => {
+    if (cursor > length - 1) setCursor(Math.max(0, length - 1));
+  }, [length]); // eslint-disable-line react-hooks/exhaustive-deps
+  const c = clampCursor(cursor, length);
+  const page = Math.max(1, pageSize);
+  const start = Math.max(0, Math.min(c - Math.floor(page / 2), Math.max(0, length - page)));
+  return {
+    cursor: c,
+    start,
+    end: Math.min(length, start + page),
+    up: () => setCursor((x) => clampCursor(x - 1, length)),
+    down: () => setCursor((x) => clampCursor(x + 1, length)),
+    set: setCursor,
+    reset: () => setCursor(0),
+  };
+}
+
+/** "/" search state. Convention: "/" opens; type to filter live; Esc clears +
+ * exits; Enter keeps the filter and exits input mode. */
+export function useSearch() {
+  const [searching, setSearching] = React.useState(false);
+  const [query, setQuery] = React.useState("");
+  // ink's useInput fires the render-time closure; two keys in one tick both see
+  // the stale `searching` before React commits. A ref mutated synchronously in
+  // open/confirm/clear lets the branch guard read the up-to-date mode, so a key
+  // pressed immediately after "/" (or after Enter) routes correctly instead of
+  // leaking into destructive commands.
+  const ref = React.useRef(false);
+  const setMode = (v) => { ref.current = v; setSearching(v); };
+  return {
+    searching,
+    query,
+    active: searching || query.length > 0,
+    isSearchingNow: () => ref.current,
+    open: () => setMode(true),
+    confirm: () => setMode(false),
+    clear: () => { setQuery(""); setMode(false); },
+    type: (ch) => setQuery((q) => q + ch),
+    backspace: () => setQuery((q) => q.slice(0, -1)),
+  };
+}
+
+/** Bottom search line: ` / query▏   (N matches)` while typing, or a dim filter
+ * chip when a query is set but input is closed. Renders an empty line otherwise
+ * (so the frame height stays constant). */
+export function SearchBar({ searching, query, count }) {
+  if (!searching && !query) return h(Text, {}, "");
+  return h(
+    Text,
+    {},
+    h(Text, { color: C.ACCENT, bold: true }, " / "),
+    h(Text, { color: C.FG }, query),
+    searching ? h(Text, { color: C.ACCENT }, "▏") : null,
+    h(Text, { color: C.FG_FAINT }, `   ${count} match${count === 1 ? "" : "es"}${searching ? " · esc clear · enter keep" : " · / edit"}`),
+  );
+}
+
+// ===========================================================================
+// ModelDetailBar — full-width bottom detail panel for the cursor row (k9s-style)
+// ===========================================================================
+
+const fmtCtx = (n) => (!n ? "—" : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
+const orDash = (s) => (s == null || s === "" ? "—" : String(s));
+
+const refLoc = (r) => (r.source_path || r.location_label || "") + (r.source_line ? ":" + r.source_line : "");
+
+// Display width: most chars 1 column, CJK / fullwidth / most emoji 2, combining
+// & zero-width 0. Dependency-free approximation — enough to keep the snippet
+// panel (the only place we clip raw user-file content) from overflowing.
+function charWidth(cp) {
+  if (cp === 0) return 0;
+  if ((cp >= 0x0300 && cp <= 0x036f) || (cp >= 0x200b && cp <= 0x200f) || cp === 0xfeff) return 0;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0x303e) ||
+    (cp >= 0x3041 && cp <= 0x33ff) || (cp >= 0x3400 && cp <= 0x4dbf) ||
+    (cp >= 0x4e00 && cp <= 0x9fff) || (cp >= 0xa000 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x1f300 && cp <= 0x1faff) ||
+    (cp >= 0x20000 && cp <= 0x3fffd)
+  ) return 2;
+  return 1;
+}
+export function dispWidth(str) {
+  let w = 0;
+  for (const ch of String(str)) w += charWidth(ch.codePointAt(0));
+  return w;
+}
+/** Truncate + right-pad a string to exactly `w` display columns (code-point aware). */
+function padDisp(s, w) {
+  s = String(s ?? "");
+  let out = "", used = 0;
+  for (const ch of s) {
+    const cw = charWidth(ch.codePointAt(0));
+    if (used + cw > w) break;
+    out += ch; used += cw;
+  }
+  return out + " ".repeat(Math.max(0, w - used));
+}
+
+/** Clip + right-pad a segment array to exactly `budget` display columns,
+ * optionally skipping the first `skip` columns (left horizontal-scroll).
+ * Code-point + display-width aware so wide chars never split or overflow. */
+function clipSegs(segs, budget, skip = 0) {
+  const out = [];
+  let used = 0, skipped = 0;
+  for (const s of segs) {
+    if (used >= budget) break;
+    let text = "";
+    for (const ch of String(s.text)) {
+      const w = charWidth(ch.codePointAt(0));
+      if (skipped < skip) { skipped += w; continue; }
+      if (used + w > budget) { used = budget; break; }
+      text += ch; used += w;
+    }
+    if (text) out.push({ ...s, text });
+    if (used >= budget) break;
+  }
+  if (used < budget) out.push({ text: " ".repeat(budget - used), color: C.FG });
+  return out;
+}
+
+/** Columns to skip so the accent-highlighted span on a match row is visible
+ * (~8 cols from the left) when it sits past `budget`; 0 if already on-screen. */
+function matchScroll(segs, budget) {
+  let col = 0, hitCol = -1, hitW = 0;
+  for (const s of segs) {
+    const w = dispWidth(s.text);
+    if (s.bg === C.ACCENT && hitCol < 0) { hitCol = col; hitW = w; }
+    col += w;
+  }
+  if (hitCol < 0 || hitCol + hitW <= budget) return 0;
+  return Math.max(0, hitCol - 8);
+}
+
+/** Render a readSnippet() result (from snippet.js) to ≤ maxRows full-width Text
+ * lines: a file:line header then syntax-highlighted code with the match line
+ * gutter-marked and the offending string accent-highlighted. */
+export function snippetLines(snippet, width, maxRows) {
+  if (!snippet || !snippet.rows || !snippet.rows.length) return [];
+  const W = Math.max(20, width);
+  const all = snippet.rows;
+  const max = Math.max(1, maxRows);
+  // Window AROUND the matched row (readSnippet centers it) so the offending line
+  // stays visible when we can't render every context line — top-slicing would
+  // drop the one line the preview exists to show.
+  let start = 0;
+  if (all.length > max) {
+    const m = all.findIndex((r) => r.isMatch);
+    start = Math.max(0, Math.min((m < 0 ? 0 : m) - Math.floor((max - 1) / 2), all.length - max));
+  }
+  const rows = all.slice(start, start + max);
+  const gw = String(rows[rows.length - 1].num).length;
+  const hdr = snippet.path.split(/[\\/]/).slice(-2).join("/") + ":" + snippet.line; // split both seps (Windows)
+  const out = [h(Text, { key: "sh", color: C.FG_FAINT }, padDisp(" " + hdr, W))];
+  rows.forEach((row, i) => {
+    const gutter = (row.isMatch ? GLYPH.caret : " ") + String(row.num).padStart(gw) + " ";
+    const budget = W - gutter.length;
+    // Horizontal-scroll the match row so a model string past the panel width
+    // (long minified configs, deep indentation) is still shown, not left-clipped.
+    const skip = row.isMatch ? matchScroll(row.segs, budget) : 0;
+    const lead = skip > 0 ? 1 : 0;
+    out.push(
+      h(
+        Text,
+        { key: "sl" + i },
+        h(Text, { color: row.isMatch ? C.ACCENT : C.FG_FAINT }, gutter),
+        skip > 0 ? h(Text, { key: "ell", color: C.FG_FAINT }, "…") : null,
+        ...clipSegs(row.segs, budget - lead, skip).map((s, j) => h(Text, { key: j, color: s.color, bold: s.bold, backgroundColor: s.bg }, s.text)),
+      ),
+    );
+  });
+  return out;
+}
+
+/**
+ * Full-width bottom detail panel for the highlighted reference. Every line is a
+ * single colored Text padded to exactly `width` (the StatusBar/ListRow
+ * discipline) so the panel fills uniformly — no nested bordered box, no flex
+ * shrink-wrap. Padded to `height` rows. `model` is the registry model (or null
+ * for custom); `refs` are the local references to it.
+ */
+export function ModelDetailBar({ title, health, model, refs = [], width, height = 6, refCursor = -1, snippet = null }) {
+  const W = Math.max(20, width);
+  const focused = refCursor >= 0;
+  const rt = model && model.retires_date ? relativeTime(model.retires_date) : null;
+  const lines = [];
+  // separator rule
+  lines.push(h(Text, { key: "rule", color: C.BORDER }, "─".repeat(W)));
+  // header: health glyph + slug (strong) + health word, padded to W
+  const hg = `${healthGlyph(health)} `;
+  const hw = `  ${health}`;
+  const slugW = Math.max(8, W - hg.length - hw.length);
+  lines.push(
+    h(
+      Text,
+      { key: "head" },
+      h(Text, { color: healthColor(health) }, hg),
+      h(Text, { color: C.FG_STRONG, bold: true }, cellE(title, slugW)),
+      h(Text, { color: healthColor(health) }, cell(hw, W - hg.length - slugW)),
+    ),
+  );
+  // Distinct usage locations (preserve the candidate object for each).
+  const distinct = [...new Map(refs.map((r) => [refLoc(r), r])).values()];
+
+  if (focused) {
+    // Selectable reference list (drilled in) + a syntax-highlighted snippet of
+    // the highlighted ref below it.
+    lines.push(h(Text, { key: "hint", color: C.FG_FAINT }, cell(`  used in ${distinct.length} · ↑↓ select · ↵ open · e exclude · esc/⌫ back`, W)));
+    // Size the snippet from the rows actually left (was a fixed 7, which on a
+    // standard 80x24 — panelH 9 — overflowed and bottom-truncated the match
+    // line + collapsed the ref list to one row). Reserve a few ref rows when
+    // there's room, hand the remainder (minus its own rule) to the snippet.
+    const chrome = lines.length; // rule + head + hint
+    const avail = Math.max(1, height - chrome);
+    const minRefRows = Math.min(distinct.length || 1, avail <= 6 ? 1 : avail <= 10 ? 2 : 3);
+    const snipMax = Math.max(0, avail - minRefRows - 1); // -1 for the snippet's own rule
+    const snip = snippet && snipMax >= 2 ? snippetLines(snippet, W, snipMax - 1) : []; // snipMax incl. snippet's file:line header
+    const reserve = snip.length ? snip.length + 1 : 0; // +1 for the rule above the snippet
+    const rowsAvail = Math.max(1, avail - reserve);
+    const cur = Math.max(0, Math.min(refCursor, distinct.length - 1));
+    const start = Math.max(0, Math.min(cur - Math.floor(rowsAvail / 2), Math.max(0, distinct.length - rowsAvail)));
+    const envW = 8;
+    const pathW = Math.max(8, W - 1 - envW);
+    distinct.slice(start, start + rowsAvail).forEach((r, i) => {
+      const idx = start + i;
+      const isCur = idx === cur;
+      lines.push(
+        h(
+          Text,
+          { key: "rf" + idx },
+          h(Text, { color: C.ACCENT }, isCur ? GLYPH.rail : " "),
+          h(Text, { color: isCur ? C.FG_STRONG : C.FG_DIM, bold: isCur }, cellL(refLoc(r), pathW)),
+          h(Text, { color: C.FG_FAINT }, cell(r.environment || "", W - 1 - pathW)),
+        ),
+      );
+    });
+    if (snip.length) {
+      lines.push(h(Text, { key: "srule", color: C.BORDER }, "─".repeat(W)));
+      lines.push(...snip);
+    }
+  } else {
+    if (model) {
+      const life = `released ${orDash(model.release_date)}   deprecated ${orDash(model.deprecation_date)}   retires ${orDash(model.retires_date)}${rt && rt.text ? ` (${rt.text})` : ""}${model.replacement_slug ? `   ${GLYPH.repl} ${model.replacement_slug}` : ""}`;
+      const about = `provider ${orDash(model.provider_slug)}   family ${orDash(model.family)}   modality ${orDash(model.modality)}   context ${fmtCtx(model.context_window)}`;
+      lines.push(h(Text, { key: "life", color: C.FG_DIM }, cell(life, W)));
+      lines.push(h(Text, { key: "about", color: C.FG_DIM }, cell(about, W)));
+    } else {
+      lines.push(h(Text, { key: "cu", color: C.FG_FAINT }, cell("not in the registry — tracked as a custom model", W)));
+    }
+    const locs = distinct.slice(0, 8).map(refLoc).join("  ");
+    const more = distinct.length > 1 ? "  ·  ↵ select" : "";
+    lines.push(h(Text, { key: "used", color: C.FG_FAINT }, cell(`used in ${distinct.length} place${distinct.length === 1 ? "" : "s"}: ${locs}${distinct.length > 8 ? "  …" : ""}${more}`, W)));
+  }
+  while (lines.length < height) lines.push(h(Text, { key: "p" + lines.length, color: C.FG }, cell("", W)));
+  return h(Box, { flexDirection: "column" }, ...lines.slice(0, height));
+}
+
+/** Distinct usage locations for a model, preserving the first candidate per file:line. */
+export function distinctRefs(refs = []) {
+  return [...new Map(refs.map((r) => [refLoc(r), r])).values()];
+}