@xzzpig/pi-starline 0.2.0 → 0.3.0

package/README.md

@@ -44,16 +44,17 @@ pieces of one product, not a theme:
 
 The second half of the product: the statusline tells you where you are, the
 mouse lets you act on what you see. Starline drives Pi 0.84's own renderer
-(`tuiMode: "fullscreen"`) by patching its methods directly — the extension API
-stops at high-level hooks, and the selection hint, click-to-expand and clean-copy all
-need to reach into the renderer itself. That is also why they live in Starline:
-they sit on the same prototype patches the footer and editor already use, and
-Pi keeps its core deliberately minimal — behaviours belong in extensions.
+(`tuiMode: "fullscreen"`) through the [`@xzzpig/pi-mouse-events`](https://www.npmjs.com/package/@xzzpig/pi-mouse-events)
+extension, which owns the renderer prototype and dispatches mouse events to
+components — the extension API stops at high-level hooks, and the selection
+hint, click-to-expand and clean-copy all need to reach into the renderer
+itself. Install it alongside Starline; without it Starline's mouse features
+are simply off (everything else keeps working).
 
 - **Select and copy anywhere.** Drag to select in the transcript or the input box; double-click a word (paths and kebab-case stay whole), triple-click a line. Releasing copies — or set Pi's `fullscreenCopyOnSelect: false` and the selection stays highlighted, waiting for the copy key ([Pi #7720](https://github.com/earendil-works/pi/issues/7720), shipped in Pi 0.84.4).
 - **Clean copies.** Transcript selections drop Starline's rails, rule rows and pi-toolbox frame borders before they reach the clipboard; editor selections copy the draft's text, not the painted rows.
 - **Selection hint.** A selection that is not auto-copying shows exactly how many characters the copy key (`ctrl+x` by default, whatever `app.message.copy` is bound to) will copy, and a selection inside the editor names your editor — `ctrl+g to edit in nvim`.
-- **Click to expand one tool box.** A click on a box's hint row expands just that box (MCP boxes included), and the `(ctrl+o to collapse)` anchor row closes it again.
+- **Click to expand one component.** A plain click anywhere on a tool box — title, output, hint row, borders — toggles just that box (MCP boxes included); bash boxes, skill blocks, branch summaries, compaction summaries and custom entries count too. The direction comes from the hint row when one is on screen and from the component's own state otherwise, so a box with no hint left once expanded still closes on a click. Only a plain click toggles: dragging across a box still selects and copies, a double-click still word-selects, and a click on a link still opens it.
 - **Click to move the caret** in the input box; **backspace/delete remove a selected range**; the **wheel scrolls the draft** over the input box, and a draft taller than the box keeps the `ctrl+g` external-editor hint on screen.
 
 0.2.x's `fixedEditor` config block was renamed to `mouse` (migrated

package/extensions/starline/index.ts

@@ -4,7 +4,8 @@ import type {
 	KeybindingsManager,
 	Theme,
 } from "@earendil-works/pi-coding-agent";
-import { type EditorTheme, type TUI, TuiAltScreen } from "@earendil-works/pi-tui";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+import type { MouseEventsApi } from "@xzzpig/pi-mouse-events/api";
 import {
 	type ColorSourcesConfig,
 	type ContextStyle,
@@ -42,7 +43,8 @@ import { installFooter } from "./footer";
 import { buildSessionDurationLabel, invalidateUsageTotalsCache } from "./format";
 import { emptyGitStatus, readGitHost, readGitStatus } from "./git";
 import { LiveContextController } from "./live-context";
-import { installMouse } from "./mouse";
+import { installMouseFeaturesOn } from "./mouse";
+import { getMouseEventsApi } from "./mouse/api-consumer";
 import { setActiveEditor } from "./mouse/editor-mouse";
 import { readPackageVersionResult } from "./package-version";
 import { installPasteCollapse } from "./paste-collapse";
@@ -99,6 +101,7 @@ export default function (pi: ExtensionAPI) {
 	let lastProjectCwd: string | undefined;
 	let disposePasteCollapse: (() => void) | undefined;
 	let disposeMouse: (() => void) | undefined;
+	let lastTuiCtx: ExtensionContext | undefined;
 
 	const refresh = () => {
 		if (sessionLifecycle.isCurrent()) requestFooterRender?.();
@@ -236,44 +239,41 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	/**
-	 * Install the mouse features on `TuiAltScreen.prototype`.
+	 * Register Starline's mouse features with the `pi-mouse-events` extension.
 	 *
-	 * The prototype, not an instance: from 0.84 Pi hands extensions a Proxy over
-	 * the live renderer and swaps the renderer itself when the TUI mode changes,
-	 * so an instance captured at session start is not necessarily the one drawing
-	 * later. The shared prototype survives both.
-	 *
-	 * Reinstalling is already safe — `installPrototypePatch` keeps one wrapper per
-	 * adapter and only swaps the behaviour behind it — but disposing first keeps
-	 * exactly one live registration, so the disposer held here always removes
-	 * everything this extension put on the prototype.
+	 * That extension owns `TuiAltScreen.prototype` now — Starline wraps none of
+	 * it — so this only hands it behaviour: handlers for the wheel, press, and
+	 * copy slots, and the keyboard half of click-to-caret on
+	 * `ctx.ui.onTerminalInput`. Without the extension installed there is no
+	 * fallback and nothing is registered; the mouse features are simply off,
+	 * with one console note per process so the silence is diagnosable.
 	 *
 	 * `mouse.enabled` is read here rather than captured, and every sub-option is
-	 * read inside the patches themselves, so `/starline` toggles apply without a
-	 * restart.
+	 * read inside the handlers themselves, so `/starline` toggles apply without
+	 * a restart.
 	 */
-	const installMousePatches = () => {
+	const installMouseFeatures = (ctx: ExtensionContext) => {
 		uninstallMouse();
+		lastTuiCtx = ctx;
 		if (!getCurrentConfig().mouse.enabled) return;
-		// `TuiAltScreen` only ships with pi-tui >= 0.84.0 (the peer range below
-		// already says so). This guard is for environments that bypass peer
-		// resolution: fail with a readable hint instead of a TypeError on
-		// `TuiAltScreen.prototype`.
-		if (!TuiAltScreen) {
-			console.warn(
-				"starline: mouse support needs @earendil-works/pi-tui >= 0.84.0 (" +
-					"TuiAltScreen is not exported by the installed pi-tui). Upgrade Pi, " +
-					"or wait for your distribution to bundle a newer one.",
-			);
+		const api = getMouseEventsApi();
+		if (!api) {
+			warnMouseApiMissing();
 			return;
 		}
-		// Repaints are not wired from here: each patch asks its own receiver —
-		// the live renderer it is running inside — to render. Handing it the
-		// extension's `refresh` instead tied the pending hint to the footer's
-		// existence, and the hint is in the editor.
-		disposeMouse = installMouse(TuiAltScreen.prototype, { getConfig: getCurrentConfig });
+		disposeMouse = installMouseFeaturesOn(api, ctx, { getConfig: getCurrentConfig });
 	};
 
+	let mouseApiWarned = false;
+	function warnMouseApiMissing() {
+		if (mouseApiWarned) return;
+		mouseApiWarned = true;
+		console.info(
+			"[starline] mouse features need the pi-mouse-events extension " +
+				"(`pi install npm:@xzzpig/pi-mouse-events`); they are off until it is installed.",
+		);
+	}
+
 	/**
 	 * `editorCursor: "terminal"` hides the software cursor so the real one shows
 	 * through, which needs the hardware cursor to actually be on. Pi re-applies
@@ -484,7 +484,7 @@ export default function (pi: ExtensionAPI) {
 		syncFooterState(ctx);
 		stopProjectRefresh();
 		applyConfiguredUi(ctx);
-		installMousePatches();
+		installMouseFeatures(ctx);
 		refresh();
 	};
 
@@ -509,6 +509,7 @@ export default function (pi: ExtensionAPI) {
 			stopProjectRefresh();
 			requestFooterRender = undefined;
 			getActiveExtensionStatuses = () => new Map();
+			lastTuiCtx = undefined;
 			if (isTuiContext(ctx)) {
 				ctx.ui.setFooter(undefined);
 				const currentFactory = ctx.ui.getEditorComponent();
@@ -595,10 +596,10 @@ export default function (pi: ExtensionAPI) {
 		setExtensionStatusColorMode(key: string, colorMode: ExtensionStatusColorMode) {
 			currentConfig = saveExtensionStatusColorMode(key, colorMode);
 		},
-		setMouseConfig(patch: Partial<MouseConfig>, _ctx: ExtensionContext) {
+		setMouseConfig(patch: Partial<MouseConfig>, ctx: ExtensionContext) {
 			currentConfig = saveMousePatch(patch);
 			if (patch.enabled === true) {
-				installMousePatches();
+				installMouseFeatures(lastTuiCtx ?? ctx);
 			} else if (patch.enabled === false) {
 				uninstallMouse();
 			}

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

@@ -0,0 +1,31 @@
+/**
+ * The consumer-side accessor for the `pi-mouse-events` extension's API.
+ *
+ * All Starline needs from that package is its published runtime object, and
+ * the package publishes it under a process-global `Symbol.for` key precisely
+ * so consumers do not have to import it: Pi loads every extension through a
+ * jiti instance with `moduleCache: false`, so a static value import of
+ * `@xzzpig/pi-mouse-events/api` would both give Starline its own fresh copy
+ * of the module *and* make the whole extension fail to load when the package
+ * is not installed — the one situation this integration must survive
+ * gracefully. A type-only import carries the contract's types at development
+ * time; this duplicated key string is the only runtime surface, and
+ * `test/contract/mouse-api.test.ts` asserts it matches the real package's.
+ *
+ * `Symbol.for()` is process-global by spec, so the accessor observes exactly
+ * what the extension wrote, whatever module copy this file was loaded in.
+ */
+
+import type { MouseEventsApi } from "@xzzpig/pi-mouse-events/api";
+
+/**
+ * MUST match `MOUSE_EVENTS_API_KEY` in `@xzzpig/pi-mouse-events/api` — the
+ * contract test above is what keeps that true.
+ */
+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
+		| MouseEventsApi
+		| undefined;
+}

package/extensions/starline/mouse/capabilities.ts

@@ -1,31 +1,22 @@
 /**
- * What of Pi's renderer this build can actually reach.
+ * What of the live renderer Starline's mouse features 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.
+ * Starline no longer patches anything — the `pi-mouse-events` extension owns
+ * the prototype — so the probe is about *calling*, not replacing: every
+ * method a feature needs on the receiver must exist and be callable, probed
+ * structurally on the instance the extension hands over (`ctx.ui`, the Proxy
+ * that forwards to the live renderer). Signature drift is caught by the
+ * contract tests rather than guessed at here.
  *
- * `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.
- *
- * Since 0.84.4 the peer floor guarantees `copyActiveSelectionToClipboard`,
- * `getCopyOnSelect` and `hasActiveSelection` exist; the probe still runs so a
- * future Pi that moves them degrades feature-by-feature instead of breaking
- * the whole install.
+ * The `pi-mouse-events` API gates everything before this table runs: without
+ * it no feature registers at all (see `installMouseFeaturesOn`). The one API
+ * capability that varies on its own is the copy slot — the extension installs
+ * it only when `copyActiveSelectionToClipboard` exists (pi-tui ≥ 0.84.3) —
+ * so it arrives as `copySlotAvailable` rather than being probed here.
  */
 
-export type MouseCapability =
-	| "handleViewportInput"
-	| "routeWheel"
-	| "handleSelectionMouseEvent"
-	| "copyActiveSelectionToClipboard"
+/** The receiver methods the features call, probed on the live renderer. */
+export type MouseReceiverCapabilities =
 	| "getCopyOnSelect"
 	| "hasActiveSelection"
 	| "getSelectionBounds"
@@ -34,6 +25,8 @@ export type MouseCapability =
 	| "hasOverlay"
 	| "requestRender";
 
+export type MouseCapability = MouseReceiverCapabilities | "copySlot";
+
 export type MouseFeature =
 	| "selectionHint"
 	| "clickToExpandTools"
@@ -43,10 +36,6 @@ export type MouseFeature =
 	| "transcriptCleanCopy";
 
 const CAPABILITIES: readonly MouseCapability[] = [
-	"handleViewportInput",
-	"routeWheel",
-	"handleSelectionMouseEvent",
-	"copyActiveSelectionToClipboard",
 	"getCopyOnSelect",
 	"hasActiveSelection",
 	"getSelectionBounds",
@@ -54,19 +43,21 @@ const CAPABILITIES: readonly MouseCapability[] = [
 	"flash",
 	"hasOverlay",
 	"requestRender",
+	"copySlot",
 ];
 
 /**
- * Every capability a feature needs before it may install.
+ * Every capability a feature needs before it may register.
  *
  * 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.
+ * (see the header of `mouse/index.ts` before the clean-copy successor
+ * replaced it). A feature listed here is one `installMouseFeaturesOn`
+ * registers, and a table that claims a feature nothing registers is worse
+ * than no table.
  */
 const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
-	// Derived from Pi 0.84.4's own select-without-copy state: the hint shows
-	// only while the renderer is NOT auto-copying (`getCopyOnSelect` false) and
+	// Derived from Pi's own select-without-copy state: the hint shows only
+	// while the renderer is NOT auto-copying (`getCopyOnSelect` false) and
 	// something is actually selected (`hasActiveSelection`). The character
 	// count is computed from the live selection through `getSelectionBounds`
 	// and `getSelectionColumns`, matching the columns the copy itself would
@@ -79,74 +70,42 @@ const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
 		"getSelectionBounds",
 		"getSelectionColumns",
 	],
-	// 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 `copyActiveSelectionToClipboard` — the method Pi 0.84.4's
-	// Ctrl+X handler reaches (`handleCopyCommand` with `preferSelection`), so
-	// the clean copy answers exactly the copies that key performs — and reads
-	// the selection through `getSelectionBounds` to find out whether it is the
-	// editor's. `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: ["copyActiveSelectionToClipboard", "getSelectionBounds", "hasOverlay", "flash"],
-	// Shares the `copyActiveSelectionToClipboard` 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 its 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.
+	// The press arrives through the `pi-mouse-events` handler slot, which
+	// always exists once the API does; what this feature needs beyond that is
+	// `hasOverlay` — the same question Pi's own press path asks before
+	// resolving a scroll view, without which a click on a dialog would toggle
+	// whatever tool box happens to sit behind it — and `requestRender`, because
+	// consuming the press means Pi never reaches its own repaint for that
+	// event.
+	clickToExpandTools: ["hasOverlay", "requestRender"],
+	// Same shape as click-to-expand: the notch arrives through the handler
+	// slot, `hasOverlay` keeps a notch aimed at a dialog from scrolling the
+	// draft hidden behind it, and consuming the notch means `requestRender` is
+	// the only thing that draws the scrolled box.
+	editorWheelScroll: ["hasOverlay", "requestRender"],
+	// The press half rides the same slot as click-to-expand; the keyboard half
+	// (backspace/delete over a selection) rides `ctx.ui.onTerminalInput`, which
+	// every interactive session exposes. Range delete reads the selection
+	// through `getSelectionBounds`, and because it *consumes* the key — so
+	// Pi's `handleInput` never reaches its own repaint — `requestRender` is
+	// the only thing that draws the shortened draft.
+	editorClickToCaret: ["getSelectionBounds", "hasOverlay", "requestRender"],
+	// Registers an `addCopyHandler`; needs the extension's copy slot to exist
+	// (`copyActiveSelectionToClipboard`, pi-tui ≥ 0.84.3), reads the selection
+	// through `getSelectionBounds` to find out whether it is the editor's, and
+	// raises its own "Copied!" through `flash`. `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`, unlisted because
+	// `terminal` is a plain instance field — checked at the call site, where a
+	// terminal that cannot be written to makes the copy fall through to Pi.
+	editorBufferCopy: ["copySlot", "getSelectionBounds", "hasOverlay", "flash"],
+	// Shares the copy slot with editorBufferCopy. 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, and asks `hasOverlay`
+	// before trusting those rows.
 	transcriptCleanCopy: [
-		"copyActiveSelectionToClipboard",
+		"copySlot",
 		"getSelectionBounds",
 		"getSelectionColumns",
 		"hasOverlay",
@@ -154,41 +113,36 @@ const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
 	],
 };
 
-function isPatchable(prototype: object, name: string): boolean {
+function isCallable(receiver: 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;
+		return typeof (receiver as Record<string, unknown>)[name] === "function";
 	} catch {
-		// A prototype that throws on inspection is one we do not touch.
+		// A receiver that throws on inspection is one we do not touch.
 		return false;
 	}
 }
 
-export function probeCapabilities(prototype: object): ReadonlySet<MouseCapability> {
+export function probeCapabilities(receiver: object): ReadonlySet<MouseCapability> {
 	const found = new Set<MouseCapability>();
 	for (const capability of CAPABILITIES) {
-		if (isPatchable(prototype, capability)) found.add(capability);
+		if (capability === "copySlot") continue;
+		if (isCallable(receiver, capability)) found.add(capability);
 	}
 	return found;
 }
 
 export function enabledFeatures(
 	available: ReadonlySet<MouseCapability>,
+	copySlotAvailable: boolean,
 ): ReadonlySet<MouseFeature> {
+	const withSlot = new Set(available);
+	if (copySlotAvailable) withSlot.add("copySlot");
 	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);
+		if (needed.every((capability) => withSlot.has(capability))) enabled.add(feature);
 	}
 	return enabled;
 }