pi-zentui 0.13.0 → 0.15.0

package/README.md

@@ -130,7 +130,16 @@ pi install git:github.com/lmilojevicc/pi-zentui
 
 User config lives at `~/.pi/agent/zentui.json`. The file is optional: missing or invalid known values fall back to Zentui defaults, unknown keys are ignored at runtime, and `/zentui` can patch color-source settings, UI feature toggles, built-in footer segment visibility, and active third-party status placements.
 
-The interactive `/zentui` menu is split into five sections. Use `Tab` and `Shift+Tab` to switch between `Coloring`, `Features`, `Layout`, `Built-in segments`, and `Extension segments`.
+The interactive `/zentui` menu is split into exactly six sections, in this order. Use `Tab` and `Shift+Tab` to switch sections. Every listed control patches the shown JSON equivalent:
+
+1. **Appearance** — Starship/footer colors (`colorSources.starship`); editor + previous-message colors (`colorSources.editor` and `colorSources.userMessages`); separator (`separator`); icon mode (`icons.mode`).
+2. **Editor** — editor enabled (`features.editor`); editor model label (`editorModelLabel`); copy-friendly mode (`features.copyFriendly`); viewport indicators (`features.viewportIndicators`); fixed editor (`fixedEditor.enabled`); and, while fixed editor is enabled, mouse scroll (`fixedEditor.mouseScroll`) and copy notice (`fixedEditor.copyNotice`).
+3. **Footer** — status line enabled (`features.statusLine`); responsive footer (`responsiveFooter`); compact footer rows (`compactFooterMaxLines`); context style (`contextStyle`); path display (`pathDisplay.mode`); path depth (`pathDisplay.depth`).
+4. **Segments** — visibility toggles for every non-Git built-in segment under `footerSegments`: `cwd`, `sessionName`, `runtime`, `context`, `tokens`, `cost`, `sessionDuration`, `username`, `time`, `os`, and `packageVersion`.
+5. **Git** — Git branch visibility (`footerSegments.gitBranch`); branch length (`gitBranch.maxLength`); Git status visibility (`footerSegments.gitStatus`); Git counts visibility (`footerSegments.gitCounts`); Git commit visibility (`footerSegments.gitCommit`); commit-only-detached (`gitCommit.onlyDetached`); exact-match tag (`gitCommit.showTag`); Git metrics visibility (`footerSegments.gitMetrics`); hide zero metrics (`gitMetrics.onlyNonzero`); ignore submodules (`gitMetrics.ignoreSubmodules`).
+6. **Extensions** — default placement (`extensionStatuses.defaultPlacement`) first, followed by placement (`extensionStatuses.placements[key]`) and color (`extensionStatuses.colorModes[key]`) controls for currently active status keys.
+
+Free-form values such as custom formats, raw colors/styles, numeric values outside the shown presets, and inactive extension keys remain JSON-only.
 
 Useful slash-command shortcuts:
 
@@ -144,6 +153,9 @@ Useful slash-command shortcuts:
 /zentui copy-friendly enable
 /zentui copy-friendly disable
 /zentui copy-friendly toggle
+/zentui viewport-indicators enable
+/zentui viewport-indicators disable
+/zentui viewport-indicators toggle
 /zentui fixed-editor enable
 /zentui fixed-editor disable
 /zentui fixed-editor toggle
