@sagmans/dsh-tui 0.3.0 → 0.5.0

package/lib/ui/layout.d.ts

@@ -0,0 +1,33 @@
+import { VStack, type Component } from '@earendil-works/pi-tui';
+/**
+ * The rows the input bar keeps when every other row is contested.
+ *
+ * The frame's two rules and one row of text: a bar that cannot show what the
+ * reader is typing is not a bar, so this floor is reserved before any work
+ * summary is allowed a row.
+ */
+export declare const PROMPT_MIN_ROWS = 3;
+/** The parts of the surface the root layout stacks, top to bottom. */
+export interface SurfaceParts {
+    /** The transcript viewport, which takes every row nothing else claims. */
+    readonly transcript: Component;
+    /** The work board: goals, plans, running jobs, and running subagents. */
+    readonly dock: Component;
+    /** The prompts waiting behind the running turn. */
+    readonly queue: Component;
+    /** The prompt bar, borrowed when a question is answered in it. */
+    readonly prompt: Component;
+    /** The footer. */
+    readonly status: Component;
+}
+/**
+ * Stack the surface, deciding who gives up rows when the terminal is short.
+ *
+ * The transcript grows into whatever is left; the dock, the queue, and the bar
+ * shrink in that order of eagerness, and the bar keeps a floor no shrink can
+ * take. A dock that could not shrink held its whole height on a short terminal
+ * and pushed the draft, its frame, and the footer out of the frame entirely,
+ * because a clipped leaf cannot restore rows the allocator never gave it.
+ */
+export declare function surfaceLayout(parts: SurfaceParts): VStack;
+//# sourceMappingURL=layout.d.ts.map

package/lib/ui/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/ui/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B,kBAAkB;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAazD"}

package/lib/ui/layout.js

@@ -0,0 +1,33 @@
+import { VStack } from '@earendil-works/pi-tui';
+/**
+ * The rows the input bar keeps when every other row is contested.
+ *
+ * The frame's two rules and one row of text: a bar that cannot show what the
+ * reader is typing is not a bar, so this floor is reserved before any work
+ * summary is allowed a row.
+ */
+export const PROMPT_MIN_ROWS = 3;
+/**
+ * Stack the surface, deciding who gives up rows when the terminal is short.
+ *
+ * The transcript grows into whatever is left; the dock, the queue, and the bar
+ * shrink in that order of eagerness, and the bar keeps a floor no shrink can
+ * take. A dock that could not shrink held its whole height on a short terminal
+ * and pushed the draft, its frame, and the footer out of the frame entirely,
+ * because a clipped leaf cannot restore rows the allocator never gave it.
+ */
+export function surfaceLayout(parts) {
+    return new VStack([
+        { component: parts.transcript, basis: 0, grow: 1, minSize: 1 },
+        // Work state earns rows only when there is some, and it gives them up first:
+        // a job ticker is worth less than the input the reader is typing into.
+        { component: parts.dock, basis: 'auto', shrink: 2, minSize: 0 },
+        // Queued input earns rows only while something is waiting, and it gives
+        // them up before the editor does: the bar being typed in outranks what is
+        // waiting behind it.
+        { component: parts.queue, basis: 'auto', shrink: 2, minSize: 0 },
+        { component: new VStack([{ component: parts.prompt, basis: 'auto', shrink: 1, minSize: 1 }]), basis: 'auto', shrink: 1, minSize: PROMPT_MIN_ROWS },
+        { component: parts.status, basis: 'auto', shrink: 0, minSize: 1 },
+    ]);
+}
+//# sourceMappingURL=layout.js.map

package/lib/ui/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/ui/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAA;AAgBhC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,OAAO,IAAI,MAAM,CAAC;QAChB,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAC9D,6EAA6E;QAC7E,uEAAuE;QACvE,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAC/D,wEAAwE;QACxE,0EAA0E;QAC1E,qBAAqB;QACrB,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAChE,EAAE,SAAS,EAAE,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE;QAClJ,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;KAClE,CAAC,CAAA;AACJ,CAAC"}

