zames_pro 2.74.0 → 2.75.1

package/dist/tui/useMouseWheel.js

@@ -13,18 +13,32 @@
 // ALTERNATE-SCROLL: while the app is in the ALTERNATE SCREEN (full-screen
 // mode), terminals turn the mouse wheel into ARROW KEYS by default (DECSET
 // 1007, "alternate scroll mode"). Ink parses those arrows as normal Up/Down,
-// and the input editor at a buffer edge maps them to HISTORY — so the wheel
+// and the input editor at a buffer edge maps them to HISTORY -- so the wheel
 // scrolled the INPUT HISTORY instead of the log (the operator's bug).
 //
-// ORDER MATTERS and reporting is ALWAYS ON: some terminals only apply `1007l`
-// while mouse reporting is enabled, so sending `1007l` alone (the previous
-// behavior when ui.mouseScroll was off) was a no-op there and the wheel kept
-// arriving as arrows. We now enable 1000/1006 unconditionally and disable 1007
-// right after. Consequence: drag-select needs SHIFT (the standard TUI
-// convention — Shift+drag bypasses the app), which is the trade-off for a
-// working wheel. `enabled` only decides whether the wheel SCROLLS the log;
-// the events are consumed either way so they never reach the editor.
-import { useEffect } from 'react';
+// Two clear, MUTUALLY EXCLUSIVE modes (a terminal cannot do both at once):
+//   - SELECT (ui.mouseScroll=false): mouse reporting stays OFF, so the
+//     terminal owns the mouse -- drag-select works natively and the wheel is
+//     inert (no arrows, no history jump).
+//   - SCROLL (ui.mouseScroll=true): mouse reporting ON, so the wheel arrives
+//     as SGR events and scrolls the log; drag-select then needs SHIFT.
+//
+// THE CRITICAL DETAIL (this bug kept coming back): the mode sequences must be
+// written ONCE per mode change, NEVER per render. An earlier version listed
+// `onWheel` in the effect deps, but callers pass an inline arrow, so the
+// effect re-ran on EVERY render (the status spinner re-renders constantly) --
+// each cleanup wrote `1007h` (alternate-scroll ON) before the next setup wrote
+// `1007l`. A wheel notch that landed in that window became an ARROW and
+// scrolled the input history: the intermittent "either scroll or selection"
+// behaviour. The effect therefore depends ONLY on the mode + stdin, and the
+// callback is read from a ref (set in its own effect) so a new closure never tears
+// the terminal mode down.
+//
+// ORDER MATTERS: some terminals only apply `1007l` while mouse reporting is
+// enabled, so we enable 1000/1006 FIRST, then disable 1007. In SELECT mode we
+// actually want reporting off, so we send the on/off pair ONCE (the 1007l then
+// "sticks") and then leave reporting off.
+import { useEffect, useRef } from 'react';
 import { useStdin } from 'ink';
 /** True when a chunk contains an SGR mouse wheel event; returns the delta. */
 export function parseWheel(chunk) {
@@ -61,30 +75,64 @@ export function incompleteTail(chunk) {
 }
 const ESC = String.fromCharCode(27);
 /**
- * The terminal-mode sequences the hook writes. Exported PURE so a test can pin
- * the exact bytes AND their order (reporting FIRST, then 1007 off — some
- * terminals ignore `1007l` when mouse reporting is off, which is what made the
- * wheel keep scrolling the input history).
+ * The terminal-mode sequences the hook writes for a given mode. Exported PURE
+ * so a test can pin the exact bytes AND their order:
+ *   - SELECT (enabled=false): NO `1000h/1006h` in the STEADY state, `on`
+ *     only applies `1007l` (the one-time prime), and `off` guarantees the
+ *     reporting bits are clear on unmount;
+ *   - SCROLL (enabled=true): `1000h 1006h 1007l` in the STEADY state.
  */
-export function mouseModeSequences() {
-    const on = 
-    // 1000 = button-event tracking, 1006 = SGR extended coords, 1007 = off.
-    ESC + '[?1000h' + ESC + '[?1006h' + ESC + '[?1007l';
-    const off = ESC + '[?1006l' + ESC + '[?1000l' + ESC + '[?1007h';
-    return { on, off };
+export function mouseModeSequences(enabled) {
+    // 1000 = button-event tracking, 1006 = SGR extended coords, 1007 off always
+    // (being in alt-screen otherwise turns the wheel into arrows => history).
+    const reportingOn = ESC + '[?1000h' + ESC + '[?1006h';
+    const reportingOff = ESC + '[?1006l' + ESC + '[?1000l';
+    const alternateScrollOff = ESC + '[?1007l';
+    const alternateScrollOn = ESC + '[?1007h';
+    if (enabled) {
+        return {
+            on: reportingOn + alternateScrollOff,
+            off: reportingOff + alternateScrollOn,
+        };
+    }
+    // SELECT: the on/off pair is applied ONCE at mount so the 1007l sticks even
+    // though reporting is then off (some terminals ignore 1007l while reporting
+    // is off). After the prime the steady state has reporting OFF, and the
+    // listener is not bound, so nothing consumes the native selection.
+    return {
+        on: reportingOn + alternateScrollOff + reportingOff,
+        off: reportingOff + alternateScrollOn,
+    };
 }
 /**
  * Subscribe to wheel events on the given terminal and call `onWheel(delta)`
- * where delta > 0 means "scroll up / back". Enables SGR mouse reporting while
- * mounted and disables alternate-scroll so the wheel is never turned into
- * arrow keys.
+ * where delta > 0 means "scroll up / back".
+ *
+ * Two mutually exclusive modes:
+ *   - `enabled=false` (SELECT): mouse reporting stays OFF, native drag-select
+ *     works, the wheel is inert. The listener is still bound so an accidental
+ *     SGR byte from a previous mode never leaks into the editor as an arrow.
+ *   - `enabled=true` (SCROLL): reporting is on, the wheel scrolls the log
+ *     (via `onWheel`), drag-select needs Shift.
+ *
+ * The terminal mode is written ONCE per `enabled` change. The wheel listener
+ * is bound once and reads the latest `onWheel` from a ref, so an inline
+ * callback (a new identity every render) does NOT re-run the effect -- a
+ * re-run would momentarily re-enable alternate-scroll and let a wheel notch
+ * scroll the input history.
  */
-export function useMouseWheel(onWheel, enabled = true) {
+export function useMouseWheel(onWheel, enabled = false) {
     const { stdin, isRawModeSupported } = useStdin();
+    // The latest callback, without making the mode effect depend on its
+    // identity (callers pass an inline arrow).
+    const onWheelRef = useRef(onWheel);
+    useEffect(() => {
+        onWheelRef.current = onWheel;
+    }, [onWheel]);
     useEffect(() => {
         if (!isRawModeSupported)
             return;
-        const seq = mouseModeSequences();
+        const seq = mouseModeSequences(enabled);
         process.stdout.write(seq.on);
         // A sequence may be split across two chunks; carry the incomplete tail.
         let carry = '';
@@ -95,13 +143,14 @@ export function useMouseWheel(onWheel, enabled = true) {
             const scan = carry ? buf.slice(0, buf.length - carry.length) : buf;
             if (!scan.includes('\u001b[<'))
                 return;
-            // `enabled` decides whether the wheel SCROLLS; the event is consumed
-            // either way, so it never falls through to the editor as an arrow.
+            // SELECT mode ignores the wheel entirely (the event never reaches the
+            // editor either -- there is no reporting to generate it in the first
+            // place, but a stale SGR byte from a previous mode is swallowed here).
             if (!enabled)
                 return;
             const delta = parseWheel(scan);
             if (delta !== 0)
-                onWheel(delta);
+                onWheelRef.current(delta);
         };
         stdin.on('data', onData);
         return () => {
@@ -109,5 +158,7 @@ export function useMouseWheel(onWheel, enabled = true) {
             // Disable mouse reporting on unmount so normal selection works again.
             process.stdout.write(seq.off);
         };
-    }, [stdin, isRawModeSupported, onWheel, enabled]);
+        // `onWheel` is deliberately NOT a dependency: it is read via the ref so an
+        // inline callback does not tear the terminal mode down on every render.
+    }, [stdin, isRawModeSupported, enabled]);
 }

package/dist/tui/widgets.js

@@ -26,7 +26,12 @@ export function Select({ value, focused, }) {
 }
 /** A framed panel (rounded border) with an optional title bar and footer. */
 export function Panel({ title, subtitle, footer, width, children, }) {
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: UI.border, paddingX: 1, width: width, children: [title ? (_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { color: UI.title, bold: true, children: title }), subtitle ? _jsx(Text, { color: UI.dim, children: subtitle }) : null] })) : null, title ? _jsx(Text, { color: "#3a3f4b", children: '─'.repeat(40) }) : null, children, footer ? footer : null] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: UI.border, paddingX: 1, width: width, children: [title ? (_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { color: UI.title, bold: true, children: title }), subtitle ? _jsx(Text, { color: UI.dim, children: subtitle }) : null] })) : null, title ? (_jsx(Text, { color: "#3a3f4b", children: '─'.repeat(panelInnerCols(width)) })) : null, children, footer ? footer : null] }));
+}
+/** Inner width (minus border + paddingX) the panel divider should span. */
+function panelInnerCols(width) {
+    const cols = width || process.stdout.columns || 80;
+    return Math.max(1, cols - 6);
 }
 /** A single hint chip: `↑/↓ select`. */
 export function Hint({ keys, label, }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.74.0",
+  "version": "2.75.1",
   "description": "Terminal coding agent that drives a real browser to chat with DeepSeek, Qwen and other web LLMs — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
     "test:watch": "tsx --test --watch test/*.test.ts",
     "self-smoke": "tsx scripts/self-smoke.mts",
     "qwen-smoke": "tsx scripts/qwen-smoke.mts",
+    "qwen-models-smoke": "tsx scripts/qwen-models-smoke.mts",
     "render-demo": "tsx scripts/render-demo.mts",
     "render-how": "tsx scripts/render-how-it-works.mts",
     "build:readme": "tsx scripts/build-readme.mts",

package/scripts/ctd-live-driver.mts

@@ -0,0 +1,51 @@
+// Drive the live-like probe: type a seed, then send Ctrl+Delete in EVERY
+// encoding a terminal might use, and print the raw bytes + the buffer.
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ESC = String.fromCharCode(27)
+const LOG = '/tmp/ctd-live.log'
+try {
+  fs.unlinkSync(LOG)
+} catch {
+  /* ignore */
+}
+
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/ctd-live.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: { ...process.env, COLUMNS: '80', LINES: '24', PROBE_CTD_LOG: LOG },
+  },
+)
+child.stdout.on('data', () => {})
+child.stderr.on('data', () => {})
+
+const seq = process.argv[2] || 'xterm'
+const enc: Record<string, string> = {
+  xterm: ESC + '[3;5~',
+  kitty: ESC + '[3;5u',
+  vt: ESC + '[3;5:1~',
+}
+const bytes = enc[seq] ?? seq
+
+setTimeout(() => {
+  child.stdin.write('foo bar baz') // seed
+  setTimeout(() => {
+    child.stdin.write(bytes) // the Ctrl+Delete encoding
+    setTimeout(() => {
+      const log = fs.readFileSync(LOG, 'utf-8')
+      process.stdout.write('=== ' + seq + ' ===' + String.fromCharCode(10))
+      process.stdout.write(
+        log
+          .split(String.fromCharCode(10))
+          .filter((l) => l.startsWith('RAW') || l.startsWith('BUF'))
+          .join(String.fromCharCode(10)) + String.fromCharCode(10),
+      )
+      child.kill('SIGTERM')
+    }, 500)
+  }, 400)
+}, 5000)
+child.on('close', () => process.exit(0))

