codex/codex-rs/tui2/docs/transcript_find.md

# Transcript Find (Inline Viewport)

This document describes the design for “find in transcript” in the **TUI2 inline viewport** (the
main transcript region above the composer), not the full-screen transcript overlay.

The goal is to provide fast, low-friction navigation through the in-memory transcript while keeping
the UI predictable and the implementation easy to review/maintain.

---

## Goals

- **Search the inline viewport content**, derived from the same flattened transcript lines used for
  scrolling/selection, so search results track what the user sees.
- **Ephemeral UI**: no always-on search bar and no scroll bar in this iteration.
- **Fast navigation**:
  - highlight all matches
  - jump to the next match repeatedly without reopening the prompt
- **Stable anchoring**: jumping should land on stable content anchors (cell + line), not raw screen
  rows.
- **Reviewable architecture**: keep `app.rs` changes small by placing feature logic in a dedicated
  module and calling it from the render loop and key handler.

---

## Current Implementation (What We Have Today)

This section documents the current state so it’s easy to compare against the “ideal/perfect” end
state discussed in review.

For implementation details, see the rustdoc comments and unit tests in `tui2/src/transcript_find.rs`.

### UI

- When active, a single prompt row is rendered **above the composer**:
  - `"/ query  current/total"`
- Matches are highlighted in the transcript:
  - all matches: underlined
  - current match: reversed + bold + underlined
- The prompt is **not persistent**: it only appears while editing.

### Keys

- `Ctrl-F`: open the find prompt and start editing the query.
- While editing:
  - type to edit the query (highlights update as you type)
  - `Backspace`: delete one character
  - `Ctrl-U`: clear the query
  - `Enter`: close the prompt and jump to a match (if any)
  - `Esc`: close the prompt without clearing the query (highlights remain)
- `Ctrl-G`: jump to next match.
  - Works while editing (prompt stays open).
  - Works even after the prompt is closed, as long as the query is still active.
- `Esc` (when not editing and a query is active): clears the search/highlights.

### Footer hints

- When the find prompt is visible, the footer shows `Ctrl-G next match`:
  - in the shortcut summary line
  - and in the `?` shortcut overlay

### Implementation layout

- Core logic lives in `tui2/src/transcript_find.rs`:
  - key handling
  - match computation/caching
  - jump selection
  - per-line rendering helper (`render_line`) and prompt rendering helper (`render_prompt_line`)
- `tui2/src/app.rs` is kept mostly additive by delegating:
  - early key handling delegation in `App::handle_key_event`
  - per-frame recompute/jump hook after transcript flattening
  - per-row render hook for match highlighting
  - prompt + cursor positioning while editing
- Footer hint integration is wired via `set_transcript_ui_state(..., find_visible)` through:
  - `tui2/src/chatwidget.rs`
  - `tui2/src/bottom_pane/mod.rs`
  - `tui2/src/bottom_pane/chat_composer.rs`
  - `tui2/src/bottom_pane/footer.rs`

---

## UX and Keybindings

### Entering search

- `Ctrl-F` opens the find prompt on the line immediately above the composer.
- While the prompt is open, typed characters update the query and immediately update highlights.

### Navigating results

- `Ctrl-G` jumps to the next match.
  - Works while the prompt is open.
  - Also works after the prompt is closed as long as a non-empty query is still active (so users can
    “keep stepping” through matches).

### Exiting / clearing

- `Esc` closes the prompt without clearing the active query (and therefore keeps highlights).
- `Esc` again (when not editing and a query is active) clears the search/highlights.

### Footer hints

When the find prompt is visible, we surface the relevant navigation key (`Ctrl-G`) in:

- the shortcut summary line (the default footer mode)
- the “?” shortcut overlay

This keeps the prompt itself visually minimal.

---

## Data Model: Search Over Flattened Lines

Search operates over the same representation as scrolling and selection:

1. Cells are flattened into a list of `Line<'static>` plus parallel `TranscriptLineMeta` entries
   (see `tui2/src/tui/scrolling.rs` and `tui2/docs/tui_viewport_and_history.md`).
2. The find module searches **plain text** extracted from each flattened line (by concatenating its
   spans’ contents).
3. Each match stores:
   - `line_index` (index into flattened lines)
   - `range` (byte range within the flattened line’s plain text)
   - `anchor` derived from `TranscriptLineMeta::CellLine { cell_index, line_in_cell }`

