@xzzpig/pi-starline 0.1.0

package/extensions/starline/live-context.ts

@@ -0,0 +1,75 @@
+import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
+import type { SessionLifecycle } from "./session-lifecycle";
+
+export type LiveContextOverride = {
+	tokens: number;
+};
+
+function usageComponent(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+export function calculateLiveContextTokens(usage: Usage | undefined): number | undefined {
+	if (!usage) return undefined;
+	const totalTokens = usageComponent(usage.totalTokens);
+	if (totalTokens > 0) return totalTokens;
+	const calculated =
+		usageComponent(usage.input) +
+		usageComponent(usage.output) +
+		usageComponent(usage.cacheRead) +
+		usageComponent(usage.cacheWrite);
+	return calculated > 0 ? calculated : undefined;
+}
+
+export function liveContextFromMessage(message: unknown): LiveContextOverride | undefined {
+	if (!message || typeof message !== "object") return undefined;
+	const assistant = message as Partial<AssistantMessage>;
+	if (assistant.role !== "assistant") return undefined;
+	if (assistant.stopReason === "error" || assistant.stopReason === "aborted") return undefined;
+	const tokens = calculateLiveContextTokens(assistant.usage);
+	return tokens === undefined ? undefined : { tokens };
+}
+
+export class LiveContextController {
+	private readonly lifecycle: SessionLifecycle;
+	private readonly requestRender: () => void;
+	private override: LiveContextOverride | undefined;
+	private cancelScheduledRender: (() => void) | undefined;
+	private scheduledGeneration: number | undefined;
+
+	constructor(lifecycle: SessionLifecycle, requestRender: () => void) {
+		this.lifecycle = lifecycle;
+		this.requestRender = requestRender;
+	}
+
+	get(): LiveContextOverride | undefined {
+		return this.override;
+	}
+
+	update(message: unknown): boolean {
+		const next = liveContextFromMessage(message);
+		if (!next || !this.lifecycle.isCurrent()) return false;
+		this.override = next;
+		const generation = this.lifecycle.currentGeneration();
+		if (this.cancelScheduledRender && this.scheduledGeneration !== generation) {
+			this.cancelScheduledRender = undefined;
+			this.scheduledGeneration = undefined;
+		}
+		if (!this.cancelScheduledRender) {
+			this.scheduledGeneration = generation;
+			this.cancelScheduledRender = this.lifecycle.defer(() => {
+				this.cancelScheduledRender = undefined;
+				this.scheduledGeneration = undefined;
+				if (this.override) this.requestRender();
+			}, 250);
+		}
+		return true;
+	}
+
+	clear(): void {
+		this.override = undefined;
+		this.cancelScheduledRender?.();
+		this.cancelScheduledRender = undefined;
+		this.scheduledGeneration = undefined;
+	}
+}

package/extensions/starline/mouse/capabilities.ts

@@ -0,0 +1,207 @@
+/**
+ * What of Pi's renderer this build can actually reach.
+ *
+ * Pi's TUI internals carry no stability contract, so every method Starline
+ * patches is probed before it is trusted. The probe is deliberately structural —
+ * the method exists, is a function, and can be replaced and put back. Signature
+ * drift is caught by `test/contract/pi-tui-contract.test.ts` in CI rather than
+ * guessed at here: default parameters make `fn.length` a liar.
+ *
+ * `requestRender` is the one entry a feature only ever *calls* on the receiver,
+ * never patches. It is probed all the same, and by the same structural test: a
+ * feature that installs and then cannot ask for a repaint leaves its own state
+ * on screen a frame late or not at all, which is precisely the half-working
+ * install this table exists to prevent. The check being stricter than a plain
+ * call needs (it also demands writable and configurable) costs nothing, because
+ * a class method declared the ordinary way is both.
+ */
+
+export type MouseCapability =
+	| "handleViewportInput"
+	| "routeWheel"
+	| "handleSelectionMouseEvent"
+	| "copySelectionToClipboard"
+	| "getWordSelection"
+	| "getSelectionSourceLine"
+	| "getSelectionBounds"
+	| "getSelectionColumns"
+	| "flash"
+	| "hasOverlay"
+	| "requestRender";
+
+export type MouseFeature =
+	| "selectionPendingMode"
+	| "pathAwareWords"
+	| "clickToExpandTools"
+	| "editorWheelScroll"
+	| "editorClickToCaret"
+	| "editorBufferCopy"
+	| "transcriptCleanCopy";
+
+const CAPABILITIES: readonly MouseCapability[] = [
+	"handleViewportInput",
+	"routeWheel",
+	"handleSelectionMouseEvent",
+	"copySelectionToClipboard",
+	"getWordSelection",
+	"getSelectionSourceLine",
+	"getSelectionBounds",
+	"getSelectionColumns",
+	"flash",
+	"hasOverlay",
+	"requestRender",
+];
+
+/**
+ * Every capability a feature needs before it may install.
+ *
+ * There is no `frameFreeSelection` entry, deliberately: the feature is cut
+ * (see `installMouse` in `index.ts`). A feature listed here is one
+ * `installMouse` installs, and a table that claims a feature nothing installs
+ * is worse than no table.
+ */
+const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
+	// Without ctrl+c interception the pending mode strands a highlight the user
+	// cannot copy, which is worse than copy-on-release. It also reads the
+	// selection directly (`getSelectionBounds`, `getSelectionColumns`) to build
+	// an exact character count, and raises its own notice (`flash`), so all
+	// three must be reachable too. `requestRender` is what puts the pending hint
+	// on screen the moment the button comes up: arming without it would leave
+	// the user staring at a highlight with nothing telling them ctrl+c copies it.
+	selectionPendingMode: [
+		"copySelectionToClipboard",
+		"handleViewportInput",
+		"getSelectionBounds",
+		"getSelectionColumns",
+		"flash",
+		"requestRender",
+	],
+	// Also reads the line under the pointer through the receiver's own
+	// `getSelectionSourceLine`, so the patch has a real line to hand
+	// `wordRangeAt` — without it there's nothing to compute a range over.
+	pathAwareWords: ["getWordSelection", "getSelectionSourceLine"],
+	// The press it acts on arrives through `handleSelectionMouseEvent`, and it
+	// asks `hasOverlay` the same question Pi's own press path asks before
+	// resolving a scroll view (`tui-alt-screen.js:684`) — without it, a click on
+	// a dialog would toggle whatever tool box happens to sit behind it. It
+	// consumes the press rather than calling through, so Pi never reaches its own
+	// repaint for that event: `requestRender` is the only thing that draws the
+	// box it just toggled.
+	clickToExpandTools: ["handleSelectionMouseEvent", "hasOverlay", "requestRender"],
+	// The notch arrives through `routeWheel`, which it consumes on an editor hit
+	// rather than calling through — so Pi never reaches its own repaint for that
+	// event and `requestRender` is the only thing that draws the scrolled box. It
+	// asks `hasOverlay` for the same reason click-to-expand does: an overlay is
+	// composited on top of a layout that still contains the editor
+	// (`tui.js:123`), so without it a notch aimed at a dialog would scroll the
+	// draft hidden behind it.
+	editorWheelScroll: ["routeWheel", "hasOverlay", "requestRender"],
+	// Two behaviours, one feature. The press arrives through
+	// `handleSelectionMouseEvent`; backspace and delete over a live selection
+	// arrive through `handleViewportInput`, which is why that is listed even
+	// though the caret alone would not need it. Range delete then reads the
+	// selection through `getSelectionBounds` to find out whether it is the
+	// editor's, and — because it *consumes* the key, so Pi's `handleInput` never
+	// reaches its own `requestImmediateRender` (`tui.js:620`) — `requestRender`
+	// is the only thing that draws the shortened draft.
+	//
+	// `hasOverlay` for the same reason the features above ask it: an overlay is
+	// composited over a layout that still contains the editor, so without it a
+	// click on a dialog would move the caret in the box behind it, and a
+	// backspace would delete from it.
+	//
+	// The consequence of listing `handleViewportInput` is deliberate and worth
+	// naming: a Pi that has moved that method loses click-to-caret entirely, not
+	// just the range delete. That is this table's rule — never install half a
+	// feature — and the alternative, a caret that installs while its delete
+	// silently does not, is exactly the half-working install the rule exists to
+	// prevent.
+	editorClickToCaret: [
+		"handleSelectionMouseEvent",
+		"handleViewportInput",
+		"getSelectionBounds",
+		"hasOverlay",
+		"requestRender",
+	],
+	// It wraps `copySelectionToClipboard`, reads the selection through
+	// `getSelectionBounds` to find out whether it is the editor's, and raises
+	// Pi's own "Copied!" through `flash` when it answers the copy itself.
+	// `hasOverlay` again: a selection dropped on a dialog must not be read as
+	// text from the draft behind it.
+	//
+	// The clipboard write goes through `terminal.write`, which is not listed
+	// because it is not on this prototype — `terminal` is a plain instance field
+	// holding somebody else's object, the same class of thing as `currentLayout`.
+	// It is checked at the call site instead, and a terminal that cannot be
+	// written to makes the copy fall through to Pi rather than disabling the
+	// feature at install time.
+	editorBufferCopy: ["copySelectionToClipboard", "getSelectionBounds", "hasOverlay", "flash"],
+	// Shares the `copySelectionToClipboard` patch with the two features above
+	// it. It reads the selection through `getSelectionBounds` to find the rows,
+	// through `getSelectionColumns` to slice the cleaned text along the same
+	// grapheme-aligned columns Pi would have used, asks `hasOverlay` before
+	// trusting those rows (an overlay is composited over a layout that still
+	// contains the transcript), and raises Pi's own "Copied!" through `flash`
+	// when it answers the copy itself. The clipboard write goes through
+	// `terminal.write`, unlisted for the same reason as editorBufferCopy's — it
+	// is an instance field, checked at the call site instead.
+	transcriptCleanCopy: [
+		"copySelectionToClipboard",
+		"getSelectionBounds",
+		"getSelectionColumns",
+		"hasOverlay",
+		"flash",
+	],
+};
+
+function isPatchable(prototype: object, name: string): boolean {
+	try {
+		let current: object | null = prototype;
+		while (current) {
+			const descriptor = Object.getOwnPropertyDescriptor(current, name);
+			if (descriptor) {
+				if (typeof descriptor.value !== "function") return false;
+				return descriptor.writable === true && descriptor.configurable === true;
+			}
+			current = Object.getPrototypeOf(current);
+		}
+		return false;
+	} catch {
+		// A prototype that throws on inspection is one we do not touch.
+		return false;
+	}
+}
+
+export function probeCapabilities(prototype: object): ReadonlySet<MouseCapability> {
+	const found = new Set<MouseCapability>();
+	for (const capability of CAPABILITIES) {
+		if (isPatchable(prototype, capability)) found.add(capability);
+	}
+	return found;
+}
+
+export function enabledFeatures(
+	available: ReadonlySet<MouseCapability>,
+): ReadonlySet<MouseFeature> {
+	const enabled = new Set<MouseFeature>();
+	for (const [feature, needed] of Object.entries(REQUIREMENTS) as [
+		MouseFeature,
+		readonly MouseCapability[],
+	][]) {
+		if (needed.every((capability) => available.has(capability))) enabled.add(feature);
+	}
+	return enabled;
+}
+
+/**
+ * One line naming everything that will not run, or null when all is well. Pi
+ * prints this once per process — a line per feature would be noise on a build
+ * where Pi has moved on.
+ */
+export function disabledFeatureWarning(enabled: ReadonlySet<MouseFeature>): string | null {
+	const disabled = (Object.keys(REQUIREMENTS) as MouseFeature[]).filter(
+		(feature) => !enabled.has(feature),
+	);
+	if (disabled.length === 0) return null;
+	return `[starline] This Pi build does not expose what these mouse features need, so they are off: ${disabled.join(", ")}. Everything else still works.`;
+}

