pi-cc-extensions 0.8.7 → 0.8.9

package/extensions/ask-user-question/tool/validate-questionnaire.ts

@@ -0,0 +1,56 @@
+import { MAX_QUESTIONS, MIN_OPTIONS, type QuestionnaireError, type QuestionParams, RESERVED_LABELS } from "./types.js";
+
+export const ERROR_NO_QUESTIONS = "Error: At least one question is required";
+export const ERROR_TOO_MANY_QUESTIONS = `Error: At most ${MAX_QUESTIONS} questions are allowed per invocation`;
+export const ERROR_DUPLICATE_QUESTION = "Error: Question text must be unique within an invocation";
+export const ERROR_TOO_FEW_OPTIONS = `Error: Each question requires at least ${MIN_OPTIONS} options`;
+export const ERROR_RESERVED_LABEL = `Error: Option label is reserved (${RESERVED_LABELS.join(", ")})`;
+export const ERROR_DUPLICATE_OPTION_LABEL = "Error: Option labels must be unique within a question";
+
+const RESERVED_LABEL_SET: ReadonlySet<string> = new Set(RESERVED_LABELS);
+
+export type ValidationResult = { ok: true } | { ok: false; error: QuestionnaireError; message: string };
+
+/**
+ * Pure runtime validator for `QuestionParams`. Covers every guard except
+ * `no_ui` (which depends on `ctx.hasUI` and stays inline at the call site).
+ * `reserved_label` MUST short-circuit before `duplicate_option_label`.
+ */
+export function validateQuestionnaire(typed: QuestionParams): ValidationResult {
+	if (typed.questions.length === 0) {
+		return { ok: false, error: "no_questions", message: ERROR_NO_QUESTIONS };
+	}
+	if (typed.questions.length > MAX_QUESTIONS) {
+		return { ok: false, error: "too_many_questions", message: ERROR_TOO_MANY_QUESTIONS };
+	}
+
+	const seenQuestions = new Set<string>();
+	for (const q of typed.questions) {
+		if (seenQuestions.has(q.question)) {
+			return { ok: false, error: "duplicate_question", message: ERROR_DUPLICATE_QUESTION };
+		}
+		seenQuestions.add(q.question);
+	}
+
+	for (const q of typed.questions) {
+		if (q.options.length < MIN_OPTIONS) {
+			return { ok: false, error: "empty_options", message: ERROR_TOO_FEW_OPTIONS };
+		}
+		const seenLabels = new Set<string>();
+		for (const o of q.options) {
+			if (RESERVED_LABEL_SET.has(o.label)) {
+				return { ok: false, error: "reserved_label", message: ERROR_RESERVED_LABEL };
+			}
+			if (seenLabels.has(o.label)) {
+				return {
+					ok: false,
+					error: "duplicate_option_label",
+					message: ERROR_DUPLICATE_OPTION_LABEL,
+				};
+			}
+			seenLabels.add(o.label);
+		}
+	}
+
+	return { ok: true };
+}

package/extensions/ask-user-question/view/component-binding.ts

@@ -0,0 +1,45 @@
+import type {
+	BindingContext,
+	GlobalSelector,
+	PerTabBindingContext,
+	PerTabSelector,
+} from "../state/selectors/contract.js";
+import type { QuestionnaireState } from "../state/state.js";
+import type { StatefulView } from "./stateful-view.js";
+import type { TabComponents } from "./tab-components.js";
+
+export interface ComponentBinding<P> {
+	readonly component: StatefulView<P>;
+	readonly select: GlobalSelector<P>;
+}
+
+export interface PerTabBinding<P> {
+	readonly resolve: (tab: TabComponents) => StatefulView<P> | undefined;
+	readonly select: PerTabSelector<P>;
+	readonly predicate?: PerTabSelector<boolean>;
+}
+
+export interface BoundGlobalBinding {
+	apply(state: QuestionnaireState, ctx: BindingContext): void;
+	invalidate(): void;
+}
+
+export interface BoundPerTabBinding {
+	apply(state: QuestionnaireState, ctx: PerTabBindingContext): void;
+}
+
+export function globalBinding<P>(spec: ComponentBinding<P>): BoundGlobalBinding {
+	return {
+		apply: (state, ctx) => spec.component.setProps(spec.select(state, ctx)),
+		invalidate: () => spec.component.invalidate(),
+	};
+}
+
+export function perTabBinding<P>(spec: PerTabBinding<P>): BoundPerTabBinding {
+	return {
+		apply: (state, ctx) => {
+			if (spec.predicate && !spec.predicate(state, ctx)) return;
+			spec.resolve(ctx.tab)?.setProps(spec.select(state, ctx));
+		},
+	};
+}

