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

package/src/ui/section-preview.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared preview body rendering for content that carries labeled parts, e.g. a
+ * tool's dropped prompt lines and definition. Both the Injections item preview
+ * and the Usage block stream present those parts the same way: a bold
+ * subheader with its token share above each part. Pure string logic.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+import type {
+	ForcedEdit, InjectedReference, InjectionSection, JsonSpan, RequestChange, TextDiff, TokenDiff,
+} from "../model.ts";
+import { normalizeInlineText, normalizePreviewText } from "../text.ts";
+import { forcedEditDiffLines, messageDiffLines, payloadDiffLines, textDiffLines } from "./diff-preview.ts";
+import { shiftJsonSpan } from "./json-preview.ts";
+import { BODY_INDENT, calculateViewport, descriptionBlockRows } from "./layout.ts";
+import {
+	type ContextMarker,
+	type DiffBase,
+	diffMarker,
+	guessMarker,
+	markerLegendLines,
+	noteBulletLines,
+	partMarkers,
+	stateMarkers,
+} from "./markers.ts";
+
+/**
+ * Arrow introducing an extension line's source label. Non-breaking spaces bind
+ * the preceding word, arrow, and label into one wrapping unit. Units wider
+ * than the content width still hard-wrap, possibly just after the arrow.
+ */
+const SOURCE_ARROW = "\u00A0<-\u00A0";
+/** Keep a normal block's worth of content visible before making room for its explanation. */
+const DESCRIPTION_MIN_CONTENT_ROWS = 22;
+/** Dim prefix of a tool declaration part, so it reads apart from a `tool call` part. */
+const TOOL_LABEL_PREFIX = "tool:";
+
+/** Raw preview content plus the labeled parts it decomposes into, when known. */
+export interface SectionedContent {
+	readonly text: string;
+	readonly jsonSpan?: JsonSpan;
+	readonly sections?: readonly InjectionSection[];
+	readonly injectedReferences?: readonly InjectedReference[];
+	/** True when a `--system-prompt` replacement dropped this content; it reads 0 tokens. */
+	readonly dropped?: boolean;
+	/** True when an extension moved this content out of the region pi renders it into. */
+	readonly moved?: boolean;
+	/** Request-only change of this content; only `forced` has a marker. */
+	readonly change?: RequestChange;
+	/** Request edit a forced prompt replaced; the body shows it as a diff from the sent text. */
+	readonly forcedEdit?: ForcedEdit;
+	/** Texts behind a System Prompt part's diff; the body shows them as a diff. */
+	readonly textDiff?: TextDiff;
+	/** Tokens this content gained and lost against its base; only Injections measures them. */
+	readonly diff?: TokenDiff;
+	/** True when the request sent other content than the session keeps; only Injections measures it. */
+	readonly requestOnly?: boolean;
+}
+
+/** Space shared by uncapped preview content, its counter, and the marker legend. */
+export interface PreviewDescriptionLayout {
+	readonly width: number;
+	/** Rows left after the view's fixed frame, before the description and counter. */
+	readonly availableRows: number;
+	/** Wrapped content rows, including entry headers/separators but never the footer. */
+	readonly contentLineCount: number;
+}
+
+/**
+ * One fixed legend for the markers a preview shows, never part of its raw
+ * content, followed by `notes` that explain the shown item further. `diffBase`
+ * names what the shown token diffs compare with. Collapse it whole when fewer
+ * than `DESCRIPTION_MIN_CONTENT_ROWS` content rows would remain, or when a
+ * shorter preview would no longer fit in full. Uncapped line counts keep the
+ * collapse decision independent of the Usage cap it helps determine.
+ */
+export function previewLegendLines(
+	theme: Theme,
+	contents: readonly SectionedContent[],
+	layout: PreviewDescriptionLayout,
+	notes: readonly string[] = [],
+	diffBase?: DiffBase,
+): string[] {
+	const markers = previewMarkers(contents);
+	if (markers.length === 0 && notes.length === 0) return [];
+	const lines = [
+		...markerLegendLines(theme, markers, layout.width, diffBase),
+		...notes.flatMap((note) => noteBulletLines(theme, note, layout.width)),
+	];
+	const availableRows = layout.availableRows - descriptionBlockRows(lines);
+	const viewport = calculateViewport(layout.contentLineCount, availableRows, 0);
+	const floor = Math.min(DESCRIPTION_MIN_CONTENT_ROWS, layout.contentLineCount);
+	return availableRows >= floor && viewport.visibleCount >= floor ? lines : [];
+}
+
+/**
+ * Preview body lines for one item or entry: labeled parts under their
+ * subheaders, or the raw text when no breakdown exists. A payload change's
+ * part renders its changed lines instead of its text, a part with a replaced
+ * edit renders that edit as a diff, and a changed System Prompt part with a
+ * base renders its diff from that base. The caller supplies
+ * `wrapText` so each view keeps its own sanitizing, wrapping, indentation, and
+ * choice of whether the marked JSON run is expanded at this level, and
+ * `heading` so an undivided body can drop a line the heading already shows.
+ */
+export function previewBodyLines(
+	theme: Theme,
+	content: SectionedContent,
+	wrapWidth: number,
+	wrapText: (text: string, jsonSpan: JsonSpan | undefined) => string[],
+	heading?: string,
+): string[] {
+	const sections = content.sections ?? [];
+	if (sections.length === 0) {
+		if (content.forcedEdit !== undefined) return forcedEditDiffLines(theme, content.text, content.forcedEdit, wrapWidth);
+		if (hasDiffBase(content.textDiff)) return textDiffLines(theme, content.textDiff, wrapWidth);
+		return contentBodyLines(theme, content, wrapWidth, wrapText, heading);
+	}
+	const lines: string[] = [];
+	for (const section of sections) {
+		if (lines.length > 0) {
+			// Captured trailing whitespace must not add to the subsection separator
+			while (lines.length > 0 && normalizeInlineText(lines[lines.length - 1] ?? "") === "") lines.pop();
+			lines.push("", "");
+		}
+		lines.push(...sectionHeaderLines(theme, section, wrapWidth));
+		if (section.message !== undefined) lines.push(...messageDiffLines(theme, section, wrapWidth));
+		else if (section.changedLines !== undefined) lines.push(...payloadDiffLines(theme, section.changedLines, wrapWidth));
+		else if (section.forcedEdit !== undefined) {
+			lines.push(...forcedEditDiffLines(theme, section.text, section.forcedEdit, wrapWidth));
+		} else if (hasDiffBase(section.textDiff)) lines.push(...textDiffLines(theme, section.textDiff, wrapWidth));
+		else lines.push(...contentBodyLines(theme, section, wrapWidth, wrapText, section.label));
+	}
+	return lines;
+}
+
+/**
+ * Whether a part's text diff has a base to compare with. Without one, the
+ * whole part is added: its `+N` already says so, and plain text reads better.
+ */
+function hasDiffBase(diff: TextDiff | undefined): diff is TextDiff {
+	return diff !== undefined && diff.base.length > 0;
+}
+
+/**
+ * Markers one preview renders: extension lines and their inferred owners come
+ * from reference metadata, while state markers follow the subheaders and
+ * metadata rows that show them, whether or not that part carries references.
+ */
+function previewMarkers(contents: readonly SectionedContent[]): ContextMarker[] {
+	const referenced = contents.flatMap((content) => referenceParts(content)).filter(hasInjectedReferences);
+	const marked = contents.flatMap((content) => [content, ...(content.sections ?? [])]);
+	const markers: ContextMarker[] = [];
+	if (referenced.length > 0) markers.push("highlighted");
+	if (referenced.some(hasGuessedReferences) || marked.some(isGuessedPart)) markers.push("guess");
+	// The legend orders and deduplicates markers itself
+	markers.push(...marked.flatMap(partMarkers));
+	return markers;
+}
+
+/** Only metadata on rendered body parts triggers the footer, never a text or label match. */
+function hasInjectedReferences(part: SectionedContent): boolean {
+	return (part.injectedReferences?.length ?? 0) > 0;
+}
+
+/** Whether a rendered reference names an inferred owner needing the extra caveat. */
+function hasGuessedReferences(part: SectionedContent): boolean {
+	return part.injectedReferences?.some((reference) => reference.attribution === "guess") === true;
+}
+
+/** Whether a part's diff belongs to an owner inferred from the text itself, marked on its subheader. */
+function isGuessedPart(part: SectionedContent | InjectionSection): boolean {
+	return "attribution" in part && part.attribution === "guess";
+}
+
+/** Body parts carrying reference metadata: the item's sections, or the item itself. */
+function referenceParts(content: SectionedContent): readonly SectionedContent[] {
+	return content.sections?.length ? content.sections : [content];
+}
+
+/** Render annotated extension lines locally; other content keeps the caller's JSON/skill transformations. */
+function contentBodyLines(
+	theme: Theme,
+	content: SectionedContent,
+	wrapWidth: number,
+	wrapText: (text: string, jsonSpan: JsonSpan | undefined) => string[],
+	heading: string | undefined,
+): string[] {
+	const references = content.injectedReferences ?? [];
+	if (references.length === 0) return bodyLines(content.text, content.jsonSpan, heading, wrapText);
+	let text = "";
+	let offset = 0;
+	for (const reference of references) {
+		text += normalizePreviewText(content.text.slice(offset, reference.start));
+		const captured = content.text.slice(reference.start, reference.end);
+		// A part that opens with an extension line drops its captured lead, as plain text does.
+		const line = text.trim().length === 0 ? captured.replace(/^\n+/, "") : captured;
+		text += theme.fg("syntaxNumber", normalizePreviewText(line));
+		text += theme.fg("borderMuted", SOURCE_ARROW);
+		text += theme.fg("mdLink", normalizeInlineText(reference.source.label));
+		if (reference.tool !== undefined) {
+			text += theme.fg("mdLinkUrl", `:${normalizeInlineText(reference.tool)}`);
+		}
+		if (reference.attribution === "guess") text += guessMarker(theme);
+		offset = reference.end;
+	}
+	text += normalizePreviewText(content.text.slice(offset));
+	const body = withoutRepeatedHeading(text.replace(/^\n+/, ""), heading);
+	return wrapTextWithAnsi(body, wrapWidth)
+		.map((line) => line === "" ? "" : `${BODY_INDENT}${line}`);
+}
+
+/**
+ * One body part, wrapped after dropping the lead its heading already carries:
+ * the newline that separated a prompt line, and a first line repeating
+ * the heading itself, as a skill block opens with its own name.
+ */
+function bodyLines(
+	text: string,
+	jsonSpan: JsonSpan | undefined,
+	heading: string | undefined,
+	wrapText: (text: string, jsonSpan: JsonSpan | undefined) => string[],
+): string[] {
+	const body = withoutRepeatedHeading(text.replace(/^\n+/, ""), heading);
+	return wrapText(body, shiftJsonSpan(jsonSpan, text.length - body.length));
+}
+
+/**
+ * Text without a first line that only repeats the heading rendered above it.
+ * The dropped line stays part of the estimate; it is redundant on screen only.
+ */
+function withoutRepeatedHeading(text: string, heading: string | undefined): string {
+	if (heading === undefined) return text;
+	const lineEnd = text.indexOf("\n");
+	if (lineEnd === -1 || headingKey(text.slice(0, lineEnd)) !== headingKey(heading)) return text;
+	return text.slice(lineEnd + 1);
+}
+
+/**
+ * Comparable form of a heading or a first content line: case and a trailing
+ * colon carry no information here, so pi's own block headers ("Available
+ * tools:", "Guidelines:") read as repeats of the part labels above them.
+ */
+function headingKey(text: string): string {
+	return text.trim().replace(/:$/, "").toLowerCase();
+}
+
+/**
+ * Bold subheader naming one part, its share of the parent estimate, its token
+ * diff, a guessed owner, and its markers. A diff-only part has no share, and a
+ * tool declaration's name follows a dim `tool:` prefix.
+ * Parts use `syntaxKeyword` rather than the usual `mdHeading` subheader color,
+ * because they nest under item and entry headings that already carry `mdHeading`.
+ */
+function sectionHeaderLines(theme: Theme, section: InjectionSection, wrapWidth: number): string[] {
+	const prefix = section.toolDeclaration === true ? theme.fg("dim", TOOL_LABEL_PREFIX) : "";
+	const label = prefix + theme.fg("syntaxKeyword", theme.bold(normalizeInlineText(section.label)));
+	const prompt = section.message?.userPrompt;
+	const number = prompt === undefined ? "" : theme.fg("muted", ` · user prompt #${prompt}`);
+	const tokens = section.diffOnly === true
+		? ""
+		: theme.fg("muted", ` · ${section.tokens.toLocaleString("en-US")} tokens`);
+	const guess = section.attribution === "guess" ? guessMarker(theme) : "";
+	const header = `${label}${number}${tokens}${diffMarker(theme, section.diff)}${guess}${stateMarkers(theme, section)}`;
+	return wrapTextWithAnsi(header, wrapWidth).map((line) => `${BODY_INDENT}${line}`);
+}

