herm-tui 1.0.0-dev.1 → 1.0.0-dev.3

package/src/index.tsx

@@ -1,113 +0,0 @@
-#!/usr/bin/env bun
-// NOTE: CPU usage at idle (~40-80% of one core) comes from OpenTUI's render loop,
-// not React's scheduler. The TUI framework renders frames at targetFps (30) to the
-// terminal, which is an inherent cost of continuous TUI rendering. The scheduler
-// override (MessageChannel/setImmediate = undefined) was a red herring — verified
-// via per-thread profiling that the main JS thread drives the render loop.
-
-// OpenTUI's tree-sitter worker opens its wasm at a relative path that
-// emscripten resolves against the worker's process.cwd(). In dev Bun's
-// asset loader handles that; in the bundle we redirect to a shim sibling
-// that chdirs into dist/ before loading the real worker. The shim is
-// emitted alongside index.js at build time, so import.meta.dirname of
-// THIS file is its directory.
-import { dirname } from "path"
-import { fileURLToPath } from "url"
-const here = dirname(fileURLToPath(import.meta.url))
-// Only override when the shim actually exists next to the bundle. In
-// dev runs the shim isn't emitted and we fall through to OpenTUI's
-// default node_modules-relative resolution.
-import { existsSync } from "fs"
-import { join } from "path"
-const shim = join(here, "parser.worker.shim.js")
-if (existsSync(shim)) process.env.OTUI_TREE_SITTER_WORKER_PATH = shim
-
-import { createCliRenderer } from "@opentui/core";
-import { createRoot } from "@opentui/react";
-import { App } from "./app";
-import { parseLaunch, HELP, VERSION } from "./app/launch";
-import * as perf from "./utils/perf";
-import * as control from "./utils/control";
-import * as preferences from "./utils/preferences";
-import { resetTerminalModes, installExitResetHooks } from "./utils/terminal-reset";
-import { warmup as warmTokens } from "./utils/tokens";
-
-// Static ESM imports hoist above module-level code, so the only
-// honest import-graph measurement is process-uptime at the point
-// this line actually runs. Captured once; reported by perf.boot().
-perf.boot("import-graph", Bun.nanoseconds() / 1e6)
-
-const argv = Bun.argv.slice(2)
-if (argv.includes("--help") || argv.includes("-h")) {
-  process.stdout.write(HELP)
-  process.exit(0)
-}
-if (argv.includes("--version") || argv.includes("-v")) {
-  process.stdout.write(VERSION + "\n")
-  process.exit(0)
-}
-const launch = parseLaunch(argv)
-
-// Initialize and render
-const main = async () => {
-  // Self-heal a tab that a prior crashed TUI left with mouse / focus
-  // / bracketed-paste / kitty-keyboard modes stuck on. @opentui/core
-  // only resets ?1049 (alt-screen), so without this the composer
-  // gets poisoned by raw escape sequences on startup.
-  resetTerminalModes()
-  // And on our own exit paths, so we don't poison the next process.
-  installExitResetHooks()
-
-  perf.mem("pre-renderer")
-
-  const prefs = preferences.load()
-
-  const end = perf.mark("renderer-init")
-  const renderer = await createCliRenderer({
-    exitOnCtrlC: false, // We handle Ctrl+C ourselves
-    useMouse: prefs.mouse ?? true,
-    targetFps: prefs.targetFps ?? 30,
-    gatherStats: false,
-  });
-  end()
-
-  // OpenTUI's setupTerminal emits CSI >4;1m (modifyOtherKeys=1), then
-  // upgrades to kitty (CSI >4;0m + CSI >{flags}u) only if the async
-  // CSI ?u probe gets a reply. Level 1 does NOT disambiguate Ctrl+digit
-  // — they arrive as legacy control bytes (Ctrl+2=NUL, Ctrl+3=ESC,
-  // Ctrl+4=FS…) so `key.ctrl` is never true and tab-jump is dead on
-  // terminals without kitty support. Level 2 encodes every modified key
-  // as CSI 27;m;c~ which parseKeypress handles. setupTerminal is awaited
-  // inside createCliRenderer, so >4;1m is already out; this lands after.
-  // If kitty detection later fires, its >4;0m overrides this — harmless.
-  // Re-asserted on focus since a suspended child may have reset modes.
-  const bump = () => renderer.capabilities?.kitty_keyboard
-    || (process.stdout.isTTY && process.stdout.write("\x1b[>4;2m"))
-  bump()
-  renderer.on("focus", bump)
-
-  perf.mem("post-renderer")
-
-  const root = createRoot(renderer);
-
-  const endRender = perf.mark("first-render")
-  root.render(<App initialTheme={prefs.theme} launch={launch} />);
-  endRender()
-  perf.boot("first-render", Bun.nanoseconds() / 1e6)
-
-  // gpt-tokenizer is ~170ms to import and not needed for first frame;
-  // kick it off the hot path so the first count() call doesn't stall.
-  warmTokens()
-
-  perf.mem("post-first-render")
-
-  // Periodic memory monitor (every 15s when PERF=1)
-  perf.monitor(15_000)
-
-  // Control server for headless interaction (CONTROL=1)
-  control.start()
-};
-
-main().catch(console.error);
-
-export {};