package/extensions/ask-user-question/view/components/inline-input.ts

@@ -0,0 +1,96 @@
+import { CURSOR_MARKER, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// Grapheme-aware extraction at the cursor: pi-tui's Input advances `cursor` by
+// grapheme-cluster code-unit length, so the cursor can land between code units of
+// one cluster (emoji, ZWJ, combining marks). Single-code-unit slicing would split
+// the cluster across the SGR 7/27 boundary. Moved here from wrapping-select.ts so
+// both the single-select (wrap) and multi-select (truncate-to-one-line) inline
+// inputs share one cursor-building core.
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export interface RenderInlineInputOptions {
+	/** Live inline-input buffer. */
+	buffer: string;
+	/** Cursor offset; `undefined` / out-of-range → end-of-buffer fallback. */
+	cursorOffset: number | undefined;
+	/** Prefix for the first emitted line (e.g. `❯ 4. `). */
+	rowPrefix: string;
+	/** Prefix for continuation lines (whitespace of equal visible width). */
+	continuationPrefix: string;
+	/** Visible columns available for the buffer content (width − prefix width). */
+	contentWidth: number;
+	/** Per-line styling (single-select: `theme.selectedText`; multi-select: accent+bold). */
+	selectedText: (text: string) => string;
+	/**
+	 * `true` (single-select): wrap across lines at `contentWidth` (byte-identical to the
+	 * pre-extraction wrapping-select behavior).
+	 * `false` (multi-select): collapse to ONE line — truncate the plain buffer to
+	 * `contentWidth` with `…` when the cursor-marked content would overflow, keeping the
+	 * dialog height state-independent. The cursor is clipped past the visible window
+	 * (accepted trade): when the cursor-marked content fits it is rendered in full.
+	 */
+	multiline: boolean;
+}
+
+/**
+ * Resolve the cursor offset, falling back to end-of-buffer for `undefined`/out-of-range.
+ * Mirrors the original wrapping-select.resolveOffset exactly.
+ */
+function resolveCursorOffset(buffer: string, requested: number | undefined): number {
+	if (requested !== undefined && requested >= 0 && requested <= buffer.length) return requested;
+	return buffer.length;
+}
+
+/**
+ * Build the cursor-marked raw string for the whole buffer: `before | CURSOR_MARKER |
+ * SGR-7 reverse-video cell | SGR-27 | after`. The cell UNDER the cursor is the single
+ * grapheme at the offset (or U+00A0 NBSP at end-of-buffer / on a literal space — NBSP is
+ * wrap-safe where a literal space would tokenize as a wrap break). Zero characters shift;
+ * the column under the cursor inverts. `CURSOR_MARKER` is zero-width so wrap/truncate math
+ * is preserved.
+ */
+function buildCursorRaw(buffer: string, offset: number): string {
+	const before = buffer.slice(0, offset);
+	const [firstGrapheme] = graphemeSegmenter.segment(buffer.slice(offset));
+	const rawAt = firstGrapheme ? firstGrapheme.segment : "";
+	// NBSP (U+00A0) fallback: visually identical to a space, wrap-safe.
+	const atCursor = rawAt === "" || rawAt === " " ? "\xa0" : rawAt;
+	const after = buffer.slice(offset + rawAt.length);
+	return `${before}${CURSOR_MARKER}\x1b[7m${atCursor}\x1b[27m${after}`;
+}
+
+/**
+ * Render the inline-input row. `multiline: true` wraps (single-select, byte-identical to
+ * the pre-extraction output); `multiline: false` collapses to a single line.
+ *
+ * Cursor visualization follows the standard TUI input-widget pattern (ECMA-48 SGR 7
+ * reverse-video on the cell AT the cursor, not an inserted glyph) — same approach used by
+ * pi-tui Input.render, ink-text-input, terkelg/prompts, ratatui's user-input example.
+ */
+export function renderInlineInputRow(opts: RenderInlineInputOptions): string[] {
+	const { buffer, cursorOffset, rowPrefix, continuationPrefix, contentWidth, selectedText, multiline } = opts;
+	const offset = resolveCursorOffset(buffer, cursorOffset);
+
+	if (multiline) {
+		// Single-select: wrap at contentWidth. Byte-identical to the original
+		// wrapping-select.renderInlineInputRow output (same raw, same wrapTextWithAnsi,
+		// same prefix/selectedText per line).
+		const raw = buildCursorRaw(buffer, offset);
+		const wrapped = wrapTextWithAnsi(raw, contentWidth);
+		return wrapped.map((segment, index) => {
+			const prefix = index === 0 ? rowPrefix : continuationPrefix;
+			return selectedText(`${prefix}${segment}`);
+		});
+	}
+
+	// Multi-select: single line. Build the cursor markup on the full buffer; if it fits
+	// contentWidth, emit it as one line. If it overflows, fall back to truncating the PLAIN
+	// buffer (ANSI-safe — never cut a CURSOR_MARKER/SGR sequence) with `…` and clip the
+	// cursor. This keeps the row at exactly one line so naturalHeight stays state-independent.
+	const cursorRaw = buildCursorRaw(buffer, offset);
+	if (visibleWidth(cursorRaw) <= contentWidth) {
+		return [selectedText(`${rowPrefix}${cursorRaw}`)];
+	}
+	const clipped = truncateToWidth(buffer, contentWidth, "…");
+	return [selectedText(`${rowPrefix}${clipped}`)];
+}

package/extensions/ask-user-question/view/components/multi-select-view.ts

@@ -0,0 +1,191 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { ROW_INTENT_META } from "../../state/row-intent.js";
+import type { QuestionData } from "../../tool/types.js";
+import type { StatefulView } from "../stateful-view.js";
+import { renderInlineInputRow } from "./inline-input.js";
+
+const ACTIVE_POINTER = "❯ ";
+const INACTIVE_POINTER = "  ";
+const CHECKED = "[✔]";
+const UNCHECKED = "[ ]";
+const NUMBER_SEPARATOR = ". ";
+const BOX_LABEL_GAP = " ";
+// CC parity: description continuation indents to col 2 (past the pointer slot), NOT to the
+// full prefix column. Wrap width still uses prefixVisibleWidth so naturalHeight matches render.
+const CONTINUATION_INDENT = "  ";
+
+export const MULTI_SUBMIT_LABEL = "Submit";
+
+export interface MultiSelectOtherRowProps {
+	/** The "Type something." row is the focused row (optionIndex === options.length). */
+	active: boolean;
+	/** `state.inputMode` — true once the row has focus and keystrokes append to the buffer. */
+	inputMode: boolean;
+	/** Live inline-input buffer (read from `runtime.inputBuffer` / `ctx.inputBuffer`). */
+	inputBuffer: string;
+	inputCursorOffset: number | undefined;
+}
+
+export interface MultiSelectViewProps {
+	rows: ReadonlyArray<{ checked: boolean; active: boolean }>;
+	other: MultiSelectOtherRowProps;
+	nextActive: boolean;
+	nextLabel: string;
+}
+
+/**
+ * Renders the multi-select option list (one row per option — pointer + checkbox + label —
+ * plus zero or more wrapped continuation lines per description).
+ *
+ * `naturalHeight(width)` is state-INDEPENDENT (depends only on theme glyph widths,
+ * question.options, and width) so the host can compute a stable globalContentHeight
+ * without rendering. `naturalHeight(w) === render(w).length` for every props.
+ *
+ * `setProps(props)` is a pure field reassignment — no render, no invalidate side effects.
+ */
+export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
+	private props: MultiSelectViewProps;
+
+	constructor(
+		private readonly theme: Theme,
+		private readonly question: QuestionData,
+	) {
+		this.props = {
+			rows: [],
+			other: { active: false, inputMode: false, inputBuffer: "", inputCursorOffset: undefined },
+			nextActive: false,
+			nextLabel: ROW_INTENT_META.next.label,
+		};
+	}
+
+	setProps(props: MultiSelectViewProps): void {
+		this.props = props;
+	}
+
+	handleInput(_data: string): void {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+		const prefixWidth = this.prefixVisibleWidth();
+		const contentWidth = Math.max(1, width - prefixWidth);
+		const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+		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 pointer = row.active ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
+			// Checked uses the same `accent` hue as the active-row label so checked rows read
+			// as "selected" rather than "success" — matches the visual rhythm of the rest of
+			// the dialog (active pointer, label, picker rows are all accent).
+			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 num = String(i + 1).padStart(numberWidth, " ");
+			const line = `${pointer}${num}${NUMBER_SEPARATOR}${box}${BOX_LABEL_GAP}${styledLabel}`;
+			lines.push(truncateToWidth(line, width, ""));
+			if (opt.description) {
+				const wrapped = wrapTextWithAnsi(opt.description, contentWidth);
+				for (const segment of wrapped) {
+					lines.push(CONTINUATION_INDENT + this.theme.fg("muted", segment));
+				}
+			}
+		}
+
+		// "Type something." row — numbered N+1, box always [ ] muted UNCHECKED (never checkable).
+		// When focused + inputMode, render the label slot via the shared inline-input helper
+		// (single-line); otherwise the static label is truncated to contentWidth with `…`.
+		const other = this.props.other;
+		const otherPointer = other.active ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
+		const otherBox = this.theme.fg("muted", UNCHECKED);
+		const otherNum = String(this.question.options.length + 1).padStart(numberWidth, " ");
+		let otherLabel: string;
+		if (other.active && other.inputMode) {
+			const rendered = renderInlineInputRow({
+				buffer: other.inputBuffer,
+				cursorOffset: other.inputCursorOffset,
+				rowPrefix: "",
+				continuationPrefix: "",
+				contentWidth,
+				selectedText: (t) => this.theme.fg("accent", this.theme.bold(t)),
+				multiline: false,
+			});
+			otherLabel = rendered[0] ?? "";
+		} else {
+			const label = truncateToWidth(ROW_INTENT_META.other.label, contentWidth, "…");
+			otherLabel = other.active ? this.theme.fg("accent", this.theme.bold(label)) : label;
+		}
+		lines.push(
+			truncateToWidth(
+				`${otherPointer}${otherNum}${NUMBER_SEPARATOR}${otherBox}${BOX_LABEL_GAP}${otherLabel}`,
+				width,
+				"",
+			),
+		);
+
+		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, ""));
+		return lines;
+	}
+
+	/**
+	 * Returns the [startRow, endRow) range of the active (focused) row within
+	 * `render(width)`. Labels are always 1 row (truncated); descriptions wrap.
+	 */
+	focusedItemRowRange(width: number): [number, number] {
+		const prefixWidth = this.prefixVisibleWidth();
+		const contentWidth = Math.max(1, width - prefixWidth);
+		let row = 0;
+		for (let i = 0; i < this.question.options.length; i++) {
+			const opt = this.question.options[i];
+			const r = this.props.rows[i];
+			if (!opt || !r) continue;
+			const itemHeight = 1 + (opt.description ? wrapTextWithAnsi(opt.description, contentWidth).length : 0);
+			if (r.active) {
+				return [row, row + itemHeight];
+			}
+			row += itemHeight;
+		}
+		// "Type something." row is always exactly 1 line (truncated, no description).
+		if (this.props.other.active) {
+			return [row, row + 1];
+		}
+		row += 1;
+		if (this.props.nextActive) {
+			return [row, row + 1];
+		}
+		return [0, 0];
+	}
+
+	naturalHeight(width: number): number {
+		const contentWidth = Math.max(1, width - this.prefixVisibleWidth());
+		let total = 0;
+		for (const opt of this.question.options) {
+			if (!opt) continue;
+			total += 1; // row line
+			if (opt.description) {
+				total += wrapTextWithAnsi(opt.description, contentWidth).length;
+			}
+		}
+		return total + 2; // "Type something." row + Next sentinel row (neither wraps).
+	}
+
+	private prefixVisibleWidth(): number {
+		// Canonical prefix for OPTION rows: INACTIVE_POINTER + numberWidth digits + NUMBER_SEPARATOR
+		// + UNCHECKED + BOX_LABEL_GAP. State-independent because ACTIVE/INACTIVE pointer share
+		// visibleWidth, CHECKED/UNCHECKED share visibleWidth, and numberWidth is constant per question.
+		// The number column fits `options.length + 1` so the "Type something." row's N+1 number
+		// is never clipped. The Next sentinel uses a bare `pointer + "Next"` shape — its width
+		// never exceeds this prefix at any reasonable terminal width, so it's safe to leave it
+		// out of the canonical computation.
+		const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+		return (
+			visibleWidth(INACTIVE_POINTER) + numberWidth + visibleWidth(`${NUMBER_SEPARATOR}${UNCHECKED}${BOX_LABEL_GAP}`)
+		);
+	}
+}

