@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/@juicesharp/rpiv-ask-user-question/state/key-router.ts

@@ -150,6 +150,135 @@ function prevNavOnUp(state: QuestionnaireState, runtime: QuestionnaireRuntime):
 	};
 }
 
+// Collapsed-mode lockout: while collapsed, swallow every keystroke except cancel so
+// the user can read the now-uncovered transcript without accidentally mutating
+// answers or notes. The collapse toggle itself is already handled above.
+function routeCollapsed(kb: QuestionnaireKeybindings, data: string): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
+function routeNotesMode(kb: QuestionnaireKeybindings, data: string): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "notes_exit" };
+	if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "notes_forward", data };
+	if (isConfirm(kb, data)) return { kind: "notes_exit" };
+	return { kind: "notes_forward", data };
+}
+
+function routeInputMode(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	// Newline takes precedence over confirmation if a user configuration binds
+	// the same physical key to both semantic actions.
+	if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "ignore" };
+	if (isConfirm(kb, data)) {
+		const answer = buildSingleSelectAnswer(state, runtime);
+		if (!answer) return { kind: "ignore" };
+		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+	}
+	// Treat Pi's Ctrl+U line-kill binding as an explicit whole-draft clear,
+	// independent of the current cursor position.
+	if (kb.matches(data, KEYBIND_CLEAR)) return { kind: "input_clear" };
+	if (kb.matches(data, KEYBIND_EXTERNAL_EDITOR)) return { kind: "input_edit", value: runtime.inputBuffer };
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	if (kb.matches(data, KEYBIND_EDITOR_UP) && runtime.canMoveInputUp) return { kind: "ignore" };
+	if (kb.matches(data, KEYBIND_EDITOR_DOWN) && runtime.canMoveInputDown) return { kind: "ignore" };
+	if (kb.matches(data, KEYBIND_UP)) return prevNavOnUp(state, runtime);
+	if (kb.matches(data, KEYBIND_DOWN)) return nextNavOnDown(state, runtime);
+	return { kind: "ignore" };
+}
+
+function routeSubmitTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	const tab = tabSwitchAction(data, state, runtime);
+	if (tab) return tab;
+	if (kb.matches(data, KEYBIND_UP) || kb.matches(data, KEYBIND_DOWN)) {
+		const delta = kb.matches(data, KEYBIND_DOWN) ? 1 : -1;
+		const next = wrapTab(state.submitChoiceIndex + delta, 2);
+		return { kind: "submit_nav", nextIndex: (next === 1 ? 1 : 0) as 0 | 1 };
+	}
+	if (isConfirm(kb, data)) {
+		// D1 (revised): Submit always submits; Cancel always cancels. The warning header
+		// is informational only — `allAnswered(state)` no longer gates submission. Partial
+		// answers flow through `orderedAnswers()` in the host.
+		return state.submitChoiceIndex === 1 ? { kind: "cancel" } : { kind: "submit" };
+	}
+	// Global note (#182): `n` on the Submit tab opens the notes editor scoped to the whole
+	// questionnaire at the pseudo-index (`questions.length` in notesByTab). Reachable only
+	// with the editor closed — `routeKey` dispatches notesVisible traffic to
+	// `routeNotesMode` before the submit-tab block runs. The branch shadows nothing above
+	// it (cancel, tab switch, submit-nav, confirm): a literal `n` byte matches none of them
+	// under default bindings, and a user who deliberately binds one of those actions to
+	// `n` keeps that mapping because the earlier branch still wins (Enter still submits).
+	if (data === NOTES_ACTIVATE_KEY) {
+		return { kind: "notes_enter" };
+	}
+	return { kind: "ignore" };
+}
+
+function routeMultiSelectTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	const focusedKind = runtime.currentItem?.kind;
+	const focusedMeta = focusedKind ? ROW_INTENT_META[focusedKind] : undefined;
+	// Space toggles the focused row's checkbox. Suppressed on rows whose META declares
+	// `blocksMultiToggle` (the Next sentinel) or `activatesInputMode` (the "Type
+	// something." row — it is an inline input, not a checkable option).
+	if (data === SPACE_KEY) {
+		if (focusedMeta?.blocksMultiToggle) return { kind: "ignore" };
+		if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+		return { kind: "toggle", index: state.optionIndex };
+	}
+	if (isConfirm(kb, data)) {
+		// Enter on the "Type something." row is handled by the inputMode block above
+		// (→ confirm kind:"custom"). Defensive: never enter the toggle/multi_confirm
+		// path for an inputMode-activating row.
+		if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+		// Enter on a regular row toggles (matching Space) — committing the question is now
+		// gated behind explicit focus on a row whose META declares `autoSubmitsInMulti`
+		// (the Next sentinel), so Enter on options is a no-cost way to flip checkboxes
+		// without leaving the keyboard home row.
+		if (!focusedMeta?.autoSubmitsInMulti) return { kind: "toggle", index: state.optionIndex };
+		// Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
+		// multi-question mode, OR submit the dialog in single-question mode
+		// (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
+		// question would have no way to commit at all.
+		return {
+			kind: "multi_confirm",
+			selected: buildMultiSelected(state, runtime),
+			autoAdvanceTab: computeAutoAdvanceTab(state, runtime),
+		};
+	}
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
+function routeSingleSelectTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	if (isConfirm(kb, data)) {
+		const answer = buildSingleSelectAnswer(state, runtime);
+		if (!answer) return { kind: "ignore" };
+		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+	}
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
 export function routeKey(data: string, state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
 	const kb = runtime.keybindings;
 
@@ -185,60 +314,11 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 		return { kind: "toggle_collapsed" };
 	}
 