package/src/keys/catalog.ts

@@ -1,115 +0,0 @@
-// Action catalog — the curated set of named, rebindable key actions.
-//
-// Each ActionId maps to a default chord string (see chord.ts for grammar),
-// a human description, and a scope. Scope drives Help grouping and tells
-// the migration which handler owns the match:
-//
-//   global    shell-level (useAppKeys) — fires regardless of focused tab
-//   list      shared nav vocabulary consumed by useListKeys across tabs/dialogs
-//   dialog    modal overlays
-//   composer  textarea keyBindings (fed via toBindings)
-//   <tab>     tab-local, matched only when that tab is focused
-//
-// `<leader>` is a two-stroke prefix (default Ctrl+X, rebindable via the
-// `leader` entry). Existing Ctrl-chords are kept as secondary alternates
-// so nothing breaks while the leader pattern settles; print() shows the
-// first alternate, so Help advertises the leader form.
-//
-// Trailing markers cross-reference opencode's config/keybinds.ts:
-//   (blank)  oc has the same action on substantively the same chord
-//   ø        oc has an analogue but herm binds it differently
-//   ☨        no oc equivalent (herm-specific surface or concept)
-
-export type Scope =
-  | "global" | "list" | "dialog" | "composer"
-  | "sessions" | "cron" | "env" | "agents" | "skills" | "config"
-
-export type Def = { chord: string; desc: string; scope: Scope }
-
-const def = (chord: string, desc: string, scope: Scope): Def => ({ chord, desc, scope })
-
-export const DEFAULTS = {
-  // ── global ──────────────────────────────────────────────────────
-  "leader":            def("ctrl+x",               "Leader prefix",                      "global"),
-  "app.exit":          def("ctrl+c",               "Quit (or copy selection)",           "global"),
-  "app.suspend":       def("ctrl+z",               "Suspend to shell",                   "global"),
-  "app.redraw":        def("ctrl+l",               "Clear & force-repaint terminal",     "global"), // ☨
-  "app.sidebar":       def("<leader>b",            "Toggle sidebar",                     "global"),
-  "palette.open":      def("ctrl+k",               "Command palette",                    "global"), // ø command_list=ctrl+p
-  "help.open":         def("f1",                   "Keyboard shortcuts",                 "global"), // ☨
-  "tab.next":          def("ctrl+right",           "Next tab",                           "global"), // ☨
-  "tab.prev":          def("ctrl+left",            "Previous tab",                       "global"), // ☨
-  "focus.cycle":       def("tab",                  "Cycle focus (double-tap → composer)","global"), // ☨
-  "editor.open":       def("<leader>e,ctrl+g",     "Open $EDITOR on prompt",             "global"),
-  "reply.copy":        def("<leader>y,ctrl+y",     "Copy last assistant reply",          "global"),
-  "clipboard.attach":  def("alt+v",                "Attach clipboard image",             "global"), // ø input_paste=ctrl+v
-  // "queue.pop":         def("ctrl+u",               "Pop last queued prompt",             "global"), // ☨ k: need to think about this more. defer
-  "session.interrupt": def("escape",               "Interrupt (double-tap while streaming)", "global"),
-  "session.new":       def("<leader>n",            "New session",                        "global"),
-  "session.undo":      def("<leader>u",            "Undo last turn",                     "global"),
-  "session.compress":  def("<leader>c",            "Compress context",                   "global"),
-  "session.timeline":  def("<leader>g",            "Session timeline",                   "global"),
-  "theme.pick":        def("<leader>t",            "Switch theme",                       "global"),
-  "model.pick":        def("<leader>m",            "Switch model",                       "global"),
-  // "tool.details":      def("<leader>d",            "Cycle tool-trail detail",            "global"), // ø tool_details=none k: I need to see if it warrants a shortcut. defer
-  "status.open":       def("<leader>s",            "Show status",                        "global"),
-
-  // ── list (shared across tabs + list-shaped dialogs) ─────────────
-  // ☨ — oc has no generic list surface; nearest are per-dialog
-  //     session_*/stash_* bindings and messages_* scroll.
-  "list.up":           def("up",                   "Move selection up",                  "list"),
-  "list.down":         def("down",                 "Move selection down",                "list"),
-  "list.pageUp":       def("pageup",               "Page up",                            "list"),
-  "list.pageDown":     def("pagedown",             "Page down",                          "list"),
-  "list.home":         def("home",                 "First item",                         "list"),
-  "list.end":          def("end",                  "Last item",                          "list"),
-  "list.activate":     def("return",               "Activate / open",                    "list"),
-  "list.delete":       def("d,delete",             "Delete item",                        "list"),
-  "list.refresh":      def("r",                    "Reload",                             "list"), // k: where is this used?  → 7 tabs; removal tracked in herm-0pg.15 (gated on bqo)
-  "list.new":          def("n",                    "Create",                             "list"), // k: keep
-  "list.search":       def("/",                    "Filter",                             "list"),
-  "list.toggle":       def("space",                "Toggle item",                        "list"),
-
-  // ── dialog ──────────────────────────────────────────────────────
-  // ☨ — oc dialogs hardcode return/escape/y/n per-component.
-  "dialog.accept":     def("return",               "Accept",                             "dialog"),
-  "dialog.cancel":     def("escape",               "Cancel / close",                     "dialog"),
-  "dialog.confirm":    def("y",                    "Yes",                                "dialog"),
-  "dialog.deny":       def("n",                    "No",                                 "dialog"),
-  "dialog.copy":       def("c",                    "Copy body",                          "dialog"),
-
-  // ── composer (fed to <textarea keyBindings> via toBindings) ───── // k: I think you need to ELI5 what you mean here
-  "input.submit":      def("return",               "Send",                               "composer"),
-  "input.newline":     def("shift+return,ctrl+return,alt+return,ctrl+j", "Insert newline", "composer"),
-
-  // ── tab-specific ────────────────────────────────────────────────
-  // ☨ — herm admin tabs (Cron/Env/Skills/Agents/Config) have no oc
-  //     counterpart; sessions.rename diverges from oc's session-
-  //     dialog ctrl+r.
-  "sessions.rename":   def("ctrl+r",               "Retitle session",                    "sessions"), // match oc session_rename
-  "sessions.prev":     def("left",                 "Walk lineage back (continues from)", "sessions"),
-  "sessions.next":     def("right",                "Walk lineage forward (compressed to)", "sessions"),
-  "agents.kill":       def("k",                    "Kill subagent",                      "agents"),	// k: I like this
-  "agents.history":    def("h",                    "Spawn history",                      "agents"),	// k: keep
-  "config.save":       def("ctrl+s",               "Write config",                       "config"),
-} satisfies Record<string, Def>
-
-export type ActionId = keyof typeof DEFAULTS
-
-/** Actions in a given scope, catalog order. */
-export function inScope(s: Scope): ActionId[] {
-  return (Object.keys(DEFAULTS) as ActionId[]).filter(id => DEFAULTS[id].scope === s)
-}
-
-// Two scopes overlap if both handlers can be live for the same keypress.
-// global fires everywhere; list is active on every admin tab alongside that
-// tab's own scope; dialog and composer are modal/focused surfaces that
-// displace the rest; distinct tab scopes are mutually exclusive.
-const TAB_SCOPES = new Set<Scope>(["sessions", "cron", "env", "agents", "skills", "config"])
-export function scopesOverlap(a: Scope, b: Scope): boolean {
-  if (a === b) return true
-  if (a === "global" || b === "global") return true
-  if (a === "list") return TAB_SCOPES.has(b)
-  if (b === "list") return TAB_SCOPES.has(a)
-  return false
-}