package/scripts/ctd-live.tsx

@@ -0,0 +1,33 @@
+// Minimal LIVE-like probe: the REAL TuiEditor exactly as index.ts builds it
+// (default options), plus a raw-stdin TAP that logs every byte the terminal
+// sends, so we can see EXACTLY what Ctrl+Delete produces on this terminal.
+import fs from 'node:fs'
+import { TuiEditor } from '../src/tui/TuiEditor.js'
+
+const LOG = process.env.PROBE_CTD_LOG || '/tmp/ctd-live.log'
+fs.writeFileSync(LOG, '')
+const w = (s: string): void => {
+  fs.appendFileSync(LOG, s + String.fromCharCode(10))
+}
+
+const ed = new TuiEditor({
+  prompt: '❯ › ',
+  commands: [],
+  locale: 'ru',
+  alternateScreen: true,
+})
+ed.onSubmit = () => {}
+ed.onAttach = () => null
+ed.onClipboard = () => Promise.resolve(null)
+ed.start()
+
+// Tap raw stdin: hex-dump every chunk so we see the exact bytes.
+process.stdin.on('data', (d: Buffer) => {
+  w('RAW ' + d.toString('hex') + ' ' + JSON.stringify(d.toString('utf-8')))
+})
+// Log the buffer after every change.
+ed.store.subscribe(() => {
+  const s = ed.store.getSnapshot().edit
+  w('BUF ' + JSON.stringify(s.buf) + ' cur=' + s.cursor)
+})
+setInterval(() => {}, 1 << 30)