package/lib/ui/markdown.d.ts

@@ -1,9 +1,29 @@
-import { type MarkdownTheme } from '@earendil-works/pi-tui';
+import { type DefaultTextStyle, type MarkdownTheme } from '@earendil-works/pi-tui';
 import type { MermaidTransform } from './mermaid.ts';
 /** Parsed messages kept for redraws; everything above this is cold transcript. */
 export declare const MARKDOWN_CACHE_LIMIT = 64;
 /**
- * Render assistant text as markdown without reparsing the whole history.
+ * How a row is based where the markdown itself has no rule for the text.
+ *
+ * Two rows can carry identical words and still have to draw differently — a
+ * prompt repeated as a reply, a thought quoted in an answer — and a parse is
+ * cached with the lines it drew, so the face is part of what identifies a parse
+ * rather than a detail of one drawing.
+ */
+export interface MarkdownFace {
+    /** Names the face in the parse cache; two faces never share a parse. */
+    readonly name: string;
+    /** The shade text keeps where the markdown has no rule for it. */
+    readonly base?: DefaultTextStyle;
+    /** A theme of this face's own, for a row the answer's colours would outshine. */
+    readonly theme?: MarkdownTheme;
+    /** Whether this face asks the renderer's transform for a drawing; a thought's does not. */
+    readonly transform?: boolean;
+}
+/** The face an answer is drawn in: the reader's markdown theme, drawings included. */
+export declare const ANSWER_FACE: MarkdownFace;
+/**
+ * Render one message as markdown without reparsing the whole history.
  *
  * A repaint walks every row, so parsing each message again on every keystroke
  * would make a long session crawl. Parsing is keyed by message text because
@@ -14,12 +34,14 @@ export declare class MarkdownRenderer {
     private readonly mermaid?;
     private readonly parsed;
     constructor(theme: MarkdownTheme, mermaid?: MermaidTransform | undefined);
-    render(text: string, width: number, live?: boolean): string[];
+    render(text: string, width: number, live?: boolean, face?: MarkdownFace): string[];
     /**
      * The parse options this renderer installs, absent when nothing transforms.
      *
      * The flag is captured rather than read per call: the component caches the
      * rows it drew, so the value that built it is the only one it could honour.
+     * A face that refuses the transform keeps its fences as source, which is how a
+     * diagram cannot take over a row that was meant to stay subordinate.
      */
     private options;
     /**

package/lib/ui/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/ui/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAiB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAF5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;gBAExB,KAAK,EAAE,aAAa,EAAmB,OAAO,CAAC,EAAE,gBAAgB,YAAA;IAE9F,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,MAAM,EAAE;IAqB3D;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAMf;;;;;;OAMG;IACH,UAAU,IAAI,IAAI;CAInB"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/ui/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,gBAAgB,EAAwB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAClH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEpD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,sFAAsF;AACtF,eAAO,MAAM,WAAW,EAAE,YAAiC,CAAA;AAE3D;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAiB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAF5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;gBAExB,KAAK,EAAE,aAAa,EAAmB,OAAO,CAAC,EAAE,gBAAgB,YAAA;IAE9F,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,UAAQ,EAAE,IAAI,GAAE,YAA0B,GAAG,MAAM,EAAE;IAqB7F;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAMf;;;;;;OAMG;IACH,UAAU,IAAI,IAAI;CAInB"}

package/lib/ui/markdown.js

@@ -1,8 +1,10 @@
 import { Markdown } from '@earendil-works/pi-tui';
 /** Parsed messages kept for redraws; everything above this is cold transcript. */
 export const MARKDOWN_CACHE_LIMIT = 64;