-	// Collapsed-mode lockout: while collapsed, swallow every keystroke except cancel so
-	// the user can read the now-uncovered transcript without accidentally mutating
-	// answers or notes. The collapse toggle itself is already handled above.
-	if (state.collapsed) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		return { kind: "ignore" };
-	}
-
-	if (state.notesVisible) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "notes_exit" };
-		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "notes_forward", data };
-		if (isConfirm(kb, data)) return { kind: "notes_exit" };
-		return { kind: "notes_forward", data };
-	}
-
-	if (state.inputMode) {
-		// Newline takes precedence over confirmation if a user configuration binds
-		// the same physical key to both semantic actions.
-		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "ignore" };
-		if (isConfirm(kb, data)) {
-			const answer = buildSingleSelectAnswer(state, runtime);
-			if (!answer) return { kind: "ignore" };
-			return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
-		}
-		// Treat Pi's Ctrl+U line-kill binding as an explicit whole-draft clear,
-		// independent of the current cursor position.
-		if (kb.matches(data, KEYBIND_CLEAR)) return { kind: "input_clear" };
-		if (kb.matches(data, KEYBIND_EXTERNAL_EDITOR)) return { kind: "input_edit", value: runtime.inputBuffer };
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		if (kb.matches(data, KEYBIND_EDITOR_UP) && runtime.canMoveInputUp) return { kind: "ignore" };
-		if (kb.matches(data, KEYBIND_EDITOR_DOWN) && runtime.canMoveInputDown) {
-			return { kind: "ignore" };
-		}
-		if (kb.matches(data, KEYBIND_UP)) return prevNavOnUp(state, runtime);
-		if (kb.matches(data, KEYBIND_DOWN)) return nextNavOnDown(state, runtime);
-		return { kind: "ignore" };
-	}
-
+	if (state.collapsed) return routeCollapsed(kb, data);
+	if (state.notesVisible) return routeNotesMode(kb, data);
+	if (state.inputMode) return routeInputMode(kb, data, state, runtime);
 	if (runtime.isMulti && state.currentTab === runtime.questions.length) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		const tab = tabSwitchAction(data, state, runtime);
