@xzzpig/pi-starline 0.1.0

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

@@ -0,0 +1,142 @@
+/**
+ * Where the input box is on screen, and which live editor is in it.
+ *
+ * A wheel notch has to be routed before it can be acted on, and routing it
+ * needs two facts Pi does not hand out: which component the draft belongs to,
+ * and which rows on screen that component drew.
+ *
+ * ## Finding the editor's rectangle
+ *
+ * The plan for this feature assumed the editor is a direct child of a stack and
+ * therefore carries its own `LayoutBox` — the one place in Pi's layout tree
+ * where `boxFor` would finally have a production caller. It is not, and
+ * `test/mouse/editor-wheel.test.ts` pins that against the real engine.
+ * `interactive-mode.js` mounts the editor in a `Container` (`tui.js:39`) and
+ * puts *the container* in the dock's `VStack`. `Container` carries no
+ * `LAYOUT_NODE`, so `layoutComponent` folds it and everything inside it into a
+ * single leaf box with `children: []` — exactly the finding
+ * `test/contract/transcript-layout.test.ts` recorded for the transcript.
+ * `boxFor(root, editor)` is therefore always `undefined`.
+ *
+ * What does work is the box one level up: the container's. Its rect is the
+ * editor's rows, because the container renders nothing but its children and
+ * holds exactly one. So the lookup here is still by identity — the identity of
+ * the live editor instance inside `Container.children` — rather than by
+ * position in the dock or by the shape of the rendered border. That
+ * distinction matters: the container also holds Pi's extension selector, input
+ * and alternate editor at various times (`interactive-mode.js:1918-2011`), and
+ * while one of those is up the draft is not on screen at all. Asking whether
+ * *this* editor is in there answers that for free.
+ *
+ * ## Finding the editor itself
+ *
+ * Nothing on Pi's renderer points at the editor: `TuiAltScreen` has no
+ * reference to one, and the extension API exposes the *factory*
+ * (`getEditorComponent`) rather than the instance it built. But Starline builds
+ * the instance itself, in `index.ts`'s editor factory, so the extension is the
+ * one thing in the process that already has it. It registers it here on the way
+ * out of the factory.
+ *
+ * Two references are registered, not one, because the mounted component and the
+ * scrollable editor are not always the same object. In the standalone path they
+ * are (`PolishedEditor` extends Pi's `Editor`); in the wrapped path Starline
+ * mounts a `WrappedPolishedEditor` that delegates by composition and exposes
+ * none of `state`, `buildVisualLineMap` or `scrollOffset`. Hit-testing needs
+ * the mounted one; scrolling needs the inner one.
+ */
+
+import { type BoxLike, boxesAt, boxMatching } from "./hit-test";
+
+export type WheelTarget = "editor" | "transcript";
+
+export type MountedEditor = {
+	/** The component in the layout — what a screen rectangle belongs to. */
+	component: unknown;
+	/**
+	 * The component that owns the draft's visual lines — what `editor-scroll.ts`
+	 * reads. In the wrapped path this is somebody else's editor, which may not
+	 * expose that surface at all; `scrollEditorBy` says so by returning false
+	 * and the notch falls through to the transcript.
+	 */
+	scrollable: unknown;
+};
+
+/**
+ * The editor Starline's factory built most recently, or undefined before the
+ * first one is built and after the extension is torn down.
+ *
+ * A module-level register rather than an `installMouse` dependency: the mouse
+ * patches live on Pi's *prototype* and outlive any one editor instance, while
+ * the editor is rebuilt whenever `setCustomEditorComponent` runs. Threading it
+ * through `installMouse` would mean re-installing every patch on every editor
+ * rebuild. This mirrors `activeSelectionHintText`'s register in `index.ts`.
+ */
+let active: MountedEditor | undefined;
+
+export function setActiveEditor(editor: MountedEditor | undefined): void {
+	active = editor;
+}
+
+export function activeEditor(): MountedEditor | undefined {
+	return active;
+}
+
+/** Whether `component` is a container the editor is currently mounted in. */
+function hosts(component: unknown, editor: unknown): boolean {
+	if (typeof component !== "object" || component === null) return false;
+	const children = (component as { children?: unknown }).children;
+	return Array.isArray(children) && children.includes(editor);
+}
+
+/**
+ * The box covering the editor's rows: its own if Pi ever gives it one, else
+ * the box of the container it is mounted in.
+ *
+ * The direct lookup is tried first and is not dead code waiting on a
+ * hypothetical: a Pi build that gave the editor a `LAYOUT_NODE`, or an
+ * embedding that put it straight into the dock stack, would produce exactly
+ * that box, and it is the more specific of the two answers.
+ */
+export function editorBoxFor(root: BoxLike | undefined, editor: unknown): BoxLike | undefined {
+	if (!root || editor === undefined || editor === null) return undefined;
+	return (
+		boxMatching(root, (component) => component === editor) ??
+		boxMatching(root, (component) => hosts(component, editor))
+	);
+}
+
+/**
+ * Whether the input box is what is painted at `(x, y)`.
+ *
+ * The box has to be under the pointer *and* actually painted there, which is
+ * why this asks `boxesAt` rather than testing the rectangle directly:
+ * `boxesAt` walks down from the root honouring each box's `clip`, so a dock
+ * squeezed out of the viewport cannot claim rows it is not drawing.
+ *
+ * Two features ask it — the wheel, for which notch belongs to the draft, and
+ * click-to-caret, for which press does.
+ */
+export function pointerOverEditor(
+	root: BoxLike | undefined,
+	editor: unknown,
+	x: number,
+	y: number,
+): boolean {
+	if (!root) return false;
+	const box = editorBoxFor(root, editor);
+	if (!box) return false;
+	return boxesAt(root, x, y).includes(box);
+}
+
+/**
+ * Whether a wheel notch at `(x, y)` belongs to the input box or to the
+ * transcript behind it.
+ */
+export function wheelTarget(
+	root: BoxLike | undefined,
+	editor: unknown,
+	x: number,
+	y: number,
+): WheelTarget {
+	return pointerOverEditor(root, editor, x, y) ? "editor" : "transcript";
+}

