@vincemakes/kiso-tui-cells 0.46.2 → 0.47.0

package/dist/approval-panel.d.ts

@@ -24,6 +24,7 @@
  * count, the W20 discipline — the #checked throw demands it); the args
  * FOLD (a bounded block's body — content folds, metadata cuts).
  */
+import { foldAtSpaces } from "./components.js";
 export type PanelFlavor = "approval" | "simple";
 /**
  * TUI2-R3v2 ① — two phases, not three.
@@ -225,6 +226,30 @@ export interface PickOption {
      *  previous selection asked ("effort xhigh \u2192 high: the nearest this
      *  model supports"). The caller's sentence, reproduced verbatim. */
     readonly levelNote?: string;
+    /** Graphite R3e: what the second axis IS, named on its key hint
+     *  (`←→ mode`); absent, it is the model's `effort`. P3: a named axis is
+     *  the row's own value, so its strip carries no label of its own. */
+    readonly axisLabel?: string;
+    /** Graphite P3: the columns after the label (a profile's host and state,
+     *  a setting's value and source), measured over EVERY option so nothing
+     *  moves as the cursor or the filter does. Absent, the `note` is the one
+     *  column. */
+    readonly cols?: readonly string[];
+    /** Graphite P3: what the selected row OPENS into, on the same wash (the
+     *  /resume shape) — what the columns cannot hold: why a profile cannot
+     *  run, how a config setting changes. After the level strip when there
+     *  is one, and it gives way first. */
+    readonly opened?: string;
+    /** Graphite P3: the option cannot run as it stands (a profile with no
+     *  credential): its row is dim. It can still be picked; the caller says
+     *  why, as it always has. */
+    readonly off?: boolean;
+    /** Graphite P3: further texts the filter reaches (a profile's name),
+     *  after the label and the first column. Never drawn. */
+    readonly match?: readonly string[];
+    /** Graphite P3: what ⏎ does on THIS row, for the key row
+     *  (`⏎ opens /model`); absent, the spec's word. */
+    readonly enter?: string;
 }
 /** The level cursor, CORRECTED at read time: never off the end, never on
  *  a forbidden index, and never invented where the caller supplied none.
@@ -242,18 +267,38 @@ export declare function startLevel(o: PickOption | undefined): number | null;
 /** The next enabled index in `dir`, or the current one at the end of the
  *  ladder. Forbidden indexes are stepped OVER, never landed on. */
 export declare function stepLevel(o: PickOption, from: number | null, dir: -1 | 1): number | null;
