@selesai/code 0.9.14 → 0.10.0

package/dist/extensions/pi-zentui/docs/footer-format.md

@@ -0,0 +1,162 @@
+# Footer format template
+
+[Back to README](../README.md) · [Configuration reference](./configuration.md)
+
+Set `components.footer.styles.starship.format` for complete control over the Starship Footer. The template supports:
+
+- `$variable` and `${variable}` tokens
+- literal text and spaces
+- conditional groups `( ... )` that disappear when every nested variable is empty
+- `$fill` layout boundaries
+
+A custom format overrides `components.footer.styles.starship.segments`. Empty or omitted format uses the segment layout.
+
+## Examples
+
+A complete left/right layout:
+
+```json
+{
+  "components": {
+    "footer": {
+      "styles": {
+        "starship": {
+          "format": "$os $username $cwd($sep$session_name)( on $git_branch)( $git_status)( via $runtime)$fill($context)($sep$tokens)($sep$cost)($sep$time)"
+        }
+      }
+    }
+  }
+}
+```
+
+Center the branch between directory and cost:
+
+```json
+{
+  "components": {
+    "footer": {
+      "styles": {
+        "starship": {
+          "format": "$cwd $fill $git_branch $fill $cost"
+        }
+      }
+    }
+  }
+}
+```
+
+Set or clear the template at runtime:
+
+```text
+/zentui format "$cwd( on $git_branch)($git_status)$fill($context)($sep$tokens)"
+/zentui format clear
+```
+
+The released flat `footerFormat` and `footerSegments` keys remain accepted only as migration input.
+
+## Variables
+
+| Token | Aliases | Renders |
+| --- | --- | --- |
+| `$cwd` | `$directory` | current directory |
+| `$session_name` | | current Pi session name |
+| `$git_branch` | `$branch` | Git branch with icon |
+| `$git_status` | `$status` | `[!?↑]` status block |
+| `$git_state` | `$state` | `REBASING`, `MERGING`, and similar state, with optional `n/m` |
+| `$git_commit` | `$commit` | short commit hash and exact-match tag when present |
+| `$git_tag` | `$tag` | exact-match tag at HEAD |
+| `$git_metrics` | | aggregate line changes `+added −deleted` |
+| `$git_added` | | added line count (`+N`) |
+| `$git_deleted` | | deleted line count (`−N`) |
+| `$runtime` | | runtime icon and version |
+| `$model` | | selected Footer model label |
+| `$provider` | | formatted provider label |
+| `$package` | | project package version as `is <glyph> <version>` |
+| `$package_version` | | raw project package version |
+| `$session_duration` | `$duration` | session running time |
+| `$username` | | `user@host` |
+| `$os` | | operating-system icon |
+| `$time` | | current time `HH:MM` |
+| `$context` | | context usage; finite percentages use one decimal |
+| `$tokens` | | input/output totals and existing cache-hit percentage |
+| `$cache_read` | | cache-read total (`R1.2k`); empty at zero or when unavailable |
+| `$cache_write` | | cache-write total (`W300`); empty at zero or when unavailable |
+| `$cost` | | session cost |
+| `$subscription` | | `(sub)` in subscription mode; otherwise empty |
+| `$auto_compaction` | | `(auto)` when automatic compaction is enabled |
+| `$sep` | `$separator` | themed `|` using `colors.separator` |
+| `$fill` | — | wide-format layout boundary |
+
+Each variable renders its core value without prose prefixes such as `on` or `via`; add those words as literals.
+
+### `$cwd` path modes
+
+`$cwd`, the built-in wide directory segment, and responsive compact/final fallback all use `components.footer.styles.starship.pathDisplay`. Its unchanged default is `{ "mode": "basename", "depth": 0 }`.
+
+- `basename` renders only the current directory name.
+- `full` renders the full path with `~` home abbreviation.
+- Opt-in `repository` excludes the repository directory name: repository root renders `.`, while `/repo/extensions/zentui` renders `extensions/zentui`.
+
+For `full` and `repository`, `depth` keeps the final N components and `0` is unlimited. Repository mode forms the repository-relative path first and then applies depth; for example, `/repo/packages/core/src` at depth `2` renders `…/core/src`. Root always remains `.`. Separator normalization matches the existing cwd formatter.
+
+Repository mode recognizes normal repositories and `.git` file worktrees. If the root is missing, stale, unsafe for the current cwd, or unavailable during a cwd/repository transition or failed lookup, `$cwd` silently uses the unlimited `full` path until current root state is safe. This fallback retains `~` abbreviation and never emits a relative path from a stale root.
+
+### Compact-only structural tokens
+
+`components.footer.styles.starship.compactFormat` also supports:
+
+| Token | Behavior |
+| --- | --- |
+| `$wrap` | starts a new compact chunk with a space boundary; the packer keeps it on the current line when it fits or wraps it to the next line |
+| `$wrap_sep` | starts a new compact chunk with the configured `$sep` boundary instead of a plain space |
+| `$extensions` | expands active third-party statuses into independently packable compact chunks, preserving their rendered text and configured color modes |
+
+Example:
+
+```json
+{
+  "components": {
+    "footer": {
+      "styles": {
+        "starship": {
+          "compactFormat": "$cwd$wrap(in $session_name)$wrap(on $git_branch) $git_status$wrap$context$wrap_sep$tokens$wrap_sep$extensions"
+        }
+      }
+    }
+  }
+}
+```
+
+These tokens are structural in compact mode: `$wrap` and `$wrap_sep` render no text themselves, and `$extensions` is empty when no third-party status is active.
+
+## `$fill` behavior
+
+| Count | Layout |
+| ---: | --- |
+| 0 | everything left-aligned |
+| 1 | tokens before are left-aligned; tokens after are right-aligned |
+| 2 | before first is left, between is truly centered, after second is right |
+| 3+ | first two count; extras are ignored |
+
+The centered middle zone uses `floor((gap - middle) / 2)`, matching third-party statuses placed in the middle.
+
+## Conditional groups
+
+Wrap optional content in parentheses:
+
+```text
+$cwd( on $git_branch)($git_status)$fill($context)
+```
+
+If every variable inside a group is empty, the group and its literal text are dropped. `$session_name` is available whenever a custom format is set, independently of segment visibility; use a group such as `($sep$session_name)` so unnamed sessions leave no separator.
+
+## Formatting rules
+
+- Literal text, pipes, and spaces render verbatim; the template owns spacing.
+- `$session_name` is independent of `components.footer.styles.starship.segments.sessionName` in custom formats.
+- Built-in wide layout appends cache totals to Tokens, `(sub)` to Cost, and `(auto)` to Context when available.
+- Custom formats keep `$tokens`, `$cost`, and `$context` backward-compatible. Add `$cache_read`, `$cache_write`, `$subscription`, and `$auto_compaction` explicitly for atomic telemetry.
+- `DEFAULT_COMPACT_FOOTER_FORMAT` omits model/provider and atomic telemetry. Add variables to `components.footer.styles.starship.compactFormat` to opt in at narrow widths. The flat `compactFooterFormat` key remains migration-only input.
+- Auto-compaction settings refresh at the next normal Footer synchronization. Unsupported Pi capabilities or read errors omit optional markers.
+- Unknown variables render empty.
+- `$fill`, `$wrap`, and `$wrap_sep` are structural and never render visible text.

