@danypops/pi-jittor 0.2.1 → 0.3.0

package/extension/src/{context-breakdown.ts → observability/context-breakdown.ts}

@@ -4,6 +4,12 @@ import {
 	CONTEXT_TREE_MAX_NODES,
 	type ContextSegment,
 	type ContextSegmentItem,
+	countTextWithFallback,
+	type RequestTokenReconciliation,
+	reconcileRequestTokens,
+	StructuralTextTokenCounter,
+	type TextTokenCounter,
+	type TokenMeasurement,
 } from "@danypops/jittor";
 import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
 
@@ -32,29 +38,108 @@ export interface SessionTreeNodeLike {
 	children: SessionTreeNodeLike[];
 }
 
-function messageContentCharacters(message: unknown): number {
-	if (typeof message !== "object" || message === null) return 0;
+interface MessageContentAnalysis {
+	characters: number;
+	text: string;
+	items: ContextSegmentItem[];
+	imageCount: number;
+}
+
+export interface ContextTokenMeasurementOptions {
+	provider?: string;
+	model?: string;
+	counters?: readonly TextTokenCounter[];
+}
+
+const STRUCTURAL_TEXT_COUNTER = new StructuralTextTokenCounter();
+
+function measurementForText(text: string, options: ContextTokenMeasurementOptions = {}): TokenMeasurement {
+	return countTextWithFallback(
+		{
+			text,
+			scope: "context-item",
+			...(options.provider === undefined ? {} : { provider: options.provider }),
+			...(options.model === undefined ? {} : { model: options.model }),
+		},
+		options.counters ?? [],
+		STRUCTURAL_TEXT_COUNTER,
+	);
+}
+
+function measuredItem(label: string, textOrCharacters: string | number, options: ContextTokenMeasurementOptions = {}): ContextSegmentItem {
+	const characters = typeof textOrCharacters === "string" ? textOrCharacters.length : textOrCharacters;
+	const measurement =
+		typeof textOrCharacters === "string"
+			? measurementForText(textOrCharacters, options)
+			: {
+					tokens: toCeilTokens(characters),
+					scope: "context-item" as const,
+					provenance: "structural-estimate" as const,
+					method: `char/${CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN}`,
+				};
+	const suffix =
+		measurement.provenance === "structural-estimate"
+			? `${characters.toLocaleString()} chars (≈ char/4)`
+			: `${measurement.tokens.toLocaleString()} tok (${measurement.method}; exact text)`;
+	return { label: `${label} · ${suffix}`, estimatedTokens: measurement.tokens, measurement };
+}
+
+/** Breaks a message into Pi's public content fields and attaches explicit exact-text or structural provenance without retaining content. */
+function analyzeMessageContent(message: unknown, options: ContextTokenMeasurementOptions = {}): MessageContentAnalysis {
+	if (typeof message !== "object" || message === null) return { characters: 0, text: "", items: [], imageCount: 0 };
 	const record = message as Record<string, unknown>;
+	const effectiveOptions = options;
 	if (record.role === "bashExecution") {
 		// Pi's own context builder excludes "!!"-prefixed bash output from context; match that.
-		if (record.excludeFromContext === true) return 0;
-		return String(record.command ?? "").length + String(record.output ?? "").length;
+		if (record.excludeFromContext === true) return { characters: 0, text: "", items: [], imageCount: 0 };
+		const command = String(record.command ?? "");
+		const output = String(record.output ?? "");
+		return {
+			characters: command.length + output.length,
+			text: command + output,
+			items: [measuredItem("command", command, effectiveOptions), measuredItem("output", output, effectiveOptions)].filter(
+				(item) => item.estimatedTokens > 0,
+			),
+			imageCount: 0,
+		};
 	}
 	const content = record.content;
-	if (typeof content === "string") return content.length;
-	if (!Array.isArray(content)) return 0;
+	if (typeof content === "string")
+		return {
+			characters: content.length,
+			text: content,
+			items: [measuredItem("text", content, effectiveOptions)],
+			imageCount: 0,
+		};
+	if (!Array.isArray(content)) return { characters: 0, text: "", items: [], imageCount: 0 };
 	let characters = 0;
-	for (const block of content) {
+	let imageCount = 0;
+	let text = "";
+	const items: ContextSegmentItem[] = [];
+	for (let index = 0; index < content.length; index++) {
+		const block = content[index];
 		if (typeof block !== "object" || block === null) continue;
 		const b = block as Record<string, unknown>;
-		if (b.type === "text") characters += String(b.text ?? "").length;
-		else if (b.type === "thinking") characters += String(b.thinking ?? "").length;
-		else if (b.type === "toolCall") characters += JSON.stringify(b.arguments ?? {}).length;
-		// "image" blocks are deliberately not counted here -- image tokens follow a different,
-		// non-character-based cost model this char/4 estimate cannot represent; this is a real,
-		// documented undercount for image-heavy sessions, not a silent approximation.
+		let blockText = "";
+		let label = `block ${index + 1}`;
+		if (b.type === "text") {
+			blockText = String(b.text ?? "");
+			label = "text";
+		} else if (b.type === "thinking") {
+			blockText = String(b.thinking ?? "");
+			label = "thinking";
+		} else if (b.type === "toolCall") {
+			blockText = JSON.stringify(b.arguments ?? {});
+			label = `tool call ${String(b.name ?? "(unknown)")} arguments`;
+		} else if (b.type === "image") {
+			imageCount += 1;
+			continue; // image tokens are provider/model-specific and cannot be derived from base64 characters
+		} else continue;
+		characters += blockText.length;
+		text += blockText;
+		if (blockText.length > 0) items.push(measuredItem(label, blockText, effectiveOptions));
 	}
-	return characters;
+	return { characters, text, items, imageCount };
 }
 
 function messageSnippet(message: unknown, maxLength = 48): string {
@@ -78,13 +163,55 @@ function messageSnippet(message: unknown, maxLength = 48): string {
 	return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1)}…` : collapsed;
 }
 
-function entryLabel(entry: SessionEntryLike): string {
+interface ProviderPromptUsage {
+	label: string;
+	reconciliation: RequestTokenReconciliation;
+}
+
+function providerPromptUsage(message: unknown): ProviderPromptUsage | null {
+	if (typeof message !== "object" || message === null) return null;
+	const messageRecord = message as Record<string, unknown>;
+	const usage = messageRecord.usage;
+	if (typeof usage !== "object" || usage === null) return null;
+	const record = usage as Record<string, unknown>;
+	const amount = (value: unknown): number => (typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0);
+	const input = amount(record.input);
+	const cacheRead = amount(record.cacheRead);
+	const cacheWrite = amount(record.cacheWrite);
+	const promptTokens = input + cacheRead + cacheWrite;
+	if (!Number.isSafeInteger(promptTokens) || promptTokens <= 0) return null;
+	const identity =
+		typeof messageRecord.provider === "string" && typeof messageRecord.model === "string"
+			? { provider: messageRecord.provider, model: messageRecord.model }
+			: {};
+	const reconciliation = reconcileRequestTokens(
+		{
+			tokens: promptTokens,
+			scope: "request-context",
+			provenance: "provider-reported",
+			method: "pi-assistant-usage",
+			...identity,
+		},
+		[],
+	);
+	const cache =
+		cacheRead > 0 || cacheWrite > 0
+			? `; new ${input.toLocaleString()}, cache read ${cacheRead.toLocaleString()}, write ${cacheWrite.toLocaleString()}`
+			: "";
+	return {
+		label: ` · provider-reported request context ${promptTokens.toLocaleString()} tok${cache} · unattributed residual ${reconciliation.residual.tokens.toLocaleString()} tok`,
+		reconciliation,
+	};
+}
+
+function entryLabel(entry: SessionEntryLike, imageCount = 0, providerUsage = ""): string {
 	if (entry.type === "compaction") return "compaction summary";
 	if (entry.type === "branch_summary") return "branch summary";
 	const role = typeof entry.message === "object" && entry.message !== null ? (entry.message as Record<string, unknown>).role : undefined;
 	const prefix = typeof role === "string" ? role : entry.type;
 	const snippet = messageSnippet(entry.message);
-	return snippet ? `${prefix}: ${snippet}` : prefix;
+	const images = imageCount > 0 ? ` · ${imageCount} image${imageCount === 1 ? "" : "s"} (token cost unavailable)` : "";
+	return `${snippet ? `${prefix}: ${snippet}` : prefix}${providerUsage}${images}`;
 }
 
 export interface MessageHistoryTree {
@@ -130,6 +257,7 @@ export function buildMessageHistoryTree(
 	roots: ReadonlyArray<SessionTreeNodeLike>,
 	activeEntryIds: ReadonlySet<string>,
 	branchEntryIds?: ReadonlySet<string>,
+	measurementOptions: ContextTokenMeasurementOptions = {},
 ): MessageHistoryTree {
 	const visited = new Set<string>();
 	let truncated = false;
@@ -160,23 +288,35 @@ export function buildMessageHistoryTree(
 	for (let index = order.length - 1; index >= 0; index--) {
 		const frame = order[index]!;
 		const entry = frame.node.entry;
-		const characters =
+		const entryMeasurementOptions = measurementOptions;
+		const analysis =
+			entry.type === "message"
+				? analyzeMessageContent(entry.message, measurementOptions)
+				: { characters: 0, text: "", items: [], imageCount: 0 };
+		const text =
 			entry.type === "message"
-				? messageContentCharacters(entry.message)
+				? analysis.text
 				: entry.type === "compaction" || entry.type === "branch_summary"
-					? (entry.summary ?? "").length
-					: 0;
-		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+					? (entry.summary ?? "")
+					: "";
+		const measurement = measurementForText(text, entryMeasurementOptions);
+		const tokens = measurement.tokens;
 		const isActive = activeEntryIds.has(entry.id);
 		if (isActive) activeTokens += tokens;
 		const isOnBranch = branchEntryIds ? branchEntryIds.has(entry.id) : isActive; // no branch set given -- fall back to the old binary active/inactive-branch label
 
-		const children = childItemsByParent.get(index) ?? [];
-		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
+		const treeChildren = childItemsByParent.get(index) ?? [];
+		const contentChildren = analysis.items;
+		const children = [...contentChildren, ...treeChildren];
+		if (tokens === 0 && children.length === 0 && analysis.imageCount === 0) continue; // no content, no descendants, and no unknown-cost image -- nothing to show
 
+		const promptUsage = providerPromptUsage(entry.message);
+		const label = entryLabel(entry, analysis.imageCount, promptUsage?.label);
 		const item: ContextSegmentItem = {
-			label: isActive ? entryLabel(entry) : isOnBranch ? `${entryLabel(entry)} (compacted)` : `${entryLabel(entry)} (inactive branch)`,
+			label: isActive ? label : isOnBranch ? `${label} (compacted)` : `${label} (inactive branch)`,
 			estimatedTokens: tokens,
+			measurement,
+			...(promptUsage ? { requestTokenReconciliation: promptUsage.reconciliation } : {}),
 			...(children.length > 0 ? { children } : {}),
 		};
 		itemByIndex.set(index, item);
@@ -228,9 +368,14 @@ export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCha
 	const toolSnippetEntries = Object.entries(options.toolSnippets ?? {});
 	// Mirrors buildSystemPrompt()'s own "- name: snippet\n" line shape closely enough to be a
 	// fair estimate without importing Pi-internal formatting code.
+	const toolSnippetDetails = toolSnippetEntries.map(([name, snippet]) => measuredItem(name, name.length + snippet.length + 4));
 	const toolSnippetsCharacters = toolSnippetEntries.reduce((sum, [name, snippet]) => sum + name.length + snippet.length + 4, 0);
 	if (toolSnippetsCharacters > 0) {
-		items.push({ label: `Tool snippets (${toolSnippetEntries.length} tools)`, estimatedTokens: toCeilTokens(toolSnippetsCharacters) });
+		items.push({
+			label: `Tool snippets (${toolSnippetEntries.length} tools)`,
+			estimatedTokens: toCeilTokens(toolSnippetsCharacters),
+			children: toolSnippetDetails,
+		});
 	}
 
 	const visibleSkills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
@@ -239,7 +384,13 @@ export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCha
 		0,
 	);
 	if (skillsCharacters > 0) {
-		items.push({ label: `Skills catalog (${visibleSkills.length} skills)`, estimatedTokens: toCeilTokens(skillsCharacters) });
+		items.push({
+			label: `Skills catalog (${visibleSkills.length} skills)`,
+			estimatedTokens: toCeilTokens(skillsCharacters),
+			children: visibleSkills.map((skill) =>
+				measuredItem(skill.name, skill.name.length + skill.description.length + skill.filePath.length + 20),
+			),
+		});
 	}
 
 	const contextFiles = options.contextFiles ?? [];
@@ -248,10 +399,32 @@ export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCha
 		items.push({
 			label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`,
 			estimatedTokens: toCeilTokens(contextFilesCharacters),
+			children: contextFiles.map((file) => measuredItem(file.path, file.path.length + file.content.length + 40)),
 		});
 	}
 