package/scripts/escd-live-driver.mts

@@ -0,0 +1,37 @@
+// Send `ESC d` (what VSCode sends for Ctrl+Delete) to the REAL TuiEditor and
+// print the resulting buffer.
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+const ESC = String.fromCharCode(27)
+const LOG = '/tmp/ctd-live.log'
+try {
+  fs.unlinkSync(LOG)
+} catch {}
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/ctd-live.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: { ...process.env, COLUMNS: '80', LINES: '24', PROBE_CTD_LOG: LOG },
+  },
+)
+child.stdout.on('data', () => {})
+child.stderr.on('data', () => {})
+setTimeout(() => {
+  child.stdin.write('foo bar baz')
+  setTimeout(() => {
+    child.stdin.write(ESC + 'd')
+    setTimeout(() => {
+      const log = fs.readFileSync(LOG, 'utf-8')
+      process.stdout.write(
+        log
+          .split(String.fromCharCode(10))
+          .filter((l) => l.startsWith('RAW') || l.startsWith('BUF'))
+          .join(String.fromCharCode(10)) + String.fromCharCode(10),
+      )
+      child.kill('SIGTERM')
+    }, 500)
+  }, 400)
+}, 5000)
+child.on('close', () => process.exit(0))

package/scripts/inline-status-driver.mts