package/src/keys/chord.ts

@@ -1,125 +0,0 @@
-// Chord primitives — parse/match/print for keybinding strings.
-//
-// A chord string is comma-separated alternates, each alternate is
-// `+`-separated modifiers followed by a key name:
-//   "ctrl+shift+k"  "shift+return,ctrl+j"  "<leader>e"  "none"
-//
-// `<leader>` is a synthetic modifier; whether the leader is currently armed
-// is provided by the caller at match time (the provider owns that state).
-
-import type { ParsedKey } from "@opentui/core"
-
-export type Chord = {
-  readonly name: string
-  readonly ctrl: boolean
-  readonly meta: boolean
-  readonly shift: boolean
-  readonly super: boolean
-  readonly leader: boolean
-}
-
-const ALIAS: Record<string, string> = {
-  esc: "escape",
-  enter: "return",
-  del: "delete",
-  ins: "insert",
-  space: "space",
-  " ": "space",
-}
-
-/** Parse a chord string into its alternate Chord list. "none" / "" → []. */
-export function parse(spec: string): Chord[] {
-  if (!spec || spec === "none") return []
-  return spec.split(",").map(one)
-}
-
-function one(combo: string): Chord {
-  const c = { name: "", ctrl: false, meta: false, shift: false, super: false, leader: false }
-  for (const raw of combo.replace(/<leader>/g, "leader+").toLowerCase().split("+")) {
-    const p = raw.trim()
-    if (!p) continue
-    if (p === "ctrl") c.ctrl = true
-    else if (p === "alt" || p === "meta" || p === "option") c.meta = true
-    else if (p === "shift") c.shift = true
-    else if (p === "super" || p === "cmd") c.super = true
-    else if (p === "leader") c.leader = true
-    else c.name = ALIAS[p] ?? p
-  }
-  return c
-}
-
-/** Normalize an OpenTUI ParsedKey to a Chord. */
-export function from(key: ParsedKey, leader = false): Chord {
-  // kitty protocol emits name=" " for space; legacy emits "space".
-  const name = key.name === " " ? "space" : key.name
-  return {
-    name,
-    ctrl: key.ctrl,
-    meta: key.meta,
-    shift: key.shift,
-    super: key.super ?? false,
-    leader,
-  }
-}
-
-function eq(a: Chord, b: Chord): boolean {
-  return a.name === b.name
-    && a.ctrl === b.ctrl && a.meta === b.meta
-    && a.shift === b.shift && a.super === b.super
-    && a.leader === b.leader
-}
-
-/** True if the event matches any alternate in the chord list. */
-export function match(list: ReadonlyArray<Chord>, key: ParsedKey, leader = false): boolean {
-  if (list.length === 0) return false
-  const k = from(key, leader)
-  return list.some(c => eq(c, k))
-}
-
-/** Render the first alternate for display. `lead` substitutes `<leader>`. */
-export function print(list: ReadonlyArray<Chord>, lead?: string): string {
-  const c = list[0]
-  if (!c) return ""
-  const mods: string[] = []
-  if (c.ctrl) mods.push("Ctrl")
-  if (c.meta) mods.push("Alt")
-  if (c.super) mods.push("Super")
-  if (c.shift) mods.push("Shift")
-  const name = LABEL[c.name] ?? cap(c.name)
-  const body = [...mods, name].join("+")
-  if (!c.leader) return body
-  return lead ? `${lead} ${body}` : `<leader> ${body}`
-}
-
-const LABEL: Record<string, string> = {
-  return: "Enter",
-  escape: "Esc",
-  space: "Space",
-  delete: "Del",
-  backspace: "⌫",
-  up: "↑", down: "↓", left: "←", right: "→",
-  pageup: "PgUp", pagedown: "PgDn",
-  home: "Home", end: "End",
-  tab: "Tab",
-}
-
-function cap(s: string): string {
-  return s.length === 1 ? s.toUpperCase() : s.charAt(0).toUpperCase() + s.slice(1)
-}
-
-/** Chord[] → KeyBinding[] for the textarea renderable's keyBindings prop. */
-export function toBindings<A extends string>(list: ReadonlyArray<Chord>, action: A) {
-  return list.map(c => ({
-    name: c.name,
-    ctrl: c.ctrl || undefined,
-    meta: c.meta || undefined,
-    shift: c.shift || undefined,
-    super: c.super || undefined,
-    action,
-  }))
-}
-
-/** Canonical string key for a Chord — for Map-bucketing by chord equality. */
-export function key(c: Chord): string {
-  return `${c.leader ? "L" : ""}${c.ctrl ? "C" : ""}${c.meta ? "M" : ""}${c.shift ? "S" : ""}${c.super ? "W" : ""}-${c.name}`
-}

