@badliveware/pi-footer-framework 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.1
+
+- Fixed footer rendering with cell-buffer composition so ANSI styling, OSC8 hyperlinks, grapheme clusters, wide characters, and overlays preserve terminal cell alignment.
+- Improved diagnostics for rendered footer layout and right/center overlay behavior.
+- Hardened footer line clearing so overwriting wide-character runs does not leave stale continuation cells.
+
+## 0.2.0
+
+- Added TypeScript render config support.
+- Simplified footer framework configuration and generalized framework-owned layout behavior.
+- Added adapter templates and built-in footer data source adaptation.
+
+## 0.1.1
+
+- Initial public package release.

package/index.ts

@@ -52,6 +52,266 @@ interface FooterItem {
 	renderSource?: "template" | "function" | "external";
 }
 
+export interface FooterCell {
+	raw: string;
+	plainText: string;
+	itemId?: string;
+	continuation?: boolean;
+	filler?: boolean;
+}
+
+export interface FooterColumnItem {
+	id: string;
+	text: string;
+	placement: Pick<FooterItemPlacement, "column" | "order">;
+}
+
+export interface ComposeFooterLineOptions {
+	width: number;
+	left: string;
+	right?: string;
+	anchor: FooterAnchorMode;
+	minGap: number;
+	maxGap: number;
+	ellipsis?: string;
+}
+
+export function readAnsiEscape(text: string, index: number): string | undefined {
+	if (text.charCodeAt(index) !== 0x1b) return undefined;
+	const csi = text.slice(index).match(/^\u001b\[[0-?]*[ -/]*[@-~]/)?.[0];
+	if (csi) return csi;
+	return text.slice(index).match(/^\u001b\][\s\S]*?(?:\u0007|\u001b\\)/)?.[0];
+}
+
+type GraphemeSegmenter = { segment(input: string): Iterable<{ segment: string }> };
+const Segmenter = (Intl as unknown as { Segmenter?: new (locale?: string | string[], options?: { granularity: "grapheme" }) => GraphemeSegmenter }).Segmenter;
+const graphemeSegmenter = Segmenter ? new Segmenter(undefined, { granularity: "grapheme" }) : undefined;
+
+function* visibleClusters(chunk: string): Iterable<string> {
+	if (graphemeSegmenter) {
+		for (const { segment } of graphemeSegmenter.segment(chunk)) yield segment;
+		return;
+	}
+	for (const char of Array.from(chunk)) yield char;
+}
+
+function updateAnsiState(escape: string, state: { ansi: string; osc: string }): void {
+	const osc8 = escape.match(/^\u001b\]8;[^;]*;([\s\S]*?)(?:\u0007|\u001b\\)$/);
+	if (osc8) {
+		state.osc = osc8[1] ? escape : "";
+		return;
+	}
+	if (!/^\u001b\[[0-?]*[ -/]*m$/.test(escape)) return;
+	const params = escape.match(/^\u001b\[([0-?]*)[ -/]*m$/)?.[1] ?? "";
+	if (params === "" || params === "0") state.ansi = "";
+	else if (params.startsWith("0;") || params.startsWith("0:")) state.ansi = escape;
+	else state.ansi += escape;
+}
+
+function activeCellPrefix(state: { ansi: string; osc: string }): string {
+	return `${state.osc}${state.ansi}`;
+}
+
+function activeCellSuffix(state: { ansi: string; osc: string }): string {
+	return `${state.ansi ? "\u001b[0m" : ""}${state.osc ? "\u001b]8;;\u0007" : ""}`;
+}
+
+function blankFooterCell(): FooterCell {
+	return { raw: " ", plainText: " ", filler: true };
+}
+
+export function createFooterCells(width: number): FooterCell[] {
+	return Array.from({ length: Math.max(0, width) }, blankFooterCell);
+}
+
+export function footerCellsFromText(text: string, itemId?: string): FooterCell[] {
+	const cells: FooterCell[] = [];
+	const state = { ansi: "", osc: "" };
+	let pendingZeroWidthRaw = "";
+	let pendingZeroWidthPlain = "";
+	const appendCluster = (cluster: string) => {
+		const clusterWidth = visibleWidth(cluster);
+		if (clusterWidth === 0) {
+			const raw = `${activeCellPrefix(state)}${cluster}${activeCellSuffix(state)}`;
+			let previous: FooterCell | undefined;
+			for (let cursor = cells.length - 1; cursor >= 0; cursor -= 1) {
+				if (!cells[cursor].continuation) {
+					previous = cells[cursor];
+					break;
+				}
+			}
+			if (previous) {
+				previous.raw += raw;
+				previous.plainText += cluster;
+			} else {
+				pendingZeroWidthRaw += raw;
+				pendingZeroWidthPlain += cluster;
+			}
+		} else {
+			cells.push({ raw: `${pendingZeroWidthRaw}${activeCellPrefix(state)}${cluster}${activeCellSuffix(state)}`, plainText: `${pendingZeroWidthPlain}${cluster}`, itemId });
+			pendingZeroWidthRaw = "";
+			pendingZeroWidthPlain = "";
+			for (let i = 1; i < clusterWidth; i += 1) cells.push({ raw: "", plainText: "", itemId, continuation: true });
+		}
+	};
+
+	let index = 0;
+	while (index < text.length) {
+		const escape = readAnsiEscape(text, index);
+		if (escape) {
+			updateAnsiState(escape, state);
+			index += escape.length;
+			continue;
+		}
+
+		const nextEscape = text.indexOf("\u001b", index);
+		const chunkEnd = nextEscape === -1 ? text.length : nextEscape;
+		if (chunkEnd === index) {
+			const codePoint = text.codePointAt(index);
+			if (codePoint === undefined) break;
+			const cluster = String.fromCodePoint(codePoint);
+			appendCluster(cluster);
+			index += cluster.length;
+			continue;
+		}
+
+		for (const cluster of visibleClusters(text.slice(index, chunkEnd))) appendCluster(cluster);
+		index = chunkEnd;
+	}
+	return cells;
+}
+
+export function plainFooterText(text: string): string {
+	return footerCellsFromText(text)
+		.filter((cell) => !cell.continuation)
+		.map((cell) => cell.plainText)
+		.join("");
+}
+
+function clearFooterCells(cells: FooterCell[], start: number, width: number): void {
+	if (width <= 0 || start >= cells.length) return;
+	const from = clamp(start, 0, cells.length);
+	const to = clamp(start + width, 0, cells.length);
+	const clearWideRun = (index: number) => {
+		let cursor = index;
+		while (cursor >= 0 && cells[cursor]?.continuation) cursor -= 1;
+		if (cursor < 0 || cursor >= cells.length) return;
+		cells[cursor] = blankFooterCell();
+		cursor += 1;
+		while (cursor < cells.length && cells[cursor].continuation) {
+			cells[cursor] = blankFooterCell();
+			cursor += 1;
+		}
+	};
+	if (cells[from]?.continuation) clearWideRun(from);
+	if (cells[to]?.continuation) clearWideRun(to);
+	for (let index = from; index < to; index += 1) cells[index] = blankFooterCell();
+}
+
+export function writeFooterText(cells: FooterCell[], start: number, text: string, itemId?: string): void {
+	if (start >= cells.length) return;
+	const textCells = footerCellsFromText(text, itemId);
+	clearFooterCells(cells, start, textCells.length);
+	for (let offset = 0; offset < textCells.length; offset += 1) {
+		const index = start + offset;
+		if (index < 0 || index >= cells.length) continue;
+		cells[index] = textCells[offset];
+	}
+}
+
+export function renderFooterCells(cells: FooterCell[]): string {
+	let end = cells.length;
+	while (end > 0) {
+		const cell = cells[end - 1];
+		if (cell.continuation || !cell.filler) break;
+		end -= 1;
+	}
+	return cells.slice(0, end).map((cell) => (cell.continuation ? "" : cell.raw)).join("");
+}
+
+export function resolveFooterColumn(column: FooterColumn | undefined, width: number, itemWidth: number): number | undefined {
+	if (column === undefined) return undefined;
+	if (typeof column === "number") return clamp(column, 0, Math.max(0, width - 1));
+	if (column === "center" || column === "middle") return clamp(Math.round((width - itemWidth) / 2), 0, Math.max(0, width - 1));
+	const percent = Number(column.slice(0, -1));
+	if (!Number.isFinite(percent)) return undefined;
+	const target = Math.round((width - 1) * (percent / 100));
+	return clamp(Math.round(target - itemWidth / 2), 0, Math.max(0, width - 1));
+}
+
+export function composeFooterLine(options: ComposeFooterLineOptions): { line: string; layout: FooterLineLayout } {
+	const { width, left, right, anchor, minGap, maxGap, ellipsis = "..." } = options;
+	const leftWidth = visibleWidth(left);
+	const cells = createFooterCells(width);
+	const compactLeft = truncateToWidth(left, width, ellipsis);
+	writeFooterText(cells, 0, compactLeft);
+
+	if (!right || visibleWidth(right) === 0) {
+		return {
+			line: renderFooterCells(cells),
+			layout: {
+				anchor,
+				leftWidth,
+				rightWidthOriginal: 0,
+				rightWidthFinal: 0,
+				padCount: 0,
+				rightStartCol: leftWidth,
+				rightEndCol: leftWidth,
+				truncated: visibleWidth(compactLeft) < leftWidth,
+			},
+		};
+	}
+
+	const rightWidthOriginal = visibleWidth(right);
+	const naturalPad = width - leftWidth - rightWidthOriginal;
+	let padCount = minGap;
+	if (anchor === "right" || anchor === "spread") {
+		padCount = Math.max(minGap, naturalPad);
+	} else if (anchor === "center") {
+		padCount = Math.max(minGap, Math.floor(naturalPad / 2));
+		padCount = Math.min(padCount, maxGap);
+	} else if (anchor === "gap") {
+		padCount = Math.max(minGap, Math.min(naturalPad, maxGap));
+	} else if (anchor === "left") {
+		padCount = minGap;
+	}
+
+	const availableForRight = Math.max(0, width - leftWidth - padCount);
+	const compactRight = truncateToWidth(right, availableForRight, ellipsis);
+	const rightWidthFinal = visibleWidth(compactRight);
+	const rightStartCol = leftWidth + padCount;
+	writeFooterText(cells, rightStartCol, compactRight);
+	const rightEndCol = Math.max(rightStartCol, rightStartCol + rightWidthFinal - 1);
+	return {
+		line: renderFooterCells(cells),
+		layout: {
+			anchor,
+			leftWidth,
+			rightWidthOriginal,
+			rightWidthFinal,
+			padCount,
+			rightStartCol,
+			rightEndCol,
+			truncated: rightWidthFinal < rightWidthOriginal,
+		},
+	};
+}
+
+export function overlayFooterColumnItems(width: number, line: string, items: FooterColumnItem[], ellipsis = "..."): string {
+	const cells = createFooterCells(width);
+	writeFooterText(cells, 0, line);
+	const sorted = items
+		.map((item) => ({ item, column: resolveFooterColumn(item.placement.column, width, visibleWidth(item.text)) }))
+		.filter((entry): entry is { item: FooterColumnItem; column: number } => entry.column !== undefined)
+		.sort((a, b) => a.column - b.column || a.item.placement.order - b.item.placement.order);
+	for (const { item, column } of sorted) {
+		const available = Math.max(0, width - column);
+		const text = truncateToWidth(item.text, available, ellipsis);
+		writeFooterText(cells, column, text, item.id);
+	}
+	return renderFooterCells(cells);
+}
+
 export interface FooterSpan {
 	text: unknown;
 	style?: string;
@@ -130,15 +390,27 @@ interface ExternalFooterItem {
 	hint: FooterItemDisplayHint;
 }
 
+interface FooterRenderDiagnostic {
+	itemId: string;
+	line: FooterLine;
+	severity: "warning";
+	message: string;
+	itemPlainText: string;
+	linePlainText?: string;
+}
+
 interface FooterSnapshot {
 	width: number;
-	lines: Array<{ line: FooterLine; text: string; layout: FooterLineLayout }>;
+	lines: Array<{ line: FooterLine; text: string; plainText: string; layout: FooterLineLayout }>;
 	line1: string;
 	line2: string;
+	line1PlainText: string;
+	line2PlainText: string;
 	line1Layout: FooterLineLayout;
 	line2Layout: FooterLineLayout;
 	gitBranch: string | null;
-	renderedItems: Array<{ id: string; line: FooterLine; zone: FooterZone; order: number; column?: FooterColumn; width: number; renderSource?: string; tokens?: FooterRenderedToken[] }>;
+	renderedItems: Array<{ id: string; line: FooterLine; zone: FooterZone; order: number; column?: FooterColumn; width: number; plainText: string; renderSource?: string; tokens?: FooterRenderedToken[] }>;
+	renderDiagnostics: FooterRenderDiagnostic[];
 	extensionStatuses: Array<{ key: string; value: string }>;
 	model: string;
 	contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } | null;
@@ -1498,66 +1770,9 @@ export default function footerFramework(pi: ExtensionAPI): void {
 		anchor: FooterAnchorMode,
 	): {
 		line: string;
-		layout: {
-			anchor: FooterAnchorMode;
-			leftWidth: number;
-			rightWidthOriginal: number;
-			rightWidthFinal: number;
-			padCount: number;
-			rightStartCol: number;
-			rightEndCol: number;
-			truncated: boolean;
-		};
+		layout: FooterLineLayout;
 	} {
-		const leftWidth = visibleWidth(left);
-		if (!right || visibleWidth(right) === 0) {
-			return {
-				line: truncateToWidth(left, width, theme.fg("dim", "...")),
-				layout: {
-					anchor,
-					leftWidth,
-					rightWidthOriginal: 0,
-					rightWidthFinal: 0,
-					padCount: 0,
-					rightStartCol: leftWidth,
-					rightEndCol: leftWidth,
-					truncated: false,
-				},
-			};
-		}
-		const rightWidthOriginal = visibleWidth(right);
-		const naturalPad = width - leftWidth - rightWidthOriginal;
-		let padCount = settings.minGap;
-		if (anchor === "right" || anchor === "spread") {
-			padCount = Math.max(settings.minGap, naturalPad);
-		} else if (anchor === "center") {
-			padCount = Math.max(settings.minGap, Math.floor(naturalPad / 2));
-			padCount = Math.min(padCount, settings.maxGap);
-		} else if (anchor === "gap") {
-			padCount = Math.max(settings.minGap, Math.min(naturalPad, settings.maxGap));
-		} else if (anchor === "left") {
-			padCount = settings.minGap;
-		}
-
-		const availableForRight = Math.max(0, width - leftWidth - padCount);
-		const compactRight = truncateToWidth(right, availableForRight, theme.fg("dim", "..."));
-		const rightWidthFinal = visibleWidth(compactRight);
-		const line = truncateToWidth(`${left}${" ".repeat(padCount)}${compactRight}`, width, theme.fg("dim", "..."));
-		const rightStartCol = leftWidth + padCount;
-		const rightEndCol = Math.max(rightStartCol, rightStartCol + rightWidthFinal - 1);
-		return {
-			line,
-			layout: {
-				anchor,
-				leftWidth,
-				rightWidthOriginal,
-				rightWidthFinal,
-				padCount,
-				rightStartCol,
-				rightEndCol,
-				truncated: rightWidthFinal < rightWidthOriginal,
-			},
-		};
+		return composeFooterLine({ width, left, right, anchor, minGap: settings.minGap, maxGap: settings.maxGap, ellipsis: theme.fg("dim", "...") });
 	}
 
 	function renderModelLabel(): string {
@@ -1608,30 +1823,39 @@ export default function footerFramework(pi: ExtensionAPI): void {
 		return sorted.sort((a, b) => a.placement.order - b.placement.order || a.id.localeCompare(b.id));
 	}
 
-	function resolveOverlayColumn(column: FooterColumn | undefined, width: number, itemWidth: number): number | undefined {
-		if (column === undefined) return undefined;
-		if (typeof column === "number") return clamp(column, 0, Math.max(0, width - 1));
-		if (column === "center" || column === "middle") return clamp(Math.round((width - itemWidth) / 2), 0, Math.max(0, width - 1));
-		const percent = Number(column.slice(0, -1));
-		if (!Number.isFinite(percent)) return undefined;
-		const target = Math.round((width - 1) * (percent / 100));
-		return clamp(Math.round(target - itemWidth / 2), 0, Math.max(0, width - 1));
+	function renderVisibilityDiagnostics(items: FooterItem[], lines: Array<{ line: FooterLine; plainText: string }>): FooterRenderDiagnostic[] {
+		const lineTextByNumber = new Map(lines.map((line) => [line.line, line.plainText]));
+		const diagnostics: FooterRenderDiagnostic[] = [];
+		for (const item of items) {
+			const itemPlainText = plainFooterText(item.text).trim();
+			if (!itemPlainText) continue;
+			const linePlainText = lineTextByNumber.get(item.placement.line);
+			if (linePlainText === undefined) {
+				diagnostics.push({
+					itemId: item.id,
+					line: item.placement.line,
+					severity: "warning",
+					message: "Item rendered but its footer line was not produced.",
+					itemPlainText,
+				});
+				continue;
+			}
+			if (!linePlainText.includes(itemPlainText)) {
+				diagnostics.push({
+					itemId: item.id,
+					line: item.placement.line,
+					severity: "warning",
+					message: "Item is present in renderedItems but its text is not visible in the final rendered line; check overlap, truncation, or layout composition.",
+					itemPlainText,
+					linePlainText,
+				});
+			}
+		}
+		return diagnostics;
 	}
 
 	function overlayAbsoluteItems(theme: ExtensionContext["ui"]["theme"], width: number, line: string, items: FooterItem[]): string {
-		let out = line;
-		const sorted = items
-			.map((item) => ({ item, column: resolveOverlayColumn(item.placement.column, width, visibleWidth(item.text)) }))
-			.filter((entry): entry is { item: FooterItem; column: number } => entry.column !== undefined)
-			.sort((a, b) => a.column - b.column || a.item.placement.order - b.item.placement.order);
-		for (const { item, column } of sorted) {
-			const prefix = truncateToWidth(out, column, "");
-			const pad = " ".repeat(Math.max(0, column - visibleWidth(prefix)));
-			const available = Math.max(0, width - column);
-			const text = truncateToWidth(item.text, available, theme.fg("dim", "..."));
-			out = truncateToWidth(`${prefix}${pad}${text}`, width, theme.fg("dim", "..."));
-		}
-		return out;
+		return overlayFooterColumnItems(width, line, items, theme.fg("dim", "..."));
 	}
 
 	function renderFooterLine(theme: ExtensionContext["ui"]["theme"], width: number, items: FooterItem[], line: FooterLine, anchor: FooterAnchorMode) {
@@ -1951,29 +2175,34 @@ export default function footerFramework(pi: ExtensionAPI): void {
 					const lineResults = Array.from({ length: maxLine }, (_, index) => {
 						const line = index + 1;
 						const result = renderFooterLine(theme, width, items, line, getLineAnchor(settings, line));
-						return { line, text: result.line, layout: result.layout };
+						return { line, text: result.line, plainText: plainFooterText(result.line), layout: result.layout };
 					});
 					const line1Result = lineResults[0];
 					const line2Result = lineResults[1];
+					const renderedItems = items.map((item) => ({
+						id: item.id,
+						line: item.placement.line,
+						zone: item.placement.zone,
+						order: item.placement.order,
+						column: item.placement.column,
+						width: visibleWidth(item.text),
+						plainText: plainFooterText(item.text),
+						renderSource: item.renderSource,
+						tokens: item.tokens,
+					}));
 
 					lastFooterSnapshot = {
 						width,
 						lines: lineResults,
 						line1: line1Result?.text ?? "",
 						line2: line2Result?.text ?? "",
+						line1PlainText: line1Result?.plainText ?? "",
+						line2PlainText: line2Result?.plainText ?? "",
 						line1Layout: line1Result?.layout ?? renderFooterLine(theme, width, [], 1, getLineAnchor(settings, 1)).layout,
 						line2Layout: line2Result?.layout ?? renderFooterLine(theme, width, [], 2, getLineAnchor(settings, 2)).layout,
 						gitBranch: footerData.getGitBranch(),
-						renderedItems: items.map((item) => ({
-							id: item.id,
-							line: item.placement.line,
-							zone: item.placement.zone,
-							order: item.placement.order,
-							column: item.placement.column,
-							width: visibleWidth(item.text),
-							renderSource: item.renderSource,
-							tokens: item.tokens,
-						})),
+						renderedItems,
+						renderDiagnostics: renderVisibilityDiagnostics(items, lineResults),
 						extensionStatuses: Array.from(footerData.getExtensionStatuses().entries()).map(([key, value]) => ({ key, value })),
 						model: ctx.model?.id ?? "no-model",
 						contextUsage: ctx.getContextUsage() ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@badliveware/pi-footer-framework",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Configurable footer framework extension for Pi.",
   "type": "module",
   "types": "./index.ts",
@@ -26,6 +26,7 @@
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "assets",
     "examples",

package/skills/footer-framework-config/SKILL.md

@@ -64,13 +64,14 @@ Use this skill when a user wants footer layout changes without editing extension
 4. Use templates when the user wants portable JSON config or simple token-level styling, such as `{{ pi.cwd | compactPath: 48, 2 | style: "dim" }} {{ pi.branch.label | default: "" | truncate: 22 | style: "accent" }}`.
 5. Use `~/.pi/agent/footer-framework.config.ts` or `<project>/.pi/footer-framework.config.ts` when normal TS helper functions are clearer; commands and tools should keep writing JSON overrides rather than rewriting TS source unless the user explicitly asks.
 6. Check `footer_framework_state` or `/footerfx-debug` for template/render diagnostics after changing templates or TS render closures.
-7. Apply one focused change at a time (adapter, template/render closure, item placement, section, anchor, or gap).
-8. Changes made through commands/tools persist automatically to the user JSON config; use `/footerfx save project` only when the user explicitly wants project-specific layout.
-9. Prefer minimal-density defaults:
+7. After any layout or visibility change, compare `lastFooterSnapshot.renderedItems[].plainText` with `lastFooterSnapshot.lines[].plainText` and read `lastFooterSnapshot.renderDiagnostics`. If an item exists in `renderedItems` but its text is missing from the final line, treat it as a layout/rendering bug or overlap/truncation issue, not as proof that more placement tweaks are needed.
+8. Apply one focused change at a time (adapter, template/render closure, item placement, section, anchor, or gap).
+9. Changes made through commands/tools persist automatically to the user JSON config; use `/footerfx save project` only when the user explicitly wants project-specific layout.
+10. Prefer minimal-density defaults:
    - keep `cwd`, `stats`, `context`, `model`, `branch` on
    - show `pr` when relevant
    - adapt only the extension statuses the user wants instead of relying on the generic `ext` bucket
-10. If the user dislikes custom-footer behavior, run `/footerfx off`.
+11. If the user dislikes custom-footer behavior, run `/footerfx off`.
 
 ## Presets
 ### Compact