@fractaal/pi-tui 0.85.3 → 0.86.1

package/README.md

@@ -4,25 +4,27 @@ Minimal terminal UI framework with differential rendering and synchronized outpu
 
 ## Features
 
-- **Differential Rendering**: Three-strategy rendering system that only updates what changed
+- **Interchangeable Renderers**: Shared `TUI` interface with main-screen and alternate-screen implementations
+- **Differential Rendering**: Updates only changed lines or viewport rows
+- **Application-owned Scrolling**: Alternate-screen viewport supports mouse, trackpad, and keyboard navigation
 - **Synchronized Output**: Uses CSI 2026 for atomic screen updates (no flicker)
 - **Bracketed Paste Mode**: Handles large pastes correctly with markers for >10 line pastes
 - **Component-based**: Simple Component interface with render() method
 - **Theme Support**: Components accept theme interfaces for customizable styling
-- **Built-in Components**: Text, TruncatedText, Input, Editor, Markdown, Loader, SelectList, SettingsList, Spacer, Image, Box, Container
+- **Built-in Components**: Text, TruncatedText, Input, Editor, Markdown, Loader, SelectList, SettingsList, MouseRegion, Spacer, Image, Box, Container, VStack, HStack, ScrollView
 - **Inline Images**: Renders images in terminals that support Kitty or iTerm2 graphics protocols
 - **Autocomplete Support**: File paths and slash commands
 
 ## Quick Start
 
 ```typescript
-import { TUI, Text, Editor, ProcessTerminal, matchesKey } from "@earendil-works/pi-tui";
+import { type TUI, Text, Editor, ProcessTerminal, TuiMainScreen, matchesKey } from "@earendil-works/pi-tui";
 
 // Create terminal
 const terminal = new ProcessTerminal();
 
-// Create TUI
-const tui = new TUI(terminal);
+// Create the default main-screen renderer through the shared TUI interface
+const tui: TUI = new TuiMainScreen(terminal);
 
 // Add components
 tui.addChild(new Text("Welcome to my app!"));
@@ -52,12 +54,20 @@ tui.start();
 
 ## Core API
 
-### TUI
+### TUI interface and renderers
 
-Main container that manages components and rendering.
+`TUI` is the shared interface for component management, focus, overlays, input, lifecycle, terminal queries, and rendering. Choose a concrete renderer only when constructing the application:
+
+- `TuiMainScreen` renders into the main terminal buffer and preserves terminal scrollback.
+- `TuiAltScreen` renders a fixed-height viewport in the alternate terminal buffer with application-owned scrolling. When stopped, it restores the main buffer and prints the complete final document.
 
 ```typescript
-const tui = new TUI(terminal);
+import { type TUI, TuiAltScreen, TuiMainScreen } from "@earendil-works/pi-tui";
+
+const tui: TUI = new TuiMainScreen(terminal);
+// To use an application-owned viewport in the alternate terminal buffer instead:
+// const tui: TUI = new TuiAltScreen(terminal);
+
 tui.addChild(component);
 tui.removeChild(component);
 tui.start();
