@xzzpig/pi-starline 0.5.1 → 0.7.1

package/extensions/starline/live-tps.ts

@@ -0,0 +1,165 @@
+/**
+ * Decode throughput of the latest assistant message, for the `tps` pill.
+ *
+ * The denominator is the part that is easy to get wrong, so the window is
+ * explicit: it opens on the first streamed delta and closes when the message is
+ * done. Queueing, time-to-first-token and every tool call in the turn fall
+ * outside it, which is what "how fast is this model writing" should mean.
+ * `usage.output` is the numerator: it is the one token count the provider reports
+ * for the message itself, and it includes thinking tokens.
+ *
+ * Two halves on purpose. `observe` only sees streaming events, because Pi turns
+ * just `text_delta` / `thinking_*` / `toolcall_*` into `message_update` — the
+ * stream's `done` event never reaches an extension. The output count therefore
+ * has to come from `message_end`, which is what `complete` takes.
+ *
+ * A provider that hands back a whole message in a single chunk has no stream to
+ * measure. Those messages are skipped rather than turned into a fabricated
+ * number, and the pill keeps the previous value instead of blinking to blank.
+ */
+
+import type { AssistantMessageEvent } from "@earendil-works/pi-ai";
+
+/**
+ * Below this the window is noise: two deltas 20 ms apart divide output by
+ * almost nothing and report a throughput no model produced. Real streams clear
+ * it by an order of magnitude.
+ */
+const MIN_WINDOW_MS = 100;
+
+/**
+ * One delta is a non-streaming reply, not a measurement.
+ */
+const MIN_DELTAS = 2;
+
+/**
+ * The live value needs a longer window than the final one: a single early delta
+ * divided by 30 ms reads as thousands of tokens per second, and the pill would
+ * flash a nonsense number before settling.
+ */
+const MIN_LIVE_WINDOW_MS = 400;
+
+/**
+ * How often the live value may be replaced. The footer already re-renders on the
+ * spinner's tick, so this is not about cost — it is about the number being
+ * readable instead of a blur.
+ */
+const LIVE_UPDATE_MS = 500;
+
+/**
+ * Rough token count for streamed text.
+ *
+ * Pi only reports usage in the final streamed chunk, so a live number cannot use
+ * the real count. CJK glyphs cost about a token each and Latin text about four
+ * characters per token, which lands within a few tens of percent of the real
+ * tokenizer — enough for a moving number that gets corrected at message end.
+ */
+export function estimateTokens(text: string): number {
+	let wide = 0;
+	let total = 0;
+	for (const character of text) {
+		total += 1;
+		const code = character.codePointAt(0) ?? 0;
+		const isWide =
+			(code >= 0x2e80 && code <= 0x9fff) || // CJK
+			(code >= 0x3040 && code <= 0x30ff) || // kana
+			(code >= 0xac00 && code <= 0xd7af); // hangul
+		if (isWide) wide += 1;
+	}
+	return wide + (total - wide) / 4;
+}
+
+export class LiveTpsController {
+	private firstDeltaAt: number | undefined;
+	private deltas = 0;
+	/** Estimated tokens seen so far in the streaming message, for the live value. */
+	private streamedTokens = 0;
+	private lastLiveAt = 0;
+	private latest: number | undefined;
+
+	/** Most recent measured throughput, or undefined before the first one. */
+	value(): number | undefined {
+		return this.latest;
+	}
+
+	/**
+	 * End a turn's measurement window without discarding the value. Called when a
+	 * new agent run starts: the pill keeps showing the last turn's speed until the
+	 * next message finishes.
+	 */
+	beginTurn(): void {
+		this.firstDeltaAt = undefined;
+		this.deltas = 0;
+		this.streamedTokens = 0;
+		this.lastLiveAt = 0;
+	}
+
+	/** True while a message is streaming, which is when the value is an estimate. */
+	streaming(): boolean {
+		return this.firstDeltaAt !== undefined;
+	}
+
+	/** Forget everything, value included. A session is over or changed. */
+	clear(): void {
+		this.beginTurn();
+		this.latest = undefined;
+	}
+
+	/**
+	 * Feed one streaming event. Returns true when the visible number changed, so
+	 * the caller can re-render the footer.
+	 *
+	 * The live value is an estimate over the whole window so far, not a sliding
+	 * one: a model that stalls for 800 ms would otherwise show a rate that drops
+	 * to nothing even though its average is fine.
+	 *
+	 * `event` is optional because older Pi builds (and some test harnesses) fire
+	 * `message_update` without the `assistantMessageEvent` field.
+	 */
+	observe(event: AssistantMessageEvent | undefined): boolean {
+		if (!event) return false;
+		switch (event.type) {
+			case "start":
+				this.beginTurn();
+				return false;
+			case "text_delta":
+			case "thinking_delta":
+			case "toolcall_delta": {
+				const now = Date.now();
+				// `firstDeltaAt` is a timestamp, so 0 is a legal value: test not-assigned
+				// rather than falsy.
+				if (this.firstDeltaAt === undefined) {
+					this.firstDeltaAt = now;
+					this.lastLiveAt = 0;
+				}
+				this.deltas += 1;
+				this.streamedTokens += estimateTokens(event.delta);
+				const windowMs = now - this.firstDeltaAt;
+				if (windowMs < MIN_LIVE_WINDOW_MS) return false;
+				if (now - this.lastLiveAt < LIVE_UPDATE_MS) return false;
+				this.lastLiveAt = now;
+				this.latest = this.streamedTokens / (windowMs / 1000);
+				return true;
+			}
+			default:
+				return false;
+		}
+	}
+
+	/**
+	 * Close the window with the message's own output count. Returns true when the
+	 * measurement landed, so the caller can re-render the footer.
+	 */
+	complete(output: number): boolean {
+		const first = this.firstDeltaAt;
+		const deltas = this.deltas;
+		const windowMs = first === undefined ? 0 : Date.now() - first;
+		this.beginTurn();
+		if (first === undefined) return false;
+		if (deltas < MIN_DELTAS) return false;
+		if (!Number.isFinite(output) || output <= 0) return false;
+		if (windowMs < MIN_WINDOW_MS) return false;
+		this.latest = output / (windowMs / 1000);
+		return true;
+	}
+}