package/src/keys/conflicts.ts

@@ -1,48 +0,0 @@
-import { DEFAULTS, scopesOverlap, type ActionId } from "./catalog"
-import { key, type Chord } from "./chord"
-
-export type Conflict = { chord: Chord; a: ActionId; b: ActionId }
-
-/**
- * Find all action pairs that share a chord in overlapping scopes.
- * O(N) bucket by chord-key, then pairwise scopesOverlap() within each
- * bucket (buckets are tiny in practice).
- */
-export function conflicts(table: ReadonlyMap<ActionId, ReadonlyArray<Chord>>): Conflict[] {
-  const buckets = new Map<string, Array<[ActionId, Chord]>>()
-  for (const [id, chords] of table)
-    for (const c of chords) {
-      const k = key(c)
-      const b = buckets.get(k)
-      if (b) b.push([id, c])
-      else buckets.set(k, [[id, c]])
-    }
-  const out: Conflict[] = []
-  for (const bucket of buckets.values()) {
-    if (bucket.length < 2) continue
-    for (let i = 0; i < bucket.length; i++)
-      for (let j = i + 1; j < bucket.length; j++) {
-        const [a, c] = bucket[i], [b] = bucket[j]
-        if (scopesOverlap(DEFAULTS[a].scope, DEFAULTS[b].scope))
-          out.push({ chord: c, a, b })
-      }
-  }
-  return out
-}
-
-/** Actions whose current chord collides with `id`'s in an overlapping scope. */
-export function conflictsWith(
-  table: ReadonlyMap<ActionId, ReadonlyArray<Chord>>,
-  id: ActionId,
-): ActionId[] {
-  const mine = new Set((table.get(id) ?? []).map(key))
-  if (mine.size === 0) return []
-  const scope = DEFAULTS[id].scope
-  const out: ActionId[] = []
-  for (const [other, chords] of table) {
-    if (other === id) continue
-    if (!scopesOverlap(scope, DEFAULTS[other].scope)) continue
-    if (chords.some(c => mine.has(key(c)))) out.push(other)
-  }
-  return out
-}

