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

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));
+}

package/src/ui/usage-preview.ts

@@ -0,0 +1,202 @@
+/**
+ * Pure block model for the Usage category preview: geometry of the flattened
+ * line stream plus the selection, paging, and in-block scrolling state shared
+ * by every preview width. No pi or TUI access — unit-testable.
+ */
+
+/** Absolute line span of one block inside the flattened preview stream. */
+export interface PreviewBlockExtent {
+	readonly start: number;
+	readonly height: number;
+}
+
+/** Owner of one flattened preview line; blank separator rows have none. */
+export interface PreviewLineRef {
+	readonly blockIndex: number;
+	readonly lineIndex: number;
+}
+
+/** Flattened preview stream: block spans plus per-line ownership. */
+export interface PreviewLayout {
+	readonly extents: readonly PreviewBlockExtent[];
+	readonly lines: ReadonlyArray<PreviewLineRef | undefined>;
+}
+
+/** Stack block heights into one line stream separated by a blank row. */
+export function layoutPreviewBlocks(heights: readonly number[]): PreviewLayout {
+	const extents: PreviewBlockExtent[] = [];
+	const lines: Array<PreviewLineRef | undefined> = [];
+	for (const [blockIndex, height] of heights.entries()) {
+		if (blockIndex > 0) lines.push(undefined);
+		extents.push({ start: lines.length, height });
+		for (let lineIndex = 0; lineIndex < height; lineIndex++) lines.push({ blockIndex, lineIndex });
+	}
+	return { extents, lines };
+}
+
+/**
+ * Selection and scroll state over stacked preview blocks. Steps move block to
+ * block, except that a block taller than the viewport scrolls line by line
+ * until its far edge is reached. Extent is re-declared each render because
+ * wrapping and terminal height both change it.
+ */
+export class BlockNavigator {
+	private extents: readonly PreviewBlockExtent[] = [];
+	private lineCount = 0;
+	private visibleCount = 1;
+	private selectedIndex = 0;
+	private offsetValue = 0;
+
+	/** Index of the selected block. */
+	public get selected(): number {
+		return this.selectedIndex;
+	}
+
+	/** Number of navigable blocks in the current stream. */
+	public get blockCount(): number {
+		return this.extents.length;
+	}
+
+	/** First stream line currently visible. */
+	public get offset(): number {
+		return this.offsetValue;
+	}
+
+	/** Highest offset that still fills the viewport. */
+	public get maxOffset(): number {
+		return Math.max(0, this.lineCount - this.visibleCount);
+	}
+
+	/** Adopt new geometry, keeping the scroll position unless it hides the selected block. */
+	public setExtent(layout: PreviewLayout, visibleCount: number): void {
+		this.extents = layout.extents;
+		this.lineCount = layout.lines.length;
+		this.visibleCount = Math.max(1, visibleCount);
+		this.selectedIndex = clamp(this.selectedIndex, this.extents.length - 1);
+		this.offsetValue = clamp(this.offsetValue, this.maxOffset);
+		if (!this.isSelectionAnchored()) this.revealSelected();
+	}
+
+	/** Step back one block, or one line while the selected block extends above the viewport. */
+	public stepBack(): boolean {
+		const block = this.extents[this.selectedIndex];
+		if (block === undefined) return false;
+		if (block.start < this.offsetValue) return this.scrollTo(this.offsetValue - 1);
+		return this.selectBlock(this.selectedIndex - 1, -1);
+	}
+
+	/** Step forward one block, or one line while the selected block extends below the viewport. */
+	public stepForward(): boolean {
+		const block = this.extents[this.selectedIndex];
+		if (block === undefined) return false;
+		if (block.start + block.height > this.offsetValue + this.visibleCount) {
+			return this.scrollTo(this.offsetValue + 1);
+		}
+		return this.selectBlock(this.selectedIndex + 1, 1);
+	}
+
+	/** Page by the viewport height, then finish at the stream boundary from its first or last page. */
+	public page(direction: -1 | 1): boolean {
+		if (this.extents.length === 0) return false;
+		const offset = clamp(this.offsetValue + direction * this.visibleCount, this.maxOffset);
+		if (offset === this.offsetValue) {
+			const boundaryIndex = direction < 0 ? 0 : this.extents.length - 1;
+			return this.moveTo(boundaryIndex, offset);
+		}
+		return this.moveTo(this.firstVisibleBlock(offset), offset);
+	}
+
+	/** Select one block, e.g. the one holding a search match, scrolling minimally to show it. */
+	public select(index: number): boolean {
+		if (index < 0 || index >= this.extents.length || index === this.selectedIndex) return false;
+		this.selectedIndex = index;
+		this.revealSelected();
+		return true;
+	}
+
+	/** Select the first block at the top of the stream. */
+	public moveToFirst(): boolean {
+		return this.moveTo(0, 0);
+	}
+
+	/** Select the last block at the end of the stream. */
+	public moveToLast(): boolean {
+		return this.moveTo(this.extents.length - 1, this.maxOffset);
+	}
+
+	/** Start over at the first block after the preview target changes. */
+	public reset(): void {
+		this.selectedIndex = 0;
+		this.offsetValue = 0;
+	}
+
+	/** Move selection to an existing block and reveal the edge reached in the navigation direction. */
+	private selectBlock(index: number, direction: -1 | 1): boolean {
+		if (index < 0 || index >= this.extents.length || index === this.selectedIndex) return false;
+		this.selectedIndex = index;
+		this.revealSelected(direction);
+		return true;
+	}
+
+	/** Scroll the stream to a clamped offset. */
+	private scrollTo(offset: number): boolean {
+		const next = clamp(offset, this.maxOffset);
+		if (next === this.offsetValue) return false;
+		this.offsetValue = next;
+		return true;
+	}
+
+	/** Apply a selection and offset pair, reporting whether either changed. */
+	private moveTo(index: number, offset: number): boolean {
+		const nextIndex = clamp(index, this.extents.length - 1);
+		const nextOffset = clamp(offset, this.maxOffset);
+		if (nextIndex === this.selectedIndex && nextOffset === this.offsetValue) return false;
+		this.selectedIndex = nextIndex;
+		this.offsetValue = nextOffset;
+		return true;
+	}
+
+	/** Whether the selected block is fully shown, or intersects the viewport when too tall to fit. */
+	private isSelectionAnchored(): boolean {
+		const block = this.extents[this.selectedIndex];
+		if (block === undefined) return true;
+		const end = block.start + block.height;
+		if (block.height <= this.visibleCount) {
+			return block.start >= this.offsetValue && end <= this.offsetValue + this.visibleCount;
+		}
+		return block.start < this.offsetValue + this.visibleCount && end > this.offsetValue;
+	}
+
+	/** Scroll minimally to show the selected block; oversized blocks expose the approached edge. */
+	private revealSelected(direction?: -1 | 1): void {
+		const block = this.extents[this.selectedIndex];
+		if (block === undefined) return;
+		const end = block.start + block.height;
+		if (block.height > this.visibleCount) {
+			if (direction === -1) this.scrollTo(end - this.visibleCount);
+			else if (direction === 1 || !this.isSelectionAnchored()) this.scrollTo(block.start);
+			return;
+		}
+		if (block.start < this.offsetValue) this.scrollTo(block.start);
+		else if (end > this.offsetValue + this.visibleCount) this.scrollTo(end - this.visibleCount);
+	}
+
+	/** First block fully inside the viewport, falling back to the first one it intersects. */
+	private firstVisibleBlock(offset: number): number {
+		const end = offset + this.visibleCount;
+		let firstIntersecting: number | undefined;
+		for (const [index, block] of this.extents.entries()) {
+			const blockEnd = block.start + block.height;
+			if (block.start >= offset && blockEnd <= end) return index;
+			if (firstIntersecting === undefined && block.start < end && blockEnd > offset) {
+				firstIntersecting = index;
+			}
+		}
+		return firstIntersecting ?? this.selectedIndex;
+	}
+}
+
+/** Restrict a candidate index or offset to a non-negative range. */
+function clamp(value: number, max: number): number {
+	return Math.max(0, Math.min(max, value));
+}