package/extensions/starline/mouse/bubble-dismiss.ts

@@ -0,0 +1,82 @@
+/**
+ * A click anywhere outside an open pill bubble puts it away.
+ *
+ * A bubble is a popover, not a panel: it covers the transcript while it is open
+ * and the way out should be wherever the user's pointer already is. Escape, a
+ * second click on the pill, and another pill all already close it; the rest of
+ * the screen — the editor, the transcript, an empty row — did nothing, so a
+ * bubble stayed up until one of those three happened.
+ *
+ * The click has to be read before Pi dispatches it, because the thing under the
+ * pointer is a component that knows nothing about bubbles. There is exactly one
+ * patch on the renderer's mouse entry (`pointer-shape.ts`, adapter
+ * `mouse-pointer-shape`) and the registry holds one behaviour per method, so this
+ * subscribes to the events that patch publishes instead of taking a second one.
+ * Nothing here consumes the event: the click goes on to move the caret, select a
+ * line, or whatever else it was going to do.
+ *
+ * The footer row is handled by the footer itself, which knows which cells are
+ * pills: a press there either belongs to a clickable pill (its own toggle or
+ * replacement) or lands on padding, a gap or an inert read-out, and that last
+ * case closes the bubble too. So the geometry check below stays off that row —
+ * closing on the press here as well would make the same pill's second click
+ * close and immediately reopen.
+ */
+
+import { activePillBubbleGeometry, closePillBubble, type PillBubbleGeometry } from "../pill-bubble";
+import {
+	isPointerPress,
+	observePointerEvents,
+	type PointerEventRaw,
+	type PointerReceiver,
+} from "./pointer-events";
+
+/** Rows between the bottom of the screen and the footer: none. */
+const FOOTER_LAST_ROW = 1;
+
+/**
+ * Whether this pointer event lands outside the bubble's rectangle.
+ *
+ * The rectangle is resolved against the terminal as it is now, not as it was when
+ * the bubble opened, so a window that grew keeps the bubble on its footer. A
+ * press on the footer row never counts here: the footer decides that row cell by
+ * cell, because it is the one place that knows where its pills are.
+ */
+export function isOutsideBubble(
+	event: PointerEventRaw,
+	geometry: PillBubbleGeometry | undefined,
+	terminalRows: number | undefined,
+): boolean {
+	if (!geometry || geometry.width <= 0 || geometry.height <= 0) return false;
+	if (terminalRows === undefined || !Number.isFinite(terminalRows)) return false;
+	if (!isPointerPress(event)) return false;
+
+	// The overlay is anchored to the bottom with a one-row gap for the footer, so
+	// its last row is that many rows above the screen's last one.
+	const bottomRow = terminalRows - FOOTER_LAST_ROW - geometry.bottomOffset;
+	const topRow = bottomRow - geometry.height + 1;
+	const left = geometry.leftColumn;
+	const right = left + geometry.width;
+
+	// The bar itself: its pills toggle and replace their own bubbles, and the rest
+	// of the row is the footer's to dismiss from (see `handleMouse` there).
+	if (event.y === terminalRows - FOOTER_LAST_ROW) return false;
+
+	return event.y < topRow || event.y > bottomRow || event.x < left || event.x >= right;
+}
+
+/**
+ * Close the open bubble when a press lands outside it.
+ *
+ * Returns the disposer. Harmless on a Pi without component mouse events: no
+ * events are ever published, so nothing happens and the bubble keeps its other
+ * three ways out.
+ */
+export function installPillBubbleDismiss(): () => void {
+	return observePointerEvents((event, receiver: PointerReceiver | undefined) => {
+		const geometry = activePillBubbleGeometry();
+		if (!geometry) return;
+		if (!isOutsideBubble(event, geometry, receiver?.terminal?.rows)) return;
+		closePillBubble();
+	});
+}

