pi-libtui 0.3.7 → 0.3.9

package/README.md

@@ -1,13 +1,11 @@
-# pi-libtui
-
-[Pi gallery](https://pi.dev/packages/pi-libtui)
+# @luan.sh/pi-libtui&nbsp;[<img src="https://pi.luan.sh/icons/pi.svg" width="14" alt="Pi gallery">](https://pi.dev/packages/@luan.sh/pi-libtui)&nbsp;[<img src="https://pi.luan.sh/icons/npm.svg" width="14" alt="npm">](https://www.npmjs.com/package/@luan.sh/pi-libtui)
 
 Shared terminal UI for Pi extensions: layouts, split panes, dialogs, pickers,
 selection actions, semantic colors, icons, cursors, syntax highlighting,
 animated tool surfaces, streamed output, diffs, terminal projection, and the
 protocols those pieces need. The primary audience is extension authors.
 
-The package has two surfaces. `import "pi-libtui"` is a
+The package has two surfaces. `import "@luan.sh/pi-libtui"` is a
 side-effect-free library: it does not start Pi, probe the terminal, register a
 tool, or install UI. `src/extension.ts` is a Pi extension (listed in the
 package's `pi.extensions`) that installs the generic mouse, cursor, and
@@ -20,24 +18,24 @@ registers no model-facing tools, keybindings, or feature-specific UI.
 
 The native palette diagnostic and shared picker components in Xsettings.
 
-![pi-libtui in Bootty](https://github.com/luan/agents/releases/download/v0.3.2/pi-libtui.png)
+![@luan.sh/pi-libtui in Bootty](https://pi.luan.sh/media/previews/pi-libtui-1820a03ca387.png)
 
-[Watch the demo](https://github.com/luan/agents/releases/download/v0.3.2/pi-libtui.mp4).
+[Watch the demo](https://pi.luan.sh/media/previews/pi-libtui-e7ff85f140d3.mp4).
 
 ## Install
 
 ```sh
-pi install npm:pi-libtui
+pi install npm:@luan.sh/pi-libtui
 ```
 
 This loads the host extension and the `harmonious` theme on its own. Feature
-packages normally bundle their own copy instead: add `pi-libtui` to
+packages normally bundle their own copy instead: add `@luan.sh/pi-libtui` to
 both `dependencies` and `bundledDependencies` in `package.json`, and list
 `"./node_modules/pi-libtui/src/extension.ts"` in the package's
 `pi.extensions` so the mouse/cursor bridge is active. The host claims itself
 once per process, so several installed copies do not conflict.
 
-Optional companion: `pi install npm:pi-xsettings` adds the `/xsettings`
+Optional companion: `pi install npm:@luan.sh/pi-xsettings` adds the `/xsettings`
 UI that publishes the appearance settings below; without it the compiled
 defaults apply.
 
@@ -49,6 +47,59 @@ neither a generated 256-color palette nor an ANSI base-16 palette, the host
 switches to Pi's built-in theme for the detected light or dark scheme (dark if
 the measurement fails).
 
+## Components
+
+Captures of the shared components inside the extensions that use them. The
+images are served from the documentation site.
+
+`ActionPanel` with a `DialogButtonBar` footer in a `DialogOverlay`: the
+pi-copy-mode reaction picker.
+
+![ActionPanel and DialogButtonBar in pi-copy-mode](https://pi.luan.sh/media/libtui/action-panel.png)
+
+`MultiSelect` with ordered checkboxes, a filter `SemanticInput`, and a
+`DialogButtonBar`: the pi-xsettings segment editor.
+
+![MultiSelect in pi-xsettings](https://pi.luan.sh/media/libtui/multi-select.png)
+
+`mountSplitPane` with side-panel tabs from `registerSidePanelProvider`:
+pi-panels hosting a pi-side conversation.
+
+![Split pane and side-panel tabs in pi-panels](https://pi.luan.sh/media/libtui/split-panes.png)
+
+`UnifiedDiffView` from `pi-libtui/diff`: the pi-fileops `apply_patch` result.
+
+![UnifiedDiffView in pi-fileops](https://pi.luan.sh/media/libtui/unified-diff.png)
+
+`PtyPane` over `TerminalProjection` from `pi-libtui/terminal`: the
+pi-exec-command Process Hub attached to a running server.
+
+![PtyPane in pi-exec-command](https://pi.luan.sh/media/libtui/terminal.png)
+
+`renderDetailCard` as an anchored overlay: a pi-copy-mode annotation.
+
+![Detail card in pi-copy-mode](https://pi.luan.sh/media/libtui/detail-card.png)
+
+`ToolActivity` and `ToolTranscript` from `pi-libtui/tool`: pi-tool-search
+and pi-exec-command rows collapsed into an `Explored` group.
+
+![ToolActivity rows in pi-tool-search](https://pi.luan.sh/media/libtui/tool-activity.png)
+
+`ProgressBar`, `renderPill`, and `renderEditorTokenPills`: the
+pi-custom-editor status row and file tokens.
+
+![Status row and editor pills in pi-custom-editor](https://pi.luan.sh/media/libtui/status-row.png)
+
+`TransientPill`: the pi-tuicr confirmation after a review comment is added.
+
+![TransientPill in pi-tuicr](https://pi.luan.sh/media/libtui/transient-pill.png)
+
+Components without a capture in a shipped extension: `PickerPanel`
+(pi-prompt-storage), `SearchableSelect` and `SelectBox` (pi-xsettings
+editors), `SelectionActionBar` (pi-copy-mode), `FramedEditorOverlay`,
+`mountHoverTooltip`, `FloatingOverlay`, `ActivityIndicator` styles, and
+`applyScrollbar`. Add them here when a gallery recording shows them in use.
+
 ## Public modules
 
 Every entry point is a side-effect-free import. "Host required" means the
@@ -56,15 +107,15 @@ Pi-native behaviour also needs the extension loaded.
 
 | Import path | Principal exports / capability | Host required |
 | --- | --- | --- |
-| `pi-libtui` | Layouts, split panes, side-panel protocol, dialogs, pickers, inputs, selection actions, semantic colors, icons, cursors, `PtyProcess`, `PtyPane`, `applyScrollbar`, `PointerInteractionController`, `RenderedLinesCache`, `SyntaxText`, motion/progress, appearance (`getTuiAppearance`, `configureTuiAppearance`, `subscribeTuiAppearance`), `ensureNativeBinary` | Rendering no; panes, PTYs, and bridges yes |
-| `pi-libtui/diff` | `createUnifiedDiffModel`, `parseUnifiedDiff`, `renderUnifiedDiff`, `UnifiedDiffView`, bounded diff models/viewports | No |
-| `pi-libtui/editor` | `ensureEditorRegistry`, `dispatchEditorPaste`, `dispatchEditorRender`, `SemanticEditor`, `semanticEditorTheme`, editor registry contracts | Only to connect the registry to Pi's editor |
-| `pi-libtui/folding` | `ensureFoldingRegistry`, `foldTargetAt`, `clearFoldingCurrent`, fold-target contracts | Only for copy-mode keyboard integration |
-| `pi-libtui/mouse` | `ensureMouseRegistry`, `registerModalPointerShield`, viewport handlers, pointer contracts, `getFullscreenLayoutCapability`, `publishFullscreenLayoutCapability`, `resolveFullscreenLayout` | Yes for terminal pointer events and layout geometry |
-| `pi-libtui/selection` | `ensureSelectionRegistry`, native selection geometry, completion events, action contracts | Yes for Pi-native selection events |
-| `pi-libtui/stream` | `BoundedStreamBuffer`, bounded UTF-8/ANSI-safe stream snapshots | No |
-| `pi-libtui/terminal` | `TerminalProjection`, incremental `TerminalOutput` for bounded PTY/ANSI projection | No |
-| `pi-libtui/tool` | `ToolAction`, `LiveToolAction`, `ToolDisclosureAction`, `ToolActivity`, `ToolOutput`, `ToolTranscript`, `ToolViewRegion`, tool-call preview helpers | No for rendering |
+| `@luan.sh/pi-libtui` | Layouts, split panes, side-panel protocol, dialogs, pickers, inputs, selection actions, semantic colors, icons, cursors, `PtyProcess`, `PtyPane`, `applyScrollbar`, `PointerInteractionController`, `RenderedLinesCache`, `SyntaxText`, motion/progress, appearance (`getTuiAppearance`, `configureTuiAppearance`, `subscribeTuiAppearance`), `ensureNativeBinary` | Rendering no; panes, PTYs, and bridges yes |
+| `@luan.sh/pi-libtui/diff` | `createUnifiedDiffModel`, `parseUnifiedDiff`, `renderUnifiedDiff`, `UnifiedDiffView`, bounded diff models/viewports | No |
+| `@luan.sh/pi-libtui/editor` | `ensureEditorRegistry`, `dispatchEditorPaste`, `dispatchEditorRender`, `SemanticEditor`, `semanticEditorTheme`, editor registry contracts | Only to connect the registry to Pi's editor |
+| `@luan.sh/pi-libtui/folding` | `ensureFoldingRegistry`, `foldTargetAt`, `clearFoldingCurrent`, fold-target contracts | Only for copy-mode keyboard integration |
+| `@luan.sh/pi-libtui/mouse` | `ensureMouseRegistry`, `registerModalPointerShield`, viewport handlers, pointer contracts, `getFullscreenLayoutCapability`, `publishFullscreenLayoutCapability`, `resolveFullscreenLayout` | Yes for terminal pointer events and layout geometry |
+| `@luan.sh/pi-libtui/selection` | `ensureSelectionRegistry`, native selection geometry, completion events, action contracts | Yes for Pi-native selection events |
+| `@luan.sh/pi-libtui/stream` | `BoundedStreamBuffer`, bounded UTF-8/ANSI-safe stream snapshots | No |
+| `@luan.sh/pi-libtui/terminal` | `TerminalProjection`, incremental `TerminalOutput` for bounded PTY/ANSI projection | No |
+| `@luan.sh/pi-libtui/tool` | `ToolAction`, `LiveToolAction`, `ToolDisclosureAction`, `ToolActivity`, `ToolOutput`, `ToolTranscript`, `ToolViewRegion`, tool-call preview helpers | No for rendering |
 
 The `ensure*Registry` functions create or reuse a process-global capability
 keyed by `Symbol.for`, so feature packages and the host share one instance.
@@ -76,16 +127,16 @@ guarded Pi 0.84–0.85 adapter; unsupported hosts keep their native transcript.
 
 ## Native binaries
 
-Feature packages shell out to Rust binaries such as `terminal_bridge` (the
+Feature packages shell out to Rust binaries such as `terminal-bridge` (the
 exported `TERMINAL_BRIDGE` descriptor). Requires a Rust toolchain
-(https://rustup.rs). The `terminal_bridge` binary builds itself on first use
-under Pi's agent directory (`native/terminal-bridge/v<version>/`), where
-`<version>` is this package's version. Set `PI_TERMINAL_BRIDGE_BINARY` to use
+(https://rustup.rs). The `terminal-bridge` binary builds itself on first use
+under Pi's agent directory (`native/terminal-bridge/<revision>/`), where
+`<revision>` is the source commit recorded in the packaged `native-revision` file. Set `PI_TERMINAL_BRIDGE_BINARY` to use
 a prebuilt binary; it must point at an executable file.
 
 `ensureNativeBinary(binary, hooks?)` resolves in this order: the descriptor's
-env override, then `<agentDir>/native/<crate>/v<version>/bin/<name>`, building
-it on first use when absent. Builds are keyed by crate and version, so every
+env override, then `<agentDir>/native/<crate>/<revision>/bin/<name>`, building
+it on first use when absent. Builds are keyed by crate and source commit, so every
 installed copy shares them, and concurrent requests within one process share
 one build. Pass `onBuild` to show the delay in the UI. The extension host keeps
 the shared PTY host alive across an extension reload; a session switch or quit
@@ -127,8 +178,8 @@ shape is absent.
 
 This package has no settings store of its own. It exposes an appearance
 registry with compiled defaults (`DEFAULT_TUI_APPEARANCE`) that a settings host
-such as `pi-xsettings` overrides through `configureTuiAppearance()`;
-with pi-xsettings installed they are edited live via `/xsettings`. Keys and
+such as `@luan.sh/pi-xsettings` overrides through `configureTuiAppearance()`;
+with @luan.sh/pi-xsettings installed they are edited live via `/xsettings`. Keys and
 defaults:
 
 | Key | Default | Values |
@@ -190,7 +241,7 @@ through `src/color/resolver.ts`. Feature code uses only the root color API:
 ## Troubleshooting
 
 - A feature renders but clicks do nothing: the host extension is not loaded.
-  Install `pi-libtui` as a Pi package or list its `src/extension.ts`
+  Install `@luan.sh/pi-libtui` as a Pi package or list its `src/extension.ts`
   in the feature package's `pi.extensions`.
 - Nerd Font or Powerline glyphs are missing: set the icon pack to `unicode` and
   disable Powerline in `/xsettings`. Those are also the compiled defaults.
@@ -203,5 +254,6 @@ Source: https://github.com/luan/agents, directory
 harnesses/pi/agent/packages/pi-libtui. Run `bun run typecheck` and
 `bun test test` in that directory. When running from that checkout,
 `ensureNativeBinary` also looks for `target/{release,debug}/<name>` in the Cargo
-workspace and reports an unbuilt checkout instead of building; builds are pinned
-to the `v<version>` git tag, so publishing requires a matching tag.
+workspace and reports an unbuilt checkout instead of building. `just pi-pack`
+records the checkout commit in every bundled `@luan.sh/pi-libtui/native-revision` file,
+so native builds do not depend on npm versions or repository-wide release tags.

package/native-revision

@@ -0,0 +1 @@
+eace67b49e52950cb408c08f290f1ca9c409d68a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-libtui",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
     "themes": [
       "./themes"
     ],
-    "image": "https://github.com/luan/agents/releases/download/v0.3.2/pi-libtui.png",
-    "video": "https://github.com/luan/agents/releases/download/v0.3.2/pi-libtui.mp4"
+    "image": "https://pi.luan.sh/media/previews/pi-libtui-1820a03ca387.png",
+    "video": "https://pi.luan.sh/media/previews/pi-libtui-e7ff85f140d3.mp4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -51,5 +51,8 @@
     "typecheck": "tsc --build",
     "test": "bun test --only-failures --timeout 15000 test"
   },
-  "bundledDependencies": []
+  "bundledDependencies": [],
+  "publishAliases": [
+    "pi-libtui"
+  ]
 }

package/src/native-binary.ts

@@ -35,7 +35,7 @@ export type NativeBinaryLocation =
 
 export const TERMINAL_BRIDGE: NativeBinary = {
 	crate: "terminal-bridge",
-	binaryName: "terminal_bridge",
+	binaryName: "terminal-bridge",
 	env: "PI_TERMINAL_BRIDGE_BINARY",
 };
 
@@ -81,7 +81,8 @@ export interface EnsureNativeBinaryHooks {
  * revision under Pi's agent directory and shared by every installed pi-libtui copy.
  */
 export async function ensureNativeBinary(binary: NativeBinary, hooks: EnsureNativeBinaryHooks = {}): Promise<string> {
-	const location = locateNativeBinary(binary, processOptions());
+	const options = processOptions();
+	const location = locateNativeBinary(binary, options);
 	if (location.kind === "found") return location.path;
 	if (location.kind === "unbuilt-checkout") {
 		throw new Error(
@@ -92,7 +93,7 @@ export async function ensureNativeBinary(binary: NativeBinary, hooks: EnsureNati
 	const existing = builds.get(location.path);
 	if (existing) return existing;
 	hooks.onBuild?.(`Building ${binary.binaryName} (first use); this takes a minute.`);
-	const build = runCargo(nativeBuildArguments(binary, nativeRevision(), location.installRoot), location.installRoot)
+	const build = runCargo(nativeBuildArguments(binary, options.rev, location.installRoot), location.installRoot)
 		.then(() => {
 			if (!isExecutable(location.path)) throw new Error(`cargo install did not produce ${location.path}`);
 			return location.path;
@@ -106,12 +107,11 @@ export function terminalBridgeBinaryPath(): Promise<string> {
 	return ensureNativeBinary(TERMINAL_BRIDGE);
 }
 
-/** Builds are pinned to the git tag matching this package's version. Tag the repository when publishing. */
+/** The pack step records the exact source commit independently of npm versions. */
 export function nativeRevision(): string {
-	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
-		version: string;
-	};
-	return `v${manifest.version}`;
+	const revision = readFileSync(new URL("../native-revision", import.meta.url), "utf8").trim();
+	if (!/^[a-f0-9]{40}$/.test(revision)) throw new Error("Invalid native source revision; reinstall the package.");
+	return revision;
 }
 
 function processOptions(): NativeBinaryOptions {

package/src/panels.ts

@@ -1,7 +1,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component, Focusable } from "@earendil-works/pi-tui";
-import type { SplitPaneHost, TuiIconName } from "pi-libtui";
-import type { TuiMouseEvent } from "pi-libtui/mouse";
+import type { SplitPaneHost, TuiIconName } from "@luan.sh/pi-libtui";
+import type { TuiMouseEvent } from "@luan.sh/pi-libtui/mouse";
 
 export const SIDE_PANEL_REGISTRY_KEY = Symbol.for("pi-panels/registry/v1");
 export const SIDE_PANEL_PROTOCOL = "pi-panels/registry/v1" as const;

package/test/editor-chrome.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
-import { tuiTheme } from "pi-libtui";
+import { tuiTheme } from "@luan.sh/pi-libtui";
 import {
 	type EditorCompositionStyle,
 	renderEditorComposition,
 	renderEditorCompositionPreview,
 	renderEditorCompositionStatus,
-} from "pi-libtui/editor";
+} from "@luan.sh/pi-libtui/editor";
 
 const theme = {
 	name: "editor-chrome-test",

package/test/native-binary.test.ts

@@ -10,7 +10,7 @@ const options = (executables: readonly string[], environment: Record<string, str
 	rev: "v1.2.3",
 	isExecutable: (path: string) => executables.includes(path),
 });
-const managed = join("/agent/native", "terminal-bridge", "v1.2.3", "bin", "terminal_bridge");
+const managed = join("/agent/native", "terminal-bridge", "v1.2.3", "bin", "terminal-bridge");
 
 test("env override wins and must be executable", () => {
 	expect(locateNativeBinary(TERMINAL_BRIDGE, options(["/x/bridge"], { [ENV]: "/x/bridge" }))).toEqual({

package/test/public-surface.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, test } from "bun:test";
 
 const PUBLIC_ENTRYPOINTS = [
-	"pi-libtui",
-	"pi-libtui/diff",
-	"pi-libtui/editor",
-	"pi-libtui/folding",
-	"pi-libtui/mouse",
-	"pi-libtui/selection",
-	"pi-libtui/stream",
-	"pi-libtui/terminal",
-	"pi-libtui/tool",
+	"@luan.sh/pi-libtui",
+	"@luan.sh/pi-libtui/diff",
+	"@luan.sh/pi-libtui/editor",
+	"@luan.sh/pi-libtui/folding",
+	"@luan.sh/pi-libtui/mouse",
+	"@luan.sh/pi-libtui/selection",
+	"@luan.sh/pi-libtui/stream",
+	"@luan.sh/pi-libtui/terminal",
+	"@luan.sh/pi-libtui/tool",
 ] as const;
 
 const CAPABILITY_KEYS = [
@@ -30,7 +30,7 @@ describe("public module boundaries", () => {
 		}
 		const after = CAPABILITY_KEYS.map((key) => Object.hasOwn(globalThis, key));
 		expect(after).toEqual(before);
-		const mouse = await import("pi-libtui/mouse");
+		const mouse = await import("@luan.sh/pi-libtui/mouse");
 		expect(Object.keys(mouse).sort()).toEqual([
 			"FULLSCREEN_LAYOUT_CAPABILITY_KEY",
 			"FULLSCREEN_LAYOUT_PROTOCOL",
@@ -44,7 +44,7 @@ describe("public module boundaries", () => {
 			"registerModalPointerShield",
 			"resolveFullscreenLayout",
 		]);
-		const editor = await import("pi-libtui/editor");
+		const editor = await import("@luan.sh/pi-libtui/editor");
 		expect(Object.keys(editor).sort()).toEqual([
 			"EDITOR_PROTOCOL",
 			"EDITOR_REGISTRY_KEY",