package/src/keys/context.tsx

@@ -1,112 +0,0 @@
-// KeysProvider — resolves the action catalog (DEFAULTS ← user overrides),
-// owns leader-armed state, and exposes match()/print()/chord()/all.
-//
-// Leader flow: the provider's own useKeyboard sees the leader chord first
-// (global listeners fire before renderable handlers). It arms, blurs the
-// focused renderable so the follow-up bare letter isn't eaten by a textarea
-// or tab handler, and starts a 2s window. The next keypress is evaluated
-// with leader=true by callers' match(); on any keypress while armed the
-// provider disarms in a microtask (after other useKeyboard subscribers on
-// the same event have read `leader`) and restores focus.
-
-import { createContext, useContext, useMemo, useRef, useCallback, useState, type ReactNode } from "react"
-import { useKeyboard, useRenderer } from "@opentui/react"
-import type { ParsedKey, Renderable } from "@opentui/core"
-import { usePref } from "../utils/preferences"
-import { DEFAULTS, type ActionId, type Scope } from "./catalog"
-import { parse, match as chordMatch, print as chordPrint, type Chord } from "./chord"
-
-const LEADER_MS = 2000
-
-export type Entry = { id: ActionId; desc: string; scope: Scope; chord: ReadonlyArray<Chord> }
-
-export type Keys = {
-  /** True while the leader prefix is armed (between Ctrl+X and the next key). */
-  readonly leader: boolean
-  /** Does `key` match the action's resolved chord? Uses current leader state. */
-  match(id: ActionId, key: ParsedKey): boolean
-  /** Display string for an action's first chord, with <leader> substituted. */
-  print(id: ActionId): string
-  /** Resolved Chord[] for an action. */
-  chord(id: ActionId): ReadonlyArray<Chord>
-  /** All actions in a scope, resolved. */
-  all(scope: Scope): ReadonlyArray<Entry>
-  /** Full resolved id→Chord[] table (for conflict detection / rebind UI). */
-  readonly table: ReadonlyMap<ActionId, ReadonlyArray<Chord>>
-}
-
-const Ctx = createContext<Keys | null>(null)
-
-const NO_OVERRIDES: Readonly<Record<string, string>> = Object.freeze({})
-
-export const KeysProvider = ({ children }: { children: ReactNode }) => {
-  const renderer = useRenderer()
-  const overrides = usePref("keys") ?? NO_OVERRIDES
-
-  // id → Chord[] computed once per overrides identity. Leader's own chord
-  // is looked up from the same table so it's rebindable.
-  const table = useMemo(() => {
-    const t = new Map<ActionId, Chord[]>()
-    for (const id of Object.keys(DEFAULTS) as ActionId[])
-      t.set(id, parse(overrides[id] ?? DEFAULTS[id].chord))
-    return t
-  }, [overrides])
-
-  const lead = table.get("leader")!
-  const leadLabel = chordPrint(lead)
-
-  // Leader arm state. `armed` is a ref so match() reads the value at
-  // key-time without the provider re-rendering every consumer on arm.
-  const armed = useRef(false)
-  const stolen = useRef<Renderable | null>(null)
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const [, bump] = useState(0)
-
-  const disarm = useCallback(() => {
-    if (!armed.current) return
-    armed.current = false
-    if (timer.current) { clearTimeout(timer.current); timer.current = null }
-    const f = stolen.current
-    stolen.current = null
-    if (f && !f.isDestroyed && !renderer.currentFocusedRenderable) f.focus()
-    bump(n => n + 1)
-  }, [renderer])
-
-  const arm = useCallback(() => {
-    armed.current = true
-    stolen.current = renderer.currentFocusedRenderable ?? null
-    stolen.current?.blur()
-    if (timer.current) clearTimeout(timer.current)
-    timer.current = setTimeout(disarm, LEADER_MS)
-    bump(n => n + 1)
-  }, [renderer, disarm])
-
-  useKeyboard((key) => {
-    if (!armed.current && chordMatch(lead, key)) {
-      arm()
-      key.stopPropagation()
-      return
-    }
-    if (armed.current) queueMicrotask(disarm)
-  })
-
-  const value = useMemo<Keys>(() => ({
-    get leader() { return armed.current },
-    match: (id, key) => chordMatch(table.get(id) ?? [], key, armed.current),
-    print: (id) => chordPrint(table.get(id) ?? [], leadLabel),
-    chord: (id) => table.get(id) ?? [],
-    all: (scope) =>
-      (Object.keys(DEFAULTS) as ActionId[])
-        .filter(id => DEFAULTS[id].scope === scope)
-        .map(id => ({ id, desc: DEFAULTS[id].desc, scope, chord: table.get(id) ?? [] })),
-    table,
-  }), [table, leadLabel])
-
-  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
-}
-
-export const useKeys = (): Keys => {
-  const ctx = useContext(Ctx)
-  if (!ctx) throw new Error("useKeys() must be inside <KeysProvider>")
-  return ctx
-}

