@cruxy/cli 1.2.0 → 1.3.0

package/dist/cli/session-factory.js

@@ -10,16 +10,39 @@ import { withCheckpointGate } from "../checkpoint/index.js";
 // session factory keep working.
 export { withCheckpointGate };
 import { shouldUseColor } from "../errors/index.js";
+// The concrete TUI modules, not `tui/index.js`: `render/index.js` already
+// imports `tui/renderer.js`, and routing this through the barrel would pull the
+// whole TUI surface into a module the one-shot path also loads.
+import { createOverlayPromptIO } from "../tui/approval-overlay.js";
+import { canOverlay } from "../tui/overlay.js";
+import { TuiRenderer } from "../tui/renderer.js";
 import { buildDefaultRegistry, } from "../tools/index.js";
-import { Session, } from "../agent/index.js";
+import { DEFAULT_MODE, Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
-import { routerForConfig } from "../routing/index.js";
+import { parseModelChoice, routerForConfig, SessionModel, } from "../routing/index.js";
 import { MemoryService, buildMultiRootRecallBlock, rememberTool, } from "../memory/index.js";
 import { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "../lsp/index.js";
 import { createWebSearchTool, createWebFetchTool } from "../web/index.js";
 import { appendRun } from "../usage/index.js";
 import { Semaphore, SubagentOrchestrator, makeSpawnSubagentTool, makeSpawnSubagentsTool, } from "../subagent/index.js";
 import { ApprovalQueue, JobManager, makeRunInBackgroundTool, } from "../jobs/index.js";
+/**
+ * Where this session's prompts are drawn (P5 track 2).
+ *
+ * The TUI gets an in-viewport modal — but only with a lease in hand. Both
+ * conditions are load-bearing and neither implies the other: without the TUI
+ * there is no drawer to paint into, and without the lease the modal would open
+ * a second raw-mode reader on the stdin the input loop is already holding,
+ * which is the contention the seam exists to prevent. Either missing, and the
+ * unchanged stderr prompt is the correct answer rather than a degraded one.
+ */
+function promptIOFor(renderer, lease) {
+    const color = shouldUseColor();
+    if (renderer instanceof TuiRenderer && lease && canOverlay(renderer)) {
+        return createOverlayPromptIO(renderer, lease, color);
+    }
+    return defaultPromptIO(color);
+}
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
  * (U.2/U.4): the prompt writes to stderr while the status line owns the last
@@ -27,25 +50,51 @@ import { ApprovalQueue, JobManager, makeRunInBackgroundTool, } from "../jobs/ind
  * hides the live line (the prompt IS the visible state) while keeping the
  * step-progress register intact, so the line comes back with full context on
  * the next transition after the user decides.
+ *
+ * Under the TUI (P5 track 2) the phase no longer hides anything — the prompt is
+ * an overlay drawer composed into the paint — but it still displaces the live
+ * state and stops the clock, so this wrapper is unchanged and still the one
+ * place the phase is entered.
+ *
+ * The trigger is `beginPrompt`, NOT `write`. This io is shared by every prompt
+ * in the session AND by write-only callers that never read — the plan
+ * executor's per-step trail, and its "plan aborted" line. Yielding on `write`
+ * treated those as pending approvals, which under the full-viewport TUI meant
+ * `TuiRenderer.paintNow` cleared the entire frame on every plan step: plan mode
+ * and the TUI together blanked the screen and never repainted until the next
+ * phase change. Only a caller that is actually about to read may release the
+ * screen, and it says so.
+ *
+ * `endPrompt` is the paired closer, and it is not optional in practice: the
+ * plan prompts had nothing that gave the screen back, so aborting a plan left
+ * the TUI painting an empty frame until some later turn happened to change the
+ * phase. Every prompt now brackets itself in a `finally`, so even a default-deny
+ * on EOF restores the live region.
  */
-function suspendStatusOnPrompt(io, renderer) {
+export function suspendStatusOnPrompt(io, renderer) {
     if (!renderer)
         return io;
     return {
         ...io,
-        write: (text) => {
+        beginPrompt: () => {
+            io.beginPrompt?.();
             renderer.setPhase({ kind: "awaiting-approval" });
-            io.write(text);
+        },
+        endPrompt: () => {
+            io.endPrompt?.();
+            renderer.promptResolved();
         },
     };
 }
 /**
- * Restore the live line once an approval request fully settles (U.4). The
- * settle point must be the service call, not the prompt's key read: the
- * prompt writes a trailing newline AFTER the read, which re-enters
- * `awaiting-approval` — resolving here is the first moment no more prompt
- * bytes can follow. Fires on every decision (prompted or not); the renderer
- * treats it as a no-op unless a prompt actually displaced the line.
+ * Restore the live line once an approval request settles (U.4).
+ *
+ * A BACKSTOP, not the primary path: `promptForApproval` now brackets itself
+ * with `beginPrompt`/`endPrompt`, so the prompted path has already restored the
+ * line by the time this runs. It stays because this wraps the whole approval
+ * SERVICE — which can settle a request without ever prompting (a session grant,
+ * a policy auto-allow) — and because `promptResolved` is a no-op unless a
+ * prompt actually displaced the line, so a second call costs nothing.
  */
 function resumeLineAfterApproval(requestApproval, renderer) {
     if (!renderer)
@@ -59,6 +108,31 @@ function resumeLineAfterApproval(requestApproval, renderer) {
         }
     };
 }
+/**
+ * Show the diff for an action that was allowed WITHOUT the user being shown it
+ * (P3) — a session grant the allowlist answered, or a read-tier pass.
+ *
+ * This is the missing caller for `StreamRenderer.preview`. The seam has been
+ * implemented on every renderer since U.2 and nothing ever originated a call:
+ * the approval prompt draws its own diff straight to the io, so a PROMPTED
+ * action is already on screen and calling `preview` there would show it twice.
+ * The gap is the other path — once the user picks "allow this session", every
+ * later edit was applied with nothing rendered at all. That is what this fills.
+ *
+ * Only fires on an allow that carries no preview of its own, and only when the
+ * action actually has one, so read-tier passes (which carry none) stay silent.
+ */
+export function previewSilentApprovals(requestApproval, renderer) {
+    if (!renderer)
+        return requestApproval;
+    return async (action) => {
+        const decision = await requestApproval(action);
+        if (decision.allow && !decision.prompted && action.preview) {
+            renderer.preview(action.preview);
+        }
+        return decision;
+    };
+}
 /**
  * Register every CONDITIONALLY-enabled runtime tool onto `registry`, in the fixed
  * order the model sees them: `remember` (memory), the four LSP tools, the two web
@@ -122,11 +196,16 @@ export function registerRuntimeTools(registry, config, opts = {}) {
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
  * The approval gate's interactivity tracks the TTY, exactly as in `run`.
  *
- * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
- * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
- * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ * The {@link PlanExecutionPolicy} over the shared U.3 allowlist and the
+ * `planRunner` are wired UNCONDITIONALLY (P5 track 3), so a session can be
+ * switched into a planning mode at runtime. `mode` decides only whether they
+ * engage; a manual session behaves exactly as before.
  */
-export function buildAgentSession(config, apiKey, workspace, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks, mcpTools = []) {
+export function buildAgentSession(config, apiKey, workspace, ttyInteractive, mode = DEFAULT_MODE, renderer, checkpoints, sandbox, hooks, mcpTools = [], 
+// An options bag rather than two more positional parameters — this signature
+// is already at ten, and P2's two additions are both optional and unrelated
+// to each other.
+opts = {}) {
     // The workspace is the single source of truth for "which roots" (C.26). Every
     // primary-scoped subsystem below (git context, project instructions, memory,
     // checkpoints, subagents, the approval gate) derives its cwd from the primary
@@ -142,10 +221,24 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         temperature: config.model.temperature,
         gatewayUrl: config.cruxy.gatewayUrl,
     });
-    // Multi-model routing (C.30): null unless routing is configured on a cruxy
-    // session, so the default path threads `undefined` and behaves exactly as
-    // before. One router is shared by the main loop, subagents, and plan mode.
-    const router = routerForConfig(config) ?? undefined;
+    // The session's model choice, and the router everything selects through
+    // (C.30 + P6 track 1). One object shared by the main loop, subagents, plan
+    // mode and background jobs — which is what makes `/model` reach all of them
+    // without re-wiring any: they hold a reference, not a resolved tier.
+    //
+    // Built ONLY for the cruxy gateway, and the omission is the honest answer
+    // rather than a gap. Tiers are a gateway concept; a bring-your-own provider's
+    // `model.model` is an upstream id this CLI must not even name (U.8), so there
+    // is no menu to offer and `router` stays `undefined` exactly as before.
+    //
+    // The starting choice is `config.model.model` when it names one — so a user
+    // who pinned `kavi` in config opens on `kavi`, and `/model auto` moves them to
+    // server-side routing rather than back to that pin. Anything else (an unknown
+    // string) falls back to `auto`, which is also the schema default.
+    const sessionModel = config.model.provider === "cruxy"
+        ? new SessionModel(parseModelChoice(config.model.model) ?? "auto", routerForConfig(config))
+        : undefined;
+    const router = sessionModel;
     // Usage telemetry (C.22): when enabled, each run's usage record is persisted
     // to the LOCAL store. Best-effort and non-fatal — a corrupt/unwritable store
     // is downgraded to a warning (CRUXY_E_USAGE_READ) and NEVER takes a run down.
@@ -159,7 +252,26 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
                 logger.warn(`${error.code}: ${error.title} — ${error.cause}`);
         }
         : undefined;
-    const execRegistry = buildDefaultRegistry();
+    // The `run_tests` side channel (P3): the structured outcome the tool already
+    // built, handed to the renderer to draw. Every field it needs is copied
+    // across as-is — nothing is derived here, so an absent `total` stays absent
+    // rather than becoming a number the parsers refused to claim.
+    const execRegistry = buildDefaultRegistry({
+        onTestResult: renderer
+            ? (result, command) => renderer.testResult({
+                passed: result.passed,
+                command: command.command,
+                durationMs: result.durationMs,
+                ...(result.total !== undefined ? { total: result.total } : {}),
+                failures: result.failures.map((f) => ({
+                    name: f.name,
+                    ...(f.file !== undefined ? { file: f.file } : {}),
+                    ...(f.line !== undefined ? { line: f.line } : {}),
+                })),
+                outputTruncated: result.outputTruncated,
+            })
+            : undefined,
+    });
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
     // Persistent memory (C.29): build the recall block ONCE at session start (the
@@ -233,7 +345,7 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     // because subagents must get the *identical* stack over a FRESH service: same
     // prompt + same checkpoint hook, but a new (empty) session allowlist — a
     // grant in the parent never silently widens a child's authority.
-    const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
+    const io = suspendStatusOnPrompt(promptIOFor(renderer, opts.keyLease), renderer);
     // The C.26 coupling: `checkpointsActive` is true exactly when a per-root gate is
     // wired, and it is set on the SAME ctx whose `requestApproval` IS that gate — so
     // lifting the non-primary-write refusal and capturing the write are one decision.
@@ -251,7 +363,10 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     // here too, so foreground servicing and job production share it.
     const executionSemaphore = new Semaphore(config.subagent.maxConcurrency);
     const approvalQueue = new ApprovalQueue();
-    const gate = (approval) => serializeGate(withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace), approvalMutex, cwd);
+    const gate = (approval) => serializeGate(withCheckpointGate(
+    // Outside `resumeLineAfterApproval`, so the live region is restored
+    // before a preview block is committed into it.
+    previewSilentApprovals(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), renderer), checkpoints, workspace), approvalMutex, cwd);
     // Subagent orchestration (C.14): spawn_subagent goes on the main registry
     // only when depth allows (maxDepth 0 disables the feature structurally).
     // Registered before the plan wiring so plan-mode execution steps can