+/** The face an answer is drawn in: the reader's markdown theme, drawings included. */
+export const ANSWER_FACE = { name: 'answer' };
 /**
- * Render assistant text as markdown without reparsing the whole history.
+ * Render one message as markdown without reparsing the whole history.
  *
  * A repaint walks every row, so parsing each message again on every keystroke
  * would make a long session crawl. Parsing is keyed by message text because
@@ -16,12 +18,12 @@ export class MarkdownRenderer {
         this.theme = theme;
         this.mermaid = mermaid;
     }
-    render(text, width, live = false) {
+    render(text, width, live = false, face = ANSWER_FACE) {
         // A streaming reply can settle on the very text it last streamed, and the
         // two renderings are not the same: only a settled one may report what a
-        // drawing lost, and a mode may draw one and withhold the other. The flag is
-        // part of a message's identity for the same reason the text is.
-        const key = live ? `live\u0000${text}` : `settled\u0000${text}`;
+        // drawing lost, and a mode may draw one and withhold the other. The flag and
+        // the face are part of a message's identity for the same reason the text is.
+        const key = `${face.name}\u0000${live ? 'live' : 'settled'}\u0000${text}`;
         let message = this.parsed.get(key);
         if (message === undefined) {
             if (this.parsed.size >= MARKDOWN_CACHE_LIMIT) {
@@ -29,7 +31,7 @@ export class MarkdownRenderer {
                 if (oldest.done !== true)
                     this.parsed.delete(oldest.value);
             }
-            message = new Markdown(text, 0, 0, this.theme, undefined, this.options(live));
+            message = new Markdown(text, 0, 0, face.theme ?? this.theme, face.base, this.options(face, live));
         }
         else {
             // Reinserting keeps a message that is still on screen from ageing out.
@@ -43,10 +45,12 @@ export class MarkdownRenderer {
      *
      * The flag is captured rather than read per call: the component caches the
      * rows it drew, so the value that built it is the only one it could honour.
+     * A face that refuses the transform keeps its fences as source, which is how a
+     * diagram cannot take over a row that was meant to stay subordinate.
      */