-		if (tab) return tab;
-		if (kb.matches(data, KEYBIND_UP) || kb.matches(data, KEYBIND_DOWN)) {
-			const delta = kb.matches(data, KEYBIND_DOWN) ? 1 : -1;
-			const next = wrapTab(state.submitChoiceIndex + delta, 2);
-			return { kind: "submit_nav", nextIndex: (next === 1 ? 1 : 0) as 0 | 1 };
-		}
-		if (isConfirm(kb, data)) {
-			// D1 (revised): Submit always submits; Cancel always cancels. The warning header
-			// is informational only — `allAnswered(state)` no longer gates submission. Partial
-			// answers flow through `orderedAnswers()` in the host.
-			return state.submitChoiceIndex === 1 ? { kind: "cancel" } : { kind: "submit" };
-		}
-		return { kind: "ignore" };
+		return routeSubmitTab(kb, data, state, runtime);
 	}
 
 	const tab = tabSwitchAction(data, state, runtime);
@@ -251,7 +331,8 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 	// (single- or multi-select, preview or no-preview). The blocks above already
 	// swallow `n` when it should NOT reach here — notesVisible forwards to the
 	// notes Input, inputMode forwards to the inline Input, the submit-tab block
-	// ignores it, and tabSwitchAction ignores it — so by the time we reach this
+	// activates it via its own branch (the global note, ahead of its ignore
+	// fall-through), and tabSwitchAction ignores it — so by the time we reach this
 	// gate, `n` is unambiguously a notes-enter request. Row intent (Next sentinel,
 	// "Type something.") is irrelevant: the gate sits ABOVE the multi-select
 	// toggle block and the Next sentinel never activates inputMode, so `n` is
@@ -267,46 +348,6 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 		return nextNavOnDown(state, runtime);
 	}
 
-	if (q.multiSelect) {
-		const focusedKind = runtime.currentItem?.kind;
-		const focusedMeta = focusedKind ? ROW_INTENT_META[focusedKind] : undefined;
-		// Space toggles the focused row's checkbox. Suppressed on rows whose META declares
-		// `blocksMultiToggle` (the Next sentinel) or `activatesInputMode` (the "Type
-		// something." row — it is an inline input, not a checkable option).
-		if (data === SPACE_KEY) {
-			if (focusedMeta?.blocksMultiToggle) return { kind: "ignore" };
-			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
-			return { kind: "toggle", index: state.optionIndex };
-		}
-		if (isConfirm(kb, data)) {
-			// Enter on the "Type something." row is handled by the inputMode block above
-			// (→ confirm kind:"custom"). Defensive: never enter the toggle/multi_confirm
-			// path for an inputMode-activating row.
-			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
-			// Enter on a regular row toggles (matching Space) — committing the question is now
-			// gated behind explicit focus on a row whose META declares `autoSubmitsInMulti`
-			// (the Next sentinel), so Enter on options is a no-cost way to flip checkboxes
-			// without leaving the keyboard home row.
-			if (!focusedMeta?.autoSubmitsInMulti) return { kind: "toggle", index: state.optionIndex };
-			// Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
-			// multi-question mode, OR submit the dialog in single-question mode
-			// (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
-			// question would have no way to commit at all.
-			return {
-				kind: "multi_confirm",
-				selected: buildMultiSelected(state, runtime),
-				autoAdvanceTab: computeAutoAdvanceTab(state, runtime),
-			};
-		}
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		return { kind: "ignore" };
-	}
-
-	if (isConfirm(kb, data)) {
-		const answer = buildSingleSelectAnswer(state, runtime);
-		if (!answer) return { kind: "ignore" };
-		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
-	}
-	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-	return { kind: "ignore" };
+	if (q.multiSelect) return routeMultiSelectTab(kb, data, state, runtime);
+	return routeSingleSelectTab(kb, data, state, runtime);
 }

package/node_modules/@juicesharp/rpiv-ask-user-question/state/questionnaire-session.ts

@@ -5,7 +5,7 @@ import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/
 import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
 import { COLLAPSED_HINT_TEMPLATE, HINT_PART_CANCEL, KEY_PLACEHOLDER } from "../view/dialog-builder.js";
 import type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
-import { buildQuestionnaire } from "./build-questionnaire.js";
+import { buildQuestionnaire, type QuestionnaireBuilt } from "./build-questionnaire.js";
 import { t } from "./i18n-bridge.js";
 import { type QuestionnaireAction, routeKey } from "./key-router.js";
 import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
