@xzzpig/pi-starline 0.3.0 → 0.4.1

package/README.md

@@ -30,7 +30,8 @@ pieces of one product, not a theme:
 - Built-in footer segments can be shown or hidden individually from `/starline`
 - Fully custom Starship-style layout via a `footerFormat` template string — see [Footer Format Template](https://github.com/Andy8647/pi-starline/blob/main/docs/configuration.md#footer-format-template)
 - Third-party Pi extension statuses from `ctx.ui.setStatus()` can be shown on the left,
-  middle, or right side, or hidden per status key from `/starline`
+  middle, or right side of the footer, on the editor's metadata row, or hidden per
+  status key from `/starline`
 
 ### Editor (Opencode-inspired)
 

package/extensions/starline/config.ts

@@ -150,7 +150,15 @@ export function migrateFixedEditorKeys(raw: Record<string, unknown>): {
 	return { config: { ...rest, mouse }, migrated: true };
 }
 
-export type ExtensionStatusPlacement = "off" | "left" | "middle" | "right";
+/**
+ * Where a third-party status is drawn.
+ *
+ * `editor` is the right-hand side of the editor's metadata row, alongside the
+ * vim-mode label and the copy/paste hints — not the footer. It needs Starline's
+ * own footer installed to have data at all, because the status map only reaches
+ * the extension through the footer factory.
+ */
+export type ExtensionStatusPlacement = "off" | "left" | "middle" | "right" | "editor";
 export type ExtensionStatusColorMode = "themed" | "original";
 
 /**
@@ -756,7 +764,13 @@ function normalizeGitMetricsConfig(record: Record<string, unknown>): GitMetricsC
 }
 
 export function isExtensionStatusPlacement(value: unknown): value is ExtensionStatusPlacement {
-	return value === "off" || value === "left" || value === "middle" || value === "right";
+	return (
+		value === "off" ||
+		value === "left" ||
+		value === "middle" ||
+		value === "right" ||
+		value === "editor"
+	);
 }
 
 export function isExtensionStatusColorMode(value: unknown): value is ExtensionStatusColorMode {
@@ -940,7 +954,10 @@ function writeConfigAtomically(path: string, record: ConfigRecord, mode?: number
 		if (file !== undefined) {
 			try {
 				closeSync(file);
-			} catch {}
+			} catch {
+				// Best-effort close during error cleanup; the outer catch
+				// already reports the primary failure.
+			}
 		}
 		try {
 			unlinkSync(tempPath);

package/extensions/starline/extension-status.ts

@@ -17,6 +17,7 @@ export type ExtensionStatusSegmentsByPlacement = {
 	left: ExtensionStatusSegment[];
 	middle: ExtensionStatusSegment[];
 	right: ExtensionStatusSegment[];
+	editor: ExtensionStatusSegment[];
 };
 
 const safeSgrPattern = /\x1b\[[0-9;:]*m/g;
@@ -65,6 +66,7 @@ export function collectExtensionStatusSegments(
 		left: [],
 		middle: [],
 		right: [],
+		editor: [],
 	};
 
 	for (const [key, value] of statuses.entries()) {
@@ -84,5 +86,6 @@ export function collectExtensionStatusSegments(
 	segments.left.sort(compareKeys);
 	segments.middle.sort(compareKeys);
 	segments.right.sort(compareKeys);
+	segments.editor.sort(compareKeys);
 	return segments;
 }

package/extensions/starline/index.ts

@@ -5,7 +5,6 @@ import type {
 	Theme,
 } from "@earendil-works/pi-coding-agent";
 import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
-import type { MouseEventsApi } from "@xzzpig/pi-mouse-events/api";
 import {
 	type ColorSourcesConfig,
 	type ContextStyle,
@@ -324,6 +323,7 @@ export default function (pi: ExtensionAPI) {
 					sessionName: ctx.sessionManager.getSessionName() ?? "",
 				}),
 				getThinkingLevel,
+				() => getActiveExtensionStatuses(),
 			);
 			applyPasteCollapse(editor);
 			// Nothing on Pi's renderer points at the live editor, and the
@@ -357,6 +357,7 @@ export default function (pi: ExtensionAPI) {
 					sessionName: ctx.sessionManager.getSessionName() ?? "",
 				}),
 				getThinkingLevel,
+				() => getActiveExtensionStatuses(),
 			);
 			// Two references, because these are two different objects here: the
 			// wrapper is what gets mounted and hit-tested, while the draft's

package/extensions/starline/mouse/api-consumer.ts

@@ -25,7 +25,14 @@ import type { MouseEventsApi } from "@xzzpig/pi-mouse-events/api";
 const MOUSE_EVENTS_API_KEY = Symbol.for("pi-mouse-events.api.v1");
 
 export function getMouseEventsApi(): MouseEventsApi | undefined {
-	return (globalThis as Record<symbol, unknown>)[MOUSE_EVENTS_API_KEY] as
+	const candidate = (globalThis as Record<symbol, unknown>)[MOUSE_EVENTS_API_KEY] as
 		| MouseEventsApi
 		| undefined;
+	// The symbol key pins the contract name, not its shape: reject an object
+	// from a different contract major so callers never dereference a
+	// mismatched surface (the key is only bumped together with the version).
+	if (!candidate || candidate.version !== 1) {
+		return undefined;
+	}
+	return candidate;
 }

package/extensions/starline/mouse/index.ts

@@ -686,8 +686,8 @@ function expandClickTarget(
  * a non-empty `pressedUrl` means Pi is about to open a link — the box stays
  * as it is and the release goes through unconsumed.
  */
-function pressedUrlAt(receiver: MouseCapableReceiver): unknown {
-	return (receiver as { pressedUrl?: unknown }).pressedUrl;
+function pressedUrlAt(receiver: MouseCapableReceiver): string | undefined {
+	return (receiver as { pressedUrl?: unknown }).pressedUrl as string | undefined;
 }
 
 /**

package/extensions/starline/settings-command.ts

@@ -42,6 +42,7 @@ const extensionStatusPlacementValues: ExtensionStatusPlacement[] = [
 	"left",
 	"middle",
 	"right",
+	"editor",
 ];
 const extensionStatusColorModeValues: ExtensionStatusColorMode[] = ["themed", "original"];
 const contextStyleValues: ContextStyle[] = ["text", "gauge", "text+gauge"];

package/extensions/starline/ui.ts

@@ -11,6 +11,7 @@ import {
 import type { PolishedTuiConfig } from "./config";
 import { applyEditorCursorStyleToLines } from "./editor-cursor";
 import { renderEditorMetadataFormat } from "./editor-metadata-format";
+import { collectExtensionStatusSegments } from "./extension-status";
 import { activeSelectionHintText, externalEditorHintText } from "./mouse";
 import { composeHints } from "./mouse/hint";
 import { pasteExpandHintText } from "./paste-collapse";
@@ -85,6 +86,8 @@ type PolishedFrameOptions = {
 	modelMeta: EditorMeta;
 	thinkingLevel: string | undefined;
 	rightStatus?: string;
+	/** Third-party statuses placed on the editor row (`placement: "editor"`). */
+	editorStatus?: string;
 	splitBaseFrame?: (lines: string[]) => PolishedFrameSplit | undefined;
 };
 
@@ -132,7 +135,8 @@ function getEditorChromeWidths(config: PolishedTuiConfig, uiTheme: Theme, reset:
 }
 
 /**
- * The right side of the metadata row: vim mode, the paste-expand hint, or both.
+ * The right side of the metadata row: vim mode, third-party statuses placed
+ * there, and the paste/selection hints.
  *
  * The hint used to live on the editor's bottom border, drawn there by the fixed
  * editor's compositor. Pi 0.84 supersedes the fixed editor, so the hint needs a
@@ -140,8 +144,15 @@ function getEditorChromeWidths(config: PolishedTuiConfig, uiTheme: Theme, reset:
  * `isHorizontalBorder` requires an unbroken rule to find the frame again. The
  * metadata row is always rendered, even when `editorMetadataFormat` is blank,
  * so the hint shows up whatever the user has done to that template.
+ *
+ * Hints come last: `composeMetadataLine` truncates this string from the right
+ * when it cannot fit, and the hints are the transient, actionable part.
  */
-function composeRightStatus(vimStatus: string | undefined, uiTheme: Theme): string | undefined {
+function composeRightStatus(
+	vimStatus: string | undefined,
+	editorStatus: string | undefined,
+	uiTheme: Theme,
+): string | undefined {
 	// A live selection hint already spells the external editor out ("N
 	// characters selected, ctrl+x to copy ⋅ ctrl+g to edit in $EDITOR"), so it
 	// takes precedence; the always-on hint only speaks when nothing else does.
@@ -149,9 +160,31 @@ function composeRightStatus(vimStatus: string | undefined, uiTheme: Theme): stri
 		pasteExpandHintText(),
 		activeSelectionHintText() ?? externalEditorHintText(),
 	);
-	if (!hint) return vimStatus;
-	const styled = safeThemeFg(uiTheme, "muted", hint);
-	return vimStatus ? `${vimStatus} ⋅ ${styled}` : styled;
+	const styled = hint ? safeThemeFg(uiTheme, "muted", hint) : undefined;
+	const parts = [vimStatus, editorStatus, styled].filter((part): part is string => Boolean(part));
+	return parts.length > 0 ? parts.join(" ⋅ ") : undefined;
+}
+
+/**
+ * Statuses configured with `placement: "editor"`, joined for the metadata row.
+ *
+ * The row is one muted line like the hints beside it, so the per-status colours
+ * and icons (footer features) are not applied here; `colorMode: "original"`
+ * text keeps whatever the extension already styled it with.
+ */
+function editorStatusText(
+	config: PolishedTuiConfig,
+	uiTheme: Theme,
+	statuses: ReadonlyMap<string, string> | undefined,
+): string | undefined {
+	if (!statuses || statuses.size === 0) return undefined;
+	const segments = collectExtensionStatusSegments(statuses, config).editor;
+	if (segments.length === 0) return undefined;
+	return segments
+		.map((segment) =>
+			segment.colorMode === "original" ? segment.text : safeThemeFg(uiTheme, "muted", segment.text),
+		)
+		.join(" ⋅ ");
 }
 
 function composeMetadataLine(left: string, right: string | undefined, width: number): string {
@@ -280,6 +313,7 @@ function renderPolishedFrame({
 	modelMeta,
 	thinkingLevel,
 	rightStatus,
+	editorStatus,
 	splitBaseFrame,
 }: PolishedFrameOptions): string[] {
 	if (width <= 2) return clampRenderedLines(baseRendered, width);
@@ -330,7 +364,7 @@ function renderPolishedFrame({
 		uiTheme,
 		config,
 	);
-	const status = composeRightStatus(rightStatus, uiTheme);
+	const status = composeRightStatus(rightStatus, editorStatus, uiTheme);
 	const copyFriendlyMeta = composeMetadataLine(meta, status, Math.max(0, width - 1));
 	const railedMeta = composeMetadataLine(meta, status, innerWidth);
 
@@ -381,6 +415,7 @@ export class PolishedEditor extends CustomEditor {
 	private readonly getThinkingLevel: () => string | undefined;
 	private readonly getConfig: () => PolishedTuiConfig;
 	private readonly uiTheme: Theme;
+	private readonly getExtensionStatuses: (() => ReadonlyMap<string, string>) | undefined;
 
 	constructor(
 		tui: TUI,
@@ -390,6 +425,7 @@ export class PolishedEditor extends CustomEditor {
 		getConfig: () => PolishedTuiConfig,
 		getModelMeta: () => EditorMeta,
 		getThinkingLevel: () => string | undefined,
+		getExtensionStatuses?: () => ReadonlyMap<string, string>,
 	) {
 		super(tui, theme, keybindings, { paddingX: 0 });
 		this.borderColor = (text: string) => safeThemeFg(uiTheme, "border", text);
@@ -397,6 +433,7 @@ export class PolishedEditor extends CustomEditor {
 		this.getConfig = getConfig;
 		this.getModelMeta = getModelMeta;
 		this.getThinkingLevel = getThinkingLevel;
+		this.getExtensionStatuses = getExtensionStatuses;
 	}
 
 	render(width: number): string[] {
@@ -412,11 +449,14 @@ export class PolishedEditor extends CustomEditor {
 		const result = renderPolishedFrame({
 			width,
 			baseRendered: rendered,
+			// SAFETY: this PolishedEditor is constructed with the internals the
+			// renderer needs; the widening crosses an interface boundary only.
 			autocompleteSource: this as unknown as AutocompleteEditorInternals,
 			uiTheme: this.uiTheme,
 			config,
 			modelMeta,
 			thinkingLevel: this.getThinkingLevel(),
+			editorStatus: editorStatusText(config, this.uiTheme, this.getExtensionStatuses?.()),
 		});
 		return result;
 	}
@@ -427,6 +467,8 @@ export class PolishedEditor extends CustomEditor {
 }
 // Also resolvable under the pre-rename key, so a pi-zentui wrapper reading a
 // pi-starline-built base still finds the splitter.
+// SAFETY: LEGACY_SPLIT_POLISHED_FRAME is our own Symbol key; the cast only
+// widens the receiver to assign a symbol-keyed method on the prototype.
 (PolishedEditor.prototype as unknown as Record<PropertyKey, unknown>)[LEGACY_SPLIT_POLISHED_FRAME] =
 	PolishedEditor.prototype[SPLIT_POLISHED_FRAME];
 
@@ -437,6 +479,7 @@ export class WrappedPolishedEditor implements EditorComponent {
 		private readonly getConfig: () => PolishedTuiConfig,
 		private readonly getModelMeta: () => EditorMeta,
 		private readonly getThinkingLevel: () => string | undefined,
+		private readonly getExtensionStatuses?: () => ReadonlyMap<string, string>,
 	) {}
 
 	get focused(): boolean {
@@ -534,6 +577,7 @@ export class WrappedPolishedEditor implements EditorComponent {
 			modelMeta,
 			thinkingLevel: this.getThinkingLevel(),
 			rightStatus: vimStatus,
+			editorStatus: editorStatusText(config, this.uiTheme, this.getExtensionStatuses?.()),
 			splitBaseFrame: (
 				this.base[SPLIT_POLISHED_FRAME] ?? this.base[LEGACY_SPLIT_POLISHED_FRAME]
 			)?.bind(this.base),
@@ -588,10 +632,17 @@ export class WrappedPolishedEditor implements EditorComponent {
 		return this.base.getLines?.() ?? this.base.getText().split("\n");
 	}
 
+	// Deliberate pass-through of the base editor's duck-typed contract: Pi
+	// returns a {line, col} cursor object, so narrowing here would assert a
+	// type this wrapper cannot guarantee.
+	// pi-lens-ignore: no-unknown-returns
 	getCursor(): unknown {
 		return this.base.getCursor?.();
 	}
 
+	// Deliberate pass-through of the base editor's duck-typed contract; callers
+	// narrow the value with their own runtime checks.
+	// pi-lens-ignore: no-unknown-returns
 	getMode(): unknown {
 		return this.base.getMode?.();
 	}
@@ -606,6 +657,8 @@ export class WrappedPolishedEditor implements EditorComponent {
 }
 // Also resolvable under the pre-rename key, so a pi-zentui wrapper reading a
 // pi-starline-built base still finds the splitter.
+// SAFETY: LEGACY_SPLIT_POLISHED_FRAME is our own Symbol key; the cast only
+// widens the receiver to assign a symbol-keyed method on the prototype.
 (WrappedPolishedEditor.prototype as unknown as Record<PropertyKey, unknown>)[
 	LEGACY_SPLIT_POLISHED_FRAME
 ] = WrappedPolishedEditor.prototype[SPLIT_POLISHED_FRAME];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzzpig/pi-starline",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A Starship-inspired statusline and Opencode-style TUI for Pi.",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,6 @@
     "@earendil-works/pi-tui": ">=0.84.4",
     "@xzzpig/pi-mouse-events": ">=0.1.0 <2"
   },
-  "peerDependenciesMeta": {
-    "@xzzpig/pi-mouse-events": {
-      "optional": true
-    }
-  },
   "pi": {
     "extensions": [
       "./extensions"
@@ -50,7 +45,12 @@
     "@types/node": "^26.0.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.8",
-    "@xzzpig/pi-mouse-events": "0.1.0"
+    "@xzzpig/pi-mouse-events": "0.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@xzzpig/pi-mouse-events": {
+      "optional": true
+    }
   },
   "scripts": {
     "lint": "biome check .",