heyspex 0.1.0 → 0.2.0

package/spexharness/src/chat/tui/ansi.mjs

@@ -0,0 +1,448 @@
+// spexharness/src/chat/tui/ansi.mjs
+//
+// Pure ANSI/VT drawing primitives for the `hs chat` TUI presenter (HS-TJYK T1). No I/O —
+// every helper here takes plain values and returns a string; the caller (status-bar.mjs,
+// welcome.mjs, presenter.mjs, ...) decides when and where to write it. This posture matches
+// every other spexharness/src/chat/*.mjs module (see chat-sigint.mjs's header).
+//
+// Sequences implemented (epic [[HS-TJYK-8CMW-EPIC-interactive-shell-parity-heyspex]] §T1):
+//   sgr(...codes)            CSI codes 'm'                    e.g. sgr(1) -> ESC[1m
+//   fg(hex, depth)           24-bit / 256-color / no-op foreground color
+//   bold / dim / reset       SGR 1 / 2 / 0
+//   cursorTo(row, col)       CSI row;col H
+//   cursorUp(n)              CSI n A — relative cursor move, up n rows (no scroll)
+//   cursorDown(n)            CSI n B — relative cursor move, down n rows (no scroll)
+//   cursorToCol(col)         CSI col G — absolute column, current row unchanged
+//   saveCursor/restoreCursor DECSC/DECRC — ESC 7 / ESC 8 (NOT CSI sequences)
+//   setScrollRegion(t, b)    DECSTBM — CSI t;b r
+//   resetScrollRegion        CSI r
+//   clearLine                CSI 2K
+//   clearScreenDown          CSI J  (erase from cursor to end of screen)
+//   enableBracketedPaste     CSI ?2004 h
+//   disableBracketedPaste    CSI ?2004 l
+//   hideCursor/showCursor    CSI ?25l / CSI ?25h
+//   pickColorDepth(stdout, env)  24 | 8 | 0
+//   visibleWidth(text)       terminal columns `text` occupies — Unicode/grapheme-aware, CSI ignored
+//   truncateVisible(text, cols)  cut to `cols` columns without splitting a grapheme or an escape
+//
+// `fg`'s 256-color path uses the standard xterm 6x6x6 color-cube + grayscale-ramp mapping
+// (the same nearest-approximation formula used by chalk/ansi-styles): each RGB channel is
+// quantized to a 0-5 cube step, or — when r === g === b — mapped onto the 24-step grayscale
+// ramp (indices 232-255) instead, since that ramp resolves neutrals far better than the
+// color cube's corners. This is a reasonable-default choice the task spec left open; no other
+// convention exists elsewhere in this repo to match.
+
+/** ESC (0x1b). Exported so callers building their own raw sequences share one constant. */
+export const ESC = '';
+
+/** CSI <codes joined by ';'> m — e.g. sgr(1, 32) -> ESC[1;32m. sgr() with no args -> ESC[m. */
+export function sgr(...codes) {
+  return `${ESC}[${codes.join(';')}m`;
+}
+
+/** SGR bold (1), dim (2), and the reset-all sequence (0). Constants, not functions — the
+ *  other named sequences below (cursorTo, setScrollRegion, ...) are functions only because
+ *  they take arguments; these three don't, so they stay plain strings for callers to inline. */
+export const bold = sgr(1);
+export const dim = sgr(2);
+export const reset = sgr(0);
+
+function hexToRgb(hex) {
+  const clean = hex.startsWith('#') ? hex.slice(1) : hex;
+  const r = parseInt(clean.slice(0, 2), 16);
+  const g = parseInt(clean.slice(2, 4), 16);
+  const b = parseInt(clean.slice(4, 6), 16);
+  return { r, g, b };
+}
+
+/** Nearest xterm-256 palette index for an RGB triple — 6x6x6 color cube (16-231) with a
+ *  24-step grayscale ramp (232-255) used for near-neutral colors. Standard chalk/ansi-styles
+ *  formula. */
+function rgbToAnsi256(r, g, b) {
+  if (r === g && g === b) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return Math.round(((r - 8) / 247) * 24) + 232;
+  }
+  return (
+    16 +
+    36 * Math.round((r / 255) * 5) +
+    6 * Math.round((g / 255) * 5) +
+    Math.round((b / 255) * 5)
+  );
+}
+
+/**
+ * Foreground color escape for a hex color at a given color depth.
+ * depth 24 -> CSI 38;2;R;G;B m (truecolor)
+ * depth 8  -> CSI 38;5;<nearest xterm-256 index> m
+ * depth 0  -> '' (no color support — caller should render plain text)
+ */
+export function fg(hex, depth) {
+  if (depth === 24) {
+    const { r, g, b } = hexToRgb(hex);
+    return `${ESC}[38;2;${r};${g};${b}m`;
+  }
+  if (depth === 8) {
+    const { r, g, b } = hexToRgb(hex);
+    return `${ESC}[38;5;${rgbToAnsi256(r, g, b)}m`;
+  }
+  return '';
+}
+
+/**
+ * Background color escape for a hex color at a given color depth — same three-way split as
+ * `fg` (depth 24 truecolor / depth 8 nearest-256 / depth 0 no-op), CSI 48 instead of 38.
+ * input-box.mjs's submitted-input transcript line uses this for its "highlighted" `❯ text`
+ * segment (HS-05L9 T10, dock-anchored layout).
+ */
+export function bg(hex, depth) {
+  if (depth === 24) {
+    const { r, g, b } = hexToRgb(hex);
+    return `${ESC}[48;2;${r};${g};${b}m`;
+  }
+  if (depth === 8) {
+    const { r, g, b } = hexToRgb(hex);
+    return `${ESC}[48;5;${rgbToAnsi256(r, g, b)}m`;
+  }
+  return '';
+}
+
+/** CSI row;col H — absolute cursor position (1-indexed, as the terminal expects). */
+export function cursorTo(row, col) {
+  return `${ESC}[${row};${col}H`;
+}
+
+/** CSI n A — move the cursor UP n rows (default 1), relative to its current position.
+ *  Never scrolls (unlike a bare '\n' at the bottom row) — status-bar.mjs's DECSTBM-homing
+ *  fix pairs this with a leading '\n' precisely to get that "scroll only if already at the
+ *  last row" behavior; cursorUp alone never scrolls either way. */
+export function cursorUp(n = 1) {
+  return `${ESC}[${n}A`;
+}
+
+/** CSI n B — move the cursor DOWN n rows (default 1), relative to its current position. The
+ *  mirror image of `cursorUp` — HS-U4AJ (T11)'s slash-menu wiring in input-box.mjs uses this
+ *  to reverse `positionOnActiveRow()`'s upward move (go from the active editing row back down
+ *  to the dock's own resting position) before a menu-driven mid-edit dock rewrite. Never
+ *  scrolls, same as `cursorUp`. */
+export function cursorDown(n = 1) {
+  return `${ESC}[${n}B`;
+}
+
+/** CSI col G — move the cursor to an absolute COLUMN on the current row (row unchanged). */
+export function cursorToCol(col) {
+  return `${ESC}[${col}G`;
+}
+
+/** DECSC — save cursor position (ESC 7, not a CSI sequence). */
+export const saveCursor = `${ESC}7`;
+
+/** DECRC — restore cursor position (ESC 8, not a CSI sequence). */
+export const restoreCursor = `${ESC}8`;
+
+/** DECSTBM — set the scrolling region to rows top..bottom (CSI top;bottom r). */
+export function setScrollRegion(top, bottom) {
+  return `${ESC}[${top};${bottom}r`;
+}
+
+/** DECSTBM with no operands — reset the scrolling region to the full screen. */
+export const resetScrollRegion = `${ESC}[r`;
+
+/** CSI 2K — clear the entire current line (cursor position unchanged). */
+export const clearLine = `${ESC}[2K`;
+
+/** CSI J — erase from the cursor to the end of the screen (cursor position unchanged). */
+export const clearScreenDown = `${ESC}[J`;
+
+/** CSI 2J (erase the entire visible screen) + CSI 3J (erase the terminal's own scrollback —
+ *  an xterm extension, harmless where unsupported) + CSI H (home the cursor to row 1, col 1).
+ *  The `/clear` built-in's sequence (HS-MW9H, T12) — clears what mouse-wheel/Page Up would
+ *  still scroll back to, not just the current viewport, then homes the cursor so whatever
+ *  redraws next (the dock) starts at the top-left. `builtins.mjs` writes this through
+ *  `presenter.notice()`, never straight to `stdout`, so the TTY presenter's dock still gets
+ *  its own redraw immediately after (dock.mjs's `writeAbove` contract). */
+export const clearScreen = `${ESC}[2J${ESC}[3J${ESC}[H`;
+
+/** Newlines enough to walk the cursor from row 1 to the LAST row of a `rows`-tall viewport.
+ *
+ *  WHY (2026-09-14, owner report: "the text box should be anchored to the bottom of the screen
+ *  like Claude Code"): the dock (dock.mjs) is a FLOW renderer by design — it has no scroll
+ *  region and no absolute positioning, so it renders wherever the cursor happens to be, i.e.
+ *  immediately under the transcript. On a fresh session that transcript is only the welcome
+ *  header, so on a tall terminal the input box + status bar floated in the middle of the
+ *  screen with dead space below them and a caret parked in the void.
+ *
+ *  The fix needs no layout engine: fill the viewport ONCE at session open so the cursor is
+ *  already sitting on the last row before the header is written. Every write from then on
+ *  scrolls the screen instead of advancing down it, which pins the dock's last line to the
+ *  bottom row for the whole session — the header and transcript grow UPWARD out of the bottom,
+ *  exactly the shape Claude Code has. Blank rows fall off the top as real content arrives.
+ *
+ *  Deliberately newlines rather than `cursorTo(rows, 1)`: a newline on the last row scrolls on
+ *  every terminal there is, whereas absolute positioning is the class of sequence this whole
+ *  renderer was rewritten to avoid depending on (see dock.mjs's header).
+ *
+ *  @param {number} rows - the terminal's height (`stdout.rows`). Non-finite/<= 1 yields ''.
+ */
+export function fillViewport(rows) {
+  const n = Number(rows);
+  if (!Number.isFinite(n) || n <= 1) return '';
+  return '\n'.repeat(Math.floor(n) - 1);
+}
+
+/** CSI ?2004 h / l — enable/disable bracketed-paste reporting (DECSET/DECRST 2004). Opportunistic
+ *  per the T9 research recommendation: emit it, parse the markers if they arrive, never depend
+ *  on it (conhost support is unsettled; Windows Terminal honours it when announced). */
+export const enableBracketedPaste = `${ESC}[?2004h`;
+export const disableBracketedPaste = `${ESC}[?2004l`;
+
+/** CSI ?25l — hide the text cursor. */
+export const hideCursor = `${ESC}[?25l`;
+
+/** CSI ?25h — show the text cursor. */
+export const showCursor = `${ESC}[?25h`;
+
+/**
+ * Pick the color depth to render at: 24 (truecolor), 8 (256-color), or 0 (no color).
+ *
+ * @param {{ isTTY?: boolean, hasColors?: (n: number) => boolean }} stdout
+ * @param {Record<string, string | undefined>} env
+ * @returns {24 | 8 | 0}
+ */
+// --- Visible width (Unicode-aware column counting) -----------------------------------------
+//
+// The shell-parity epic (HS-TJYK) left "Unicode width on Windows Terminal/conhost" as an
+// unsettled test target: `truncateVisible` used to count one column per UTF-16 code unit, so
+// any line carrying CJK, emoji, combining marks or the U+E000 HeySpex glyph was cut at the
+// wrong column — and because dock.mjs's erase-by-height math trusts the truncated line to fit
+// in `stdout.columns`, a line that then wrapped left a stale row behind on every redraw.
+//
+// What counts as what (`visibleWidth`):
+//   CSI escape sequences (`ESC [ params intermediates final`, SGR included)   0 — stepped over
+//   East Asian Wide / Fullwidth code points (CJK, Hangul syllables, kana,
+//     fullwidth forms, wide symbols/emoji — compact range table below, plus
+//     the engine's own `\p{Emoji_Presentation}` so new emoji stay wide)        2
+//   Combining marks (Mn/Me/Mc), format chars (Cf: ZWJ, ZWNJ, ZWSP, BOM,
+//     word joiner...), variation selectors, Hangul Jungseong/Jongseong jamo     0
+//   Private-use code points (U+E000–U+F8FF, planes 15/16)                       1 — the
+//     HeySpex icon font renders them single-cell; they are EAW "Ambiguous", so
+//     they never appear in the wide table
+//   Everything else (ASCII, Latin, controls, ...)                               1
+//
+// Widths are summed per GRAPHEME, not per code point: `Intl.Segmenter` (granularity
+// 'grapheme', Node 24) groups an emoji ZWJ sequence (👨‍👩‍👧), a base + combining accent (é as
+// e + U+0301), a flag (regional-indicator pair) or a keycap into one cluster, whose width is
+// the widest of its parts — so a family emoji is ONE 2-column grapheme, `e + U+0301` is 1, and
+// a text-default symbol forced to emoji presentation by VS16 (❤ + U+FE0F) is 2, matching
+// what Windows Terminal actually draws. A grapheme that is pure ASCII (e.g. "\r\n", which the
+// segmenter also clusters) keeps one column per code unit, so plain-ASCII behavior is exactly
+// what it was before this landed.
+
+/** One complete CSI sequence at the start of the string: ESC `[`, parameter bytes (0x30–0x3F),
+ *  intermediate bytes (0x20–0x2F), one final byte (0x40–0x7E). SGR (`ESC[...m`) is the only
+ *  shape status-bar.mjs / dock.mjs actually wrap text in, but any CSI is stepped over whole
+ *  so a truncation point can never land mid-escape. Other ESC-prefixed shapes (DECSC `ESC 7`,
+ *  OSC) are never part of line content and fall through as ordinary characters. */
+const CSI_RE = /^\x1b\[[0-?]*[ -/]*[@-~]/;
+const CSI_RE_G = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+/** Sorted, non-overlapping [first, last] ranges of East Asian Width W (Wide) and F (Fullwidth)
+ *  code points (EastAsianWidth.txt, Unicode 15.1), merged where adjacent. Looked up by binary
+ *  search. Ambiguous ("A") widths — box drawing, Greek/Cyrillic, the private-use area — are
+ *  deliberately NOT here: Windows Terminal and conhost render them single-cell. */
+const WIDE_RANGES = [
+  [0x1100, 0x115f], // Hangul Jamo (choseong)
+  [0x231a, 0x231b], [0x2329, 0x232a], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693],
+  [0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be], [0x26c4, 0x26c5], [0x26ce, 0x26ce],
+  [0x26d4, 0x26d4], [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa],
+  [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c],
+  [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797], [0x27b0, 0x27b0],
+  [0x27bf, 0x27bf], [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+  [0x2e80, 0x2e99], [0x2e9b, 0x2ef3], [0x2f00, 0x2fd5], [0x2ff0, 0x2fff], // CJK radicals, IDC
+  [0x3000, 0x303e], [0x3041, 0x3096], [0x3099, 0x30ff], // CJK punctuation, hiragana, katakana
+  [0x3105, 0x312f], [0x3131, 0x318e], [0x3190, 0x31e5], [0x31ef, 0x321e], [0x3220, 0x3247],
+  [0x3250, 0x4dbf], [0x4e00, 0xa48c], [0xa490, 0xa4c6], [0xa960, 0xa97c], // CJK unified, Yi
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], [0xfe10, 0xfe19], [0xfe30, 0xfe52], [0xfe54, 0xfe66], [0xfe68, 0xfe6b],
+  [0xff01, 0xff60], [0xffe0, 0xffe6], // fullwidth forms
+  [0x16fe0, 0x16fe4], [0x16ff0, 0x16ff1], [0x17000, 0x187f7], [0x18800, 0x18cd5],
+  [0x18cff, 0x18d08], [0x1aff0, 0x1aff3], [0x1aff5, 0x1affb], [0x1affd, 0x1affe],
+  [0x1b000, 0x1b122], [0x1b132, 0x1b132], [0x1b150, 0x1b152], [0x1b155, 0x1b155],
+  [0x1b164, 0x1b167], [0x1b170, 0x1b2fb], // Tangut, Khitan, Nushu, kana supplements
+  [0x1f004, 0x1f004], [0x1f0cf, 0x1f0cf], [0x1f18e, 0x1f18e], [0x1f191, 0x1f19a],
+  [0x1f200, 0x1f202], [0x1f210, 0x1f23b], [0x1f240, 0x1f248], [0x1f250, 0x1f251],
+  [0x1f260, 0x1f265], [0x1f300, 0x1f320], [0x1f32d, 0x1f335], [0x1f337, 0x1f37c],
+  [0x1f37e, 0x1f393], [0x1f3a0, 0x1f3ca], [0x1f3cf, 0x1f3d3], [0x1f3e0, 0x1f3f0],
+  [0x1f3f4, 0x1f3f4], [0x1f3f8, 0x1f43e], [0x1f440, 0x1f440], [0x1f442, 0x1f4fc],
+  [0x1f4ff, 0x1f53d], [0x1f54b, 0x1f54e], [0x1f550, 0x1f567], [0x1f57a, 0x1f57a],
+  [0x1f595, 0x1f596], [0x1f5a4, 0x1f5a4], [0x1f5fb, 0x1f64f], [0x1f680, 0x1f6c5],
+  [0x1f6cc, 0x1f6cc], [0x1f6d0, 0x1f6d2], [0x1f6d5, 0x1f6d7], [0x1f6dc, 0x1f6df],
+  [0x1f6eb, 0x1f6ec], [0x1f6f4, 0x1f6fc], [0x1f7e0, 0x1f7eb], [0x1f7f0, 0x1f7f0],
+  [0x1f90c, 0x1f93a], [0x1f93c, 0x1f945], [0x1f947, 0x1f9ff], [0x1fa70, 0x1fa7c],
+  [0x1fa80, 0x1fa89], [0x1fa90, 0x1fabe], [0x1fabf, 0x1fac6], [0x1face, 0x1fadc],
+  [0x1fae0, 0x1fae9], [0x1faf0, 0x1faf8], // emoji blocks
+  [0x20000, 0x2fffd], [0x30000, 0x3fffd], // CJK extensions B+
+];
+
+/** Emoji the Unicode data says default to emoji (2-cell) presentation. The engine's own
+ *  property tables (ICU) — a forward-compat net for emoji minted after WIDE_RANGES was written. */
+const EMOJI_PRESENTATION_RE = /^\p{Emoji_Presentation}$/u;
+
+/** Code points that occupy no column of their own: nonspacing/enclosing/spacing combining marks
+ *  (Mn/Me/Mc — includes every variation selector U+FE00–FE0F and U+E0100–E01EF), format
+ *  characters (Cf — ZWJ U+200D, ZWNJ, ZWSP, BOM, tag characters used by subdivision flags...). */
+const ZERO_WIDTH_RE = /^[\p{Mn}\p{Me}\p{Mc}\p{Cf}]$/u;
+
+/** Extended_Pictographic base + VS16 (U+FE0F) = forced emoji presentation, 2 cells. */
+const PICTOGRAPHIC_RE = /^\p{Extended_Pictographic}$/u;
+const REGIONAL_INDICATOR_RE = /^\p{Regional_Indicator}$/u;
+
+let graphemeSegmenter = null;
+function segmenter() {
+  if (graphemeSegmenter === null) {
+    graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+  }
+  return graphemeSegmenter;
+}
+
+function isWideCodePoint(cp) {
+  if (cp < 0x1100) return false;
+  let lo = 0;
+  let hi = WIDE_RANGES.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const [first, last] = WIDE_RANGES[mid];
+    if (cp < first) hi = mid - 1;
+    else if (cp > last) lo = mid + 1;
+    else return true;
+  }
+  return EMOJI_PRESENTATION_RE.test(String.fromCodePoint(cp));
+}
+
+function isZeroWidthCodePoint(cp) {
+  if (cp < 0x300) return false; // ASCII + Latin-1: always one column (matches the old rule)
+  if (cp >= 0x1160 && cp <= 0x11ff) return true; // Hangul Jungseong/Jongseong (conjoining jamo)
+  if (cp >= 0xd7b0 && cp <= 0xd7ff) return true; // Hangul Jamo Extended-B (same)
+  return ZERO_WIDTH_RE.test(String.fromCodePoint(cp));
+}
+
+/** Column width of ONE grapheme cluster (no escape sequences inside). */
+function graphemeWidth(g) {
+  // Pure-ASCII cluster (a single char, or "\r\n"): one column per code unit — the pre-Unicode
+  // rule, preserved byte-for-byte.
+  let ascii = true;
+  for (let i = 0; i < g.length; i += 1) {
+    if (g.charCodeAt(i) > 0x7f) { ascii = false; break; }
+  }
+  if (ascii) return g.length;
+
+  let width = 0;
+  let sawVS16 = false;
+  let sawPictographic = false;
+  for (const ch of g) {
+    const cp = ch.codePointAt(0);
+    if (cp === 0xfe0f) { sawVS16 = true; continue; }
+    if (cp === 0x20e3) return 2; // COMBINING ENCLOSING KEYCAP: 1️⃣ renders 2 cells
+    if (isZeroWidthCodePoint(cp)) continue;
+    if (REGIONAL_INDICATOR_RE.test(ch)) return 2; // flag pair (or a lone RI) — one wide cell
+    if (isWideCodePoint(cp)) { width = 2; continue; }
+    if (!sawPictographic && PICTOGRAPHIC_RE.test(ch)) sawPictographic = true;
+    if (width < 1) width = 1;
+  }
+  if (sawVS16 && sawPictographic) return 2;
+  return width;
+}
+
+/** Split `text` into alternating plain / escape tokens: `{ esc: true, s }` for each CSI
+ *  sequence, `{ esc: false, s }` for the plain runs between them (each run then segmented
+ *  into graphemes by the caller). */
+function* tokens(text) {
+  CSI_RE_G.lastIndex = 0;
+  let last = 0;
+  let m;
+  while ((m = CSI_RE_G.exec(text)) !== null) {
+    if (m.index > last) yield { esc: false, s: text.slice(last, m.index) };
+    yield { esc: true, s: m[0] };
+    last = m.index + m[0].length;
+  }
+  if (last < text.length) yield { esc: false, s: text.slice(last) };
+}
+
+function* graphemes(run) {
+  // Fast path: an all-ASCII run is one grapheme per code unit (the pre-Unicode rule) — skip
+  // the segmenter, which would otherwise fuse "\r\n" and change plain-ASCII results.
+  let ascii = true;
+  for (let i = 0; i < run.length; i += 1) {
+    if (run.charCodeAt(i) > 0x7f) { ascii = false; break; }
+  }
+  if (ascii) {
+    for (let i = 0; i < run.length; i += 1) yield run[i];
+    return;
+  }
+  for (const { segment } of segmenter().segment(run)) yield segment;
+}
+
+/**
+ * Number of terminal columns `text` occupies when printed — CSI escape sequences ignored,
+ * East Asian Wide/Fullwidth graphemes (and emoji, including ZWJ sequences) 2, combining marks /
+ * format characters / variation selectors 0, private-use glyphs (U+E000–F8FF) 1, everything
+ * else 1. See the section header above for the full table.
+ */
+export function visibleWidth(text) {
+  const s = String(text ?? '');
+  let width = 0;
+  for (const tok of tokens(s)) {
+    if (tok.esc) continue;
+    for (const g of graphemes(tok.s)) width += graphemeWidth(g);
+  }
+  return width;
+}
+
+/**
+ * Truncate `text` to `cols` VISIBLE columns — ANSI CSI/SGR sequences are copied through in full
+ * and never counted, and never split, so a truncation point can never land mid-escape; and the
+ * cut is grapheme-aware and width-aware (`visibleWidth`'s rules), so it never lands inside an
+ * emoji ZWJ sequence or between a base and its combining mark, and a 2-column character that
+ * does not fit in the remaining space is dropped whole rather than half-drawn.
+ * Moved here from status-bar.mjs (HS-05L9 T10) so dock.mjs can share the same primitive —
+ * every line dock.mjs renders goes through this, not just the status bar's.
+ *
+ * Escape sequences immediately following the last kept grapheme are still copied (so a
+ * trailing `reset` survives when the cut lands exactly at the end of a colored run); the walk
+ * stops at the first grapheme that does not fit.
+ */
+export function truncateVisible(text, cols) {
+  if (!(cols > 0)) return '';
+  let visible = 0;
+  let out = '';
+  for (const tok of tokens(text)) {
+    if (tok.esc) {
+      out += tok.s;
+      continue;
+    }
+    for (const g of graphemes(tok.s)) {
+      const w = graphemeWidth(g);
+      if (visible >= cols || visible + w > cols) return out;
+      out += g;
+      visible += w;
+    }
+  }
+  return out;
+}
+
+export function pickColorDepth(stdout, env) {
+  if (env.NO_COLOR !== undefined) return 0;
+  if (!stdout || !stdout.isTTY) return 0;
+
+  const hasColors = typeof stdout.hasColors === 'function' ? stdout.hasColors.bind(stdout) : null;
+
+  if ((hasColors && hasColors(16777216)) || env.WT_SESSION !== undefined || env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit') {
+    return 24;
+  }
+  if (hasColors && hasColors(256)) {
+    return 8;
+  }
+  return 0;
+}