package/src/ui/skill-preview.ts

@@ -0,0 +1,83 @@
+/**
+ * Preview-only recognition of complete pi skill-expansion wrappers. The
+ * returned segments retain ordinary and malformed text verbatim; callers are
+ * responsible for terminal sanitization before parsing or rendering.
+ */
+
+const SKILL_OPEN_TAG = /^<skill name="([^"\r\n]+)"(?: location="[^"\r\n]*")?>\r?$/gm;
+const ANY_SKILL_OPEN_TAG = /^<skill(?:\s|>)[^\r\n]*\r?$/gm;
+const SKILL_CLOSE_TAG = /^<\/skill>\r?$/gm;
+
+/** One display segment from a user message containing attached skills. */
+export type SkillPreviewSegment =
+	| { readonly type: "text"; readonly text: string }
+	| { readonly type: "skill"; readonly name: string };
+
+interface TagSpan {
+	readonly start: number;
+	readonly end: number;
+}
+
+interface SkillOpenTag extends TagSpan {
+	readonly name: string;
+}
+
+/**
+ * Replace no content directly: split complete skill wrappers into named
+ * segments so the UI can render compact badges while retaining unmatched
+ * wrappers as text. A later complete wrapper is still recognized when an
+ * earlier opening tag is malformed or unclosed.
+ */
+export function splitSkillPreview(text: string): SkillPreviewSegment[] {
+	const openings = collectOpenTags(text);
+	const openingBoundaries = collectTagSpans(text, ANY_SKILL_OPEN_TAG);
+	const closings = collectTagSpans(text, SKILL_CLOSE_TAG);
+	const segments: SkillPreviewSegment[] = [];
+	let textStart = 0;
+	let openingBoundaryIndex = 0;
+	let closingIndex = 0;
+
+	for (let openingIndex = 0; openingIndex < openings.length; openingIndex++) {
+		const opening = openings[openingIndex];
+		if (opening === undefined || opening.start < textStart) continue;
+		while ((closings[closingIndex]?.start ?? text.length) < opening.end) closingIndex++;
+		const closing = closings[closingIndex];
+		if (closing === undefined) continue;
+
+		while ((openingBoundaries[openingBoundaryIndex]?.start ?? text.length) <= opening.start) {
+			openingBoundaryIndex++;
+		}
+		const nextOpening = openingBoundaries[openingBoundaryIndex];
+		if (nextOpening !== undefined && nextOpening.start < closing.start) continue;
+
+		pushTextSegment(segments, text.slice(textStart, opening.start));
+		segments.push({ type: "skill", name: opening.name });
+		textStart = closing.end;
+		closingIndex++;
+	}
+
+	pushTextSegment(segments, text.slice(textStart));
+	return segments;
+}
+
+/** Collect structurally valid opening tags and their skill names. */
+function collectOpenTags(text: string): SkillOpenTag[] {
+	return [...text.matchAll(SKILL_OPEN_TAG)].map((match) => ({
+		start: match.index,
+		end: match.index + match[0].length,
+		name: match[1] ?? "",
+	}));
+}
+
+/** Collect complete line-delimited tag spans for one global expression. */
+function collectTagSpans(text: string, expression: RegExp): TagSpan[] {
+	return [...text.matchAll(expression)].map((match) => ({
+		start: match.index,
+		end: match.index + match[0].length,
+	}));
+}
+
+/** Append non-empty ordinary text without merging it into skill segments. */
+function pushTextSegment(segments: SkillPreviewSegment[], text: string): void {
+	if (text.length > 0) segments.push({ type: "text", text });
+}