-/** The whole pick: the header sentence, the options, the free-text
- *  escape hatch, and the honest empty state. */
+/** The whole pick: the band's name, the options, how the keys reach
+ *  them, and the honest empty state. */
 export interface PickSpec {
+    /** the band's NAME (`model`). A legacy `name — words` header still
+     *  splits: the words join the facts. */
     readonly header: string;
     readonly options: readonly PickOption[];
-    /** the `t` row — typing directly. OPTIONAL, and its absence means the
-     *  option list is the WHOLE world: `/model`'s profiles never are (a
-     *  model that exists but is not configured has to be typeable), and
-     *  `/mode`'s five tiers always are. Offering a `t` row over a closed
-     *  set is a row that carries no fact — §1.3 — and it is what made
-     *  the owner read the mode panel as "type the answer". */
-    readonly typeHint?: string;
+    /** Graphite P3: what the band's name says after the count
+     *  (`current: default · don't ask`, `run paused`). */
+    readonly facts?: string;
+    /** Graphite P3: the band counts its options with this noun
+     *  (`profiles` → `9 profiles`, `""` → `11`), and says `2 of 9 match`
+     *  under a filter. Absent, no count. */
+    readonly noun?: string;
+    /** Graphite P3: how keys reach the rows. `digits` (the default): a digit
+     *  moves to that row on screen. `filter`: the input row filters, as in
+     *  /resume — a digit is a letter there. `arrows`: ↑↓ alone. */
+    readonly input?: "digits" | "filter" | "arrows";
+    /** filter only: the input row's words while it is empty */
+    readonly filterHint?: string;
+    /** filter only: a typed `provider/model` that nothing on the list
+     *  matches becomes a row of its own, and ⏎ on it hands the text back. It
+     *  replaced the `t` row (P3, owner, 2026-10-04). Only when NOTHING
+     *  matches: a slash typed into a profile's name (`op/`) is filtering. */
+    readonly direct?: boolean;
+    /** how the columns are styled, by index: `dim` unless `plain` */
+    readonly columns?: readonly ("plain" | "dim")[];
+    /** the column that shows the walked level on the selected row (a
+     *  setting's value follows ←→) */
+    readonly levelColumn?: number;
+    /** what ⏎ does, for the key row (`⏎ switches`); a row may say its own */
+    readonly enter?: string;
     /** shown INSTEAD of the options when there are none. The copy is the
      *  caller's and is reproduced verbatim. */
     readonly emptyNote?: string;
@@ -263,15 +308,42 @@ export interface PickSpec {
      *  pays without anyone choosing to. */
     readonly initial?: number;
 }
-/** The pick panel's runtime state \u2014 the editor owns it, the compositor
- *  reads it (the AskRuntime precedent, two fields instead of five). */
+/** The pick panel's runtime state — the editor owns it, the compositor
+ *  reads it (the AskRuntime precedent). */
 export interface PickRuntime {
+    /** an OPTION index (never a position on screen); `options.length` is
+     *  the direct row. Corrected at read time by `pickList`. */
     readonly cursor: number;
-    readonly phase: "options" | "custom";
     /** OR-7: the level cursor within the highlighted option. null = the
      *  option has no levels, or has no default to mark. */
     readonly level: number | null;
+    /** filter: the input's text, read from the composer on every frame —
+     *  the panel never stores a copy that could disagree with it */
+    readonly query?: string;
+}
+/** Graphite P3 — what the pick shows right now, derived from the spec and
+ *  the runtime: the ONE derivation the renderer, the keys and the digit
+ *  window all read, so the row the eye is on is the row a key acts on. */
+export interface PickList {
+    /** the option indexes on the list, in the caller's order; the direct
+     *  row (`options.length`) last when it is offered */
+    readonly shown: readonly number[];
+    /** the cursor, corrected: an entry of `shown`, or -1 when nothing shows */
+    readonly cursor: number;
+    /** the level in force for the cursor's option */
+    readonly level: number | null;
+    /** the typed letters, per option: which text they landed in (0 the
+     *  label, 1 the first column) and where */
+    readonly hits: ReadonlyMap<number, {
+        readonly col: number;
+        readonly at: readonly number[];
+    }>;
+    /** what the direct row would hand back, when it is offered */
+    readonly direct: string | null;
+    /** the query the list was filtered by ("" when none) */
+    readonly query: string;
 }
+export declare function pickList(spec: PickSpec, state: PickRuntime): PickList;
 /** What was picked: a listed option by INDEX (never a label the caller
  *  would have to re-match against its own list), or typed text. */
 export type PickResult = {
@@ -340,6 +412,17 @@ export interface PanelView {
     /** TUI2-R2 \u2463: the options, when this view is a PICK. Same contract
      *  as `ask`, one payload over. */
     readonly pick?: PickSpec;
+    /** Graphite P1b (owner, 2026-09-30) — kiso's OWN question (a cold
+     *  cache, a call that may have run, an unanswered question, the trust
+     *  gate). Present = the panel opens on the question as its band name
+     *  with the facts dim after it, then at most two sentences at the
+     *  content edge; the gutter keeps only what is quoted verbatim (`args`).
+     *  Absent = the approval layout, unchanged. */
+    readonly asked?: {
+        readonly question: string;
+        readonly facts: readonly string[];
+        readonly prose: string;
+    };
 }
 export type PanelVerdict = {
     readonly action: "allow";
@@ -418,6 +501,14 @@ export interface PanelBlockLayout {
  *  maxRows caps the TOTAL (the args fold; the single-row lines cut). */
 export declare function panelBlockRows(view: PanelView, phase: PanelPhase, cursor: number, W: number, maxRows: number, note?: string, safer?: SaferRuntime): string[];
 export declare function panelBlockLayout(view: PanelView, phase: PanelPhase, cursor: number, W: number, maxRows: number, note?: string, safer?: SaferRuntime): PanelBlockLayout;
+/** Graphite P4's fold for a one-line command; it lives with the card's
+ *  head now, which folds a command the same way (the card round). */
+export { foldAtSpaces };
+/** The key row: the keys, cut by cells, and the counter at the right margin. */
+export declare function panelKeyRow(keys: string, list: {
+    readonly at: number;
+    readonly of: number;
+} | null, W: number): string;
 /**
  * The input row's lead. In the options phase there is NOTHING to type,
  * so the lead stops pretending there is.
@@ -429,11 +520,11 @@ export declare function panelBlockLayout(view: PanelView, phase: PanelPhase, cur
  * a human really is writing — leads with the word for what they are
  * writing.
  */
-export declare function panelLead(view: PanelView, phase: PanelPhase, cursor: number): string;
+export declare function panelLead(_view: PanelView, _phase: PanelPhase, _cursor: number): string;
 /** The lead's plain text — the editor's reflow width (the line must
  *  fit the lead + the drawn cursor's own cell — R2 retired the box and
  *  its walls with it). */
-export declare function panelLeadPlain(view: PanelView, phase: PanelPhase, cursor: number): string;
+export declare function panelLeadPlain(_view: PanelView, _phase: PanelPhase, _cursor: number): string;
 export declare function panelLeadWidth(view: PanelView, phase: PanelPhase, cursor: number): number;
 /** The status row's left text while the panel is up — the phase, not
  *  the CLI's painting status (the compositor derives it from the panel
@@ -449,64 +540,57 @@ export declare function panelStatus(view: PanelView, phase: PanelPhase, cursor:
  */
 export declare function panelAffordance(view: PanelView, phase: PanelPhase, cursor: number, safer?: SaferRuntime): string;
 /**
- * The pick block's rows — the prototype's C frame.
- *
- * The header says what is in effect right now, because the first
- * question anyone opening this panel has is "what am I on?". The
- * options are numbered from 1 and the number IS the key. The `t` row is
- * last and always present: a profile list is a convenience, never the
- * set of models that exist, and a picker that can only offer what
- * someone remembered to configure is a smaller product than the one it
- * replaced.
+ * Graphite P3 (owner, 2026-10-04) — the pick block takes the shape of every
+ * list band (§8.2, §8.13). The band names itself with its count or its
+ * current value; a window of eight rows from a 30-row terminal, five below,
+ * with dim more-marks in column 0; the rows a TABLE, each column measured
+ * over the whole list; the selected row the card head every list shares,
+ * OPENED into a second row on the same wash (the /resume shape) for the
+ * level strip and what the columns cannot hold; one key row with the
+ * counter. No closing rule: the composer's rail closes the band, as it does
+ * the command list.
  *
- * Single-row discipline: every row CUTS, never folds — the block's
- * height is its row count (the W20 rule the #checked throw demands).
- */
-export declare function pickBlockRows(view: PanelView, state: PickRuntime, W: number, maxRows: number): string[];
-/** The digits are the keys, so what one SCREEN offers is still bounded by
- *  the digits there are — but the list itself is no longer bounded by it.
+ * DECLARED REVERSALS (P3, owner, 2026-10-04): the `current:` row (its words
+ * ride the band's name), the bracketed level (the level in force is gold),
+ * the `↕ 1-9 / 11` row (the more-marks say it), PICK_MAX's nine-row window
+ * (§8.2's eight and five), and the `t` row with its typing phase (a typed
+ * `provider/model` is a row of the filter — PickSpec.direct).
  *
- *  Finding DC-58 (the owner, 2026-09-21): this constant used to cap what the
- *  KEYBOARD could reach (`/model` on a 60-profile config offered nine and
- *  said `/model <name>` for the rest). The window now follows the cursor —
- *  `pickWindow` — so PICK_MAX is only how many rows one screen shows, and
- *  ↑↓ walks every option.
+ * Single-row discipline: every row CUTS, never folds — the block's height
+ * is its row count (the W20 rule the #checked throw demands).
  */
+export declare function pickBlockRows(view: PanelView, state: PickRuntime, W: number, maxRows: number, height?: number): string[];
+/** The digits are the keys, so what one SCREEN offers is bounded by the
+ *  digits there are. Finding DC-58 (the owner, 2026-09-21) made the window
+ *  follow the cursor, so this is how many rows a digit can name, not how
+ *  many rows the keyboard reaches. */
 export declare const PICK_MAX = 9;
-/** The option window the pick panel draws and the digits name: `size` rows
- *  starting at `first`, with `first` derived from the cursor so it cannot
- *  drift from it. Edge-following (the window starts moving only when the
- *  cursor leaves it) and clamped at both ends, so the last page is full
- *  rather than short.
- *
- *  Pure, and the ONE copy: the renderer, the digit keys and the click
- *  hit-test all ask this function rather than each deriving an offset.
- */
-/** The pick panel's window for THIS frame's budget — the one derivation the
- *  renderer and the input layer share (review of this round).
+/**
+ * The pick's window for THIS frame — the one derivation the renderer and
+ * the digit keys share (DC-58's review: a size derived twice is a size that
+ * can disagree). Positions are into `pickList(...).shown`.
  *
- *  The renderer draws it; `Dock.visiblePickWindow` hands the SAME value to the
- *  digit keys, because a size derived twice is a size that can disagree — and
- *  on a short terminal it did (two rows drawn, nine assumed, so `1` could mean
- *  a row nobody could see). `phase` is compared as a string so this module
- *  keeps its zero-dependency contract.
+ * Graphite P3: §8.2's window (eight rows from a 30-row terminal, five
+ * below, the cursor kept a row inside an edge while more lies past it),
+ * within the frame's budget: the band's name, the key row, the opened row
+ * and a `nothing matches` row are the chrome.
  */
-export declare function pickWindowOf(view: PanelView, cursor: number, phase: string, maxRows: number): {
-    first: number;
-    size: number;
-};
-export declare function pickWindow(cursor: number, count: number, size: number): {
+export declare function pickWindowOf(view: PanelView, state: PickRuntime, maxRows: number, height?: number): {
     first: number;
     size: number;
 };
-/** The input row's lead: the digit range while picking, the named
- *  prompt while typing one out. */
-export declare function pickLeadPlain(view: PanelView, state: PickRuntime): string;
-export declare function pickLead(view: PanelView, state: PickRuntime): string;
-/** The status row's left text \u2014 the CALLER's, because only the caller
- *  knows whether a run is paused behind this panel. */
+/** The input row's lead. Graphite P3: a pick leaves the input row to the
+ *  composer — the filter is typed there, and a digit list needs no lead
+ *  to say so (its key row does). */
+export declare function pickLeadPlain(_view: PanelView, _state: PickRuntime): string;
+export declare function pickLead(_view: PanelView, _state: PickRuntime): string;
+/** The status row's left text — the CALLER's, because only the caller
+ *  knows whether a run is paused behind this panel. (Graphite P3: on a
+ *  dock the bar stays under a pick; this is the dock-less text.) */
 export declare function pickStatus(view: PanelView): string;
-export declare function pickAffordance(state: PickRuntime, axis?: boolean): string;
+/** The key words, for a caller that draws them outside the block. The
+ *  block's own key row is the one on screen (P3). */
+export declare function pickAffordance(_state: PickRuntime, axis?: boolean | string): string;
 /** Compose a pick view. The flavor/name/title/args fields exist for the
  *  approval path and are given inert values here \u2014 the pick block
  *  reads none of them. */
@@ -518,6 +602,9 @@ export declare function pickAffordance(state: PickRuntime, axis?: boolean): stri
  *  `pick` and `statusText`, so a second flavour is a name and a
  *  fallback question, not a second mechanism. */
 export declare function modePickView(spec: PickSpec, statusText: string): PanelView;
+/** Graphite R3e — `/settings` as a pick panel: a row per setting, the
+ *  session's own ones with a second axis to walk. */
+export declare function settingsPickView(spec: PickSpec, statusText: string): PanelView;
 /** ADR-0058 (3e): the `/tasks` list, a task's actions, and the exit
  *  question — the same pick panel as /mode and /model, under its name. */
 export declare function namedPickView(name: string, spec: PickSpec, statusText: string, fallbackQuestion: string): PanelView;