@xprnvd/pi-context-view 0.0.0-stage → 0.7.2

package/src/ui/json-preview.ts

@@ -0,0 +1,41 @@
+/**
+ * Preview-only expansion of the JSON runs the model marks structurally: a
+ * tool's parameter schema, tool-call arguments, and serialized message
+ * content. Every preview level expands them; the compact provider-bound form
+ * still backs every token estimate. Pure string logic — no pi or TUI access.
+ */
+import type { JsonSpan } from "../model.ts";
+
+/** Spaces per nesting level, matching how tool schemas are usually authored. */
+const JSON_INDENT = 2;
+
+/**
+ * Text with its marked JSON run re-serialized across indented lines. Text
+ * without a span, and a span whose slice no longer parses, are returned
+ * unchanged, so a stale marker degrades to the captured form.
+ */
+export function expandJsonSpan(text: string, span: JsonSpan | undefined): string {
+	if (span === undefined) return text;
+	const expanded = prettifyJson(text.slice(span.start, span.end));
+	if (expanded === undefined) return text;
+	return `${text.slice(0, span.start)}${expanded}${text.slice(span.end)}`;
+}
+
+/**
+ * Re-anchor a span after `removed` characters were dropped from the front of
+ * its text; undefined once the removal reaches into the JSON run itself.
+ */
+export function shiftJsonSpan(span: JsonSpan | undefined, removed: number): JsonSpan | undefined {
+	if (span === undefined || removed === 0) return span;
+	if (removed > span.start) return undefined;
+	return { start: span.start - removed, end: span.end - removed };
+}
+
+/** Indented re-serialization of one JSON document, or undefined when the run does not parse. */
+function prettifyJson(source: string): string | undefined {
+	try {
+		return JSON.stringify(JSON.parse(source), undefined, JSON_INDENT);
+	} catch {
+		return undefined;
+	}
+}