@@ -68,6 +78,91 @@ tui.requestRender(); // Request a re-render
 tui.onDebug = () => console.log("Debug triggered");
 ```
 
+### Colors and terminal styles
+
+Colors are values that can be converted or mixed before terminal rendering:
+
+```typescript
+import {
+  colorToRgb,
+  foregroundAnsi,
+  getTerminalColorMode,
+  mixColors,
+  parseColor,
+  rgbColor,
+  styleText,
+} from "@earendil-works/pi-tui";
+
+const accent = parseColor("oklch(70% 0.12 220)");
+const background = parseColor("#20242a");
+const foreground = mixColors(accent, background, 0.2);
+
+const text = styleText(
+  "Ready",
+  { fg: foreground, bg: background, bold: true },
+  getTerminalColorMode(),
+);
+```
+
+`Color` is an indexed ANSI color, an sRGB color, or an OKLCH color. Every color converts to sRGB, so color math such as `mixColors()` always works. Indices 0-15 follow the user's terminal palette, so their sRGB values are approximations. `styleText()` converts colors to truecolor or 256-color output based on the requested terminal mode.
+
+`parseColor()` also accepts OKHSL, as in `okhsl(250 60% 55%)`; `okhslColor()` builds it in code and `colorToOkhsl()` reads any color's OKHSL channels. OKHSL saturation is relative to the most the sRGB gamut allows at the hue and lightness, so every value is in gamut and equal saturation looks equally colorful across hues. OKHSL colors are converted to sRGB when created.
+
+Conversions are not cached. OKLCH colors, especially ones outside the sRGB gamut, are more expensive to convert than sRGB or indexed colors. For colors used on every render, convert once and reuse the result:
+
+```typescript
+const { r, g, b } = colorToRgb(mixColors(accent, background, 0.2));
+const foreground = rgbColor(r, g, b); // cheap to render repeatedly
+const foregroundCode = foregroundAnsi(foreground, getTerminalColorMode());
+```
+
+### Alternate-screen viewport layouts
+
+`TuiAltScreen` can render an explicit terminal-height layout. `VStack` and `HStack` allocate constrained regions, while `ScrollView` owns scrolling for one region. These semantics are intentionally unavailable on `TuiMainScreen`, where the terminal owns scrollback.
+
+```typescript
+import {
+  Container,
+  isViewportTUI,
+  ScrollView,
+  Text,
+  VStack,
+} from "@earendil-works/pi-tui";
+
+const transcript = new Container();
+transcript.addChild(new Text("History"));
+
+const editorAndFooter = new VStack([
+  editor,
+  new Text("status"),
+]);
+
+if (isViewportTUI(tui)) {
+  tui.setLayoutRoot(new VStack([
+    {
+      component: new ScrollView(transcript, {
+        follow: "end",
+        primary: true,
+        overscroll: "chain",
+      }),
+      basis: 0,
+      grow: 1,
+      minSize: 1,
+    },
+    {
+      component: editorAndFooter,
+      basis: "auto",
+      shrink: 1,
+      minSize: 1,
+    },
+  ]));
+}
+```
+
+Stack entries support `basis`, `grow`, `shrink`, `minSize`, `maxSize`, and responsive `visible` callbacks. Mouse-wheel input targets the scroll view under the pointer and unused delta chains to outer scroll views by default. The primary scroll view receives the alternate-screen keyboard navigation actions and wheel input over non-scrollable regions. It can also jump between OSC 133 semantic prompt markers, matching common terminal prompt-navigation shortcuts. Press `Ctrl+Shift+F` to open or close its bordered search panel. The panel shows the configured previous/next shortcuts and provides clickable arrow controls; by default, `Enter`/`Ctrl+G` and `Shift+Enter`/`Ctrl+Shift+G` move between matches, and `Escape` also closes search. `TuiAltScreenOptions.searchMatchStyle` and `searchCurrentMatchStyle` customize match highlighting, while `searchNavigationButtonStyle` styles each arrow button and receives its hover state. `TuiAltScreenOptions.scrollToEndIndicator` renders a clickable label centered on the last row of a `follow: "end"` primary scroll view while it is scrolled away from the end; clicking it resumes end-following.
+
+Layout geometry is rebuilt for each requested frame. Stateful components are retained, and their existing rendered-line caches remain effective. Calling `render(width)` directly on these layout components produces an unbounded document, which is also used when alt mode restores the main screen.
+
 ### Overlays
 
 Overlays render components on top of existing content without replacing it. Useful for dialogs, menus, and modal UI.
@@ -120,6 +215,7 @@ handle.unfocus();           // Release focus to normal fallback
 handle.unfocus({ target: baseComponent }); // Release this overlay to a specific component
 handle.unfocus({ target: null });   // Release this overlay and leave focus empty
 handle.isFocused();         // Check if overlay has focus
+handle.getBounds();         // Get last rendered terminal-relative bounds
 
 handle.unfocus();
 // Overlay loses focus; TUI falls back to another visible capturing overlay or the previous focus target.
@@ -154,7 +250,8 @@ All components implement:
 interface Component {
   render(width: number): string[];
   handleInput?(data: string): void;
-  invalidate?(): void;
+  handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+  invalidate(): void;
 }
 ```
 