-    options(live) {
+    options(face, live) {
         const mermaid = this.mermaid;
-        if (mermaid === undefined)
+        if (mermaid === undefined || face.transform === false)
             return undefined;
         return { transform: (markdown, availableWidth) => mermaid(markdown, availableWidth, live) };
     }

package/lib/ui/markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/ui/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA4C,MAAM,wBAAwB,CAAA;AAG3F,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAGE;IAAuC;IAFnD,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAA;IAErD,YAA6B,KAAoB,EAAmB,OAA0B;QAAjE,UAAK,GAAL,KAAK,CAAe;QAAmB,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IAElG,MAAM,CAAC,IAAY,EAAE,KAAa,EAAE,IAAI,GAAG,KAAK;QAC9C,0EAA0E;QAC1E,wEAAwE;QACxE,4EAA4E;QAC5E,gEAAgE;QAChE,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAA;QAC/D,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,oBAAoB,EAAE,CAAC;gBAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;gBACxC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;oBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAC5D,CAAC;YACD,OAAO,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;QAC/E,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACvD,CAAC;IAED;;;;;OAKG;IACK,OAAO,CAAC,IAAa;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC5B,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QAC3C,OAAO,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,CAAA;IAC7F,CAAC;IAED;;;;;;OAMG;IACH,UAAU;QACR,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,OAAO,CAAC,UAAU,EAAE,CAAA;QAChE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF"}
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/ui/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmE,MAAM,wBAAwB,CAAA;AAGlH,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAqBtC,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAGE;IAAuC;IAFnD,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAA;IAErD,YAA6B,KAAoB,EAAmB,OAA0B;QAAjE,UAAK,GAAL,KAAK,CAAe;QAAmB,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IAElG,MAAM,CAAC,IAAY,EAAE,KAAa,EAAE,IAAI,GAAG,KAAK,EAAE,OAAqB,WAAW;QAChF,0EAA0E;QAC1E,wEAAwE;QACxE,6EAA6E;QAC7E,6EAA6E;QAC7E,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,SAAS,IAAI,EAAE,CAAA;QACzE,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,oBAAoB,EAAE,CAAC;gBAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;gBACxC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;oBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAC5D,CAAC;YACD,OAAO,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;QACnG,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACvD,CAAC;IAED;;;;;;;OAOG;IACK,OAAO,CAAC,IAAkB,EAAE,IAAa;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC5B,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK;YAAE,OAAO,SAAS,CAAA;QACvE,OAAO,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,CAAA;IAC7F,CAAC;IAED;;;;;;OAMG;IACH,UAAU;QACR,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,OAAO,CAAC,UAAU,EAAE,CAAA;QAChE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF"}

package/lib/ui/picker-card.d.ts

@@ -0,0 +1,42 @@
+import { type Component, type SizeValue } from '@earendil-works/pi-tui';
+import type { TuiTheme } from '../theme.ts';
+import type { PickerCard } from './picker.ts';
+/**
+ * The rows a list draws, wherever it is drawn.
+ *
+ * One renderer for the card, so the list at the end of the transcript and the
+ * box over it cannot drift apart: a field added to a card reaches both at once.
+ * The width is the room the rows themselves have, which is what a frame around
+ * them narrows before it is asked for.
+ */
+export declare function pickerCardLines(picker: PickerCard, width: number, theme: TuiTheme): string[];
+/** The same share as the library resolves a percentage SizeValue, so the option and the row budget cannot disagree. */
+export declare const POPUP_MAX_HEIGHT: SizeValue;
+/** The columns the box may take on a terminal this wide. */
+export declare function popupWidth(columns: number): number;
+/** The rows the box may occupy, resolved the way the library resolves a percentage. */
+export declare function popupHeight(rows: number): number;
+/** How many list rows fit in that height, with the frame's own rows and the scroll counts reserved. */
+export declare function popupRowBudget(rows: number): number;
+/**
+ * A list drawn as a box over the surface rather than at the end of it.
+ *
+ * The box is only a frame: the rows, the filter, and the counts are the card's,
+ * which the list builds to whatever budget this component can afford. A screen
+ * too short for the whole card shrinks the window rather than the box, because
+ * the hint naming the keys that close it is the last thing that may fall off.
+ */
+export declare class PickerPopup implements Component {
+    private readonly card;
+    /** The terminal the box is drawn on, read per paint so a resize lands on the next frame. */
+    private readonly rows;
+    private readonly theme;
+    constructor(card: (rows: number) => PickerCard | undefined, 
+    /** The terminal the box is drawn on, read per paint so a resize lands on the next frame. */
+    rows: () => number, theme: TuiTheme);
+    invalidate(): void;
+    /** The card closed into a frame, or nothing when the list is already gone. */
+    private box;
+    render(width: number): string[];
+}
+//# sourceMappingURL=picker-card.d.ts.map

package/lib/ui/picker-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker-card.d.ts","sourceRoot":"","sources":["../../src/ui/picker-card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAkC,MAAM,wBAAwB,CAAA;AAEvG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAoB7C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,EAAE,CAkC5F;AAuBD,uHAAuH;AACvH,eAAO,MAAM,gBAAgB,EAAE,SAAgC,CAAA;AAE/D,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;GAOG;AACH,qBAAa,WAAY,YAAW,SAAS;IAEzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAHL,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS;IAC/D,4FAA4F;IAC3E,IAAI,EAAE,MAAM,MAAM,EAClB,KAAK,EAAE,QAAQ;IAGlC,UAAU,IAAI,IAAI;IAIlB,8EAA8E;IAC9E,OAAO,CAAC,GAAG;IAWX,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;CAchC"}

package/lib/ui/picker-card.js

@@ -0,0 +1,148 @@
+import { visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { canFrame, frameLines, FRAME_COLUMNS } from "./frame.js";
+/** The columns a list's rows are indented by, and the ones a wrapped line under them uses. */
+const ROW_INDENT = '   ';
+const TEXT_INDENT = '    ';
+/** The mark a cursor falls back to when the reader has not set one, so no literal lives in a template. */
+const CURSOR_MARK = '❯';
+/** An unselected row has no cursor, and a blank column is not a value to configure. */
+const NO_CURSOR = ' ';
+/** One wrapped block of plain text under a prefix, at the width the card has. */
+function pushWrapped(lines, text, width, prefix, token, theme) {
+    const lead = visibleWidth(prefix);
+    const indent = ' '.repeat(lead);
+    const wrapped = wrapTextWithAnsi(theme.rich(text, { token, column: lead }), Math.max(1, width - lead));
+    wrapped.forEach((line, index) => {
+        lines.push(theme.cut(`${index === 0 ? prefix : indent}${line}`, width, ''));
+    });
+}
+/**
+ * The rows a list draws, wherever it is drawn.
+ *
+ * One renderer for the card, so the list at the end of the transcript and the
+ * box over it cannot drift apart: a field added to a card reaches both at once.
+ * The width is the room the rows themselves have, which is what a frame around
+ * them narrows before it is asked for.
+ */
+export function pickerCardLines(picker, width, theme) {
+    const lines = [];
+    if (theme.visible('picker.title')) {
+        const glyph = theme.glyph('picker.glyph');
+        const lead = glyph === '' ? '' : `${glyph} `;
+        lines.push(theme.cut(theme.rich(`${lead}${picker.title}`, { token: 'picker.title', column: visibleWidth(lead) }), width, ''));
+    }
+    if (picker.note !== undefined && theme.visible('picker.note')) {
+        pushWrapped(lines, picker.note, width, TEXT_INDENT, 'picker.note', theme);
+    }
+    if (picker.filter !== '' && theme.visible('picker.filter')) {
+        lines.push(theme.cut(theme.rich(`${TEXT_INDENT}filter: ${picker.filter}`, { token: 'picker.filter', column: visibleWidth(TEXT_INDENT) }), width, ''));
+    }
+    if (picker.above > 0 && theme.visible('picker.scrollNewer')) {
+        lines.push(theme.style('picker.scrollNewer', theme.cut(`${ROW_INDENT}… ${picker.above} newer`, width, '')));
+    }
+    for (const row of picker.rows) {
+        const token = row.current ? 'picker.rowCurrent' : 'picker.row';
+        if (!theme.visible(token))
+            continue;
+        const cursor = row.current ? theme.glyph('picker.cursor') || CURSOR_MARK : NO_CURSOR;
+        const text = row.description === undefined
+            ? `${cursor} ${row.label}`
+            : `${cursor} ${row.label} — ${row.description}`;
+        lines.push(theme.cut(theme.rich(`${ROW_INDENT}${text}`, { token, column: visibleWidth(ROW_INDENT) }), width, ''));
+    }
+    if (picker.below > 0 && theme.visible('picker.scrollOlder')) {
+        lines.push(theme.style('picker.scrollOlder', theme.cut(`${ROW_INDENT}… ${picker.below} older`, width, '')));
+    }
+    if (theme.visible('picker.hint')) {
+        // The hint names the keys that leave the list, so it folds rather than
+        // being cut: a narrow screen must still be told the way out.
+        pushWrapped(lines, picker.hint, width, ROW_INDENT, 'picker.hint', theme);
+    }
+    return lines;
+}
+/**
+ * Share of the terminal a popup may take.
+ *
+ * The box is an overlay on work the reader is in the middle of, so it never
+ * claims the screen: the rows behind it stay the context for what is being
+ * chosen, and the editor stays where the reader left it.
+ */
+const HEIGHT_PERCENT = 80;
+/** Air between the box and the terminal's edge, so the frame never touches one. */
+const MARGIN = 1;
+/** A box narrower than this cannot name an action and its keys on one row. */
+const MIN_WIDTH = 40;
+/** Past this the rows are mostly empty, and a list reads better narrow than stretched. */
+const MAX_WIDTH = 100;
+/** Rows the box spends before the list itself: two rules, the heading, the filter line, and the hint. */
+const CHROME_ROWS = 5;
+/** Rows the two scroll counts may take when the list is longer than the window. */
+const MARKER_ROWS = 2;
+/** A list that can show a row and still say the map continues. */
+const MIN_ROWS = 3;
+/** The same share as the library resolves a percentage SizeValue, so the option and the row budget cannot disagree. */
+export const POPUP_MAX_HEIGHT = `${HEIGHT_PERCENT}%`;
+/** The columns the box may take on a terminal this wide. */
+export function popupWidth(columns) {
+    return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, columns - MARGIN * 2));
+}
+/** The rows the box may occupy, resolved the way the library resolves a percentage. */
+export function popupHeight(rows) {
+    return Math.floor((rows * HEIGHT_PERCENT) / 100);
+}
+/** How many list rows fit in that height, with the frame's own rows and the scroll counts reserved. */
+export function popupRowBudget(rows) {
+    return Math.max(MIN_ROWS, popupHeight(rows) - CHROME_ROWS - MARKER_ROWS);
+}
+/**
+ * A list drawn as a box over the surface rather than at the end of it.
+ *
+ * The box is only a frame: the rows, the filter, and the counts are the card's,
+ * which the list builds to whatever budget this component can afford. A screen
+ * too short for the whole card shrinks the window rather than the box, because
+ * the hint naming the keys that close it is the last thing that may fall off.
+ */
+export class PickerPopup {
+    card;
+    rows;
+    theme;
+    constructor(card, 
+    /** The terminal the box is drawn on, read per paint so a resize lands on the next frame. */
+    rows, theme) {
+        this.card = card;
+        this.rows = rows;
+        this.theme = theme;
+    }
+    invalidate() {
+        // Nothing is cached: the card is read fresh on every frame.
+    }
+    /** The card closed into a frame, or nothing when the list is already gone. */
+    box(picker, width) {
+        if (picker === undefined)
+            return [];
+        const framed = canFrame(width, this.theme.visible('picker.border'));
+        const inside = framed ? width - FRAME_COLUMNS : width;
+        return frameLines(pickerCardLines(picker, inside, this.theme), width, {
+            text: line => line,
+            border: rule => this.theme.style('picker.border', rule),
+            framed,
+        });
+    }
+    render(width) {
+        if (width <= 0)
+            return [];
+        const rows = this.rows();
+        const room = popupHeight(rows);
+        let budget = popupRowBudget(rows);
+        for (;;) {
+            const lines = this.box(this.card(budget), width);
+            // A refusal note can spend rows the budget did not reserve, so a card that
+            // still overflows asks for a shorter window rather than lose its closing
+            // rule to the library's own clamp.
+            if (lines.length <= room || budget <= MIN_ROWS)
+                return lines;
+            budget = Math.max(MIN_ROWS, budget - (lines.length - room));
+        }
+    }
+}
+//# sourceMappingURL=picker-card.js.map