package/src/ui/layout.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared pi-native fullscreen-view helpers: indentation constants,
+ * terminal-height viewport math, width fitting, hint-row formatting, and
+ * step-navigation key matching used by the Usage and Injections views. Pure
+ * string/number logic — no pi access.
+ */
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Hint-row key label for the single-step navigation keys both views accept. */
+export const STEP_KEY_HINT = "↑↓/jk";
+
+/** Two-space indent for descriptions, counters, hints, and body content. */
+export const BODY_INDENT = "  ";
+export const DEFAULT_TERMINAL_ROWS = 24;
+
+/** How many content rows fit and whether an overflow indicator is needed. */
+export interface Viewport {
+	visibleCount: number;
+	showScroll: boolean;
+}
+
+/** Divide terminal rows between content and an overflow indicator. */
+export function calculateViewport(
+	itemCount: number,
+	terminalRows: number,
+	fixedLineCount: number,
+	extraLineCount = 0,
+): Viewport {
+	const available = Math.max(1, terminalRows - fixedLineCount - extraLineCount);
+	const showScroll = itemCount > available && available > 1;
+	return {
+		visibleCount: Math.max(1, available - (showScroll ? 1 : 0)),
+		showScroll,
+	};
+}
+
+/** Keep emergency short-terminal output bounded while preserving both borders. */
+export function fitToTerminalHeight(lines: string[], terminalRows: number, border: string): string[] {
+	if (lines.length <= terminalRows) return lines;
+	if (terminalRows === 1) return [border];
+	return [...lines.slice(0, terminalRows - 1), border];
+}
+
+/** Normalize an injected terminal-height reading to a usable positive integer. */
+export function normalizeTerminalRows(rows: number): number {
+	return Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : DEFAULT_TERMINAL_ROWS;
+}
+
+/** Whether input requests one step backwards: Up or vim-style `k`. */
+export function isStepBackKey(data: string): boolean {
+	return matchesKey(data, Key.up) || data === "k";
+}
+
+/** Whether input requests one step forwards: Down or vim-style `j`. */
+export function isStepForwardKey(data: string): boolean {
+	return matchesKey(data, Key.down) || data === "j";
+}
+
+/** Whether input requests one page backwards: PgUp or `Ctrl+U`. */
+export function isPageBackKey(data: string): boolean {
+	return matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("u"));
+}
+
+/** Whether input requests one page forwards: PgDn or `Ctrl+D`. */
+export function isPageForwardKey(data: string): boolean {
+	return matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("d"));
+}
+
+/** Truncate one rendered line to the supplied width. */
+export function fitLine(line: string, width: number): string {
+	return truncateToWidth(line, width, "…");
+}
+
+/**
+ * Rows a description block occupies, including the blank row above it; zero
+ * when collapsed. A description is the least important block on a frame, so
+ * each view drops the whole block once its own content threshold is reached.
+ */
+export function descriptionBlockRows(lines: readonly string[]): number {
+	return lines.length === 0 ? 0 : lines.length + 1;
+}
+
+/** Wrap plain dialog-description text with semantic color and an indented continuation column. */
+export function wrapDescriptionLines(
+	theme: Theme,
+	text: string,
+	color: ThemeColor,
+	width: number,
+): string[] {
+	const indentWidth = Math.min(BODY_INDENT.length, Math.max(0, width - 1));
+	const indent = BODY_INDENT.slice(0, indentWidth);
+	const contentWidth = Math.max(1, width - indentWidth);
+	const wrapped = wrapTextWithAnsi(text, contentWidth);
+	return (wrapped.length === 0 ? [""] : wrapped).map((line) =>
+		truncateToWidth(theme.fg(color, `${indent}${line}`), width, "")
+	);
+}
+
+/**
+ * Keep wrapped notice blocks within `maxLines` rows, so a broken configuration
+ * file cannot push a view's content off the frame. On overflow, the last kept
+ * row becomes a `… +N more` notice, wrapped by `wrapNotice`, counting every
+ * block not shown whole.
+ */
+export function capNoticeLines(
+	blocks: readonly (readonly string[])[],
+	maxLines: number,
+	wrapNotice: (notice: string) => string[],
+): string[] {
+	const lines = blocks.flat();
+	if (lines.length <= maxLines) return lines;
+	const kept = lines.slice(0, maxLines - 1);
+	const hidden = blocks.length - countWholeBlocks(blocks, kept.length);
+	return [...kept, ...wrapNotice(`… +${hidden} more`)];
+}
+
+/** Notices whose wrapped lines fit entirely into the first `keptLines` rows. */
+function countWholeBlocks(blocks: readonly (readonly string[])[], keptLines: number): number {
+	let used = 0;
+	let whole = 0;
+	for (const block of blocks) {
+		if (used + block.length > keptLines) break;
+		used += block.length;
+		whole += 1;
+	}
+	return whole;
+}
+
+/** Spread left and right content across the width, truncating the left side on overlap. */
+export function spreadLine(left: string, right: string, width: number): string {
+	const gap = width - visibleWidth(left) - visibleWidth(right);
+	if (gap < 1) {
+		return fitLine(`${truncateToWidth(left, Math.max(1, width - visibleWidth(right) - 2), "…")} ${right}`, width);
+	}
+	return `${left}${" ".repeat(gap)}${right}`;
+}
+
+/** Pi-style hint row: two-space indent, `key description` pairs joined by ` · `. */
+export function hintRow(theme: Theme, hints: ReadonlyArray<readonly [string, string]>): string {
+	const separator = theme.fg("dim", " · ");
+	return `${BODY_INDENT}${hints.map(([key, description]) => hint(theme, key, description)).join(separator)}`;
+}
+
+/** Pi-style hint: dim key, slightly brighter (muted) description. */
+function hint(theme: Theme, key: string, description: string): string {
+	return theme.fg("dim", key) + theme.fg("muted", ` ${description}`);
+}

package/src/ui/markers.ts

