@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 "@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 editor-token bridges, keeps the shared native PTY host alive, measures terminal colors, applies the harmonious theme fallback, drives Pi's streaming status row, and registers the /libtui:colors 256-color palette diagnostic. It registers no model-facing tools, keybindings, or feature-specific UI.

Preview

The native palette diagnostic and shared picker components in Xsettings.

Watch the demo.

Install

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 @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:@luan.sh/pi-xsettings adds the /xsettings UI that publishes the appearance settings below; without it the compiled defaults apply.

Themes

The manifest exposes themes/harmonious.json, which relies on the terminal's indexed palette. If harmonious is active and the measured terminal reports 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.

MultiSelect with ordered checkboxes, a filter SemanticInput, and a DialogButtonBar: the pi-xsettings segment editor.

mountSplitPane with side-panel tabs from registerSidePanelProvider: pi-panels hosting a pi-side conversation.

UnifiedDiffView from pi-libtui/diff: the pi-fileops apply_patch result.

PtyPane over TerminalProjection from pi-libtui/terminal: the pi-exec-command Process Hub attached to a running server.

renderDetailCard as an anchored overlay: a pi-copy-mode annotation.

ToolActivity and ToolTranscript from pi-libtui/tool: pi-tool-search and pi-exec-command rows collapsed into an Explored group.

ProgressBar, renderPill, and renderEditorTokenPills: the pi-custom-editor status row and file tokens.

TransientPill: the pi-tuicr confirmation after a review comment is added.

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 Pi-native behaviour also needs the extension loaded.

Import path	Principal exports / capability	Host required
@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. Tool presentation has three layers: ToolTranscript (copy-friendly action plus payload), ToolActivity (streaming, diff, terminal, and viewport state for a live surface), and ToolOutput for text streams. mountTranscriptProjection exposes native transcript entries to a feature-owned component through a 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 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/<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>/<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 shuts it down.

Fullscreen split panes

mountSplitPane() composes one extension-owned pane beside Pi's complete fullscreen layout. Pi's transcript, editor, widgets, status, and footer stay in the main pane and reflow to its width. The highest-priority contribution is visible, with the latest mount breaking ties; disposing it restores the previous contribution or Pi's unwrapped layout.

const unmount = mountSplitPane({
	id: "example.details",
	position: "right",
	size: 32,
	initialRatio: 0.4,
	minMainSize: 1,
	priority: 10,
	onResize: (size) => saveCommittedWidth(size),
	component: (host, theme) => new DetailsPane(host, theme),
});

A draggable vertical border separates the pane from the main surface; Pi keeps only minMainSize. initialRatio derives the first width when none is restored, and onResize runs once when a drag commits. The pane hides when the terminal cannot fit one pane cell, the border and gap, and the minimum main size. The factory receives the active tui, viewport size, render requests, and focus(), blur(), isFocused(); clicking either pane focuses it without consuming the click. Split panes exist only in fullscreen mode. Pi 0.84.x has setLayoutRoot() but no getter, so the host validates one private field through a ref-counted prototype lease and leaves the layout unchanged if the shape is absent.

Appearance settings

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 @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
iconPack	unicode	unicode, nerd-fonts, emoji
activityIndicator	spinner	off, spinner, static, and the Unicode/ASCII/Braille/Nerd Font animations in TUI_ACTIVITY_INDICATOR_OPTIONS
activityMessage	phase	phase, typewriter
textEffect	off	off, sweep, glow, rainbow, rainbow-glow, lightning, aurora, glitch, crush
textEffectScope	message	message only or the whole indicator, separator, and message unit
pulseEffect	off	dim-to-bright or contrasting-color pulse over any indicator/text effect
statusPresentation	standard	standard, mixed compositions such as brainstorm, or exclusive scenes in TUI_STATUS_PRESENTATION_OPTIONS
animationSpeed	normal	slow, relaxed, normal, fast, very-fast
animationSmoothness	balanced	economy, balanced, smooth, ultra (roughly 13 to 60 redraws per second)
thinking*, working*, tool* (Indicator, Message, TextEffect, PulseEffect, Presentation)	inherit	per-phase overrides of the general value
powerline, powerlineButtons, softCursor	false	Powerline separators, button caps, softer virtual cursor
insertionCursor, navigationCursor, selectionCursor	virtual	cursor styles

Inline activity is composed as indicator + message, then the effect scope is painted; an exclusive scene replaces that composition. The extension applies the same renderer to Pi's streaming status row: Thinking takes priority over Tool, which takes priority over Working. Feature surfaces may pass ActivityAnimationOverrides to activityFrame() and mountConfiguredAnimation(); omitted fields inherit the live appearance.

Architecture

Responsibility	Owner
Tool definition	None; the package adds no model-facing tool
Execution	None in the library; src/extension.ts owns host setup
State	Components own local state; MouseBridgeHost owns bridge state; RequestAnimationController owns request phase state
Shared contracts	src/editor/protocol.ts (via src/editor.ts), src/folding.ts, src/selection.ts, src/decoration/pointer-interaction.ts, the public contracts selected by src/mouse.ts
Native boundary	Mouse/cursor compatibility, terminal color queries, PTY host, host bridges in src/host/

The host knows only generic TUI mechanics; feature labels, settings, actions, and workflows stay in their owning packages. Color resolution has one path: src/color/theme.ts owns the semantic-token table and resolves every paint through src/color/resolver.ts. Feature code uses only the root color API: tuiTheme(theme), createTuiThemeVariation(theme, name), tuiThemeAppearance(theme), TuiForegroundToken/TuiBackgroundToken, TuiSwatch (seven ramps at shades 0–5), opaque TuiColor handles, and TuiTheme.mixForeground().

Layout

Responsibility	Source
Extension entry and host	src/extension.ts, src/host/
Layout and rendering infrastructure	src/background-surface.ts, src/component-stack.ts, src/line-layout.ts, src/render-cache.ts, src/scrollbar.ts
Split panes and side panel	src/split-pane.ts, src/host/split-pane-bridge.ts, src/panels.ts
Overlays	src/overlay/
Controls	src/controls/
Text content, glyphs, status, pills, editor	src/content/, src/decoration/, src/editor.ts, src/editor/
Appearance, motion, request animation	src/appearance.ts, src/motion.ts, src/request-animation.ts
Colors and syntax	src/color/, src/terminal-colors.ts, src/syntax.ts
Streams, terminal projection, PTY host, diffs, tools	src/stream.ts, src/terminal/, src/diff/, src/tool/
Native binary discovery and first-use builds	src/native-binary.ts

Troubleshooting

• A feature renders but clicks do nothing: the host extension is not loaded. 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.
• cargo was not found: install Rust from https://rustup.rs, or set the binary's env override to a prebuilt executable.

Develop

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. 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.