package/extensions/starline/mouse/cursor-marker.ts

@@ -0,0 +1,69 @@
+/**
+ * A stopgap for Pi's cursor-marker leak during mouse selection.
+ *
+ * `TuiAltScreen.applySelection` cuts a selected row into `before` / `selected` /
+ * `after` with `sliceByColumn`, and `sliceWithWidth` carries every escape sequence
+ * that precedes a slice into it (`pendingAnsi`). The editor's caret marker
+ * (`\x1b_pi:c\x07`, a zero-width APC) therefore gets copied into each later slice:
+ * one marker becomes two or three.
+ *
+ * `extractCursorPosition` strips only the first copy per line and returns, so the
+ * rest are written to the terminal. Ghostty only ends an APC on `ESC \`, treats the
+ * `BEL` as payload, and swallows the bytes that follow — which shows up as
+ * garbled text in and around the editor while dragging. Upstream issue
+ * earendil-works/pi#9332; the fix is earendil-works/pi#9441, still unmerged as of
+ * Pi 1.4.0.
+ *
+ * Starline makes this fire on every editor drag-select because
+ * `editorClickToCaret` moves the caret to the press point, so the caret row is
+ * always the row being dragged over. This module keeps the first marker per line
+ * and drops the duplicates — the same thing #9441 does in `extractCursorPosition`,
+ * from the outside. **Delete it once a Pi release contains #9441.**
+ */
+
+import { CURSOR_MARKER } from "@earendil-works/pi-tui";
+import { installPrototypePatch } from "../prototype-patch-registry";
+
+/**
+ * Keep the first cursor marker on a line, drop the rest.
+ *
+ * The first one is the one `extractCursorPosition` reads the caret column from, so
+ * keeping it preserves the caret exactly; the extras are what leak.
+ */
+export function dedupeCursorMarkers(lines: readonly string[]): string[] {
+	return lines.map((line) => {
+		const first = line.indexOf(CURSOR_MARKER);
+		if (first === -1) return line;
+		const head = line.slice(0, first + CURSOR_MARKER.length);
+		const rest = line.slice(first + CURSOR_MARKER.length);
+		return rest.includes(CURSOR_MARKER) ? head + rest.split(CURSOR_MARKER).join("") : line;
+	});
+}
+
+/**
+ * Installs the marker dedupe on `applySelection`, or does nothing on a build that
+ * has no selection rendering at all. Returns the disposer, or undefined when there
+ * was nothing to patch.
+ */
+export function installCursorMarkerDedupe(prototype: object): (() => void) | undefined {
+	const target = prototype as Record<string, unknown>;
+	if (typeof target.applySelection !== "function") return undefined;
+	try {
+		return installPrototypePatch(
+			prototype,
+			"applySelection",
+			"selection-marker-dedupe",
+			({ predecessor, receiver, args }) => {
+				const result = Reflect.apply(predecessor, receiver, args);
+				// Anything that is not the row array Pi documents is passed through
+				// untouched: this patch exists to clean a frame, not to reshape one.
+				if (!Array.isArray(result)) return result;
+				return dedupeCursorMarkers(result as string[]);
+			},
+		);
+	} catch {
+		// An unpatchable method means the leak stays, which is exactly how Pi
+		// behaves without Starline. Never fail an install over it.
+		return undefined;
+	}
+}