package/src/ui/status-bar.ts

@@ -0,0 +1,94 @@
+/**
+ * Status bar of the Injections list: what the selected row's changes are,
+ * where they live, who made them, and what its markers mean, one field per
+ * line. It never shows raw text or repeats the row's source or location.
+ * Pure string logic.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+import type { ChangeEditor, TokenDiff } from "../model.ts";
+import { normalizeInlineText } from "../text.ts";
+import type { ChangeScope, InjectionRow } from "./injections-model.ts";
+import { fitLine } from "./layout.ts";
+import { formatDiffAdded, formatDiffRemoved, guessMarker, markerStatusField } from "./markers.ts";
+
+/** Indent of each field, two columns deeper than the description, so the bar reads apart from it. */
+const FIELD_INDENT = "    ";
+/** Indent of a field's wrapped continuation lines. */
+const CONTINUATION_INDENT = "      ";
+
+/** Where a row's changes live, after the diff in its Change field. */
+const SCOPE_PHRASES: Record<ChangeScope, string> = {
+	saved: "saved in the session",
+	"saved-and-edit": "saved in the session, with an edit only in this request",
+	partly: "some saved in the session, some only in this request",
+	request: "only in this request",
+	"request-edit": "only in this request; the session keeps the original",
+	"request-new": "only in this request; not in the session",
+	payload: "only in the provider payload",
+};
+
+/** Why a `system prompt` row shows no value. */
+const DIFF_ONLY_NOTE = "Already counted in System Prompt";
+
+/**
+ * Wrapped status lines of one list row: Change, then Changed By or the note
+ * of a `system prompt` row, then one explanation per marker. Empty for a row
+ * without a change or marker, and for the separator and TOTAL.
+ */
+export function statusBarLines(theme: Theme, row: InjectionRow, width: number): string[] {
+	return statusFields(theme, row).flatMap((field) => wrapField(field, width));
+}
+
+/** Unwrapped fields of one row, in display order. */
+function statusFields(theme: Theme, row: InjectionRow): string[] {
+	if (row.kind !== "group" && row.kind !== "item") return [];
+	const fields: string[] = [];
+	if (row.scope !== undefined) fields.push(field(theme, "Change", changeText(theme, row.diff, row.scope)));
+	if (row.kind !== "item") return fields;
+	if (row.diffOnly === true) fields.push(theme.fg("dim", DIFF_ONLY_NOTE));
+	else if (row.editors !== undefined) fields.push(field(theme, "Changed By", editorsText(theme, row.editors)));
+	// A row shows one of Dropped and Moved, like its markers
+	if (row.dropped === true) fields.push(markerStatusField(theme, "dropped"));
+	else if (row.moved === true) fields.push(markerStatusField(theme, "moved"));
+	if (row.change === "forced") fields.push(markerStatusField(theme, "forced"));
+	if (row.forcedEdit !== undefined) {
+		fields.push(markerStatusField(theme, row.forcedEdit.sent ? "forced-edit-sent" : "forced-edit-unsent"));
+	}
+	return fields;
+}
+
+/** One field: its `muted` name, then a dim colon and the value. */
+function field(theme: Theme, name: string, value: string): string {
+	return `${theme.fg("muted", name)}${theme.fg("dim", ": ")}${value}`;
+}
+
+/** `+N -N` in the diff colors, then where the changes live; only the phrase without a diff. */
+function changeText(theme: Theme, diff: TokenDiff | undefined, scope: ChangeScope): 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)));
+	const phrase = SCOPE_PHRASES[scope];
+	if (sides.length === 0) return theme.fg("dim", phrase);
+	return `${sides.join(" ")}${theme.fg("dim", `${scope === "partly" ? "," : ""} ${phrase}`)}`;
+}
+
+/** Comma-separated editors: sanitized extension labels with a dim `(guess)` where inferred, then `Unknown`. */
+function editorsText(theme: Theme, editors: readonly ChangeEditor[]): string {
+	return editors.map((editor) => {
+		if (editor.type === "unknown") return theme.fg("dim", "Unknown");
+		const label = theme.fg("dim", normalizeInlineText(editor.source.label));
+		return editor.attribution === "guess" ? `${label}${guessMarker(theme)}` : label;
+	}).join(theme.fg("dim", ", "));
+}
+
+/** Wrap one field under its indent, hanging continuation lines two columns deeper. */
+function wrapField(text: string, width: number): string[] {
+	const indentWidth = Math.min(CONTINUATION_INDENT.length, Math.max(0, width - 1));
+	const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indentWidth));
+	return wrapped.map((line, index) => {
+		const indent = (index === 0 ? FIELD_INDENT : CONTINUATION_INDENT).slice(0, indentWidth);
+		return fitLine(`${indent}${line}`, width);
+	});
+}