-	const knownCharacters = toolSnippetsCharacters + skillsCharacters + contextFilesCharacters;
+	const promptGuidelines = options.promptGuidelines ?? [];
+	const promptGuidelinesCharacters = promptGuidelines.reduce((sum, guideline) => sum + guideline.length + 2, 0);
+	if (promptGuidelinesCharacters > 0) {
+		items.push({
+			label: `Tool guidelines (${promptGuidelines.length})`,
+			estimatedTokens: toCeilTokens(promptGuidelinesCharacters),
+			children: promptGuidelines.map((guideline, index) => measuredItem(`guideline ${index + 1}`, guideline.length + 2)),
+		});
+	}
+
+	const customPromptCharacters = options.customPrompt?.length ?? 0;
+	if (customPromptCharacters > 0) items.push(measuredItem("Custom system prompt", customPromptCharacters));
+	const appendedPromptCharacters = options.appendSystemPrompt?.length ?? 0;
+	if (appendedPromptCharacters > 0) items.push(measuredItem("Appended system prompt", appendedPromptCharacters));
+
+	const knownCharacters =
+		toolSnippetsCharacters +
+		skillsCharacters +
+		contextFilesCharacters +
+		promptGuidelinesCharacters +
+		customPromptCharacters +
+		appendedPromptCharacters;
 	const remainderCharacters = Math.max(0, totalCharacters - knownCharacters);
 	if (remainderCharacters > 0 || items.length === 0) {
 		items.push({ label: "Base template, guidelines, and formatting", estimatedTokens: toCeilTokens(remainderCharacters) });

package/extension/src/observability/context-growth.ts

@@ -0,0 +1,26 @@
+export interface ContextGrowthPoint {
+	turn: number;
+	tokens: number;
+}
+
+/**
+ * Owns the current post-compaction context-growth observation window. Trend fitting and a
+ * trailing-size cap deliberately remain outside this task; reset() is the critical invariant
+ * that prevents one regression window from spanning a real compaction discontinuity.
+ */
+export class ContextGrowthCapability {
+	private points: ContextGrowthPoint[] = [];
+
+	observe(turn: number, tokens: number): void {
+		if (!Number.isInteger(turn) || turn < 0 || !Number.isFinite(tokens) || tokens < 0) return;
+		this.points.push({ turn, tokens });
+	}
+
+	observations(): readonly ContextGrowthPoint[] {
+		return this.points.map((point) => ({ ...point }));
+	}
+
+	reset(): void {
+		this.points = [];
+	}
+}

package/extension/src/{context-report.ts → observability/context-report.ts}

@@ -1,9 +1,10 @@
 import type { ContextSegment } from "@danypops/jittor";
-import { buildContextRows, type ContextSegment as MalevichContextSegment } from "malevich-tui-components";
+import type { ContextRow, ContextSegment as MalevichContextSegment } from "malevich-tui-components";
 import type { ContextBreakdown } from "./context-breakdown.ts";
 
 /** Bounds how many items render per segment in the plain-text fallback -- a notify-mode report is a scan-at-a-glance summary, not a full dump (the interactive TUI view has no such cap, since it scrolls). */
 const MAX_ITEMS_PER_SEGMENT_LINE = 5;
+const MAX_REPORT_ROWS = 200;
 
 function formatTokens(tokens: number): string {
 	return tokens >= 1_000 ? `${(tokens / 1_000).toFixed(1)}k` : String(tokens);
@@ -13,6 +14,34 @@ function percentOf(part: number, whole: number): string {
 	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
 }
 
+/** Malevich-compatible row projection with an explicit stack, safe for long linear session trees. */
+export function buildContextRowsIterative(segments: readonly MalevichContextSegment[], totalTokens?: number | null): ContextRow[] {
+	const rows: ContextRow[] = [];
+	const denominator = totalTokens ?? segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	for (const segment of segments) {
+		const items = [...(segment.items ?? [])]
+			.filter((item) => item.estimatedTokens > 0)
+			.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+		if (segment.estimatedTokens <= 0 && items.length === 0 && !segment.unknown) continue;
+		rows.push({
+			key: segment.key,
+			isHeader: true,
+			depth: 0,
+			text: `${segment.label} — ${segment.estimatedTokens} tok (${percentOf(segment.estimatedTokens, denominator)})`,
+		});
+		const stack = items.reverse().map((item) => ({ item, depth: 1 }));
+		while (stack.length > 0) {
+			const { item, depth } = stack.pop()!;
+			rows.push({ key: segment.key, isHeader: false, depth, text: `${item.estimatedTokens.toString().padStart(6)} tok  ${item.label}` });
+			const children = [...(item.children ?? [])]
+				.filter((child) => child.estimatedTokens > 0)
+				.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+			for (let index = children.length - 1; index >= 0; index--) stack.push({ item: children[index]!, depth: depth + 1 });
+		}
+	}
+	return rows;
+}
+
 /** Malevich's row builder is confidence-unaware (it's a generic segment/item shape); folding the tier into the label is how it survives into the rendered row text, e.g. "Active Rules [exact-cooperative]". */
 function withConfidenceLabel(segment: ContextSegment): MalevichContextSegment {
 	const items = [...(segment.items ?? [])]
@@ -49,12 +78,15 @@ export function buildContextReport(breakdown: ContextBreakdown): string {
 		lines.push(`Estimates exceed real total by ~${breakdown.overshootTokens} tok -- sizes below are approximate, not exact`);
 
 	const sorted = [...breakdown.segments].sort((left, right) => right.estimatedTokens - left.estimatedTokens).map(withConfidenceLabel);
-	const rows = buildContextRows(sorted, breakdown.totalTokens ?? undefined);
+	const rows = buildContextRowsIterative(sorted, breakdown.totalTokens ?? undefined);
 	if (rows.length === 0) {
 		lines.push("", "(no segments observed yet)");
 		return lines.join("\n");
 	}
 	lines.push("");
-	for (const row of rows) lines.push(row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`);
+	const visibleRows = rows.slice(0, MAX_REPORT_ROWS);
+	for (const row of visibleRows) lines.push(row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`);
+	if (rows.length > visibleRows.length)
+		lines.push(`… ${rows.length - visibleRows.length} more context rows (open /context in TUI mode to search and filter)`);
 	return lines.join("\n");
 }

package/extension/src/observability/context-view.ts

@@ -0,0 +1,264 @@
+import type { ContextDelta, ContextSegment } from "@danypops/jittor";
+import type { ExtensionCommandContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { matchesKey, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	type ContextBarTheme,
+	type ContextRow,
+	type ContextRowsTheme,
+	type ContextSegment as MalevichContextSegment,
+	renderContextRowLines,
+	renderContextUsageBar,
+} from "malevich-tui-components";
+import type { ContextBreakdown } from "./context-breakdown.ts";
+import { buildContextReport, buildContextRowsIterative } from "./context-report.ts";
+
+const VISIBLE_ROWS = 22;
+const MIN_TOKEN_FILTERS = [0, 100, 1_000, 10_000] as const;
+
+export type ContextRowScope = "all" | "active" | "historical";
+
+function rowTokens(row: ContextRow): number {
+	const match = row.isHeader ? row.text.match(/—\s+([\d,]+)\s+tok/) : row.text.match(/^\s*([\d,]+)\s+tok/);
+	return match ? Number(match[1]!.replaceAll(",", "")) : 0;
+}
+
+/** Filters the flattened pre-order tree while retaining every ancestor needed to understand a match. */
+export function filterContextRows(rows: readonly ContextRow[], query: string, scope: ContextRowScope, minimumTokens: number): ContextRow[] {
+	const terms = query.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+	const included = rows.map(() => false);
+	const parentByIndex: Array<number | null> = [];
+	const ancestors: number[] = [];
+	const historicalByDepth: boolean[] = [];
+	for (let index = 0; index < rows.length; index++) {
+		const row = rows[index]!;
+		while (ancestors.length > row.depth) ancestors.pop();
+		parentByIndex[index] = row.depth > 0 ? (ancestors[row.depth - 1] ?? null) : null;
+		const lower = row.text.toLocaleLowerCase();
+		const inheritedHistorical = row.depth > 0 ? (historicalByDepth[row.depth - 1] ?? false) : false;
+		const historical = inheritedHistorical || lower.includes("(inactive branch)") || lower.includes("(compacted)");
+		const scopeMatches = scope === "all" || (scope === "historical" ? historical : !historical);
+		const queryMatches = terms.every((term) => lower.includes(term));
+		included[index] = scopeMatches && queryMatches && rowTokens(row) >= minimumTokens;
+		ancestors[row.depth] = index;
+		ancestors.length = row.depth + 1;
+		historicalByDepth[row.depth] = historical;
+		historicalByDepth.length = row.depth + 1;
+	}
+	// Children follow parents in this pre-order list, so one reverse pass propagates every
+	// match to its ancestors in O(rows), even for a 50k-entry linear session tree.
+	for (let index = rows.length - 1; index >= 0; index--) {
+		if (!included[index]) continue;
+		const parent = parentByIndex[index];
+		if (parent !== null && parent !== undefined) included[parent] = true;
+	}
+	return rows.filter((_row, index) => included[index]);
+}
+
+/**
+ * A dynamically-contributed segment set (any string key from any extension, not a fixed enum)
+ * can't use a hardcoded per-key color map the way Papyrus's own ContextViewport did for its
+ * fixed seven segments -- this cycles a small categorical palette keyed by a stable hash of the
+ * segment key, so the same key always renders the same color within one process without needing
+ * every possible contributor's key to be known in advance.
+ */
+const PALETTE: ThemeColor[] = ["accent", "success", "syntaxFunction", "warning", "syntaxKeyword", "syntaxType", "muted"];
+
+function paletteColor(key: string): ThemeColor {
+	let hash = 0;
+	for (let index = 0; index < key.length; index += 1) hash = (hash * 31 + key.charCodeAt(index)) >>> 0;
+	return PALETTE[hash % PALETTE.length]!;
+}
+
+function formatTokenCount(tokens: number): string {
+	return tokens >= 1_000 ? `${(tokens / 1_000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+function contextDeltaLines(delta: ContextDelta): string[] {
+	const lifecycle = new Map<string, number>();
+	for (const change of delta.changes) lifecycle.set(change.lifecycle, (lifecycle.get(change.lifecycle) ?? 0) + 1);
+	const lifecycleText = [...lifecycle.entries()].map(([name, count]) => `${name} ${count}`).join(" · ") || "none";
+	const growthText = delta.growthBySource
+		.filter((growth) => growth.deltaTokens !== 0)
+		.map((growth) => `${growth.source} ${growth.deltaTokens > 0 ? "+" : ""}${growth.deltaTokens.toLocaleString()} tok`)
+		.join(" · ");
+	const changed = delta.firstChangedSegment
+		? `first change: ${delta.firstChangedSegment.source} @ request ${delta.firstChangedSegment.requestPosition ?? "historical"}`
+		: delta.resetReason
+			? `comparison reset: ${delta.resetReason}`
+			: "request structure unchanged";
+	return [
+		`Stable prefix ${delta.stablePrefixTokens.toLocaleString()} tok · ${changed}`,
+		`Lifecycle ${lifecycleText} · growth ${growthText || "none"}${delta.truncated ? " · bounded snapshot (truncated)" : ""}`,
+		"Stable-prefix correlation is structural evidence, not provider cache proof.",
+	];
+}
+
+/** Folds each segment's confidence tier into its label so it survives Malevich's confidence-unaware row builder. */
+function withConfidenceLabel(segment: ContextSegment): MalevichContextSegment {
+	return {
+		key: segment.key,
+		label: `${segment.label} [${segment.confidence}]`,
+		estimatedTokens: segment.estimatedTokens,
+		items: segment.items,
+		unknown: segment.unknown,
+	};
+}
+
+class ContextViewport {
+	private offsetY = 0;
+	private readonly rows: ContextRow[];
+	private readonly segments: readonly MalevichContextSegment[];
+	private searchMode = false;
+	private query = "";
+	private scope: ContextRowScope = "all";
+	private minimumFilterIndex = 0;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly breakdown: ContextBreakdown,
+		private readonly delta: ContextDelta | null,
+		private readonly close: () => void,
+	) {
+		// Heaviest-first: Malevich renders segments in the order given, so sorting by weight for a
+		// merged multi-producer view is this viewport's own policy, matching context-report.ts.
+		this.segments = [...breakdown.segments].sort((left, right) => right.estimatedTokens - left.estimatedTokens).map(withConfidenceLabel);
+		this.rows = buildContextRowsIterative(this.segments, breakdown.totalTokens ?? undefined);
+	}
+
+	invalidate(): void {}
+
+	private visibleRows(): ContextRow[] {
+		return filterContextRows(this.rows, this.query, this.scope, MIN_TOKEN_FILTERS[this.minimumFilterIndex]!);
+	}
+
+	private clampOffset(rows: readonly ContextRow[]): void {
+		this.offsetY = Math.min(this.offsetY, Math.max(0, rows.length - VISIBLE_ROWS));
+	}
+
+	render(width: number): string[] {
+		const theme = this.theme;
+		const contentWidth = Math.max(1, width);
+		const border = theme.fg("borderMuted", "─".repeat(contentWidth));
+		const lines: string[] = [border, truncateToWidth(theme.fg("accent", theme.bold("Context")), contentWidth, "")];
+
+		const { totalTokens, effectiveBudget } = this.breakdown;
+		if (totalTokens !== null && effectiveBudget !== null) {
+			lines.push(
+				truncateToWidth(
+					`${formatTokenCount(totalTokens)} / ${formatTokenCount(effectiveBudget)} tokens (${percentOf(totalTokens, effectiveBudget)} of usable budget)`,
+					contentWidth,
+					"",
+				),
+			);
+		} else if (totalTokens !== null) {
+			lines.push(truncateToWidth(`${formatTokenCount(totalTokens)} tokens (model context window unknown)`, contentWidth, ""));
+		} else {
+			lines.push(theme.fg("dim", "No real usage reported yet — sizes below are estimates only"));
+		}
+
+		const colorFor = (key: string) => (s: string) => theme.fg(paletteColor(key), s);
+		const barTheme: ContextBarTheme = { colorFor, empty: (s) => theme.fg("dim", s) };
+		lines.push(renderContextUsageBar(barTheme, this.segments, contentWidth, effectiveBudget ?? undefined, totalTokens ?? undefined));
+		if (this.breakdown.overshootTokens > 0) {
+			lines.push(
+				truncateToWidth(
+					theme.fg(
+						"warning",
+						`Estimates exceed real total by ~${this.breakdown.overshootTokens} tok — sizes below are approximate, not exact`,
+					),
+					contentWidth,
+					"",
+				),
+			);
+		}
+		lines.push(theme.fg("dim", "Exact-text items name the model tokenizer; ≈ uses char/4; provider request totals remain aggregate."));
+		if (this.delta) {
+			for (const line of contextDeltaLines(this.delta)) lines.push(truncateToWidth(theme.fg("muted", line), contentWidth, ""));
+		}
+		lines.push("");
+
+		const rowsTheme: ContextRowsTheme = { colorFor, header: (s) => theme.bold(s) };
+		const filteredRows = this.visibleRows();
+		this.clampOffset(filteredRows);
+		const visible = filteredRows.slice(this.offsetY, this.offsetY + VISIBLE_ROWS);
+		lines.push(...renderContextRowLines(visible, contentWidth, rowsTheme));
+		if (filteredRows.length === 0) lines.push(theme.fg("dim", "  (no matching context items)"));
+		else lines.push(theme.fg("muted", `  ${Math.min(this.offsetY + VISIBLE_ROWS, filteredRows.length)}/${filteredRows.length}`));
+
+		lines.push("");
+		const minimum = MIN_TOKEN_FILTERS[this.minimumFilterIndex]!;
+		const filterState = `scope: ${this.scope} · min: ${minimum === 0 ? "any" : `${formatTokenCount(minimum)} tok`}`;
+		lines.push(
+			truncateToWidth(
+				this.searchMode
+					? theme.fg("accent", `Search: ${this.query}▌ · ${filterState}`)
+					: theme.fg("muted", `${this.query ? `search: ${this.query} · ` : ""}${filterState}`),
+				contentWidth,
+				"",
+			),
+		);
+		lines.push(
+			theme.fg(
+				"dim",
+				this.searchMode
+					? "type to search · backspace edit · enter apply · esc clear"
+					: "/ search · f scope · m min tokens · g/G top/bottom · ↑↓ scroll · esc close",
+			),
+		);
+		lines.push(border);
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (this.searchMode) {
+			if (matchesKey(data, "escape")) {
+				if (this.query.length > 0) this.query = "";
+				else this.searchMode = false;
+			} else if (matchesKey(data, "enter")) this.searchMode = false;
+			else if (matchesKey(data, "backspace")) this.query = this.query.slice(0, -1);
+			else if (/^[\x20-\x7e]+$/.test(data)) this.query += data;
+			else return;
+			this.offsetY = 0;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.close();
+			return;
+		}
+		const rows = this.visibleRows();
+		if (data === "/") {
+			this.searchMode = true;
+			this.offsetY = 0;
+		} else if (data === "f") {
+			this.scope = this.scope === "all" ? "active" : this.scope === "active" ? "historical" : "all";
+			this.offsetY = 0;
+		} else if (data === "m") {
+			this.minimumFilterIndex = (this.minimumFilterIndex + 1) % MIN_TOKEN_FILTERS.length;
+			this.offsetY = 0;
+		} else if (data === "g") this.offsetY = 0;
+		else if (data === "G") this.offsetY = Math.max(0, rows.length - VISIBLE_ROWS);
+		else if (matchesKey(data, "up")) this.offsetY = Math.max(0, this.offsetY - 1);
+		else if (matchesKey(data, "down")) this.offsetY = Math.min(Math.max(0, rows.length - VISIBLE_ROWS), this.offsetY + 1);
+		else return;
+		this.tui.requestRender();
+	}
+}
+
+/** Interactive scrollable Context Hub view in TUI mode; the same plain-text report as /context's non-interactive path otherwise. */
+export async function showContextView(
+	ctx: ExtensionCommandContext,
+	breakdown: ContextBreakdown,
+	delta: ContextDelta | null = null,
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify([buildContextReport(breakdown), ...(delta ? ["", ...contextDeltaLines(delta)] : [])].join("\n"), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new ContextViewport(tui, theme, breakdown, delta, done));
+}