@xzzpig/pi-starline 0.1.0

package/extensions/starline/mouse/selection-state.ts

@@ -0,0 +1,68 @@
+import { basename } from "node:path";
+
+/**
+ * The one piece of selection state Starline owns.
+ *
+ * Pi holds the anchor, the focus and the granularity; this holds only whether a
+ * released selection is still waiting to be copied. Keeping it this small is
+ * what the 0.2.0 controller could not do, because back then Pi had no selection
+ * at all.
+ */
+export class SelectionPendingState {
+	private characters = 0;
+	/**
+	 * `keyText("app.editor.external")`, resolved at arm time, when the pending
+	 * selection is the editor's. Editor selections cannot grow past the visible
+	 * window (there is no drag-scroll), so the hint points at the external
+	 * editor as the way to act on the whole draft.
+	 */
+	private externalEditorKey: string | undefined;
+
+	arm(characters: number, externalEditorKey?: string): void {
+		this.characters = characters > 0 ? characters : 0;
+		this.externalEditorKey = this.characters > 0 ? externalEditorKey : undefined;
+	}
+
+	clear(): void {
+		this.characters = 0;
+		this.externalEditorKey = undefined;
+	}
+
+	get pending(): { characters: number; externalEditorKey?: string } | undefined {
+		return this.characters > 0
+			? { characters: this.characters, externalEditorKey: this.externalEditorKey }
+			: undefined;
+	}
+}
+
+export function selectionHintText(
+	state: SelectionPendingState,
+	editorName: string | null = null,
+): string | null {
+	const pending = state.pending;
+	if (!pending) return null;
+	const noun = pending.characters === 1 ? "character" : "characters";
+	const base = `${pending.characters} ${noun} selected, ctrl+c to copy`;
+	return pending.externalEditorKey
+		? `${base} ⋅ ${pending.externalEditorKey} to edit in ${editorName ?? "$EDITOR"}`
+		: base;
+}
+
+/**
+ * The user's external editor, for the "edit in …" hints.
+ *
+ * `$EDITOR` is a shell variable; the hint must say what it expands to, or a
+ * reader stares at a literal `$EDITOR`. `$VISUAL` outranks `$EDITOR` (the
+ * usual convention: VISUAL is the full-screen one), the first word of the
+ * value is the command, and its basename is what reads well in a hint —
+ * "nvim", not "/opt/homebrew/bin/nvim". Null when neither variable is set;
+ * callers keep the literal `$EDITOR` then, which is itself the hint that
+ * nothing is configured.
+ */
+export function externalEditorName(env: NodeJS.ProcessEnv = process.env): string | null {
+	const value = env.VISUAL || env.EDITOR;
+	if (!value) return null;
+	const command = value.trim().split(/\s+/)[0];
+	if (!command) return null;
+	return basename(command);
+}

package/extensions/starline/mouse/tool-box.ts