@@ -0,0 +1,31 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { Term } from '../test/vt100.mts'
+const NL = String.fromCharCode(10)
+const term = new Term(12, 60)
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/inline-status.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: { ...process.env, COLUMNS: '60', LINES: '12' },
+  },
+)
+child.stdout.on('data', (d) => term.write(d.toString('utf-8')))
+child.stderr.on('data', (d) => term.write(d.toString('utf-8')))
+setTimeout(() => {
+  const g = term.grid
+  if (g[term.r]) g[term.r][term.c] = String.fromCharCode(9673)
+  process.stdout.write(
+    g
+      .map((r) => r.join('').replace(/\s+$/, ''))
+      .map((l, n) => String(n).padStart(2) + '| ' + l)
+      .join(NL) +
+      NL +
+      'CURSOR row=' +
+      term.r +
+      NL,
+  )
+  child.kill('SIGTERM')
+}, 5000)
+child.on('close', () => process.exit(0))

package/scripts/inline-status.tsx

@@ -0,0 +1,33 @@
+import React from 'react'
+import { render } from 'ink'
+import { TuiStore } from '../src/tui/store.js'
+import { TuiApp } from '../src/tui/TuiApp.js'
+import { initialEditState } from '../src/tui/edit.js'
+const store = new TuiStore()
+store.set({
+  title: 'z',
+  version: '1',
+  workdir: '/tmp',
+  prompt: '> ',
+  locale: 'en',
+  commands: [],
+  edit: { ...initialEditState(), buf: 'abc' },
+  statusText: 'STATUS HERE',
+})
+const p = {
+  onSubmit: () => {},
+  onEscape: () => {},
+  onCtrlC: () => {},
+  onCopyCode: () => {},
+  onAttach: () => null,
+  onClipboard: () => Promise.resolve(null),
+  onHistoryChange: () => {},
+  onClearScreen: () => {},
+  attachments: [],
+  onPastesChange: () => {},
+}
+render(React.createElement(TuiApp, { store, inputProps: p }), {
+  exitOnCtrlC: false,
+  patchConsole: false,
+})
+setInterval(() => {}, 1 << 30)

package/scripts/mouse-churn.mts

