@vincemakes/kiso-tui 0.5.0 → 0.7.0

package/dist/at-picker.d.ts

@@ -0,0 +1,159 @@
+/**
+ * KC3 §3 — the @ file picker's PURE half: the subsequence filter and
+ * the deterministic rank. No scoring library, no index, no disk. The
+ * file list is DATA the CLI feeds in (the tui purity rule: input is
+ * data, output is bytes); this module decides which of those paths a
+ * query matches, in what order, and which characters to embolden.
+ *
+ * Determinism is the whole design constraint. A fuzzy finder that
+ * reorders on a tie is unusable at speed — the row under the cursor
+ * must not move because two paths scored equal. Every comparison here
+ * ends in a total order: run length, then path length, then the raw
+ * lexical order of the path (never localeCompare, whose result depends
+ * on the machine's locale).
+ */
+/** The bound source's item — a repo-relative path and nothing else.
+ *  Structural: the CLI passes whatever it likes as long as it has a
+ *  path (slice 5 passes exactly this). */
+export interface AtItem {
+    readonly path: string;
+}
+/** A matched path plus the indices the panel emboldens. */
+export interface AtMatch {
+    readonly path: string;
+    /** the matched character positions, ascending — the panel renders
+     *  these bold-white and the rest dim */
+    readonly hit: readonly number[];
+    /** the longest CONTIGUOUS run inside `hit` — the rank's first key,
+     *  carried so the panel and the ranking can never disagree about
+     *  why a row is where it is */
+    readonly run: number;
+}
+/**
+ * KC3 §5 — the ONE cap. The file list is computed per open with no
+ * index and no watcher, so its cost is bounded here rather than
+ * amortized somewhere invisible. The source collects at most CAP + 1
+ * entries: the extra one is what makes "there were more" DISTINGUISHABLE
+ * from "there were exactly this many", so the counter row can say so
+ * honestly instead of guessing.
+ */
+export declare const AT_CAP = 2000;
+/**
+ * KC3 §5 — the directories the picker never offers, and the other half
+ * of its contract with whatever host has to walk a tree to fill it.
+ *
+ * It lives here beside the cap because the two are the same kind of
+ * promise: a host that walks must prune these BEFORE descending (a
+ * post-filter would already have walked node_modules, which is the
+ * cost the pruning exists to avoid), and must stop at the cap. Hosts
+ * that get their list from a VCS ignore this set entirely — the VCS
+ * has already applied a better one.
+ */
+export declare const AT_SKIP: ReadonlySet<string>;
+/** KC3 §4 — the panel's visible height. A ceiling, not a promise: the
+ *  compositor clamps further when the terminal is short. */
+export declare const AT_VISIBLE = 5;
+/**
+ * The subsequence embedding, TIGHTENED — the two-pass walk every good
+ * fuzzy finder uses, and the reason `@ra` emboldens the "ra" of
+ * "src/range.js" rather than the r of "src" and the a of "range".
+ *
+ * Pass 1 walks forward and stops at the EARLIEST index that completes
+ * the query — this both answers "does it match at all" and fixes the
+ * right-hand edge. Pass 2 walks backward from that edge, taking the
+ * LATEST position for each query character in turn, which slides every
+ * matched character as far right as it can go without crossing the
+ * next one. The result is the most clustered embedding that ends where
+ * the earliest match ends.
+ *
+ * Case-insensitive: both sides are lowercased by the caller once per
+ * query rather than once per character.
+ *
+ * Returns the ascending match indices, or null when the query is not a
+ * subsequence of the path at all.
+ */
+export declare function atEmbed(lowerPath: string, lowerQuery: string): number[] | null;
+/** The longest run of CONSECUTIVE indices in an ascending list. An
+ *  empty query has no run — every path ties on it, and the rank falls
+ *  through to path length. */
+export declare function longestRun(hit: readonly number[]): number;
+/**
+ * The filter + the rank. Case-insensitive SUBSEQUENCE over the FULL
+ * relative path (so `@tui/ed` finds packages/tui/src/editor.ts — the
+ * directory is part of what the user is typing at, not a separate
+ * field), ordered by:
+ *
+ *   1. contiguous-run length DESC — a path where the query appears as
+ *      a solid stretch beats one where it is scattered across the
+ *      whole string. This is the key that makes typing feel like
+ *      aiming rather than fishing.
+ *   2. path length ASC — among equally solid hits, the shorter path is
+ *      the more likely target (src/range.js over a deep vendored copy
+ *      of the same name).
+ *   3. the path itself, lexically — the tiebreak of last resort, and
+ *      the reason the order NEVER depends on the source's iteration
+ *      order or on two runs of the same query disagreeing.
+ *
+ * An EMPTY query matches everything: rule 1 ties at 0 for all, so the
+ * listing is shortest-path-first, then lexical. The list is sliced to
+ * AT_CAP; `capped` reports whether anything was dropped.
+ */
+export declare function atFilter(items: readonly AtItem[], query: string): {
+    matches: AtMatch[];
+    capped: boolean;
+};
+/**
+ * KC3 §4 — the picker's WINDOW: which slice of the ranked list is on
+ * screen. The window TRAILS the selection exactly as the composer's
+ * own viewport trails the cursor (KC1 §5) — derived per read, never
+ * stored, so it can never disagree with the selection it is meant to
+ * follow.
+ */
+export declare function atWindow(total: number, selected: number, visible?: number): {
+    first: number;
+    count: number;
+};
+/**
+ * KC3 §4 — ONE row of the panel.
+ *
+ * Two columns: the file's NAME on the left with its matched characters
+ * bold, and the DIRECTORY dim on the right, pushed to the far edge.
+ * The name is what the user is aiming at; the directory is what tells
+ * two same-named files apart, which is why it is present but quiet.
+ *
+ * The selected row carries `→` on the inverse band (SGR 7, closed with
+ * 27 — never SGR 0, so it composes inside the row's own spans).
+ *
+ * The `hit` indices are over the FULL path, so they are shifted by the
+ * directory's length to land on the name. A hit that falls INSIDE the
+ * directory is simply not drawn bold — the directory column is
+ * uniformly dim by design (a bold fragment in a right-aligned dim
+ * column reads as damage, not as information).
+ *
+ * The row never exceeds W: the name cuts first (it is the flexible
+ * column), and the directory is dropped entirely before the name is
+ * cut to nothing.
+ */
+export declare function atRow(match: AtMatch, selected: boolean, W: number): string;
+/**
+ * KC3 §4 — the counter row: `(n/total)`, where n is the 1-based
+ * position of the SELECTION in the whole ranked list, not in the
+ * visible window. The user needs to know where they are in the list,
+ * which the five visible rows cannot tell them.
+ *
+ * When the source list was truncated the row SAYS SO. A file picker
+ * that quietly lists 2,000 of 40,000 files and shows a confident
+ * "(3/1998)" is lying by omission; this one admits the horizon.
+ */
+export declare function atCounterRow(selected: number, total: number, capped: boolean, W: number): string;
+/**
+ * KC3 §4 — the whole band: at most AT_VISIBLE windowed rows, then the
+ * counter. Returned as plain strings for the menu-rows channel, which
+ * already accounts them in chromeRows — the picker needs no geometry
+ * of its own, which is the entire reason it rides that channel.
+ */
+export declare function atPanelRows(state: {
+    matches: readonly AtMatch[];
+    selected: number;
+    capped: boolean;
+}, W: number): string[];

