docs(02): research vault core and rendering phase

2026-02-28 21:55:13 +01:00
parent 7222543d4c
commit 24f11f39be
1 changed files with 999 additions and 0 deletions
@@ -0,0 +1,999 @@
 # Phase 2: Vault Core and Rendering - Research
 **Researched:** 2026-02-28
 **Domain:** Markdown parsing (pulldown-cmark), ratatui widget system, syntax highlighting (syntect), scrolling, CGA color palette, file I/O
 **Confidence:** HIGH
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 ### Locked Decisions
 #### Color palette & text styling
 - Classic CGA 16-color palette for accent elements (headers, code, links, emphasis markers)
 - Body text uses terminal default foreground/background — respects user's TERM color scheme
 - CGA accent colors only override for specific elements, not body text
 - Heading levels (H1-H6) distinguished by both color AND decorators (e.g. H1 = bright cyan + ══ underline, H2 = bright yellow, H3 = green, etc.)
 - Bold uses terminal bold attribute, italic uses terminal italic attribute, inline code uses terminal styling — modern terminals support these natively
 - No need to fall back to color-only for bold/italic since SSH users have modern terminal emulators
 #### Screen layout & chrome
 - No content borders — content goes edge-to-edge, maximizing reading space
 - Single status bar at the bottom only (vim-style)
 - Status bar content: current filename on the left, keyboard hints (q:Quit j/k:Scroll) on the right
 - Status bar style: reverse video (inverted colors) — classic terminal status bar look
 - No top bar, no title bar, no breadcrumb bar (breadcrumb comes in Phase 3)
 #### Code blocks & tables
 - Fenced code blocks get syntax highlighting using CGA palette colors (cyan keywords, green strings, etc.)
 - Code blocks framed with indent + colored background + rounded-corner box-drawing borders (╭─╮│╰─╯)
 - GFM tables rendered with full box-drawing grid (┌┬┐├┼┤└┴┘) — classic DOS table look
 - Table header row styled with bold + CGA accent color (e.g. bright cyan or yellow)
 #### Scrolling
 - j/k and arrow keys scroll one line at a time
 - PgUp/PgDn scroll a full page height
 - No splash screen on startup — go straight to content
 ### Claude's Discretion
 - Exact CGA color assignments per heading level (H1-H6)
 - Exact decorator style per heading level (═══ vs ─── vs none)
 - Syntax highlighting color mapping (which CGA color for keywords, strings, comments, etc.)
 - Blockquote visual style
 - Horizontal rule style
 - Image placeholder styling
 - List bullet/number styling
 - Scroll boundary behavior (stop or bounce)
 ### Deferred Ideas (OUT OF SCOPE)
 None — discussion stayed within phase scope
 </user_constraints>
 <phase_requirements>
 ## Phase Requirements
 | ID | Description | Research Support |
 |----|-------------|-----------------|
 | REND-01 | User sees H1-H6 headers with visual hierarchy and styling | pulldown-cmark Tag::Heading { level: HeadingLevel, .. } event; ratatui Line/Span with Color::LightCyan + Modifier::BOLD + decorator spans |
 | REND-02 | User sees bold, italic, and inline code rendered with terminal styling | pulldown-cmark Tag::Strong, Tag::Emphasis, Event::Code; ratatui Modifier::BOLD, Modifier::ITALIC, Color::LightCyan for inline code |
 | REND-03 | User sees fenced code blocks with syntax highlighting | pulldown-cmark CodeBlockKind::Fenced with language name; syntect 5.3 HighlightLines; CGA color mapping function |
 | REND-04 | User sees ordered and unordered lists with proper indentation | pulldown-cmark Tag::List(Option<u64>), Tag::Item; u64=None is unordered, u64=Some(n) is ordered starting at n |
 | REND-05 | User sees blockquotes with visual distinction | pulldown-cmark Tag::BlockQuote; render with left-margin │ character in CGA color + indented content |
 | REND-06 | User sees horizontal rules as visual separators | pulldown-cmark Event::Rule; render as a full-width line of ─── characters in dim/DarkGray |
 | REND-07 | User sees [IMAGE: alt text] placeholders for images | pulldown-cmark Tag::Image { .. }; collect alt text from nested Text events; render as Span "[IMAGE: {alt}]" |
 | REND-08 | User sees GFM tables rendered with aligned columns | pulldown-cmark Tag::Table(Vec<Alignment>) with Options::ENABLE_TABLES; two-pass rendering: collect cells then emit box-drawing grid |
 | REND-09 | User sees box-drawing borders on content panels | Code blocks use BorderType::Rounded (╭╮╰╯); tables use manual box-drawing chars; no borders on main content area per decision |
 | REND-10 | User sees CGA-era retro color theme (cyan/magenta/green on dark) | ratatui Color::LightCyan, Color::Cyan, Color::LightGreen, Color::Green, Color::LightMagenta, Color::Yellow, Color::White |
 | NAV-05 | User can scroll content with j/k, arrows, PgUp/PgDn | App state scroll_offset: u16; Paragraph::scroll((y, 0)); compute max_scroll from line_count(width) - viewport_height |
 | NAV-06 | User lands on index.md as the entry point | On init: vault_path.join("index.md"); if not exists show BBS error screen; use std::fs::read_to_string |
 | NAV-07 | User sees graceful error page when a linked file is not found | BBS-styled error widget with box-drawing border; message + vault path + create hint |
 | NAV-08 | User sees keyboard hints in status bar | Reverse-video single-line Paragraph at bottom; Layout split [Min(0), Length(1)] |
 | NAV-09 | App handles terminal resize without breaking layout | Event::Resize in crossterm event loop; ratatui autoresize in draw() handles buffer resize automatically for Viewport::Fullscreen |
 </phase_requirements>
 ---
 ## Summary
 Phase 2 is primarily a markdown parsing and rendering pipeline problem. The critical path runs: read file from disk → parse with pulldown-cmark → convert events to `Vec<Line>` (ratatui's styled text lines) → store in App state → render with `Paragraph::scroll()` → handle scroll keys. Every requirement maps cleanly to a specific pulldown-cmark event type and a ratatui rendering primitive.
 The ratatui 0.30 Widget trait has a verified, stable signature: `fn render(self, area: Rect, buf: &mut Buffer) where Self: Sized`. Custom widgets implement either consuming (`impl Widget for MyWidget`) or reference-based (`impl Widget for &MyWidget`) patterns. For Phase 2, the recommended approach is to build a `DocumentWidget` struct holding `Vec<ratatui::text::Line>` and implementing `Widget` on a reference to it, since the document content is stable between renders and only scroll_offset changes.
 Syntax highlighting uses syntect 5.3.0 + syntect-tui 3.0. The `HighlightLines` API returns `Vec<(syntect::highlighting::Style, &str)>` per line; `syntect-tui::into_span()` converts each tuple to a `ratatui::text::Span`. Since the user specified CGA 16-color output, a custom RGB-to-CGA mapping function is needed: syntect themes produce RGB values and these must be quantized to the nearest of the 16 ratatui named colors. The ~200KB binary overhead from embedded syntax definitions is acceptable.
 GFM table rendering is the most complex single requirement: pulldown-cmark delivers table events in streaming order (TableHead → TableCell* → TableRow* → TableCell*), requiring a two-pass approach — first collect all cell content with column widths, then emit the full box-drawing grid as `Line` objects. This is purely Rust data transformation, no additional library needed.
 **Primary recommendation:** Build a `MarkdownRenderer` struct that converts a markdown string to `Vec<ratatui::text::Line<'static>>` (owned strings, no lifetime leakage). Store the rendered lines in `App` state. Use `Paragraph::new(lines).scroll((offset, 0))` for display. Add `syntect` and `syntect-tui` to Cargo.toml.
 ---
 ## Standard Stack
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | pulldown-cmark | 0.13.1 | Markdown event-based parser | Already decided pre-Phase 1; CommonMark + GFM extensions; iterator-based, no allocation tree |
 | ratatui | 0.30.0 | TUI rendering, Widget/Paragraph/Line/Span | Already a dependency; 0.30 stable Widget trait |
 | syntect | 5.3.0 | Syntax highlighting for code blocks | De-facto Rust standard; embedded syntax definitions; HighlightLines API |
 | syntect-tui | 3.0 | Convert syntect Style to ratatui Span | Lightweight bridge; avoids manual color conversion for most cases |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | std::fs | stdlib | Read markdown files from vault_path | Opening index.md and linked files |
 | std::path::PathBuf | stdlib | Resolve file paths within vault | Join vault_path with relative file paths |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | syntect | Manual keyword regex highlighter | Manual approach avoids ~200KB binary overhead but requires per-language keyword lists; syntect has 80+ languages for free |
 | syntect | tree-sitter | tree-sitter is more accurate but requires C compilation and is heavier; overkill for a terminal reader |
 | pulldown-cmark | comrak | Pre-Phase 1 decision locked pulldown-cmark; comrak builds a DOM tree which uses more memory |
 | tui-markdown crate | Custom renderer | tui-markdown is experimental PoC (0.3.7); cannot produce BBS-specific CGA aesthetics without heavy forking; building from pulldown-cmark events gives full control |
 **Installation:**
 ```toml
 [dependencies]
 ratatui = "0.30.0"          # already present
 pulldown-cmark = "0.13.1"
 syntect = { version = "5.3.0", default-features = false, features = ["default-fancy"] }
 syntect-tui = "3.0"
 ```
 Note: `default-features = false, features = ["default-fancy"]` uses the pure-Rust fancy-regex engine instead of the Oniguruma C library. This avoids build complexity on non-standard systems (including some SSH server environments). The `default-fancy` feature still includes all embedded syntax definitions.
 ---
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 src/
 ├── main.rs              # unchanged from Phase 1
 ├── config.rs            # unchanged from Phase 1
 ├── signals.rs           # unchanged from Phase 1
 ├── terminal.rs          # unchanged from Phase 1
 ├── app.rs               # extended: add document state, scroll, key handling
 ├── vault.rs             # NEW: file loading, index.md resolution, error states
 ├── renderer.rs          # NEW: pulldown-cmark → Vec<Line> conversion pipeline
 └── highlighter.rs       # NEW: syntect integration, CGA color mapping
 ```
 ### Pattern 1: Markdown-to-Lines Conversion Pipeline
 **What:** Convert a markdown string to `Vec<ratatui::text::Line<'static>>` using pulldown-cmark events. This is the core of Phase 2.
 **When to use:** Called once when a document is loaded. The result is stored in App state and reused on every frame render.
 **Key insight:** Use `'static` lifetime for the output (owned `String` content in each `Span`) so there are no lifetime dependencies on the input markdown string. This simplifies App state dramatically.
 ```rust
 // Source: https://docs.rs/pulldown-cmark/latest/pulldown_cmark/
 use pulldown_cmark::{Event, Options, Parser, Tag, TagEnd, HeadingLevel, CodeBlockKind, Alignment};
 use ratatui::text::{Line, Span};
 use ratatui::style::{Color, Modifier, Style};
 pub struct MarkdownRenderer {
    pub lines: Vec<Line<'static>>,
    // Internal state during parsing
    current_spans: Vec<Span<'static>>,
    current_style: Style,
    in_code_block: bool,
    code_lang: String,
    code_buf: String,
    list_depth: u32,
    list_counters: Vec<Option<u64>>,  // None=unordered, Some(n)=ordered at n
    in_table: bool,
    table_columns: Vec<Alignment>,
    table_rows: Vec<Vec<String>>,     // raw cell text (two-pass for tables)
    in_table_head: bool,
 }
 ```
 **Event loop skeleton:**
 ```rust
 // Source: https://docs.rs/pulldown-cmark/latest/pulldown_cmark/
 pub fn render_markdown(input: &str) -> Vec<Line<'static>> {
    let mut opts = Options::empty();
    opts.insert(Options::ENABLE_TABLES);
    opts.insert(Options::ENABLE_STRIKETHROUGH);
    opts.insert(Options::ENABLE_TASKLISTS);
    opts.insert(Options::ENABLE_GFM);  // blockquote alerts
    // TextMergeStream coalesces consecutive Text events
    let parser = pulldown_cmark::TextMergeStream::new(Parser::new_ext(input, opts));
    let mut state = RenderState::new();
    for event in parser {
        state.handle(event);
    }
    state.finish()
 }
 ```
 ### Pattern 2: pulldown-cmark Event Handling — Complete Event Map
 All events relevant to Phase 2 requirements:
 ```rust
 // Source: https://docs.rs/pulldown-cmark/latest/pulldown_cmark/enum.Event.html
 // Source: https://docs.rs/pulldown-cmark/latest/pulldown_cmark/enum.Tag.html
 match event {
    // ── HEADING ──────────────────────────────────────────────────────────────
    Event::Start(Tag::Heading { level, .. }) => {
        // level: HeadingLevel (H1..H6)
        // Flush current line, push heading style onto style stack
        // After End(TagEnd::Heading), add underline decorator line
    }
    Event::End(TagEnd::Heading(_)) => {
        // Emit the heading Line, then emit a decorator Line (═══ or ───)
    }
    // ── PARAGRAPH ────────────────────────────────────────────────────────────
    Event::Start(Tag::Paragraph) => { /* nothing — spans accumulate */ }
    Event::End(TagEnd::Paragraph) => {
        // Flush current_spans → push Line to lines; push empty Line for spacing
    }
    // ── INLINE FORMATTING ────────────────────────────────────────────────────
    Event::Start(Tag::Strong) => { push_modifier(Modifier::BOLD); }
    Event::End(TagEnd::Strong) => { pop_modifier(Modifier::BOLD); }
    Event::Start(Tag::Emphasis) => { push_modifier(Modifier::ITALIC); }
    Event::End(TagEnd::Emphasis) => { pop_modifier(Modifier::ITALIC); }
    // ── INLINE CODE ──────────────────────────────────────────────────────────
    Event::Code(text) => {
        // Render as Span with distinct style (e.g., Color::LightCyan + DIM background)
        let span = Span::styled(text.to_string(), inline_code_style());
        current_spans.push(span);
    }
    // ── TEXT ─────────────────────────────────────────────────────────────────
    Event::Text(text) => {
        // If in_code_block: accumulate to code_buf
        // Otherwise: push Span with current_style
        if in_code_block {
            code_buf.push_str(&text);
        } else {
            current_spans.push(Span::styled(text.to_string(), current_style));
        }
    }
    // ── CODE BLOCK ───────────────────────────────────────────────────────────
    Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(lang))) => {
        code_lang = lang.to_string();
        in_code_block = true;
        code_buf.clear();
    }
    Event::Start(Tag::CodeBlock(CodeBlockKind::Indented)) => {
        code_lang = String::new();  // no language, no highlighting
        in_code_block = true;
        code_buf.clear();
    }
    Event::End(TagEnd::CodeBlock) => {
        // Emit code block: rounded borders + highlighted lines
        emit_code_block(&code_buf, &code_lang, &mut lines);
        in_code_block = false;
    }
    // ── LISTS ────────────────────────────────────────────────────────────────
    Event::Start(Tag::List(start_num)) => {
        list_counters.push(start_num);  // None = bullet, Some(n) = ordered from n
    }
    Event::End(TagEnd::List(_)) => {
        list_counters.pop();
        // Push blank line after list
    }
    Event::Start(Tag::Item) => {
        // Render bullet/number based on list_counters.last()
        let prefix = match list_counters.last() {
            Some(None) => "  • ".to_string(),
            Some(Some(n)) => format!("  {}. ", n),
            None => "  • ".to_string(),
        };
        // Increment counter for ordered lists
    }
    // ── BLOCKQUOTE ───────────────────────────────────────────────────────────
    Event::Start(Tag::BlockQuote(_kind)) => {
        // Push quote context: prepend "│ " to subsequent lines in CGA color
    }
    Event::End(TagEnd::BlockQuote(_)) => { /* pop quote context */ }
    // ── HORIZONTAL RULE ──────────────────────────────────────────────────────
    Event::Rule => {
        let rule = Line::from(Span::styled(
            "─".repeat(width),  // width available at render time, not parse time
            Style::default().fg(Color::DarkGray),
        ));
        lines.push(rule);
        lines.push(Line::default());
    }
    // ── IMAGE ─────────────────────────────────────────────────────────────────
    Event::Start(Tag::Image { .. }) => { /* begin collecting alt text */ }
    Event::End(TagEnd::Image) => {
        let placeholder = format!("[IMAGE: {}]", collected_alt_text);
        current_spans.push(Span::styled(placeholder, image_style()));
    }
    // ── TABLE (two-pass) ─────────────────────────────────────────────────────
    Event::Start(Tag::Table(alignments)) => {
        table_columns = alignments;
        table_rows.clear();
        in_table = true;
    }
    Event::End(TagEnd::Table) => {
        emit_table(&table_columns, &table_rows, &mut lines);
        in_table = false;
    }
    Event::Start(Tag::TableHead) => { in_table_head = true; }
    Event::End(TagEnd::TableHead) => { in_table_head = false; }
    Event::Start(Tag::TableRow) => { table_rows.push(Vec::new()); }
    Event::Start(Tag::TableCell) => { /* begin cell accumulation */ }
    Event::End(TagEnd::TableCell) => {
        // Push accumulated cell text to current row
        table_rows.last_mut().unwrap().push(current_cell_text.clone());
        current_cell_text.clear();
    }
    // ── BREAKS ───────────────────────────────────────────────────────────────
    Event::SoftBreak => { current_spans.push(Span::raw(" ")); }
    Event::HardBreak => {
        flush_line(&mut lines, &mut current_spans);
    }
    _ => {} // FootnoteReference, Html, InlineHtml, TaskListMarker handled as needed
 }
 ```
 **IMPORTANT:** `Tag::List` contains `Option<u64>` not `Option<u32>`. Ordered lists start at the `u64` value. `None` means unordered. This is the actual type as of pulldown-cmark 0.13.1.
 ### Pattern 3: ratatui Widget Trait — Verified 0.30 Signature
 The Widget trait signature in ratatui 0.30.0 is:
 ```rust
 // Source: https://docs.rs/ratatui/0.30.0/ratatui/widgets/trait.Widget.html
 pub trait Widget {
    fn render(self, area: Rect, buf: &mut Buffer)
    where Self: Sized;
 }
 ```
 **Breaking change from 0.28/0.29:** WidgetRef no longer has a blanket impl of Widget. The correct pattern for a reusable widget stored in state is to implement Widget for a reference:
 ```rust
 // Source: https://ratatui.rs/recipes/widgets/custom/
 pub struct DocumentWidget {
    lines: Vec<Line<'static>>,
    scroll_offset: u16,
 }
 impl Widget for &DocumentWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        let paragraph = Paragraph::new(self.lines.clone())
            .scroll((self.scroll_offset, 0));
        paragraph.render(area, buf);
    }
 }
 ```
 For widgets that need to modify their own state during render (e.g., update scroll limits after layout is known), implement `Widget for &mut MyWidget`.
 ### Pattern 4: Scrolling with Paragraph
 ```rust
 // Source: https://docs.rs/ratatui/0.30.0/ratatui/widgets/struct.Paragraph.html
 // Scroll signature:
 pub const fn scroll(self, offset: (u16, u16)) -> Paragraph<'a>
 // (y, x) — y is lines, x is chars. NOTE: unusual (y, x) order, not (x, y)
 // Computing max scroll:
 let content_height = paragraph.line_count(area.width) as u16;
 let viewport_height = content_area.height;
 let max_scroll = content_height.saturating_sub(viewport_height);
 // Clamping scroll:
 scroll_offset = scroll_offset.min(max_scroll);
 // Page scroll:
 let page_size = viewport_height;
 scroll_offset = scroll_offset.saturating_add(page_size).min(max_scroll); // PgDn
 scroll_offset = scroll_offset.saturating_sub(page_size);                  // PgUp
 ```
 **Critical note on line_count:** `Paragraph::line_count(width)` computes total lines accounting for word wrapping. Since the document lines are pre-rendered as discrete `Line` objects (one per logical line), and the content area has no wrap by default in Paragraph, `line_count` will equal `lines.len()` unless you enable `Wrap`. Keep wrapping disabled for pre-rendered markdown lines.
 ### Pattern 5: Status Bar Layout
 ```rust
 // Source: https://docs.rs/ratatui/0.30.0/ratatui/prelude/struct.Layout.html
 // Split the frame: content area above, status bar at bottom
 let chunks = Layout::default()
    .direction(Direction::Vertical)
    .constraints([Constraint::Min(0), Constraint::Length(1)])
    .split(frame.area());
 let content_area = chunks[0];
 let status_area = chunks[1];
 // Status bar: reverse video, filename left, hints right
 let status = Paragraph::new(Line::from(vec![
    Span::styled(
        format!(" {} ", filename),
        Style::default().add_modifier(Modifier::REVERSED),
    ),
    Span::styled(
        "  q:Quit  j/k:Scroll  PgUp/PgDn:Page ",
        Style::default().add_modifier(Modifier::REVERSED),
    ),
 ]))
 .style(Style::default().add_modifier(Modifier::REVERSED));
 frame.render_widget(status, status_area);
 ```
 ### Pattern 6: Code Block Rendering with Rounded Borders
 Code blocks use ratatui's `Block` with `BorderType::Rounded` (produces ╭╮╰╯):
 ```rust
 // Source: https://docs.rs/ratatui/0.30.0/ratatui/widgets/struct.Block.html
 use ratatui::widgets::{Block, BorderType, Borders};
 // Emit a Block frame around the highlighted code
 let code_block_border = Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)   // ╭─╮ / ╰─╯ corners
    .border_style(Style::default().fg(Color::DarkGray))
    .title(Span::styled(lang, Style::default().fg(Color::Yellow)));
 // The inner area of the block holds the Paragraph with highlighted lines
 ```
 When building `Vec<Line>`, code blocks are NOT rendered inside a live `Block` widget (that would require nested rendering). Instead, emit the border characters as raw `Span` objects forming the box-drawing frame:
 ```
 ╭─ rust ──────────────────╮
 │ let x = 1;              │
 │ println!("{}", x);      │
 ╰─────────────────────────╯
 ```
 This is simpler: each line of the code block becomes a `Line` with a leading `│` span and a trailing `│` span. The top/bottom borders are separate `Line` objects. This keeps everything in the flat `Vec<Line>` model and avoids nested widget rendering complexity.
 ### Pattern 7: Syntax Highlighting with syntect + syntect-tui
 ```rust
 // Source: https://docs.rs/syntect/latest/syntect/easy/struct.HighlightLines.html
 // Source: syntect-tui 3.0 (into_span function)
 use syntect::easy::HighlightLines;
 use syntect::highlighting::ThemeSet;
 use syntect::parsing::SyntaxSet;
 // Load once at program start (not per-document):
 lazy_static! {
    static ref SYNTAX_SET: SyntaxSet = SyntaxSet::load_defaults_newlines();
    static ref THEME_SET: ThemeSet = ThemeSet::load_defaults();
 }
 pub fn highlight_code(code: &str, lang: &str) -> Vec<Line<'static>> {
    let syntax = SYNTAX_SET.find_syntax_by_token(lang)
        .or_else(|| SYNTAX_SET.find_syntax_by_name(lang))
        .unwrap_or_else(|| SYNTAX_SET.find_syntax_plain_text());
    // Use base16-ocean.dark as starting theme; map RGB to CGA afterwards
    let mut highlighter = HighlightLines::new(
        syntax,
        &THEME_SET.themes["base16-ocean.dark"],
    );
    let mut result = Vec::new();
    for line in code.lines() {
        // highlight_line signature:
        // pub fn highlight_line<'b>(&mut self, line: &'b str, syntax_set: &SyntaxSet)
        //     -> Result<Vec<(Style, &'b str)>, Error>
        let ranges = highlighter.highlight_line(line, &SYNTAX_SET).unwrap_or_default();
        let spans: Vec<Span<'static>> = ranges.into_iter()
            .map(|(style, text)| {
                let fg = syntect_color_to_cga(style.foreground);
                Span::styled(
                    text.to_string(),  // 'static via owned String
                    Style::default().fg(fg),
                )
            })
            .collect();
        result.push(Line::from(spans));
    }
    result
 }
 ```
 **Note:** `syntect_tui::into_span()` can be used instead of manual conversion, but it passes through RGB colors as `Color::Rgb(r, g, b)`. For strict CGA 16-color output, the manual mapping function below is needed.
 ### Pattern 8: RGB to CGA 16-Color Mapping
 Syntect themes use RGB colors. Map to nearest CGA 16 color for terminal compatibility:
 ```rust
 // Source: ratatui Color variants documented at
 // https://docs.rs/ratatui/0.30.0/ratatui/style/enum.Color.html
 use syntect::highlighting::Color as SyntectColor;
 use ratatui::style::Color;
 /// Map a syntect RGB color to the nearest CGA 16-color ratatui Color.
 /// Uses Euclidean distance in RGB space.
 pub fn syntect_color_to_cga(c: SyntectColor) -> Color {
    // CGA 16 palette: (r, g, b, Color variant)
    const CGA: &[(u8, u8, u8, Color)] = &[
        (0,   0,   0,   Color::Black),
        (170, 0,   0,   Color::Red),
        (0,   170, 0,   Color::Green),
        (170, 170, 0,   Color::Yellow),
        (0,   0,   170, Color::Blue),
        (170, 0,   170, Color::Magenta),
        (0,   170, 170, Color::Cyan),
        (170, 170, 170, Color::Gray),
        (85,  85,  85,  Color::DarkGray),
        (255, 85,  85,  Color::LightRed),
        (85,  255, 85,  Color::LightGreen),
        (255, 255, 85,  Color::LightYellow),  // also Color::Yellow bright variant
        (85,  85,  255, Color::LightBlue),
        (255, 85,  255, Color::LightMagenta),
        (85,  255, 255, Color::LightCyan),
        (255, 255, 255, Color::White),
    ];
    let mut best = Color::White;
    let mut best_dist = u32::MAX;
    for &(r, g, b, color) in CGA {
        let dr = (c.r as i32 - r as i32).pow(2) as u32;
        let dg = (c.g as i32 - g as i32).pow(2) as u32;
        let db = (c.b as i32 - b as i32).pow(2) as u32;
        let dist = dr + dg + db;
        if dist < best_dist {
            best_dist = dist;
            best = color;
        }
    }
    best
 }
 ```
 **Alternative approach:** Assign CGA colors by syntect scope name rather than RGB proximity. Scope names like `keyword`, `string.quoted`, `comment` can be mapped directly to desired CGA colors without going through RGB at all. This is more predictable for the BBS aesthetic but requires scope inspection from syntect's `ScopeRegionIterator`. For Phase 2, RGB proximity is simpler and sufficient.
 ### Pattern 9: Terminal Resize Handling
 ```rust
 // Source: https://ratatui.rs/faq/
 // Source: https://docs.rs/ratatui/0.30.0/ratatui/struct.Terminal.html
 // In the event loop (extending Phase 1 pattern):
 match event::read()? {
    Event::Key(key) => { self.handle_key(key); }
    Event::Resize(_w, _h) => {
        // For Viewport::Fullscreen: Terminal::draw() calls autoresize() internally.
        // Buffer is resized automatically on next draw call.
        // No explicit action needed — just let the next draw() handle it.
        // HOWEVER: recompute max_scroll after resize since content_area.height changes.
        // This happens naturally because max_scroll is computed inside draw().
    }
    _ => {}
 }
 ```
 **Key finding:** `Viewport::Fullscreen` + `Terminal::draw()` automatically resizes the internal buffer when terminal size changes. No explicit `terminal.autoresize()` call is needed. The draw closure receives a `Frame` whose `frame.area()` reflects the current terminal size. Scroll offset recomputation happens inside the draw closure naturally.
 ### Pattern 10: GFM Table Two-Pass Rendering
 Tables require knowing all column widths before emitting any lines:
 ```rust
 // Phase 1: Collect all cells during event parsing
 // Phase 2: Emit box-drawing grid
 pub fn emit_table(
    alignments: &[Alignment],
    rows: &[Vec<String>],    // rows[0] = header row
    lines: &mut Vec<Line<'static>>,
 ) {
    let n_cols = alignments.len();
    // Compute column widths
    let mut col_widths: Vec<usize> = vec![3; n_cols];
    for row in rows {
        for (i, cell) in row.iter().enumerate() {
            if i < n_cols {
                col_widths[i] = col_widths[i].max(cell.len() + 2); // padding
            }
        }
    }
    // Top border: ┌──────┬──────┐
    let top = build_table_row('┌', '┬', '┐', '─', &col_widths);
    lines.push(Line::from(Span::styled(top, Style::default().fg(Color::Cyan))));
    // Header row with bold CGA styling
    if let Some(header) = rows.first() {
        let row_line = build_table_data_row(header, &col_widths, alignments,
            Style::default().fg(Color::LightCyan).add_modifier(Modifier::BOLD));
        lines.push(row_line);
        // Header separator: ├──────┼──────┤
        let sep = build_table_row('├', '┼', '┤', '─', &col_widths);
        lines.push(Line::from(Span::styled(sep, Style::default().fg(Color::Cyan))));
    }
    // Data rows
    for row in rows.iter().skip(1) {
        let row_line = build_table_data_row(row, &col_widths, alignments,
            Style::default());
        lines.push(row_line);
    }
    // Bottom border: └──────┴──────┘
    let bottom = build_table_row('└', '┴', '┘', '─', &col_widths);
    lines.push(Line::from(Span::styled(bottom, Style::default().fg(Color::Cyan))));
    lines.push(Line::default()); // spacing after table
 }
 ```
 ### Pattern 11: File Loading and Error State
 ```rust
 // Source: stdlib std::fs
 pub enum VaultDocument {
    Loaded { path: PathBuf, content: String },
    Missing { path: PathBuf },
    ReadError { path: PathBuf, reason: String },
 }
 pub fn load_document(vault_path: &Path, relative: &str) -> VaultDocument {
    let full_path = vault_path.join(relative);
    match std::fs::read_to_string(&full_path) {
        Ok(content) => VaultDocument::Loaded { path: full_path, content },
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            VaultDocument::Missing { path: full_path }
        }
        Err(e) => VaultDocument::ReadError {
            path: full_path,
            reason: e.to_string(),
        },
    }
 }
 ```
 The missing index.md error screen is a custom `ErrorScreenWidget` that renders a BBS-styled box with box-drawing borders:
 ```
 ┌─────────────────────────────────────────┐
 │  *** SYSTEM ERROR ***                   │
 │                                         │
 │  No index.md found in vault:            │
 │  /path/to/vault                         │
 │                                         │
 │  Create index.md to begin.              │
 └─────────────────────────────────────────┘
 ```
 ### Anti-Patterns to Avoid
 - **Lifetime-borrowing `Line<'a>` from input markdown string:** The markdown string goes out of scope or is reloaded. Always convert to `Line<'static>` (owned `String` in each `Span`) during rendering. This costs a small allocation but avoids pervasive lifetime annotations through `App`.
 - **Calling `SyntaxSet::load_defaults_newlines()` per document:** Loading the embedded syntax set takes ~23ms. Call it once at startup. Use `lazy_static!` or pass a `&SyntaxSet` reference.
 - **Forgetting `Options::ENABLE_TABLES`:** Without this flag, `Parser::new_ext()` will not emit `Tag::Table` events. Table markdown is silently treated as plain text with pipe characters. Always set GFM extension flags explicitly.
 - **Not using `TextMergeStream`:** pulldown-cmark may split a single logical text run across multiple `Event::Text` events when inline formatting markers exist nearby (e.g., text before an emphasis marker). `TextMergeStream::new(parser)` coalesces adjacent `Text` events before your handler sees them.
 - **Rendering live `Block` widgets inside the lines Vec:** `Block` is a ratatui widget that requires a `Rect` and `Buffer` to render. You cannot embed it inside `Vec<Line>`. All box-drawing for code blocks and tables must be emitted as raw character spans (│, ╭, ─, etc.) in the Line sequence.
 - **Scroll offset as `i32` or signed:** Use `u16` throughout. `saturating_sub` handles underflow. `saturating_add` + `min(max)` handles overflow. Paragraph::scroll() takes `(u16, u16)` — passing `usize` requires explicit cast.
 - **Using `Paragraph::scroll()` with `Wrap` enabled:** When Paragraph wraps lines, `line_count()` reflects wrap expansion, but the input `Line` objects do not change. The scroll offset applies to rendered lines, not input lines. For pre-rendered markdown (one `Line` per logical line), disable `Wrap` to keep scroll math simple and predictable.
 ---
 ## Don't Hand-Roll
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | Markdown parsing | Custom parser | pulldown-cmark 0.13.1 | CommonMark spec compliance, edge cases (nested emphasis, escaped chars, HTML entities) |
 | Syntax tokenization | Keyword regex lists | syntect 5.3.0 | 80+ languages, Sublime text definitions, maintained separately |
 | Color conversion (syntect→ratatui) | Manual RGB conversion | syntect-tui 3.0 `into_span()` | Handles style flag mapping (bold, italic from theme); only override for CGA quantization |
 | Table column widths | Screen-width allocation | Two-pass cell collection + max() | Tables need all cell content before first border char can be emitted |
 **Key insight:** The pulldown-cmark event stream is a correct CommonMark parser; building on top of it is always correct. The only custom logic needed is converting events to ratatui `Line` objects — this is inherently application-specific and there is no general library that produces BBS-CGA-styled output.
 ---
 ## Common Pitfalls
 ### Pitfall 1: Widget Trait Signature Changed in 0.29/0.30
 **What goes wrong:** Code written for ratatui <= 0.28 using `WidgetRef` directly fails to compile with 0.30. Code that `impl WidgetRef for Foo` instead of `impl Widget for &Foo` no longer works.
 **Why it happens:** In 0.30, `WidgetRef` no longer has a blanket impl of `Widget`. The relationship inverted: `impl Widget for &W` is now the canonical pattern for immutable reference-based widgets.
 **How to avoid:** Use `impl Widget for &MyWidget` (consuming a reference) for stored, reusable widgets. Use `impl Widget for MyWidget` (consuming ownership) for one-shot widgets created in the draw closure. Do NOT implement `WidgetRef` directly.
 **Warning signs:** Compiler error "the trait `Widget` is not implemented for `MyWidget`" when passing a stored widget to `frame.render_widget()`.
 ### Pitfall 2: pulldown-cmark Table Events Not Firing
 **What goes wrong:** Markdown tables render as plain text with pipe characters instead of structured tables.
 **Why it happens:** `Options::ENABLE_TABLES` is not set. Tables are a GFM extension, not CommonMark. They require explicit opt-in.
 **How to avoid:** Use `Parser::new_ext(input, opts)` with `opts.insert(Options::ENABLE_TABLES)`. Verify with a test document containing a table.
 **Warning signs:** `| col1 | col2 |` appears verbatim in output instead of a box-drawing grid.
 ### Pitfall 3: Consecutive Text Events Splitting Styled Runs
 **What goes wrong:** Text like `Hello *world* there` produces four separate `Event::Text` events — "Hello ", then inside the emphasis a "world" text, then "world" again, then " there" — causing broken styled spans.
 **Why it happens:** pulldown-cmark's internal state machine may emit multiple adjacent `Text` events at inline formatting boundaries.
 **How to avoid:** Wrap the parser in `TextMergeStream::new(parser)` before iterating events. This coalesces adjacent `Text` events into single events.
 **Warning signs:** Text appears duplicated or styling bleeds into adjacent text.
 ### Pitfall 4: Syntect Load on Every Document
 **What goes wrong:** Loading `SyntaxSet::load_defaults_newlines()` takes ~23ms. If called on each document load, it adds perceptible lag on navigation.
 **Why it happens:** The embedded syntax definitions are a ~200KB compressed binary blob that requires decompression and linking on each call.
 **How to avoid:** Initialize `SyntaxSet` and `ThemeSet` once at program startup. Store in a module-level `OnceLock<SyntaxSet>` or pass as shared references. Do not call `load_defaults_*` inside document rendering loops.
 **Warning signs:** Noticeable lag when switching documents (Phase 3 concern, but architecture must support it from Phase 2).
 ### Pitfall 5: Scroll Math with Paragraph::scroll() is (y, x) Not (x, y)
 **What goes wrong:** Passing `(horizontal, vertical)` produces sideways scrolling instead of vertical scrolling.
 **Why it happens:** The `Paragraph::scroll()` method takes `(y, x)` — vertical first, horizontal second. This is the opposite of typical (x, y) coordinate convention. The ratatui documentation explicitly flags this as a deliberate deviation from crate convention.
 **How to avoid:** Always write `paragraph.scroll((self.scroll_offset, 0))` where the first element is vertical scroll and the second is always `0` (no horizontal scroll for a markdown reader).
 **Warning signs:** Content scrolls horizontally but not vertically when pressing j/k.
 ### Pitfall 6: Line<'static> vs Line<'a> Lifetime Confusion
 **What goes wrong:** Storing `Vec<Line<'a>>` in `App` where `'a` is tied to the markdown string lifetime causes the borrow checker to reject the code because `App` must outlive the borrowed string.
 **Why it happens:** If `Span` content is borrowed `&str` from the markdown string, the `Line` borrows from that string. When the string is dropped or replaced, all the `Line` objects become invalid.
 **How to avoid:** Always use `.to_string()` or `.into_owned()` when creating `Span` content during rendering: `Span::styled(text.to_string(), style)`. This makes every `Span` own its content (`'static`). `Vec<Line<'static>>` can be stored in `App` without lifetime parameters.
 **Warning signs:** Compiler error "cannot infer an appropriate lifetime for borrow expression" in the renderer function.
 ### Pitfall 7: Missing index.md Should NOT Panic
 **What goes wrong:** `std::fs::read_to_string(vault_path.join("index.md")).unwrap()` panics if index.md is missing, leaving the terminal in raw mode.
 **Why it happens:** Missing files are an expected user-facing state (new vault), not a bug. `unwrap()` on `Result` converts expected errors into panics.
 **How to avoid:** Use `match` or `.map_err()` to convert `io::Error` to a `VaultDocument::Missing` state. The App then renders the BBS error screen widget instead of a document widget. Never unwrap file I/O operations.
 **Warning signs:** Terminal stuck in raw mode after starting with an empty vault directory.
 ---
 ## Code Examples
 Verified patterns from official sources:
 ### CGA Color Assignments for Headings (Claude's Discretion)
 Based on CGA palette and BBS aesthetic — assigned by researcher:
 | Level | Color | Decorator |
 |-------|-------|-----------|
 | H1 | `Color::LightCyan` + `Modifier::BOLD` | `══════` (double-line, full width) |
 | H2 | `Color::LightYellow` + `Modifier::BOLD` | `──────` (single-line, full width) |
 | H3 | `Color::LightGreen` + `Modifier::BOLD` | none (color only) |
 | H4 | `Color::Green` | none |
 | H5 | `Color::Cyan` | none |
 | H6 | `Color::DarkGray` | none |
 ### CGA Colors for Syntax Highlighting (Claude's Discretion)
 For syntax scopes mapped to CGA colors:
 | Scope Category | CGA Color |
 |----------------|-----------|
 | Keywords (`fn`, `let`, `if`, etc.) | `Color::LightCyan` |
 | Strings | `Color::LightGreen` |
 | Comments | `Color::DarkGray` |
 | Numbers | `Color::LightYellow` |
 | Types/classes | `Color::Yellow` |
 | Functions/methods | `Color::LightMagenta` |
 | Operators | `Color::Gray` |
 | Default/text | `Color::Gray` |
 ### Blockquote Style (Claude's Discretion)
 ```
 │ This is a blockquote line
 │ with a second line.
 ```
 - Left border `│` in `Color::Yellow`
 - Content in `Color::Gray` (slightly dimmed from default)
 - One blank line before and after
 ### Horizontal Rule Style (Claude's Discretion)
 ```
 ────────────────────────────────────────
 ```
 Full-width `─` characters in `Color::DarkGray`. One blank line before and after.
 ### Image Placeholder Style (Claude's Discretion)
 ```
 [IMAGE: alt text here]
 ```
 `Color::DarkGray` + `Modifier::DIM`. Surrounded by blank lines if block-level.
 ### List Bullet Style (Claude's Discretion)
 - Unordered: `  •  ` in `Color::Cyan`, content in default color
 - Ordered: `  1. ` in `Color::Cyan`, content in default color
 - Nested (each level adds 2 spaces): `    ◦  ` for depth 2, `      ▪  ` for depth 3
 ### Scroll Boundary Behavior (Claude's Discretion)
 **Stop at boundaries** (not bounce): `scroll_offset = scroll_offset.saturating_sub(1)` for up, `scroll_offset = (scroll_offset + 1).min(max_scroll)` for down. Scroll stops silently at top/bottom — no visual indicator needed in Phase 2.
 ### Complete pulldown-cmark Parser Setup
 ```rust
 // Source: https://docs.rs/pulldown-cmark/latest/pulldown_cmark/
 use pulldown_cmark::{Options, Parser, TextMergeStream};
 pub fn make_parser(input: &str) -> impl Iterator<Item = pulldown_cmark::Event<'_>> {
    let mut opts = Options::empty();
    opts.insert(Options::ENABLE_TABLES);
    opts.insert(Options::ENABLE_STRIKETHROUGH);
    opts.insert(Options::ENABLE_TASKLISTS);
    opts.insert(Options::ENABLE_GFM);  // blockquote alert syntax
    opts.insert(Options::ENABLE_HEADING_ATTRIBUTES);  // {#id .class} on headings
    TextMergeStream::new(Parser::new_ext(input, opts))
 }
 ```
 ### syntect Initialization (Once at Startup)
 ```rust
 // Source: https://docs.rs/syntect/latest/syntect/
 use std::sync::OnceLock;
 use syntect::highlighting::ThemeSet;
 use syntect::parsing::SyntaxSet;
 static SYNTAX_SET: OnceLock<SyntaxSet> = OnceLock::new();
 static THEME_SET: OnceLock<ThemeSet> = OnceLock::new();
 pub fn init_highlighter() {
    SYNTAX_SET.get_or_init(SyntaxSet::load_defaults_newlines);
    THEME_SET.get_or_init(ThemeSet::load_defaults);
 }
 pub fn syntax_set() -> &'static SyntaxSet {
    SYNTAX_SET.get().expect("init_highlighter() not called")
 }
 pub fn theme_set() -> &'static ThemeSet {
    THEME_SET.get().expect("init_highlighter() not called")
 }
 ```
 ### App State Extension for Phase 2
 ```rust
 // Extending Phase 1 App struct
 pub struct App {
    // Phase 1 fields (unchanged)
    is_login_shell: bool,
    ctrl_c_pressed_at: Option<Instant>,
    show_quit_prompt: bool,
    should_quit: bool,
    config: Config,
    // Phase 2 additions
    document: DocumentState,
    scroll_offset: u16,
 }
 pub enum DocumentState {
    Rendering,                           // initial state during parse
    Loaded {
        filename: String,
        lines: Vec<Line<'static>>,
    },
    Missing {
        path: PathBuf,
    },
    Error {
        path: PathBuf,
        reason: String,
    },
 }
 ```
 ---
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | `impl WidgetRef for Foo` | `impl Widget for &Foo` | ratatui 0.29/0.30 (2024-2025) | Previous WidgetRef impl pattern no longer compiles; must update if migrating from older ratatui |
 | `Parser::new()` only | `Parser::new_ext(input, opts)` with Options flags | pulldown-cmark 0.9+ | Extensions like tables require explicit opt-in via Options struct |
 | syntect with Oniguruma C lib | `default-features = false, features = ["default-fancy"]` | syntect 4.0 (2022) | Avoids C compilation; pure-Rust regex engine; simpler build on Linux servers |
 | Manual scroll state management | `Paragraph::scroll((y, 0))` | ratatui stable | Paragraph handles the offset; app only needs to track the u16 offset value |
 **Deprecated/outdated:**
 - `tui-rs`: The predecessor crate to ratatui. All docs using `tui::widgets::*` are from this era. Not applicable.
 - `syntect::highlighting::HighlightIterator`: The lower-level iterator API. `easy::HighlightLines` is the preferred high-level wrapper.
 - `pulldown_cmark::html::push_html`: The HTML output function. Phase 2 never produces HTML; ignore this API.
 ---
 ## Open Questions
 1. **syntect-tui 3.0 ratatui 0.30 compatibility**
   - What we know: syntect-tui 3.0 targets ratatui. The crate list shows syntect-tui 3.0 most recently updated.
   - What's unclear: Whether syntect-tui 3.0 has been tested specifically against ratatui 0.30.0. The Widget trait change in 0.30 only affects widget implementations, not `Span`/`Style` types which syntect-tui converts. The risk is LOW.
   - Recommendation: Add `syntect-tui = "3.0"` and `syntect = "5.3"` to Cargo.toml. If compilation fails due to ratatui version mismatch, use manual syntect-style-to-ratatui-style conversion (the Pattern 8 RGB-to-CGA function handles the whole pipeline anyway).
 2. **Horizontal rule width at parse time**
   - What we know: `Event::Rule` fires during markdown parsing before we know the terminal width. Full-width `─────` requires knowing `area.width` which is only available inside `frame.render_widget()`.
   - What's unclear: Best approach to defer width-dependent rendering.
   - Recommendation: Emit a sentinel `Line` with a special marker during parsing (e.g., `Line::from(Span::raw("--- RULE ---"))`). In the widget's `render()` method, detect this sentinel and replace it with `"─".repeat(area.width)`. Alternatively, emit a fixed 80-char rule and accept that it won't be exact width.
 3. **Table rendering width constraint**
   - What we know: Tables with many wide columns may exceed terminal width. The two-pass approach computes column widths from content, not from available terminal width.
   - What's unclear: Whether to truncate, wrap, or overflow table cells.
   - Recommendation: For Phase 2, emit tables at natural content width and let the terminal clip. Horizontal scrolling is not required (NAV-05 only specifies vertical scroll). Address overflow in Phase 3 if reported.
 4. **OnceLock for syntect vs. passing as parameter**
   - What we know: `OnceLock` is in stable `std` since Rust 1.70. The project uses edition 2024.
   - What's unclear: Whether to initialize `SyntaxSet`/`ThemeSet` in `main.rs` and pass down, or use module-level `OnceLock`.
   - Recommendation: Initialize in `main.rs` before `App::new()`, store `SyntaxSet` in `App`. Avoids global state and is more testable. `SyntaxSet` is `Send + Sync` so storing in App is fine.
 ---
 ## Sources
 ### Primary (HIGH confidence)
 - `https://docs.rs/pulldown-cmark/latest/pulldown_cmark/enum.Event.html` — 13 Event variants documented, including all Phase 2 relevant types
 - `https://docs.rs/pulldown-cmark/latest/pulldown_cmark/enum.Tag.html` — Complete Tag enum: Heading{level, id, classes, attrs}, List(Option<u64>), CodeBlock(CodeBlockKind), Table(Vec<Alignment>), TableHead, TableRow, TableCell
 - `https://docs.rs/pulldown-cmark/latest/pulldown_cmark/struct.Options.html` — 15 Options flags documented, including ENABLE_TABLES, ENABLE_STRIKETHROUGH, ENABLE_TASKLISTS, ENABLE_GFM
 - `https://docs.rs/ratatui/0.30.0/ratatui/widgets/trait.Widget.html` — Verified Widget trait: `fn render(self, area: Rect, buf: &mut Buffer) where Self: Sized`
 - `https://docs.rs/ratatui/0.30.0/ratatui/widgets/struct.Paragraph.html` — scroll((y, x): (u16, u16)), line_count(width: u16) -> usize
 - `https://docs.rs/ratatui/0.30.0/ratatui/style/struct.Style.html` — fg(), bg(), add_modifier(), Modifier constants: BOLD, ITALIC, DIM, UNDERLINED, REVERSED
 - `https://docs.rs/ratatui/0.30.0/ratatui/style/enum.Color.html` — Named colors: Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White, Reset
 - `https://docs.rs/ratatui/0.30.0/ratatui/widgets/struct.Block.html` — BorderType::Rounded produces ╭╮╰╯ corners
 - `https://ratatui.rs/highlights/v030/` — Breaking change: WidgetRef no longer blanket-implements Widget; use `impl Widget for &Foo` pattern
 - `https://docs.rs/syntect/latest/syntect/easy/struct.HighlightLines.html` — highlight_line<'b>(&mut self, line: &'b str, &SyntaxSet) -> Result<Vec<(Style, &'b str)>, Error>
 - `https://docs.rs/syntect/latest/syntect/` — Version 5.3.0 confirmed; embedded syntax set ~200KB; load time ~23ms
 - `https://ratatui.rs/faq/` — Resize: Event::Resize captured via crossterm; Viewport::Fullscreen autoresizes buffer in draw()
 ### Secondary (MEDIUM confidence)
 - `https://github.com/chanq-io/syntect-tui` — syntect-tui 3.0: `into_span()` converts `(syntect::Style, &str)` to `ratatui::Span`; MIT license
 - `https://ratatui.rs/recipes/widgets/custom/` — Widget impl patterns for 0.30: consuming vs reference-based
 - `https://github.com/joshka/tui-markdown` — Experimental PoC; not suitable for BBS aesthetic without heavy forking; reference only
 ### Tertiary (LOW confidence, flag for validation)
 - syntect-tui 3.0 compatibility with ratatui 0.30.0 — not explicitly verified against 0.30; Style/Span API compatibility inferred from no known breaking changes in those types between 0.28 and 0.30
 - CGA color assignments for syntax scopes (keywords, strings, etc.) — researcher recommendation based on classic BBS aesthetics, not from an authoritative source; adjust during implementation
 ---
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: HIGH — all versions verified via docs.rs; pulldown-cmark 0.13.1, ratatui 0.30.0, syntect 5.3.0 confirmed
 - Architecture: HIGH — Widget trait signature verified from official ratatui 0.30 docs; pulldown-cmark Event and Tag enums verified; Paragraph::scroll() API verified
 - Pitfalls: HIGH for ratatui 0.30 Widget breaking change (confirmed from release notes); HIGH for pulldown-cmark Options flags; MEDIUM for syntect-tui compatibility
 - CGA color assignments: LOW — researcher recommendation, no authoritative source; safe to adjust during implementation
 **Research date:** 2026-02-28
 **Valid until:** 2026-03-30 (stable libraries; pulldown-cmark and ratatui move slowly)