package/extensions/starline/mouse/editor-scroll.ts

@@ -0,0 +1,119 @@
+/**
+ * Wheel scrolling inside the editor box.
+ *
+ * Pi's editor keeps no scroll command of its own: its `scrollOffset` is
+ * re-derived from the caret on every render — see the editor component, which
+ * pulls the offset back whenever the caret would fall outside the window of
+ * `max(5, rows * 0.3)` visual lines. So moving the offset alone is undone by
+ * the very next frame; the caret has to come along, exactly as it would if you
+ * had held the arrow keys instead. That is what this does.
+ *
+ * Everything is probed before use and the whole thing is wrapped: when the
+ * editor is not the shape we expect, this reports failure and the wheel falls
+ * back to scrolling the transcript.
+ *
+ * The `editorWheelScroll` patch in `mouse/index.ts` drives it; it lives in its
+ * own module because `editor-caret.ts` shares the visual-line map it builds.
+ *
+ * @internal
+ */
+
+type VisualLine = { logicalLine: number; startCol: number; length: number };
+
+type ScrollableEditor = {
+	state: { lines: string[]; cursorLine?: number; cursorCol?: number };
+	buildVisualLineMap: (width: number) => VisualLine[];
+	scrollOffset?: number;
+	lastWidth?: number;
+	preferredVisualCol?: number | null;
+	snappedFromCursorCol?: number | null;
+};
+
+/** How many visual lines the editor shows, per its own render. */
+export function editorVisibleLines(terminalRows: number): number {
+	return Math.max(5, Math.floor(terminalRows * 0.3));
+}
+
+function asScrollableEditor(value: unknown): ScrollableEditor | null {
+	if (typeof value !== "object" || value === null) return null;
+	const editor = value as ScrollableEditor;
+	if (typeof editor.buildVisualLineMap !== "function") return null;
+	if (!editor.state || !Array.isArray(editor.state.lines)) return null;
+	return editor;
+}
+
+/** Which visual row the caret sits on, or -1 when it cannot be placed. */
+function cursorVisualRow(visualLines: VisualLine[], line: number, col: number): number {
+	let fallback = -1;
+	for (let row = 0; row < visualLines.length; row++) {
+		const visual = visualLines[row];
+		if (!visual || visual.logicalLine !== line) continue;
+		fallback = row;
+		if (col >= visual.startCol && col <= visual.startCol + visual.length) return row;
+	}
+	return fallback;
+}
+
+/**
+ * Scroll the editor by `delta` visual lines: negative shows earlier lines,
+ * positive later ones. Returns false when there is nothing to scroll — no
+ * scrollable content, or an editor we cannot read — so the caller can let the
+ * transcript have the wheel instead.
+ *
+ * Reaching the top or bottom of scrollable content still returns true: once the
+ * pointer is over an editor that scrolls, the wheel belongs to it, and chaining
+ * on to the transcript at the boundary would make the box feel like it slipped.
+ */
+export function scrollEditorBy(value: unknown, delta: number, terminalRows: number): boolean {
+	return scrollEditorWindow(value, delta, editorVisibleLines(terminalRows));
+}
+
+/**
+ * The same, for a caller that already knows how many rows the box shows — the
+ * box's own geometry, rather than Pi's formula for it.
+ */
+export function scrollEditorWindow(value: unknown, delta: number, visibleLines: number): boolean {
+	const editor = asScrollableEditor(value);
+	if (!editor) return false;
+	if (visibleLines < 1) return false;
+
+	try {
+		const width = Math.max(1, editor.lastWidth ?? 80);
+		const visualLines = editor.buildVisualLineMap(width);
+		if (!Array.isArray(visualLines) || visualLines.length === 0) return false;
+
+		const maxOffset = visualLines.length - visibleLines;
+		// The whole input fits: there is no scrolling to be done here.
+		if (maxOffset <= 0) return false;
+
+		const current = Math.max(0, Math.min(editor.scrollOffset ?? 0, maxOffset));
+		const next = Math.max(0, Math.min(current + delta, maxOffset));
+		if (next === current) return true;
+		editor.scrollOffset = next;
+
+		// Drag the caret into the new window, or the next render snaps back.
+		const cursorLine = editor.state.cursorLine ?? 0;
+		const cursorCol = editor.state.cursorCol ?? 0;
+		const row = cursorVisualRow(visualLines, cursorLine, cursorCol);
+		if (row < 0) return true;
+
+		const first = next;
+		const last = next + visibleLines - 1;
+		if (row >= first && row <= last) return true;
+
+		const targetRow = row < first ? first : last;
+		const target = visualLines[targetRow];
+		if (!target) return true;
+		// Keep the column where it was, as far as the target line allows.
+		const offsetInLine = Math.max(0, cursorCol - (visualLines[row]?.startCol ?? 0));
+		editor.state.cursorLine = target.logicalLine;
+		editor.state.cursorCol = target.startCol + Math.min(offsetInLine, target.length);
+		// Clear the sticky column, or the next up/down press jumps back to
+		// wherever the caret used to be rather than where it was just put.
+		editor.preferredVisualCol = null;
+		editor.snappedFromCursorCol = null;
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/starline/mouse/editor-text-cursor.ts

@@ -0,0 +1,209 @@
+/**
+ * Map between the editor's rendered rows and its own text: resolve a row and
+ * column to a point in the buffer, read a row's text back out, and move the
+ * cursor to a point the user clicked.
+ *
+ * Pi's editor lays its text out onto visual lines and keeps that mapping to
+ * itself, and offers a way to read the cursor but not to move it. So this
+ * reaches into the live editor instance for both. Everything is probed before
+ * use and the whole thing is wrapped: when the shape is not what we expect —
+ * a Pi upgrade, a different editor implementation — it reports failure and the
+ * click falls back to doing nothing, rather than taking the editor down.
+ *
+ * Ported from pi-powerline-footer, where this has been in daily use.
+ *
+ * @internal
+ */
+
+import { displayColumnToStringIndex } from "./editor-hit-test";
+
+type VisualLine = { logicalLine: number; startCol: number; length: number };
+
+export type EditorInternals = {
+	state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+	buildVisualLineMap?: (width: number) => VisualLine[];
+	scrollOffset?: number;
+	lastWidth?: number;
+	preferredVisualCol?: number | null;
+	snappedFromCursorCol?: number | null;
+	setCursorCol?: (col: number) => void;
+	pushUndoSnapshot?: () => void;
+	cancelAutocomplete?: () => void;
+	exitHistoryBrowsing?: () => void;
+	onChange?: (text: string) => void;
+	lastAction?: unknown;
+};
+
+/** A point in the editor's own text: which logical line, and where in it. */
+export type EditorTextPoint = { line: number; index: number };
+
+function asEditorInternals(value: unknown): EditorInternals | null {
+	if (typeof value !== "object" || value === null) return null;
+	const editor = value as EditorInternals;
+	if (typeof editor.buildVisualLineMap !== "function") return null;
+	if (!editor.state || !Array.isArray(editor.state.lines)) return null;
+	return editor;
+}
+
+/** Whether this editor exposes enough for click-to-position to work at all. */
+export function supportsEditorTextCursor(value: unknown): boolean {
+	return asEditorInternals(value) !== null;
+}
+
+/**
+ * Find the object that actually holds the editor state.
+ *
+ * What the compositor tracks is the *container* Pi puts the editor in, and
+ * Starline may itself wrap the editor in a decorator. So walk down through
+ * children and wrapped bases until something answers the probe. The visited
+ * set keeps a cyclic component graph from looping.
+ */
+export function resolveEditorInternals(root: unknown): unknown {
+	const seen = new Set<unknown>();
+	const queue: unknown[] = [root];
+
+	while (queue.length > 0) {
+		const node = queue.shift();
+		if (typeof node !== "object" || node === null || seen.has(node)) continue;
+		seen.add(node);
+		if (supportsEditorTextCursor(node)) return node;
+
+		const record = node as { base?: unknown; children?: unknown };
+		if (record.base) queue.push(record.base);
+		if (Array.isArray(record.children)) queue.push(...record.children);
+	}
+
+	return undefined;
+}
+
+/** The editor's visual line map, or null when it cannot be read. */
+function visualLineMap(editor: EditorInternals, fallbackWidth: number): VisualLine[] | null {
+	const width = Math.max(1, editor.lastWidth ?? fallbackWidth);
+	const visualLines = editor.buildVisualLineMap?.(width);
+	return Array.isArray(visualLines) ? visualLines : null;
+}
+
+/**
+ * Resolve an absolute visual row/column of the editor to a point in its text.
+ *
+ * Absolute means an index into the editor's whole visual line map, not into the
+ * rows currently on screen. Selection works in these coordinates so that
+ * scrolling the box does not move the text a selection is anchored to.
+ *
+ * Returns null when the point is out of range or the editor cannot be read.
+ */
+export function resolveEditorTextPointAt(
+	value: unknown,
+	absoluteRow: number,
+	visualCol: number,
+	fallbackWidth = 80,
+): EditorTextPoint | null {
+	const editor = asEditorInternals(value);
+	if (!editor?.state?.lines) return null;
+
+	try {
+		const visualLines = visualLineMap(editor, fallbackWidth);
+		const visual = visualLines?.[absoluteRow];
+		if (!visual) return null;
+
+		const text = editor.state.lines[visual.logicalLine] ?? "";
+		const index = displayColumnToStringIndex(text, visual.startCol, visualCol);
+		return {
+			line: visual.logicalLine,
+			index: Math.max(visual.startCol, Math.min(index, visual.startCol + visual.length)),
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve a visual row/column of the *rendered* editor to a point in its text —
+ * a row as counted from the top of the box, which is what a click gives.
+ * Returns null when the point is out of range or the editor cannot be read.
+ */
+export function resolveEditorTextPoint(
+	value: unknown,
+	visualRow: number,
+	visualCol: number,
+	fallbackWidth = 80,
+): EditorTextPoint | null {
+	const editor = asEditorInternals(value);
+	if (!editor) return null;
+	return resolveEditorTextPointAt(
+		value,
+		visualRow + (editor.scrollOffset ?? 0),
+		visualCol,
+		fallbackWidth,
+	);
+}
+
+/**
+ * Plain text of one absolute visual row of the editor, or null when the row is
+ * out of range or the editor cannot be read.
+ *
+ * This is the editor's own buffer, not the rendered row: it carries no cursor
+ * highlight and no frame, and it is there whether the row is on screen or
+ * scrolled out of the box — which is what lets a selection reach past what the
+ * box shows.
+ */
+export function editorVisualRowText(
+	value: unknown,
+	absoluteRow: number,
+	fallbackWidth = 80,
+): string | null {
+	const editor = asEditorInternals(value);
+	if (!editor?.state?.lines) return null;
+
+	try {
+		const visualLines = visualLineMap(editor, fallbackWidth);
+		const visual = visualLines?.[absoluteRow];
+		if (!visual) return null;
+		const text = editor.state.lines[visual.logicalLine] ?? "";
+		return text.slice(visual.startCol, visual.startCol + visual.length);
+	} catch {
+		return null;
+	}
+}
+
+/** How many visual rows the editor's text lays out to, or 0 when unreadable. */
+export function editorVisualRowCount(value: unknown, fallbackWidth = 80): number {
+	const editor = asEditorInternals(value);
+	if (!editor) return 0;
+	try {
+		return visualLineMap(editor, fallbackWidth)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}
+
+/** The editor's current scroll position, in visual rows from the top. */
+export function editorScrollOffset(value: unknown): number {
+	const editor = asEditorInternals(value);
+	const offset = editor?.scrollOffset;
+	return typeof offset === "number" && Number.isFinite(offset) ? Math.max(0, offset) : 0;
+}
+
+/**
+ * Place the cursor at a visual row/column of the editor's own text.
+ * Returns false when the point is out of range or the editor cannot be driven.
+ */
+export function positionEditorTextCursor(
+	value: unknown,
+	visualRow: number,
+	visualCol: number,
+	fallbackWidth = 80,
+): boolean {
+	const editor = asEditorInternals(value);
+	if (!editor?.state) return false;
+	const point = resolveEditorTextPoint(value, visualRow, visualCol, fallbackWidth);
+	if (!point) return false;
+
+	editor.state.cursorLine = point.line;
+	editor.state.cursorCol = point.index;
+	// Clear the sticky column, or the next up/down press jumps back to
+	// wherever the cursor used to be rather than where it was just put.
+	editor.preferredVisualCol = null;
+	editor.snappedFromCursorCol = null;
+	return true;
+}

package/extensions/starline/mouse/editor-text-edit.ts

@@ -0,0 +1,90 @@
+/**
+ * Delete a selected range from Pi's editor.
+ *
+ * Pi's editor has no selection of its own, so it has nothing to delete from and
+ * no API for doing it. `setText` is not a way in either: it clears the paste map
+ * and counter, which would turn every collapsed `[paste #N]` marker in the box
+ * into text that expands to nothing on submit. So the range is spliced out of
+ * `state.lines` directly, the same way the paste expansion does it, with an undo
+ * snapshot pushed first so ctrl+z still puts it back.
+ *
+ * Everything is probed before use: an editor that does not look like Pi's is
+ * left alone and the key falls through to Pi.
+ *
+ * @internal
+ */
+
+import {
+	type EditorInternals,
+	type EditorTextPoint,
+	resolveEditorTextPointAt,
+} from "./editor-text-cursor";
+
+function asEditorInternals(value: unknown): EditorInternals | null {
+	if (typeof value !== "object" || value === null) return null;
+	const editor = value as EditorInternals;
+	if (typeof editor.buildVisualLineMap !== "function") return null;
+	if (!editor.state || !Array.isArray(editor.state.lines)) return null;
+	return editor;
+}
+
+function comparePoints(a: EditorTextPoint, b: EditorTextPoint): number {
+	return a.line === b.line ? a.index - b.index : a.line - b.line;
+}
+
+/**
+ * Delete the text between two points of the editor, given as absolute visual
+ * row/column pairs — rows counted through the editor's whole text rather than
+ * from the top of the box, which is how a selection stores them so that
+ * scrolling cannot move it. `end` is exclusive. Returns false without touching
+ * anything when the range cannot be resolved or comes out empty.
+ */
+export function deleteEditorVisualRange(
+	value: unknown,
+	start: { visualRow: number; visualCol: number },
+	end: { visualRow: number; visualCol: number },
+	fallbackWidth = 80,
+): boolean {
+	const editor = asEditorInternals(value);
+	const lines = editor?.state?.lines;
+	if (!editor?.state || !lines) return false;
+
+	try {
+		const a = resolveEditorTextPointAt(editor, start.visualRow, start.visualCol, fallbackWidth);
+		const b = resolveEditorTextPointAt(editor, end.visualRow, end.visualCol, fallbackWidth);
+		if (!a || !b) return false;
+
+		const [from, to] = comparePoints(a, b) <= 0 ? [a, b] : [b, a];
+		if (comparePoints(from, to) === 0) return false;
+		if (from.line >= lines.length || to.line >= lines.length) return false;
+
+		editor.cancelAutocomplete?.call(editor);
+		editor.exitHistoryBrowsing?.call(editor);
+		editor.lastAction = null;
+		editor.pushUndoSnapshot?.call(editor);
+
+		const head = (lines[from.line] ?? "").slice(0, from.index);
+		const tail = (lines[to.line] ?? "").slice(to.index);
+		const next = [...lines.slice(0, from.line), head + tail, ...lines.slice(to.line + 1)];
+		editor.state.lines = next.length === 0 ? [""] : next;
+
+		editor.state.cursorLine = from.line;
+		if (typeof editor.setCursorCol === "function") {
+			editor.setCursorCol.call(editor, from.index);
+		} else {
+			editor.state.cursorCol = from.index;
+		}
+		// The sticky column belongs to wherever the cursor used to be.
+		editor.preferredVisualCol = null;
+		editor.snappedFromCursorCol = null;
+
+		// Anything watching the text — autocomplete, hints — hears about it the
+		// same way it would for a keystroke. Paste entries whose marker was inside
+		// the deleted range are left in the map: they are unreachable, and Pi only
+		// ever expands markers it finds in the text.
+		editor.onChange?.call(editor, editor.state.lines.join("\n"));
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/starline/mouse/hint.ts

@@ -0,0 +1,14 @@
+/**
+ * The right-hand side of the editor's metadata row.
+ *
+ * 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.
+ */
+export function composeHints(
+	pasteHint: string | null,
+	selectionHint: string | null,
+): string | null {
+	if (pasteHint && selectionHint) return `${pasteHint} ⋅ ${selectionHint}`;
+	return pasteHint ?? selectionHint ?? null;
+}