pi-zentui 0.6.0 → 0.8.0

package/README.md

@@ -17,11 +17,11 @@ Zentui brings two popular aesthetics to Pi:
 
 ### Footer (Starship-inspired)
 
-- `󰝰 dirname` — current directory with icon (`basename` by default; optional `full` path with directory depth via `pathDisplay`)
+- `dirname` — current directory (`basename` by default; optional `full` path with directory depth via `pathDisplay`)
 - `on  branch` — git branch with icon
 - `[!?↑]` — git status indicators (modified, untracked, ahead/behind, stashed, etc.)
 - `via  v5.5.0` — runtime detection with version and Starship-style Nerd Font runtime/language modules
-- Optional segments (off by default): `user@host`, current time, OS icon, and session duration
+- Optional segments (off by default): `user@host`, current time, OS icon, session duration, and the **project package version** (e.g. `package.json` → `0.6.0`) — distinct from the runtime segment, which shows the installed toolchain
 - Right side shows context usage, token counts, and cost
 - Built-in footer segments can be shown or hidden individually from `/zentui`
 - Fully custom Starship-style layout via a `footerFormat` template string — see [Footer Format Template](#footer-format-template)
@@ -35,6 +35,7 @@ Zentui brings two popular aesthetics to Pi:
 - Configurable model, provider, and thinking-level indicator colors
 - Prompt-box-style user messages matching the ZentUI input chrome
 - Copy-friendly mode hides editor and previous-message rail glyphs so terminal selection copies less chrome
+- **Fixed editor** (experimental, opt-in): Pin the editor and footer at the bottom of the terminal while the transcript scrolls above
 
 ### Git Status Icons
 
@@ -143,6 +144,9 @@ Useful slash-command shortcuts:
 /zentui copy-friendly enable
 /zentui copy-friendly disable
 /zentui copy-friendly toggle
+/zentui fixed-editor enable
+/zentui fixed-editor disable
+/zentui fixed-editor toggle
 /zentui format "$cwd on branch $git_branch$git_status using $runtime $fill $context"
 /zentui format clear
 ```
@@ -164,7 +168,7 @@ Default config values — copy this and change any value you want:
 	},
 	"icons": {
 		"mode": "auto",
-		"cwd": "󰝰",
+		"cwd": "",
 		"git": "",
 		"ahead": "↑",
 		"behind": "↓",
@@ -197,6 +201,10 @@ Default config values — copy this and change any value you want:
 		"separator": "bright-black",
 		"runtimePrefix": "",
 		"sessionDuration": "yellow",
+		"packageVersion": "208",
+		"gitCommit": "bold green",
+		"gitMetricsAdded": "bold green",
+		"gitMetricsDeleted": "bold red",
 		"username": "bold yellow",
 		"time": "bold yellow",
 		"os": "bold white",
@@ -234,12 +242,29 @@ Default config values — copy this and change any value you want:
 		"sessionDuration": false,
 		"username": false,
 		"time": false,
-		"os": false
+		"os": false,
+		"packageVersion": false,
+		"gitCommit": false,
+		"gitMetrics": false
+	},
+	"gitCommit": {
+		"hashLength": 7,
+		"onlyDetached": true,
+		"showTag": true
+	},
+	"gitMetrics": {
+		"onlyNonzero": true,
+		"ignoreSubmodules": false
 	},
 	"extensionStatuses": {
 		"defaultPlacement": "right",
 		"placements": {},
 		"colorModes": {}
+	},
+	"fixedEditor": {
+		"enabled": false,
+		"mouseScroll": true,
+		"copyNotice": true
 	}
 }
 ```
@@ -252,8 +277,10 @@ Default config values — copy this and change any value you want:
 - `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`.
+- `footerSegments`: show or hide individual built-in footer segments (`cwd`, `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, path display mode/depth, and icon mode; set or clear custom formats with `/zentui format`.
+- `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.
 - 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.
@@ -285,22 +312,29 @@ 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                             |
-| `$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                            |
+| 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`)                         |
+| `$git_commit`       | `$commit`    | short commit hash (+ 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 + version                                              |
+| `$package`          |              | project package version, `is <glyph> <version>` (manifest-derived)  |
+| `$package_version`  |              | raw project package version (no icon)                               |
+| `$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
 
@@ -317,9 +351,59 @@ Center the branch between directory and cost:
 - Unknown `$variables` render empty.
 - Set or clear at runtime: `/zentui format "<template>"` and `/zentui format clear`.
 
+## Fixed editor (experimental, opt-in)
+
+The fixed editor pins the Zentui editor and footer at the bottom of the terminal while the transcript scrolls above. This enables composing follow-up messages while referencing earlier conversation history.
+
+### How to enable
+
+```text
+/zentui fixed-editor enable
+```
+
+Or in `~/.pi/agent/zentui.json`:
+
+```json
+{
+	"fixedEditor": {
+		"enabled": true
+	}
+}
+```
+
+### Keyboard controls
+
+| Key | Action |
+| --- | ------ |
+| `PageUp` / `PageDown` | Scroll transcript one viewport up/down |
+| `Ctrl+Shift+↑` / `Ctrl+Shift+↓` | Scroll transcript up/down (Kitty protocol variants supported) |
+| `Enter` | Jump to bottom (and submit message) |
+
+### Mouse scroll (default on)
+
+Mouse wheel scrolling is enabled by default when the fixed editor is on. Disable it via `/zentui` Features or:
+
+```json
+{
+	"fixedEditor": {
+		"enabled": true,
+		"mouseScroll": true
+	}
+}
+```
+
+**Warning**: Mouse scroll enables SGR mouse reporting, which disables native terminal text selection, URL click-through, and tmux/Herdr scrollback for the Pi session. Toggle off if you need those features.
+
+### Conflicts and limitations
+
+- **Incompatible with** `pi-powerline-footer`, `@tifan/pi-fixed-editor`, and `pi-sticky-input`. These packages patch the same Pi TUI internals; only one rendering owner can be active at a time.
+- **Alternate screen**: Uses the terminal's alternate screen buffer. Native scrollback history is not accessible while the fixed editor is active.
+- **Pi version fragility**: Patches internal TUI methods (`doRender`, `render`, `terminal.write`, `terminal.rows`) that may change across Pi versions. If the TUI layout is unsupported, Zentui falls back to normal rendering with a console warning.
+- If your terminal is stuck after a crash, run `reset` or restart the terminal.
+
 ## Requirements
 
-- [Pi](https://pi.dev) coding agent 0.79 or newer
+- [Pi](https://pi.dev) coding agent 0.80 or newer
 - A [Nerd Font](https://www.nerdfonts.com/) for icons (or set `icons.mode` to `"ascii"`)
 
 ## Development

package/extensions/zentui/config.ts

@@ -48,6 +48,8 @@ export type FooterSegmentsConfig = {
 	gitBranch: boolean;
 	gitStatus: boolean;
 	gitCounts: boolean;
+	gitCommit: boolean;
+	gitMetrics: boolean;
 	runtime: boolean;
 	context: boolean;
 	tokens: boolean;
@@ -56,11 +58,37 @@ export type FooterSegmentsConfig = {
 	username: boolean;
 	time: boolean;
 	os: boolean;
+	packageVersion: boolean;
+};
+
+export type FixedEditorConfig = {
+	enabled: boolean;
+	mouseScroll: boolean;
+	copyNotice: boolean;
 };
 
 export type ExtensionStatusPlacement = "off" | "left" | "middle" | "right";
 export type ExtensionStatusColorMode = "zentui" | "original";
 
+/**
+ * Starship `git_commit`-style options.
+ * See https://starship.rs/config/#git-commit
+ */
+export type GitCommitConfig = {
+	hashLength: number;
+	onlyDetached: boolean;
+	showTag: boolean;
+};
+
+/**
+ * Starship `git_metrics`-style options.
+ * See https://starship.rs/config/#git-metrics
+ */
+export type GitMetricsConfig = {
+	onlyNonzero: boolean;
+	ignoreSubmodules: boolean;
+};
+
 const DEFAULT_EXTENSION_STATUS_COLOR_MODE: ExtensionStatusColorMode = "zentui";
 
 export type ExtensionStatusesConfig = {
@@ -92,6 +120,10 @@ export type PolishedTuiConfig = {
 		runtimePrefix: ColorSpec;
 		extensionStatus: ColorSpec;
 		sessionDuration: ColorSpec;
+		packageVersion: ColorSpec;
+		gitCommit: ColorSpec;
+		gitMetricsAdded: ColorSpec;
+		gitMetricsDeleted: ColorSpec;
 		username: ColorSpec;
 		time: ColorSpec;
 		os: ColorSpec;
@@ -110,7 +142,10 @@ export type PolishedTuiConfig = {
 	colorSources: ColorSourcesConfig;
 	features: UiFeaturesConfig;
 	footerSegments: FooterSegmentsConfig;
+	gitCommit: GitCommitConfig;
+	gitMetrics: GitMetricsConfig;
 	extensionStatuses: ExtensionStatusesConfig;
+	fixedEditor: FixedEditorConfig;
 };
 
 /**
@@ -130,6 +165,13 @@ export const FOOTER_FORMAT_VARIABLES = [
 	"context",
 	"tokens",
 	"cost",
+	"package",
+	"package_version",
+	"git_commit",
+	"git_tag",
+	"git_metrics",
+	"git_added",
+	"git_deleted",
 	"sep",
 ] as const;
 
@@ -142,6 +184,8 @@ export const FOOTER_FORMAT_ALIASES: Record<string, string> = {
 	branch: "git_branch",
 	status: "git_status",
 	state: "git_state",
+	commit: "git_commit",
+	tag: "git_tag",
 	duration: "session_duration",
 	separator: "sep",
 };
@@ -171,6 +215,10 @@ export const defaultConfig: PolishedTuiConfig = {
 		runtimePrefix: "",
 		extensionStatus: "bright-black",
 		sessionDuration: "yellow",
+		packageVersion: "208",
+		gitCommit: "bold green",
+		gitMetricsAdded: "bold green",
+		gitMetricsDeleted: "bold red",
 		username: "bold yellow",
 		time: "bold yellow",
 		os: "bold white",
@@ -198,12 +246,29 @@ export const defaultConfig: PolishedTuiConfig = {
 		username: false,
 		time: false,
 		os: false,
+		packageVersion: false,
+		gitCommit: false,
+		gitMetrics: false,
+	},
+	gitCommit: {
+		hashLength: 7,
+		onlyDetached: true,
+		showTag: true,
+	},
+	gitMetrics: {
+		onlyNonzero: true,
+		ignoreSubmodules: false,
 	},
 	extensionStatuses: {
 		defaultPlacement: "right",
 		placements: {},
 		colorModes: {},
 	},
+	fixedEditor: {
+		enabled: false,
+		mouseScroll: true,
+		copyNotice: true,
+	},
 };
 
 type ConfigRecord = Record<string, unknown>;
@@ -330,6 +395,10 @@ function normalizeColors(record: Record<string, unknown>): Partial<PolishedTuiCo
 		runtimePrefix: colorValue(record, "runtimePrefix"),
 		extensionStatus: colorValue(record, "extensionStatus"),
 		sessionDuration: colorValue(record, "sessionDuration"),
+		packageVersion: colorValue(record, "packageVersion"),
+		gitCommit: colorValue(record, "gitCommit"),
+		gitMetricsAdded: colorValue(record, "gitMetricsAdded"),
+		gitMetricsDeleted: colorValue(record, "gitMetricsDeleted"),
 		username: colorValue(record, "username"),
 		time: colorValue(record, "time"),
 		os: colorValue(record, "os"),
@@ -377,6 +446,41 @@ function normalizeFooterSegments(record: Record<string, unknown>): FooterSegment
 		username: footerSegmentValue(record, "username"),
 		time: footerSegmentValue(record, "time"),
 		os: footerSegmentValue(record, "os"),
+		packageVersion: footerSegmentValue(record, "packageVersion"),
+		gitCommit: footerSegmentValue(record, "gitCommit"),
+		gitMetrics: footerSegmentValue(record, "gitMetrics"),
+	};
+}
+
+/** Clamp hashLength to Git's valid abbreviation range [4, 40]. */
+function normalizeGitHashLength(value: unknown): number {
+	const parsed = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(parsed)) return defaultConfig.gitCommit.hashLength;
+	const rounded = Math.round(parsed);
+	return Math.min(40, Math.max(4, rounded));
+}
+
+function normalizeGitCommitConfig(record: Record<string, unknown>): GitCommitConfig {
+	return {
+		hashLength: normalizeGitHashLength(record.hashLength),
+		onlyDetached:
+			typeof record.onlyDetached === "boolean"
+				? record.onlyDetached
+				: defaultConfig.gitCommit.onlyDetached,
+		showTag: typeof record.showTag === "boolean" ? record.showTag : defaultConfig.gitCommit.showTag,
+	};
+}
+
+function normalizeGitMetricsConfig(record: Record<string, unknown>): GitMetricsConfig {
+	return {
+		onlyNonzero:
+			typeof record.onlyNonzero === "boolean"
+				? record.onlyNonzero
+				: defaultConfig.gitMetrics.onlyNonzero,
+		ignoreSubmodules:
+			typeof record.ignoreSubmodules === "boolean"
+				? record.ignoreSubmodules
+				: defaultConfig.gitMetrics.ignoreSubmodules,
 	};
 }
 
@@ -416,6 +520,21 @@ function normalizeExtensionStatuses(record: Record<string, unknown>): ExtensionS
 	};
 }
 
+function normalizeFixedEditorConfig(record: Record<string, unknown>): FixedEditorConfig {
+	return {
+		enabled:
+			typeof record.enabled === "boolean" ? record.enabled : defaultConfig.fixedEditor.enabled,
+		mouseScroll:
+			typeof record.mouseScroll === "boolean"
+				? record.mouseScroll
+				: defaultConfig.fixedEditor.mouseScroll,
+		copyNotice:
+			typeof record.copyNotice === "boolean"
+				? record.copyNotice
+				: defaultConfig.fixedEditor.copyNotice,
+	};
+}
+
 function isColorSourceKey(value: string): value is keyof ColorSourcesConfig {
 	return value === "starship" || value === "editor" || value === "userMessages";
 }
@@ -437,7 +556,10 @@ function isFooterSegmentKey(value: string): value is keyof FooterSegmentsConfig
 		value === "sessionDuration" ||
 		value === "username" ||
 		value === "time" ||
-		value === "os"
+		value === "os" ||
+		value === "packageVersion" ||
+		value === "gitCommit" ||
+		value === "gitMetrics"
 	);
 }
 
@@ -505,6 +627,15 @@ export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 	const extensionStatuses = isRecord(config.extensionStatuses)
 		? normalizeExtensionStatuses(config.extensionStatuses as Record<string, unknown>)
 		: defaultConfig.extensionStatuses;
+	const gitCommit = isRecord(config.gitCommit)
+		? normalizeGitCommitConfig(config.gitCommit as Record<string, unknown>)
+		: defaultConfig.gitCommit;
+	const gitMetrics = isRecord(config.gitMetrics)
+		? normalizeGitMetricsConfig(config.gitMetrics as Record<string, unknown>)
+		: defaultConfig.gitMetrics;
+	const fixedEditor = isRecord(config.fixedEditor)
+		? normalizeFixedEditorConfig(config.fixedEditor as Record<string, unknown>)
+		: defaultConfig.fixedEditor;
 	return {
 		projectRefreshIntervalMs: parseProjectRefreshIntervalMs(config.projectRefreshIntervalMs),
 		footerFormat: stringValue(config, "footerFormat") ?? "",
@@ -519,11 +650,14 @@ export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 		colorSources: { ...colorSources },
 		features: { ...features },
 		footerSegments: { ...footerSegments },
+		gitCommit,
+		gitMetrics,
 		extensionStatuses: {
 			defaultPlacement: extensionStatuses.defaultPlacement,
 			placements: { ...extensionStatuses.placements },
 			colorModes: { ...extensionStatuses.colorModes },
 		},
+		fixedEditor,
 	};
 }
 
@@ -709,3 +843,21 @@ export function saveExtensionStatusColorMode(
 	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
 	return mergeConfig(record);
 }
+
+export function saveFixedEditorPatch(
+	patch: Partial<FixedEditorConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	const record = readConfigRecord(path);
+	const existing = isRecord(record.fixedEditor)
+		? { ...(record.fixedEditor as Record<string, unknown>) }
+		: {};
+	record.fixedEditor = {
+		...existing,
+		...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
+		...(patch.mouseScroll !== undefined ? { mouseScroll: patch.mouseScroll } : {}),
+		...(patch.copyNotice !== undefined ? { copyNotice: patch.copyNotice } : {}),
+	};
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+	return mergeConfig(record);
+}

package/extensions/zentui/fixed-editor/cluster.ts

@@ -0,0 +1,194 @@
+/**
+ * Cluster discovery and rendering for the fixed editor.
+ *
+ * The "cluster" is the set of Pi TUI children around the editor that should be
+ * pinned at the bottom: status container, above-editor widget, editor,
+ * below-editor widget, and footer.
+ *
+ * @internal
+ */
+
+import { CURSOR_MARKER, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { ClusterRender } from "./types";
+
+/** Minimal Component shape needed for rendering. */
+type Renderable = {
+	render(width: number): string[];
+	/** Saved original render when the compositor has patched render → [] */
+	__zentuiOriginalRender?: (width: number) => string[];
+};
+
+/** Minimal Container shape for child scanning. */
+type ContainerLike = Renderable & {
+	children: unknown[];
+};
+
+/** Check if a value is a container-like object (has children + render). */
+function isContainerLike(value: unknown): value is ContainerLike {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		Array.isArray(Reflect.get(value, "children")) &&
+		typeof Reflect.get(value, "render") === "function"
+	);
+}
+
+/** Check if a value looks like an editor component (duck-typed). */
+function isEditorLike(value: unknown): boolean {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "getText") === "function" &&
+		typeof Reflect.get(value, "setText") === "function" &&
+		typeof Reflect.get(value, "handleInput") === "function"
+	);
+}
+
+/**
+ * Find the index in `children` of the container holding the editor.
+ * Prefers the focused component's parent; falls back to scanning for
+ * an editor-like grandchild.
+ */
+export function findEditorContainerIndex(
+	children: unknown[],
+	focusedComponent?: unknown,
+): number | undefined {
+	// Try focused component first.
+	if (focusedComponent && typeof focusedComponent === "object") {
+		const idx = children.findIndex(
+			(c) => isContainerLike(c) && c.children.includes(focusedComponent),
+		);
+		if (idx !== -1) return idx;
+	}
+
+	// Scan for a container with an editor-like child.
+	const idx = children.findIndex(
+		(c) => isContainerLike(c) && c.children.some((gc) => isEditorLike(gc)),
+	);
+	return idx === -1 ? undefined : idx;
+}
+
+/** The 5-component cluster pinned at the bottom. */
+export type FixedCluster = {
+	status: Renderable | null;
+	aboveWidget: Renderable | null;
+	editor: Renderable;
+	belowWidget: Renderable | null;
+	footer: Renderable | null;
+};
+
+/**
+ * Patch a cluster component's render to return [] (hide from transcript).
+ * Saves the original render for cluster painting.
+ */
+export function hideRenderable(component: Renderable | null): void {
+	if (!component || component.__zentuiOriginalRender) return;
+	component.__zentuiOriginalRender = component.render.bind(component);
+	component.render = () => [];
+}
+
+/** Restore a cluster component's original render. */
+export function restoreRenderable(component: Renderable | null): void {
+	if (!component?.__zentuiOriginalRender) return;
+	component.render = component.__zentuiOriginalRender;
+	delete component.__zentuiOriginalRender;
+}
+
+/** Build the cluster from children around the editor index. */
+export function buildCluster(children: unknown[], editorIdx: number): FixedCluster | null {
+	const editor = children[editorIdx];
+	if (!editor || typeof (editor as Renderable).render !== "function") return null;
+	return {
+		status: (children[editorIdx - 2] as Renderable | undefined) ?? null,
+		aboveWidget: (children[editorIdx - 1] as Renderable | undefined) ?? null,
+		editor: editor as Renderable,
+		belowWidget: (children[editorIdx + 1] as Renderable | undefined) ?? null,
+		footer: (children[editorIdx + 2] as Renderable | undefined) ?? null,
+	};
+}
+
+/** Render a component at `width`, using the saved original render if hidden. */
+function renderComponent(component: Renderable | null, width: number): string[] {
+	if (!component) return [];
+	const renderFn = component.__zentuiOriginalRender ?? component.render;
+	const lines = renderFn.call(component, width);
+	// Strip only trailing blank lines — internal blank lines (e.g. editor
+	// padding in copy-friendly mode) must be preserved.
+	let end = lines.length;
+	while (end > 0 && visibleWidth(lines[end - 1]) === 0) end--;
+	return lines.slice(0, Math.max(end, 1));
+}
+
+/**
+ * Cap editor lines to `maxLines`, keeping the cursor row visible.
+ * If the cursor marker is found, the window centers on it; otherwise
+ * the last `maxLines` are kept.
+ */
+export function capEditorLines(lines: string[], maxLines: number): string[] {
+	if (maxLines <= 0) return [];
+	if (lines.length <= maxLines) return lines;
+
+	const cursorRow = lines.findIndex((line) => line.includes(CURSOR_MARKER));
+	if (cursorRow !== -1) {
+		const start = Math.max(0, Math.min(cursorRow - maxLines + 1, lines.length - maxLines));
+		return lines.slice(start, start + maxLines);
+	}
+	return lines.slice(lines.length - maxLines);
+}
+
+function sanitizeLines(lines: string[], width: number): string[] {
+	return lines.map((line) =>
+		visibleWidth(line) > width ? truncateToWidth(line, width, "", true) : line,
+	);
+}
+
+/**
+ * Render the full cluster (status + widgets + editor + footer) and extract
+ * the cursor position from the CURSOR_MARKER.
+ */
+export function renderCluster(
+	cluster: FixedCluster,
+	width: number,
+	maxHeight: number,
+): ClusterRender {
+	const w = Math.max(1, width);
+	const maxRows = Math.max(1, maxHeight - 1);
+
+	const statusLines = sanitizeLines(renderComponent(cluster.status, w), w);
+	const aboveLines = sanitizeLines(renderComponent(cluster.aboveWidget, w), w);
+	const editorSource = sanitizeLines(renderComponent(cluster.editor, w), w);
+	const belowLines = sanitizeLines(renderComponent(cluster.belowWidget, w), w);
+	const footerLines = sanitizeLines(renderComponent(cluster.footer, w), w);
+
+	const editorLines = capEditorLines(editorSource, maxRows);
+	let remaining = maxRows - editorLines.length;
+
+	const footer = footerLines.slice(-remaining);
+	remaining -= footer.length;
+
+	const below = belowLines.slice(-remaining);
+	remaining -= below.length;
+
+	const above = aboveLines.slice(-remaining);
+	remaining -= above.length;
+
+	const status = statusLines.slice(-remaining);
+
+	let allLines = [...status, ...above, ...editorLines, ...below, ...footer];
+
+	// Strip leading blank lines (e.g. empty status line above the editor border).
+	let start = 0;
+	while (start < allLines.length - 1 && visibleWidth(allLines[start]) === 0) start++;
+	allLines = allLines.slice(start);
+
+	let cursor: { row: number; col: number } | null = null;
+	const cleaned = allLines.map((line, row) => {
+		const markerIndex = line.indexOf(CURSOR_MARKER);
+		if (markerIndex === -1) return line;
+		cursor ??= { row, col: visibleWidth(line.slice(0, markerIndex)) };
+		return line.slice(0, markerIndex) + line.slice(markerIndex + CURSOR_MARKER.length);
+	});
+
+	return { lines: cleaned, cursor };
+}