@@ -162,10 +259,50 @@ interface Component {
 |--------|-------------|
 | `render(width)` | Returns an array of strings, one per line. Each line **must not exceed `width`** or the TUI will error. Use `truncateToWidth()` or manual wrapping to ensure this. |
 | `handleInput?(data)` | Called when the component has focus and receives keyboard input. The `data` string contains raw terminal input (may include ANSI escape sequences). |
-| `invalidate?()` | Called to clear any cached render state. Components should re-render from scratch on the next `render()` call. |
+| `handleMouse?(event)` | Called by `TuiAltScreen` for normalized pointer input targeted at the component. |
+| `invalidate()` | Required. Clear any cached render state so the next `render()` starts from scratch. Components without cached render state can use an empty implementation. |
 
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
+### Mouse Input
+
+`TuiAltScreen` normalizes SGR mouse input and hit-tests components and overlays. Events contain component-local `x`/`y`, absolute `screenX`/`screenY`, bounds, button, modifiers, click count, and wheel delta. `TuiMainScreen` does not capture mouse input because the terminal owns its scrollback.
+
+```typescript
+import type { TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
+
+handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+  if (event.type === "click" && event.button === "left") {
+    this.expanded = !this.expanded;
+    return { handled: true };
+  }
+  if (event.type === "press" && event.button === "left") {
+    return { handled: true, capture: true, focus: true };
+  }
+  if (event.type === "drag") {
+    this.updateFromPointer(event.x, event.y);
+    return { handled: true, render: true };
+  }
+  return undefined;
+}
+```
+
+Returning `handled` suppresses renderer-level fallback behavior. `capture` keeps subsequent drag and release events routed to the same component. `focus` requests keyboard focus. The optional `render` flag controls repainting: press, click, drag, and wheel default to rendering; move and release do not. Set `render: true` for a hover state that visibly changed, or `render: false` for a handled no-op. Render requests are coalesced and terminal output remains differential.
+
+Unhandled gestures retain alternate-screen defaults: wheel input scrolls the nearest `ScrollView` and chains unused delta, primary-button drags select text, OSC 8 links open before parent click handlers, and unhandled right-click preserves configured paste behavior. A click is emitted only when press/release completes without a drag.
+
+Use `MouseRegion` to add mouse behavior without changing a component's rendering:
+
+```typescript
+const collapsible = new MouseRegion(content, (event) => {
+  if (event.type !== "click" || event.button !== "left") return undefined;
+  expanded = !expanded;
+  return { handled: true };
+});
+```
+
+`Container` and `Box` route events to nested children using geometry recorded by the last rendered frame, so pointer motion does not rerender children merely to hit-test them. Explicit `VStack`, `HStack`, and `ScrollView` layouts use the alternate-screen layout frame directly.
+
 ### Focusable Interface (IME Support)
 
 Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
@@ -181,6 +318,8 @@ class MyInput implements Component, Focusable {
     // Emit marker right before the fake cursor
     return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
   }
+
+  invalidate(): void {}
 }
 ```
 
@@ -190,7 +329,7 @@ When a `Focusable` component has focus, TUI:
 3. Positions the hardware terminal cursor at that location
 4. Shows the hardware cursor only when `showHardwareCursor` is enabled
 
-The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the `TUI` constructor option, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
+The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer constructor's `showHardwareCursor` argument or `setShowHardwareCursor(true)`. The `Editor` and `Input` built-in components already implement this interface.
 
 **Container components with embedded inputs:** When a container component (dialog, selector, etc.) contains an `Input` or `Editor` child, the container must implement `Focusable` and propagate the focus state to the child:
 
@@ -282,6 +421,8 @@ input.setValue("initial");
 input.getValue();
 ```
 