package/dist/at-picker.js

@@ -0,0 +1,228 @@
+/**
+ * KC3 §3 — the @ file picker's PURE half: the subsequence filter and
+ * the deterministic rank. No scoring library, no index, no disk. The
+ * file list is DATA the CLI feeds in (the tui purity rule: input is
+ * data, output is bytes); this module decides which of those paths a
+ * query matches, in what order, and which characters to embolden.
+ *
+ * Determinism is the whole design constraint. A fuzzy finder that
+ * reorders on a tie is unusable at speed — the row under the cursor
+ * must not move because two paths scored equal. Every comparison here
+ * ends in a total order: run length, then path length, then the raw
+ * lexical order of the path (never localeCompare, whose result depends
+ * on the machine's locale).
+ */
+import { escapeTerminal, palette } from "./render.js";
+import { visibleWidth, widthCut } from "./components.js";
+/**
+ * KC3 §5 — the ONE cap. The file list is computed per open with no
+ * index and no watcher, so its cost is bounded here rather than
+ * amortized somewhere invisible. The source collects at most CAP + 1
+ * entries: the extra one is what makes "there were more" DISTINGUISHABLE
+ * from "there were exactly this many", so the counter row can say so
+ * honestly instead of guessing.
+ */
+export const AT_CAP = 2000;
+/**
+ * KC3 §5 — the directories the picker never offers, and the other half
+ * of its contract with whatever host has to walk a tree to fill it.
+ *
+ * It lives here beside the cap because the two are the same kind of
+ * promise: a host that walks must prune these BEFORE descending (a
+ * post-filter would already have walked node_modules, which is the
+ * cost the pruning exists to avoid), and must stop at the cap. Hosts
+ * that get their list from a VCS ignore this set entirely — the VCS
+ * has already applied a better one.
+ */
+export const AT_SKIP = new Set([".git", "node_modules", "dist", "build", "coverage"]);
+/** KC3 §4 — the panel's visible height. A ceiling, not a promise: the
+ *  compositor clamps further when the terminal is short. */
+export const AT_VISIBLE = 5;
+/**
+ * The subsequence embedding, TIGHTENED — the two-pass walk every good
+ * fuzzy finder uses, and the reason `@ra` emboldens the "ra" of
+ * "src/range.js" rather than the r of "src" and the a of "range".
+ *
+ * Pass 1 walks forward and stops at the EARLIEST index that completes
+ * the query — this both answers "does it match at all" and fixes the
+ * right-hand edge. Pass 2 walks backward from that edge, taking the
+ * LATEST position for each query character in turn, which slides every
+ * matched character as far right as it can go without crossing the
+ * next one. The result is the most clustered embedding that ends where
+ * the earliest match ends.
+ *
+ * Case-insensitive: both sides are lowercased by the caller once per
+ * query rather than once per character.
+ *
+ * Returns the ascending match indices, or null when the query is not a
+ * subsequence of the path at all.
+ */
+export function atEmbed(lowerPath, lowerQuery) {
+    if (lowerQuery === "")
+        return [];
+    // pass 1 — forward, to the earliest completing index
+    let qi = 0;
+    let end = -1;
+    for (let pi = 0; pi < lowerPath.length; pi += 1) {
+        if (lowerPath[pi] === lowerQuery[qi]) {
+            qi += 1;
+            if (qi === lowerQuery.length) {
+                end = pi;
+                break;
+            }
+        }
+    }
+    if (end === -1)
+        return null; // not a subsequence — no embedding exists
+    // pass 2 — backward from that edge, sliding each character right
+    const hit = new Array(lowerQuery.length);
+    let pi = end;
+    for (let j = lowerQuery.length - 1; j >= 0; j -= 1) {
+        while (lowerPath[pi] !== lowerQuery[j])
+            pi -= 1;
+        hit[j] = pi;
+        pi -= 1;
+    }
+    return hit;
+}
+/** The longest run of CONSECUTIVE indices in an ascending list. An
+ *  empty query has no run — every path ties on it, and the rank falls
+ *  through to path length. */
+export function longestRun(hit) {
+    let best = 0;
+    let run = 0;
+    for (let i = 0; i < hit.length; i += 1) {
+        run = i > 0 && hit[i] === hit[i - 1] + 1 ? run + 1 : 1;
+        if (run > best)
+            best = run;
+    }
+    return best;
+}
+/**
+ * The filter + the rank. Case-insensitive SUBSEQUENCE over the FULL
+ * relative path (so `@tui/ed` finds packages/tui/src/editor.ts — the
+ * directory is part of what the user is typing at, not a separate
+ * field), ordered by:
+ *
+ *   1. contiguous-run length DESC — a path where the query appears as
+ *      a solid stretch beats one where it is scattered across the
+ *      whole string. This is the key that makes typing feel like
+ *      aiming rather than fishing.
+ *   2. path length ASC — among equally solid hits, the shorter path is
+ *      the more likely target (src/range.js over a deep vendored copy
+ *      of the same name).
+ *   3. the path itself, lexically — the tiebreak of last resort, and
+ *      the reason the order NEVER depends on the source's iteration
+ *      order or on two runs of the same query disagreeing.
+ *
+ * An EMPTY query matches everything: rule 1 ties at 0 for all, so the
+ * listing is shortest-path-first, then lexical. The list is sliced to
+ * AT_CAP; `capped` reports whether anything was dropped.
+ */
+export function atFilter(items, query) {
+    const capped = items.length > AT_CAP;
+    const pool = capped ? items.slice(0, AT_CAP) : items;
+    const lowerQuery = query.toLowerCase();
+    const matches = [];
+    for (const item of pool) {
+        const hit = atEmbed(item.path.toLowerCase(), lowerQuery);
+        if (hit === null)
+            continue;
+        matches.push({ path: item.path, hit, run: longestRun(hit) });
+    }
+    matches.sort((a, b) => {
+        if (a.run !== b.run)
+            return b.run - a.run;
+        if (a.path.length !== b.path.length)
+            return a.path.length - b.path.length;
+        return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+    });
+    return { matches, capped };
+}
+/**
+ * KC3 §4 — the picker's WINDOW: which slice of the ranked list is on
+ * screen. The window TRAILS the selection exactly as the composer's
+ * own viewport trails the cursor (KC1 §5) — derived per read, never
+ * stored, so it can never disagree with the selection it is meant to
+ * follow.
+ */
+export function atWindow(total, selected, visible = AT_VISIBLE) {
+    const count = Math.min(total, visible);
+    const first = Math.max(0, Math.min(selected - count + 1, total - count));
+    return { first, count };
+}
+/** The path split into the two columns the panel draws: the file's own
+ *  name, and the directory that qualifies it. A path with no slash is
+ *  all name and no directory. */
+function splitPath(path) {
+    const cut = path.lastIndexOf("/");
+    return cut === -1 ? { dir: "", name: path } : { dir: path.slice(0, cut + 1), name: path.slice(cut + 1) };
+}
+/**
+ * KC3 §4 — ONE row of the panel.
+ *
+ * Two columns: the file's NAME on the left with its matched characters
+ * bold, and the DIRECTORY dim on the right, pushed to the far edge.
+ * The name is what the user is aiming at; the directory is what tells
+ * two same-named files apart, which is why it is present but quiet.
+ *
+ * The selected row carries `→` on the inverse band (SGR 7, closed with
+ * 27 — never SGR 0, so it composes inside the row's own spans).
+ *
+ * The `hit` indices are over the FULL path, so they are shifted by the
+ * directory's length to land on the name. A hit that falls INSIDE the
+ * directory is simply not drawn bold — the directory column is
+ * uniformly dim by design (a bold fragment in a right-aligned dim
+ * column reads as damage, not as information).
+ *
+ * The row never exceeds W: the name cuts first (it is the flexible
+ * column), and the directory is dropped entirely before the name is
+ * cut to nothing.
+ */
+export function atRow(match, selected, W) {
+    const p = palette();
+    const { dir, name } = splitPath(escapeTerminal(match.path));
+    const lead = selected ? `${p.rv}→ ${p.rvEnd}` : "  ";
+    // the name's own matched positions, mapped out of the full path
+    const marks = new Set(match.hit.filter((i) => i >= dir.length).map((i) => i - dir.length));
+    // room: W − the 2-cell lead − 1 separating space before the directory
+    const nameRoom = Math.max(1, W - 2 - (dir === "" ? 0 : visibleWidth(dir) + 1));
+    const shownName = widthCut(name, nameRoom);
+    let painted = "";
+    for (let i = 0; i < shownName.length; i += 1) {
+        painted += marks.has(i) ? `${p.bold}${shownName[i]}${p.reset}` : shownName[i];
+    }
+    if (dir === "")
+        return `${lead}${painted}`;
+    const pad = Math.max(1, W - 2 - visibleWidth(shownName) - visibleWidth(dir));
+    return `${lead}${painted}${" ".repeat(pad)}${p.dim}${dir}${p.reset}`;
+}
+/**
+ * KC3 §4 — the counter row: `(n/total)`, where n is the 1-based
+ * position of the SELECTION in the whole ranked list, not in the
+ * visible window. The user needs to know where they are in the list,
+ * which the five visible rows cannot tell them.
+ *
+ * When the source list was truncated the row SAYS SO. A file picker
+ * that quietly lists 2,000 of 40,000 files and shows a confident
+ * "(3/1998)" is lying by omission; this one admits the horizon.
+ */
+export function atCounterRow(selected, total, capped, W) {
+    const p = palette();
+    const text = capped ? `  (${selected + 1}/${total}) · first ${AT_CAP} files only` : `  (${selected + 1}/${total})`;
+    return `${p.dim}${widthCut(text, W)}${p.reset}`;
+}
+/**
+ * KC3 §4 — the whole band: at most AT_VISIBLE windowed rows, then the
+ * counter. Returned as plain strings for the menu-rows channel, which
+ * already accounts them in chromeRows — the picker needs no geometry
+ * of its own, which is the entire reason it rides that channel.
+ */
+export function atPanelRows(state, W) {
+    const { first, count } = atWindow(state.matches.length, state.selected);
+    const rows = [];
+    for (let i = first; i < first + count; i += 1)
+        rows.push(atRow(state.matches[i], i === state.selected, W));
+    rows.push(atCounterRow(state.selected, state.matches.length, state.capped, W));
+    return rows;
+}