@@ -0,0 +1,34 @@
+// Prove the mouse-mode churn is ZERO: mount the REAL TuiEditor, force several
+// store updates (like the 1s badge refresh does), and COUNT how many times the
+// raw stdout receives the mouse-mode sequences. With the effect depending on
+// an inline onWheel, the count grew per render (the wheel-vs-history bug);
+// with the ref fix, each mode byte is written ONCE.
+//
+// Exit code 0 = OK, 1 = churn detected. Prints a one-line verdict so the pty
+// test can assert on it.
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/tui-mouse-churn-probe.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: { ...process.env, COLUMNS: '80', LIMES: '24' },
+  },
+)
+let out = ''
+child.stdout.on('data', (d) => (out += d.toString('utf-8')))
+child.stderr.on('data', (d) => (out += d.toString('utf-8')))
+setTimeout(() => child.kill('SIGTERM'), 8000)
+child.on('close', () => {
+  const count = (seq: string): number => out.split(seq).length - 1
+  const on = count('\u001b[?1000h')
+  const altOff = count('\u001b[?1007l')
+  const altOn = count('\u001b[?1007h')
+  console.log('MOUSE_CHURN 1000h=' + on + ' 1007l=' + altOff + ' 1007h=' + altOn)
+  const ok = on === 1 && altOff === 1 && altOn === 0
+  console.log(ok ? 'MOUSE_CHURN_OK' : 'MOUSE_CHURN_FAIL')
+  process.exit(ok ? 0 : 1)
+})

package/scripts/qwen-models-smoke.mts

@@ -0,0 +1,117 @@
+// Qwen model-switching self-smoke: launch a REAL isolated QwenBrowser, list
+// the model catalogue, then SWITCH to several models and ask a question with
+// each — the operator explicitly asked that model switching be exercised.
+//
+// Isolation mirrors qwen-smoke.mts: a throwaway HOME + a read-only COPY of the
+// real qwen-profile (the live profile is never opened).
+//
+// Usage: npx tsx scripts/qwen-models-smoke.mts [--headed] [--all]
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const HEADED = process.argv.includes('--headed')
+const ALL = process.argv.includes('--all')
+const REAL_HOME = os.homedir()
+const PROFILE_SRC = path.join(REAL_HOME, '.zames', 'qwen-profile')
+
+if (!process.env.ZAMES_QWEN_MODELS_HOME) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'zames-qwen-models-'))
+  process.env.HOME = tmp
+  process.env.ZAMES_QWEN_MODELS_HOME = tmp
+  fs.mkdirSync(path.join(tmp, '.zames'), { recursive: true })
+  fs.mkdirSync(path.join(tmp, '.cache'), { recursive: true })
+  const realCfg = path.join(REAL_HOME, '.zames', 'config.json')
+  if (fs.existsSync(realCfg)) {
+    fs.copyFileSync(realCfg, path.join(tmp, '.zames', 'config.json'))
+  }
+  const realPw = path.join(REAL_HOME, '.cache', 'ms-playwright')
+  if (fs.existsSync(realPw)) {
+    fs.symlinkSync(realPw, path.join(tmp, '.cache', 'ms-playwright'))
+  }
+  if (fs.existsSync(PROFILE_SRC)) {
+    fs.cpSync(PROFILE_SRC, path.join(tmp, '.zames', 'qwen-profile'), {
+      recursive: true,
+      filter: (src) => !/^Singleton/.test(path.basename(src)),
+    })
+  }
+}
+
+const { QwenBrowser } = await import('../src/qwen-browser.ts')
+const { loadConfig } = await import('../src/config.ts')
+const cfg = loadConfig()
+
+const results: Array<{ name: string; ok: boolean; note?: string }> = []
+const record = (name: string, ok: boolean, note?: string): void => {
+  results.push({ name, ok, note })
+  console.log((ok ? 'PASS ' : 'FAIL ') + name + (note ? '  — ' + note : ''))
+}
+
+const browser = new QwenBrowser({
+  headless: !HEADED,
+  debug: false,
+  channel: cfg.browserChannel,
+  auth: cfg.browser.auth,
+  locale: 'ru',
+  minSendIntervalMs: 0,
+  answerTimeoutMs: 180000,
+  webSearch: false,
+  deepThinking: false,
+})
+browser.onNotice = (t: string) => console.log('  [notice] ' + t)
+
+async function main(): Promise<void> {
+  await browser.launch()
+  const timedOut = await Promise.race([
+    browser.waitForLogin().then(() => false),
+    new Promise<boolean>((r) => setTimeout(() => r(true), 60000)),
+  ])
+  if (timedOut) {
+    record('login', false, 'timed out')
+    await browser.close().catch(() => {})
+    process.exit(2)
+  }
+  record('login', true)
+
+  const models = await browser.listModels()
+  record(
+    'listModels',
+    models.length > 0,
+    'n=' + models.length + ' ' + models.map((m) => m.id).join(','),
+  )
+
+  // Switch through a few models and ask with each. Prefer distinct vendors so
+  // the dropdown selection really changes the backend.
+  const wanted = ALL ? models : models.slice(0, 3)
+  for (const m of wanted) {
+    try {
+      await browser.newChat()
+      browser.model = m.id
+      const ans = await browser.ask('Reply with exactly: OK', { agent: true })
+      const ok = /OK/i.test(ans)
+      record('model:' + m.id, ok, ok ? '' : 'got: ' + ans.slice(0, 60))
+    } catch (e) {
+      record('model:' + m.id, false, (e as Error).message)
+    }
+  }
+
+  await browser.close().catch(() => {})
+  const failed = results.filter((r) => !r.ok)
+  console.log(
+    '\nqwen-models-smoke: ' +
+      (results.length - failed.length) +
+      '/' +
+      results.length +
+      ' passed',
+  )
+  if (!process.env.ZAMES_QWEN_MODELS_KEEP) {
+    fs.rmSync(process.env.ZAMES_QWEN_MODELS_HOME as string, {
+      recursive: true,
+      force: true,
+    })
+  }
+  process.exit(failed.length ? 1 : 0)
+}
+
+void main()

