@aiwayds/dsh-tui-pi 0.22.0 → 0.23.0

package/README.md

@@ -201,12 +201,13 @@ There's no slash command to toggle the feature — it's always on, controlled by
 
 While the model is mid-turn it can pause and ask you structured questions via the `ask_user_question` tool (`@deepseek-ai/dsh-tool-ask-user`, mounted by this profile's bundle patch). The TUI hosts the answering side: a bordered panel pins itself directly above the chat input (the Todos-panel slot — no floating popup), takes the keyboard while open, the tool call stays pending until you answer, and your answers flow back to the model as a normal tool result.
 
-- **One panel, all questions flattened** — every question renders as a header row followed by its supporting `detail` text (when the model supplies any), option rows, plus a `Type something.` sentinel row for free text. Single-select replaces on Enter; multi-select toggles (`[+]` marks).
+- **One question at a time, tabs for the rest** — with several questions the panel shows exactly ONE question block (header row + supporting `detail` text, option rows, plus a `Type something.` sentinel row for free text); a tab strip under the title (`[1] · 2✓ · 3` — brackets mark the focused tab, ✓ an answered one) folds the other questions away. `←`/`→` (and Tab/Shift-Tab) switch tabs; answering a single-select tab auto-advances to the next unanswered one (or onto the Confirm row once everything is answered). Single-select replaces on Enter; multi-select toggles (`●`/`○` marks) and never auto-advances.
+- **Ctrl+T folds the panel to a 3-line strip** — the questions panel can block the transcript it stacks on while you think; Ctrl+T collapses it to borders + one summary line (phase, tab position, answered count, how to expand) and the same key unfolds it. While folded only the toggle and the Esc chain act; folding mid-edit commits the buffer like the ↑↓ arrow-exit does.
 - **Single-question fast path** — a lone single-select question submits immediately on Enter: picking an option or committing typed free text both submit right away (a question without options is answered by typing alone). A lone multiSelect question instead gets a `⏎ Confirm answers` row so you can pick several options before submitting.
-- **Multi-question review page** — with ≥ 2 questions a `⏎ Confirm answers` row hops to a review listing every answer, each row editable in place; `Submit answers` commits (Enter on it while an answer is missing flashes a hint instead of failing silently). After committing free text on one question the cursor hops to the next unanswered one.
+- **Multi-question review page** — with ≥ 2 questions a `⏎ Confirm answers` row hops to a review listing every answer, each row editable in place (jumping back re-focuses that question's tab); `Submit answers` commits (Enter on it while an answer is missing flashes a hint instead of failing silently).
 - **Double-Esc declines** — two Esc presses within 200 ms return a declined envelope (the model reads it as a normal reply that no answer was given); holding Esc does not accidentally fire (key auto-repeat below a minimum gap is ignored), and the tool call being aborted settles as declined too. While the panel is open it owns the keyboard exactly like an open overlay: Esc never arms the running-task stop, and app keys (Ctrl+L/G/O, Tab) yield to the panel.
 - **Conservative-use guidance** — a system-prompt section nudges the model to ask only when it genuinely needs you (1–3 questions, 2–4 options each), so the TUI doesn't turn into a questionnaire.
-- **Keyboard** — `↑↓` navigate · `Enter` select/toggle/confirm · type into the sentinel for free text · `Esc` twice to decline.
+- **Keyboard** — `←→` switch question tabs · `↑↓` navigate · `Enter` select/toggle/confirm · type into the sentinel for free text · `Ctrl+T` fold/unfold the panel · `Esc` twice to decline.
 
 Inspired by [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question).
 
@@ -304,8 +305,9 @@ Precedence per field: an explicit value in settings.yaml > the
 `DSH_TUI_RETENTION_MAX_COUNT` / `DSH_TUI_RETENTION_MAX_AGE_DAYS` /
 `DSH_TUI_RETENTION_MIN_IDLE_HOURS` and `DSH_TUI_RESUME_MAX_AGE_DAYS` /
 `DSH_TUI_RESUME_MIN_BYTES` environment variables > the defaults above.
-An invalid settings value warns once on stderr and falls to the next
-level; an invalid env value falls back silently to the default — a typo
+An invalid settings value surfaces a transient notice via the shared
+notice bridge (silently dropped when no TUI sink is registered — headless
+runs never print it) and falls to the next level; an invalid env value — a typo
 never widens or guts the policy. `maxCount` and `minBytes` must be
 integers at every layer (a fractional cap or byte floor is garbage, not a
 window).
@@ -500,7 +502,8 @@ See [CHANGELOG.md](CHANGELOG.md) for the release history.
 
 - [Ask User Question](#ask-user-question) is inspired by
   [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question) —
-  the interaction design (flattened option list with a free-text sentinel,
-  multi-question review page, decline gesture) was adapted to this TUI's
-  framed-overlay and dsh `userQuestions` provider architecture. All code here
-  is original.
+  the interaction design (numbered option list with a free-text sentinel,
+  multi-question review page, decline gesture; since reworked into a
+  one-question-at-a-time tab view with a fold-away strip) was adapted to this
+  TUI's docked-panel and dsh `userQuestions` provider architecture. All code
+  here is original.

package/lib/ask-user.d.ts

@@ -8,12 +8,17 @@
  * `AskUserQuestionAnswer` envelope back to `dsh-tool-ask-user` as a normal
  * tool result.
  *
- * Layout — one bordered dock panel, all questions flattened (numbered rows, a
- * divider between each question block and its options, and a scroll window
- * so the cursor row is always visible even when the dock is height-capped):
+ * Layout — one bordered dock panel showing EXACTLY ONE question at a time
+ * (numbered rows, a divider between the question block and its options, and
+ * a scroll window so the cursor row is always visible even when the dock is
+ * height-capped). With ≥ 2 questions a tab strip under the title carries one
+ * tab per question (`[1] · 2✓ · 3` — brackets mark the focused tab, ✓ an
+ * answered one); ←/→ (and Tab/Shift-Tab) switch tabs so a question batch
+ * never floods the dock:
  *
  *   ┌────────────────────────────────────┐
- *   │ ● Questions (2)                    │
+ *   │ ● Questions (1/2)                  │
+ *   │ [1] · 2                            │   (tab strip, ≥ 2 questions only)
  *   │ SELECTION                          │
  *   │ ─────────────────────────────      │   (table chrome)
  *   │ Fruit  Where should we deploy?     │   (header — not selectable)
@@ -26,6 +31,11 @@
  *   │     ⏎ Confirm answers              │   (when ≥ 2 questions, or any multiSelect)
  *   └────────────────────────────────────┘
  *
+ * Ctrl+T folds the whole panel into a 3-line strip (borders + one summary
+ * line) so the transcript stays readable while the question pends; the same
+ * key unfolds it. While folded only the toggle and the Esc chain do
+ * anything — answering keys are inert until the panel is back.
+ *
  * While the panel is open it owns the keyboard: it is mounted into the dock
  * slot between the live widgets and the editor, takes focus through
  * `tui.setFocus`, and `setModalActive(true)` routes the app keymap exactly
@@ -45,7 +55,9 @@
  * Single-question single-select panel: Enter on an option (or committing a
  * filled sentinel) submits immediately. A multiSelect question — even a lone
  * one — gets a Confirm row instead of auto-submitting, so the user can pick
- * several options first. Multi-question panel: Enter on the Confirm row hops
+ * several options first. Multi-question panel: answering a single-select tab
+ * auto-advances the focus to the next unanswered tab (or onto the Confirm
+ * row once everything is answered). Enter on the Confirm row hops
  * to the review page (all answers listed, each editable in place). Esc
  * double-press within 200 ms declines — but terminal key auto-repeat (holding
  * Esc) is ignored below `ESC_REPEAT_GUARD_MS`, so a long press cannot
@@ -65,7 +77,7 @@
  * Inspired by juicesharp/rpiv-ask-user-question
  * (https://github.com/juicesharp/rpiv-ask-user-question).
  */
-import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type Component, type KeyId, type TUI } from '@earendil-works/pi-tui';
 import type { AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionOption } from '@deepseek-ai/dsh-user-questions';
 import type { Context } from '@deepseek-ai/cordis';
 import { type TuiTheme } from './theme/index.ts';
@@ -80,6 +92,13 @@ export declare const DOUBLE_ESC_WINDOW_MS = 200;
 export declare const ESC_REPEAT_GUARD_MS = 50;
 /** Sentinel row label appended to every question's option list. */
 export declare const SENTINEL_LABEL = "Type something.";
+/**
+ * Key that folds the whole panel into a 3-line strip (and unfolds it again).
+ * A control key on purpose: it must never read as free-text input while the
+ * sentinel editor is engaged (folding commits the buffer, exactly like the
+ * ↑↓ arrow-exit path does).
+ */
+export declare const ASK_COLLAPSE_KEY: KeyId;
 /** Decline message embedded into the answer envelope when the user bails. */
 export declare const DECLINE_MESSAGE = "User declined to answer questions.";
 /** Transient hint when Enter lands on an incomplete confirm/submit row. */
@@ -99,9 +118,11 @@ export declare const ASK_USER_MAX_VISIBLE = 6;
  * panel budget is the terminal height minus the reserved dock rows, minus
  * the panel's own chrome. At the 24-row e2e floor this yields exactly
  * ASK_USER_MAX_VISIBLE (6); larger terminals scale up. Without a usable row
- * count it degrades to ASK_USER_MAX_VISIBLE.
+ * count it degrades to ASK_USER_MAX_VISIBLE. `extraChromeLines` covers
+ * optional interior lines the default budget does not count (the tab strip
+ * of a multi-question panel).
  */
-export declare function askUserMaxVisibleForRows(termRows: number | undefined): number;
+export declare function askUserMaxVisibleForRows(termRows: number | undefined, extraChromeLines?: number): number;
 /** A row in the multi-question view. */
 export interface FlatRow {
     kind: 'question-header' | 'option' | 'sentinel' | 'confirm';
@@ -133,8 +154,15 @@ export interface AskUserState {
     questions: readonly AskUserQuestionItem[];
     /** Per-question pending answer. */
     perQuestion: PendingAnswer[];
-    /** Cursor position in the flat row list (see `buildRowList`). */
+    /** Cursor position in the focused question's row list (see `buildRowList`). */
     cursorIndex: number;
+    /**
+     * Which question tab the questions pane shows. The pane renders exactly
+     * one question at a time; ←/→ (and Tab/Shift-Tab) move this index.
+     */
+    focusQuestion: number;
+    /** Panel folded to the 3-line strip (Ctrl+T). While folded only the toggle key and the Esc chain act. */
+    collapsed: boolean;
     /** Live inline-edit text per question; non-null when the sentinel is engaged for that question. */
     customInputs: (string | null)[];
     /** Live inline edit owner (question index); null when not editing. */
@@ -187,8 +215,13 @@ export declare function didDoubleEscFire(prevState: AskUserState, nextState: Ask
 export declare function buildAnswerEnvelope(state: AskUserState): AskUserQuestionAnswer;
 /** Canonical envelope for the decline path: empty selected + custom decline message on every question. */
 export declare function buildDeclinedEnvelope(questions: readonly AskUserQuestionItem[], message?: string): AskUserQuestionAnswer;
-/** Build the ordered, flat list of rows for the questions pane. */
-export declare function buildRowList(questions: readonly AskUserQuestionItem[], perQuestion: readonly PendingAnswer[]): FlatRow[];
+/**
+ * Build the ordered row list for the questions pane: the FOCUSED question's
+ * block only (header + options + sentinel), followed by the panel-wide
+ * Confirm pseudo-row when `needsConfirmRow` says so — the pane shows one
+ * question at a time; ←/→ swaps `focusQuestion` and rebuilds this list.
+ */
+export declare function buildRowList(questions: readonly AskUserQuestionItem[], perQuestion: readonly PendingAnswer[], focusQuestion?: number): FlatRow[];
 /** Find the next selectable index from `i` going in `direction`, clamped into range. */
 export declare function nextSelectableIndex(rows: readonly FlatRow[], from: number, direction: 1 | -1): number;
 /** True when every question has at least one selected option or a non-empty custom answer. */
@@ -233,15 +266,51 @@ export declare function needsConfirmRow(questions: readonly AskUserQuestionItem[
  */
 export declare function canAutoSubmit(state: AskUserState): boolean;
 /**
- * Row index to land on after answering question `answeredQi`: the first
- * selectable row of the nearest LATER unanswered question, or -1 when every
- * later question is already answered (caller keeps the current cursor).
+ * Row index to land on after a single-select answer on question `answeredQi`
+ * (option toggle or committed custom text): advance the tab focus to the
+ * nearest LATER unanswered question (cursor on its answer), or — once every
+ * question is answered — park the cursor on the Confirm row of the current
+ * tab so submission is one Enter away. Returns the state unchanged when no
+ * Confirm row exists (the lone single-select fast path submits instead).
  */
-export declare function nextUnansweredRow(rows: readonly FlatRow[], perQuestion: readonly PendingAnswer[], answeredQi: number): number;
-/** Render the questions pane as a flat table line list behind a scroll window. */
+export declare function advanceAfterAnswer(state: AskUserState, answeredQi: number): AskUserState;
+/** Index of the nearest question AFTER `answeredQi` with no answer yet, or -1. */
+export declare function nextUnansweredQuestion(questions: readonly AskUserQuestionItem[], perQuestion: readonly PendingAnswer[], answeredQi: number): number;
+/**
+ * Cursor position for a freshly focused question tab: its first selected
+ * option when one exists, else the sentinel when a custom answer exists,
+ * else the first selectable row — so revisiting an answered tab lands on
+ * the answer, not on option 1.
+ */
+export declare function focusCursor(rows: readonly FlatRow[], perQuestion: readonly PendingAnswer[], questionIndex: number): number;
+/**
+ * Move the tab focus by `direction` (clamped at the ends — no wrap-around:
+ * predictable ends beat flourish mid-questionnaire) and land the cursor on
+ * the tab's answer per `focusCursor`. Clears the transient hints like any
+ * navigation. The component must exit an engaged sentinel edit BEFORE
+ * switching (committing the buffer), same as the ↑↓ arrow-exit path.
+ */
+export declare function switchFocus(state: AskUserState, direction: 1 | -1): AskUserState;
+/**
+ * Flip the Ctrl+T fold. Folding while a sentinel edit is engaged first
+ * commits the buffer (the arrow-exit semantics — the text stays visible on
+ * the sentinel's ✎ mark), then collapses; transient hints clear on both
+ * directions. The double-Esc clock is deliberately untouched so an armed
+ * decline keeps its hint when the panel unfolds.
+ */
+export declare function toggleCollapse(state: AskUserState): AskUserState;
+/** Render the questions pane (one focused question tab) as a flat table line list behind a scroll window. */
 export declare function renderQuestionsView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
 /** Render the review page for multi-question overlays (scroll-windowed). */
 export declare function renderReviewView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
+/**
+ * The ONE interior line of the folded (Ctrl+T) panel. The panel is a hard
+ * modal that owns the keyboard while it pends, so the strip keeps the
+ * state machine discoverable: which phase, how far along, how to unfold —
+ * and an armed decline replaces the summary so the 200 ms window is not
+ * silently ticking off-screen.
+ */
+export declare function renderCollapsedLine(theme: TuiTheme, state: AskUserState, width: number): string;
 /** Options for assembling the panel + provider function. */
 export interface AskUserPanelDeps {
     tui: TUI;
@@ -291,7 +360,7 @@ export declare function isDuplicateProviderError(error: unknown): boolean;
  * Wires the provider into `ctx.userQuestions`. Call from inside `ctx.effect`.
  *
  * Failure semantics are deliberate (review round BM):
- * - missing service → warn + no-op disposer. The tool stays mounted by the
+ * - missing service → one notice + no-op disposer. The tool stays mounted by the
  *   bundle patch; without a provider its calls fail with the upstream
  *   NO_PROVIDER error, which is better than crashing the whole TUI plugin.
  * - DUPLICATE_PROVIDER → silent no-op disposer (a prior UI owns the slot).