package/lib/ui/picker-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker-card.js","sourceRoot":"","sources":["../../src/ui/picker-card.ts"],"names":[],"mappings":"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"}

package/lib/ui/picker.d.ts

@@ -46,6 +46,14 @@ export interface PickerHints {
     readonly empty: () => string;
     readonly listed: () => string;
 }
+/**
+ * Fold a value onto one drawn row.
+ *
+ * A filter can be seeded from a multiline draft or typed through a paste, and a
+ * raw newline inside a row would push the frame's own accounting apart; the
+ * needle the list matches with stays untouched.
+ */
+export declare function singleLine(text: string): string;
 /** Human age of a session, so a list of ids becomes a list of moments. */
 export declare function describeAge(createdAt: number, now: number): string;
 /**
@@ -68,6 +76,15 @@ export declare class ListPicker<Row> {
     private readonly hints;
     /** The keys in force, read per press so a settings edit lands on the next key. */
     private readonly keys;
+    /**
+     * Told which row the cursor is on whenever it moves.
+     *
+     * A list whose rows can be shown as well as taken needs the row under the
+     * cursor before it is picked — a theme is judged by looking at the screen it
+     * paints — and only the list knows where the cursor landed once a filter has
+     * reordered the rows under it.
+     */
+    private readonly onCursor?;
     private cursor;
     private filter;
     private note;
