bug(tui): token dashboards overflow small terminal viewports

[styler-ai]

Why

The token overview and trend snapshots render fixed buffers with an 80-column minimum and fixed heights. A smaller terminal can therefore wrap rows or scroll the top of the dashboard out of view. The overview also measures width separately for graph loading and rendering, allowing a resize-dependent decision and unnecessary graph work.

Ratatui can collapse over-constrained areas, so shrinking the existing full dashboard does not define which facts survive. The terminal boundary needs one captured two-dimensional viewport and a deliberately bounded compact presentation.

What Changes

• Capture one validated terminal viewport for each token TUI invocation.
• Prefer the live terminal size; use valid non-zero COLUMNS and LINES only as deterministic non-TTY fallbacks, then the established valid default.
• Preserve the existing full overview at 80 by 50 or larger and full trend at 80 by 30 or larger.
• Render a bounded compact Ratatui snapshot below either full-layout boundary.
• Use the same viewport to decide whether the optional Atlas preview is loaded and rendered.
• Add unit, real CLI, platform, installed-candidate, and human-terminal regressions at the exact boundaries.

Capabilities

• terminal-bounded-token-dashboard: overview and trend snapshots remain within the selected terminal viewport and retain their highest-priority signed facts as space permits.

Architecture Diagrams

• Token dashboard viewport selection

Release Scope

ProjectAtlas v0.4.5-rc2 correctness fix in the existing CLI token TUI adapter, required CI, packaged release verification, and durable terminal guidance.

Non-Goals

• Add an interactive resize loop, persistent terminal session, renderer trait, new dependency, or second output system.
• Compress every full-size panel into an unreadable miniature.
• Change token telemetry storage, calculation, MCP payloads, or database schemas.
• Load or display the Atlas preview when compact mode cannot present it usefully.

Pre-Mortem

Likely failure modes:

1. Width is bounded while short terminals still lose top content or collide with the prompt.
2. Graph loading and rendering consult different viewport measurements.
3. Compact output hides or changes the sign of the primary saving.
4. Invalid or zero fallback dimensions create a zero-sized backend or panic.
5. Source tests pass while a packaged binary still wraps in a real terminal.

Mitigations:

• Bound both dimensions through one captured viewport and verify wide-but-short plus narrow cases. (OpenSpec tasks: 2.1, 2.2, 2.3, 3.2, 3.3)
• Use that same viewport for graph loading, layout, buffer construction, and serialization. (OpenSpec tasks: 2.1, 2.2, 3.1)
• Preserve signed facts and semantic styles in compact unit and CLI coverage. (OpenSpec tasks: 2.3, 3.1, 3.2)
• Reject invalid or zero dimensions before TestBackend and use a valid deterministic fallback. (OpenSpec tasks: 2.1, 3.1, 3.2)
• Run cross-platform and installed-candidate contracts plus real terminal visual review. (OpenSpec tasks: 3.2, 3.3, 3.4, 3.5)

OpenSpec Tasks

1. Contract And Architecture

• 1.1 Map issue bug(tui): token dashboards overflow small terminal viewports #462 to this change, synchronize its objective checklist, and keep RC2 scope limited to one captured viewport plus a bounded compact fallback.
• 1.2 Update the token telemetry diagram and durable terminal guidance only where the viewport decision changes the flow; render every changed Mermaid block and inspect it visually and semantically.

2. Viewport And Compact Rendering

• 2.1 Add one validated columns-and-rows viewport capture with live-terminal authority, deterministic non-TTY fallbacks, zero/invalid handling, and no duplicate measurement.
• 2.2 Select full overview, full trend, compact overview, compact trend, and optional Atlas loading from that captured viewport while preserving supported full-layout behavior.
• 2.3 Render compact overview and trend snapshots through the existing Ratatui buffer and ANSI serializer with priority-ordered signed facts, semantic styles, bounded truncation, and propagated render errors.

3. Mandatory Regression And Release Proof

• 3.1 Add deterministic unit tests for viewport resolution, every width/height boundary, buffer bounds, signed negative values, themes, compact fact priority, full-layout compatibility, and Atlas suppression.
• 3.2 Add real CLI subprocess tests for bounded ANSI rows/cells, invalid and zero dimensions, overview and trend boundaries, output failure, and wide-but-short graph suppression without implicit mutation.
• 3.3 Wire the named terminal-size CLI contract into required Linux, Windows, and macOS CI plus Linux and Windows installed-candidate release checks; perform Windows ConPTY and representative Linux/macOS visual review.
• 3.4 Run focused tests, cargo fmt --check, cargo check --workspace --all-targets --all-features, warnings-denied workspace Clippy, full workspace/all-feature and doc tests, warnings-denied docs, strict OpenSpec, IssueOps checklist parity, ProjectAtlas lint, and bounded-output checks with explicit timeouts.
• 3.5 Update durable TUI, release, platform, accessibility, and failure guidance; resolve or disposition every live review and automated finding and verify the exact packaged RC2 behavior without displacing v0.4.4 Latest.
• 3.6 Review the final implementation against the architecture diagrams, update the diagrams or implementation until they agree, or reconfirm the reasoned N/A.