package/extensions/ask-user-question/view/components/option-list-view.ts

@@ -0,0 +1,68 @@
+import type { StatefulView } from "../stateful-view.js";
+import { WrappingSelect, type WrappingSelectItem, type WrappingSelectTheme } from "./wrapping-select.js";
+
+/**
+ * Maximum number of option rows visible in the WrappingSelect window. Lifted here from
+ * `preview-pane.ts` so the cap travels with the option-list owner.
+ */
+export const MAX_VISIBLE_OPTIONS = 10;
+
+export interface OptionListViewConfig {
+	items: readonly WrappingSelectItem[];
+	theme: WrappingSelectTheme;
+}
+
+/**
+ * Per-tick projection of OptionListView state. After Phase 11b, `inputBuffer`
+ * is part of the props bag — the session-owned `inlineInput` (a headless
+ * `pi-tui` Input instance) supplies its current `getValue()` here per tick.
+ * `OptionListView` is purely props-driven; the imperative buffer surface and
+ * read-back getters are gone.
+ */
+export interface OptionListViewProps {
+	selectedIndex: number;
+	focused: boolean;
+	inputBuffer: string;
+	inputCursorOffset?: number;
+	/** Optional previously-confirmed indicator. Omit when no marker should be drawn. */
+	confirmed?: { index: number; labelOverride?: string };
+}
+
+/**
+ * Sole owner of the option list's interactive state. Wraps a single
+ * `WrappingSelect`. Implements `StatefulView<OptionListViewProps>`:
+ * `setProps` is the only mutator; render output reflects the last props
+ * received.
+ */
+export class OptionListView implements StatefulView<OptionListViewProps> {
+	private readonly select: WrappingSelect;
+
+	constructor(config: OptionListViewConfig) {
+		this.select = new WrappingSelect(config.items, Math.min(config.items.length, MAX_VISIBLE_OPTIONS), config.theme, {
+			numberStartOffset: 0,
+			totalItemsForNumbering: config.items.length,
+		});
+	}
+
+	setProps(props: OptionListViewProps): void {
+		this.select.setSelectedIndex(props.selectedIndex);
+		this.select.setFocused(props.focused);
+		this.select.setConfirmedIndex(props.confirmed?.index, props.confirmed?.labelOverride);
+		this.select.setInputBuffer(props.inputBuffer);
+		this.select.setInputCursorOffset(props.inputCursorOffset);
+	}
+
+	handleInput(_data: string): void {}
+
+	invalidate(): void {
+		this.select.invalidate();
+	}
+
+	render(width: number): string[] {
+		return this.select.render(width);
+	}
+
+	focusedItemRowRange(width: number): [number, number] {
+		return this.select.focusedItemRowRange(width);
+	}
+}

