pi-zentui 0.4.0 → 0.5.0

package/README.md

@@ -129,7 +129,7 @@ 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 four sections. Use `Tab` and `Shift+Tab` to switch between `Coloring`, `Features`, `Built-in segments`, and `Extension segments`.
+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`.
 
 Useful slash-command shortcuts:
 
@@ -153,7 +153,13 @@ Default config values — copy this and change any value you want:
 {
 	"projectRefreshIntervalMs": 30000,
 	"footerFormat": "",
+	"contextStyle": "text",
+	"contextThresholds": {
+		"warning": 70,
+		"error": 90
+	},
 	"icons": {
+		"mode": "auto",
 		"cwd": "󰝰",
 		"git": "",
 		"ahead": "↑",
@@ -234,13 +240,15 @@ Default config values — copy this and change any value you want:
 }
 ```
 
-- Style values can be Starship/terminal strings (`bold purple`, `fg:202`, `#89b4fa`, `bg:blue fg:bright-green`) or Pi theme tokens (`accent`, `borderMuted`, `thinkingHigh`).
-- `projectRefreshIntervalMs`: project status polling interval; `0` disables polling.
-- `icons`: every shown icon key is configurable; omit any key to use the Zentui default. `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.
+- Style values can be Starship/terminal strings (`bold purple`, `fg:202`, `#89b` / `#89b4fa`, `bg:blue fg:bright-green`) or Pi theme tokens (`accent`, `borderMuted`, `thinkingHigh`). Short `#rgb` hex values expand to `#rrggbb`.
+- `projectRefreshIntervalMs`: project status polling interval; `0` disables polling. Values `1..4999` clamp up to `5000` (minimum 5s); invalid/non-finite values fall back to `30000`.
+- `contextStyle`: `text` (default), `gauge`, or `text+gauge` for the context segment.
+- `contextThresholds`: `{ warning, error }` percentages (default `70` / `90`) that select contextNormal / contextWarning / contextError colors.
+- `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`, `gitBranch`, `gitStatus`, `gitCounts`, `runtime`, `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.
+- `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 and icon mode; set or clear custom formats with `/zentui format`.
 - `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.
 - 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.
@@ -252,13 +260,13 @@ Tip: when using copy-friendly mode, setting Pi's `editorPaddingX` to `1` in `~/.
 
 ## Footer Format Template
 
-For full control, set a Starship-style `footerFormat` template string. It supports `$variable` and `${variable}` tokens plus a special `$fill` token that splits the line into left and right zones. When set, it overrides the built-in `footerSegments` layout; when empty or omitted, the segment layout above is used.
+For full control, set a Starship-style `footerFormat` template string. It supports `$variable` and `${variable}` tokens, a special `$fill` token that splits the line into left and right zones, and conditional groups `( ... )` that drop entirely when every nested variable is empty. When set, it overrides the built-in `footerSegments` layout; when empty or omitted, the segment layout above is used.
 
 A second `$fill` creates a **centered middle zone** — content between the two fills is true-centered (`floor((gap - middle) / 2)`), just like third-party statuses placed `middle`.
 
 ```json
 {
-	"footerFormat": "$os $username $cwd on branch $git_branch$git_status using $runtime $fill $context | $tokens | $cost $time"
+	"footerFormat": "$os $username $cwd( on $git_branch)( $git_status)( via $runtime)$fill($context)($sep$tokens)($sep$cost)($sep$time)"
 }
 ```
 
@@ -272,20 +280,22 @@ Center the branch between directory and cost:
 
 ### Variables
 