package/scripts/ru-shot.mts

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { Term } from '../test/vt100.mts'
+const NL = String.fromCharCode(10)
+const term = new Term(20, 80)
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/tui-repro.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: { ...process.env, COLUMNS: '80', LINES: '20', PROBE_LOCALE: 'ru' },
+  },
+)
+child.stdout.on('data', (d) => term.write(d.toString('utf-8')))
+child.stderr.on('data', (d) => term.write(d.toString('utf-8')))
+setTimeout(() => {
+  process.stdout.write(term.render() + NL)
+  child.kill('SIGTERM')
+}, 5000)
+child.on('close', () => process.exit(0))

package/scripts/tui-comp-shot.mts

@@ -0,0 +1,63 @@
+// Screenshot a standalone TUI component under a pty, optionally driving keys.
+// Usage: npx tsx scripts/tui-comp-shot.mts --component=select --keys=j,j --cols=80 --rows=24
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { Term } from '../test/vt100.mts'
+
+const ESC = String.fromCharCode(27)
+const NL = String.fromCharCode(10)
+function arg(name: string, def = ''): string {
+  const hit = process.argv.find((a) => a.startsWith('--' + name + '='))
+  return hit ? hit.slice(name.length + 3) : def
+}
+const component = arg('component', 'select')
+const cols = Number(arg('cols', '80'))
+const rows = Number(arg('rows', '24'))
+const keys = arg('keys', '')
+  .split(',')
+  .filter((s) => s.length > 0)
+  .map((s) =>
+    s === 'UP'
+      ? ESC + '[A'
+      : s === 'DOWN'
+        ? ESC + '[B'
+        : s === 'TAB'
+          ? String.fromCharCode(9)
+          : s === 'ENTER'
+            ? String.fromCharCode(13)
+            : s === 'ESC'
+              ? ESC
+              : s,
+  )
+
+const term = new Term(rows, cols)
+const child = spawn(
+  'script',
+  ['-qec', 'npx tsx scripts/tui-components.tsx', '/dev/null'],
+  {
+    cwd: path.resolve('.'),
+    env: {
+      ...process.env,
+      COLUMNS: String(cols),
+      LINES: String(rows),
+      PROBE_COMPONENT: component,
+    },
+  },
+)
+child.stdout.on('data', (d) => term.write(d.toString('utf-8')))
+child.stderr.on('data', (d) => term.write(d.toString('utf-8')))
+let i = 0
+const tick = (): void => {
+  if (i < keys.length) {
+    child.stdin.write(keys[i])
+    i++
+    setTimeout(tick, 250)
+  } else {
+    setTimeout(() => {
+      process.stdout.write(term.render() + NL)
+      child.kill('SIGTERM')
+    }, 400)
+  }
+}
+setTimeout(tick, 4500)
+child.on('close', () => process.exit(0))