@vincemakes/kiso-tui 0.6.0 → 0.8.0

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

@@ -43,7 +43,14 @@
  * line-mode bytes byte-for-byte (the e2e guards them).
  */
 import { type MenuItem } from "./editor.js";
-import { type PanelState } from "./approval-panel.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

@@ -45,7 +45,10 @@
 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";
+// KC3.5: the panel-slot reads come from the DISPATCHERS — one source
+// for four reads, so an ask can never render half as an approval.
+import { panelAffordanceOf, panelLeadOf, panelRowsOf, panelStatusOf } from "./ask-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 +121,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 +150,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;
@@ -651,7 +659,7 @@ export class Body {
     #statusSource() {
         const panel = this.#panelState?.() ?? null;
         if (panel !== null)
-            return { status: panelStatus(panel.view, panel.phase, panel.sel), hint: panelAffordance(panel.view, panel.phase, panel.sel) };
+            return { status: panelStatusOf(panel), hint: panelAffordanceOf(panel) };
         // W22: while turns wait in the queue, the right hint shows the
         // count — the chips below carry the lines themselves.
         const queued = this.#queueState?.().length ?? 0;
@@ -675,6 +683,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. */
@@ -692,7 +706,7 @@ export class Body {
         // + 1 — the SAME formula the marker embeds at (the panel lead when
         // the panel owns the row; the old prompt-only math desynced the
         // panel rows' edit column; leadWidth is the ONE authority)
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
+        const lead = panel !== null ? panelLeadOf(panel) : this.#inputPrompt;
         return 3 + leadWidth(lead) + st.cursor;
     }
     /** The old dock's redraw — the editor's onRender target: mark + the
@@ -766,7 +780,7 @@ export class Body {
             // W21: the panel's own rows (the cap is exact — the scalar
             // reflects the screen). W22: the queue chips occupy their
             // own band — the panel's cap shrinks by their rows.
-            return (panelBlockRows(panel.view, panel.phase, panel.sel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
+            return (panelRowsOf(panel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
                 CHROME_ROWS +
                 inputExtra +
                 queueRows.length);
@@ -853,7 +867,7 @@ export class Body {
             // the W11 blank would separate it from the frozen content).
             // The cap is exact, so the force-commit loop never fires. W22:
             // the queue band sits below the panel — the cap shrinks by it.
-            liveLines = panelBlockRows(panel.view, panel.phase, panel.sel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
+            liveLines = panelRowsOf(panel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
         }
         else {
             let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
@@ -1098,7 +1112,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 [];
@@ -1195,7 +1226,7 @@ export class Body {
         // the lead — the panel's phase lead when the panel owns the row
         // (1-3> / the rule input's "2 Yes, don't ask again for " / the
         // amend "feedback (deny): "), the bound prompt otherwise
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
+        const lead = panel !== null ? panelLeadOf(panel) : this.#inputPrompt;
         const leadW = leadWidth(lead);
         // a LEGACY one-row provider (the old {line, cursor} shape) keeps
         // working: its single line is the composer's single row
@@ -1589,6 +1620,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 +1655,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

@@ -23,7 +23,8 @@
  */
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
-import { type PanelState, type PanelVerdict, type PanelView } from "./approval-panel.js";
+import type { PanelState, PanelVerdict, 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). */
@@ -83,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