The anchor is used to update `TranscriptScroll` when jumping so the viewport lands on stable content
even if the transcript grows.

---

## Matching Semantics

### Smart-case

The search is “smart-case”:

- If the query contains any ASCII uppercase, the match is case-sensitive.
- Otherwise, both haystack and needle are matched in ASCII-lowercased form.

This avoids expensive Unicode case folding and keeps behavior predictable in terminals.

---

## Rendering

### Highlights

- All matches are highlighted (currently: underlined).
- The “current match” is emphasized more strongly (currently: reversed + bold + underlined).

Highlighting is applied at render time for each visible line by splitting spans into segments and
patching styles for the match ranges.

### Prompt line

While editing, the line directly above the composer shows:

`/ query  current/total`

It is rendered inside the transcript viewport area (not as a persistent UI element), and the cursor
is moved into this line while editing.

---

## Performance / Caching

Recomputing matches happens only when needed. The search module caches based on:

- transcript width (wrapping changes can change the flattened line list)
- number of flattened lines (transcript growth)

This keeps the work proportional to actual content changes rather than every frame.

---

## Code Layout (Additive, Review-Friendly)

The implementation is structured so `app.rs` only delegates:

- `tui2/src/transcript_find.rs` owns:
  - query/edit state
  - match computation and caching
  - key handling for find-related shortcuts
  - rendering helpers for highlighted lines and the prompt line
  - producing a scroll anchor when a jump is requested

`app.rs` integration points are intentionally small:

- **Key handling**: early delegation to `TranscriptFind::handle_key_event`.
- **Render**:
  - call `TranscriptFind::on_render` after building flattened lines to apply pending jumps
  - call `TranscriptFind::render_line` per visible row
  - render `render_prompt_line` when active and set cursor with `cursor_position`
- **Footer**:
  - `set_transcript_ui_state(..., find_visible)` so the footer can show find-related hints only when
    the prompt is visible.

---

## Comparison to the “Ideal” End State

### Ideal UX (what “perfect” looks like)

- **Ephemeral, minimal UI**: no always-on search bar, and no scroll bar for this feature.
- **Fast entry**: `Ctrl-F` opens a single prompt row above the composer.
- **Live feedback**: highlights update as you type, and the prompt shows `current/total`.
- **Repeat navigation without closing**: `Ctrl-G` jumps to the next match while the prompt stays
  open, and continues to work after the prompt closes as long as the query is active.
- **Predictable exit semantics**:
  - `Enter`: accept query, close prompt, and jump (if any matches)
  - `Esc`: close the prompt but keep the query/highlights
  - `Esc` again (with an active query): clear the query/highlights
- **Stable jumping**: navigation targets stable transcript anchors (cell + line-in-cell), so jumping
  behaves well as the transcript grows.
- **Discoverability without clutter**: when the prompt is visible, the footer/shortcuts surface the
  navigation key (`Ctrl-G`) so the prompt itself stays tight.
- **Future marker integration**: if/when a scroll indicator is introduced, match markers integrate
  with it (faint ticks for match lines, stronger marker for the current match).

### Already aligned with the ideal

- Ephemeral prompt (no always-on bar).
- Live highlighting while typing.
- `Ctrl-G` repeat navigation without reopening the prompt (including while editing).
- Stable jump anchoring via `(cell_index, line_in_cell)` metadata.
- Footer hints (`Ctrl-G next match`) shown only while the prompt is visible.
- Minimal, review-friendly integration points in `app.rs` via `tui2/src/transcript_find.rs`.

### Not implemented yet (intentional deferrals)

- Prev match (e.g. `Ctrl-Shift-G`).
- “Contextual landing” when jumping (e.g. padding/centering so the match isn’t pinned to the top).
- Match markers integrated with a future scroll indicator.

### Known limitations / trade-offs in the current version

- Matching is ASCII smart-case (no full Unicode case folding).
- Match ranges are byte ranges in the flattened plain text. This is fine for styling spans by byte
  slicing, but any future “column-precise” behaviors should be careful with multi-byte characters.

---

## Future Work (Not Implemented Here)

- **Prev match**: add `Ctrl-Shift-G` for previous match if desired.
- **Marker integration**: if/when a scroll indicator is added, include match markers derived from
  match line indices (faint ticks) and a stronger marker for the current match.
- **Contextual jump placement**: center the current match (or provide padding above) rather than
  placing it at the exact top row when jumping.