package/dist/compositor.d.ts

@@ -44,6 +44,13 @@
  */
 import { type MenuItem } from "./editor.js";
 import { type PanelState } from "./approval-panel.js";
+import { type AtMatch } from "./at-picker.js";
+/** KC3 §4 — the @ picker's bound state (the editor's atState()). */
+export interface AtPanelState {
+    readonly matches: readonly AtMatch[];
+    readonly selected: number;
+    readonly capped: boolean;
+}
 import { type ResumeMeta } from "./render.js";
 /** The cursor marker — an APC private sequence the focus component
  *  embeds at the edit position; the compositor strips it and moves
@@ -205,6 +212,10 @@ export declare class Body {
         items: readonly MenuItem[];
         selected: number;
     } | null): void;
+    /** KC3 §4: bind the editor's @ file picker. It shares the menu's
+     *  band — see #menuRows for why that is a decision and not a
+     *  shortcut. */
+    bindAt(state: () => AtPanelState | null): void;
     /** Bind the pending-turn queue — the CLI's live slots (chat.ts):
      *  the chips render in the menu-rows family, the live caps shrink
      *  by their rows, and the +N queued hint rides the status row. */
@@ -246,6 +257,10 @@ export declare class Dock {
         items: readonly MenuItem[];
         selected: number;
     } | null): void;
+    /** KC3 §4: bind the editor's @ picker — the SAME band as the slash
+     *  menu (see Body#menuRows). Unbound, the picker cannot render, and
+     *  every frame is byte-identical to before the round. */
+    bindAt(state: () => AtPanelState | null): void;
     /** W22: bind the pending-turn queue — the chips + the +N queued
      *  hint (the CLI binds it from chat(); the editor's pop keys ride
      *  the LineInput's own bindQueue). */

package/dist/compositor.js

@@ -46,6 +46,7 @@ import { truncateDiff } from "./diff.js";
 import { displayWidth } from "./editor.js";
 import { leadWidth } from "./width.js"; // W23: the ONE width authority (the editor, #inputRow, and editCol share it)
 import { panelAffordance, panelBlockRows, panelLead, panelStatus } from "./approval-panel.js";
