@xzzpig/pi-starline 0.5.0 → 0.5.1

package/FORK-CHANGELOG.md

@@ -0,0 +1,9 @@
+# Fork release notes
+
+## 0.5.1 — Release candidate
+
+- Recognize the optional `@xzzpig/transcript-expand-target.v1` contract for group summary clicks. Invalid or absent providers fall back to the existing component resolver; no new mandatory package dependency or default-setting change.
+- Add `build:types` and `prepack` to include `dist/public.d.ts` alongside the extension sources.
+- Keep historical upstream/fork release notes in `CHANGELOG.md`; this fork-only file records the new compatibility release without expanding upstream documentation edits.
+
+Validated host: Pi 1.1.0. Native drag-selection acceptance and OpenSpec archival are release gates, not implied by a successful package build.

package/README.md

@@ -227,3 +227,26 @@ Inspired by:
 ## License
 
 MIT
+
+## Compatibility: explicit expand targets (fork-only)
+
+This fork's click-to-expand resolution (`mouse/tool-box.ts`) checks an
+optional, versioned **explicit expand-target protocol** before its own
+`setExpanded`/hint logic:
+
+- Providers publish a resolver on a component instance under
+  `Symbol.for("@xzzpig/transcript-expand-target.v1")` with
+  `{ version: 1, resolveLocalTarget(localRow, width) }`. The consumer is
+  `mouse/explicit-expand-target.ts` (fork-only file).
+- Today the only provider is
+  [`@xzzpig/pi-group-collapse`](../pi-group-collapse): its group summaries
+  resolve to the independent group object, so clicking a summary toggles
+  the group instead of the tool that carries it.
+- Without a provider nothing changes: no published protocol, a wrong
+  version, a non-callable resolver, a thrown resolution, or an invalid
+  resolved shape all fall through to the existing resolution. Installing
+  the provider is never required, and load order in either direction
+  works (the resolver is read per click, not cached).
+- Drag selection, double-click word selection, hyperlinks, wheel, and
+  overlay behavior are unaffected; the explicit target only answers for
+  the specific local rows it owns.

package/dist/public.d.ts

@@ -0,0 +1,5 @@
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+declare function export_default(pi: ExtensionAPI): void;
+
+export { export_default as default };

package/extensions/starline/mouse/explicit-expand-target.ts

@@ -0,0 +1,89 @@
+/**
+ * Fork-only consumer for the versioned explicit expand-target protocol
+ * (`@xzzpig/transcript-expand-target.v1`).
+ *
+ * Providers (pi-group-collapse today) publish a resolver on the component
+ * instance that draws a group summary. Starline checks that resolver for
+ * the component's *local* row before its own `setExpanded`/hint logic, so a
+ * click on a summary toggles the group object instead of the first tool
+ * inside it.
+ *
+ * The contract is defensive by requirement (see the mouse-api spec):
+ * no published protocol, a wrong version, a non-callable resolver, a
+ * thrown resolution, or an invalid resolved shape all fall back to the
+ * existing component path — installing the provider is never required and
+ * a broken provider cannot break clicks that used to work.
+ *
+ * This module deliberately depends on nothing: the symbol key is its only
+ * tie to the provider, so Starline keeps working with the provider absent,
+ * and any number of providers can publish the same key.
+ */
+
+/** The shared protocol key; `Symbol.for` so every copy in the process agrees. */
+export const EXPAND_TARGET_KEY = Symbol.for("@xzzpig/transcript-expand-target.v1");
+
+/** The slice of the protocol Starline reads. */
+type ExpandTargetProtocol = {
+	version: 1;
+	resolveLocalTarget: (localRow: number, width: number) => unknown;
+};
+
+/** The resolved target, validated before use. */
+export type ExplicitExpandTarget = {
+	component: { setExpanded(expanded: boolean): void };
+	expanded: boolean;
+};
+
+/**
+ * Resolve an explicit expand target for a component's local row, or
+ * undefined when there is no provider, no hit, or anything invalid.
+ */
+export function explicitExpandTargetAt(
+	component: unknown,
+	localRow: number,
+	width: number,
+): ExplicitExpandTarget | undefined {
+	if (typeof component !== "object" || component === null) return undefined;
+	let protocol: unknown;
+	try {
+		protocol = (component as Record<PropertyKey, unknown>)[EXPAND_TARGET_KEY];
+	} catch {
+		return undefined;
+	}
+	if (
+		typeof protocol !== "object" ||
+		protocol === null ||
+		(protocol as ExpandTargetProtocol).version !== 1 ||
+		typeof (protocol as ExpandTargetProtocol).resolveLocalTarget !== "function"
+	) {
+		return undefined;
+	}
+	let resolved: unknown;
+	try {
+		resolved = (protocol as ExpandTargetProtocol).resolveLocalTarget(localRow, width);
+	} catch {
+		return undefined;
+	}
+	if (
+		typeof resolved !== "object" ||
+		resolved === null ||
+		typeof (resolved as ExplicitExpandTarget).expanded !== "boolean"
+	) {
+		return undefined;
+	}
+	const target = resolved as {
+		component?: { setExpanded?: unknown };
+		expanded: boolean;
+	};
+	if (
+		typeof target.component !== "object" ||
+		target.component === null ||
+		typeof target.component.setExpanded !== "function"
+	) {
+		return undefined;
+	}
+	return {
+		component: target.component as { setExpanded(expanded: boolean): void },
+		expanded: target.expanded,
+	};
+}

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