package/extensions/ask-user-question/view/components/preview/markdown-content-cache.ts

@@ -0,0 +1,76 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Markdown, type MarkdownTheme, visibleWidth } from "@earendil-works/pi-tui";
+import type { QuestionData } from "../../../tool/types.js";
+import { stripFenceMarkers } from "./preview-box-renderer.js";
+
+/** CC parity in side-by-side layout. */
+export const MAX_PREVIEW_HEIGHT_SIDE_BY_SIDE = 20;
+/** Preserves narrow-terminal protection in stacked layout. */
+export const MAX_PREVIEW_HEIGHT_STACKED = 15;
+export const NO_PREVIEW_TEXT = "No preview available";
+/** 1 blank separator + 1 affordance text row reserved when `hasAnyPreview` (height stability of the affordance row's offset relative to the box). */
+export const NOTES_AFFORDANCE_OVERHEAD = 2;
+
+/**
+ * Per-question cache for rendered markdown previews. Width-keyed: switching the
+ * inner width invalidates every cached `Markdown`'s render output (pi-tui's
+ * `Markdown.render(width)` re-wraps when width changes).
+ *
+ * Replaces the inline `previewTexts`, `markdownCache`, `cachedWidth` triple from
+ * the previous monolithic `preview-pane.ts`. One Markdown per option, lazy on
+ * first request, never re-constructed — count semantics frozen by tests.
+ */
+export class MarkdownContentCache {
+	private readonly previewTexts: Map<number, string>;
+	private readonly markdownCache: Map<number, Markdown>;
+	private cachedWidth: number | undefined;
+	private readonly theme: Theme;
+	private readonly markdownTheme: MarkdownTheme;
+
+	constructor(question: QuestionData, theme: Theme, markdownTheme: MarkdownTheme) {
+		this.theme = theme;
+		this.markdownTheme = markdownTheme;
+		this.previewTexts = new Map();
+		for (let i = 0; i < question.options.length; i++) {
+			const raw = question.options[i]?.preview;
+			if (raw && raw.length > 0) this.previewTexts.set(i, raw);
+		}
+		this.markdownCache = new Map();
+	}
+
+	hasAnyPreview(): boolean {
+		return this.previewTexts.size > 0;
+	}
+
+	has(optionIndex: number): boolean {
+		return this.previewTexts.has(optionIndex);
+	}
+
+	/**
+	 * Compute the body lines for a given option at a given inner width. Width changes
+	 * invalidate the per-Markdown render cache.
+	 */
+	bodyFor(optionIndex: number, innerWidth: number): string[] {
+		if (this.cachedWidth !== innerWidth) {
+			for (const md of this.markdownCache.values()) md.invalidate();
+			this.cachedWidth = innerWidth;
+		}
+		const text = this.previewTexts.get(optionIndex);
+		if (!text) {
+			const placeholder = this.theme.fg("dim", NO_PREVIEW_TEXT);
+			const pad = Math.max(0, innerWidth - visibleWidth(placeholder));
+			return [placeholder + " ".repeat(pad)];
+		}
+		let md = this.markdownCache.get(optionIndex);
+		if (!md) {
+			md = new Markdown(text, 0, 0, this.markdownTheme);
+			this.markdownCache.set(optionIndex, md);
+		}
+		return stripFenceMarkers(md.render(innerWidth));
+	}
+
+	invalidate(): void {
+		for (const md of this.markdownCache.values()) md.invalidate();
+		this.cachedWidth = undefined;
+	}
+}