@@ -113,31 +113,38 @@ export class QuestionnaireSession {
 		this.inlineInput = built.inlineInput;
 		this.viewAdapter = built.adapter;
 
-		const theme = config.theme;
-		// Collapsed render: a single dim row at the bottom of the overlay. pi-tui sizes
-		// the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
-		// the bottom-anchored overlay from full-height to one row and the transcript
-		// behind it becomes readable (#47). The overlay stays focused and in the
-		// stack, so the collapse key still routes here to expand. `t` stays inside the
-		// closure (live locale updates); the key display is static per session.
-		//
-		// With collapseKey "off" the router and raw listener never toggle `collapsed`,
-		// but `toggleCollapsedExternal()` is a public ungated entry — fall back to the
-		// cancel-only line rather than rendering a literal "Off to expand".
-		const collapseKeyDisplay = formatKeySpecForDisplay(this.collapseKey);
-		const collapsedHintLine = (): string =>
-			this.collapseKey === COLLAPSE_KEY_OFF
-				? t("hint.cancel", HINT_PART_CANCEL)
-				: t("hint.expand_line", COLLAPSED_HINT_TEMPLATE).replace(KEY_PLACEHOLDER, collapseKeyDisplay);
-		const collapsedRender = (_width: number): string[] => [theme.fg("dim", ` ${collapsedHintLine()} `)];
+		this.component = this.assembleComponent(built, config.theme);
+		this.viewAdapter.apply(this.state);
+	}
 