package/extensions/starline/mouse/editor-hit-test.ts

@@ -45,7 +45,10 @@ export type EditorBoxGeometry = {
  * they cannot be mistaken for a rule.
  *
  * Layout between the rules, per renderPolishedFrame:
- *   rule, [pad], ...text, [pad], metadata, rule
+ *   rule, [pad], ...text, [filler], [pad], rule
+ *
+ * Filler rows (`editorMinRows`) are counted as text rows here; a click on one
+ * lands past the end of the draft either way.
  */
 export function findEditorBox(
 	clusterLines: string[],
@@ -72,8 +75,8 @@ export function findEditorBox(
 
 	const pad = paddingY > 0 ? 1 : 0;
 	const firstTextRow = top + 1 + pad;
-	// Below the text: the padding row, then the metadata row, then the rule.
-	const lastTextRow = bottom - 2 - pad;
+	// Below the text: the padding row, then the rule.
+	const lastTextRow = bottom - 1 - pad;
 	if (lastTextRow < firstTextRow) return null;
 
 	return { firstTextRow, lastTextRow, textColumn };

package/extensions/starline/mouse/external-layer.ts

@@ -0,0 +1,42 @@
+/**
+ * Detection for an extension that already owns Pi's mouse layer.
+ *
+ * `@xzzpig/pi-mouse-events` patches the same `TuiAltScreen` methods Starline does
+ * (wheel, press, copy) from one place and publishes an API object under a
+ * process-global symbol so consumers do not have to import it — the way Pi loads
+ * extensions makes a static import of a package that may not be installed a
+ * problem, and `Symbol.for` is process-global by spec.
+ *
+ * Two layers patching the same prototype would both answer every notch, click and
+ * copy: the wheel would move twice, the caret would move twice, the clipboard
+ * would be written twice. Neither is wrong on its own, so the only safe answer is
+ * for the later layer to stand down and say so.
+ */
+
+/** The key `@xzzpig/pi-mouse-events` publishes its API under, version-pinned. */
+const MOUSE_EVENTS_API_KEY = Symbol.for("pi-mouse-events.api.v2");
+const MOUSE_EVENTS_API_VERSION = 2;
+
+export type ExternalMouseLayer = { name: string; version: number };
+
+/**
+ * The extension that owns the mouse layer in this process, if any.
+ *
+ * Read from the global the way that package's own consumers do, and checked for
+ * the contract version: the symbol key pins the name, not the shape, so an object
+ * from a different contract major is not something to hand events to.
+ */
+export function externalMouseLayer(
+	scope: Record<PropertyKey, unknown> = globalThis,
+): ExternalMouseLayer | undefined {
+	try {
+		const candidate = scope[MOUSE_EVENTS_API_KEY];
+		if (typeof candidate !== "object" || candidate === null) return undefined;
+		const version = (candidate as { version?: unknown }).version;
+		return version === MOUSE_EVENTS_API_VERSION
+			? { name: "@xzzpig/pi-mouse-events", version: MOUSE_EVENTS_API_VERSION }
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}

package/extensions/starline/mouse/fork-native-clipboard.ts

@@ -0,0 +1,57 @@
+import type { AsyncCopyHandler, CopyHandlerContext } from "@xzzpig/pi-mouse-events/api";
+
+type CopyReceiver = {
+	copySelection?: (text: string) => boolean | string | Promise<boolean | string>;
+	terminal?: { write?: (data: string) => void };
+	flash?: (message: string) => void;
+};
+
+type CopyCandidates = {
+	receiver: CopyReceiver;
+	showNotice: boolean;
+	/** The editor gets first refusal, followed by the cleaned transcript. */
+	texts: Array<() => string | undefined>;
+};
+
+async function copyText(
+	receiver: CopyReceiver,
+	text: string,
+	showNotice: boolean,
+): Promise<boolean> {
+	if (typeof receiver.copySelection === "function") {
+		try {
+			if ((await receiver.copySelection(text)) === true) {
+				if (showNotice) receiver.flash?.("Copied!");
+				return true;
+			}
+		} catch {
+			// A failed native clipboard falls back to OSC 52, as upstream does.
+		}
+	}
+	try {
+		if (typeof receiver.terminal?.write !== "function") return false;
+		receiver.terminal.write(`\x1b]52;c;${Buffer.from(text).toString("base64")}\x07`);
+		if (showNotice) receiver.flash?.("Copied!");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Build an async shared-layer handler; unavailable on older v2 publishers. */
+export function nativeCopyHandler(
+	candidatesFor: (context: CopyHandlerContext) => CopyCandidates | undefined,
+): AsyncCopyHandler {
+	return async (context) => {
+		const candidates = candidatesFor(context);
+		if (!candidates) return undefined;
+		for (const read of candidates.texts) {
+			const text = read();
+			if (text === undefined) continue;
+			if (text.length === 0 || (await copyText(candidates.receiver, text, candidates.showNotice))) {
+				return { handled: true };
+			}
+		}
+		return undefined;
+	};
+}

package/extensions/starline/mouse/fork-pill-mouse.ts

@@ -0,0 +1,19 @@
+import type { MouseEventsApi } from "@xzzpig/pi-mouse-events/api";
+import { installPillBubbleDismiss } from "./bubble-dismiss";
+import { type PointerReceiver, publishPointerEvent } from "./pointer-events";
+
+/** Feed the upstream bubble observer from the shared, non-consuming mouse slot. */
+export function installSharedPillMouse(api: MouseEventsApi): () => void {
+	const stopDismiss = installPillBubbleDismiss();
+	const stopEvents = api.addMouseHandler(
+		({ event, tui }) => {
+			// SAFETY: the shared API supplies the live TuiAltScreen; the observer only reads terminal.rows.
+			publishPointerEvent(event, tui as unknown as PointerReceiver);
+		},
+		{ priority: Number.MAX_SAFE_INTEGER },
+	);
+	return () => {
+		stopEvents();
+		stopDismiss();
+	};
+}

package/extensions/starline/mouse/fork-pointer-coordination.ts

@@ -0,0 +1,10 @@
+import type { PointerShape } from "@xzzpig/pi-mouse-events/api";
+import { getMouseEventsApi } from "./api-consumer";
+
+/** Use the shared pointer owner when the installed v2 API supports it. */
+export function requestSharedPointer(shape: PointerShape): boolean {
+	const api = getMouseEventsApi();
+	if (!api?.requestPointerShape) return false;
+	api.requestPointerShape(shape);
+	return true;
+}

package/extensions/starline/mouse/fork-transcript-copy.ts

@@ -0,0 +1,54 @@
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+import { type CleanedRows, cleanTranscriptRows } from "./transcript-copy";
+
+/** Preserve Starline's configurable message rail alongside upstream's pi-tidy cleaning. */
+export function cleanForkTranscriptRows(
+	lines: readonly string[],
+	startRow: number,
+	endRow: number,
+	railGlyph: string,
+	starlineOwnsMessages = true,
+): CleanedRows {
+	const upstream = cleanTranscriptRows(lines, startRow, endRow);
+	// When tidy owns messages, its icon is decoration rather than user text.
+	if (railGlyph === "│" && !starlineOwnsMessages) return upstream;
+
+	const prefix = railGlyph ? `${railGlyph} ` : "";
+	const dropped = new Set<number>();
+	const railContent = new Set<number>();
+	let lastRule: { row: number; width: number } | undefined;
+	for (let row = 0; row < lines.length; row++) {
+		const text = stripTerminalSequences(lines[row] ?? "");
+		if (/^─+$/.test(text)) {
+			const width = visibleWidth(text);
+			if (lastRule && lastRule.width === width && row - lastRule.row >= 2) {
+				dropped.add(lastRule.row);
+				dropped.add(row);
+				for (let inner = lastRule.row + 1; inner < row; inner++) railContent.add(inner);
+			}
+			lastRule = { row, width };
+		} else if (prefix && !text.startsWith(prefix)) {
+			lastRule = undefined;
+		}
+	}
+
+	let changed = upstream.changed;
+	const rows = upstream.rows.map((cleaned, index) => {
+		const row = startRow + index;
+		if (dropped.has(row)) {
+			changed = true;
+			return null;
+		}
+		if (cleaned === null || !prefix || !railContent.has(row)) return cleaned;
+		const original = stripTerminalSequences(lines[row] ?? "");
+		if (!original.startsWith(prefix)) return cleaned;
+		// For Starline's own rail the icon may be user text, so preserve it even
+		// when upstream would identify it as a pi-tidy decoration.
+		if (!starlineOwnsMessages && (cleaned.text !== original || cleaned.leftTrim !== 0)) {
+			return cleaned;
+		}
+		changed = true;
+		return { text: original.slice(prefix.length), leftTrim: visibleWidth(prefix) };
+	});
+	return { rows, changed };
+}

package/extensions/starline/mouse/fork-wheel-compat.ts

@@ -0,0 +1,22 @@
+import type {
+	MouseEventsApi,
+	MouseHandlerContext,
+	MouseHandlerRegistrationOptions,
+	MouseHandlerResult,
+} from "@xzzpig/pi-mouse-events/api";
+
+/** v2 publishers before the post-component wheel slot do not declare it. */
+export type SharedWheelHandler = (
+	context: MouseHandlerContext & { readonly wheelDelta?: number },
+) => MouseHandlerResult;
+
+type WheelRegistrar = (
+	handler: SharedWheelHandler,
+	options?: MouseHandlerRegistrationOptions,
+) => () => void;
+
+/** Read the optional capability without requiring a newer v2 type package. */
+export function sharedWheelRegistrar(api: MouseEventsApi): WheelRegistrar | undefined {
+	const candidate = (api as MouseEventsApi & { addWheelHandler?: WheelRegistrar }).addWheelHandler;
+	return typeof candidate === "function" ? candidate.bind(api) : undefined;
+}

package/extensions/starline/mouse/hint.ts

@@ -1,9 +1,9 @@
 /**
- * The right-hand side of the editor's metadata row.
+ * The hints on the right end of the editor's top rule.
  *
- * Both hints share one slot. `ui.ts` renders that row whether or not
- * `editorMetadataFormat` has anything in it, which is why 0.2.2 moved the paste
- * hint here off the editor border — blanking the template must not hide it.
+ * Both hints share one slot. They sat on the bottom border until 0.2.2, then on
+ * a metadata row under the text until 0.9, which kept the box a row taller than
+ * its text; the top rule holds them without adding a row.
  */
 export function composeHints(
 	pasteHint: string | null,