@@ -270,7 +385,18 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         sandbox,
         checkpointsActive,
         executionSemaphore,
-        makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
+        // A child gets the parent's MODE but not its grants (P5 track 3). The two
+        // are different kinds of thing: a scoped session grant is consent to one
+        // command in one root, and widening it to a child would be authority the
+        // user never gave — whereas auto-approve is a standing instruction about
+        // how this session runs, and a subagent that stopped to ask would strand an
+        // unattended run on a prompt nobody is watching.
+        makeChildApproval: () => gate(new ApprovalService({
+            cwd,
+            interactive: ttyInteractive,
+            io,
+            policy: new InteractivePolicy(new SessionAllowlist(), io, autoApprove),
+        })),
     });
     // Background jobs (C.28): the session-scoped manager the `run_in_background`
     // tool dispatches onto. Built only when enabled. It shares the SAME execution
@@ -312,61 +438,33 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         spawnManyTool,
         jobTool,
     });
-    if (planMode) {
-        // One allowlist shared by the plan-approval prompt and the per-action
-        // gate, so a grant recorded during execution is honored by U.3's own check.
-        const allowlist = new SessionAllowlist();
-        const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
-        const approval = new ApprovalService({
-            cwd,
-            interactive: ttyInteractive,
-            policy: planPolicy,
-            io,
-        });
-        const ctx = {
-            cwd,
-            workspace,
-            config,
-            logger,
-            requestApproval: gate(approval),
-            checkpointsActive,
-            sandbox,
-        };
-        const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, onRequestUsage, }) => runPlanSession({
-            provider,
-            config,
-            ctx,
-            execRegistry,
-            planPolicy,
-            io,
-            interactive: ttyInteractive,
-            messages,
-            git,
-            projectInstructions,
-            recalledMemory: turnMemory,
-            renderer: turnRenderer,
-            router,
-            onRequestUsage,
-        });
-        return new Session({
-            provider,
-            registry: execRegistry,
-            config,
-            ctx,
-            git,
-            projectInstructions,
-            recalledMemory,
-            planMode: true,
-            planRunner,
-            hooks,
-            router,
-            onRunUsage,
-            jobs: jobManager,
-        });
-    }
+    // The plan wiring is built ALWAYS, not only when the session STARTS in a
+    // planning mode (P5 track 3). It used to be gated on `--plan`, and that had a
+    // consequence nobody had written down: `setPlanMode` refuses to engage without
+    // a wired runner, so `/plan` in a session launched without the flag silently
+    // did nothing at all. A mode the user can cycle into at runtime cannot have
+    // its machinery decided at construction.
+    //
+    // Building it unconditionally is behaviour-preserving for a manual session:
+    // `PlanExecutionPolicy` with no safe-step grants enabled is a pass-through to
+    // the interactive policy, and `planRunner` is only ever *called* by a
+    // planning mode.
+    //
+    // One allowlist shared by the plan-approval prompt and the per-action gate, so
+    // a grant recorded during execution is honored by U.3's own check.
+    const allowlist = new SessionAllowlist();
+    // Late-bound to the session constructed below. The policy has to read the LIVE
+    // mode — the user can leave auto-approve between two actions of a single turn
+    // — and the session cannot exist yet because it needs the ctx this policy is
+    // wired into. Before it exists there is nothing to approve, so the `false`
+    // fallback is a closed door rather than a gap.
+    const holder = {};
+    const autoApprove = () => holder.session?.getAutoApprove() ?? false;
+    const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io, autoApprove));
     const approval = new ApprovalService({
         cwd,
         interactive: ttyInteractive,
+        policy: planPolicy,
         io,
     });
     const ctx = {
@@ -378,7 +476,23 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         checkpointsActive,
         sandbox,
     };
