@xzzpig/pi-starline 0.5.0 → 0.7.1

package/extensions/starline/working-indicator.ts

@@ -0,0 +1,189 @@
+/**
+ * The status indicator Pi hands to the mounted editor.
+ *
+ * Pi draws a working / retry / compaction status in its own row above the editor
+ * unless the editor opts in with `embedWorkingStatus`; opting in makes the
+ * placement the editor's problem. Starline takes that deal so the plain
+ * `working` spinner can ride in the model pill: same glyph slot, same display
+ * width, no extra row and no pill bar reflow. The plain spinner also carries the
+ * run's elapsed time in the pill, which is the one thing the spinner alone does
+ * not say — and keeps the total there once the run is over.
+ *
+ * Everything that is not a plain spinner (retry, compaction, branch summary)
+ * spells a sentence and carries an interrupt hint, which a pill cannot hold, so
+ * those stay on the editor's top border in Pi's own layout.
+ *
+ * The reference is published by the editor and read by the footer, so it lives
+ * here rather than in either of them.
+ */
+
+import { stripVTControlCharacters } from "node:util";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { PolishedTuiConfig } from "./config";
+import { buildElapsedLabel } from "./format";
+import type { TurnTiming } from "./turn-clock";
+
+/**
+ * Structural twin of Pi's `StatusIndicator`, which the package does not export.
+ *
+ * Both render helpers are optional because they only exist on the Pi versions
+ * that also support embedding. Without them the indicator renders nowhere and
+ * Pi's own row stays the only one, which is the pre-embedding behaviour.
+ */
+export type WorkingIndicator = {
+	/** "working" | "retry" | "compaction" | "branchSummary". */
+	readonly kind?: string;
+	renderInBorder?: (width: number) => string;
+	renderSpinnerInBorder?: (width: number) => string;
+};
+
+let currentIndicator: WorkingIndicator | undefined;
+
+export function setWorkingIndicator(indicator: WorkingIndicator | undefined): void {
+	currentIndicator = indicator;
+}
+
+/**
+ * The model pill exists when the status line is on and `pill.segments` asks for
+ * it. When it does not, the spinner belongs on the editor's top border instead of
+ * vanishing, so the editor asks exactly the question the footer answers.
+ */
+export function footerRendersModel(config: PolishedTuiConfig): boolean {
+	return config.features.statusLine && config.pill.segments.includes("model");
+}
+
+/** A plain spinner, as opposed to a status that has to spell something out. */
+function isSpinnerOnly(indicator: WorkingIndicator): boolean {
+	return indicator.kind === undefined || indicator.kind === "working";
+}
+
+/**
+ * Whether the pill should read as working, which is a wider question than
+ * whether it has a frame: `setWorkingIndicator({ frames: [] })` keeps the run
+ * going with the animation hidden, and the elapsed time is still true then.
+ */
+function isPlainSpinnerWorking(): boolean {
+	const indicator = currentIndicator;
+	return indicator !== undefined && isSpinnerOnly(indicator);
+}
+
+/**
+ * Pi's default frames. Sparse on purpose: each frame inks a few dots, so the
+ * spinner reads as a moving speck.
+ */
+const PI_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * The pill's own frames: the same braille grid, but filled, so the ink covers the
+ * whole cell instead of hugging one corner.
+ *
+ * Pi's sparse set is what makes the spinner look like it sits high above the
+ * model name — the top-left dot lands near the pill's top edge while the pill's
+ * text is optically centred. A filled frame has no such corner bias.
+ */
+const PILL_FRAMES = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+
+/** `icons.mode: "ascii"` exists for terminals without a Nerd Font; braille is no safer. */
+const ASCII_PILL_FRAMES = ["|", "/", "-", "\\"];
+
+/**
+ * Swap Pi's frame for the pill's, keeping Pi's cadence: the frame arrives from the
+ * loader's own tick, so its index in Pi's set is the phase to reuse. Anything the
+ * session customized is passed through untouched.
+ */
+function pillFrame(frame: string, frames: string[]): string {
+	const index = PI_FRAMES.indexOf(frame);
+	if (index < 0) return frame;
+	const scaled = Math.floor((index * frames.length) / PI_FRAMES.length) % frames.length;
+	return frames[scaled] ?? frame;
+}
+
+/** Long statuses still clip, but to what the border can hold rather than to nothing. */
+function borderStatus(indicator: WorkingIndicator, width: number): string | undefined {
+	try {
+		const status = stripVTControlCharacters(
+			indicator.renderInBorder?.(Math.max(1, width)) ?? "",
+		).trim();
+		return visibleWidth(status) > 0 ? status : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The current spinner frame for the footer, or undefined when the pill should
+ * keep its own icon: no indicator, not a plain spinner, a Pi build without the
+ * render helper, or `setWorkingIndicator({ frames: [] })` hiding the animation.
+ *
+ * The frame arrives already coloured (Pi paints it with the editor's border
+ * colour), so the colour is stripped here and the footer paints it like any
+ * other segment text.
+ */
+export function readWorkingFrame(ascii = false): string | undefined {
+	const indicator = currentIndicator;
+	if (!indicator || !isSpinnerOnly(indicator)) return undefined;
+	try {
+		const frame = stripVTControlCharacters(indicator.renderSpinnerInBorder?.(1) ?? "");
+		if (visibleWidth(frame) === 0) return undefined;
+		return pillFrame(frame, ascii ? ASCII_PILL_FRAMES : PILL_FRAMES);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * What the editor's top border has to show, if anything: every status that is
+ * not the pill's spinner, plus the spinner itself when there is no model pill to
+ * put it in.
+ */
+export function workingStatusForBorder(
+	config: PolishedTuiConfig,
+	width: number,
+): string | undefined {
+	const indicator = currentIndicator;
+	if (!indicator) return undefined;
+	if (isSpinnerOnly(indicator) && footerRendersModel(config)) return undefined;
+	return borderStatus(indicator, width);
+}
+
+/**
+ * The model pill's icon slot while the agent works. The spinner takes the icon's
+ * place at the icon's own display width, so the pill never resizes and the pill
+ * bar never reflows. An icon-less pill gains the two cells the spinner needs; a
+ * one-cell icon is swapped in place.
+ */
+export function modelPillIcon(icon: string, frame: string | undefined): string {
+	if (!frame) return icon;
+	const frameWidth = visibleWidth(frame);
+	if (frameWidth === 0) return icon;
+	return `${frame}${" ".repeat(Math.max(0, visibleWidth(icon) - frameWidth))}`;
+}
+
+/**
+ * The model pill's whole label: icon slot, model name, and the run's elapsed
+ * time — ticking while the agent works, frozen at the total once the run ends.
+ *
+ * The time sits after the name rather than before it because the spinner has
+ * already taken the icon's slot: `⣾ claude 12s` reads as one sentence, while a
+ * number between the spinner and the name reads as a second icon.
+ *
+ * Two reasons to keep it in the one pill rather than a segment of its own: a
+ * segment that appears and disappears would slide the rest of the bar sideways
+ * at the start and end of every turn, and "working" and "for how long" are the
+ * same question. Whether the number is still counting is what the icon slot
+ * says — a spinner there means live, the model's own icon means this is the last
+ * run's total.
+ */
+export function modelPillLabel(
+	icon: string,
+	label: string,
+	options: { ascii?: boolean; timing?: TurnTiming } = {},
+): string {
+	if (!label) return "";
+	const iconSlot = modelPillIcon(icon, readWorkingFrame(options.ascii === true));
+	const working = isPlainSpinnerWorking();
+	const timing = options.timing ?? {};
+	const elapsedMs = working ? timing.running : timing.last;
+	const text = elapsedMs === undefined ? label : `${label} ${buildElapsedLabel(elapsedMs)}`;
+	return iconSlot ? `${iconSlot} ${text}` : text;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzzpig/pi-starline",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "description": "A Starship-inspired statusline and Opencode-style TUI for Pi.",
   "type": "module",
   "license": "MIT",
@@ -20,32 +20,37 @@
     "tui"
   ],
   "files": [
-    "extensions"
+    "extensions",
+    "dist",
+    "types",
+    "FORK-CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.86.0 <0.88",
-    "@earendil-works/pi-coding-agent": ">=0.86.0 <0.88",
-    "@earendil-works/pi-tui": ">=0.86.0 <0.88",
+    "@earendil-works/pi-ai": ">=1.0.0 <2",
+    "@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+    "@earendil-works/pi-tui": ">=1.0.0 <2",
     "@xzzpig/pi-mouse-events": ">=0.2.0 <3"
   },
   "pi": {
     "extensions": [
       "./extensions"
     ],
-    "image": "https://raw.githubusercontent.com/Andy8647/pi-starline/main/assets/starline.png"
+    "image": "https://raw.githubusercontent.com/Andy8647/pi-starline/main/assets/cover.png"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
-    "@earendil-works/pi-tui": "^0.87.1",
+    "@biomejs/biome": "^2.6.3",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@types/node": "^26.0.0",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.4.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.8",
-    "@xzzpig/pi-mouse-events": "0.2.0"
+    "@xzzpig/pi-mouse-events": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@xzzpig/pi-mouse-events": {
@@ -55,11 +60,12 @@
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs && biome format --write dist/public.d.ts",
     "test": "vitest run",
     "pi:dev": "${PI_BIN:-/opt/homebrew/bin/pi} --no-extensions -e ./extensions/starline/index.ts",
     "pi:install-local": "${PI_BIN:-/opt/homebrew/bin/pi} install ./ -l",
     "fmt": "biome format --write .",
-    "fmt:check": "biome format --check .",
+    "fmt:check": "biome format .",
     "verify": "npm run lint && npm run typecheck && npm run test",
     "pack:check": "npm pack --dry-run"
   }

package/types/pill-api.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Types for Starline's pill API: make your extension's footer pill clickable and
+ * open Starline's popover with your own content.
+ *
+ * The API is found on `globalThis`, not imported, so an extension can use it
+ * without depending on Starline at runtime. Only these types are imported:
+ *
+ *     import type { PillApi } from "@xzzpig/pi-starline/types/pill-api";
+ *     const api = (globalThis as Record<symbol, unknown>)[
+ *       Symbol.for("pi-starline.pill-api.v1")
+ *     ] as PillApi | undefined;
+ *
+ * Guide and templates: docs/pill-api.md in the pi-starline repository.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Where a pill sits and how it is painted, as the footer last drew it. Pass it
+ * through to `showBubble` untouched; its fields are Starline's to interpret.
+ */
+export type PillAnchor = {
+	/** The pill's segment key; a click on the pill whose bubble is open closes it. */
+	key?: string;
+	/** First column painted in the pill's colour. */
+	startColumn?: number;
+	/** First column after the pill's colour, where its arrow or cap begins. */
+	endColumn?: number;
+	/** Column of the pill's centre on the footer line. */
+	centerColumn: number;
+	/** Width the footer was rendered at, which is the terminal width. */
+	terminalWidth: number;
+	/** Background SGR the pill was painted with. */
+	background: string;
+	/** Foreground SGR of the pill; "" derives a legible one from the background. */
+	foreground: string;
+};
+
+/**
+ * A body line. A plain string is information; an object with `onSelect` is a
+ * target: it renders underlined, the pointer turns into a hand over it, and a
+ * click (or Enter while it is selected) closes the bubble and then runs the
+ * callback.
+ *
+ * `current: true` marks the target that stands for the present state, such as
+ * the active level in a picker: the bubble opens with it selected, so the arrow
+ * keys move from there. At most one should be current; the first one wins.
+ */
+export type PillBubbleLine = string | { text: string; onSelect: () => void; current?: boolean };
+
+export type PillBubbleContent = {
+	/** Bold first line, optional. */
+	title?: string;
+	/** Body lines, wrapped to the bubble. */
+	body: PillBubbleLine[];
+	/** Muted last line, e.g. the key that dismisses it. */
+	hint?: string;
+};
+
+/**
+ * Content, or a function that returns it. A function is called again on every
+ * `refresh()`, which is how a bubble shows numbers that change while it is open.
+ */
+export type PillBubbleSource = PillBubbleContent | (() => PillBubbleContent);
+
+/** The open bubble. Returned by `showBubble` from Starline 0.4; older versions return nothing. */
+export type PillBubbleHandle = {
+	/**
+	 * Read the content again (when it was given as a function) and redraw. The
+	 * bubble widens if a line outgrew it; it never narrows while open. A no-op once
+	 * the bubble is closed, so a timer that fires late is harmless.
+	 */
+	refresh(): void;
+	/** Close the bubble. Safe to call more than once. */
+	close(): void;
+	/** Whether the bubble is still on screen. */
+	isOpen(): boolean;
+	/**
+	 * Run `callback` once the bubble closes, however that happens: Escape, a
+	 * second click on its pill, another bubble replacing it, or `close()`. Stop
+	 * timers here. Runs at once if the bubble is already closed.
+	 */
+	onClose(callback: () => void): void;
+};
+
+export type PillApiContext = {
+	ctx: ExtensionContext;
+	/** The pill that was clicked, or the one the footer last drew for this key. */
+	pill?: PillAnchor;
+	/**
+	 * "click" from the pill, "command" from `/starline <key>`. A bubble's targets
+	 * need a pointer, so an action that offers choices can act directly from the
+	 * command instead. Absent on Starline versions before it was added.
+	 */
+	via?: "click" | "command";
+};
+
+export type PillApiAction = (context: PillApiContext) => void | Promise<void>;
+
+export type PillApi = {
+	version: 1;
+	/**
+	 * Make the pill published under `key` (your `ctx.ui.setStatus` key) clickable.
+	 * Register from `session_start`; a second registration for the same key
+	 * replaces the first. Returns an unregister handle that only removes its own
+	 * registration.
+	 */
+	register(key: string, action: PillApiAction): () => void;
+	/** Open the standard bubble, attached to `pill` when one is known. */
+	showBubble(
+		ctx: ExtensionContext,
+		content: PillBubbleSource,
+		pill?: PillAnchor,
+	): PillBubbleHandle | undefined;
+};

package/extensions/starline/editor-metadata-format.ts

@@ -1,259 +0,0 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { PolishedTuiConfig } from "./config";
-import { type FormatToken, parseFooterFormat } from "./footer-format";
-import { EDITOR_ACCENT_FALLBACK, renderStyleForSourceOrFallback, safeThemeFg } from "./style";
-
-export type EditorMetadataValues = {
-	model: string;
-	modelId: string;
-	modelName: string;
-	provider: string;
-	thinking: string;
-	sessionName: string;
-};
-
-type RenderedTokens = {
-	styled: string;
-	hasDynamic: boolean;
-	hasNonEmptyDynamic: boolean;
-};
-
-const ESC = 0x1b;
-const BEL = 0x07;
-const CAN = 0x18;
-const SUB = 0x1a;
-const C1_DCS = 0x90;
-const C1_CSI = 0x9b;
-const C1_ST = 0x9c;
-const C1_OSC = 0x9d;
-const C1_SOS = 0x98;
-const C1_PM = 0x9e;
-const C1_APC = 0x9f;
-
-function consumeCsi(value: string, start: number): number {
-	for (let index = start; index < value.length; index++) {
-		const code = value.charCodeAt(index);
-		if (code === CAN || code === SUB) return index + 1;
-		if (code >= 0x40 && code <= 0x7e) return index + 1;
-	}
-	return value.length;
-}
-
-function consumeControlString(value: string, start: number, allowBel: boolean): number {
-	for (let index = start; index < value.length; index++) {
-		const code = value.charCodeAt(index);
-		if (code === CAN || code === SUB) return index + 1;
-		if (allowBel && code === BEL) return index + 1;
-		if (code === C1_ST) return index + 1;
-		if (code === ESC && value.charCodeAt(index + 1) === 0x5c) return index + 2;
-	}
-	return value.length;
-}
-
-function consumeEscape(value: string, start: number): number {
-	if (start + 1 >= value.length) return value.length;
-	const next = value.charCodeAt(start + 1);
-	if (next === 0x5b) return consumeCsi(value, start + 2);
-	if (next === 0x5d) return consumeControlString(value, start + 2, true);
-	if (next === 0x50 || next === 0x58 || next === 0x5e || next === 0x5f) {
-		return consumeControlString(value, start + 2, false);
-	}
-
-	let index = start + 1;
-	while (index < value.length) {
-		const code = value.charCodeAt(index);
-		if (code >= 0x20 && code <= 0x2f) {
-			index += 1;
-			continue;
-		}
-		return code >= 0x30 && code <= 0x7e ? index + 1 : index;
-	}
-	return value.length;
-}
-
-function isNormalizedWhitespace(code: number): boolean {
-	return (
-		code === 0x09 ||
-		code === 0x0a ||
-		code === 0x0b ||
-		code === 0x0c ||
-		code === 0x0d ||
-		code === 0x85 ||
-		code === 0x2028 ||
-		code === 0x2029
-	);
-}
-
-export function sanitizeEditorMetadataText(value: string): string {
-	let sanitized = "";
-	for (let index = 0; index < value.length; ) {
-		const code = value.charCodeAt(index);
-		if (code === ESC) {
-			index = consumeEscape(value, index);
-			continue;
-		}
-		if (code === C1_CSI) {
-			index = consumeCsi(value, index + 1);
-			continue;
-		}
-		if (code === C1_OSC) {
-			index = consumeControlString(value, index + 1, true);
-			continue;
-		}
-		if (code === C1_DCS || code === C1_SOS || code === C1_PM || code === C1_APC) {
-			index = consumeControlString(value, index + 1, false);
-			continue;
-		}
-		if (isNormalizedWhitespace(code)) {
-			sanitized += " ";
-			do index += 1;
-			while (index < value.length && isNormalizedWhitespace(value.charCodeAt(index)));
-			continue;
-		}
-		if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
-			index += 1;
-			continue;
-		}
-		sanitized += value[index];
-		index += 1;
-	}
-	return sanitized;
-}
-
-function editorThinkingStyle(config: PolishedTuiConfig, level: string): string | undefined {
-	switch (level.toLowerCase()) {
-		case "minimal":
-			return config.colors.editorThinkingMinimal ?? config.colors.editorThinking;
-		case "low":
-			return config.colors.editorThinkingLow ?? config.colors.editorThinking;
-		case "medium":
-			return config.colors.editorThinkingMedium ?? config.colors.editorThinking;
-		case "high":
-			return config.colors.editorThinkingHigh ?? config.colors.editorThinking;
-		case "xhigh":
-			return config.colors.editorThinkingXhigh ?? config.colors.editorThinking;
-		default:
-			return config.colors.editorThinking;
-	}
-}
-
-function renderVariable(
-	name: string,
-	values: EditorMetadataValues,
-	uiTheme: Theme,
-	config: PolishedTuiConfig,
-): { plain: string; styled: string } {
-	const colorSource = config.colorSources.editor;
-	const thinking = values.thinking.toLowerCase() === "off" ? "" : values.thinking;
-	const raw =
-		name === "model"
-			? values.model
-			: name === "model_id"
-				? values.modelId
-				: name === "model_name"
-					? values.modelName
-					: name === "provider"
-						? values.provider
-						: name === "thinking"
-							? thinking
-							: name === "session_name"
-								? values.sessionName
-								: "";
-	const plain = sanitizeEditorMetadataText(raw);
-	if (!plain) return { plain: "", styled: "" };
-
-	if (name === "model" || name === "model_id" || name === "model_name") {
-		return {
-			plain,
-			styled: renderStyleForSourceOrFallback(
-				uiTheme,
-				colorSource,
-				config.colors.editorModel,
-				EDITOR_ACCENT_FALLBACK,
-				plain,
-			),
-		};
-	}
-	if (name === "provider") {
-		return {
-			plain,
-			styled: renderStyleForSourceOrFallback(
-				uiTheme,
-				colorSource,
-				config.colors.editorProvider,
-				"text",
-				plain,
-			),
-		};
-	}
-	if (name === "thinking") {
-		return {
-			plain,
-			styled: renderStyleForSourceOrFallback(
-				uiTheme,
-				colorSource,
-				editorThinkingStyle(config, plain),
-				"muted",
-				plain,
-			),
-		};
-	}
-	if (name === "session_name") {
-		return { plain, styled: safeThemeFg(uiTheme, "border", plain) };
-	}
-	return { plain: "", styled: "" };
-}
-
-function renderTokens(
-	tokens: FormatToken[],
-	values: EditorMetadataValues,
-	uiTheme: Theme,
-	config: PolishedTuiConfig,
-): RenderedTokens {
-	let styled = "";
-	let hasDynamic = false;
-	let hasNonEmptyDynamic = false;
-
-	for (const token of tokens) {
-		if (token.kind === "text") {
-			const plain = sanitizeEditorMetadataText(token.value);
-			if (plain) styled += safeThemeFg(uiTheme, "border", plain);
-			continue;
-		}
-		if (token.kind === "fill") {
-			hasDynamic = true;
-			continue;
-		}
-		if (token.kind === "var") {
-			hasDynamic = true;
-			const rendered = renderVariable(token.name, values, uiTheme, config);
-			styled += rendered.styled;
-			if (rendered.plain) hasNonEmptyDynamic = true;
-			continue;
-		}
-
-		const rendered = renderTokens(token.tokens, values, uiTheme, config);
-		const visible = !rendered.hasDynamic || rendered.hasNonEmptyDynamic;
-		hasDynamic = true;
-		if (visible) {
-			styled += rendered.styled;
-			hasNonEmptyDynamic = true;
-		}
-	}
-
-	return { styled, hasDynamic, hasNonEmptyDynamic };
-}
-
-export function renderEditorMetadataFormat(
-	format: string,
-	values: EditorMetadataValues,
-	uiTheme: Theme,
-	config: PolishedTuiConfig,
-): string {
-	return renderTokens(
-		parseFooterFormat(sanitizeEditorMetadataText(format)),
-		values,
-		uiTheme,
-		config,
-	).styled;
-}