package/extensions/ask-user-question/view/components/preview/preview-block-renderer.ts

@@ -0,0 +1,108 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { MarkdownTheme } from "@earendil-works/pi-tui";
+import type { QuestionData } from "../../../tool/types.js";
+import {
+	MAX_PREVIEW_HEIGHT_SIDE_BY_SIDE,
+	MAX_PREVIEW_HEIGHT_STACKED,
+	MarkdownContentCache,
+	NOTES_AFFORDANCE_OVERHEAD,
+} from "./markdown-content-cache.js";
+import {
+	BORDER_HORIZONTAL_OVERHEAD,
+	BORDER_INNER_PADDING_HORIZONTAL,
+	BORDER_VERTICAL_OVERHEAD,
+	computeBoxDimensions,
+	renderBorderedBox,
+} from "./preview-box-renderer.js";
+import type { PreviewLayoutMode } from "./preview-layout-decider.js";
+
+/**
+ * Affordance text shown below the bordered preview when focused on a preview-bearing option.
+ * Re-exported by `preview-pane.ts` for the existing test surface.
+ */
+export const NOTES_AFFORDANCE_TEXT = "Notes: press n to add notes";
+
+export interface PreviewBlockRendererConfig {
+	question: QuestionData;
+	theme: Theme;
+	markdownTheme: MarkdownTheme;
+}
+
+/**
+ * Renders the bordered markdown preview block for a single question (one block per render call,
+ * for the option at `optionIndex`). Owns a per-question `MarkdownContentCache`.
+ *
+ * NOT a `Component` — pure render-and-measure helper consumed by `PreviewPane`. The layout mode
+ * is threaded as an explicit param (never re-derived from column width post-split).
+ *
+ * The affordance row is always emitted (visually empty when gated) so the preview block's row
+ * count is height-stable across affordance-state transitions.
+ */
+export class PreviewBlockRenderer {
+	private readonly theme: Theme;
+	private readonly cache: MarkdownContentCache;
+
+	constructor(config: PreviewBlockRendererConfig) {
+		this.theme = config.theme;
+		this.cache = new MarkdownContentCache(config.question, config.theme, config.markdownTheme);
+	}
+
+	hasAnyPreview(): boolean {
+		return this.cache.hasAnyPreview();
+	}
+
+	has(optionIndex: number): boolean {
+		return this.cache.has(optionIndex);
+	}
+
+	invalidate(): void {
+		this.cache.invalidate();
+	}
+
+	/**
+	 * Height contribution of the preview block: `BORDER_VERTICAL_OVERHEAD + contentRows +
+	 * NOTES_AFFORDANCE_OVERHEAD`. Always returns the same value as `renderBlock(...).length`
+	 * — 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 rawRows = this.cache.bodyFor(optionIndex, innerWidth).length;
+		const contentRows = Math.min(rawRows, contentBudget);
+		return BORDER_VERTICAL_OVERHEAD + contentRows + NOTES_AFFORDANCE_OVERHEAD;
+	}
+
+	/**
+	 * Render the full preview block at `width`: bordered box + blank separator + affordance row.
+	 * `focused` and `notesVisible` together gate the affordance text (visible only when the
+	 * focused option carries a preview AND notes mode is inactive). The affordance row is ALWAYS
+	 * emitted (as an empty string when gated) so the row count is invariant.
+	 */
+	renderBlock(
+		width: number,
+		optionIndex: number,
+		mode: PreviewLayoutMode,
+		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 raw = this.cache.bodyFor(optionIndex, maxInnerWidth);
+		const truncated = raw.length > contentBudget;
+		const hidden = truncated ? raw.length - contentBudget : 0;
+		const contentLines = truncated ? raw.slice(0, contentBudget) : raw;
+
+		const { boxWidth } = computeBoxDimensions(contentLines, maxInnerWidth);
+		const colorFn = (s: string) => this.theme.fg("accent", s);
+		const boxedLines = renderBorderedBox(contentLines, boxWidth, colorFn, hidden);
+
+		const showAffordance = focused && !notesVisible && this.cache.has(optionIndex);
+		const affordance = showAffordance
+			? this.theme.fg("muted", NOTES_AFFORDANCE_TEXT)
+			: "";
+		return [...boxedLines, "", affordance];
+	}
+}