+import { atPanelRows } from "./at-picker.js";
 import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, foldLine, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
 import { bannerLines, escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, toolTarget } from "./render.js";
 /** The cursor marker — an APC private sequence the focus component
@@ -118,6 +119,9 @@ export class Body {
     #inputState = () => ({ line: "", cursor: 0 });
     #inputPrompt = "";
     #menuState = null;
+    // KC3 §4: the @ picker's bound state — the SAME band as the menu
+    // (see #menuRows: the two are mutually exclusive by construction).
+    #atState = null;
     // W22: the pending-turn queue's bound state — the CLI's live slots
     // (chat.ts); the chips render in the menu-rows family (above the
     // box top), the live caps shrink by their rows, and the status
@@ -144,6 +148,8 @@ export class Body {
         this.#inputPrompt = dockBindings.prompt;
         if (dockBindings.menu !== null)
             this.#menuState = dockBindings.menu;
+        if (dockBindings.at !== null)
+            this.#atState = dockBindings.at;
         this.#panelState = dockBindings.panel;
         if (dockBindings.queue !== null)
             this.#queueState = dockBindings.queue;
@@ -675,6 +681,12 @@ export class Body {
     bindMenu(state) {
         this.#menuState = state;
     }
+    /** KC3 §4: bind the editor's @ file picker. It shares the menu's
+     *  band — see #menuRows for why that is a decision and not a
+     *  shortcut. */
+    bindAt(state) {
+        this.#atState = state;
+    }
     /** Bind the pending-turn queue — the CLI's live slots (chat.ts):
      *  the chips render in the menu-rows family, the live caps shrink
      *  by their rows, and the +N queued hint rides the status row. */
@@ -1098,7 +1110,24 @@ export class Body {
         const hidden = lines.length - keep;
         return [...pendingQueueRows(lines.slice(0, keep), W), `${p.dim}□ …${hidden} more queued${p.reset}`];
     }
+    /**
+     * The band ABOVE the box top. Two occupants share it — the slash
+     * menu and (KC3 §4) the @ file picker.
+     *
+     * Sharing is the design, not an economy. This band is already
+     * counted in chromeRows, already shrinks the live content cap,
+     * already redraws with the frame, and already clamps the composer's
+     * visible rows; a picker with a band of its own would have to
+     * re-derive every one of those and could disagree with any of them.
+     * The two occupants are mutually exclusive BY CONSTRUCTION — the
+     * editor's precedence gate keeps the picker shut whenever the menu
+     * is open — so one function can own the band without either
+     * occupant knowing the other exists.
+     */
     #menuRows(W) {
+        const at = this.#atState?.() ?? null;
+        if (at !== null)
+            return atPanelRows(at, W);
         const menu = this.#menuState?.();
         if (menu === null || menu === undefined || menu.items.length === 0)
             return [];
@@ -1589,6 +1618,16 @@ export class Dock {
         }
         compositorRef.bindMenu(state);
     }
+    /** KC3 §4: bind the editor's @ picker — the SAME band as the slash
+     *  menu (see Body#menuRows). Unbound, the picker cannot render, and
+     *  every frame is byte-identical to before the round. */
+    bindAt(state) {
+        if (compositorRef === null) {
+            dockBindings.at = state;
+            return;
+        }
+        compositorRef.bindAt(state);
+    }
     /** W22: bind the pending-turn queue — the chips + the +N queued
      *  hint (the CLI binds it from chat(); the editor's pop keys ride
      *  the LineInput's own bindQueue). */
@@ -1614,4 +1653,4 @@ let compositorRef = null;
  *  — the old snapshot froze `menu` at bindInput time and the slash-
  *  command menu silently never bound in the real CLI (the e2e gates
  *  bind the Body directly and could not see it). */
-const dockBindings = { state: null, prompt: "", menu: null, panel: null, queue: null };
+const dockBindings = { state: null, prompt: "", menu: null, at: null, panel: null, queue: null };

package/dist/editor.d.ts

@@ -24,6 +24,7 @@
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
 import { type PanelState, type PanelVerdict, type PanelView } from "./approval-panel.js";
+import { type AtItem, type AtMatch } from "./at-picker.js";
 export declare const PROMPT = "\u258C ";
 export declare const PROMPT_WIDTH: number;
 /** v3 §04 — the slash-command menu's command table (English one-liners). */