package/extensions/starline/mouse/component-tree.ts

@@ -0,0 +1,230 @@
+/**
+ * Which of Pi's components rendered a given row of a container's output.
+ *
+ * `hit-test.ts` answers the same question from Pi's *layout* tree, and for
+ * the editor and the transcript viewport that is the right tree. It cannot
+ * answer it for a message inside the transcript, because there is no box to
+ * find: `layoutComponent` (pi-tui's `layout.js`) only builds child boxes for
+ * a component carrying a `LAYOUT_NODE`, which is `Stack` and `ScrollView` and
+ * nothing else. Every message component extends `Container`, which has none,
+ * so the whole transcript is one leaf box with `children: []` and a `lines`
+ * array. Ownership inside that array has to come from the *component* tree.
+ *
+ * It can, exactly. `Container.render(width)` (pi-tui's `tui.ts`) renders each
+ * child at the **same width** and concatenates the results in order, with no
+ * gap, padding or reordering:
+ *
+ * ```ts
+ * render(width: number): string[] {
+ * 	const lines: string[] = [];
+ * 	for (const child of this.children) {
+ * 		for (const line of child.render(width)) lines.push(line);
+ * 	}
+ * 	return lines;
+ * }
+ * ```
+ *
+ * So a child occupies rows `[sum of its preceding siblings' rendered heights,
+ * + its own rendered height)` of its parent's output, and the same rule
+ * applies again inside a child that is itself a container. Rendering is the
+ * only way to learn those heights — a component's height is whatever its
+ * `render` returns.
+ *
+ * ## Why the walk verifies instead of trusting `children`
+ *
+ * A `Container` subclass may override `render`, and the ones that matter do:
+ * `pi-toolbox` replaces `ToolExecutionComponent.prototype.render` with one
+ * that draws `╭─╮ │ ╰─╯` around its children's lines. Its `children` are then
+ * no longer a partition of its own rows at all — they are the *contents* of a
+ * frame it added rows around. Descending on the strength of `children` alone
+ * would attribute the frame's rows to whichever child happened to line up.
+ *
+ * So each step of the walk checks its own premise: a child's rendered lines
+ * must appear **verbatim, in place** in the parent's output at the offset the
+ * running total predicts. If they do, the offset is not an estimate, it is
+ * the parent's own output read back. If they do not, the parent is not a
+ * plain concatenator and the walk stops there — which is the correct answer,
+ * because the parent is then the component that actually drew those rows.
+ *
+ * The check is a prefix check, and stops at the child containing the target
+ * row: siblings after it are never rendered. That is cheaper than verifying
+ * the whole parent and just as exact — matching `parent.lines[0 .. cursor +
+ * height)` against the concatenation of children `0..k` establishes exactly
+ * where child `k` sits, and nothing later in the parent's output can move it.
+ *
+ * ## Cost
+ *
+ * Every child up to the target row is rendered once, at each level. This runs
+ * on a copy and on a click, never per frame — and components cache their own
+ * renders (pi-tui's `Text` and `Markdown` keep a `cachedLines`; `pi-toolbox`
+ * keeps a `__frameCache`), so a repeat render of an unchanged component is
+ * usually a cache probe rather than real work. A `ComponentTree` also caches
+ * every render it does, so asking about a hundred rows of one selection costs
+ * one pass, not a hundred.
+ *
+ * Nothing here imports pi-tui: `ComponentLike` is the structural slice a
+ * component has to expose for this to work, so the tests can build a real
+ * component graph out of pi-tui's own `Container` and the extension does not
+ * take a dependency on its class identities.
+ */
+
+/** The slice of a Pi component this module reads. */
+export type ComponentLike = {
+	children?: readonly unknown[];
+	render(width: number): string[];
+};
+
+/**
+ * One component's own rows, as an interval of the tree root's output.
+ * `start` is inclusive and `end` exclusive, both in the root's row space;
+ * `lines` are the component's own rendered rows, so `lines[row - start]` is
+ * the text at root row `row`.
+ */
+export type ComponentSpan = {
+	component: unknown;
+	start: number;
+	end: number;
+	lines: readonly string[];
+};
+
+export type ComponentTree = {
+	/** Root first, innermost last. Empty when `row` is outside the root. */
+	pathAt(row: number): ComponentSpan[];
+	/** The innermost component that rendered `row`. */
+	ownerAt(row: number): ComponentSpan | undefined;
+};
+
+/** Whether `value` renders — the one method this module needs to call. */
+export function isComponentLike(value: unknown): value is ComponentLike {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof (value as { render?: unknown }).render === "function"
+	);
+}
+
+/**
+ * Whether `component` is one of Pi's expandable message components — the duck
+ * type for "clicking this could expand or collapse it". Verified against the
+ * installed `pi-coding-agent`: `bash-execution`, `branch-summary-message`,
+ * `compaction-summary-message`, `custom-entry`, `custom-message`,
+ * `skill-invocation-message` and `tool-execution` all expose `setExpanded`;
+ * pi-tui's own leaf components (`Text`, `Markdown`, `Container`) expose none.
+ *
+ * Note what this does *not* say: nothing about how the component looks. It
+ * was briefly used to infer that a component had drawn a border, which is
+ * exactly the inference frame-free selection was cut for — `setExpanded` says
+ * a box could be expanded, never that a box was drawn. It is kept for the
+ * question it can answer, which is Task 8's.
+ */
+export function isExpandableComponent(component: unknown): boolean {
+	return (
+		typeof component === "object" &&
+		component !== null &&
+		typeof (component as { setExpanded?: unknown }).setExpanded === "function"
+	);
+}
+
+function childrenOf(component: unknown): readonly unknown[] {
+	const children = (component as { children?: unknown }).children;
+	return Array.isArray(children) ? children : [];
+}
+
+/**
+ * A component's rendered rows, memoised, and never able to take a copy down
+ * with it: a component whose `render` throws (or returns something that is
+ * not an array of lines) is treated as zero rows tall. Its siblings keep
+ * their own offsets, because a zero-height child advances the running total
+ * by zero — the same thing a component that legitimately renders nothing
+ * does, which both `ToolExecutionComponent` (`if (this.hideComponent) return
+ * []`) and `pi-toolbox`'s framed render already do routinely.
+ */
+function renderOnce(
+	component: unknown,
+	width: number,
+	cache: Map<unknown, readonly string[]>,
+): readonly string[] {
+	const cached = cache.get(component);
+	if (cached) return cached;
+	let lines: readonly string[] = [];
+	if (isComponentLike(component)) {
+		try {
+			const rendered = component.render(width);
+			if (Array.isArray(rendered)) lines = rendered;
+		} catch {
+			lines = [];
+		}
+	}
+	cache.set(component, lines);
+	return lines;
+}
+
+/**
+ * The child of `parent` that rendered `row`, or `undefined` when `parent`
+ * turns out not to be a plain concatenation of its children (see the module
+ * docstring) or has no child there.
+ */
+function childSpanAt(
+	parent: ComponentSpan,
+	row: number,
+	width: number,
+	cache: Map<unknown, readonly string[]>,
+): ComponentSpan | undefined {
+	let cursor = parent.start;
+	for (const child of childrenOf(parent.component)) {
+		const lines = renderOnce(child, width, cache);
+		for (let offset = 0; offset < lines.length; offset++) {
+			if (parent.lines[cursor - parent.start + offset] !== lines[offset]) return undefined;
+		}
+		if (row >= cursor && row < cursor + lines.length) {
+			return { component: child, start: cursor, end: cursor + lines.length, lines };
+		}
+		cursor += lines.length;
+	}
+	return undefined;
+}
+
+/**
+ * A row→component map over the component graph rooted at `root`, rendered at
+ * `width`.
+ *
+ * `width` must be the width `root` was actually rendered at — for the
+ * transcript that is the scroll content box's `rect.width`, which is what
+ * pi-tui passed to `renderCached` when it produced `scrollContentLines`.
+ * `rootLines` is that same output when the caller already holds it (the
+ * selection path does), which saves re-rendering the entire transcript to
+ * learn something it was just handed; omit it and the root renders once.
+ *
+ * The returned tree caches every render it performs, so it is worth keeping
+ * for the whole of one question (a selection's rows) and throwing away after
+ * — it holds no invalidation logic and will happily hand back stale rows if
+ * kept across a component update.
+ */
+export function createComponentTree(
+	root: ComponentLike,
+	width: number,
+	rootLines?: readonly string[],
+): ComponentTree {
+	const cache = new Map<unknown, readonly string[]>();
+	if (rootLines) cache.set(root, rootLines);
+
+	const pathAt = (row: number): ComponentSpan[] => {
+		if (!Number.isInteger(row) || row < 0) return [];
+		const lines = renderOnce(root, width, cache);
+		if (row >= lines.length) return [];
+		const path: ComponentSpan[] = [{ component: root, start: 0, end: lines.length, lines }];
+		// A component that is its own descendant would otherwise loop here.
+		const seen = new Set<unknown>([root]);
+		let current = path[0];
+		for (;;) {
+			const child = childSpanAt(current, row, width, cache);
+			if (!child || seen.has(child.component)) break;
+			seen.add(child.component);
+			path.push(child);
+			current = child;
+		}
+		return path;
+	};
+
+	return { pathAt, ownerAt: (row) => pathAt(row).at(-1) };
+}