package/dist/extensions/pi-zentui/extensions/zentui/accent-rail-editor.ts

@@ -0,0 +1,99 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+	applyOwnedSurfaceBackground,
+	fillTerminalLine,
+	renderCompletionRows,
+} from "./completion-menu";
+import type { ZentuiConfig } from "./config";
+import { sanitizeEditorMetadataText } from "./editor-metadata-format";
+import { renderStyleForSourceOrFallback, type SourceStyleFallback } from "./style";
+
+export const ACCENT_RAIL_CHROME_WIDTH = 2;
+
+const ACCENT_RAIL_FALLBACK: SourceStyleFallback = {
+	theme: "syntaxNumber",
+	terminal: "fg:215",
+};
+
+export type AccentRailViewport = {
+	above?: string;
+	below?: string;
+};
+
+export type AccentRailEditorFrameOptions = {
+	width: number;
+	editorLines: string[];
+	autocompleteLines?: string[];
+	viewport?: AccentRailViewport;
+	uiTheme: Theme;
+	config: ZentuiConfig;
+};
+
+function clampLines(lines: string[], width: number): string[] {
+	const maxWidth = Math.max(0, width);
+	return lines.map((line) => truncateToWidth(line, maxWidth, ""));
+}
+
+function selectedRail(config: ZentuiConfig): string {
+	const style = config.components.editor.styles["accent-rail"];
+	const fallback = config.icons.mode === "ascii" ? "|" : "▎";
+	const configured = config.icons.mode === "ascii" ? style.asciiRail : style.rail;
+	const sanitized = sanitizeEditorMetadataText(configured);
+	const glyph = truncateToWidth(sanitized, 1, "");
+	return visibleWidth(glyph) === 1 ? glyph : fallback;
+}
+
+function viewportLabel(
+	direction: "above" | "below",
+	count: string | undefined,
+): string | undefined {
+	if (!count || !/^[1-9]\d*$/.test(count)) return undefined;
+	return `${direction === "above" ? "↑" : "↓"} ${count} more`;
+}
+
+/** Pure compact accent-rail composition shared by live rendering and settings previews. */
+export function renderAccentRailEditorFrame({
+	width,
+	editorLines,
+	autocompleteLines = [],
+	viewport = {},
+	uiTheme,
+	config,
+}: AccentRailEditorFrameOptions): string[] {
+	if (width < ACCENT_RAIL_CHROME_WIDTH + 1) {
+		return clampLines([...editorLines, ...autocompleteLines], width);
+	}
+
+	const contentWidth = width - ACCENT_RAIL_CHROME_WIDTH;
+	const rail = renderStyleForSourceOrFallback(
+		uiTheme,
+		config.components.editor.colorSource,
+		config.colors.editorRail,
+		ACCENT_RAIL_FALLBACK,
+		selectedRail(config),
+	);
+	const above = config.components.editor.viewportIndicators
+		? viewportLabel("above", viewport.above)
+		: undefined;
+	const below = config.components.editor.viewportIndicators
+		? viewportLabel("below", viewport.below)
+		: undefined;
+	const rows = [...(above ? [above] : []), ...editorLines, ...(below ? [below] : [])];
+	const transparent = config.components.editor.styles["accent-rail"].transparent;
+	const surface = rows.map((line) => {
+		const railCell = transparent ? rail : applyOwnedSurfaceBackground(uiTheme, rail);
+		const bodyText = ` ${fillTerminalLine(line, contentWidth)}`;
+		const body = transparent ? bodyText : applyOwnedSurfaceBackground(uiTheme, bodyText);
+		return `${railCell}${body}`;
+	});
+	const autocompleteSurface = renderCompletionRows({
+		lines: autocompleteLines,
+		width,
+		theme: uiTheme,
+		selectedPrefix: `${rail} `,
+		ownedBackground: !transparent,
+	});
+
+	return clampLines([...surface, ...autocompleteSurface], width);
+}