@@ -0,0 +1,253 @@
+/**
+ * State markers rendered after a token estimate, token diffs, and the bullet
+ * preview legend and selected-row status fields that explain them. Markers
+ * name how pi accounts for a part rather than a usage category, so their colors are fixed instead
+ * of configurable. Pure string logic shared by both views.
+ */
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+import type { ForcedEdit, RequestChange, TokenDiff } from "../model.ts";
+import { BODY_INDENT, fitLine } from "./layout.ts";
+
+/** Dim separator introducing a state marker after the estimate it explains. */
+const MARKER_SEPARATOR = " · ";
+
+/** Markers a frame can show, in the fixed order their legend bullets render. */
+const MARKER_ORDER = [
+	"highlighted", "guess", "dropped", "moved", "forced", "forced-edit", "diff", "request-only",
+] as const;
+
+/** One marked state a description bullet explains; `diff` stands for `+N`/`-N` token diffs. */
+export type ContextMarker = (typeof MARKER_ORDER)[number];
+
+/**
+ * The state of one part or row that markers show; only a `forced` change has a
+ * marker of its own. A replaced edit shows the same `Forced` keyword.
+ */
+export interface MarkedState {
+	readonly dropped?: boolean;
+	readonly moved?: boolean;
+	readonly change?: RequestChange;
+	readonly forcedEdit?: Pick<ForcedEdit, "sent">;
+	readonly requestOnly?: boolean;
+}
+
+/**
+ * What the token diffs of a preview compare with:
+ *   default-prompt     pi's default prompt, for contributions under pi
+ *   session            the session, for extension tools and messages
+ *   captured-request   the captured request, for payload changes
+ */
+export type DiffBase = "default-prompt" | "session" | "captured-request";
+
+/** Preview diff-legend sentences by base; the fallback sentence names none. */
+const DIFF_EXPLANATIONS: Record<DiffBase | "list", string> = {
+	list: " Tokens extensions added or removed.",
+	"default-prompt": " Tokens extensions added or removed, compared with pi’s default prompt.",
+	session: " Tokens extensions added or removed, compared with the session.",
+	"captured-request": " Tokens added or removed, compared with the captured request.",
+};
+
+/** Bullet marker and hanging indent of a legend entry, both two columns wide. */
+const BULLET_MARKER = "- ";
+const BULLET_INDENT = `${BODY_INDENT}  `;
+
+/** A legend sentence: dim text, with runs that name a colored mark shown in that mark's color. */
+type LegendText = string | ReadonlyArray<string | { readonly text: string; readonly color: ThemeColor }>;
+
+/** Keyword opening a legend bullet, its fixed color, and the sentence it heads. */
+interface MarkerLegend {
+	readonly keyword: string;
+	readonly color: ThemeColor;
+	readonly explanation: LegendText;
+}
+
+/** One fixed sentence per marker, independent of the others. */
+const MARKER_LEGENDS: Record<Exclude<ContextMarker, "diff">, MarkerLegend> = {
+	highlighted: {
+		keyword: "Highlighted",
+		// Extension lines carry this color, so the bullet opens in it too.
+		color: "syntaxNumber",
+		explanation: " parts are injected by extensions into pi’s system prompt.",
+	},
+	guess: {
+		keyword: "(guess)",
+		color: "dim",
+		explanation: " sources are inferred from the injected text itself.",
+	},
+	dropped: {
+		keyword: "Dropped",
+		color: "toolDiffRemoved",
+		explanation: " parts were replaced by a custom system prompt and are counted nowhere.",
+	},
+	moved: {
+		keyword: "Moved",
+		color: "warning",
+		explanation: " blocks appear in a different position in the system prompt than usual.",
+	},
+	forced: {
+		keyword: "Forced",
+		color: "warning",
+		explanation: " prompts replace pi’s system prompt for this request.",
+	},
+	"forced-edit": {
+		keyword: "Forced",
+		color: "warning",
+		// The signs open diff lines in these colors, so the sentence names them in the same colors
+		explanation: [
+			" parts were edited for this request, but the forced prompt discarded the edit. Lines marked ",
+			{ text: "+", color: "toolDiffAdded" },
+			" were sent to the model; lines marked ",
+			{ text: "-", color: "toolDiffRemoved" },
+			" were never sent.",
+		],
+	},
+	"request-only": {
+		keyword: "Request-Only",
+		color: "dim",
+		explanation: " Includes changes made only in this request, not saved in the session.",
+	},
+};
+
+/**
+ * Markers the Injections status bar explains on the selected row; its Change
+ * field covers diffs and Request-Only. A replaced edit is explained by whether
+ * the forced prompt still sent its part.
+ */
+export type StatusMarker = "dropped" | "moved" | "forced" | "forced-edit-sent" | "forced-edit-unsent";
+
+/** Status-bar explanation of each marker, about the one selected row, and the legend naming its keyword. */
+const MARKER_STATUS: Record<StatusMarker, { readonly legend: keyof typeof MARKER_LEGENDS; readonly text: string }> = {
+	dropped: { legend: "dropped", text: "a custom system prompt replaced this part; counted nowhere" },
+	moved: { legend: "moved", text: "in a different position in the system prompt than usual" },
+	forced: { legend: "forced", text: "an extension’s prompt replaced pi’s system prompt for this request" },
+	"forced-edit-sent": {
+		legend: "forced-edit",
+		text: "a forced prompt replaced this part’s request edit; Pi sent the forced prompt’s version",
+	},
+	"forced-edit-unsent": {
+		legend: "forced-edit",
+		text: "a forced prompt replaced this part’s request edit; Pi sent nothing",
+	},
+};
+
+/** Themed marker naming content pi never sent, for a preview subheader or a hierarchy row. */
+export function droppedMarker(theme: Theme): string {
+	return stateMarker(theme, MARKER_LEGENDS.dropped);
+}
+
+/** Themed marker naming content pi sends from elsewhere in the prompt than it wrote it. */
+export function movedMarker(theme: Theme): string {
+	return stateMarker(theme, MARKER_LEGENDS.moved);
+}
+
+/** `+N` with thousands separators; the plain text of a diff column. */
+export function formatDiffAdded(tokens: number): string {
+	return `+${tokens.toLocaleString("en-US")}`;
+}
+
+/** `-N` with thousands separators; the plain text of a diff column. */
+export function formatDiffRemoved(tokens: number): string {
+	return `-${tokens.toLocaleString("en-US")}`;
+}
+
+/**
+ * A token diff after an estimate in preview metadata, behind a dim separator:
+ * `+N` in `toolDiffAdded` and `-N` in `toolDiffRemoved`, leaving out a zero
+ * side. Empty without a diff.
+ */
+export function diffMarker(theme: Theme, diff: TokenDiff | undefined): string {
+	const sides: string[] = [];
+	if (diff !== undefined && diff.added > 0) sides.push(theme.fg("toolDiffAdded", formatDiffAdded(diff.added)));
+	if (diff !== undefined && diff.removed > 0) sides.push(theme.fg("toolDiffRemoved", formatDiffRemoved(diff.removed)));
+	return sides.length === 0 ? "" : `${theme.fg("dim", MARKER_SEPARATOR)}${sides.join(" ")}`;
+}
+
+/** Themed marker naming a request that carried an extension's forced prompt instead of pi's. */
+export function forcedMarker(theme: Theme): string {
+	return stateMarker(theme, MARKER_LEGENDS.forced);
+}
+
+/**
+ * Every state marker of one part, in legend order: dropped, moved, forced,
+ * then request-only. Empty when the part carries none. Token diffs, not
+ * markers, show what an added, modified, or deleted part changed.
+ */
+export function stateMarkers(theme: Theme, part: MarkedState): string {
+	let markers = part.dropped === true ? droppedMarker(theme) : part.moved === true ? movedMarker(theme) : "";
+	if (part.change === "forced" || part.forcedEdit !== undefined) markers += forcedMarker(theme);
+	if (part.requestOnly === true) markers += stateMarker(theme, MARKER_LEGENDS["request-only"]);
+	return markers;
+}
+
+/** Markers one part carries, including its token diff, for the legend of the frame showing it. */
+export function partMarkers(part: MarkedState & { readonly diff?: TokenDiff }): ContextMarker[] {
+	const markers: ContextMarker[] = [];
+	if (part.dropped === true) markers.push("dropped");
+	if (part.moved === true) markers.push("moved");
+	if (part.change === "forced") markers.push("forced");
+	if (part.forcedEdit !== undefined) markers.push("forced-edit");
+	if (part.diff !== undefined && (part.diff.added > 0 || part.diff.removed > 0)) markers.push("diff");
+	if (part.requestOnly === true) markers.push("request-only");
+	return markers;
+}
+
+/** Themed suffix naming an owner this extension inferred rather than one pi reported. */
+export function guessMarker(theme: Theme): string {
+	const { color, keyword } = MARKER_LEGENDS.guess;
+	return theme.fg(color, ` ${keyword}`);
+}
+
+/**
+ * Description bullets explaining the markers one frame shows, in fixed order
+ * and without duplicates. Callers pass only the markers actually visible there,
+ * so a view never explains a state it does not render. `diffBase` names what
+ * the preview's token diffs compare with; omitted, the bullet names no base.
+ */
+export function markerLegendLines(
+	theme: Theme,
+	markers: Iterable<ContextMarker>,
+	width: number,
+	diffBase?: DiffBase,
+): string[] {
+	const shown = new Set(markers);
+	return MARKER_ORDER.filter((marker) => shown.has(marker)).flatMap((marker) => {
+		if (marker === "diff") {
+			const keyword = `${theme.fg("toolDiffAdded", "+N")} ${theme.fg("toolDiffRemoved", "-N")}`;
+			return bulletLines(theme, keyword, DIFF_EXPLANATIONS[diffBase ?? "list"], width);
+		}
+		const legend = MARKER_LEGENDS[marker];
+		return bulletLines(theme, theme.fg(legend.color, legend.keyword), legend.explanation, width);
+	});
+}
+
+/**
+ * Status-bar field explaining one marker of the selected row: the keyword in
+ * the marker's fixed color, then a dim colon and explanation.
+ */
+export function markerStatusField(theme: Theme, marker: StatusMarker): string {
+	const status = MARKER_STATUS[marker];
+	const { color, keyword } = MARKER_LEGENDS[status.legend];
+	return `${theme.fg(color, keyword)}${theme.fg("dim", `: ${status.text}`)}`;
+}
+
+/** One dim description bullet with a hanging indent, for a note that is not a marker legend. */
+export function noteBulletLines(theme: Theme, text: string, width: number): string[] {
+	return bulletLines(theme, "", text, width);
+}
+
+/** Dim separator plus the keyword in the one fixed color its legend bullet also opens with. */
+function stateMarker(theme: Theme, legend: MarkerLegend): string {
+	return `${theme.fg("dim", MARKER_SEPARATOR)}${theme.fg(legend.color, legend.keyword)}`;
+}
+
+/** One bullet: dim marker, styled keyword in the colors it explains, dim sentence, hanging indent. */
+function bulletLines(theme: Theme, keyword: string, explanation: LegendText, width: number): string[] {
+	const runs = typeof explanation === "string" ? [explanation] : explanation;
+	const sentence = runs.map((run) => typeof run === "string" ? theme.fg("dim", run) : theme.fg(run.color, run.text));
+	const text = `${keyword}${sentence.join("")}`;
+	const wrapped = wrapTextWithAnsi(text, Math.max(1, width - BULLET_INDENT.length));
+	const lead = `${BODY_INDENT}${theme.fg("dim", BULLET_MARKER)}`;
+	return wrapped.map((line, index) => fitLine(`${index === 0 ? lead : BULLET_INDENT}${line}`, width));
+}