package/src/keys/index.ts

@@ -1,5 +0,0 @@
-export { KeysProvider, useKeys, type Keys } from "./context"
-export { useListKeys, handleListKey, useFollow } from "./list"
-export { DEFAULTS, type ActionId, type Scope } from "./catalog"
-export { parse, toBindings, type Chord } from "./chord"
-export { conflicts, conflictsWith } from "./conflicts"

package/src/keys/list.ts

@@ -1,94 +0,0 @@
-// Shared list navigation — maps list.* catalog actions onto a selection
-// index + per-tab action callbacks. Two entry points:
-//
-//   handleListKey()  plain dispatcher, returns true if consumed. Tabs with
-//                    text-capture sub-modes (search/edit) call this from
-//                    their own useKeyboard after the sub-mode branch.
-//   useListKeys()    hook wrapper that owns the useKeyboard subscriber for
-//                    tabs that don't need a bespoke one.
-//
-// Callers own the `active` guard (focused ∧ no dialog ∧ no sub-mode) so this
-// layer doesn't depend on ui/dialog. Leader-armed correctness falls out of
-// keys.match(): list.* chords have leader=false, so a bare letter while
-// armed never matches here and falls through to useAppKeys.
-
-import { useRef, type Dispatch, type SetStateAction } from "react"
-import { useKeyboard } from "@opentui/react"
-import type { ParsedKey, ScrollBoxRenderable } from "@opentui/core"
-import { useKeys, type Keys } from "./context"
-
-export type ListOpts = {
-  count: number
-  setSel: Dispatch<SetStateAction<number>>
-  /** PgUp/PgDn stride; typically viewport height − 1. */
-  page?: number
-  /** Called with the clamped target after every nav move (scroll-into-view). */
-  scrollTo?: (i: number) => void
-  onActivate?: () => void
-  onDelete?: () => void
-  onRefresh?: () => void
-  onNew?: () => void
-  onToggle?: () => void
-  onSearch?: () => void
-}
-
-export function handleListKey(keys: Keys, key: ParsedKey, o: ListOpts): boolean {
-  const move = (next: (p: number) => number) => {
-    o.setSel(p => {
-      const n = Math.max(0, Math.min(o.count - 1, next(p)))
-      o.scrollTo?.(n)
-      return n
-    })
-  }
-  const pg = o.page ?? 10
-  if (keys.match("list.up", key))       { move(p => p - 1); return true }
-  if (keys.match("list.down", key))     { move(p => p + 1); return true }
-  if (keys.match("list.pageUp", key))   { move(p => p - pg); return true }
-  if (keys.match("list.pageDown", key)) { move(p => p + pg); return true }
-  if (keys.match("list.home", key))     { move(() => 0); return true }
-  if (keys.match("list.end", key))      { move(() => o.count - 1); return true }
-  if (o.onActivate && keys.match("list.activate", key)) { o.onActivate(); return true }
-  if (o.onDelete   && keys.match("list.delete",   key)) { o.onDelete();   return true }
-  if (o.onRefresh  && keys.match("list.refresh",  key)) { o.onRefresh();  return true }
-  if (o.onNew      && keys.match("list.new",      key)) { o.onNew();      return true }
-  if (o.onToggle   && keys.match("list.toggle",   key)) { o.onToggle();   return true }
-  if (o.onSearch   && keys.match("list.search",   key)) { o.onSearch();   return true }
-  return false
-}
-
-export function useListKeys(o: ListOpts & {
-  active: boolean
-  /** Tab-scoped actions; runs if no list.* action matched. */
-  also?: (key: ParsedKey, keys: Keys) => void
-}): Keys {
-  const keys = useKeys()
-  useKeyboard(key => {
-    if (!o.active) return
-    if (handleListKey(keys, key, o)) return
-    o.also?.(key, keys)
-  })
-  return keys
-}
-
-// Scroll-follow for list tabs: returns a scrollbox ref, a row-id
-// generator, and the two ListOpts fields (scrollTo, page) derived from
-// them. `scrollChildIntoView` resolves by element id, so each row's
-// root box must set `id={follow.id(i)}` and the scrollbox
-// `ref={follow.ref}`. Spread the rest into handleListKey/useListKeys:
-//
-//   const follow = useFollow("tab")
-//   handleListKey(keys, key, { count, setSel, ...follow.opts, ... })
-//   <scrollbox ref={follow.ref}>
-//     <Row id={follow.id(i)} ... />
-//
-export function useFollow(prefix: string) {
-  const ref = useRef<ScrollBoxRenderable | null>(null)
-  const id = (i: number) => `${prefix}-row-${i}`
-  return {
-    ref, id,
-    opts: {
-      scrollTo: (n: number) => ref.current?.scrollChildIntoView(id(n)),
-      get page() { return Math.max(1, (ref.current?.viewport.height ?? 10) - 1) },
-    },
-  }
-}