-    return new Session({
+    const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, onRequestUsage, }) => runPlanSession({
+        provider,
+        config,
+        ctx,
+        execRegistry,
+        planPolicy,
+        io,
+        interactive: ttyInteractive,
+        messages,
+        git,
+        projectInstructions,
+        recalledMemory: turnMemory,
+        renderer: turnRenderer,
+        router,
+        onRequestUsage,
+    });
+    holder.session = new Session({
         provider,
         registry: execRegistry,
         config,
@@ -386,9 +500,17 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         git,
         projectInstructions,
         recalledMemory,
+        mode,
+        planRunner,
         hooks,
         router,
+        // The same object as `router`, under the handle `/model` mutates. See the
+        // note on `SessionArgs.model`.
+        ...(sessionModel ? { model: sessionModel } : {}),
         onRunUsage,
         jobs: jobManager,
+        recorder: opts.recorder,
+        restore: opts.restore,
     });
+    return holder.session;
 }

package/dist/cli/suggest.js

@@ -0,0 +1,77 @@
+/**
+ * "Did you mean …?" for bare operands (P1 entry).
+ *
+ * Bare `cruxy <token>` is a message — `cruxy refactor`, `cruxy fix`. But a
+ * mistyped subcommand (`cruxy confgi`) arrives in exactly the same shape, and
+ * silently sending it to the model would spend a turn on nonsense. So the
+ * DEFAULT is "message", and only a token that is a near-miss for a real
+ * subcommand is refused.
+ *
+ * Edit distance, not the fuzzy subsequence scorer in `components/fuzzy.ts`:
+ * that scorer answers "does the query appear in order inside the label?", which
+ * is the wrong question here. `confgi` is not a subsequence of `config` (there
+ * is no `i` after the `g`), so the fuzzy path would let the commonest kind of
+ * typo — a transposition — straight through.
+ */
+/**
+ * Levenshtein distance, bounded: returns `max + 1` as soon as the true distance
+ * is known to exceed `max`. The bound matters because the caller only ever asks
+ * "is this within 1 or 2?", and the early exit makes a far-apart pair cheap.
+ */
+export function editDistance(a, b, max = Infinity) {
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    // Single row, rolled forward — the full matrix is never needed.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        let best = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const value = Math.min(prev[j] + 1, // deletion
+            row[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+            row.push(value);
+            if (value < best)
+                best = value;
+        }
+        // Every remaining row can only grow the running minimum, so once the whole
+        // row is past the bound the answer is settled.
+        if (best > max)
+            return max + 1;
+        prev = row;
+    }
+    return prev[b.length];
+}
+/**
+ * How wrong a token may be and still read as a typo rather than a message.
+ *
+ * Short tokens get one edit: at four or five characters, two edits reaches too
+ * many unrelated words, and a short word is far more likely to be a real
+ * instruction (`fix`, `test`, `plan`) than a fumbled command. Six or more
+ * characters gets two, which is what catches a transposition (`confgi` →
+ * `config`, distance 2) without pulling in genuine tasks (`refactor` is 4+ edits
+ * from every command name).
+ */
+export function typoThreshold(length) {
+    return length <= 5 ? 1 : 2;
+}
+/**
+ * The closest subcommand to `token`, or `null` when it is far enough from all of
+ * them to be a message. Ties break on the earlier command in `commands`, which
+ * is registration order — deterministic, never arbitrary.
+ */
+export function suggestCommand(token, commands) {
+    const max = typoThreshold(token.length);
+    let best = null;
+    for (const name of commands) {
+        const distance = editDistance(token.toLowerCase(), name.toLowerCase(), max);
+        if (distance > max)
+            continue;
+        if (best === null || distance < best.distance)
+            best = { name, distance };
+    }
+    return best?.name ?? null;
+}