-| Token               | Aliases      | Renders                   |
-| ------------------- | ------------ | ------------------------- |
-| `$cwd`              | `$directory` | current directory         |
-| `$git_branch`       | `$branch`    | git branch with icon      |
-| `$git_status`       | `$status`    | `[!?↑]` status block      |
-| `$runtime`          |              | runtime icon + version    |
-| `$session_duration` | `$duration`  | session running time      |
-| `$username`         |              | `user@host`               |
-| `$os`               |              | operating-system icon     |
-| `$time`             |              | current time `HH:MM`      |
-| `$context`          |              | context usage             |
-| `$tokens`           |              | input/output token counts |
-| `$cost`             |              | session cost              |
-| `$fill`             | —            | special: splits zones     |
+| Token               | Aliases      | Renders                                          |
+| ------------------- | ------------ | ------------------------------------------------ |
+| `$cwd`              | `$directory` | current directory                                |
+| `$git_branch`       | `$branch`    | git branch with icon                             |
+| `$git_status`       | `$status`    | `[!?↑]` status block                             |
+| `$git_state`        | `$state`     | `REBASING` / `MERGING` / … (optional `n/m`)      |
+| `$runtime`          |              | runtime icon + version                           |
+| `$session_duration` | `$duration`  | session running time                             |
+| `$username`         |              | `user@host`                                      |
+| `$os`               |              | operating-system icon                            |
+| `$time`             |              | current time `HH:MM`                             |
+| `$context`          |              | context usage (text and/or gauge via config)     |
+| `$tokens`           |              | input/output token counts                        |
+| `$cost`             |              | session cost                                     |
+| `$sep`              | `$separator` | themed ` | ` using `colors.separator`            |
+| `$fill`             | —            | special: splits zones                            |
 
 ### `$fill` behavior
 
@@ -298,13 +308,14 @@ Center the branch between directory and cost:
 
 - Literal text (`on branch`, `using`, `\|`, spaces) is rendered verbatim — you control all spacing.
 - Each variable renders its core value only (no `on`/`via` prefixes); add those words as literal text.