@@ -87,6 +87,7 @@
 
 import { stripTerminalSequences } from "@earendil-works/pi-tui";
 import { createComponentTree, isComponentLike, isExpandableComponent } from "./component-tree";
+import { explicitExpandTargetAt } from "./explicit-expand-target";
 import { type BoxLike, boxesAt, scrollContentLinesFor, scrollContentOrigin } from "./hit-test";
 import { keyTextFor } from "./key-text";
 
@@ -242,6 +243,9 @@ export function expandTargetAt(
 
 	for (let index = path.length - 1; index >= 0; index--) {
 		const span = path[index];
+		// Fork seam: a versioned explicit target on this component's local row wins over the component's own expand state, so a group summary toggles its group instead of the tool carrying it. No provider, wrong version, or invalid shape falls through untouched.
+		const explicit = explicitExpandTargetAt(span.component, row - span.start, origin.rect.width);
+		if (explicit) return { component: explicit.component, expanded: explicit.expanded };
 		if (!isExpandableComponent(span.component)) continue;
 		const component = span.component as ExpandableComponent;
 		// The hint is matched against this component's own rendered row, not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzzpig/pi-starline",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A Starship-inspired statusline and Opencode-style TUI for Pi.",
   "type": "module",
   "license": "MIT",
@@ -20,12 +20,14 @@
     "tui"
   ],
   "files": [
-    "extensions"
+    "extensions",
+    "dist",
+    "FORK-CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.86.0 <0.88",
-    "@earendil-works/pi-coding-agent": ">=0.86.0 <0.88",
-    "@earendil-works/pi-tui": ">=0.86.0 <0.88",
+    "@earendil-works/pi-ai": ">=1.0.0 <2",
+    "@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+    "@earendil-works/pi-tui": ">=1.0.0 <2",
     "@xzzpig/pi-mouse-events": ">=0.2.0 <3"
   },
   "pi": {
@@ -39,10 +41,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
-    "@earendil-works/pi-tui": "^0.87.1",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@types/node": "^26.0.0",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.4.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.8",
     "@xzzpig/pi-mouse-events": "0.2.0"
@@ -55,6 +59,7 @@
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs && biome format --write dist/public.d.ts",
     "test": "vitest run",
     "pi:dev": "${PI_BIN:-/opt/homebrew/bin/pi} --no-extensions -e ./extensions/starline/index.ts",
     "pi:install-local": "${PI_BIN:-/opt/homebrew/bin/pi} install ./ -l",