@xzzpig/pi-starline 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Starline
 
-A Starship-inspired statusline and Opencode-style TUI for [Pi](https://pi.dev).
+A Starship-inspired statusline, Opencode-style editor chrome, and fullscreen mouse control for [Pi](https://pi.dev).
 
 > Starline is a fork of [pi-zentui](https://github.com/lmilojevicc/pi-zentui) by Luka, renamed and released on its own. It has diverged well past upstream and adds a pill footer style, a colour palette with `$ref` expansion, `model`/`thinking` footer segments, a git host icon, per-segment display options, configurable editor cursor styles, and mouse selection and copying.
 
@@ -10,10 +10,12 @@ A Starship-inspired statusline and Opencode-style TUI for [Pi](https://pi.dev).
 
 ## What is this?
 
-Starline brings two popular aesthetics to Pi:
+Starline makes Pi's fullscreen mode feel like a finished terminal app — three
+pieces of one product, not a theme:
 
-- **[Starship](https://starship.rs/) footer** — shows your current directory, git branch, git status indicators, and runtime/version detection in a compact, icon-rich format
-- **[Opencode](https://github.com/opencode-ai/opencode) editor** — clean bordered input box with accent rail, copy-friendly mode, and model/provider display inside the editor frame
+- **See the state** — a Starship-inspired statusline and pill footer: current directory, git branch and status, runtime/version detection, context usage and token counts in a compact, icon-rich format
+- **Type comfortably** — Opencode-style editor chrome: a clean bordered input box with accent rail and copy-friendly mode, model and provider inside the frame, paste collapse, and a `ctrl+g` hint pointing at your `$EDITOR` when a draft outgrows the box
+- **Drive with the mouse** — fullscreen mouse control: select and copy anywhere, click a tool box to expand just it, click to move the caret, wheel to scroll the draft — [see Mouse](#mouse-fullscreen-control)
 
 ## Features
 
@@ -37,7 +39,26 @@ Starline brings two popular aesthetics to Pi:
 - Configurable model, provider, and thinking-level indicator colors
 - Prompt-box-style user messages matching the Starline input chrome
 - Copy-friendly mode hides editor and previous-message rail glyphs so terminal selection copies less chrome
-- **Fixed editor** (experimental, opt-in): Pin the editor and footer at the bottom of the terminal while the transcript scrolls above
+
+### Mouse (fullscreen control)
+
+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.
+
+- **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 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
+automatically, see [the changelog](CHANGELOG.md)); the fixed editor itself is
+gone, superseded by Pi's fullscreen mode.
 
 ### Git Status Icons
 
@@ -130,6 +151,9 @@ Detects Starship Nerd Font runtime/language modules, uses the Starship Nerd Font
 
 ## Install
 
+Starline drives Pi 0.84's alternate-screen renderer, so it needs **Pi ≥ 0.84.4**.
+If you are on a distribution that bundles an older Pi, upgrade it or wait for it to catch up.
+
 ```bash
 # From npm (local fork @xzzpig/pi-starline)
 pi install npm:@xzzpig/pi-starline
@@ -150,7 +174,7 @@ Settings live in `~/.pi/agent/starline.json`. The file is optional — anything
 {
 	"footerStyle": "pill",
 	"colors": { "gitBranch": "bold purple" },
-	"mouse": { "copyOnSelect": false }
+	"mouse": { "clickToExpandTools": false }
 }
 ```
 
@@ -158,29 +182,9 @@ Settings live in `~/.pi/agent/starline.json`. The file is optional — anything
 
 **[Full configuration reference →](https://github.com/Andy8647/pi-starline/blob/main/docs/configuration.md)** — every option with its default: the pill footer, the colour palette and its `$name` references, footer format templates, per-segment display options, icon overrides, and editor styling.
 
-## Mouse
-
-Starline reads and drives Pi 0.84's own renderer, so mouse handling works in
-both TUI modes — use Pi's fullscreen mode (`tuiMode: "fullscreen"`) for the
-sticky editor and footer.
-
-- **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 hold the selection for `ctrl+c` with
-`mouse.copyOnSelect: false`. Transcript copies drop Starline's rails, rule
-rows and pi-toolbox frame borders.
-- **Click a tool box's hint row to expand just that box**, and collapse it via
-the `(ctrl+o to collapse)` anchor row (pi-toolbox 0.2.2+).
-- **Click to move the caret** in the input box; **backspace/delete remove a
-selected range**; the **wheel scrolls the draft** over the input box.
-
-0.2.x's `fixedEditor` config block was renamed to `mouse` (migrated
-automatically, see [the changelog](CHANGELOG.md)); the fixed editor itself is
-gone, superseded by Pi's fullscreen mode.
-
 ## Requirements
 
-- [Pi](https://pi.dev) coding agent 0.80.3 or newer
+- [Pi](https://pi.dev) coding agent 0.84.4 or newer
 - A [Nerd Font](https://www.nerdfonts.com/) for icons (or set `icons.mode` to `"ascii"`)
 
 ## Development

package/extensions/starline/config.ts

@@ -109,12 +109,8 @@ export type MouseConfig = {
 	wheelRouting: boolean;
 	/** Show a "copied to clipboard" notice for a copy Starline itself performs. */
 	copyNotice: boolean;
-	/** Copy on mouse release. When false the highlight waits for ctrl+c. */
-	copyOnSelect: boolean;
 	/** Clicking a tool box's `ctrl+o to expand` hint expands that one box. */
 	clickToExpandTools: boolean;
-	/** Double/triple-click word selection stops at path separators. */
-	pathAwareWords: boolean;
 	/** Copy transcript selections without the painted rails, rules and frames. */
 	transcriptCleanCopy: boolean;
 };
@@ -123,7 +119,6 @@ const FIXED_EDITOR_KEY_MAP: Record<string, keyof MouseConfig> = {
 	enabled: "enabled",
 	mouseScroll: "wheelRouting",
 	copyNotice: "copyNotice",
-	copyOnSelect: "copyOnSelect",
 	clickToExpandTools: "clickToExpandTools",
 };
 
@@ -415,9 +410,7 @@ export const defaultConfig: PolishedTuiConfig = {
 		enabled: true,
 		wheelRouting: true,
 		copyNotice: true,
-		copyOnSelect: true,
 		clickToExpandTools: true,
-		pathAwareWords: true,
 		transcriptCleanCopy: true,
 	},
 };
@@ -831,18 +824,10 @@ function normalizeMouseConfig(record: Record<string, unknown>): MouseConfig {
 				: defaultConfig.mouse.wheelRouting,
 		copyNotice:
 			typeof record.copyNotice === "boolean" ? record.copyNotice : defaultConfig.mouse.copyNotice,
-		copyOnSelect:
-			typeof record.copyOnSelect === "boolean"
-				? record.copyOnSelect
-				: defaultConfig.mouse.copyOnSelect,
 		clickToExpandTools:
 			typeof record.clickToExpandTools === "boolean"
 				? record.clickToExpandTools
 				: defaultConfig.mouse.clickToExpandTools,
-		pathAwareWords:
-			typeof record.pathAwareWords === "boolean"
-				? record.pathAwareWords
-				: defaultConfig.mouse.pathAwareWords,
 		transcriptCleanCopy:
 			typeof record.transcriptCleanCopy === "boolean"
 				? record.transcriptCleanCopy
@@ -1304,11 +1289,9 @@ export function saveMousePatch(patch: Partial<MouseConfig>, path = configPath):
 			...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
 			...(patch.wheelRouting !== undefined ? { wheelRouting: patch.wheelRouting } : {}),
 			...(patch.copyNotice !== undefined ? { copyNotice: patch.copyNotice } : {}),
-			...(patch.copyOnSelect !== undefined ? { copyOnSelect: patch.copyOnSelect } : {}),
 			...(patch.clickToExpandTools !== undefined
 				? { clickToExpandTools: patch.clickToExpandTools }
 				: {}),
-			...(patch.pathAwareWords !== undefined ? { pathAwareWords: patch.pathAwareWords } : {}),
 			...(patch.transcriptCleanCopy !== undefined
 				? { transcriptCleanCopy: patch.transcriptCleanCopy }
 				: {}),

package/extensions/starline/index.ts

@@ -255,6 +255,18 @@ export default function (pi: ExtensionAPI) {
 	const installMousePatches = () => {
 		uninstallMouse();
 		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.",
+			);
+			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

package/extensions/starline/mouse/capabilities.ts

@@ -14,15 +14,20 @@
  * 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.
  */
 
 export type MouseCapability =
 	| "handleViewportInput"
 	| "routeWheel"
 	| "handleSelectionMouseEvent"
-	| "copySelectionToClipboard"
-	| "getWordSelection"
-	| "getSelectionSourceLine"
+	| "copyActiveSelectionToClipboard"
+	| "getCopyOnSelect"
+	| "hasActiveSelection"
 	| "getSelectionBounds"
 	| "getSelectionColumns"
 	| "flash"
@@ -30,8 +35,7 @@ export type MouseCapability =
 	| "requestRender";
 
 export type MouseFeature =
-	| "selectionPendingMode"
-	| "pathAwareWords"
+	| "selectionHint"
 	| "clickToExpandTools"
 	| "editorWheelScroll"
 	| "editorClickToCaret"
@@ -42,9 +46,9 @@ const CAPABILITIES: readonly MouseCapability[] = [
 	"handleViewportInput",
 	"routeWheel",
 	"handleSelectionMouseEvent",
-	"copySelectionToClipboard",
-	"getWordSelection",
-	"getSelectionSourceLine",
+	"copyActiveSelectionToClipboard",
+	"getCopyOnSelect",
+	"hasActiveSelection",
 	"getSelectionBounds",
 	"getSelectionColumns",
 	"flash",
@@ -61,25 +65,20 @@ const CAPABILITIES: readonly MouseCapability[] = [
  * 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",
+	// 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
+	// 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
+	// slice — the hint promises what ctrl+x delivers. No release interception,
+	// no pending state: Pi's `copyOnSelect: false` already keeps the selection
+	// highlighted, and the hint rides Pi's own repaints.
+	selectionHint: [
+		"getCopyOnSelect",
+		"hasActiveSelection",
 		"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
@@ -123,11 +122,12 @@ const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
 		"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.
+	// 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
@@ -135,18 +135,18 @@ const REQUIREMENTS: Record<MouseFeature, readonly MouseCapability[]> = {
 	// 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
+	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 Pi's own "Copied!" through `flash`
+	// 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.
 	transcriptCleanCopy: [
-		"copySelectionToClipboard",
+		"copyActiveSelectionToClipboard",
 		"getSelectionBounds",
 		"getSelectionColumns",
 		"hasOverlay",

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

@@ -397,9 +397,9 @@ type EditableEditor = {
  * range back a letter at a time. So one snapshot is pushed up front through the
  * editor's own `pushUndoSnapshot`, and the editor's own is shadowed for the
  * duration of the loop and put back in a `finally` — the same shadow-and-restore
- * shape `copyWithNotice` uses on `flash` and `installPasteCollapse` uses on
- * `handlePaste`. This is a plain assignment on Starline's own editor instance,
- * never on anything reached through Pi's renderer Proxy.
+ * shape `installPasteCollapse` uses on `handlePaste`. This is a plain
+ * assignment on Starline's own editor instance, never on anything reached
+ * through Pi's renderer Proxy.
  *
  * The loop is bounded twice over: by the character count of the range, and by a
  * no-progress check, so an editor that stops deleting cannot spin.