+- Conditional groups: wrap optional pieces in parentheses, e.g. `$cwd( on $git_branch)($git_status)$fill($context)`. If every `$var` inside a group is empty, the whole group (including its literals) is dropped.
 - Unknown `$variables` render empty.
 - Set or clear at runtime: `/zentui format "<template>"` and `/zentui format clear`.
 
 ## Requirements
 
 - [Pi](https://pi.dev) coding agent 0.79 or newer
-- A [Nerd Font](https://www.nerdfonts.com/) for icons
+- A [Nerd Font](https://www.nerdfonts.com/) for icons (or set `icons.mode` to `"ascii"`)
 
 ## Development
 

package/extensions/zentui/config.ts

@@ -1,10 +1,27 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	ICON_GLYPH_KEYS,
+	type IconGlyphs,
+	type IconMode,
+	NERD_DEFAULT_ICONS,
+	normalizeIconMode,
+	type ResolvedIcons,
+	resolveConfiguredIcons,
+} from "./icons";
 import { isSupportedColorSpec } from "./style";
 
 export type ColorSpec = string;
 export type ColorSource = "theme" | "terminal";
+export type { IconMode } from "./icons";
+
+export type ContextStyle = "text" | "gauge" | "text+gauge";
+
+export type ContextThresholds = {
+	warning: number;
+	error: number;
+};
 
 export type ColorSourcesConfig = {
 	starship: ColorSource;
@@ -50,27 +67,9 @@ const MIN_PROJECT_REFRESH_INTERVAL_MS = 5_000;
 export type PolishedTuiConfig = {
 	projectRefreshIntervalMs: number;
 	footerFormat: string;
-	icons: {
-		cwd: string;
-		git: string;
-		ahead: string;
-		behind: string;
-		diverged: string;
-		conflicted: string;
-		untracked: string;
-		stashed: string;
-		modified: string;
-		staged: string;
-		renamed: string;
-		deleted: string;
-		typechanged: string;
-		cacheHit: string;
-		editorPrompt: string;
-		rail: string;
-		username: string;
-		time: string;
-		os: string;
-	};
+	contextStyle: ContextStyle;
+	contextThresholds: ContextThresholds;
+	icons: ResolvedIcons;
 	colors: {
 		cwd: ColorSpec;
 		gitBranch: ColorSpec;
@@ -113,6 +112,7 @@ export const FOOTER_FORMAT_VARIABLES = [
 	"cwd",
 	"git_branch",
 	"git_status",
+	"git_state",
 	"runtime",
 	"session_duration",
 	"username",
@@ -121,6 +121,7 @@ export const FOOTER_FORMAT_VARIABLES = [
 	"context",
 	"tokens",
 	"cost",
+	"sep",
 ] as const;
 
 /**
@@ -131,7 +132,9 @@ export const FOOTER_FORMAT_ALIASES: Record<string, string> = {
 	directory: "cwd",
 	branch: "git_branch",
 	status: "git_status",
+	state: "git_state",
 	duration: "session_duration",
+	separator: "sep",
 };
 
 export const configPath = join(getAgentDir(), "zentui.json");
@@ -139,26 +142,11 @@ export const configPath = join(getAgentDir(), "zentui.json");
 export const defaultConfig: PolishedTuiConfig = {
 	projectRefreshIntervalMs: DEFAULT_PROJECT_REFRESH_INTERVAL_MS,
 	footerFormat: "",
+	contextStyle: "text",
+	contextThresholds: { warning: 70, error: 90 },
 	icons: {
-		cwd: "󰝰",
-		git: "",
-		ahead: "↑",
-		behind: "↓",
-		diverged: "⇕",
-		conflicted: "=",
-		untracked: "?",
-		stashed: "$",
-		modified: "!",
-		staged: "+",
-		renamed: "»",
-		deleted: "✘",
-		typechanged: "T",
-		cacheHit: "󰆼",
-		editorPrompt: "",
-		rail: "│",
-		username: "",
-		time: "",
-		os: "",
+		mode: "auto",
+		...NERD_DEFAULT_ICONS,
 	},
 	colors: {
 		cwd: "bold cyan",
@@ -208,27 +196,6 @@ export const defaultConfig: PolishedTuiConfig = {
 	},
 };
 
-const iconKeys = [
-	"cwd",
-	"git",
-	"ahead",
-	"behind",
-	"diverged",
-	"conflicted",
-	"untracked",
-	"stashed",
-	"modified",
-	"staged",
-	"renamed",
-	"deleted",
-	"typechanged",
-	"cacheHit",
-	"editorPrompt",
-	"username",
-	"time",
-	"os",
-] as const satisfies readonly (keyof PolishedTuiConfig["icons"])[];
-
 type ConfigRecord = Record<string, unknown>;
 
 function isRecord(value: unknown): value is ConfigRecord {
@@ -238,17 +205,43 @@ function isRecord(value: unknown): value is ConfigRecord {
 function parseProjectRefreshIntervalMs(value: unknown): number {
 	if (value === 0) return 0;
 	if (typeof value !== "number" || !Number.isFinite(value)) {
-		return defaultConfig.projectRefreshIntervalMs;
+		return DEFAULT_PROJECT_REFRESH_INTERVAL_MS;
 	}
 
 	const interval = Math.round(value);
-	return interval >= MIN_PROJECT_REFRESH_INTERVAL_MS
-		? interval
-		: defaultConfig.projectRefreshIntervalMs;
+	if (interval <= 0) return 0;
+	return Math.max(MIN_PROJECT_REFRESH_INTERVAL_MS, interval);
 }
 
-function railValue(value: unknown): string {
-	return typeof value === "string" && value.trim().length > 0 ? value : defaultConfig.icons.rail;
+function clampPercent(value: number): number {
+	return Math.max(0, Math.min(100, value));
+}
+
+function parseContextStyle(value: unknown): ContextStyle {
+	if (value === "text" || value === "gauge" || value === "text+gauge") return value;
+	return defaultConfig.contextStyle;
+}
+
+function parseContextThresholds(value: unknown): ContextThresholds {
+	const defaults = defaultConfig.contextThresholds;
+	if (!isRecord(value)) return { ...defaults };
+
+	const warningRaw = value.warning;
+	const errorRaw = value.error;
+	let warning =
+		typeof warningRaw === "number" && Number.isFinite(warningRaw)
+			? clampPercent(Math.round(warningRaw))
+			: defaults.warning;
+	let error =
+		typeof errorRaw === "number" && Number.isFinite(errorRaw)
+			? clampPercent(Math.round(errorRaw))
+			: defaults.error;
+	if (error < warning) {
+		const swapped = warning;
+		warning = error;
+		error = swapped;
+	}
+	return { warning, error };
 }
 
 function stringValue(record: Record<string, unknown>, key: string): string | undefined {
@@ -292,13 +285,13 @@ function definedColors(
 	) as Partial<PolishedTuiConfig["colors"]>;
 }
 
-function normalizeIcons(record: Record<string, unknown>): Partial<PolishedTuiConfig["icons"]> {
+function normalizeIconOverrides(record: Record<string, unknown>): Partial<IconGlyphs> {
 	return Object.fromEntries(
-		iconKeys.flatMap((key) => {
+		ICON_GLYPH_KEYS.flatMap((key) => {
 			const value = stringValue(record, key);
 			return value === undefined ? [] : [[key, value]];
 		}),
-	) as Partial<PolishedTuiConfig["icons"]>;
+	) as Partial<IconGlyphs>;
 }
 
 function normalizeColors(record: Record<string, unknown>): Partial<PolishedTuiConfig["colors"]> {
@@ -473,7 +466,8 @@ export function ensureConfigExists(): void {
 export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 	const config = isRecord(parsed) ? parsed : {};
 	const iconsRecord = isRecord(config.icons) ? (config.icons as Record<string, unknown>) : {};
-	const icons = normalizeIcons(iconsRecord);
+	const iconMode = normalizeIconMode(iconsRecord.mode);
+	const iconOverrides = normalizeIconOverrides(iconsRecord);
 	const colors = isRecord(config.colors)
 		? normalizeColors(config.colors as Record<string, unknown>)
 		: {};
@@ -492,11 +486,9 @@ export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 	return {
 		projectRefreshIntervalMs: parseProjectRefreshIntervalMs(config.projectRefreshIntervalMs),
 		footerFormat: stringValue(config, "footerFormat") ?? "",
-		icons: {
-			...defaultConfig.icons,
-			...icons,
-			rail: railValue(iconsRecord.rail),
-		},
+		contextStyle: parseContextStyle(config.contextStyle),
+		contextThresholds: parseContextThresholds(config.contextThresholds),
+		icons: resolveConfiguredIcons(iconMode, iconOverrides),
 		colors: {
 			...defaultConfig.colors,
 			...colors,
@@ -590,6 +582,40 @@ export function saveFooterFormatPatch(value: string, path = configPath): Polishe
 	return mergeConfig(record);
 }
 
+export function saveIconsModePatch(mode: IconMode, path = configPath): PolishedTuiConfig {
+	const record = readConfigRecord(path);
+	const existing = isRecord(record.icons) ? { ...(record.icons as Record<string, unknown>) } : {};
+	record.icons = {
+		...existing,
+		mode: normalizeIconMode(mode),
+	};
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+	return mergeConfig(record);
+}
+
+export function saveContextStylePatch(style: ContextStyle, path = configPath): PolishedTuiConfig {
+	const record = readConfigRecord(path);
+	record.contextStyle = parseContextStyle(style);
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+	return mergeConfig(record);
+}
+
+export function saveContextThresholdsPatch(
+	thresholds: Partial<ContextThresholds>,
+	path = configPath,
+): PolishedTuiConfig {
+	const record = readConfigRecord(path);
+	const existing = isRecord(record.contextThresholds)
+		? { ...(record.contextThresholds as Record<string, unknown>) }
+		: {};
+	record.contextThresholds = {
+		...existing,
+		...thresholds,
+	};
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+	return mergeConfig(record);
+}
+
 export function saveExtensionStatusPlacement(
 	key: string,
 	placement: ExtensionStatusPlacement,

package/extensions/zentui/footer-format.ts

@@ -2,46 +2,98 @@
  * Starship-style footer format string parser and renderer.
  *
  * Pure module (no TUI/config imports) so it is fully unit-testable.
+ *
+ * Supports conditional groups: `( ... )` is dropped when every nested
+ * variable (and nested group) renders empty.
  */
 
 export type FormatToken =
 	| { kind: "text"; value: string }
 	| { kind: "var"; name: string }
-	| { kind: "fill" };
+	| { kind: "fill" }
+	| { kind: "group"; tokens: FormatToken[] };
 
 const TOKEN_REGEX = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}|\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
 
 /**
- * Tokenize a format string into text/var/fill tokens.
+ * Tokenize a format string into text/var/fill/group tokens.
  *
  * `$name` and `${name}` both produce a variable token. A variable named
- * `fill` becomes a fill token instead. Text between/around variables is
- * preserved exactly (including spaces). Empty input produces an empty array.
+ * `fill` becomes a fill token instead. Parentheses form conditional groups
+ * that drop entirely when all nested vars are empty.
  */
 export function parseFooterFormat(format: string): FormatToken[] {
 	if (!format) return [];
+	return parseTokenSlice(format, 0, format.length, true).tokens;
+}
 
+function parseTokenSlice(
+	format: string,
+	start: number,
+	end: number,
+	topLevel = false,
+): { tokens: FormatToken[]; nextIndex: number } {
 	const tokens: FormatToken[] = [];
-	let lastIndex = 0;
+	let index = start;
+	let textStart = start;
+
+	const flushText = (until: number) => {
+		if (until > textStart) {
+			tokens.push({ kind: "text", value: format.slice(textStart, until) });
+		}
+	};
 
-	for (const match of format.matchAll(TOKEN_REGEX)) {
-		if (match.index !== undefined && match.index > lastIndex) {
-			tokens.push({ kind: "text", value: format.slice(lastIndex, match.index) });
+	while (index < end) {
+		const ch = format[index];
+
+		if (ch === "(") {
+			flushText(index);
+			const nested = parseTokenSlice(format, index + 1, end, false);
+			tokens.push({ kind: "group", tokens: nested.tokens });
+			index = nested.nextIndex;
+			textStart = index;
+			continue;
 		}
-		const name = match[1] ?? match[2];
-		if (name === "fill") {
-			tokens.push({ kind: "fill" });
-		} else {
-			tokens.push({ kind: "var", name });
+
+		if (ch === ")") {
+			// Nested groups close on `)`. Unmatched top-level `)` is literal text so
+			// trailing tokens like `$cwd) $tokens` are not discarded.
+			if (topLevel) {
+				index += 1;
+				continue;
+			}
+			flushText(index);
+			return { tokens, nextIndex: index + 1 };
 		}
-		lastIndex = (match.index ?? 0) + match[0].length;
-	}
 
-	if (lastIndex < format.length) {
-		tokens.push({ kind: "text", value: format.slice(lastIndex) });
+		if (ch === "$") {
+			TOKEN_REGEX.lastIndex = index;
+			const match = TOKEN_REGEX.exec(format);
+			if (match && match.index === index && match.index < end) {
+				const full = match[0];
+				const matchEnd = match.index + full.length;
+				if (matchEnd > end) {
+					index += 1;
+					continue;
+				}
+				flushText(index);
+				const name = match[1] ?? match[2] ?? "";
+				if (name === "fill") {
+					tokens.push({ kind: "fill" });
+				} else {
+					tokens.push({ kind: "var", name });
+				}
+				index = matchEnd;
+				textStart = index;
+				continue;
+			}
+		}
+
+		index += 1;
 	}
 
-	return tokens;
+	flushText(end);
+	return { tokens, nextIndex: end };
 }
 
 /**
@@ -53,6 +105,7 @@ export function parseFooterFormat(format: string): FormatToken[] {
  *   (centered by the caller via the existing middle-zone logic), after the
  *   second → `right`.
  * - Additional fills beyond the first two are ignored.
+ * - `$fill` inside a group is ignored (renders empty).
  *
  * Text tokens contribute their `value` verbatim (unstyled/plain); var tokens
  * contribute `renderVariable(name)` (already styled by caller). No automatic
@@ -62,10 +115,7 @@ export function renderFormatSplit(
 	tokens: FormatToken[],
 	renderVariable: (name: string) => string,
 ): { left: string; middle: string; right: string } {
-	const fillIndices: number[] = [];
-	for (let index = 0; index < tokens.length; index++) {
-		if (tokens[index]?.kind === "fill") fillIndices.push(index);
-	}
+	const fillIndices = findTopLevelFillIndices(tokens);
 
 	if (fillIndices.length === 0) {
 		return {
@@ -101,6 +151,14 @@ export function renderFormatSplit(
 	};
 }
 
+function findTopLevelFillIndices(tokens: FormatToken[]): number[] {
+	const fillIndices: number[] = [];
+	for (let index = 0; index < tokens.length; index++) {
+		if (tokens[index]?.kind === "fill") fillIndices.push(index);
+	}
+	return fillIndices;
+}
+
 function renderTokenSlice(
 	tokens: FormatToken[],
 	start: number,
@@ -111,11 +169,111 @@ function renderTokenSlice(
 	for (let i = start; i < end; i++) {
 		const token = tokens[i];
 		if (!token) continue;
-		if (token.kind === "text") {
-			result += token.value;
-		} else if (token.kind === "var") {
-			result += renderVariable(token.name);
+		result += renderToken(token, renderVariable);
+	}
+	return result;
+}
+
+function renderToken(token: FormatToken, renderVariable: (name: string) => string): string {
+	if (token.kind === "text") return token.value;
+	if (token.kind === "var") return renderVariable(token.name);
+	if (token.kind === "fill") return "";
+	// group
+	const rendered = token.tokens.map((child) => renderToken(child, renderVariable)).join("");
+	if (isGroupEmpty(token, renderVariable)) return "";
+	return rendered;
+}
+
+/**
+ * Separator vars only style gaps between content; they must not keep a group
+ * alive when every real content var is empty (e.g. `($sep$tokens)` drops if
+ * tokens is empty).
+ */
+const NON_CONTENT_VARS = new Set(["sep", "separator"]);
+
+/**
+ * A group is empty iff every content var leaf is empty and every nested group
+ * is empty. Text-only groups (no vars) always show. `$sep` / `$separator` are
+ * ignored for emptiness so orphan themed pipes do not force a group to render.
+ */
+function isGroupEmpty(
+	group: FormatToken & { kind: "group" },
+	renderVariable: (name: string) => string,
+): boolean {
+	let sawContentVarOrGroup = false;
+	for (const child of group.tokens) {
+		if (child.kind === "var") {
+			if (NON_CONTENT_VARS.has(child.name)) continue;
+			sawContentVarOrGroup = true;
+			if (renderVariable(child.name) !== "") return false;
+		} else if (child.kind === "group") {
+			sawContentVarOrGroup = true;
+			if (!isGroupEmpty(child, renderVariable)) return false;
+		}
+	}
+	// Text-only groups (or groups with only $sep) are shown only when no content vars.
+	// Groups that only contain $sep still count as empty so they drop.
+	return sawContentVarOrGroup || groupOnlyNonContentVars(group);
+}
+
+function groupOnlyNonContentVars(group: FormatToken & { kind: "group" }): boolean {
+	let sawSep = false;
+	for (const child of group.tokens) {
+		if (child.kind === "text") {
+			if (child.value.trim() !== "") return false;
+			continue;
+		}
+		if (child.kind === "var") {
+			if (!NON_CONTENT_VARS.has(child.name)) return false;
+			sawSep = true;
+			continue;
 		}
+		if (child.kind === "group") return false;
+		if (child.kind === "fill") continue;
 	}
+	return sawSep;
+}
+
+/** One optional SGR sequence (`\x1b[…m`). */
+const ANSI_ONE_SRC = "\u001b\\[[0-9;]*m";
+
+/**
+ * One ` | ` separator unit, plain or with a single ANSI wrapper on either side
+ * of the spaces/pipe (matches `renderStyle(..., " | ")` output).
+ */
+const SEP_UNIT_SRC = `(?:${ANSI_ONE_SRC})?\\s+\\|\\s+(?:${ANSI_ONE_SRC})?`;
+
+/**
+ * Join non-empty parts with a separator (segment-mode style).
+ * Useful when building right-side metrics without orphan pipes.
+ */
+export function joinNonEmpty(parts: string[], separator: string): string {
+	return parts.filter(Boolean).join(separator);
+}
+
+/**
+ * Tidy a rendered format left/middle/right slice:
+ * - collapse repeated pipe separators (plain or simple ANSI-wrapped) into one
+ * - strip leading/trailing pipe separators
+ * - strip leading/trailing whitespace
+ * - drop slices that are only ANSI / whitespace after cleanup
+ */
+export function stripOrphanSeparators(rendered: string): string {
+	if (!rendered) return rendered;
+
+	// Collapse consecutive separator units, keeping the first (preserves themed color).
+	const consecutive = new RegExp(`(${SEP_UNIT_SRC})(?:${SEP_UNIT_SRC})+`, "g");
+	let result = rendered.replace(consecutive, "$1");
+
+	// Strip leading / trailing separator units.
+	result = result.replace(new RegExp(`^(?:${SEP_UNIT_SRC})+`), "");
+	result = result.replace(new RegExp(`(?:${SEP_UNIT_SRC})+$`), "");
+
+	// Strip leading / trailing plain whitespace left by empty groups.
+	result = result.replace(/^\s+/, "").replace(/\s+$/, "");
+
+	// Pure ANSI (or empty) leftovers are not useful content.
+	if (result.replace(new RegExp(ANSI_ONE_SRC, "g"), "").trim() === "") return "";
+
 	return result;
 }