docs 05 - Update architecture documentation and runtime requirements (Bun 1.4+) #145

EPIC: #140
Branch: feat/bun14-terminal
Depends on: #141, #142, #143, #144 (content must be stable before documenting)

Context / Problem

The introduction of src/render/terminal.ts (new pure layer) and the raised minimum Bun runtime requirement are not yet reflected in any documentation:

• AGENTS.md lists project modules, but src/render/terminal.ts is absent and the Bun runtime constraint still reads ">= 1.0".
• docs/architecture/components.md describes the rendering components without the native terminal measurement layer.
• docs/architecture/containers.md does not document the live resize behavior via SIGWINCH.
• README.md does not explicitly state the minimum Bun version.

Solution

AGENTS.md

Runtime and toolchain table: update Bun from ">= 1.0" to ">= 1.4".

Module table (src/ section): add the row:

render/terminal.ts   Pure wrappers around Bun 1.4 native APIs: visibleWidth,
                     stripAnsi, clipToWidth, hasAnsi. No I/O, no external
                     dependencies. The only authorized call site for
                     Bun.stringWidth, Bun.sliceAnsi, and Bun.stripANSI.

"Key architectural principles" section: add the rule:

render/terminal.ts is the only authorized call site for Bun.stringWidth, Bun.sliceAnsi, and Bun.stripANSI. All visible-width calculations and ANSI-aware truncation go through this module.

TUI / tui.ts entry: document that the SIGWINCH handler in tui.ts re-reads process.stdout.rows and process.stdout.columns and triggers an immediate redraw without requiring a keypress.

README.md

Update the Bun version requirement in the installation / getting started section to "Bun >= 1.4", with a reference to the Bun 1.4 release page.

docs/architecture/components.md

Add render/terminal.ts as a pure component in the rendering group, with outbound edges to the three Bun 1.4 native APIs it wraps. Update any existing component diagram if present.

docs/architecture/containers.md

• Document that the TUI process subscribes to SIGWINCH for live terminal resize.
• Note that Bun.Terminal is out of scope for the main TUI: it is a PTY API for child processes, not a way to query the current terminal dimensions.

Updated render-layer component view

graph TD
    subgraph "Application layer"
        tui["src/tui.ts"]
        render["src/render.ts (facade)"]
        teampick["src/render/team-pick.ts"]
    end

    subgraph "Pure render modules"
        terminal["src/render/terminal.ts"]
        rows["src/render/rows.ts"]
        highlight["src/render/highlight.ts"]
        summary["src/render/summary.ts"]
        filter["src/render/filter.ts"]
        selection["src/render/selection.ts"]
    end

    subgraph "Bun 1.4 runtime"
        bun_sw["Bun.stringWidth()"]
        bun_sa["Bun.stripANSI()"]
        bun_sl["Bun.sliceAnsi()"]
    end

    tui --> render
    render --> terminal
    render --> rows
    render --> highlight
    render --> summary
    render --> filter
    render --> selection
    teampick --> terminal

    terminal --> bun_sw
    terminal --> bun_sa
    terminal --> bun_sl

Acceptance Criteria

• AGENTS.md - runtime table: Bun ">= 1.4".
• AGENTS.md - module table: src/render/terminal.ts present with description.
• AGENTS.md - architectural principles: rule on render/terminal.ts as the sole Bun ANSI API call site.
• AGENTS.md - SIGWINCH behavior documented in the tui.ts entry.
• README.md - Bun ">= 1.4" requirement visible in the installation section.
• docs/architecture/components.md - render/terminal.ts present with its Bun 1.4 API edges.
• docs/architecture/containers.md - SIGWINCH behavior and Bun.Terminal scope documented.
• bun run docs:build completes without errors.
• No remaining references to "Bun >= 1.0" in product documentation.

Definition of Done

• PR reviewed and merged into feat/bun14-terminal.
• bun run docs:build passes.
• No stale "Bun >= 1.0" references remain in the docs.