@@ -0,0 +1,290 @@
+/**
+ * Expanding one tool box by clicking it.
+ *
+ * `ctrl+o` toggles every box in the transcript at once, which is a screenful
+ * for the one line of output you wanted. This resolves the component under a
+ * mouse press and, when the press landed on that component's *hint row*,
+ * toggles just it.
+ *
+ * ## Why the hint row is the only target
+ *
+ * The plan for this feature started as "click the box's border". Pi 0.84's own
+ * tool boxes have no border: there is not a single box-drawing character
+ * anywhere in `pi-coding-agent`'s tool rendering, and a collapsed box is a
+ * plain `Container` of preview lines with an inline hint. The `╭─╮ │ ╰─╯` in a
+ * real session comes from `pi-toolbox`, a separate extension that patches
+ * `ToolExecutionComponent.prototype.render`. So a border is conditional on
+ * what else is installed and cannot be the target — and inferring one from the
+ * rendered rows is exactly what frame-free selection was cut for.
+ *
+ * The hint row can be. Pi renders it through `keyHint("app.tools.expand",
+ * description)` (`keybinding-hints.js`), which is `theme.fg("dim", keyText) +
+ * theme.fg("muted", " " + description)`, and every call site wraps it in
+ * parentheses:
+ *
+ * - `bash-execution.js:140,143` — `(ctrl+o to collapse)` when expanded,
+ *   `... 3 more lines (ctrl+o to expand)` when collapsed.
+ * - `core/tools/{bash,find,grep,ls,read,write}.js` — `... (N more lines,
+ *   ctrl+o to expand)`.
+ * - `read.js:91`, `skill-invocation-message.js:42`,
+ *   `branch-summary-message.js:39`, `compaction-summary-message.js:40` —
+ *   `(ctrl+o to expand)` on the title line.
+ *
+ * The description carries the *direction*: `to expand` when collapsed, `to
+ * collapse` when expanded. That is what this module toggles on, rather than
+ * tracking expansion itself — a `WeakMap` of "what I last set" would desync
+ * the first time `ctrl+o` toggled everything behind its back, whereas the row
+ * on screen is by definition current.
+ *
+ * ## Why resolution goes through the component tree
+ *
+ * `layoutComponent` builds a child box only for a component carrying a
+ * `LAYOUT_NODE`, and only `Stack` and `ScrollView` have one. Every message
+ * component extends `Container`, which has none, so the whole transcript is a
+ * single leaf box and `boxesAt` can never return a tool box. The layout tree
+ * is used for exactly what it does know — which scroll view is under the
+ * pointer, and where content row 0 sits on screen — and ownership below that
+ * comes from `component-tree.ts`. `test/contract/transcript-layout.test.ts`
+ * pins both halves against pi-tui's real engine.
+ *
+ * ## What this deliberately does not do
+ *
+ * Nothing here looks at how a component *renders* to decide what it is:
+ * `isExpandableComponent` asks whether `setExpanded` is callable, and the hint
+ * rule is scoped to that component's own rows. An ordinary message that quotes
+ * the hint — an assistant explaining `ctrl+o`, a paste of these very docs — is
+ * a `Text` or a `Markdown` with no `setExpanded` anywhere in its path, so it
+ * resolves to nothing and the press starts a selection as usual.
+ *
+ * ## Two accepted limitations
+ *
+ * Both are known, both were weighed, and neither has a fix worth its cost.
+ * They are recorded here and in `docs/configuration.md` because a user meets
+ * them before they meet any of the reasoning above.
+ *
+ * **1. Clicking cannot always collapse what it expanded.** The premise that
+ * "the hint row exists in both states, so one rule covers both directions" is
+ * only true of `bash-execution` and of `tool-execution` results that still
+ * have a preview to hide. For everything else Pi renders the hint *only while
+ * collapsed*, so expanding it removes the very row that would close it again:
+ *
+ * - `core/tools/{read,grep,ls,write,find}.js` append the hint inside `if
+ *   (remaining > 0)`, and expanding sets `maxLines` to `lines.length`, so
+ *   `remaining` becomes 0 and the row is not emitted at all (`read.js:113-118`
+ *   is the clearest instance).
+ * - `skill-invocation-message.js:42`, `branch-summary-message.js:39` and
+ *   `compaction-summary-message.js:40` build the hint in their `else` branch,
+ *   i.e. only when `this.expanded` is false.
+ *
+ * For the first group there is a way back: current `pi-toolbox` appends a
+ * `(ctrl+o to collapse)` anchor row as the last line inside the frame of an
+ * expanded `ToolExecutionComponent` — the same text `bash-execution` renders
+ * natively — and the hint rule above matches it exactly as it matches Pi's
+ * own rows, because it is the component's own rendered row. That closes
+ * `read`/`grep`/`ls`/`write`/`find` boxes with one click. The second group
+ * (skill, branch and compaction summaries) keeps the limitation: no anchor
+ * exists for them, `ctrl+o` (which closes everything) is the way back, and
+ * inventing a second target (the title line, the first output row) would
+ * mean guessing at a component's layout, which is the inference this module
+ * exists to avoid. Without `pi-toolbox` installed the first group keeps the
+ * limitation too — no anchor is rendered, and nothing here invents one.
+ *
+ * **2. A box's own output can read like its hint.** The component scoping
+ * above stops a *different* message from being clickable, but not the box's
+ * own body: a line inside an expandable component that literally contains
+ * `(ctrl+o to expand)` — `cat` of a file documenting the keybinding, a
+ * transcript of this very docstring — is indistinguishable from the real hint,
+ * because Pi renders the box's output and the box's hint through the same
+ * `Text` with the same structure and only different theme colours. Matching
+ * the colours instead would make the rule depend on the user's theme.
+ * Accepted: the worst case is that a click on a box opens the box it is
+ * already inside — no crash, no lost input, and the same click a row above or
+ * below behaves normally.
+ */
+
+import { keyText } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, stripTerminalSequences } from "@earendil-works/pi-tui";
+import { createComponentTree, isComponentLike, isExpandableComponent } from "./component-tree";
+import { type BoxLike, boxesAt, scrollContentLinesFor, scrollContentOrigin } from "./hit-test";
+
+/** The slice of a Pi message component this module calls. */
+export type ExpandableComponent = { setExpanded(expanded: boolean): void };
+
+export type ExpandTarget = {
+	component: ExpandableComponent;
+	/** What `setExpanded` should be called with — the opposite of today. */
+	expanded: boolean;
+};
+
+export type ExpandLookup = {
+	/** `currentLayout.root`, or undefined before the first frame. */
+	root: BoxLike | undefined;
+	/** `keyText("app.tools.expand")` for this session; "" when unbound. */
+	keyText: string;
+};
+
+const KEYBINDING = "app.tools.expand";
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// One press asks one question, but the pattern is the same on every press of a
+// session, so it is built once per distinct key text rather than per call.
+let cachedKeyText: string | undefined;
+let cachedPattern: RegExp | undefined;
+
+function hintPattern(keyText: string): RegExp {
+	if (cachedPattern && cachedKeyText === keyText) return cachedPattern;
+	// `\([^()]*` is the parenthesis Pi always opens before the hint, with
+	// whatever prefix the call site put inside it ("... 12 more lines, ").
+	// Case-insensitive: pi-mcp-adapter renders its collapsed-result hint as
+	// `(Ctrl+O to expand)` — capitalized, unlike the `ctrl+o` Pi's own
+	// `keyText` yields — and a case-sensitive match declined the press, so MCP
+	// tool boxes were the one box a click could not open. Widening the match
+	// only reaches rows an expandable component renders about its own key, so
+	// the cost is the same accepted false positive as limitation 2 above.
+	cachedPattern = new RegExp(`\\([^()]*${escapeRegExp(keyText)} to (expand|collapse)\\)`, "i");
+	cachedKeyText = keyText;
+	return cachedPattern;
+}
+
+/**
+ * Whether `line` is Pi's expand hint, and which way clicking it goes.
+ *
+ * The line arrives with theme colours in it, so it is stripped the same way
+ * Pi's own `getWordSelection` strips a selection source line. An empty
+ * `keyText` declines everything: with no key bound the pattern would collapse
+ * to `(… to expand)` and start matching ordinary prose.
+ */
+export function expandHintAction(line: string, keyText: string): "expand" | "collapse" | undefined {
+	if (!keyText) return undefined;
+	const match = hintPattern(keyText).exec(stripTerminalSequences(line));
+	if (!match) return undefined;
+	return match[1] === "collapse" ? "collapse" : "expand";
+}
+
+/**
+ * The keys spelled the way the hint on screen spells them.
+ *
+ * The primary source is `pi-coding-agent`'s own exported `keyText` — literally
+ * the function `keyHint` calls to build the text this module then matches, so
+ * there is no second formatting rule to drift (it is `keyText` that turns
+ * `alt` into `option` on macOS and joins alternatives with "/"), and no second
+ * keybinding registry to disagree.
+ *
+ * That last point is not theoretical. `getKeybindings()` is a *singleton* per
+ * copy of pi-tui, and a copy is per `node_modules` tree: in this repo
+ * `pi-coding-agent` nests its own pi-tui, so the registry Starline's direct
+ * import reaches is not the registry the hints are rendered from. Production
+ * resolves both to Pi's own copy, but reading the value through the same
+ * package that renders it makes the question moot instead of assumed.
+ *
+ * pi-tui's registry is kept as a fallback for the case where `keyText` yields
+ * nothing — which also means nothing is on screen to match, so the fallback
+ * can only ever turn a non-match into a non-match. Both routes return "" when
+ * `app.tools.expand` is unbound, and `expandHintAction` reads "" as "no hint
+ * rule at all" rather than as a wildcard.
+ */
+export function expandKeyText(): string {
+	return keyTextFor(KEYBINDING);
+}
+
+/**
+ * `keyText(keybinding)` with the registry fallback, shared by every feature
+ * that quotes a key on screen. See `expandKeyText` for why the primary route
+ * is pi-coding-agent's own function rather than this repo's registry.
+ */
+export function keyTextFor(keybinding: string): string {
+	try {
+		const rendered = keyText(keybinding as never);
+		if (typeof rendered === "string" && rendered.length > 0) return rendered;
+	} catch {
+		// A Pi build that has moved this function is one where quoting the key
+		// simply shows nothing; it is never a reason to break a mouse feature.
+	}
+	return fallbackKeyText(keybinding);
+}
+
+/**
+ * `keyText` re-derived from pi-tui's registry: keys joined with "/", `alt`
+ * shown as `option` on macOS, matching `formatKeyText` in
+ * `keybinding-hints.js`.
+ */
+function fallbackKeyText(keybinding: string): string {
+	try {
+		const bound: unknown = getKeybindings().getKeys(keybinding as never);
+		if (!Array.isArray(bound) || bound.length === 0) return "";
+		const keys = bound.filter((key): key is string => typeof key === "string");
+		return keys
+			.map((key: string) =>
+				key
+					.split("+")
+					.map((part) =>
+						process.platform === "darwin" && part.toLowerCase() === "alt" ? "option" : part,
+					)
+					.join("+"),
+			)
+			.join("/");
+	} catch {
+		return "";
+	}
+}
+
+/** The innermost scroll view whose box contains the screen cell. */
+function scrollViewAt(root: BoxLike, x: number, y: number): unknown {
+	let found: unknown;
+	for (const box of boxesAt(root, x, y)) {
+		const scrollView = (box as { scrollView?: unknown }).scrollView;
+		if (scrollView !== undefined) found = scrollView;
+	}
+	return found;
+}
+
+/**
+ * The expandable component whose hint row is at screen cell (`x`, `y`), or
+ * undefined when that cell is anything else.
+ *
+ * Resolution is done end to end here and thrown away: the component tree it
+ * builds holds no invalidation and a running tool re-renders under it (a
+ * `BashExecutionComponent` carries a ticking `Loader`), so the answer is only
+ * true of the frame that is on screen at this instant. Callers act on it
+ * inside the same press or not at all.
+ */
+export function expandTargetAt(
+	lookup: ExpandLookup,
+	x: number,
+	y: number,
+): ExpandTarget | undefined {
+	// Renamed on the way out of `lookup` so it cannot be read as this module's
+	// imported `keyText` function.
+	const { root, keyText: keys } = lookup;
+	if (!root || !keys) return undefined;
+
+	const scrollView = scrollViewAt(root, x, y);
+	if (scrollView === undefined) return undefined;
+	const lines = scrollContentLinesFor(root, scrollView);
+	const origin = scrollContentOrigin(root, scrollView);
+	if (!lines || !origin) return undefined;
+	if (!isComponentLike(origin.component)) return undefined;
+
+	// The content box is laid out at `viewportY - scrollTop`, so a screen row
+	// becomes a content row by subtracting its origin — the relation pinned in
+	// `test/contract/transcript-layout.test.ts`.
+	const row = y - origin.rect.y;
+	if (row < 0 || row >= lines.length) return undefined;
+
+	const tree = createComponentTree(origin.component, origin.rect.width, lines);
+	const path = tree.pathAt(row);
+	for (let index = path.length - 1; index >= 0; index--) {
+		const span = path[index];
+		if (!isExpandableComponent(span.component)) continue;
+		// The hint is matched against this component's own rendered row, not
+		// against the transcript, so nothing outside the box it would toggle can
+		// stand in for its hint.
+		const action = expandHintAction(span.lines[row - span.start] ?? "", keys);
+		if (!action) return undefined;
+		return { component: span.component as ExpandableComponent, expanded: action === "expand" };
+	}
+	return undefined;
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Strips decoration out of a transcript selection before it reaches the
+ * clipboard.
+ *
+ * Pi's `copySelectionToClipboard` copies *rendered* rows. In the transcript
+ * those rows carry chrome that two components paint around their content:
+ *
+ * - Starline's own user messages (`user-message.ts`): a full-width `─` rule
+ *   above and below, and every content row prefixed with the configured rail
+ *   glyph plus a space (`│ hello`).
+ * - `pi-toolbox`'s tool box frames (`frame.ts`): rounded corners
+ *   (`╭──╮` / `╰──╯`) and every content row wrapped in verticals
+ *   (`│ hello │`).
+ * - pi-coding-agent's `DynamicBorder` (bash boxes) paints the same full-width
+ *   `─` rule — but bash content rows start with a space, not the rail
+ *   (`bash-execution.js` renders them with paddingX=1), so under the default
+ *   rail the pair below never forms and a bash box copies verbatim. Only in
+ *   `copyFriendly` mode (empty rail prefix), where the rule pair alone
+ *   decides, do its borders come off. Its content is never touched either
+ *   way.
+ *
+ * The clipboard should hold the content, not the chrome. The frame-free
+ * selection task that was cut from 0.3.0 tried to do this by *inferring* where
+ * a frame was from rendered text alone, and every discriminator it tried
+ * produced a new edge case — a frame is not a structural concept in Pi. This
+ * module therefore recognises only the exact markers above: a rounded-corner
+ * pair of equal width, and a full-width rule pair whose every inner row
+ * carries the configured rail prefix. Anything else — a markdown table with
+ * its square `┌┬┐` corners, a blockquote's `│ ` gutter, a horizontal rule the
+ * assistant actually wrote — is content and passes through byte-identical.
+ *
+ * Everything here is a pure function over strings; the Pi-facing wiring
+ * (selection bounds, column mapping, the OSC 52 write) lives in `index.ts`.
+ */
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+
+/**
+ * One entry per selected row. `null` drops the row entirely — it was pure
+ * decoration (a frame edge or border rule). Otherwise `text` is the row's
+ * ANSI-free content and `leftTrim` the number of *visible columns* removed
+ * from its left edge, which the caller subtracts from the selection columns
+ * so a drag that started mid-row still lands on the same character.
+ */
+export type CleanedRow = { text: string; leftTrim: number } | null;
+
+export type CleanedRows = {
+	rows: CleanedRow[];
+	/**
+	 * False when no selected row carried any recognised decoration. The caller
+	 * falls back to Pi's verbatim copy in that case, so a selection with
+	 * nothing to clean takes exactly the path it always did.
+	 */
+	changed: boolean;
+};
+
+/** A full-width rule: Starline's user message border, `DynamicBorder`. */
+const RULE_ROW_RE = /^─+$/;
+/** pi-toolbox's rounded frame edges. Square corners are content (tables). */
+const FRAME_OPEN_RE = /^╭─*╮$/;
+const FRAME_CLOSE_RE = /^╰─*╯$/;
+
+function strippedRow(lines: readonly string[], cache: string[], row: number): string {
+	let text = cache[row];
+	if (text === undefined) {
+		text = stripTerminalSequences(lines[row] ?? "");
+		cache[row] = text;
+	}
+	return text;
+}
+
+/**
+ * Classifies every row of `lines`, then cleans the rows in
+ * `[startRow, endRow]`. The scan covers the whole buffer rather than the
+ * selection because a drag that starts inside a box never contains the box's
+ * own edges; whether a row is framed is a property of rows the selection may
+ * not touch.
+ */
+export function cleanTranscriptRows(
+	lines: readonly string[],
+	startRow: number,
+	endRow: number,
+	railGlyph: string,
+): CleanedRows {
+	const cache: string[] = new Array(lines.length);
+	/** Rows to drop: paired frame edges and paired border rules. */
+	const dropped = new Set<number>();
+	/** pi-toolbox frame content rows: strip one `│` from each side. */
+	const frameContent = new Set<number>();
+	/** Starline user message rows: strip the rail prefix. */
+	const railContent = new Set<number>();
+
+	// Pass 1 — rounded frames. Edges pair strictly by equal width, inner rows
+	// are content. A rounded box drawn inside bash output can mis-pair, but the
+	// rows it would swallow are inside a real frame and get cleaned anyway.
+	const openEdges: Array<{ row: number; width: number }> = [];
+	const framePairs: Array<[number, number]> = [];
+	for (let row = 0; row < lines.length; row++) {
+		const text = strippedRow(lines, cache, row);
+		if (FRAME_OPEN_RE.test(text)) {
+			openEdges.push({ row, width: visibleWidth(text) });
+		} else if (FRAME_CLOSE_RE.test(text)) {
+			const open = openEdges[openEdges.length - 1];
+			if (open && open.width === visibleWidth(text)) {
+				openEdges.pop();
+				framePairs.push([open.row, row]);
+			}
+		}
+	}
+	for (const [open, close] of framePairs) {
+		dropped.add(open);
+		dropped.add(close);
+		for (let row = open + 1; row < close; row++) frameContent.add(row);
+	}
+
+	// Pass 2 — full-width rule pairs. Two rules of equal width with at least
+	// one row between them are a Starline user message's borders, and the rows
+	// between carry the rail. Any inner row *without* the rail prefix breaks
+	// the candidate: it is what keeps an assistant's own `---` rules, and the
+	// text between two of them, from being eaten — those rows are content.
+	//
+	// With an empty rail prefix (the `copyFriendly` render drops the rail)
+	// nothing can break a candidate, so any two equal-width rules pair. That
+	// also matches a markdown `---` pair, which then loses its rules from the
+	// copy — accepted: a horizontal rule is closer to chrome than to content,
+	// and the alternative is leaving real borders in every copyFriendly copy.
+	const railPrefix = railGlyph.length > 0 ? `${railGlyph} ` : "";
+	let lastRule: { row: number; width: number } | undefined;
+	for (let row = 0; row < lines.length; row++) {
+		if (dropped.has(row)) continue;
+		const text = strippedRow(lines, cache, row);
+		if (RULE_ROW_RE.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 (railPrefix.length > 0 && !text.startsWith(railPrefix)) {
+			lastRule = undefined;
+		}
+	}
+
+	const rows: CleanedRow[] = [];
+	let changed = false;
+	for (let row = startRow; row <= endRow; row++) {
+		if (dropped.has(row)) {
+			rows.push(null);
+			changed = true;
+			continue;
+		}
+		const text = strippedRow(lines, cache, row);
+		if (frameContent.has(row) && text.startsWith("│") && text.endsWith("│") && text.length >= 2) {
+			rows.push({ text: text.slice(1, -1), leftTrim: 1 });
+			changed = true;
+			continue;
+		}
+		if (railContent.has(row) && railPrefix.length > 0 && text.startsWith(railPrefix)) {
+			rows.push({ text: text.slice(railPrefix.length), leftTrim: visibleWidth(railPrefix) });
+			changed = true;
+			continue;
+		}
+		rows.push({ text, leftTrim: 0 });
+	}
+	return { rows, changed };
+}

package/extensions/starline/mouse/word-select.ts

@@ -0,0 +1,145 @@
+/**
+ * Which columns a double click on one line should select.
+ *
+ * Ported from `getWordSelection` in pi commit `56419be51`
+ * (`feat/word-selection-path-chars`, `packages/tui/src/tui-alt-screen.ts`),
+ * filed upstream as issue #7746. The installed Pi build's own
+ * `getWordSelection` predates that patch, so this substitutes Pi's whole
+ * word-selection rule rather than layering path handling on top of it — see
+ * `index.ts` for where that substitution happens and why it's the intended
+ * scope, not creep.
+ *
+ * This is a pure function of one already-plain (no ANSI) line and a terminal
+ * column; the caller in `index.ts` is what reads Pi's live source line and
+ * strips escape sequences before calling in, matching the split
+ * `getWordSelection`/`getSelectionSourceLine` already have upstream.
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+const wordSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+
+/**
+ * Characters that join two words into one for double-click selection.
+ *
+ * `Intl.Segmenter` already keeps `_` and `.` inside a word, so `foo_bar` and
+ * `file.ts` survive on their own. It breaks on `/` and `-`, which is what
+ * takes a path or a kebab-case identifier apart. Terminals keep these inside
+ * a word so paths and URLs select whole; this set is what makes fullscreen's
+ * own double-click agree with them.
+ */
+const WORD_JOINERS = new Set(["/", "-"]);
+
+type WordSegment = {
+	start: number;
+	end: number;
+	isWordLike: boolean;
+	isJoiner: boolean;
+	isSpace: boolean;
+};
+
+/** `segments[index]`, guaranteed — every call site here only ever passes an index it just found in range. */
+function segmentAt(segments: readonly WordSegment[], index: number): WordSegment {
+	const segment = segments[index];
+	if (segment === undefined) {
+		throw new RangeError(`word-select: no segment at index ${index}`);
+	}
+	return segment;
+}
+
+function collectWordSegments(line: string): WordSegment[] {
+	const segments: WordSegment[] = [];
+	let start = 0;
+	for (const segment of wordSegmenter.segment(line)) {
+		const text = segment.segment;
+		const end = start + visibleWidth(text);
+		segments.push({
+			start,
+			end,
+			isWordLike: segment.isWordLike === true,
+			// Joiners arrive one per segment, so `//` in a URL is two of these.
+			isJoiner: text.length > 0 && [...text].every((char) => WORD_JOINERS.has(char)),
+			isSpace: text.length > 0 && text.trim().length === 0,
+		});
+		start = end;
+	}
+	return segments;
+}
+
+/**
+ * Walk back over a run of joiners that opens a word, as in `/usr` or `--flag`.
+ *
+ * The run only counts as part of the word when nothing but whitespace
+ * precedes it, which is what separates a leading separator from an infix one.
+ * In `http://a.com` the `//` is preceded by `:`, so the scheme stays out.
+ */
+function openingJoinerRun(segments: WordSegment[], first: number): number {
+	let index = first;
+	while (segments[index - 1]?.isJoiner) index--;
+	if (index === first) return first;
+	const before = segments[index - 1];
+	return before === undefined || before.isSpace ? index : first;
+}
+
+/**
+ * Grow a word segment across joiners that have a word on both sides, plus any
+ * separator run that opens it.
+ *
+ * Anchoring on word-like segments is what keeps this conservative: in
+ * `http://a.com/b` the `:` is not a joiner, so the run stops there instead of
+ * swallowing the scheme, and a dash used as prose punctuation in `a - b` has
+ * whitespace around it rather than a word.
+ */
+function expandOverWordJoiners(
+	segments: WordSegment[],
+	index: number,
+): { start: number; end: number } {
+	const anchor = segmentAt(segments, index);
+	if (anchor.isJoiner) {
+		// Clicking a separator should take the word it belongs to. Prefer the
+		// word on the left so an infix `/` grows the whole path; failing that,
+		// step over the run to the word it opens, so clicking the `/` of
+		// `/usr/bin` works.
+		if (segments[index - 1]?.isWordLike && segments[index + 1]?.isWordLike) {
+			return expandOverWordJoiners(segments, index - 1);
+		}
+		if (!segments[index - 1]?.isWordLike) {
+			let next = index;
+			while (segments[next]?.isJoiner) next++;
+			if (segments[next]?.isWordLike) return expandOverWordJoiners(segments, next);
+		}
+	}
+	if (!anchor.isWordLike) return { start: anchor.start, end: anchor.end };
+
+	let first = index;
+	while (first >= 2 && segments[first - 1]?.isJoiner && segments[first - 2]?.isWordLike) {
+		first -= 2;
+	}
+	first = openingJoinerRun(segments, first);
+	// A trailing run gets no such treatment: nothing follows it to make it
+	// part of the word, and `trailing- x` reading as `trailing-` would be
+	// wrong.
+	let last = index;
+	while (segments[last + 1]?.isJoiner && segments[last + 2]?.isWordLike) {
+		last += 2;
+	}
+	return { start: segmentAt(segments, first).start, end: segmentAt(segments, last).end };
+}
+
+/**
+ * The column range a double click at `column` on `line` should select, in
+ * the same column units as Pi's own `SelectionRange`. `undefined` when
+ * `column` lands past the end of the line — the caller calls through to Pi's
+ * own selection in that case rather than inventing a range.
+ */
+export function wordRangeAt(
+	line: string,
+	column: number,
+): { start: number; end: number } | undefined {
+	const segments = collectWordSegments(line);
+	for (let index = 0; index < segments.length; index++) {
+		const segment = segmentAt(segments, index);
+		if (column < segment.start || column >= segment.end) continue;
+		return expandOverWordJoiners(segments, index);
+	}
+	return undefined;
+}