package/src/ui/notes.ts

@@ -0,0 +1,117 @@
+/** Presentation notes, kept separate from layout and from the states they explain. */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { InjectionItem } from "../model.ts";
+import type { GuardResult } from "../snapshot.ts";
+import { normalizeInlineText } from "../text.ts";
+import { wrapDescriptionLines } from "./layout.ts";
+import { noteBulletLines } from "./markers.ts";
+
+/** Payload attention is independent of its compact label or longer explanation. */
+export type PayloadCheck = "pending" | "unchecked" | "partial";
+
+/** A note's identity survives copy changes; text may contain theme styling, never raw content. */
+export interface DescriptionNote {
+	readonly kind: "overview" | "degraded" | "probe" | "probing-disabled" | "payload-check" | "hidden-tools" | "payload-changes" | "thinking" | "empty";
+	readonly text: string;
+}
+
+/** Capture metadata that can be explained without opening raw content. */
+export interface InjectionsNotesInput {
+	readonly degradedReason?: string;
+	readonly probe?: boolean;
+	/** True when no request was captured yet and configuration disables the silent probe. */
+	readonly probingDisabled?: boolean;
+	readonly guard?: GuardResult;
+	readonly hiddenTools?: readonly string[];
+	readonly items: readonly InjectionItem[];
+}
+
+/** A complete comparison and a fallback without a request need no attention state. */
+export function payloadCheck(guard: GuardResult | undefined): PayloadCheck | undefined {
+	if (guard?.status === "pending") return "pending";
+	if (guard?.status === "incomplete") return guard.findings === undefined ? "unchecked" : "partial";
+	return undefined;
+}
+
+/** Compact wording for an independently classified payload check. */
+export function payloadCheckLabel(check: PayloadCheck): string {
+	const labels: Record<PayloadCheck, string> = {
+		pending: "pending", unchecked: "not checked", partial: "partly checked",
+	};
+	return labels[check];
+}
+
+/** Origin stays visible even when the optional notes collapse. */
+export function requestOriginLabel(probe = false): string {
+	return probe ? "[Request Probe]" : "[Latest Request]";
+}
+
+/** Build optional notes in presentation order, with dynamic metadata sanitized before styling. */
+export function injectionsNotes(theme: Theme, input: InjectionsNotesInput): DescriptionNote[] {
+	const notes: DescriptionNote[] = [{ kind: "overview", text: "Injections into the model context, with token estimates." }];
+	if (input.degradedReason !== undefined) {
+		notes.push({ kind: "degraded", text: theme.fg("warning", "Degraded") + theme.fg("dim", ": pi-native fallback used") });
+	}
+	if (input.probingDisabled === true) notes.push(probingDisabledNote(theme));
+	if (input.probe === true) {
+		notes.push({ kind: "probe", text: `Captured by a ${theme.fg("warning", "request probe")}` + theme.fg(
+			"dim", " with an empty prompt. Prompt-dependent injections may be missing.",
+		) });
+	}
+	const check = payloadCheck(input.guard);
+	if (check === "pending") {
+		notes.push({ kind: "payload-check", text: "Payload changes are not checked yet: the comparison is pending." });
+	} else if (input.guard?.status === "incomplete") {
+		const reason = normalizeInlineText(input.guard.reason);
+		notes.push({ kind: "payload-check", text: check === "unchecked"
+			? `Payload changes were not checked: ${reason}`
+			: `Payload changes were checked only in part: ${reason}` });
+	}
+	const tools = input.hiddenTools ?? [];
+	if (tools.length > 0) {
+		const names = [...tools].sort().map(normalizeInlineText).join(", ");
+		notes.push({ kind: "hidden-tools", text: `${tools.length} ${tools.length === 1 ? "tool" : "tools"} hidden by pi: ${names}.` });
+	}
+	return [...notes, ...findingNotes(input.items)];
+}
+
+/** Payload findings explain a separate observation layer in the list and preview. */
+export function findingNotes(items: readonly InjectionItem[]): DescriptionNote[] {
+	return items.some((item) => item.kind === "payload-change")
+		? [{ kind: "payload-changes", text: "Payload changes appear only in the provider payload. Their sources are unknown." }]
+		: [];
+}
+
+/** Explain what a view opened before the first request misses while the silent probe is disabled. */
+export function probingDisabledNote(theme: Theme): DescriptionNote {
+	return { kind: "probing-disabled", text: `${theme.fg("warning", "Request probing")}` + theme.fg(
+		"dim", " is disabled. Request-only injections may be missing before the first prompt.",
+	) };
+}
+
+/** Explain why category estimates need not reconcile with reported usage. */
+export function usageNote(): DescriptionNote {
+	return { kind: "overview", text: "Estimated context for the next model request. " +
+		"Token counts are approximate and may differ from the provider's estimate." };
+}
+
+/** Explain the different bases of thinking estimates, without retaining signatures. */
+export function thinkingNote(): DescriptionNote {
+	return { kind: "thinking", text: "Entry headers read: [DD-MM-YYYY] [assistant] visible + Reasoning ≈invisible (≈total). " +
+		"≈ is a provider-reported count; ~ is a rough approximation when no breakdown " +
+		"is reported and excluded from category totals. " +
+		"Encoded replaces Reasoning when the provider replays encrypted reasoning with its message." };
+}
+
+/** Empty content is explicit, rather than an unexplained blank preview. */
+export function emptyPreviewNote(): DescriptionNote {
+	return { kind: "empty", text: "No content captured for this category." };
+}
+
+/** Wrap a complete note; the caller decides whether the whole block fits. */
+export function descriptionNoteLines(theme: Theme, note: DescriptionNote, width: number): string[] {
+	return note.kind === "overview" || note.kind === "degraded" || note.kind === "thinking" || note.kind === "empty"
+		? wrapDescriptionLines(theme, note.text, "dim", width)
+		: noteBulletLines(theme, note.text, width);
+}