@@ -157,6 +169,9 @@ Default config values — copy this and change any value you want:
 {
 	"projectRefreshIntervalMs": 30000,
 	"footerFormat": "",
+	"responsiveFooter": true,
+	"compactFooterFormat": "$cwd$wrap(in $session_name)$wrap(on $git_branch) $git_status$wrap$context$wrap_sep$tokens",
+	"compactFooterMaxLines": 2,
 	"editorMetadataFormat": "$model  $provider(  $thinking)",
 	"separator": "pipe",
 	"contextStyle": "text",
@@ -235,7 +250,8 @@ Default config values — copy this and change any value you want:
 	"features": {
 		"editor": true,
 		"statusLine": true,
-		"copyFriendly": false
+		"copyFriendly": false,
+		"viewportIndicators": true
 	},
 	"footerSegments": {
 		"cwd": true,
@@ -282,18 +298,21 @@ Default config values — copy this and change any value you want:
 - `contextStyle`: `text` (default), `gauge`, or `text+gauge` for the context segment. Context usage refreshes during assistant streaming; token and cost totals remain canonical and finalize at turn boundaries.
 - `editorModelLabel`: controls the model shown in the editor frame. `id` (default) shows the model id; `name` shows the model's display name (including custom `name` values set in `models.json`), falling back to the id when no name is set.
 - `editorMetadataFormat`: JSON-only template for the left side of the editor metadata row. Missing, non-string, or empty values restore the default `$model  $provider(  $thinking)` layout; non-empty strings, including whitespace-only strings, are preserved. See [Editor Metadata Format](#editor-metadata-format) below.
-- `separator`: controls the default footer layout and extension-status connectors: `pipe` (default, ` | `), `dot` (` · `), `chevron` (` › `), or `none` (one space). Cycle it from the `/zentui` **Layout** tab. This selects the separator glyph; `colors.separator` controls its color. Custom `footerFormat` literals and `$sep` keep their existing behavior.
+- `separator`: controls the default footer layout and extension-status connectors: `pipe` (default, ` | `), `dot` (` · `), `chevron` (` › `), or `none` (one space). Cycle it from the `/zentui` **Appearance** tab. This selects the separator glyph; `colors.separator` controls its color. Custom `footerFormat` literals and `$sep` keep their existing behavior.
 - `contextThresholds`: `{ warning, error }` percentages (default `70` / `90`) that select contextNormal / contextWarning / contextError colors.
-- `pathDisplay`: controls how the cwd/`$cwd` path is shown. `mode` is `basename` (default, last segment only) or `full` (path with home contracted to `~`). In `full` mode, `depth` keeps only the last N trailing directories (`0` = entire path after `~`, max `5`); when parents are dropped the path is prefixed with `…/` (Starship-style). The `/zentui` **Layout** tab cycles path mode and path depth (`0`–`5`; depth is ignored for basename). Example: `~/Projects/foo/bar` with `depth: 2` → `…/foo/bar`.
-- `gitBranch.maxLength`: visible width of the built-in branch name and `$git_branch` / `$branch`. The default `full` preserves the complete name; any positive integer uses that width including the trailing `…`. `/zentui` **Layout** cycles `full`, `10`, `20`, `30`, `40`, and `50`; custom positive integers can be set in JSON.
+- `pathDisplay`: controls how the cwd/`$cwd` path is shown. `mode` is `basename` (default, last segment only) or `full` (path with home contracted to `~`). In `full` mode, `depth` keeps only the last N trailing directories (`0` = entire path after `~`, max `5`); when parents are dropped the path is prefixed with `…/` (Starship-style). The `/zentui` **Footer** tab cycles path mode and path depth (`0`–`5`; depth is ignored for basename). Example: `~/Projects/foo/bar` with `depth: 2` → `…/foo/bar`.
+- `gitBranch.maxLength`: visible width of the built-in branch name and `$git_branch` / `$branch`. The default `full` preserves the complete name; any positive integer uses that width including the trailing `…`. `/zentui` **Git** cycles `full`, `10`, `20`, `30`, `40`, and `50`; custom positive integers can be set in JSON.
 - `icons`: every shown icon key is configurable; omit any key to use the Zentui default. `icons.mode` is `auto` | `nerd` | `ascii` (default `auto`, same glyphs as nerd). ASCII mode swaps in plain fallbacks for statusline icons and runtime symbols — useful without a Nerd Font. Custom per-icon strings always win over mode defaults. Custom `icons.os` always wins; when left at the mode default, Zentui maps the OS icon by platform. `rail` sets the vertical glyph drawn as the left rail of the active editor frame and previous user messages when `copyFriendly` is disabled (default `│`; any single Unicode vertical or block glyph). `editorPrompt` controls an optional copy-friendly editor prompt glyph; the default is `""` so copy-friendly mode stays rail-free.
 - `colorSources`: `theme` maps styles through Pi theme tokens; `terminal` emits terminal colors. `/zentui` switches these sources; manual JSON controls specific style values.
-- `features`: `editor` enables Zentui's custom editor, selector borders, and previous-message chrome. `statusLine` enables Zentui's custom footer/status line. `copyFriendly` hides editor and previous-message rail glyphs so native terminal selection copies less chrome. All three can be changed from `/zentui` or direct slash-command arguments.
-- `footerSegments`: show or hide individual built-in footer segments (`cwd`, `sessionName`, `gitBranch`, `gitStatus`, `gitCounts`, `gitCommit`, `gitMetrics`, `runtime`, `packageVersion`, `sessionDuration`, `username`, `time`, `os`, `context`, `tokens`, `cost`). Toggle them from the `Built-in segments` tab in `/zentui`.
-- `footerFormat`: optional Starship-style template string that fully controls the footer layout. When set, it overrides `footerSegments`. See [Footer Format Template](#footer-format-template) below. The `/zentui` **Layout** tab configures context style, separator, path display mode/depth, branch length, and icon mode; set or clear custom formats with `/zentui format`.
+- `features`: `editor` enables Zentui's custom editor, selector borders, and previous-message chrome. `statusLine` enables Zentui's custom footer/status line. `copyFriendly` hides editor and previous-message rail glyphs so native terminal selection copies less chrome. `viewportIndicators` preserves Pi's native `↑ N more` / `↓ N more` wrapped-row counts in Zentui's editor borders (default `true`). All four can be changed from `/zentui` or direct slash-command arguments.
+- `footerSegments`: show or hide individual built-in footer segments (`cwd`, `sessionName`, `gitBranch`, `gitStatus`, `gitCounts`, `gitCommit`, `gitMetrics`, `runtime`, `packageVersion`, `sessionDuration`, `username`, `time`, `os`, `context`, `tokens`, `cost`). Toggle non-Git segments from **Segments** and Git segments from **Git** in `/zentui`.
+- `footerFormat`: optional Starship-style template string that fully controls the footer layout. When set, it overrides `footerSegments`. See [Footer Format Template](#footer-format-template) below. The `/zentui` **Footer** tab configures responsive behavior, compact rows, context style, and path display mode/depth; **Appearance** configures separator and icon mode; **Git** configures branch length; set or clear custom formats with `/zentui format`.
+- `responsiveFooter`: enabled by default. Zentui keeps the current aligned one-row footer while every settings-resolved left/middle/right zone fits without layout truncation. Otherwise it tries two complete left-aligned rows, preferring `left` / `middle right` and then `left middle` / `right`. Only when neither split fits does it use `compactFooterFormat`. Set `false` to restore the legacy one-row fitting behavior. Selection uses measured terminal-cell width, not fixed device breakpoints.
+- `compactFooterFormat`: JSON-only template used by the compact stage. The default keeps cwd, session name, git branch/status, context, and abbreviated token/cache metrics. A top-level `$wrap` is an automatic wrap opportunity: one space on the same row or no space at a row break. `$wrap_sep` is the same kind of boundary but renders the styled ` | ` divider only when its adjacent chunks share a row. Nested uses of either boundary remain empty variables. `$fill` is ignored. A standalone `$extensions` chunk inserts active non-`off` extension statuses in left/middle/right placement order; embedded uses render empty. Custom `footerFormat` values use this built-in compact fallback unless this key is also customized.
+- `compactFooterMaxLines`: `1`, `2`, `3`, or `"unlimited"` (default `2`). Finite limits crop remaining chunks with exactly one trailing `…`. Compact cwd always uses basename mode; cwd/session/branch chunks target half the available row width before final ANSI-aware clamping. `/zentui` exposes the responsive toggle and row limit, while compact format editing remains JSON-only. Pi supplies footer width but no supported viewport-height budget, so `"unlimited"` is explicit.
 - `gitCommit`: Starship [`git_commit`](https://starship.rs/config/#git-commit)-style options for the `gitCommit` footer segment. `hashLength` (default `7`, clamped to `4`–`40`) controls the short-hash display length. `onlyDetached` (default `true`) shows the hash mainly on detached HEAD. `showTag` (default `true`) appends an exact-match tag (`git describe --tags --exact-match HEAD`). The tag probe piggybacks on the existing git refresh — it only runs when both the segment and `showTag` are on, and misses/failures degrade silently.
 - `gitMetrics`: Starship [`git_metrics`](https://starship.rs/config/#git-metrics)-style options for the `gitMetrics` footer segment. Uses `git diff HEAD --numstat` (staged + unstaged combined — the Starship “total dirty” view) to show aggregate `+added −deleted` line counts. `onlyNonzero` (default `true`) omits each zero component independently and hides the segment entirely at `0/0`. `ignoreSubmodules` (default `false`) adds `--ignore-submodules=all`. The numstat diff piggybacks on the existing git refresh and uses a hard 2s timeout; a metrics-only failure degrades silently without discarding fresh branch/status data. On very large monorepos the diff may lag or be omitted on timeout.
-- `extensionStatuses`: controls third-party statuses published by other Pi extensions through `ctx.ui.setStatus()`. `defaultPlacement` and each `placements` value can be `off`, `left`, `middle`, or `right`. The `Extension segments` tab in `/zentui` lists only statuses that are currently active.
+- `extensionStatuses`: controls third-party statuses published by other Pi extensions through `ctx.ui.setStatus()`. `defaultPlacement` and each `placements` value can be `off`, `left`, `middle`, or `right`. The **Extensions** tab in `/zentui` lists only statuses that are currently active. `defaultPlacement` applies only when a status key has no entry in `placements`; keyed overrides always win.
 - The shown `editor*` values match the default `theme` source. Omit those keys to keep Zentui's source-aware defaults when switching between `theme` and `terminal`.
 - `editorAccent` styles the active editor rail and previous user-message rail when `features.copyFriendly` is disabled.
 - `editorPrompt` styles the copy-friendly editor prompt glyph. Omit it to use `editorAccent`, then the default accent fallback.

package/extensions/zentui/config.ts

@@ -33,6 +33,10 @@ export type { IconMode } from "./icons";
 export type ContextStyle = "text" | "gauge" | "text+gauge";
 export type SeparatorStyle = "pipe" | "dot" | "chevron" | "none";
 export type ModelLabelSource = "id" | "name";
+export type CompactFooterMaxLines = 1 | 2 | 3 | "unlimited";
+
+export const DEFAULT_COMPACT_FOOTER_FORMAT =
+	"$cwd$wrap(in $session_name)$wrap(on $git_branch) $git_status$wrap$context$wrap_sep$tokens";
 
 export type ContextThresholds = {
 	warning: number;
@@ -63,6 +67,7 @@ export type UiFeaturesConfig = {
 	editor: boolean;
 	statusLine: boolean;
 	copyFriendly: boolean;
+	viewportIndicators: boolean;
 };
 
 export type FooterSegmentsConfig = {
@@ -127,6 +132,9 @@ export const DEFAULT_EDITOR_METADATA_FORMAT = "$model  $provider(  $thinking)";
 export type PolishedTuiConfig = {
 	projectRefreshIntervalMs: number;
 	footerFormat: string;
+	responsiveFooter: boolean;
+	compactFooterFormat: string;
+	compactFooterMaxLines: CompactFooterMaxLines;
 	editorMetadataFormat: string;
 	separator: SeparatorStyle;
 	contextStyle: ContextStyle;
@@ -225,6 +233,9 @@ export const configPath = join(getAgentDir(), "zentui.json");
 export const defaultConfig: PolishedTuiConfig = {
 	projectRefreshIntervalMs: DEFAULT_PROJECT_REFRESH_INTERVAL_MS,
 	footerFormat: "",
+	responsiveFooter: true,
+	compactFooterFormat: DEFAULT_COMPACT_FOOTER_FORMAT,
+	compactFooterMaxLines: 2,
 	editorMetadataFormat: DEFAULT_EDITOR_METADATA_FORMAT,
 	separator: "pipe",
 	contextStyle: "text",
@@ -267,6 +278,7 @@ export const defaultConfig: PolishedTuiConfig = {
 		editor: true,
 		statusLine: true,
 		copyFriendly: false,
+		viewportIndicators: true,
 	},
 	footerSegments: {
 		cwd: true,
@@ -399,6 +411,10 @@ function stringValue(record: Record<string, unknown>, key: string): string | und
 	return typeof value === "string" ? value : undefined;
 }
 
+function parseCompactFooterMaxLines(value: unknown): CompactFooterMaxLines {
+	return value === 1 || value === 2 || value === 3 || value === "unlimited" ? value : 2;
+}
+
 function colorValue(record: Record<string, unknown>, key: string): string | undefined {
 	const value = stringValue(record, key);
 	return value !== undefined && isSupportedColorSpec(value) ? value : undefined;
@@ -493,6 +509,7 @@ function normalizeUiFeatures(record: Record<string, unknown>): UiFeaturesConfig
 		editor: booleanValue(record, "editor"),
 		statusLine: booleanValue(record, "statusLine"),
 		copyFriendly: booleanValue(record, "copyFriendly"),
+		viewportIndicators: booleanValue(record, "viewportIndicators"),
 	};
 }
 
@@ -605,7 +622,12 @@ function isColorSourceKey(value: string): value is keyof ColorSourcesConfig {
 }
 
 function isUiFeatureKey(value: string): value is keyof UiFeaturesConfig {
-	return value === "editor" || value === "statusLine" || value === "copyFriendly";
+	return (
+		value === "editor" ||
+		value === "statusLine" ||
+		value === "copyFriendly" ||
+		value === "viewportIndicators"
+	);
 }
 
 function isFooterSegmentKey(value: string): value is keyof FooterSegmentsConfig {
@@ -773,9 +795,19 @@ export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 		? normalizeFixedEditorConfig(config.fixedEditor as Record<string, unknown>)
 		: defaultConfig.fixedEditor;
 	const editorMetadataFormat = stringValue(config, "editorMetadataFormat");
+	const compactFooterFormat = stringValue(config, "compactFooterFormat");
 	return {
 		projectRefreshIntervalMs: parseProjectRefreshIntervalMs(config.projectRefreshIntervalMs),
 		footerFormat: stringValue(config, "footerFormat") ?? "",
+		responsiveFooter:
+			typeof config.responsiveFooter === "boolean"
+				? config.responsiveFooter
+				: defaultConfig.responsiveFooter,
+		compactFooterFormat:
+			compactFooterFormat && compactFooterFormat.length > 0
+				? compactFooterFormat
+				: DEFAULT_COMPACT_FOOTER_FORMAT,
+		compactFooterMaxLines: parseCompactFooterMaxLines(config.compactFooterMaxLines),
 		editorMetadataFormat:
 			editorMetadataFormat && editorMetadataFormat.length > 0
 				? editorMetadataFormat
@@ -879,6 +911,25 @@ export function saveFooterFormatPatch(value: string, path = configPath): Polishe
 	});
 }
 
+export function saveResponsiveFooterPatch(
+	patch: Partial<
+		Pick<PolishedTuiConfig, "responsiveFooter" | "compactFooterFormat" | "compactFooterMaxLines">
+	>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		if (typeof patch.responsiveFooter === "boolean") {
+			record.responsiveFooter = patch.responsiveFooter;
+		}
+		if (typeof patch.compactFooterFormat === "string") {
+			record.compactFooterFormat = patch.compactFooterFormat;
+		}
+		if (patch.compactFooterMaxLines !== undefined) {
+			record.compactFooterMaxLines = parseCompactFooterMaxLines(patch.compactFooterMaxLines);
+		}
+	});
+}
+
 export function saveIconsModePatch(mode: IconMode, path = configPath): PolishedTuiConfig {
 	return mutateConfig(path, (record) => {
 		const existing = isRecord(record.icons) ? { ...(record.icons as Record<string, unknown>) } : {};
@@ -947,6 +998,62 @@ export function saveGitBranchPatch(
 	});
 }
 
+export function saveEditorModelLabel(
+	value: ModelLabelSource,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		record.editorModelLabel = parseEditorModelLabel(value);
+	});
+}
+
+export function saveGitCommitPatch(
+	patch: Partial<Pick<GitCommitConfig, "onlyDetached" | "showTag">>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.gitCommit)
+			? { ...(record.gitCommit as Record<string, unknown>) }
+			: {};
+		if (typeof patch.onlyDetached === "boolean") existing.onlyDetached = patch.onlyDetached;
+		if (typeof patch.showTag === "boolean") existing.showTag = patch.showTag;
+		record.gitCommit = existing;
+	});
+}
+
+export function saveGitMetricsPatch(
+	patch: Partial<GitMetricsConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.gitMetrics)
+			? { ...(record.gitMetrics as Record<string, unknown>) }
+			: {};
+		if (typeof patch.onlyNonzero === "boolean") existing.onlyNonzero = patch.onlyNonzero;
+		if (typeof patch.ignoreSubmodules === "boolean") {
+			existing.ignoreSubmodules = patch.ignoreSubmodules;
+		}
+		record.gitMetrics = existing;
+	});
+}
+
+export function saveExtensionStatusDefaultPlacement(
+	placement: ExtensionStatusPlacement,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.extensionStatuses)
+			? { ...(record.extensionStatuses as Record<string, unknown>) }
+			: {};
+		record.extensionStatuses = {
+			...existing,
+			defaultPlacement: isExtensionStatusPlacement(placement)
+				? placement
+				: defaultConfig.extensionStatuses.defaultPlacement,
+		};
+	});
+}
+
 export function saveExtensionStatusPlacement(
 	key: string,
 	placement: ExtensionStatusPlacement,

package/extensions/zentui/footer-format.ts

@@ -13,6 +13,12 @@ export type FormatToken =
 	| { kind: "fill" }
 	| { kind: "group"; tokens: FormatToken[] };
 
+export type CompactBoundaryKind = "space" | "separator";
+
+export type CompactFormatChunk =
+	| { kind: "tokens"; tokens: FormatToken[]; boundary: CompactBoundaryKind }
+	| { kind: "extensions"; boundary: CompactBoundaryKind };
+
 const TOKEN_REGEX = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}|\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
 
 /**
@@ -151,6 +157,85 @@ export function renderFormatSplit(
 	};
 }
 
+export function compileCompactFormat(tokens: FormatToken[]): CompactFormatChunk[] {
+	const chunks: CompactFormatChunk[] = [];
+	let current: FormatToken[] = [];
+	let incomingBoundary: CompactBoundaryKind = "space";
+
+	const flush = () => {
+		const normalized = trimBoundaryWhitespace(current);
+		current = [];
+		if (normalized.length === 0) return;
+		if (
+			normalized.length === 1 &&
+			normalized[0]?.kind === "var" &&
+			normalized[0].name === "extensions"
+		) {
+			chunks.push({ kind: "extensions", boundary: incomingBoundary });
+			return;
+		}
+		chunks.push({ kind: "tokens", tokens: normalized, boundary: incomingBoundary });
+	};
+
+	for (const token of tokens) {
+		if (token.kind === "var" && (token.name === "wrap" || token.name === "wrap_sep")) {
+			flush();
+			incomingBoundary = token.name === "wrap_sep" ? "separator" : "space";
+			continue;
+		}
+		if (token.kind === "fill") continue;
+		current.push(token);
+	}
+	flush();
+	return chunks;
+}
+
+function trimBoundaryWhitespace(tokens: FormatToken[]): FormatToken[] {
+	const result = tokens.map((token) => (token.kind === "text" ? { ...token } : token));
+	while (result[0]?.kind === "text") {
+		result[0].value = result[0].value.replace(/^\s+/, "");
+		if (result[0].value) break;
+		result.shift();
+	}
+	while (result.at(-1)?.kind === "text") {
+		const last = result.at(-1);
+		if (last?.kind !== "text") break;
+		last.value = last.value.replace(/\s+$/, "");
+		if (last.value) break;
+		result.pop();
+	}
+	return result;
+}
+
+export function renderFormatTokens(
+	tokens: FormatToken[],
+	renderVariable: (name: string) => string,
+): string {
+	return renderTokenSlice(tokens, 0, tokens.length, renderVariable);
+}
+
+export function collectFooterFormatReferences(
+	tokens: FormatToken[],
+	aliases: Record<string, string> = {},
+): Set<string> {
+	const references = new Set<string>();
+	const visit = (items: FormatToken[]) => {
+		for (const token of items) {
+			if (token.kind === "group") {
+				visit(token.tokens);
+				continue;
+			}
+			if (token.kind !== "var") continue;
+			const canonical = aliases[token.name] ?? token.name;
+			if (canonical !== "wrap" && canonical !== "wrap_sep" && canonical !== "extensions") {
+				references.add(canonical);
+			}
+		}
+	};
+	visit(tokens);
+	return references;
+}
+
 function findTopLevelFillIndices(tokens: FormatToken[]): number[] {
 	const fillIndices: number[] = [];
 	for (let index = 0; index < tokens.length; index++) {

package/extensions/zentui/footer-layout.ts

@@ -0,0 +1,122 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { CompactFooterMaxLines } from "./config";
+import type { CompactBoundaryKind } from "./footer-format";
+
+export type FooterZones = {
+	left: string;
+	middle: string;
+	right: string;
+};
+
+export function fullFooterFitsAligned(zones: FooterZones, innerWidth: number): boolean {
+	const leftWidth = visibleWidth(zones.left);
+	const middleWidth = visibleWidth(zones.middle);
+	const rightWidth = visibleWidth(zones.right);
+	if (middleWidth === 0) {
+		return leftWidth + rightWidth + (leftWidth > 0 && rightWidth > 0 ? 1 : 0) <= innerWidth;
+	}
+
+	const gapWidth = innerWidth - leftWidth - rightWidth;
+	if (gapWidth < middleWidth) return false;
+	const leftPadding = Math.floor((gapWidth - middleWidth) / 2);
+	const rightPadding = gapWidth - middleWidth - leftPadding;
+	return (leftWidth === 0 || leftPadding >= 1) && (rightWidth === 0 || rightPadding >= 1);
+}
+
+function joinZones(parts: string[]): string {
+	return parts.filter(Boolean).join(" ");
+}
+
+function validRows(rows: string[], innerWidth: number): string[] | undefined {
+	const nonEmpty = rows.filter(Boolean);
+	if (nonEmpty.length === 0 || nonEmpty.length > 2) return undefined;
+	return nonEmpty.every((row) => visibleWidth(row) <= innerWidth) ? nonEmpty : undefined;
+}
+
+/** Prefer project identity alone, with middle/right status on the second row. */
+export function reflowFullFooter(zones: FooterZones, innerWidth: number): string[] | undefined {
+	const preferred = validRows([zones.left, joinZones([zones.middle, zones.right])], innerWidth);
+	if (preferred) return preferred;
+	return validRows([joinZones([zones.left, zones.middle]), zones.right], innerWidth);
+}
+
+export function compactChunkBudget(innerWidth: number): number {
+	return Math.max(8, Math.floor((innerWidth - 1) / 2));
+}
+
+export type CompactLayoutChunk = {
+	text: string;
+	boundary: CompactBoundaryKind;
+};
+
+type PackedRow = {
+	text: string;
+	endsWithRendererEllipsis: boolean;
+};
+
+function fitChunk(chunk: string, innerWidth: number): PackedRow {
+	if (visibleWidth(chunk) <= innerWidth) {
+		return { text: chunk, endsWithRendererEllipsis: false };
+	}
+	return {
+		text: truncateToWidth(chunk, innerWidth, "…"),
+		endsWithRendererEllipsis: true,
+	};
+}
+
+function appendOmissionMarker(row: PackedRow, innerWidth: number): PackedRow {
+	if (row.endsWithRendererEllipsis) return row;
+	if (innerWidth <= 1) return { text: "…", endsWithRendererEllipsis: true };
+	return {
+		text: `${truncateToWidth(row.text, innerWidth - 1, "")}…`,
+		endsWithRendererEllipsis: true,
+	};
+}
+
+export function packCompactChunks(
+	chunks: CompactLayoutChunk[],
+	innerWidth: number,
+	maxLines: CompactFooterMaxLines,
+	separator: string,
+): string[] {
+	if (innerWidth <= 0) return [""];
+	const content = chunks
+		.map((chunk) => ({ ...chunk, text: chunk.text.trim() }))
+		.filter((chunk) => chunk.text.length > 0);
+	if (content.length === 0) return [""];
+
+	const finiteLimit = maxLines === "unlimited" ? Number.POSITIVE_INFINITY : maxLines;
+	const rows: PackedRow[] = [];
+	let current: PackedRow | undefined;
+	let omitted = false;
+
+	for (const chunk of content) {
+		const fitted = fitChunk(chunk.text, innerWidth);
+		if (!current) {
+			current = fitted;
+			continue;
+		}
+
+		const join = chunk.boundary === "separator" ? separator : " ";
+		const candidate = `${current.text}${join}${fitted.text}`;
+		if (visibleWidth(candidate) <= innerWidth) {
+			current = {
+				text: candidate,
+				endsWithRendererEllipsis: fitted.endsWithRendererEllipsis,
+			};
+			continue;
+		}
+
+		if (rows.length + 1 < finiteLimit) {
+			rows.push(current);
+			current = fitted;
+			continue;
+		}
+
+		omitted = true;
+		break;
+	}
+
+	if (current) rows.push(omitted ? appendOmissionMarker(current, innerWidth) : current);
+	return rows.map((row) => truncateToWidth(row.text, innerWidth, ""));
+}