@vincemakes/kiso-tui 0.6.0 → 0.8.0

package/dist/ask-panel.d.ts

@@ -0,0 +1,95 @@
+/**
+ * KC3.5 — the ask view: the model asks the human a real question.
+ *
+ * The W21 approval panel generalizes rather than duplicates. An ask is a
+ * PanelView carrying `ask`, so it rides the EXISTING panel slot: the
+ * compositor's live region, the input row's lead, the status/affordance
+ * pair, and — the part that matters — the editor's buffer stash/restore
+ * and its key precedence (the panel owns the keys; the menu, the history
+ * walk and the @ picker never open under it).
+ *
+ * This module owns three things and nothing else:
+ *
+ *   1. the ROWS — the question, the ‹ n/m › counter, the numbered
+ *      options with their descriptions and selection marks, the
+ *      type-your-own line;
+ *   2. the pure REDUCER — a key plus a state gives the next state (and,
+ *      when the walk ends, the result). No I/O, no editor internals: the
+ *      editor feeds it keys and renders what comes back, which is what
+ *      makes the whole interaction unit-testable without a terminal;
+ *   3. the DISPATCHERS — panelBlockRows/panelLead/panelStatus/
+ *      panelAffordance re-exported with the ask branch folded in, so the
+ *      compositor and the editor change ONE import line between them and
+ *      the panel slot itself stays exactly as W21 built it.
+ *
+ * What is deliberately NOT here (the round's stop clauses): no partial
+ * answer durability (a crash re-presents the WHOLE call — per-toggle
+ * durability would need a new durable mechanism), no "chat about this"
+ * hand-off, no timeout and no countdown.
+ */
+import { type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type PanelPhase, type PanelSel, type PanelState, type PanelView } from "./approval-panel.js";
+/** The schema's own bounds — the registry refuses anything outside them
+ *  (extensions/ask validates; these are the numbers it validates to). */
+export declare const ASK_MAX_QUESTIONS = 4;
+export declare const ASK_MIN_OPTIONS = 2;
+export declare const ASK_MAX_OPTIONS = 4;
+export declare const ASK_HEADER_CAP = 12;
+/** The ask panel's opening state: nothing picked, the cursor on the
+ *  first option of the first question. */
+export declare function askStart(spec: AskSpec): AskRuntime;
+/** The decline's honest record: every question with its options, so the
+ *  model reads what it did NOT get an answer to (frame 4). The SAME
+ *  list whether the human pressed esc on question one or question four
+ *  — the round declines the CALL, never half of it. */
+export declare function askDeclineList(spec: AskSpec): string[];
+export declare function askDeclineAll(spec: AskSpec): AskResult;
+/** The answers collected so far, in the tool_result's own shapes: a
+ *  typed answer wins over the picks (the human typed it last), a
+ *  multi-select question yields `choices`, a single one `choice`. */
+export declare function askAnswers(spec: AskSpec, state: AskRuntime): AskAnswer[];
+/** The reducer's outcome: the next state, plus the RESULT when the walk
+ *  ended (the last question answered, or the decline). */
+export interface AskStep {
+    readonly state: AskRuntime;
+    readonly result?: AskResult;
+}
+/**
+ * The pure key reducer. `key` is a single logical key: a digit "1".."4",
+ * "space", "up"/"down", "left" (walk back), "enter", "t" (type your own),
+ * or "esc". The custom phase's TEXT is not routed here — the editor owns
+ * the buffer exactly as it does for the rule-input phase, and hands the
+ * committed line to `askCommitCustom`.
+ */
+export declare function askKey(spec: AskSpec, state: AskRuntime, key: string): AskStep;
+/** The typed answer commits: it becomes THE answer for this question
+ *  (clearing its picks) and the walk advances. An empty line is a
+ *  no-op back to the options — nothing is recorded. */
+export declare function askCommitCustom(spec: AskSpec, state: AskRuntime, text: string): AskStep;
+/** The ask block's rows — the question as the rule line, the header (or
+ *  the counter) as the title, the options as the body, and the
+ *  type-your-own line last. The shape is the W21 block's: gutter, rule,
+ *  title, divider, body, affordance, corner. */
+export declare function askBlockRows(view: PanelView, state: AskRuntime, W: number, maxRows: number): string[];
+/** The status row's right-hand hint — the phase's keys. */
+export declare function askAffordance(state: AskRuntime): string;
+/** The status row's left text — the ask's own line, with the walk. */
+export declare function askStatus(view: PanelView, state: AskRuntime): string;
+/** The input row's lead: the digit lead while picking, the typing lead
+ *  in the custom phase (the rule-input phase's shape, reused). */
+export declare function askLeadPlain(state: AskRuntime): string;
+export declare function panelBlockRows(view: PanelView, phase: PanelPhase, sel: PanelSel, W: number, maxRows: number, ask?: AskRuntime): string[];
+export declare function panelLead(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelLeadPlain(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelStatus(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelAffordance(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+/** The whole panel state in one call — the compositor's four reads share
+ *  one source, so an ask can never render half as an approval. */
+export declare const panelRowsOf: (s: PanelState, W: number, maxRows: number) => string[];
+export declare const panelLeadOf: (s: PanelState) => string;
+export declare const panelStatusOf: (s: PanelState) => string;
+export declare const panelAffordanceOf: (s: PanelState) => string;
+/** The ask's PanelView. The dock-less fallback question is HONEST: a
+ *  terminal without a panel cannot walk options, so it says the ask is
+ *  being declined rather than pretending y/n answered it. */
+export declare function askView(spec: AskSpec): PanelView;
+export type { AskAnswer, AskOption, AskQuestion, AskResult, AskRuntime, AskSpec };

package/dist/ask-panel.js

@@ -0,0 +1,268 @@
+/**
+ * KC3.5 — the ask view: the model asks the human a real question.
+ *
+ * The W21 approval panel generalizes rather than duplicates. An ask is a
+ * PanelView carrying `ask`, so it rides the EXISTING panel slot: the
+ * compositor's live region, the input row's lead, the status/affordance
+ * pair, and — the part that matters — the editor's buffer stash/restore
+ * and its key precedence (the panel owns the keys; the menu, the history
+ * walk and the @ picker never open under it).
+ *
+ * This module owns three things and nothing else:
+ *
+ *   1. the ROWS — the question, the ‹ n/m › counter, the numbered
+ *      options with their descriptions and selection marks, the
+ *      type-your-own line;
+ *   2. the pure REDUCER — a key plus a state gives the next state (and,
+ *      when the walk ends, the result). No I/O, no editor internals: the
+ *      editor feeds it keys and renders what comes back, which is what
+ *      makes the whole interaction unit-testable without a terminal;
+ *   3. the DISPATCHERS — panelBlockRows/panelLead/panelStatus/
+ *      panelAffordance re-exported with the ask branch folded in, so the
+ *      compositor and the editor change ONE import line between them and
+ *      the panel slot itself stays exactly as W21 built it.
+ *
+ * What is deliberately NOT here (the round's stop clauses): no partial
+ * answer durability (a crash re-presents the WHOLE call — per-toggle
+ * durability would need a new durable mechanism), no "chat about this"
+ * hand-off, no timeout and no countdown.
+ */
+import { panelAffordance as basePanelAffordance, panelBlockRows as basePanelBlockRows, panelLead as basePanelLead, panelLeadPlain as basePanelLeadPlain, panelStatus as basePanelStatus, } from "./approval-panel.js";
+import { cutLine } from "@vincemakes/kiso-tui-cells/components";
+import { escapeTerminal, palette } from "./render.js";
+/** The schema's own bounds — the registry refuses anything outside them
+ *  (extensions/ask validates; these are the numbers it validates to). */
+export const ASK_MAX_QUESTIONS = 4;
+export const ASK_MIN_OPTIONS = 2;
+export const ASK_MAX_OPTIONS = 4;
+export const ASK_HEADER_CAP = 12;
+/** The ask panel's opening state: nothing picked, the cursor on the
+ *  first option of the first question. */
+export function askStart(spec) {
+    return {
+        qIndex: 0,
+        cursor: 0,
+        picks: spec.questions.map(() => []),
+        custom: spec.questions.map(() => null),
+        phase: "options",
+    };
+}
+/** The decline's honest record: every question with its options, so the
+ *  model reads what it did NOT get an answer to (frame 4). The SAME
+ *  list whether the human pressed esc on question one or question four
+ *  — the round declines the CALL, never half of it. */
+export function askDeclineList(spec) {
+    return spec.questions.map((q) => `${q.question} (${q.options.map((o) => o.label).join(", ")})`);
+}
+export function askDeclineAll(spec) {
+    return { declined: askDeclineList(spec) };
+}
+/** The answers collected so far, in the tool_result's own shapes: a
+ *  typed answer wins over the picks (the human typed it last), a
+ *  multi-select question yields `choices`, a single one `choice`. */
+export function askAnswers(spec, state) {
+    return spec.questions.map((q, i) => {
+        const typed = state.custom[i];
+        if (typed !== null && typed !== undefined && typed !== "")
+            return { q: q.question, custom: typed };
+        const picked = (state.picks[i] ?? []).map((n) => q.options[n]?.label ?? "");
+        return q.multiSelect === true ? { q: q.question, choices: picked } : { q: q.question, choice: picked[0] ?? "" };
+    });
+}
+/** Whether the CURRENT question has something to submit — a pick or a
+ *  typed answer. Enter on an empty question is a no-op: the panel never
+ *  invents an answer, and never silently skips one. */
+function answered(state, i) {
+    const typed = state.custom[i];
+    return (state.picks[i] ?? []).length > 0 || (typed !== null && typed !== undefined && typed !== "");
+}
+/** Advance past the current question — the next one, or the end. */
+function advance(spec, state) {
+    const next = state.qIndex + 1;
+    if (next >= spec.questions.length)
+        return { state, result: { answers: askAnswers(spec, state) } };
+    return { state: { ...state, qIndex: next, cursor: 0, phase: "options" } };
+}
+function toggle(state, option, multi) {
+    const current = state.picks[state.qIndex] ?? [];
+    const next = multi
+        ? current.includes(option)
+            ? current.filter((n) => n !== option)
+            : [...current, option].sort((a, b) => a - b)
+        : [option];
+    const picks = state.picks.map((p, i) => (i === state.qIndex ? next : p));
+    // a pick supersedes a typed answer for the same question — one
+    // question, one answer, and the human's last gesture is the one.
+    const custom = state.custom.map((c, i) => (i === state.qIndex ? null : c));
+    return { ...state, picks, custom, cursor: option };
+}
+/**
+ * The pure key reducer. `key` is a single logical key: a digit "1".."4",
+ * "space", "up"/"down", "left" (walk back), "enter", "t" (type your own),
+ * or "esc". The custom phase's TEXT is not routed here — the editor owns
+ * the buffer exactly as it does for the rule-input phase, and hands the
+ * committed line to `askCommitCustom`.
+ */
+export function askKey(spec, state, key) {
+    const q = spec.questions[state.qIndex];
+    const multi = q.multiSelect === true;
+    if (state.phase === "custom") {
+        // esc backs out of the typing line; enter is the editor's (it
+        // carries the text and calls askCommitCustom).
+        if (key === "esc")
+            return { state: { ...state, phase: "options" } };
+        return { state };
+    }
+    if (key === "esc")
+        return { state, result: askDeclineAll(spec) };
+    if (key === "t")
+        return { state: { ...state, phase: "custom" } };
+    if (key === "left")
+        return { state: state.qIndex === 0 ? state : { ...state, qIndex: state.qIndex - 1, cursor: 0 } };
+    if (key === "up")
+        return { state: { ...state, cursor: Math.max(0, state.cursor - 1) } };
+    if (key === "down")
+        return { state: { ...state, cursor: Math.min(q.options.length - 1, state.cursor + 1) } };
+    if (key === "enter")
+        return answered(state, state.qIndex) ? advance(spec, state) : { state };
+    // SPACE selects at the cursor and NEVER commits — in either mode. It
+    // used to answer-and-advance a single-select question, which made a
+    // stray space (the most pressable key there is) an instant answer of
+    // whatever the cursor happened to be on. Enter and the digits are the
+    // only gestures that commit; space is how you point at something.
+    if (key === "space")
+        return { state: toggle(state, state.cursor, multi) };
+    const digit = Number.parseInt(key, 10);
+    if (Number.isInteger(digit) && digit >= 1 && digit <= q.options.length) {
+        const next = toggle(state, digit - 1, multi);
+        // single-select answers AND advances — the fast path a human
+        // expects; multi-select toggles and waits for enter.
+        return multi ? { state: next } : advance(spec, next);
+    }
+    return { state };
+}
+/** The typed answer commits: it becomes THE answer for this question
+ *  (clearing its picks) and the walk advances. An empty line is a
+ *  no-op back to the options — nothing is recorded. */
+export function askCommitCustom(spec, state, text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return { state: { ...state, phase: "options" } };
+    const custom = state.custom.map((c, i) => (i === state.qIndex ? trimmed : c));
+    const picks = state.picks.map((p, i) => (i === state.qIndex ? [] : p));
+    return advance(spec, { ...state, custom, picks, phase: "options" });
+}
+// ── the rows ─────────────────────────────────────────────────────────
+/** One option row: the number, the selection mark, the label, and the
+ *  description after an em dash. The row CUTS (never folds) — the
+ *  block's height is its row count, the W20 discipline. */
+function optionRow(o, n, picked, cursor, multi, W) {
+    const p = palette();
+    const mark = multi ? (picked ? "◉" : "◯") : picked ? "◉" : " ";
+    const head = `${cursor ? p.bold : ""} ${n} ${mark} ${escapeTerminal(o.label)}${p.reset}`;
+    const body = o.description === undefined ? "" : `${p.dim} — ${escapeTerminal(o.description)}${p.reset}`;
+    return cutLine(`${head}${body}`, Math.max(1, W - 2));
+}
+/** The ask block's rows — the question as the rule line, the header (or
+ *  the counter) as the title, the options as the body, and the
+ *  type-your-own line last. The shape is the W21 block's: gutter, rule,
+ *  title, divider, body, affordance, corner. */
+export function askBlockRows(view, state, W, maxRows) {
+    const p = palette();
+    const spec = view.ask;
+    const q = spec.questions[state.qIndex];
+    const multi = q.multiSelect === true;
+    const gutter = `${p.dim}│${p.reset} `;
+    const counter = spec.questions.length > 1 ? `${p.dim} ‹ ${state.qIndex + 1}/${spec.questions.length} ›${p.reset}` : "";
+    const rows = [];
+    rows.push(`${gutter}${cutLine(`${p.bold}${escapeTerminal(q.question)}${p.reset}${counter}`, Math.max(1, W - 2))}`);
+    const header = q.header === undefined ? "the question" : escapeTerminal(q.header.slice(0, ASK_HEADER_CAP));
+    rows.push(`${gutter}${cutLine(`${p.dim}${header}${p.reset}`, Math.max(1, W - 2))}`);
+    rows.push(cutLine(`${p.dim}─ ${multi ? "pick any — space toggles" : "pick one"} ─${p.reset}`, Math.max(1, W - 2)));
+    const picks = state.picks[state.qIndex] ?? [];
+    const body = q.options.map((o, i) => `${gutter}${optionRow(o, i + 1, picks.includes(i), state.cursor === i, multi, W)}`);
+    const typed = state.custom[state.qIndex];
+    body.push(`${gutter}${cutLine(typed === null || typed === undefined
+        ? `${p.dim} t   type your own answer${p.reset}`
+        : ` t ◉ ${escapeTerminal(typed)}`, Math.max(1, W - 2))}`);
+    // the bounded block: the options fold nothing and cut individually,
+    // so the cap drops whole rows with the W21 notice row.
+    const budget = Math.max(1, maxRows - 5);
+    if (body.length > budget) {
+        const kept = Math.max(0, budget - 1);
+        rows.push(...body.slice(0, kept));
+        rows.push(cutLine(`${p.dim}└ +${body.length - kept} more rows — the full question is in the event log${p.reset}`, Math.max(1, W - 2)));
+    }
+    else {
+        rows.push(...body);
+    }
+    rows.push(`${gutter}${p.dim}${askAffordance(state)}${p.reset}`);
+    rows.push(`${p.dim}└ ${p.reset}`);
+    return rows;
+}
+/** The status row's right-hand hint — the phase's keys. */
+export function askAffordance(state) {
+    if (state.phase === "custom")
+        return "enter answers · esc backs out";
+    return state.qIndex > 0 ? "1-4 pick · t type · ← back · esc decline" : "1-4 pick · t type · esc decline";
+}
+/** The status row's left text — the ask's own line, with the walk. */
+export function askStatus(view, state) {
+    const total = view.ask.questions.length;
+    return total > 1 ? `▸ question ${state.qIndex + 1} of ${total}` : "▸ a question for you";
+}
+/** The input row's lead: the digit lead while picking, the typing lead
+ *  in the custom phase (the rule-input phase's shape, reused). */
+export function askLeadPlain(state) {
+    return state.phase === "custom" ? "your answer: " : "1-4> ";
+}
+// ── the dispatchers: the panel slot, with the ask branch folded in ────
+export function panelBlockRows(view, phase, sel, W, maxRows, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askBlockRows(view, ask, W, maxRows);
+    return basePanelBlockRows(view, phase, sel, W, maxRows);
+}
+export function panelLead(view, phase, sel, ask) {
+    const p = palette();
+    if (view.ask !== undefined && ask !== undefined)
+        return `${p.bold}${askLeadPlain(ask)}${p.reset}`;
+    return basePanelLead(view, phase, sel);
+}
+export function panelLeadPlain(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askLeadPlain(ask);
+    return basePanelLeadPlain(view, phase, sel);
+}
+export function panelStatus(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askStatus(view, ask);
+    return basePanelStatus(view, phase, sel);
+}
+export function panelAffordance(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askAffordance(ask);
+    return basePanelAffordance(view, phase, sel);
+}
+/** The whole panel state in one call — the compositor's four reads share
+ *  one source, so an ask can never render half as an approval. */
+export const panelRowsOf = (s, W, maxRows) => panelBlockRows(s.view, s.phase, s.sel, W, maxRows, s.ask);
+export const panelLeadOf = (s) => panelLead(s.view, s.phase, s.sel, s.ask);
+export const panelStatusOf = (s) => panelStatus(s.view, s.phase, s.sel, s.ask);
+export const panelAffordanceOf = (s) => panelAffordance(s.view, s.phase, s.sel, s.ask);
+// ── the view: what the human reads when the model asks ────────────────
+/** The ask's PanelView. The dock-less fallback question is HONEST: a
+ *  terminal without a panel cannot walk options, so it says the ask is
+ *  being declined rather than pretending y/n answered it. */
+export function askView(spec) {
+    const first = spec.questions[0];
+    return {
+        flavor: "simple",
+        name: "ask_user",
+        title: first.header ?? first.question,
+        speaker: "kiso",
+        statusText: "▸ a question for you",
+        args: { kind: "text", lines: askDeclineList(spec) },
+        fallbackQuestion: `⚠ ${escapeTerminal(first.question)} — this terminal cannot show the option panel; the question is declined `,
+        ask: spec,
+    };
+}

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[];