Status Quo

Terminal output is currently viewable only as raw text in the terminal grid (single terminal expanded view or grid cells). There is no way to read terminal history in a comfortable, formatted view. Users working with AI agents see large amounts of structured output (markdown-formatted explanations, code blocks, lists) rendered as plain terminal text with ANSI escapes. The existing story overlay (story_overlay.zig) renders markdown files from disk but uses a minimal parser limited to prose lines, code blocks, and diffs — it has no inline formatting (bold/italic), no lists, and no general-purpose markdown support. There is no mechanism to extract and reformat live terminal content as markdown.

Objectives

Give users a distraction-free reading view of their terminal's history. When working with AI coding agents that produce markdown-formatted output, the reader mode presents that output with proper headings, bold/italic text, code blocks, and lists — making long agent responses easy to read, scroll through, and search. The view updates live so users can watch agent output stream in beautifully formatted.

User Flow

Trigger: User presses Cmd+R while a terminal is focused.

1. A toast appears: "Reader Mode". A centered overlay opens with a smooth expand animation over the terminal, showing the focused terminal's history formatted as markdown.
2. The overlay is scrolled to the bottom (most recent output). Content updates live as the terminal produces output, staying pinned to the bottom unless the user scrolls up.
3. The user scrolls up to read earlier output. Once scrolled up, new output doesn't auto-scroll — a "scroll to bottom" indicator appears.
4. The user presses Cmd+F to open an incremental search bar. Matches are highlighted; next/prev navigation (Enter / Shift+Enter) jumps between them.
5. The user presses Escape or Cmd+R to close the overlay and return to the terminal.

Result: User has read and searched through formatted terminal history without losing context.

Scope

In scope:

• New ReaderOverlayComponent as a fullscreen overlay (using FullscreenOverlay base)
• Extracting terminal scrollback + viewport text from the focused session's ghostty-vt terminal
• New markdown parser supporting: headings, bold, italic, inline code, fenced code blocks (with language-based syntax highlighting), unordered/ordered lists, blockquotes, horizontal rules
• New markdown renderer drawing formatted text via SDL (font variations for bold/italic/code, indentation for lists/blockquotes, background tinting for code blocks)
• Reduced-width centered content column (reading-width, e.g. ~80–100 chars or proportion of window)
• Live content updates — re-extract and re-parse terminal content each frame (or on terminal epoch change)
• Scroll position management: pinned to bottom on open, stays put when user scrolls up, "jump to bottom" affordance
• Incremental text search (Cmd+F) with match highlighting and next/prev navigation
• Cmd+R keybinding in global shortcuts, toast on toggle, help overlay entry
• Documentation updates (README, ARCHITECTURE, configuration if applicable)

Out of scope:

• Tables, task lists, strikethrough, images, links (clickable) — may be added later
• Syntax highlighting with full language grammars (use simple keyword/token coloring or monochrome code blocks)
• Editing or interacting with terminal content from reader mode
• Reader mode for grid view (only works on focused/expanded terminal)
• Persisting reader mode state across sessions
• ANSI escape sequence interpretation for coloring (strip them, re-parse as markdown)

Implementation Plan

Affected Modules

• src/ui/components/reader_overlay.zig (new): Reader mode overlay component
• src/ui/components/markdown_parser.zig (new): Markdown tokenizer and AST builder
• src/ui/components/markdown_renderer.zig (new): SDL-based markdown rendering from AST
• src/ui/types.zig: Add ReaderMode toggle to UiAction enum
• src/ui/root.zig: Register reader overlay component
• src/app/runtime.zig: Register component, handle UiAction.ReaderMode
• src/ui/components/help_overlay.zig: Add Cmd+R entry
• src/ui/components/global_shortcuts.zig: Route Cmd+R if needed

Tasks

Each task is independently testable. Ordered by implementation sequence.

1. Terminal text extraction — Add a function to extract full scrollback + viewport as a plain UTF-8 string from a session's terminal (stripping ANSI escapes), exposed via UiHost or a new action/callback pattern — src/app/runtime.zig, src/ui/types.zig
2. Markdown parser — Implement a block-level + inline tokenizer that produces a flat list of styled runs (heading, paragraph, bold, italic, code span, code block line, list item, blockquote, horizontal rule). Input: plain text string. Output: []DisplayBlock where each block has type, indent level, and []StyledSpan — src/ui/components/markdown_parser.zig
3. Markdown renderer — Implement SDL rendering of parsed markdown blocks: font selection (bold/italic/monospace via FontCache), indented list rendering, code block background rectangles, heading size scaling, horizontal rules. Renders into a scrollable virtual canvas — src/ui/components/markdown_renderer.zig
4. Reader overlay component — Create ReaderOverlayComponent using FullscreenOverlay base with reduced-width centered column, scroll management (pinned-to-bottom with detach on user scroll, jump-to-bottom button), live content updates on terminal epoch change — src/ui/components/reader_overlay.zig
5. Search functionality — Add Cmd+F search bar to reader overlay with incremental text matching, match highlighting in rendered output, next/prev (Enter/Shift+Enter) navigation, match count display — src/ui/components/reader_overlay.zig
6. Keybinding and integration — Wire Cmd+R as toggle in global shortcuts or the component, add UiAction variant, register component in runtime.zig / root.zig, show toast on open — src/ui/components/global_shortcuts.zig, src/ui/types.zig, src/app/runtime.zig
7. Help overlay — Add "⌘R Reader Mode" entry to help overlay shortcuts array — src/ui/components/help_overlay.zig
8. Write tests — Unit tests for markdown parser (headings, inline formatting, code blocks, lists, nested structures, edge cases like empty input, no-markdown plain text). Integration test for text extraction roundtrip.
9. Update docs/ARCHITECTURE.md — Document reader overlay component, markdown parser/renderer modules, and the text extraction flow
10. Update README.md — Add reader mode to features list, document Cmd+R shortcut

New Dependencies

None — markdown parsing and rendering implemented from scratch using existing SDL + font infrastructure.

Acceptance Criteria

• All tasks completed
• Cmd+R opens reader mode on focused terminal, Escape/Cmd+R closes it
• Terminal history displays with proper markdown formatting (headings, bold/italic, code blocks, lists)
• Overlay is centered with reading-width column
• Content is live-updating and scrolled to bottom on open
• Scrolling up detaches from bottom; jump-to-bottom affordance appears
• Cmd+F search works with match highlighting and next/prev navigation
• Toast shown on open
• Help overlay includes Cmd+R
• Tests cover markdown parser happy path and edge cases
• zig build, zig build test, and just lint pass
• README and ARCHITECTURE docs updated