+Clicking positions the cursor and gives the input keyboard focus in alternate-screen mode.
+
 **Key Bindings:**
 - `Enter` - Submit
 - `Ctrl+A` / `Ctrl+E` - Line start/end
@@ -317,6 +458,7 @@ editor.getPaddingX();  // Get current padding
 ```
 
 **Features:**
+- Click-to-position cursor and clickable autocomplete rows in alternate-screen mode
 - Multi-line editing with word wrap
 - Slash command autocomplete (type `/`)
 - File path autocomplete (press `Tab`)
@@ -457,6 +599,8 @@ list.setFilter("opt"); // Filter items
 ```
 
 **Controls:**
+- Mouse move/wheel: Highlight rows in alternate-screen mode
+- Click: Select a row
 - Arrow keys: Navigate
 - Enter: Select
 - Escape: Cancel
@@ -497,6 +641,8 @@ settings.updateValue("theme", "light");
 ```
 
 **Controls:**
+- Mouse move/wheel: Highlight rows in alternate-screen mode
+- Click: Activate a row
 - Arrow keys: Navigate
 - Enter/Space: Activate (cycle value or open submenu)
 - Escape: Cancel
@@ -535,6 +681,10 @@ tui.addChild(image);
 
 Supported formats: PNG, JPEG, GIF, WebP. Dimensions are parsed from the image headers automatically.
 
+#### Alternate-screen image compatibility
+
+`TuiAltScreen` supports inline images and partial viewport cropping in terminals that implement the Kitty graphics protocol, including Kitty and Ghostty. iTerm2's inline-image protocol does not provide operations to delete an existing placement or crop its source while scrolling. To prevent stale images from remaining over repainted content, `TuiAltScreen` renders image components as text placeholders in iTerm2. `TuiMainScreen` continues to render iTerm2 inline images normally.
+
 ## Autocomplete
 
 ### CombinedAutocompleteProvider
@@ -588,15 +738,17 @@ if (matchesKey(data, Key.enter)) {
 - With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
 - String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
 
-## Differential Rendering
+## Rendering modes
 
-The TUI uses three rendering strategies:
+`TuiMainScreen` uses three rendering strategies:
 
 1. **First Render**: Output all lines without clearing scrollback
-2. **Width Changed or Change Above Viewport**: Clear screen and full re-render
-3. **Normal Update**: Move cursor to first changed line, clear to end, render changed lines
+2. **Width Changed or Change Above Viewport**: Clear screen and fully re-render
+3. **Normal Update**: Move the cursor to the first changed line, clear to the end, and render changed lines
 
-All updates are wrapped in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering.
+`TuiAltScreen` owns a terminal-height viewport. Without an explicit layout root it preserves the legacy single-document scrolling behavior. With `setLayoutRoot()`, `VStack`, `HStack`, and nested `ScrollView` components can reserve fixed regions and independently scroll constrained regions. It updates changed viewport rows in place, follows streaming output while at the bottom, and preserves a manually selected scroll position while content grows. Mouse-wheel and configurable keyboard navigation scroll without modifying terminal scrollback, including jumps between OSC 133 semantic prompt markers. Scrollbars support hover expansion, thumb dragging, and track-click jumping. Clicking an OSC 8 hyperlink opens it with the configured URL handler. Dragging with the primary mouse button selects text and, unless `TuiAltScreenOptions.copyOnSelect` is `false`, copies it to the clipboard with OSC 52; holding the drag at a scroll view's top or bottom edge auto-scrolls and extends the selection into off-screen content. Kitty images support vertical viewport cropping; iTerm2 inline images fall back to text because the iTerm2 protocol cannot delete or crop placements during viewport repainting.
+
+Both renderers wrap updates in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering.
 
 ## Terminal Interface
 
@@ -678,6 +830,8 @@ class MyInteractiveComponent implements Component {
       return truncateToWidth(prefix + item, width);
     });
   }
+
+  invalidate(): void {}
 }
 ```
 