@@ -48,6 +49,11 @@ export declare class Editor {
     onEot(cb: () => void): void;
     onEscape(cb: () => void): void;
     onExpand(cb: () => void): void;
+    /** KC2 §2: the redirect chain — the gesture hands the buffer's text
+     *  over while the run is told to stop. Mirrors onEscape (a list, so
+     *  listeners can coexist); the line arrives already gone from the
+     *  composer, exactly as a submit's does. */
+    onRedirect(cb: (line: string) => void): void;
     /** W22: bind the pending-turn queue — the CLI's live slots. The ↑
      *  pop walks them (each pop leaves the queue, cancelling the turn);
      *  esc ends the walk after one more pop. */
@@ -78,6 +84,20 @@ export declare class Editor {
         items: readonly MenuItem[];
         selected: number;
     } | null;
+    /** KC3 §3 — bind the file source. The tui owns no file list and
+     *  never touches a disk (input is data, output is bytes): the CLI
+     *  feeds the paths, and until it does, the picker cannot open at
+     *  all — which is exactly why every non-@ scenario and every
+     *  consumer that does not bind (the recovery flow, the existing
+     *  gates) is byte-identical. */
+    bindAtItems(source: () => readonly AtItem[]): void;
+    /** KC3 §4 — the picker's visible state for the dock; null when
+     *  closed. The compositor windows it and draws the counter. */
+    atState(): {
+        matches: readonly AtMatch[];
+        selected: number;
+        capped: boolean;
+    } | null;
     /** One-shot question mode: the NEXT submit answers, not a turn. */
     question(_query: string, cb: (answer: string) => void): void;
     /** Cancel a pending question — the buffer stays (its text becomes the

package/dist/editor.js

@@ -27,6 +27,7 @@ import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
 import { palette } from "./render.js";
 import { panelLead } from "./approval-panel.js";
+import { AT_VISIBLE, atFilter } from "./at-picker.js";
 // TUI v4 #16d: the input row is the blue brick + the edit area — the
 // "you>" text is gone (the brick IS the prompt; the pipe path's readline
 // prompt keeps its own "you> " — v2a line mode, byte-for-byte).
@@ -44,6 +45,13 @@ export const MENU_ITEMS = [
 /** KC1 §3 — the newline code point. Every source (paste, Ctrl+J, the
  *  Shift+Enter encodings, a CRLF pair) normalizes to exactly ONE. */
 const NEWLINE = 0x0a;
+/** KC3 §3 — the picker's sigil, and the two characters that count as a
+ *  word boundary before it. A `@` anywhere else (vince@example.com) is
+ *  an ordinary character: the reference is a thing you START, not a
+ *  thing an address accidentally becomes. */
+const AT = 0x40;
+const SPACE = 0x20;
+const TAB = 0x09;
 /** KC1 §5 — the composer's CEILING (adjudication A1): at most 6 visible
  *  rows. A ceiling only — N_visible clamps by the terminal's height so
  *  the geometry stays legal down to the compositor's enter gate (H = 4
@@ -87,6 +95,12 @@ export class Editor {
     // (dispatch) coexist; a listener removes itself via an unarmed guard
     // (the compact's handler no-ops after its abort has fired).
     #escapeCbs = [];
+    // KC2 §2: the redirect LIST — mirrors #escapeCbs. The editor FORWARDS
+    // the gesture with the buffer's text; it never interprets it. What a
+    // redirect MEANS (abort the run, then run THIS ahead of the queue) is
+    // the CLI's — here it is only "these two keys, pressed together, hand
+    // the line over by a different door than Enter's".
+    #redirectCbs = [];
     // W15: the expand-key list (ctrl+r) — the CLI's dispatch decides the
     // target (a live cell toggles in place; a committed cell appends the
     // expanded block). Mirrors the escape list: multiple listeners can
@@ -95,6 +109,22 @@ export class Editor {
     #onRender;
     #menuOpen = false; // v3 §04: the slash-command menu
     #menuSel = 0;
+    // KC3 §3 — the @ file picker. THREE fields and no more: the armed
+    // bit, the selection, and the per-open SNAPSHOT of the file list.
+    // The query is deliberately NOT stored — it is derived from the
+    // buffer and the cursor on every read (the KC1 flat-buffer
+    // discipline: never a second mutable model). That is what makes
+    // backspacing past the `@` close the picker with no handler
+    // anywhere, and what keeps every existing op — the kills, paste,
+    // the history stash, the queue-pop replace — correct for free.
+    #atOpen = false;
+    #atSel = 0;
+    // the list is snapshotted AT OPEN and held for that open's lifetime
+    // (§4: no index, no watcher, no re-listing per keystroke). An armed
+    // bit with no token under the cursor is inert by construction — the
+    // next open re-snapshots, so a stale list can never be shown.
+    #atList = null;
+    #atItems = null;
     // A2 (the feel): the session-scoped input history — every submitted TURN
     // line (never a question answer), capped at 100, never persisted. ↑↓
     // navigate it ONLY from an empty input or while already browsing.
@@ -144,6 +174,13 @@ export class Editor {
     onExpand(cb) {
         this.#expandCbs.push(cb);
     }
+    /** KC2 §2: the redirect chain — the gesture hands the buffer's text
+     *  over while the run is told to stop. Mirrors onEscape (a list, so
+     *  listeners can coexist); the line arrives already gone from the
+     *  composer, exactly as a submit's does. */
+    onRedirect(cb) {
+        this.#redirectCbs.push(cb);
+    }
     /** W22: bind the pending-turn queue — the CLI's live slots. The ↑
      *  pop walks them (each pop leaves the queue, cancelling the turn);
      *  esc ends the walk after one more pop. */
@@ -202,7 +239,7 @@ export class Editor {
      *  the frame's clamp is the authority. */
     #visibleRows(lineCount) {
         const H = process.stdout.rows ?? 24;
-        const bands = (this.#menuOpen ? this.#menuFiltered().length : 0) + this.#queueState().length;
+        const bands = (this.#menuOpen ? this.#menuFiltered().length : 0) + this.#atRows() + this.#queueState().length;
         return Math.max(1, Math.min(lineCount, N_MAX, Math.max(1, H - 3 - bands)));
     }
     /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
@@ -263,6 +300,128 @@ export class Editor {
             this.#menuSel = 0;
         this.#onRender();
     }
+    /** KC3 §3 — bind the file source. The tui owns no file list and
+     *  never touches a disk (input is data, output is bytes): the CLI
+     *  feeds the paths, and until it does, the picker cannot open at
+     *  all — which is exactly why every non-@ scenario and every
+     *  consumer that does not bind (the recovery flow, the existing
+     *  gates) is byte-identical. */
+    bindAtItems(source) {
+        this.#atItems = source;
+    }
+    /**
+     * KC3 §3 — the token under the cursor, DERIVED. Scans back from the
+     * cursor within the CURSOR'S LINE for the `@` that opens it:
+     *  - whitespace before finding one → there is no token (the space
+     *    ended it);
+     *  - an `@` that is not itself at a word boundary → inert (the
+     *    email case: the `@` of vince@example.com opens nothing);
+     *  - otherwise the token runs from that `@` to the CURSOR — never
+     *    to the end of the line, so `@ra|.js` narrows on "ra".
+     * Line-local: the start of any line of a multi-line composer is a
+     * boundary, exactly like the start of the buffer.
+     */
+    #atToken() {
+        const b = this.#cursorBounds();
+        for (let i = this.#cursor - 1; i >= b.start; i -= 1) {
+            const cp = this.#chars[i];
+            if (cp === SPACE || cp === TAB)
+                return null;
+            if (cp !== AT)
+                continue;
+            const before = i > b.start ? this.#chars[i - 1] : null;
+            if (before !== null && before !== SPACE && before !== TAB)
+                return null; // mid-word
+            return { start: i, query: String.fromCodePoint(...this.#chars.slice(i + 1, this.#cursor)) };
+        }
+        return null;
+    }
+    /** KC3 §3 — the picker's full state, or null when it is not up. Up
+     *  requires ALL of: armed, nobody with higher precedence holding the
+     *  keys, a live token under the cursor, and at least one match (the
+     *  menu's precedent — a panel with nothing in it is noise, and the
+     *  keys fall back to their ordinary meanings). */
+    #atView() {
+        if (!this.#atOpen || this.#atList === null)
+            return null;
+        if (this.#panel !== null || this.#menuOpen)
+            return null;
+        const token = this.#atToken();
+        if (token === null)
+            return null;
+        const { matches, capped } = atFilter(this.#atList, token.query);
+        if (matches.length === 0)
+            return null;
+        // the selection CLAMPS at read time rather than being corrected
+        // on every edit — narrowing the query can only ever shrink the
+        // list, and a clamp is the whole correction that needs
+        return { matches, selected: Math.min(this.#atSel, matches.length - 1), capped, start: token.start };
+    }
+    #atUp() {
+        return this.#atView() !== null;
+    }
+    /** KC3 §4 — the picker's visible state for the dock; null when
+     *  closed. The compositor windows it and draws the counter. */
+    atState() {
+        const view = this.#atView();
+        if (view === null)
+            return null;
+        return { matches: view.matches, selected: view.selected, capped: view.capped };
+    }
+    /** KC3 §3 — arm the picker at a freshly typed `@`. The gate is the
+     *  KC2 precedence pattern: the approval panel, the slash menu and a
+     *  pending question each own the keys first. A paste is literal text
+     *  (guarded by the caller). The history browse and the queue-pop
+     *  walk are NOT re-tested here because typing has already ended them
+     *  — #insert leaves both before a character ever lands. */
+    #atArm() {
+        if (this.#atItems === null)
+            return;
+        if (this.#panel !== null || this.#menuOpen || this.#questionCb !== null)
+            return;
+        if (this.#atToken() === null)
+            return; // not at a word boundary
+        this.#atOpen = true;
+        this.#atSel = 0;
+        this.#atList = this.#atItems(); // §5: listed per OPEN, never per keystroke
+    }
+    #atClose() {
+        this.#atOpen = false;
+        this.#atSel = 0;
+        this.#atList = null;
+    }
+    /**
+     * KC3 §3 — accept: the token becomes `@<path> `.
+     *
+     * The CANONICAL PATH and a trailing space, and nothing else — the
+     * file's CONTENT is never inserted. That is the whole product
+     * decision: the model is handed a reference it can choose to read,
+     * so an @ mention costs a path's worth of tokens instead of a
+     * file's, and the model's own read_file call is what pays for the
+     * bytes it actually needs.
+     *
+     * Only [token.start, cursor) is replaced, so text after the cursor
+     * survives and a multi-line buffer keeps every other line.
+     */
+    #atAccept() {
+        const view = this.#atView();
+        if (view === null)
+            return;
+        const insert = [...`@${view.matches[view.selected].path} `].map((ch) => ch.codePointAt(0));
+        this.#chars.splice(view.start, this.#cursor - view.start, ...insert);
+        this.#cursor = view.start + insert.length;
+        this.#atClose();
+        this.#reflow();
+        this.#onRender();
+    }
+    /** KC3 §4 — the picker's band height, the editor's honest estimate
+     *  (the compositor re-applies the clamp against the frame's REAL
+     *  folded rows, exactly as it does for the menu): the windowed rows
+     *  plus the counter row. */
+    #atRows() {
+        const view = this.#atView();
+        return view === null ? 0 : Math.min(view.matches.length, AT_VISIBLE) + 1;
+    }
     /** One-shot question mode: the NEXT submit answers, not a turn. */
     question(_query, cb) {
         this.#questionCb = cb;
@@ -291,6 +450,7 @@ export class Editor {
         this.#menuOpen = false;
         this.#menuSel = 0;
         this.#queuePopMode = false; // W22: the panel owns the keys while up
+        this.#atClose(); // KC3 §3: and the picker closes with everything else
         this.#onRender();
     }
     /** W21: cancel the panel — the SIGINT path's pair to beginPanel. */
@@ -408,6 +568,17 @@ export class Editor {
                 else if (rest.startsWith("O")) {
                     i += 3; // SS3 (function keys) — ignored
                 }
+                else if (rest.startsWith("\x0d") && this.#composerIdle()) {
+                    // KC2 §2 — Alt+Enter. A terminal sends Alt+X as ESC and X in
+                    // ONE write, so SAME-CHUNK is the whole test: no timer, no
+                    // hold, nothing parked. The identical two bytes arriving in
+                    // SEPARATE chunks are NOT combined — they fall to the branch
+                    // below, where the bare Esc fires at once (its immediacy is
+                    // exactly what a hold would spend) and the next chunk's CR
+                    // submits: today's two gestures, untouched.
+                    this.#redirect();
+                    i += 2; // both bytes belong to the one gesture
+                }
                 else if (this.#menuOpen) {
                     // v3 §04: Esc closes the menu and clears the buffer.
                     // CA-4: the closing esc consumes its burst (the `i += 1`
@@ -419,6 +590,17 @@ export class Editor {
                     this.#refreshMenu();
                     i += 1;
                 }
+                else if (this.#atUp()) {
+                    // KC3 §3: esc closes the picker and leaves the BUFFER
+                    // ALONE — unlike the menu's esc, which clears it. The
+                    // sentence around the reference is still being written,
+                    // and a dismissed picker must not take it away. CA-4:
+                    // the closing esc consumes its burst, so it can never
+                    // also abort the run.
+                    this.#atClose();
+                    this.#onRender();
+                    i += 1;
+                }
                 else if (this.#queuePopMode) {
                     // W22: esc in the pop-mode — ONE more pop, then the
                     // mode ends: the next esc at rest rides the escapeCbs
@@ -515,6 +697,12 @@ export class Editor {
                 }
                 i += 1;
             }
+            else if (c === "\t" && this.#atUp()) {
+                // KC3 §3: Tab accepts the selected path — the token becomes
+                // `@<path> `. Never the file's content.
+                this.#atAccept();
+                i += 1;
+            }
             else if (c === "\x12") {
                 // W15: the expand key (ctrl+r) — rides the chain like a
                 // command, the editor just forwards it.
@@ -541,6 +729,18 @@ export class Editor {
             this.#insert(NEWLINE);
             return;
         }
+        // KC2 §2 — Ctrl+Enter, the SAME two encodings with modifier 5
+        // (1 + ctrl): kitty's CSI-u and xterm's modifyOtherKeys. Never
+        // claimed universal — a terminal that encodes neither sends a plain
+        // CR, which is an ordinary submit/queue (the safe degrade). The
+        // chunk-split safety is the existing #pending CSI resume, shared
+        // with Shift+Enter above. Outside the normal composer state the
+        // sequence is simply unknown, exactly like any other stray CSI.
+        if ((final === "u" && params === "13;5") || (final === "~" && params === "27;5;13")) {
+            if (this.#composerIdle())
+                this.#redirect();
+            return;
+        }
         if (final === "~") {
             const n = Number(params);
             if (n === 3)
@@ -568,6 +768,14 @@ export class Editor {
                 else
                     this.#menuSel = Math.min(this.#menuFiltered().length - 1, this.#menuSel + 1);
             }
+            else if (this.#atUp()) {
+                // KC3 §3: the picker owns ↑↓ while up — the SELECTION, never
+                // the cursor and never the composer's line walk. It sits
+                // ABOVE the multi-line branch on purpose: a picker opened on
+                // line 2 of a composer must still select.
+                const view = this.#atView();
+                this.#atSel = final === "A" ? Math.max(0, view.selected - 1) : Math.min(view.matches.length - 1, view.selected + 1);
+            }
             else if (this.#chars.includes(NEWLINE)) {
                 // KC1 §4: a MULTI-LINE buffer's ↑↓ walk its lines. The
                 // history and the queue-pop below stay gated on an EMPTY
@@ -728,6 +936,11 @@ export class Editor {
         this.#reflow();
         if (!this.#pasting)
             this.#refreshMenu();
+        // KC3 §3: a TYPED `@` arms the picker; a PASTED one never does —
+        // a paste is content, and content that happens to contain an
+        // address must not open a file browser mid-sentence.
+        if (cp === AT && !this.#pasting)
+            this.#atArm();
     }
     #backspace() {
         if (this.#cursor === 0)
@@ -783,8 +996,86 @@ export class Editor {
         this.#cursor = i;
         this.#reflow();
     }
+    /** KC1/KC2 — the buffer LEAVES: the flat chars, the cursor, the
+     *  horizontal scroll, the ↑/↓ goal, the menu and the pop-walk all
+     *  reset together (W22: a departing line ends the pop-walk, so the
+     *  next esc at rest interrupts again). Shared by the submit and the
+     *  redirect — the two doors a line can leave by. */
+    #takeLine() {
+        const line = String.fromCodePoint(...this.#chars);
+        this.#chars = [];
+        this.#cursor = 0;
+        this.#scroll = 0;
+        this.#verticalGoalCol = null;
+        this.#menuOpen = false;
+        this.#menuSel = 0;
+        this.#queuePopMode = false;
+        this.#atClose(); // KC3 §3: a departing line takes its picker with it
+        return line;
+    }
+    /** A2: the history remembers submitted TURN lines — never question
+     *  answers, never empties; adjacent duplicates collapse, the tail
+     *  caps at 100. A redirect is a turn, so it is remembered too. */
+    #remember(line) {
+        if (this.#history[this.#history.length - 1] !== line)
+            this.#history.push(line);
+        if (this.#history.length > 100)
+            this.#history.shift();
+    }
+    /** KC2 §2 — the NORMAL composer state: the redirect gesture is live
+     *  ONLY here. The approval panel, the slash menu, the history browse
+     *  and the queue-pop walk each OWN their keys first (the W21 "the
+     *  panel owns the keys" design, restated as a gate); a pending
+     *  question is the panel's dock-less twin (askPanel routes to
+     *  question() when the dock cannot render, so the ask owns the keys
+     *  there too); and a bracketed paste is literal TEXT, where an ESC CR
+     *  is the pasted content's own bytes and never a keypress. In every
+     *  one of those states the two bytes fall through to today's
+     *  handling — two gestures, unchanged. */
+    #composerIdle() {
+        return (this.#panel === null &&
+            !this.#menuOpen &&
+            !this.#atUp() && // KC3 §3: the @ picker owns the keys while up, exactly like the menu
+            this.#historyIdx === null &&
+            !this.#queuePopMode &&
+            !this.#pasting &&
+            this.#questionCb === null);
+    }
+    /**
+     * KC2 §2 — the gesture's meaning, kept as small as it can honestly be.
+     *
+     * An EMPTY buffer carries no correction, so the gesture degenerates to
+     * the bare Esc: the abort alone, nothing submitted. With text, the
+     * line leaves exactly as a submit's does and the listeners decide (the
+     * CLI aborts a live run and front-jumps the correction; idle, it is
+     * simply an Enter). UNWIRED — the recovery flow never binds it — the
+     * gesture IS a submit: a line is never lost to a missing binding.
+     */
+    #redirect() {
+        if (this.#chars.length === 0) {
+            for (const cb of [...this.#escapeCbs])
+                cb();
+            return;
+        }
+        if (this.#redirectCbs.length === 0) {
+            this.#submit();
+            return;
+        }
+        const line = this.#takeLine();
+        this.#remember(line);
+        for (const cb of [...this.#redirectCbs])
+            cb(line);
+        this.#onRender();
+    }
     #submit() {
-        let line = String.fromCodePoint(...this.#chars);
+        // KC3 §3: Enter ACCEPTS while the picker is up — the same rule the
+        // menu's A1 feel established (complete first, let the user read
+        // what they got, and let the NEXT Enter send it). An @ reference
+        // that submitted on the first Enter would send the fragment.
+        if (this.#atUp()) {
+            this.#atAccept();
+            return;
+        }
         if (this.#menuOpen) {
             // A1 (the feel): Enter submits the EXACT selection directly; a
             // PARTIAL selection COMPLETES the buffer (the Tab semantics)
@@ -792,7 +1083,7 @@ export class Editor {
             // again. The old behavior executed the completed command on
             // the first Enter, before the user had seen the completion.
             const m = this.#menuFiltered()[this.#menuSel];
-            if (m !== undefined && m.name !== line) {
+            if (m !== undefined && m.name !== this.line()) {
                 this.#chars = [...m.name].map((ch) => ch.codePointAt(0));
                 this.#cursor = this.#chars.length;
                 this.#reflow();
@@ -801,13 +1092,7 @@ export class Editor {
                 return; // completed, not executed
             }
         }
-        this.#chars = [];
-        this.#cursor = 0;
-        this.#scroll = 0;
-        this.#verticalGoalCol = null;
-        this.#menuOpen = false;
-        this.#menuSel = 0;
-        this.#queuePopMode = false; // W22: a submit ends the pop-walk — the next esc at rest interrupts again
+        const line = this.#takeLine();
         const cb = this.#questionCb;
         this.#questionCb = null;
         if (cb !== null) {
@@ -819,14 +1104,8 @@ export class Editor {
         else {
             this.#pendingLines.push(line); // nobody wired yet — hold it
         }
-        // A2: the history remembers submitted TURN lines — never question
-        // answers, never empties; adjacent duplicates collapse.
-        if (cb === null && line !== "") {
-            if (this.#history[this.#history.length - 1] !== line)
-                this.#history.push(line);
-            if (this.#history.length > 100)
-                this.#history.shift();
-        }
+        if (cb === null && line !== "")
+            this.#remember(line);
         this.#onRender();
     }
     /** A2: step the history browse; a delta past the newest exits back to

package/dist/index.d.ts

@@ -11,3 +11,6 @@ export { Container, foldLine, visibleWidth, SPINNER, type Component, type FrameC
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type PathResolver, type RecapStats, type ResumeMeta, type RenderInput, type RenderResult, type RunUsage, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
+export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact } from "./strings.js";
+export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun, type AtItem, type AtMatch } from "./at-picker.js";

package/dist/index.js

@@ -14,3 +14,13 @@ export { Container, foldLine, visibleWidth, SPINNER } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
+// KC2 §5: the status rows' formatters — the CLI keeps the state and the
+// repaint, the terminal layer owns what the row says.
+export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+// KC3 §1 (the extraction): the human-facing strings — the prompt, the
+// project-trust listing/view/note, the uncertain execution's view. The
+// FLOW (who is asked, what a verdict means) stays in the cli.
+export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView } from "./strings.js";
+// KC3 §3/§5: the @ file picker's pure half — the subsequence filter, the
+// deterministic rank, and the ONE cap the CLI's file source shares.
+export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun } from "./at-picker.js";

package/dist/status.d.ts

@@ -0,0 +1,38 @@
+/**
+ * KC2 §5 — the status line's FORMATTERS, extracted from the CLI (the
+ * ADR-0041 escape hatch: extraction, never a fifth raise). The split is
+ * the one the ADR names: the CLI keeps the STATE (the rotating glyph,
+ * the run's start instant, the live usage, whether the dock is up) and
+ * the REPAINT; what a status row SAYS is presentation, and presentation
+ * belongs to the terminal layer.
+ *
+ * Two callers built these rows independently before the move — chat's
+ * REPL and the recovery flow — with the running row duplicated verbatim
+ * in both. One definition now serves both, and the tier stays a
+ * PARAMETER precisely because the two callers disagree on it (chat
+ * spells plan's read-only posture out per W19, the recovery flow prints
+ * the bare mode): the extraction must not silently unify a difference it
+ * was not asked to settle.
+ *
+ * The rows are byte-for-byte what the CLI built before the move — the
+ * v2b/v3 §03 shapes the e2e transcripts pin by substring — with ONE
+ * deliberate exception: the running row's interrupt hint, which KC2 §2
+ * widens to name the new gesture.
+ */
+/** v3 §03/§05 — the working glyph family; the CLI's 200ms spinner walks
+ *  it and hands each glyph back to `runningStatus`. */
+export declare const STATUS_GLYPHS: readonly ["▖", "▘", "▝", "▗"];
+/**
+ * The RUNNING row: the rotating glyph, the wall seconds since `since`
+ * (never below 1 — a run that just started still reads "1s", so the row
+ * never claims a turn took no time), the streamed output tokens once the
+ * count is known, the interrupt hints, and the live ctx estimate.
+ *
+ * KC2 §2: the hint names BOTH gestures. Esc still stops; alt+⏎ redirects
+ * — stop, and do THIS instead. The row is where the gesture is taught,
+ * because it is on screen exactly when the gesture is useful.
+ */
+export declare function runningStatus(glyph: string, since: number, outTokens: number | null, ctxRatio: number): string;
+/** The IDLE row: the approval tier as the CALLER names it, the /mode
+ *  hint, the model driving the session, and the ctx estimate. */
+export declare function idleStatus(tier: string, model: string, ctxRatio: number): string;

package/dist/status.js

@@ -0,0 +1,52 @@
+/**
+ * KC2 §5 — the status line's FORMATTERS, extracted from the CLI (the
+ * ADR-0041 escape hatch: extraction, never a fifth raise). The split is
+ * the one the ADR names: the CLI keeps the STATE (the rotating glyph,
+ * the run's start instant, the live usage, whether the dock is up) and
+ * the REPAINT; what a status row SAYS is presentation, and presentation
+ * belongs to the terminal layer.
+ *
+ * Two callers built these rows independently before the move — chat's
+ * REPL and the recovery flow — with the running row duplicated verbatim
+ * in both. One definition now serves both, and the tier stays a
+ * PARAMETER precisely because the two callers disagree on it (chat
+ * spells plan's read-only posture out per W19, the recovery flow prints
+ * the bare mode): the extraction must not silently unify a difference it
+ * was not asked to settle.
+ *
+ * The rows are byte-for-byte what the CLI built before the move — the
+ * v2b/v3 §03 shapes the e2e transcripts pin by substring — with ONE
+ * deliberate exception: the running row's interrupt hint, which KC2 §2
+ * widens to name the new gesture.
+ */
+import { kUnit } from "./render.js";
+/** v3 §03/§05 — the working glyph family; the CLI's 200ms spinner walks
+ *  it and hands each glyph back to `runningStatus`. */
+export const STATUS_GLYPHS = ["▖", "▘", "▝", "▗"];
+/** The ~ctx estimate as the whole-percent LEFT. A non-finite ratio (no
+ *  window, no estimate) yields null and the row prints "~null%" — the
+ *  long-standing shape, kept on purpose: an honest null beats an
+ *  invented percentage. */
+function ctxLeft(ratio) {
+    return Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
+}
+/**
+ * The RUNNING row: the rotating glyph, the wall seconds since `since`
+ * (never below 1 — a run that just started still reads "1s", so the row
+ * never claims a turn took no time), the streamed output tokens once the
+ * count is known, the interrupt hints, and the live ctx estimate.
+ *
+ * KC2 §2: the hint names BOTH gestures. Esc still stops; alt+⏎ redirects
+ * — stop, and do THIS instead. The row is where the gesture is taught,
+ * because it is on screen exactly when the gesture is useful.
+ */
+export function runningStatus(glyph, since, outTokens, ctxRatio) {
+    const out = outTokens !== null ? ` ↓ ${kUnit(outTokens)} tokens` : "";
+    const seconds = Math.max(1, Math.round((Date.now() - since) / 1000));
+    return `${glyph} working ${seconds}s${out} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
+}
+/** The IDLE row: the approval tier as the CALLER names it, the /mode
+ *  hint, the model driving the session, and the ctx estimate. */
+export function idleStatus(tier, model, ctxRatio) {
+    return `▸ ${tier} · /mode to switch · ${model} · ctx left ~${ctxLeft(ctxRatio)}%`;
+}

package/dist/strings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * KC3 slice 1 — the strings shim: the human-facing strings moved to the
+ * 9th package (the ADR-0043 Amendment 4 hatch); the tui re-exports them
+ * so its consumers (the cli) import a stable path.
+ */
+export * from "@vincemakes/kiso-tui-cells/strings";

package/dist/strings.js

@@ -0,0 +1,6 @@
+/**
+ * KC3 slice 1 — the strings shim: the human-facing strings moved to the
+ * 9th package (the ADR-0043 Amendment 4 hatch); the tui re-exports them
+ * so its consumers (the cli) import a stable path.
+ */
+export * from "@vincemakes/kiso-tui-cells/strings";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "kiso tui — the pure terminal layer (cell renderer, dock, raw editor, diff, palette). Zero runtime dependencies: input is data, output is bytes.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,6 @@
   },
   "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tui#readme",
   "dependencies": {
-    "@vincemakes/kiso-tui-cells": "0.5.0"
+    "@vincemakes/kiso-tui-cells": "0.7.0"
   }
 }