package/spexharness/src/chat/tui/palette.mjs

@@ -0,0 +1,22 @@
+// spexharness/src/chat/tui/palette.mjs
+//
+// GENERATED by scripts/gen-tui-palette.mjs — do not edit by hand.
+// Source: spex-console/public/design-system/tokens.dtcg.json (dark theme).
+// Regenerate: node scripts/gen-tui-palette.mjs
+// Verify without writing: node scripts/gen-tui-palette.mjs --check
+
+export const PALETTE = Object.freeze({
+  brand: '#00fa8e',
+  working: '#ff8a3d',
+  pending: '#f7c948',
+  blocked: '#ff5a44',
+  review: '#8b76e0',
+  approved: '#3b82f6',
+  secondary: '#b2b2b2',
+  stale: '#707070',
+  primary: '#ffffff',
+  highlight: '#3a3d42',
+  highlightSubtle: '#333333',
+});
+
+export const PALETTE_SOURCE = 'spex-console/public/design-system/tokens.dtcg.json';

package/spexharness/src/chat/tui/select.mjs

@@ -0,0 +1,208 @@
+// spexharness/src/chat/tui/select.mjs
+//
+// Arrow-key select prompt (HS-TJYK-8CMW-EPIC §Phase 2, task HS-3I1X, T15) — the numbered-list
+// "walk with the arrows or a number and confirm with Enter" prompt every peer agent (Claude
+// Code, Command Code, Cursor Agent) already uses for a folder-trust/tool-permission ask,
+// replacing SpexCode's own typed y/n answer for those two asks. Parity source priority (owner
+// ruling 2026-09-11): 1. Claude Code, 2. Command Code, 3. Cursor Agent — hence the `❯ n. label`
+// list shape (Claude Code's own), not Cursor's bracketed `[a]` hotkey row.
+//
+// PURE PROMPT, NO DOCK — unlike input-box.mjs/status-bar.mjs, this module does not render
+// through the shared dock (dock.mjs): it owns a small self-contained block (title + lines +
+// numbered options + footer) and erases/rewrites THAT block itself, with its own
+// cursorUp+clearScreenDown accounting (the same "erase the last K lines, rewrite them"
+// technique dock.mjs uses, duplicated here rather than shared because select() needs its own
+// synchronous Promise-driven keypress loop, not a `set()`/`erase()` pair a caller drives).
+// Callers that ALSO use the shared dock (hs-chat.ts's folder-trust and tool-permission asks)
+// are responsible for erasing the dock's own block before calling `select()` and redrawing it
+// after — the same "erase what you own before something else draws in the same rows" contract
+// input-box.mjs already follows for the menu/status-bar coordination; select() only ever
+// touches the rows IT wrote.
+//
+// Raw-mode discipline mirrors keys.mjs's `bindKeys` exactly (same rule, deliberately
+// duplicated rather than imported — `bindKeys` is wired to a `readline.Interface`'s own
+// Shift+Tab/Escape hooks and has no notion of Up/Down/digit/key navigation or resolving a
+// value, so reusing it here would mean threading a throwaway `rl` through just to satisfy its
+// signature): raw mode is set only when `stdin.setRawMode` exists AND `stdin` was not already
+// raw, and is only ever turned back OFF by THIS call if THIS call was the one that turned it
+// on — never double-toggling a mode some other owner (an outer readline Interface) already
+// holds.
+//
+// Non-TTY stdin: `select()` throws (rejects with) `SELECT_NEEDS_TTY` synchronously, before
+// registering any listener or touching raw mode — the caller's contract (Scope 2/3: "TTY-only
+// wiring") is to catch this and fall back to the existing typed y/n prompt, never to call
+// `select()` speculatively and hope.
+
+import readline from 'node:readline';
+
+import { fg, reset, cursorUp, clearScreenDown, hideCursor, showCursor } from './ansi.mjs';
+import { PALETTE } from './palette.mjs';
+
+/** Thrown (as a rejected promise, `select` being `async`) when `stdin` is not a real TTY —
+ *  the caller's signal to fall back to the typed prompt instead of hanging on a stream that
+ *  will never deliver a raw keypress. Both `error.message` and `error.code` are set to this
+ *  string so either check works. */
+export const SELECT_NEEDS_TTY = 'SELECT_NEEDS_TTY';
+
+/** Wrap `text` in `fg(hex, depth)` ... `reset` — at depth 0 `fg` returns '', so this degrades
+ *  to plain text with no dangling reset (same convention as every other tui/*.mjs
+ *  colorSegment helper — input-box.mjs, slash-menu.mjs, status-bar.mjs). */
+function colorSegment(text, hex, depth) {
+  const prefix = fg(hex, depth);
+  return prefix ? `${prefix}${text}${reset}` : text;
+}
+
+/** Build this prompt's full block of lines (title, explanatory lines verbatim, the numbered
+ *  option list with the selected row in brand green, and the footer hint) — pure, no I/O,
+ *  called fresh on every render so `selectedIndex` is always reflected. `lines` are printed
+ *  exactly as given (a caller that wants a colored path/sentence, e.g. the folder-trust ask's
+ *  brand-colored path, pre-colors it itself — this module never re-colors caller text). */
+function buildLines({ title, lines, options, selectedIndex, footer, depth }) {
+  const out = [];
+  if (title) out.push(colorSegment(String(title), PALETTE.primary, depth));
+  for (const line of Array.isArray(lines) ? lines : []) {
+    out.push(String(line ?? ''));
+  }
+  options.forEach((opt, i) => {
+    const n = i + 1;
+    const marker = i === selectedIndex ? '❯' : ' ';
+    const text = `${marker} ${n}. ${opt.label}`;
+    out.push(i === selectedIndex ? colorSegment(text, PALETTE.brand, depth) : text);
+  });
+  if (footer) out.push(colorSegment(String(footer), PALETTE.stale, depth));
+  return out;
+}
+
+/** The index a single typed character jumps to, or -1 — a digit ("1".."9") jumps by 1-indexed
+ *  position; a single-character `option.key` (case-insensitive) jumps by identity. Multi-
+ *  character option keys (the common case — hs-chat.ts's callers use ids like "yes"/"exit",
+ *  not single-letter hotkeys) simply never match here, which is fine: Up/Down and the digit
+ *  jump always work regardless of what `key` looks like. */
+function jumpIndexForChar(ch, options) {
+  if (typeof ch !== 'string' || ch.length !== 1) return -1;
+  if (/^[1-9]$/.test(ch)) {
+    const idx = Number(ch) - 1;
+    return idx < options.length ? idx : -1;
+  }
+  return options.findIndex(
+    (o) => typeof o?.key === 'string' && o.key.length === 1 && o.key.toLowerCase() === ch.toLowerCase(),
+  );
+}
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.title]
+ * @param {string[]} [opts.lines] - explanatory lines, printed verbatim between the title and
+ *   the option list.
+ * @param {Array<{ key: string, label: string, hint?: string }>} opts.options - non-empty.
+ *   `hint`, when given, is appended to the option's row in the secondary color.
+ * @param {NodeJS.ReadStream} [opts.stdin] - defaults to `process.stdin`. Must be a real TTY
+ *   (`isTTY === true`) or this rejects with `SELECT_NEEDS_TTY`.
+ * @param {{ write: (s: string) => unknown }} [opts.stdout] - defaults to `process.stdout`.
+ * @param {24 | 8 | 0} [opts.depth]
+ * @param {string} [opts.footer] - the navigation hint line (e.g. "↑/↓ to navigate · enter to
+ *   select · esc to exit"), rendered in the secondary/stale color as the block's last line.
+ * @returns {Promise<string | null>} the chosen option's `key` on Enter, `null` on Escape.
+ */
+export async function select({
+  title,
+  lines = [],
+  options,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  depth = 0,
+  footer,
+} = {}) {
+  if (!Array.isArray(options) || options.length === 0) {
+    throw new Error('select(): options must be a non-empty array');
+  }
+  if (stdin.isTTY !== true) {
+    const err = new Error(SELECT_NEEDS_TTY);
+    err.code = SELECT_NEEDS_TTY;
+    throw err;
+  }
+
+  const alreadyRaw = stdin.isRaw === true;
+  const canSetRaw = typeof stdin.setRawMode === 'function';
+
+  readline.emitKeypressEvents(stdin);
+
+  let rawModeSetByUs = false;
+  if (canSetRaw && !alreadyRaw) {
+    stdin.setRawMode(true);
+    rawModeSetByUs = true;
+  }
+
+  let selectedIndex = 0;
+  let height = 0;
+
+  stdout.write(hideCursor);
+
+  function render() {
+    const rendered = buildLines({ title, lines, options, selectedIndex, footer, depth });
+    let seq = '';
+    if (height > 0) seq += `${cursorUp(height)}\r${clearScreenDown}`;
+    for (const line of rendered) seq += `${line}\n`;
+    stdout.write(seq);
+    height = rendered.length;
+  }
+
+  function erase() {
+    if (height === 0) return;
+    stdout.write(`${cursorUp(height)}\r${clearScreenDown}`);
+    height = 0;
+  }
+
+  return new Promise((resolve) => {
+    function cleanup() {
+      stdin.removeListener('keypress', onKeypress);
+      if (rawModeSetByUs && canSetRaw) stdin.setRawMode(false);
+      stdout.write(showCursor);
+    }
+
+    function finish(result) {
+      erase();
+      cleanup();
+      resolve(result);
+    }
+
+    function onKeypress(str, key) {
+      if (!key) {
+        const jump = jumpIndexForChar(str, options);
+        if (jump !== -1 && jump !== selectedIndex) {
+          selectedIndex = jump;
+          render();
+        }
+        return;
+      }
+      if (key.name === 'up') {
+        selectedIndex = (selectedIndex - 1 + options.length) % options.length;
+        render();
+        return;
+      }
+      if (key.name === 'down') {
+        selectedIndex = (selectedIndex + 1) % options.length;
+        render();
+        return;
+      }
+      if (key.name === 'return' || key.name === 'enter') {
+        finish(options[selectedIndex].key);
+        return;
+      }
+      if (key.name === 'escape') {
+        finish(null);
+        return;
+      }
+      const jump = jumpIndexForChar(str, options);
+      if (jump !== -1 && jump !== selectedIndex) {
+        selectedIndex = jump;
+        render();
+      }
+    }
+
+    stdin.on('keypress', onKeypress);
+    render();
+  });
+}
+
+export default { select, SELECT_NEEDS_TTY };