@@ -709,6 +863,8 @@ class MyComponent implements Component {
     // Pad to exact width (optional, for backgrounds)
     return [line + " ".repeat(width - visible)];
   }
+
+  invalidate(): void {}
 }
 ```
 
@@ -766,7 +922,7 @@ See `test/chat-simple.ts` for a complete chat interface example with:
 
 Run it:
 ```bash
-npx tsx test/chat-simple.ts
+node test/chat-simple.ts
 ```
 
 ## Development
@@ -779,7 +935,7 @@ npm install
 npm run check
 
 # Run the demo
-npx tsx test/chat-simple.ts
+node test/chat-simple.ts
 ```
 
 ### Debug logging
@@ -787,5 +943,5 @@ npx tsx test/chat-simple.ts
 Set `PI_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 
 ```bash
-PI_TUI_WRITE_LOG=/tmp/tui-ansi.log npx tsx test/chat-simple.ts
+PI_TUI_WRITE_LOG=/tmp/tui-ansi.log node test/chat-simple.ts
 ```

package/dist/alt-screen-search.d.ts

@@ -0,0 +1,46 @@
+import type { Component, Focusable } from "./tui.ts";
+export interface AltScreenSearchSegment {
+    row: number;
+    startCol: number;
+    endCol: number;
+}
+export interface AltScreenSearchMatch {
+    segments: AltScreenSearchSegment[];
+}
+export interface AltScreenSearchResult {
+    matches: AltScreenSearchMatch[];
+    changed: boolean;
+}
+/** Cache the searchable corpus and matches while rendered transcript lines remain unchanged. */
+export declare class AltScreenSearchIndex {
+    private sourceLines;
+    private corpus;
+    private normalizedQuery;
+    private matches;
+    search(lines: readonly string[], query: string): AltScreenSearchResult;
+}
+export declare function findAltScreenSearchMatches(lines: readonly string[], query: string): AltScreenSearchMatch[];
+export declare function getAltScreenSearchMatchKey(match: AltScreenSearchMatch): string;
+export declare class AltScreenSearchComponent implements Component, Focusable {
+    private readonly input;
+    private readonly onQueryChange;
+    private readonly navigationButtonStyle;
+    private resultCount;
+    private resultIndex;
+    private previousButtonStart;
+    private previousButtonEnd;
+    private nextButtonStart;
+    private nextButtonEnd;
+    private hoveredNavigationDirection;
+    private _focused;
+    constructor(onQueryChange: (query: string) => void, navigationButtonStyle?: (text: string, hovered: boolean) => string);
+    get focused(): boolean;
+    set focused(value: boolean);
+    setResult(index: number, count: number): void;
+    getNavigationDirectionAt(row: number, column: number): -1 | 1 | undefined;
+    setHoveredNavigationDirection(direction: -1 | 1 | undefined): boolean;
+    handleInput(data: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+//# sourceMappingURL=alt-screen-search.d.ts.map

package/dist/alt-screen-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alt-screen-search.d.ts","sourceRoot":"","sources":["../src/alt-screen-search.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAmBrD,MAAM,WAAW,sBAAsB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAwHD,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,gGAAgG;AAChG,qBAAa,oBAAoB;IAChC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,OAAO,CAA8B;IAE7C,MAAM,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAqBrE;CACD;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAG1G;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAI9E;AAED,qBAAa,wBAAyB,YAAW,SAAS,EAAE,SAAS;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAInB;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA6C;IACnF,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,0BAA0B,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAS;IAEzB,YACC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EACtC,qBAAqB,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAuB,EAIlF;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAGzB;IAED,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG5C;IAED,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAKxE;IAED,6BAA6B,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAIpE;IAED,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAK9B;IAED,UAAU,IAAI,IAAI,CAEjB;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAkE9B;CACD"}

package/dist/alt-screen-search.js

@@ -0,0 +1,282 @@
+import { Input } from "./components/input.js";
+import { getKeybindings } from "./keybindings.js";
+import { getGraphemeSegmenter, stripTerminalSequences, truncateToWidth, visibleWidth } from "./utils.js";
+const segmenter = getGraphemeSegmenter();
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+function buildSearchCorpus(lines) {
+    const chunks = [];
+    const spans = [];
+    let textLength = 0;
+    let pendingSeparator = false;
+    const appendSeparator = () => {
+        if (!pendingSeparator)
+            return;
+        chunks.push(" ");
+        textLength += 1;
+        pendingSeparator = false;
+    };
+    for (let row = 0; row < lines.length; row++) {
+        const line = stripTerminalSequences(lines[row] ?? "");
+        let column = 0;
+        // Rendered transcripts are overwhelmingly ASCII. Index complete non-space
+        // runs at once instead of segmenting and allocating one mapping per cell.
+        if (PRINTABLE_ASCII.test(line)) {
+            let index = 0;
+            while (index < line.length) {
+                if (line.charCodeAt(index) === 0x20) {
+                    if (textLength > 0)
+                        pendingSeparator = true;
+                    column += 1;
+                    index += 1;
+                    continue;
+                }
+                let end = index + 1;
+                while (end < line.length && line.charCodeAt(end) !== 0x20)
+                    end += 1;
+                appendSeparator();
+                const text = line.slice(index, end);
+                chunks.push(text);
+                spans.push({
+                    textStart: textLength,
+                    textEnd: textLength + text.length,
+                    row,
+                    startCol: column,
+                    endCol: column + text.length,
+                    linearColumns: true,
+                });
+                textLength += text.length;
+                column += text.length;
+                index = end;
+            }
+        }
+        else {
+            for (const grapheme of segmenter.segment(line)) {
+                const text = grapheme.segment;
+                const width = visibleWidth(text);
+                if (/^\s+$/u.test(text)) {
+                    if (textLength > 0)
+                        pendingSeparator = true;
+                    column += width;
+                    continue;
+                }
+                appendSeparator();
+                chunks.push(text);
+                spans.push({
+                    textStart: textLength,
+                    textEnd: textLength + text.length,
+                    row,
+                    startCol: column,
+                    endCol: column + width,
+                    linearColumns: false,
+                });
+                textLength += text.length;
+                column += width;
+            }
+        }
+        if (textLength > 0)
+            pendingSeparator = true;
+    }
+    return { text: chunks.join(""), spans };
+}
+function normalizeQuery(query) {
+    return query.replace(/\s+/gu, " ").trim();
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findSearchCorpusMatches(corpus, normalizedQuery) {
+    if (!normalizedQuery)
+        return [];
+    const expression = new RegExp(escapeRegExp(normalizedQuery), "giu");
+    const matches = [];
+    let spanIndex = 0;
+    for (const match of corpus.text.matchAll(expression)) {
+        const start = match.index;
+        const end = start + match[0].length;
+        while (spanIndex < corpus.spans.length && corpus.spans[spanIndex].textEnd <= start)
+            spanIndex += 1;
+        const segments = [];
+        for (let index = spanIndex; index < corpus.spans.length; index++) {
+            const span = corpus.spans[index];
+            if (span.textStart >= end)
+                break;
+            if (span.textEnd <= start)
+                continue;
+            const startCol = span.linearColumns
+                ? span.startCol + Math.max(start, span.textStart) - span.textStart
+                : span.startCol;
+            const endCol = span.linearColumns ? span.startCol + Math.min(end, span.textEnd) - span.textStart : span.endCol;
+            const previous = segments[segments.length - 1];
+            if (previous && previous.row === span.row && startCol <= previous.endCol) {
+                previous.endCol = Math.max(previous.endCol, endCol);
+            }
+            else {
+                segments.push({ row: span.row, startCol, endCol });
+            }
+        }
+        while (spanIndex < corpus.spans.length && corpus.spans[spanIndex].textEnd <= end)
+            spanIndex += 1;
+        if (segments.length > 0)
+            matches.push({ segments });
+    }
+    return matches;
+}
+/** Cache the searchable corpus and matches while rendered transcript lines remain unchanged. */
+export class AltScreenSearchIndex {
+    sourceLines;
+    corpus;
+    normalizedQuery;
+    matches = [];
+    search(lines, query) {
+        let sourceChanged = this.sourceLines?.length !== lines.length;
+        if (!sourceChanged && this.sourceLines) {
+            for (let index = 0; index < lines.length; index++) {
+                if (this.sourceLines[index] === lines[index])
+                    continue;
+                sourceChanged = true;
+                break;
+            }
+        }
+        if (sourceChanged || !this.corpus) {
+            this.sourceLines = Array.from(lines);
+            this.corpus = buildSearchCorpus(lines);
+        }
+        const normalizedQuery = normalizeQuery(query);
+        const changed = sourceChanged || normalizedQuery !== this.normalizedQuery;
+        if (changed) {
+            this.normalizedQuery = normalizedQuery;
+            this.matches = findSearchCorpusMatches(this.corpus, normalizedQuery);
+        }
+        return { matches: this.matches, changed };
+    }
+}
+export function findAltScreenSearchMatches(lines, query) {
+    const normalizedQuery = normalizeQuery(query);
+    return normalizedQuery ? findSearchCorpusMatches(buildSearchCorpus(lines), normalizedQuery) : [];
+}
+export function getAltScreenSearchMatchKey(match) {
+    const first = match.segments[0];
+    const last = match.segments[match.segments.length - 1];
+    return first && last ? `${first.row}:${first.startCol}:${last.row}:${last.endCol}` : "";
+}
+export class AltScreenSearchComponent {
+    input = new Input({
+        prompt: " ",
+        placeholder: "Find in transcript",
+        placeholderStyle: (text) => `\x1b[2m${text}\x1b[22m`,
+    });
+    onQueryChange;
+    navigationButtonStyle;
+    resultCount = 0;
+    resultIndex = -1;
+    previousButtonStart = -1;
+    previousButtonEnd = -1;
+    nextButtonStart = -1;
+    nextButtonEnd = -1;
+    hoveredNavigationDirection;
+    _focused = false;
+    constructor(onQueryChange, navigationButtonStyle = (text) => text) {
+        this.onQueryChange = onQueryChange;
+        this.navigationButtonStyle = navigationButtonStyle;
+    }
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        this._focused = value;
+        this.input.focused = value;
+    }
+    setResult(index, count) {
+        this.resultIndex = index;
+        this.resultCount = count;
+    }
+    getNavigationDirectionAt(row, column) {
+        if (row !== 2)
+            return undefined;
+        if (column >= this.previousButtonStart && column < this.previousButtonEnd)
+            return -1;
+        if (column >= this.nextButtonStart && column < this.nextButtonEnd)
+            return 1;
+        return undefined;
+    }
+    setHoveredNavigationDirection(direction) {
+        if (direction === this.hoveredNavigationDirection)
+            return false;
+        this.hoveredNavigationDirection = direction;
+        return true;
+    }
+    handleInput(data) {
+        const previous = this.input.getValue();
+        this.input.handleInput(data);
+        const query = this.input.getValue();
+        if (query !== previous)
+            this.onQueryChange(query);
+    }
+    invalidate() {
+        this.input.invalidate();
+    }
+    render(width) {
+        const safeWidth = Math.max(1, width);
+        const innerWidth = Math.max(0, safeWidth - 2);
+        const formatKey = (key) => key
+            ? key
+                .split("+")
+                .map((part) => {
+                if (process.platform === "darwin" && part.toLowerCase() === "alt")
+                    return "Option";
+                return part.charAt(0).toUpperCase() + part.slice(1);
+            })
+                .join("+")
+            : "Unbound";
+        const keybindings = getKeybindings();
+        const previousKey = formatKey(keybindings.getKeys("tui.altScreen.searchPrevious")[0]);
+        const nextKey = formatKey(keybindings.getKeys("tui.altScreen.searchNext")[0]);
+        const query = this.input.getValue();
+        const result = !query
+            ? ""
+            : this.resultCount === 0
+                ? "No matches"
+                : `${this.resultIndex + 1}/${this.resultCount}`;
+        const resultSpace = Math.max(0, innerWidth - 3);
+        const visibleResult = truncateToWidth(result, resultSpace, "");
+        const resultText = visibleResult ? `\x1b[2m ${visibleResult} \x1b[22m` : "";
+        const inputWidth = Math.max(0, innerWidth - visibleWidth(resultText));
+        const inputLine = truncateToWidth(this.input.render(Math.max(1, inputWidth))[0] ?? "", inputWidth, "");
+        const inputPadding = " ".repeat(Math.max(0, inputWidth - visibleWidth(inputLine)));
+        const content = `${inputLine}${inputPadding}${resultText}`;
+        let previousButton = `↑ ${previousKey}`;
+        let nextButton = `↓ ${nextKey}`;
+        let separator = " · ";
+        const outerGapWidth = 1;
+        const availableControlsWidth = Math.max(0, innerWidth - outerGapWidth * 2 - 1);
+        let controlsWidth = visibleWidth(previousButton) + visibleWidth(separator) + visibleWidth(nextButton);
+        if (controlsWidth > availableControlsWidth) {
+            previousButton = "↑";
+            nextButton = "↓";
+            separator = " ";
+            controlsWidth = visibleWidth(previousButton) + visibleWidth(separator) + visibleWidth(nextButton);
+        }
+        const showButtons = controlsWidth <= availableControlsWidth;
+        const renderedButtons = showButtons
+            ? this.navigationButtonStyle(previousButton, this.hoveredNavigationDirection === -1) +
+                separator +
+                this.navigationButtonStyle(nextButton, this.hoveredNavigationDirection === 1)
+            : "";
+        const outerGapsWidth = showButtons ? outerGapWidth * 2 : 0;
+        const rightRuleWidth = renderedButtons && innerWidth > controlsWidth + outerGapsWidth ? 1 : 0;
+        const leftRuleWidth = Math.max(0, innerWidth - (showButtons ? controlsWidth : 0) - outerGapsWidth - rightRuleWidth);
+        const previousStart = 1 + leftRuleWidth + outerGapWidth;
+        this.previousButtonStart = showButtons ? previousStart : -1;
+        this.previousButtonEnd = showButtons ? previousStart + visibleWidth(previousButton) : -1;
+        this.nextButtonStart = showButtons ? this.previousButtonEnd + visibleWidth(separator) : -1;
+        this.nextButtonEnd = showButtons ? this.nextButtonStart + visibleWidth(nextButton) : -1;
+        if (safeWidth === 1)
+            return ["┌", "│", "└"];
+        return [
+            `┌${"─".repeat(innerWidth)}┐`,
+            `│${content}│`,
+            `└${"─".repeat(leftRuleWidth)}${renderedButtons ? " " : ""}${renderedButtons}${renderedButtons ? " " : ""}${"─".repeat(rightRuleWidth)}┘`,
+        ];
+    }
+}
+//# sourceMappingURL=alt-screen-search.js.map