@vincemakes/kiso-tui 0.6.0 → 0.8.0

package/dist/editor.js

@@ -26,7 +26,10 @@ import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 // authority) — re-exported so the editor's public surface is unchanged.
 export { charWidth, displayWidth, widthOf };
 import { palette } from "./render.js";
-import { panelLead } from "./approval-panel.js";
+// KC3.5: the panel-slot dispatchers — the ask branch folded into the
+// W21 lead/rows, so this file keeps ONE panel and one key owner.
+import { askCommitCustom, askKey, askStart, panelLead } from "./ask-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 +47,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
@@ -101,6 +111,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.
@@ -215,7 +241,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
@@ -276,6 +302,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;
@@ -293,6 +441,7 @@ export class Editor {
             view,
             phase: "options",
             sel: 0,
+            ask: view.ask === undefined ? null : askStart(view.ask),
             amend: "yes",
             onCommit,
             stash: { chars: this.#chars, cursor: this.#cursor, scroll: this.#scroll },
@@ -304,6 +453,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. */
@@ -316,7 +466,7 @@ export class Editor {
         const panel = this.#panel;
         if (panel === null)
             return null;
-        return { view: panel.view, phase: panel.phase, sel: panel.sel };
+        return { view: panel.view, phase: panel.phase, sel: panel.sel, ...(panel.ask === null ? {} : { ask: panel.ask }) };
     }
     enter() {
         if (this.#entered)
@@ -346,7 +496,7 @@ export class Editor {
         // W21: the panel's lead owns the row while up (the brick returns
         // when the panel closes).
         const panel = this.#panel;
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : `${p.bold}${PROMPT}${p.reset}`;
+        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel, panel.ask ?? undefined) : `${p.bold}${PROMPT}${p.reset}`;
         // W23: the ONE width authority — leadWidth(lead), the ANSI-stripped
         // visible width (the styled panel lead / the styled brick measure
         // the same as their plain text — a lead can never measure
@@ -373,6 +523,45 @@ export class Editor {
                 // text); ctrl-c still rides the SIGINT handler (which
                 // cancels the panel).
                 const panel = this.#panel;
+                // KC3.5: an ASK panel routes its own keys — the digits pick
+                // (single-select advances, multi toggles), space toggles at
+                // the cursor, `t` opens the type-your-own line (the
+                // rule-input phase's shape: the buffer is the editor's, so
+                // only esc and enter are intercepted while typing), esc
+                // declines the whole call. Everything else falls through to
+                // the ordinary editing chain below.
+                if (panel.ask !== null) {
+                    const typing = panel.ask.phase === "custom";
+                    if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
+                        this.#askStep("esc");
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "\x0d" || c === "\x0a") {
+                        this.#askStep(typing ? "commit" : "enter");
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && (c === " " || (c !== undefined && c >= "1" && c <= "4") || c === "t" || c === "T")) {
+                        this.#askStep(c === " " ? "space" : c === "T" ? "t" : c);
+                        i += 1;
+                        continue;
+                    }
+                    // an ask at rest swallows stray PRINTABLE keys — the panel
+                    // owns them, and a typed "/" or "@" must not arm the menu
+                    // or the picker underneath. Two things are never
+                    // swallowed: the CSI/SS3 introducer, because ←/↑/↓ are
+                    // the ask's own keys and the parser below routes them
+                    // (the T-Q1 red), and the CONTROL characters, because
+                    // ctrl-c must still reach the SIGINT handler that
+                    // cancels the panel — W21's own rule, and what the T-Q6
+                    // race red caught: an abort with the panel up did
+                    // nothing at all.
+                    if (!typing && c !== undefined && c >= " " && c !== "\x7f") {
+                        i += 1;
+                        continue;
+                    }
+                }
                 if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
                     this.#panelEsc();
                     i += 1;
@@ -443,6 +632,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
@@ -539,6 +739,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.
@@ -596,7 +802,10 @@ export class Editor {
             // panel owns the keys while up (↑↓ do nothing — the panel has no
             // ↑↓ role).
             if (this.#panel !== null) {
-                /* the panel owns the keys */
+                // W21: the panel owns the keys. KC3.5: an ask uses ↑↓ for
+                // the option cursor (the approval panel still has no ↑↓ role).
+                if (this.#panel.ask !== null && this.#panel.ask.phase === "options")
+                    this.#askStep(final === "A" ? "up" : "down");
             }
             else if (this.#menuOpen) {
                 if (final === "A")
@@ -604,6 +813,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
@@ -626,7 +843,12 @@ export class Editor {
             this.#onRender();
         }
         else if (final === "D") {
-            this.#move(-1);
+            // KC3.5: ← walks the ask BACK a question (the ‹ n/m › walk); at
+            // question one it stays put — esc is the decline, never ←.
+            if (this.#panel?.ask != null && this.#panel.ask.phase === "options")
+                this.#askStep("left");
+            else
+                this.#move(-1);
         }
         else if (final === "C") {
             this.#move(1);
@@ -741,6 +963,33 @@ export class Editor {
         else if (panel.sel === 3)
             this.#panelClose({ action: "deny", reason: "" });
     }
+    /**
+     * KC3.5 — one ask key: the pure reducer decides, this method applies.
+     * The buffer is cleared on every phase change so the type-your-own
+     * line starts empty and its text never leaks back into the options
+     * (the rule-input phase's own discipline). A step that produced a
+     * RESULT closes the panel with it — the stash/restore is the W21
+     * path, identical for an answer and for a decline.
+     */
+    #askStep(key) {
+        const panel = this.#panel;
+        if (panel === null || panel.ask === null)
+            return;
+        const spec = panel.view.ask;
+        const before = panel.ask.phase;
+        const step = key === "commit" ? askCommitCustom(spec, panel.ask, this.line()) : askKey(spec, panel.ask, key);
+        panel.ask = step.state;
+        if (step.state.phase !== before) {
+            this.#chars = [];
+            this.#cursor = 0;
+            this.#scroll = 0;
+        }
+        if (step.result !== undefined) {
+            this.#panelClose({ action: "answers", result: step.result });
+            return;
+        }
+        this.#onRender();
+    }
     #panelClose(verdict) {
         const panel = this.#panel;
         if (panel === null)
@@ -764,6 +1013,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)
@@ -833,6 +1087,7 @@ export class Editor {
         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
@@ -857,6 +1112,7 @@ export class Editor {
     #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 &&
@@ -889,6 +1145,14 @@ export class Editor {
         this.#onRender();
     }
     #submit() {
+        // 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)
@@ -975,7 +1239,7 @@ export class Editor {
         // W23: the ONE width authority — leadWidth(lead) — the cap follows
         // the lead the editor itself renders (the panel lead when the panel
         // owns the keys, the brick otherwise): maxW = W − walls − lead.
-        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel) : PROMPT;
+        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel, this.#panel.ask ?? undefined) : PROMPT;
         const leadW = leadWidth(lead);
         const maxW = Math.max(1, W - leadW - 4); // W6: the box's walls (2+2) — the visible line fits the box's inner width; the "…" rides inside
         // KC1: the scroll is the CURSOR LINE's own offset — a single-line

package/dist/index.d.ts

@@ -12,3 +12,7 @@ export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widt
 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";
+export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type AskStep, } from "./ask-panel.js";
+export { extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";

package/dist/index.js

@@ -17,3 +17,17 @@ 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";
+// KC3.5 (the ask round): the ask view — the panel machinery generalized.
+// The cli composes the view and hands the answers to the tool; the keys,
+// the rows and the walk are the terminal layer's.
+export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, } from "./ask-panel.js";
+// KC3.5 §4: the interrupted-ask copy — the SAME uncertainty gate, said
+// honestly for a question nobody answered (the ① probe's surface).
+export { extensionsBannerText, helpRows, unansweredAskView } from "./strings.js";

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.6.0",
+  "version": "0.8.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.6.0"
+    "@vincemakes/kiso-tui-cells": "0.8.0"
   }
 }