package/src/ui/usage-map.ts

@@ -0,0 +1,157 @@
+/**
+ * Pure proportional-cell model for the Usage view's context map. Geometry is
+ * an input: the caller clamps the configured cell counts to what the viewport
+ * can render. The map uses estimated category totals against the selected
+ * Window/Fit scale. Pi's separately reported occupied tokens may differ
+ * because of tokenizer, serialization, caching, and last-response timing.
+ */
+import type { ContextUsageSnapshot } from "../model.ts";
+
+const FIT_SCALE_PERCENT = 115;
+const PERCENT_DENOMINATOR = 100;
+const MINIMUM_FIT_SCALE_TOKENS = 10_000;
+const FIT_SCALE_SIGNIFICANT_DIGITS = 2;
+
+/** One visual map cell assigned to a category, the auto-compact buffer, or remaining free space. */
+export interface UsageMapCell {
+	readonly categoryId?: string;
+	readonly fill: "full" | "partial" | "buffer" | "free";
+}
+
+/** Rectangular context-usage map in row-major order. */
+export interface UsageMap {
+	readonly columns: number;
+	readonly rows: number;
+	/** Tokens one cell represents at the active scale; shrinks when Fit narrows the denominator. */
+	readonly blockTokens: number;
+	readonly cells: readonly UsageMapCell[];
+}
+
+interface MapSegment {
+	readonly categoryId: string;
+	readonly start: number;
+	readonly end: number;
+}
+
+/**
+ * Calculate a Fit denominator from estimated occupancy: 15% headroom,
+ * rounded upward to two significant digits, with the documented floor/cap.
+ */
+export function calculateFitMapScale(usage: ContextUsageSnapshot): number | undefined {
+	const contextWindow = usage.reported?.contextWindow;
+	if (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) return undefined;
+
+	const estimatedTotal = usage.categories.reduce((sum, category) => sum + category.tokens, 0);
+	const withHeadroom = Math.max(0, estimatedTotal) * FIT_SCALE_PERCENT / PERCENT_DENOMINATOR;
+	const rounded = roundUpToSignificantDigits(withHeadroom, FIT_SCALE_SIGNIFICANT_DIGITS);
+	return Math.min(contextWindow, Math.max(MINIMUM_FIT_SCALE_TOKENS, rounded));
+}
+
+/**
+ * Build a proportional map from estimated categories. `scaleTokens` changes
+ * only the mapped denominator; buffer placement remains anchored to the true
+ * context window. Returns undefined without a usable denominator.
+ */
+export function buildUsageMap(
+	usage: ContextUsageSnapshot,
+	columns: number,
+	rows: number,
+	scaleTokens?: number,
+): UsageMap | undefined {
+	const contextWindow = usage.reported?.contextWindow;
+	if (
+		contextWindow === undefined ||
+		!Number.isFinite(contextWindow) ||
+		contextWindow <= 0 ||
+		columns <= 0 ||
+		rows <= 0
+	) return undefined;
+
+	const requestedScale = scaleTokens ?? contextWindow;
+	if (!Number.isFinite(requestedScale) || requestedScale <= 0) return undefined;
+	const mapScale = Math.min(contextWindow, requestedScale);
+	const cellCount = Math.floor(columns) * Math.floor(rows);
+	const estimatedTotal = usage.categories.reduce((sum, category) => sum + category.tokens, 0);
+	const occupiedTokens = clamp(estimatedTotal, 0, mapScale);
+	const occupiedCells = occupiedTokens / mapScale * cellCount;
+	// Fit reserves its headroom as visible free space; the true-window buffer remains outside the mapped range.
+	const windowOccupancy = clamp(estimatedTotal, 0, contextWindow);
+	const bufferTokens = mapScale < contextWindow
+		? 0
+		: clamp(usage.autoCompactReserveTokens ?? 0, 0, contextWindow - windowOccupancy);
+	const bufferStart = (contextWindow - bufferTokens) / mapScale * cellCount;
+	const segments = createSegments(usage, estimatedTotal, occupiedCells);
+	const cells = Array.from(
+		{ length: cellCount },
+		(_, index) => createCell(index, occupiedCells, bufferStart, segments),
+	);
+	return {
+		columns: Math.floor(columns),
+		rows: Math.floor(rows),
+		blockTokens: mapScale / cellCount,
+		cells,
+	};
+}
+
+/** Scale estimated category shares into the occupied map range. */
+function createSegments(
+	usage: ContextUsageSnapshot,
+	estimatedTotal: number,
+	occupiedCells: number,
+): MapSegment[] {
+	if (estimatedTotal <= 0 || occupiedCells <= 0) return [];
+	const segments: MapSegment[] = [];
+	let cursor = 0;
+	for (const category of usage.categories) {
+		const size = category.tokens / estimatedTotal * occupiedCells;
+		segments.push({ categoryId: category.id, start: cursor, end: cursor + size });
+		cursor += size;
+	}
+	return segments;
+}
+
+/** Assign one map cell to its largest category overlap and classify its fill. */
+function createCell(
+	index: number,
+	occupiedCells: number,
+	bufferStart: number,
+	segments: readonly MapSegment[],
+): UsageMapCell {
+	const occupiedOverlap = overlap(index, index + 1, 0, occupiedCells);
+	if (occupiedOverlap <= 0) {
+		// An unoccupied cell belongs to the buffer when at least half of it lies past the trigger point.
+		return overlap(index, index + 1, bufferStart, index + 1) >= 0.5 ? { fill: "buffer" } : { fill: "free" };
+	}
+
+	let categoryId: string | undefined;
+	let categoryOverlap = 0;
+	for (const segment of segments) {
+		const currentOverlap = overlap(index, index + 1, segment.start, segment.end);
+		if (currentOverlap > categoryOverlap) {
+			categoryId = segment.categoryId;
+			categoryOverlap = currentOverlap;
+		}
+	}
+	return {
+		categoryId,
+		fill: categoryOverlap >= 0.7 ? "full" : "partial",
+	};
+}
+
+/** Length shared by two half-open numeric ranges. */
+function overlap(aStart: number, aEnd: number, bStart: number, bEnd: number): number {
+	return Math.max(0, Math.min(aEnd, bEnd) - Math.max(aStart, bStart));
+}
+
+/** Round a positive value upward at the requested significant-digit boundary. */
+function roundUpToSignificantDigits(value: number, significantDigits: number): number {
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	const boundary = 10 ** (Math.floor(Math.log10(value)) - significantDigits + 1);
+	return Math.ceil(value / boundary) * boundary;
+}
+
+/** Restrict a finite value to an inclusive range. */
+function clamp(value: number, minimum: number, maximum: number): number {
+	if (!Number.isFinite(value)) return minimum;
+	return Math.min(maximum, Math.max(minimum, value));
+}