package/dist/components/fuzzy.js

@@ -1,7 +1,6 @@
 import { fitMiddle } from "../render/layout.js";
 import { resolveTheme } from "../theme/index.js";
-import { createFrame } from "./frame.js";
-import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
+import { componentFrame, defaultComponentIO, resolveNonInteractive, } from "./input.js";
 /** Word-boundary characters that earn the boundary bonus for the NEXT char. */
 const SEPARATORS = new Set(["/", "-", "_", ".", " "]);
 /** Per-character score weights — the entire ranking formula. */
@@ -98,7 +97,8 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
     const t = resolveTheme(io.caps);
     const g = t.glyph;
     const maxVisible = opts.maxVisible ?? 10;
-    const frame = createFrame(io.write, io.caps);
+    // The host's region when there is one (the TUI overlay), else its own.
+    const frame = componentFrame(io);
     let query = "";
     let cursor = 0; // index into the ranked results
     const paint = (ranked) => {

package/dist/components/input.js

@@ -1,5 +1,10 @@
 import { interactiveRequired } from "../errors/index.js";
-import { detectCapabilities } from "../render/index.js";
+// The concrete modules, NOT `render/index.js`: that barrel pulls in
+// `createRenderer`, which imports `tui/renderer.js`, which is where the overlay
+// seam (P5 track 1) lives — and a component importing the TUI that hosts it is
+// a cycle that leaves this module half-initialized at import time.
+import { detectCapabilities } from "../render/capabilities.js";
+import { createFrame } from "./frame.js";
 import { decodeKeys } from "./keys.js";
 /** Build the real reader over `stdin` (or an injected fake in tests). */
 export function createKeyReader(stdin = process.stdin) {
@@ -86,10 +91,12 @@ export async function readSingleKey(stdin = process.stdin) {
 }
 /** The real environment: frames to stderr, keys from stdin, caps from stderr. */
 export function defaultComponentIO() {
+    // Detection resolves both axes (stderr for output, stdin for input) and their
+    // conjunction — so `interactive` is read, not recomputed here.
     const caps = detectCapabilities(process.stderr);
     return {
         caps,
-        interactive: Boolean(process.stdin.isTTY) && caps.cursor,
+        interactive: caps.interactive,
         write: (text) => void process.stderr.write(text),
         keys: createKeyReader(process.stdin),
     };
@@ -109,3 +116,11 @@ export function resolveNonInteractive(io, what, defaultValue, alternatives = [])
     }
     throw interactiveRequired(what, alternatives);
 }
+/**
+ * The transient region a component should draw into: the host's, when one is
+ * offered (the TUI overlay), otherwise its own stderr frame. One line, shared,
+ * so no component has to know which world it is running in.
+ */
+export function componentFrame(io) {
+    return io.makeFrame ? io.makeFrame() : createFrame(io.write, io.caps);
+}

package/dist/components/keys.js

@@ -5,12 +5,19 @@
  */
 const CTRL_C = 0x03;
 const CTRL_D = 0x04;
+const CTRL_K = 0x0b;
 const BACKSPACE = 0x08;
 const TAB = 0x09;
 const LF = 0x0a;
 const CR = 0x0d;
 const ESC = 0x1b;
 const DELETE = 0x7f;
+/**
+ * CSI final byte `Z` — CBT, "cursor backward tabulation". Every terminal that
+ * distinguishes Shift+Tab at all sends this and sends it for nothing else, so
+ * unlike the arrows it is safe to accept with OR without parameters.
+ */
+const CBT = 0x5a;
 /** CSI final byte → arrow key, for `ESC [ <final>` sequences. */
 const ARROWS = {
     0x41: "up", // A
@@ -23,9 +30,9 @@ const ARROWS = {
  * keys per chunk; all are returned in order.
  *
  * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
- * any other CSI sequence (`ESC [ …final`) is swallowed whole (unmapped keys
- * must not leak garbage chars into a query), and a lone ESC decodes to
- * `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * `ESC [ … Z` decodes to Shift+Tab, any other CSI sequence (`ESC [ …final`) is
+ * swallowed whole (unmapped keys must not leak garbage chars into a query), and
+ * a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
  * split across chunks degrades to `escape` + literal chars, which is safe
  * (escape cancels).
  */
@@ -42,6 +49,18 @@ export function decodeKeys(chunk) {
                 while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x3f)
                     j++;
                 if (j < buf.length) {
+                    if (buf[j] === CBT) {
+                        // Shift+Tab, in BOTH its forms: bare `ESC [ Z`, and the
+                        // parameterized `ESC [ 1 ; 2 Z` some terminals send when a modifier
+                        // map is active. The `j === i + 2` guard below deliberately rejects
+                        // parameterized sequences — it exists so a modifier-arrow cannot act
+                        // as a plain arrow — but `Z` has exactly one meaning whatever its
+                        // parameters, so applying that guard here would silently swallow
+                        // half the terminals that can send this key at all.
+                        keys.push({ kind: "shift-tab" });
+                        i = j + 1;
+                        continue;
+                    }
                     // Only a bare `ESC [ <final>` maps to an arrow; parameterized
                     // sequences (modifier arrows, Home/End variants) are swallowed —
                     // an unmapped combo must do nothing, not act as a plain arrow.
@@ -88,6 +107,11 @@ export function decodeKeys(chunk) {
             i++;
             continue;
         }
+        if (byte === CTRL_K) {
+            keys.push({ kind: "ctrl-k" });
+            i++;
+            continue;
+        }
         if (byte < 0x20) {
             // Other control chars: ignore (same rule as the secret reader).
             i++;

package/dist/components/select.js

@@ -1,7 +1,6 @@
 import { fitMiddle } from "../render/layout.js";
 import { resolveTheme } from "../theme/index.js";
-import { createFrame } from "./frame.js";
-import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
+import { componentFrame, defaultComponentIO, resolveNonInteractive, } from "./input.js";
 /**
  * Pick one item: ↑/↓ move (wrapping past either end), Enter selects the
  * highlighted item, Esc / Ctrl-C / EOF cancel. Renders a transient frame via
@@ -19,7 +18,8 @@ export async function selectList(items, opts = {}, io = defaultComponentIO()) {
     const t = resolveTheme(io.caps);
     const g = t.glyph;
     const maxVisible = opts.maxVisible ?? 10;
-    const frame = createFrame(io.write, io.caps);
+    // The host's region when there is one (the TUI overlay), else its own.
+    const frame = componentFrame(io);
     let cursor = Math.min(Math.max(opts.initialIndex ?? 0, 0), items.length - 1);
     const paint = () => {
         const lines = [];