@@ -77,7 +94,18 @@ export declare class ListPicker<Row> {
     /** Extra text the filter matches besides the row's own label. */
     haystackOf: (row: Row) => string, hints: PickerHints, 
     /** The keys in force, read per press so a settings edit lands on the next key. */
-    keys: () => Keymap);
+    keys: () => Keymap, 
+    /** A draft to open already filtered by, so a search can start where the reader is. */
+    initialFilter?: string, 
+    /**
+     * Told which row the cursor is on whenever it moves.
+     *
+     * A list whose rows can be shown as well as taken needs the row under the
+     * cursor before it is picked — a theme is judged by looking at the screen it
+     * paints — and only the list knows where the cursor landed once a filter has
+     * reordered the rows under it.
+     */
+    onCursor?: ((row: Row | undefined) => void) | undefined);
     /** Rows matching the typed filter, best match first. */
     visible(): readonly Row[];
     /**
@@ -90,7 +118,27 @@ export declare class ListPicker<Row> {
     setNote(text: string | undefined): void;
     /** Apply one key press; returns an action only when the picker settles. */
     handleKey(data: string): PickerAction | undefined;
-    card(): PickerCard;
+    /**
+     * Say which row the cursor is on now.
+     *
+     * Announced after every press rather than on the arrows alone: typing a filter
+     * moves the cursor to the best match, and a row the filter just hid must not
+     * stay on screen as the one being shown. A filter that matches nothing reports
+     * no row, which is the one answer that is not a row.
+     */
+    private announce;
+    /** One key press, without the announcement every way out of it owes. */
+    private step;
+    /**
+     * The card as it draws right now, in the window the caller can afford.
+     *
+     * The window is a parameter because the caller is the one that knows how many
+     * rows it has to give: a list at the end of the transcript takes the usual
+     * window whatever the terminal, while a box over it has to leave room for its
+     * own frame on a short screen. The rule stays here, so both windows keep the
+     * cursor centred and the counts above and below honest.
+     */
+    card(window?: number): PickerCard;
 }
 /**
  * One stored session chosen by key press.

package/lib/ui/picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../src/ui/picker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../src/ui/picker.ts"],"names":[],"mappings":"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"}

package/lib/ui/picker.js

@@ -12,6 +12,18 @@ import { describePreset } from "../agent/presets.js";
  * window stays around the cursor instead, and the counts say what is hidden.
  */
 export const PICKER_WINDOW = 12;