-		this.component = {
+	private assembleComponent(built: QuestionnaireBuilt, theme: Theme): QuestionnaireSessionComponent {
+		const collapsedRender = this.buildCollapsedRender(theme);
+		return {
 			render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
 			invalidate: built.invalidate,
 			handleInput: (data) => this.dispatch(data),
 		};
+	}
 
-		this.viewAdapter.apply(this.state);
+	/**
+	 * Collapsed render: a single dim row at the bottom of the overlay. pi-tui sizes
+	 * the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
+	 * the bottom-anchored overlay from full-height to one row and the transcript
+	 * behind it becomes readable (#47). The overlay stays focused and in the
+	 * stack, so the collapse key still routes here to expand. `t` stays inside the
+	 * closure (live locale updates); the key display is static per session.
+	 *
+	 * With collapseKey "off" the router and raw listener never toggle `collapsed`,
+	 * but `toggleCollapsedExternal()` is a public ungated entry — fall back to the
+	 * cancel-only line rather than rendering a literal "Off to expand".
+	 */
+	private buildCollapsedRender(theme: Theme): (width: number) => string[] {
+		const collapseKeyDisplay = formatKeySpecForDisplay(this.collapseKey);
+		const collapsedHintLine = (): string =>
+			this.collapseKey === COLLAPSE_KEY_OFF
+				? t("hint.cancel", HINT_PART_CANCEL)
+				: t("hint.expand_line", COLLAPSED_HINT_TEMPLATE).replace(KEY_PLACEHOLDER, collapseKeyDisplay);
+		return (_width: number): string[] => [theme.fg("dim", ` ${collapsedHintLine()} `)];
 	}
 
 	dispatch(data: string): void {
@@ -174,18 +181,7 @@ export class QuestionnaireSession {
 				this.inlineInput.setText("");
 				return;
 			case "open_input_editor":
-				if (this.inputEditorOpen) return;
-				this.inputEditorOpen = true;
-				void this.editInput(effect.value).then(
-					(value) => {
-						this.inputEditorOpen = false;
-						if (value !== undefined) this.commit({ kind: "input_replace", value });
-					},
-					() => {
-						// The host callback reports launch errors; retain the draft and restore input handling.
-						this.inputEditorOpen = false;
-					},
-				);
+				this.openInputEditorAsync(effect.value);
 				return;
 			case "set_notes_value":
 				this.notesInput.setText(effect.value);
@@ -210,6 +206,22 @@ export class QuestionnaireSession {
 		}
 	}
 
+	/** Opens Pi's configured external editor; on success commits the replacement buffer, on reported failure retains the draft. */
+	private openInputEditorAsync(value: string): void {
+		if (this.inputEditorOpen) return;
+		this.inputEditorOpen = true;
+		void this.editInput(value).then(
+			(edited) => {
+				this.inputEditorOpen = false;
+				if (edited !== undefined) this.commit({ kind: "input_replace", value: edited });
+			},
+			() => {
+				// The host callback reports launch errors; retain the draft and restore input handling.
+				this.inputEditorOpen = false;
+			},
+		);
+	}
+
 	/**
 	 * Per-keystroke `ignore` fast path: delegates text editing to Pi's headless
 	 * multiline `Editor`, including paste, undo, cursor movement, and configured

package/node_modules/@juicesharp/rpiv-ask-user-question/state/selectors/projections.ts

@@ -5,23 +5,32 @@ import type { SubmitPickerProps } from "../../view/components/submit-picker.js";
 import type { TabBarProps } from "../../view/components/tab-bar.js";
 import type { DialogProps } from "../../view/dialog-builder.js";
 import { displayLabel } from "../i18n-bridge.js";
-import type { GlobalSelector, PerTabSelector } from "./contract.js";
+import type { GlobalSelector, PerTabBindingContext, PerTabSelector } from "./contract.js";
 import { selectConfirmedIndicator } from "./derivations.js";
 
+function emptyMultiSelectProps(ctx: PerTabBindingContext): MultiSelectViewProps {
+	return {
+		rows: [],
+		other: {
+			active: false,
+			inputMode: false,
+			inputBuffer: ctx.inputBuffer,
+			inputCursorOffset: ctx.inputCursorOffset,
+		},
+		nextActive: false,
+		nextLabel: displayLabel("next"),
+	};
+}
+
+function nextLabelFor(ctx: PerTabBindingContext): string {
+	const isLastQuestion = ctx.i === ctx.questions.length - 1;
+	return isLastQuestion ? MULTI_SUBMIT_LABEL : displayLabel("next");
+}
+
 export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (state, ctx) => {
 	const question = ctx.questions[ctx.i];
 	if (!question) {
-		return {
-			rows: [],
-			other: {
-				active: false,
-				inputMode: false,
-				inputBuffer: ctx.inputBuffer,
-				inputCursorOffset: ctx.inputCursorOffset,
-			},
-			nextActive: false,
-			nextLabel: displayLabel("next"),
-		};
+		return emptyMultiSelectProps(ctx);
 	}
 	const focused = ctx.activeView === "options";
 	const rows: { checked: boolean; active: boolean }[] = [];
@@ -33,8 +42,6 @@ export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (sta
 	}
 	const otherActive = focused && state.optionIndex === question.options.length;
 	const nextActive = focused && state.optionIndex === question.options.length + 1;
-	const isLastQuestion = ctx.i === ctx.questions.length - 1;
-	const nextLabel = isLastQuestion ? MULTI_SUBMIT_LABEL : displayLabel("next");
 	return {
 		rows,
 		other: {
@@ -44,7 +51,7 @@ export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (sta
 			inputCursorOffset: ctx.inputCursorOffset,
 		},
 		nextActive,
-		nextLabel,
+		nextLabel: nextLabelFor(ctx),
 	};
 };
 

package/node_modules/@juicesharp/rpiv-ask-user-question/state/state-reducer.ts

@@ -139,7 +139,17 @@ function switchTabResult(state: QuestionnaireState, nextTab: number, ctx: ApplyC
 }
 
 function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolean): ApplyResult {
-	const result: QuestionnaireResult = { answers: orderedAnswers(state, ctx.questions), cancelled };
+	// Global note lift: the Submit-tab note lives at the `questions.length` pseudo-index
+	// in `notesByTab` — question tabs only occupy 0..questions.length-1, so this can never
+	// cross-contaminate a per-question note. Attached regardless of `cancelled` (the
+	// reducer is truth; the envelope owns decline presentation), with cancel/submit/confirm
+	// sharing this single lift. Conditional spread keeps note-free results byte-identical.
+	const globalNote = state.notesByTab.get(ctx.questions.length);
+	const result: QuestionnaireResult = {
+		answers: orderedAnswers(state, ctx.questions),
+		cancelled,
+		...(globalNote && globalNote.length > 0 ? { globalNote } : {}),
+	};
 	return { state, effects: [{ kind: "done", result }] };
 }
 

package/node_modules/@juicesharp/rpiv-ask-user-question/tool/response-envelope.ts

@@ -9,12 +9,18 @@ export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in
  * Map a `QuestionnaireResult` (or null/cancelled) to the LLM-facing tool envelope.
  * Pure of `(result, params)`; cancelled and "no segments" both fall to `DECLINE_MESSAGE`
  * so the model sees a single canonical "didn't answer" signal regardless of why.
+ * "No segments" means no answers AND no global note — the `global note:` segment is
+ * pushed before the zero-segments check, so a note-bearing submit with zero answers
+ * still yields the answered envelope.
  */
 export function buildQuestionnaireResponse(result: QuestionnaireResult | null | undefined, params: QuestionParams) {
 	if (!result || result.cancelled) {
+		// Decline text stays canonical even when a global note rides the cancelled result;
+		// the note survives in `details` (like partial `answers`) for replay consumers.
 		return buildToolResult(DECLINE_MESSAGE, {
 			answers: result?.answers ?? [],
 			cancelled: true,
+			...(result?.globalNote && result.globalNote.length > 0 ? { globalNote: result.globalNote } : {}),
 		});
 	}
 	const segments: string[] = [];
@@ -22,6 +28,11 @@ export function buildQuestionnaireResponse(result: QuestionnaireResult | null |
 		const a = result.answers.find((x) => x.questionIndex === i);
 		if (a) segments.push(buildAnswerSegment(a));
 	}
+	// Global note rides after the per-question segments: raw multiline echo (no
+	// reformatting), trailing period mirroring `buildAnswerSegment`'s shape.
+	if (result.globalNote && result.globalNote.length > 0) {
+		segments.push(`global note: ${result.globalNote}.`);
+	}
 	if (segments.length === 0) {
 		return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
 	}

package/node_modules/@juicesharp/rpiv-ask-user-question/tool/types.ts

@@ -135,6 +135,17 @@ export type QuestionnaireError =
 export interface QuestionnaireResult {
 	answers: QuestionAnswer[];
 	cancelled: boolean;
+	/**
+	 * Global note authored on the Submit tab: `n` opens the shared notes editor there,
+	 * and the committed text lives at the `notesByTab[questions.length]` pseudo-index
+	 * (a slot no question tab can occupy) until `doneFor` lifts it onto the result —
+	 * attached on both submit and cancel, like per-question `answers[].notes`.
+	 * Conditional-spread contract, mirroring `QuestionAnswer.notes`: the key appears
+	 * only via conditional spread of a non-empty string — never assigned `undefined`,
+	 * never kept for an empty/whitespace-only draft — so note-free results stay
+	 * byte-identical (`!("globalNote" in result)` holds).
+	 */
+	globalNote?: string;
 	error?: QuestionnaireError;
 }
 

package/node_modules/@juicesharp/rpiv-ask-user-question/view/components/multi-select-view.ts

@@ -50,6 +50,12 @@ interface MultiSelectLayout {
 	focusedRange: [number, number];
 }
 
+/** Mutable row accumulator threaded through the append helpers during a layout miss. */
+interface MultiSelectBuild {
+	lines: string[];
+	focusedRange: [number, number];
+}
+
 export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
 	private props: MultiSelectViewProps;
 	private cachedLayout: { width: number; value: MultiSelectLayout } | undefined;
@@ -92,47 +98,55 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
 	private layout(width: number): MultiSelectLayout {
 		if (this.cachedLayout?.width === width) return this.cachedLayout.value;
 
-		const lines: string[] = [];
-		let focusedRange: [number, number] = [0, 0];
+		const build: MultiSelectBuild = { lines: [], focusedRange: [0, 0] };
 		const contentWidth = Math.max(1, width - this.prefixVisibleWidth());
 		const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+
+		this.appendOptionRows(build, width, contentWidth, numberWidth);
+
+		const otherStart = build.lines.length;
+		build.lines.push(...this.renderOtherRow(contentWidth, numberWidth));
+		if (this.props.other.active) build.focusedRange = [otherStart, build.lines.length];
+
+		this.appendNextRow(build, width);
+
+		const value = { lines: build.lines, focusedRange: build.focusedRange };
+		this.cachedLayout = { width, value };
+		return value;
+	}
+
+	private appendOptionRows(build: MultiSelectBuild, width: number, contentWidth: number, numberWidth: number): void {
 		for (let i = 0; i < this.question.options.length; i++) {
 			const opt = this.question.options[i];
 			const row = this.props.rows[i];
 			if (!opt || !row) continue;
-			const start = lines.length;
+			const start = build.lines.length;
 			const pointer = row.active ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
 			// Checked and active rows share the accent hue, matching the dialog's selection rhythm.
 			const box = row.checked ? this.theme.fg("accent", CHECKED) : this.theme.fg("muted", UNCHECKED);
 			const label = truncateToWidth(opt.label, contentWidth, "…");
 			const styledLabel = row.active ? this.theme.fg("accent", this.theme.bold(label)) : label;
 			const number = String(i + 1).padStart(numberWidth, " ");
-			lines.push(
+			build.lines.push(
 				truncateToWidth(`${pointer}${number}${NUMBER_SEPARATOR}${box}${BOX_LABEL_GAP}${styledLabel}`, width, ""),
 			);
 			if (opt.description) {
 				for (const segment of wrapTextWithAnsi(opt.description, contentWidth)) {
-					lines.push(CONTINUATION_INDENT + this.theme.fg("muted", segment));
+					build.lines.push(CONTINUATION_INDENT + this.theme.fg("muted", segment));
 				}
 			}
-			if (row.active) focusedRange = [start, lines.length];
+			if (row.active) build.focusedRange = [start, build.lines.length];
 		}
+	}
 
-		const otherStart = lines.length;
-		lines.push(...this.renderOtherRow(contentWidth, numberWidth));
-		if (this.props.other.active) focusedRange = [otherStart, lines.length];
-
-		const nextStart = lines.length;
+	private appendNextRow(build: MultiSelectBuild, width: number): void {
+		const nextStart = build.lines.length;
 		const nextPointer = this.props.nextActive ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
 		const nextLabel = this.props.nextActive
 			? this.theme.fg("accent", this.theme.bold(this.props.nextLabel))
 			: this.props.nextLabel;
-		lines.push(truncateToWidth(`${nextPointer}${nextLabel}`, width, ""));
-		if (this.props.nextActive) focusedRange = [nextStart, lines.length];
-
-		const value = { lines, focusedRange };
-		this.cachedLayout = { width, value };
-		return value;
+		build.lines.push(truncateToWidth(`${nextPointer}${nextLabel}`, width, ""));
+		if (this.props.nextActive) build.focusedRange = [nextStart, build.lines.length];
 	}
 
 	private renderOtherRow(contentWidth: number, numberWidth: number): string[] {

package/node_modules/@juicesharp/rpiv-ask-user-question/view/components/preview/preview-block-renderer.ts

@@ -23,6 +23,17 @@ import type { PreviewLayoutMode } from "./preview-layout-decider.js";
  */
 export const NOTES_AFFORDANCE_TEXT = "Notes: press n to add notes";
 
+/** Content row budget for a layout mode: preview cap minus border + affordance overhead. */
+function contentBudgetFor(mode: PreviewLayoutMode): number {
+	const cap = mode === "side-by-side" ? MAX_PREVIEW_HEIGHT_SIDE_BY_SIDE : MAX_PREVIEW_HEIGHT_STACKED;
+	return Math.max(1, cap - BORDER_VERTICAL_OVERHEAD - NOTES_AFFORDANCE_OVERHEAD);
+}
+
+/** Inner (padding-aware) content width for a total block width. */
+function innerWidthFor(width: number): number {
+	return Math.max(1, width - BORDER_HORIZONTAL_OVERHEAD - 2 * BORDER_INNER_PADDING_HORIZONTAL);
+}
+
 export interface PreviewBlockRendererConfig {
 	question: QuestionData;
 	theme: Theme;
@@ -66,9 +77,8 @@ export class PreviewBlockRenderer {
 	 * — the affordance overhead is constant, not gated by `focused`/`notesVisible`.
 	 */
 	blockHeight(width: number, optionIndex: number, mode: PreviewLayoutMode): number {
-		const cap = mode === "side-by-side" ? MAX_PREVIEW_HEIGHT_SIDE_BY_SIDE : MAX_PREVIEW_HEIGHT_STACKED;
-		const contentBudget = Math.max(1, cap - BORDER_VERTICAL_OVERHEAD - NOTES_AFFORDANCE_OVERHEAD);
-		const innerWidth = Math.max(1, width - BORDER_HORIZONTAL_OVERHEAD - 2 * BORDER_INNER_PADDING_HORIZONTAL);
+		const contentBudget = contentBudgetFor(mode);
+		const innerWidth = innerWidthFor(width);
 		const rawRows = this.cache.bodyFor(optionIndex, innerWidth).length;
 		const contentRows = Math.min(rawRows, contentBudget);
 		return BORDER_VERTICAL_OVERHEAD + contentRows + NOTES_AFFORDANCE_OVERHEAD;
@@ -87,9 +97,8 @@ export class PreviewBlockRenderer {
 		focused: boolean,
 		notesVisible: boolean,
 	): string[] {
-		const cap = mode === "side-by-side" ? MAX_PREVIEW_HEIGHT_SIDE_BY_SIDE : MAX_PREVIEW_HEIGHT_STACKED;
-		const contentBudget = Math.max(1, cap - BORDER_VERTICAL_OVERHEAD - NOTES_AFFORDANCE_OVERHEAD);
-		const maxInnerWidth = Math.max(1, width - BORDER_HORIZONTAL_OVERHEAD - 2 * BORDER_INNER_PADDING_HORIZONTAL);
+		const contentBudget = contentBudgetFor(mode);
+		const maxInnerWidth = innerWidthFor(width);
 
 		const raw = this.cache.bodyFor(optionIndex, maxInnerWidth);
 		const truncated = raw.length > contentBudget;

package/node_modules/@juicesharp/rpiv-ask-user-question/view/components/wrapping-select.ts

@@ -216,6 +216,20 @@ export class WrappingSelect implements Component {
 			return this.renderInlineInputRow(rowPrefix, continuationPrefix, contentWidth);
 		}
 
+		const { label, isConfirmed } = this.deriveConfirmedState(item, index);
+		const applySelectedStyle = isActive || isConfirmed;
+
+		return [
+			...this.renderLabelBlock(label, rowPrefix, continuationPrefix, contentWidth, applySelectedStyle),
+			...this.renderDescriptionBlock(item.description, continuationPrefix, contentWidth),
+		];
+	}
+
+	/**
+	 * Derive the confirmed-rendering facts for one row: the final label (custom draft
+	 * or confirmed-override aware) and whether the ✔ mark applies.
+	 */
+	private deriveConfirmedState(item: WrappingSelectItem, index: number): { label: string; isConfirmed: boolean } {
 		// Keep an in-flight custom draft visible even while the cursor browses another row.
 		// If it differs from a previously confirmed custom answer, omit the confirmation
 		// mark so the pending draft is not presented as committed.
@@ -230,12 +244,7 @@ export class WrappingSelect implements Component {
 		const label = isConfirmed
 			? `${this.confirmedLabelOverride ?? baseLabel}${WrappingSelect.CONFIRMED_MARK}`
 			: baseLabel;
-		const applySelectedStyle = isActive || isConfirmed;
-
-		return [
-			...this.renderLabelBlock(label, rowPrefix, continuationPrefix, contentWidth, applySelectedStyle),
-			...this.renderDescriptionBlock(item.description, continuationPrefix, contentWidth),
-		];
+		return { label, isConfirmed };
 	}
 
 	private buildRowPrefix(index: number, isActive: boolean, numberWidth: number): string {