+/** Runs of whitespace, including the newlines a seeded draft or a paste can carry. */
+const WHITESPACE = /\s+/gu;
+/**
+ * Fold a value onto one drawn row.
+ *
+ * A filter can be seeded from a multiline draft or typed through a paste, and a
+ * raw newline inside a row would push the frame's own accounting apart; the
+ * needle the list matches with stays untouched.
+ */
+export function singleLine(text) {
+    return text.replace(WHITESPACE, ' ').trim();
+}
 const MINUTE_MS = 60_000;
 const HOUR_MS = 60 * MINUTE_MS;
 const DAY_MS = 24 * HOUR_MS;
@@ -43,6 +55,7 @@ export class ListPicker {
     haystackOf;
     hints;
     keys;
+    onCursor;
     cursor = 0;
     filter = '';
     note;
@@ -52,7 +65,18 @@ export class ListPicker {
     /** Extra text the filter matches besides the row's own label. */
     haystackOf, hints, 
     /** The keys in force, read per press so a settings edit lands on the next key. */
-    keys) {
+    keys, 
+    /** A draft to open already filtered by, so a search can start where the reader is. */
+    initialFilter = '', 
+    /**
+     * Told which row the cursor is on whenever it moves.
+     *
+     * A list whose rows can be shown as well as taken needs the row under the
+     * cursor before it is picked — a theme is judged by looking at the screen it
+     * paints — and only the list knows where the cursor landed once a filter has
+     * reordered the rows under it.
+     */
+    onCursor) {
         this.source = source;
         this.heading = heading;
         this.idOf = idOf;
@@ -60,6 +84,8 @@ export class ListPicker {
         this.haystackOf = haystackOf;
         this.hints = hints;
         this.keys = keys;
+        this.onCursor = onCursor;
+        this.filter = initialFilter;
     }
     /** Rows matching the typed filter, best match first. */
     visible() {
@@ -86,6 +112,29 @@ export class ListPicker {
     }
     /** Apply one key press; returns an action only when the picker settles. */
     handleKey(data) {
+        const action = this.step(data);
+        // A press that settles the list needs no announcement: the row it settled on
+        // is the row already on screen.
+        if (action === undefined)
+            this.announce();
+        return action;
+    }
+    /**
+     * Say which row the cursor is on now.
+     *
+     * Announced after every press rather than on the arrows alone: typing a filter
+     * moves the cursor to the best match, and a row the filter just hid must not
+     * stay on screen as the one being shown. A filter that matches nothing reports
+     * no row, which is the one answer that is not a row.
+     */
+    announce() {
+        if (this.onCursor === undefined)
+            return;
+        const rows = this.visible();
+        this.onCursor(rows[Math.min(this.cursor, Math.max(0, rows.length - 1))]);
+    }
+    /** One key press, without the announcement every way out of it owes. */
+    step(data) {
         this.note = undefined;
         const rows = this.visible();
         // A picker owns the keyboard while it is open, so the interrupt key has to
@@ -122,21 +171,31 @@ export class ListPicker {
         }
         return undefined;
     }
-    card() {
+    /**
+     * The card as it draws right now, in the window the caller can afford.
+     *
+     * The window is a parameter because the caller is the one that knows how many
+     * rows it has to give: a list at the end of the transcript takes the usual
+     * window whatever the terminal, while a box over it has to leave room for its
+     * own frame on a short screen. The rule stays here, so both windows keep the
+     * cursor centred and the counts above and below honest.
+     */
+    card(window = PICKER_WINDOW) {
         const rows = this.visible();
         const cursor = Math.min(this.cursor, Math.max(0, rows.length - 1));
-        const start = Math.max(0, Math.min(cursor - Math.floor(PICKER_WINDOW / 2), rows.length - PICKER_WINDOW));
-        const window = rows.slice(start, start + PICKER_WINDOW);
+        const size = Math.max(1, Math.min(window, rows.length));
+        const start = Math.max(0, Math.min(cursor - Math.floor(size / 2), rows.length - size));
+        const shown = rows.slice(start, start + size);
         return {
             title: this.heading(),
             note: this.note,
-            rows: window.map((row, index) => ({
+            rows: shown.map((row, index) => ({
                 ...this.describe(row),
                 current: start + index === cursor,
             })),
             above: start,
-            below: Math.max(0, rows.length - start - window.length),
-            filter: this.filter,
+            below: Math.max(0, rows.length - start - shown.length),
+            filter: singleLine(this.filter),
             hint: rows.length === 0 ? this.hints.empty() : this.hints.listed(),
         };
     }