tai/research/tui-framework-design/conclusions/messaging-layout-chat-scene.md

# Conclusion: Telegram-like messaging layout for tai's chat scene

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | tui-framework-design |
| Document type | Conclusion |
| Tier | N/A |
| Date decided | 2026-10-11 |
| Decided by | retoor, advised by tai (agent, Muse Spark) |
| Status | Active |
| Confidence | Medium |

## Question / problem statement

How should tai's Telegram-like chat scene (conversation sidebar, message transcript, input box, status line) be laid out, navigated, and rendered on top of the retained-DOM framework — which geometry, which keybindings, which scroll and send contracts — given that the working tree has no chat-transcript widget, no status-bar widget, no send-on-Enter mode, and no responsive breakpoints (established by the same-session internal inventory of tai.py)?

## Conclusion

Build the chat scene as a left chat list at 30% width (min 24, max 36 columns) beside a right transcript plus input, with the input 3 rows collapsed growing to 5–8 rows with content and a 1-line status bar at the bottom carrying transient status plus per-focus hints on one side and connection/user/chat identity on the other. Ship a manual sidebar toggle first (F2/Ctrl+B or Tab cycle), adding automatic hide below 80 columns only as an enhancement. Navigate modally (Normal/Input) with Tab/Shift+Tab pane cycling, `i`/Enter/Esc, `j`/`k` plus arrows, `g`/`G`, PgUp/PgDn, `/` search, `?` hints, `q` quit. Render left-aligned wrapped rows with sender grouping and per-message sending/failed state (never right-aligned bubbles); render markdown only for assistant content at viewport width minus frame minus gutter; stream by re-setting viewport content with pin-to-bottom only when already at the bottom; show tool calls as collapsible bordered block rows. Input is multiline with Enter to send, Shift+Enter (or Alt+Enter) for newline, per-chat draft retention, send history, and a ~2000-character cap with optimistic echo.

## Supporting sources

- `../telecli-tui-chat-layout.md` — base numbers: 30/70 split, 3-row input, 1-line status overlay, modal Normal/Input keys.
- `../send-rs-tui-draw-main.md` — confirms the 30/70 + 1-line-status skeleton; focused-pane accent border.
- `../send-rs-tui-focus-state.md` — explicit focus state with per-chat draft retention on focus moves.
- `../send-rs-config-keymap.md` — default keymap (Tab cycle, `i`/Enter/Esc, Shift+Enter newline) and 5-line input cap.
- `../send-rs-tui-status-bar.md` — status content policy: per-focus hints with transient-override messages.
- `../send-rs-chat-widget.md` — pre-wrapped rows plus scrollbar, dynamic input height, and the decisive bubble rejection.
- `../za-tui-app-styles.md` — cross-framework corroboration of 30/70 + 3–8-row input + 1-row status.
- `../za-tui-main-screen.md` — manual sidebar toggle (F2/Ctrl+B) with auto-hide deliberately omitted; F6 focus cycle.
- `../za-tui-status-bar.md` — identity half of status content: connection dot + user + active conversation.
- `../za-tui-input-bar.md` — input contract: Enter send, Shift+Enter newline, 2000-char cap, 100-entry history.
- `../za-tui-chat-view.md` — transcript contract: sender grouping, per-message status, conditional pin-to-bottom, scroll-top history load.
- `../bubbletea-chat-example.md` — viewport height math (window minus input) and send-then-bottom behavior.
- `../bubbletea-glamour-example.md` — markdown width-minus-chrome rule (viewport minus frame minus 3-column gutter).
- `../ai-nexus-ratatui-best-practices.md` — provisional sub-80-column breakpoint number (guidance-doc sourced, flagged as such).

## Alternatives considered and rejected

- Right-aligned outgoing bubbles: rejected — send-rs implemented them and reverted them as ugly; all shipped clients use left-aligned rows.
- Automatic sidebar auto-hide from day one: rejected as v1 — za-tui deliberately omitted it (breaks tests) and ships manual toggle; auto-hide below 80 columns follows as an enhancement.
- Sidebar-free full-width layout (bubbletea chat example): rejected — tai needs a conversation/agent list beside the transcript.
- Fixed-cell sidebar width (`Length(30)`): rejected — appears only in the guidance doc while every inspected client uses `Percentage(30)`; percentage with min/max clamps wins.
- Always-stacked layout: rejected — all three messaging clients ship side-by-side as the default, stacking only as the narrow fallback.

## Risks / open questions

- The 80-column breakpoint comes from a guidance doc, not a shipped client — no inspected real client implements automatic narrow-terminal breakpoints. Validate the number against real terminals before treating it as settled.
- No streaming/token rendering or tool-call blocks were observed in any messaging client; the re-set-plus-pin-to-bottom carrier and collapsible-block rows are inferred patterns, with Glamour covering static markdown only.
- tai still needs a markdown-to-styled-run renderer (the REPL's `render_markdown` emits ANSI strings unusable by the compositor), a send-on-Enter input mode, and a wide-character width table — all established gaps from the same-session inventory.
- Agent turns are blocking and must run in threads posting back via timers; the streaming contract assumes that bridge works.

## Action taken

Nothing built yet: the chat scene is specified by this conclusion and its sources, but no chat-transcript widget, status-bar widget, or scene builder exists in the working tree. This conclusion records what to build, not what shipped.

## Changelog

| Date | Change |
|---|---|
| 2026-10-11 | Initial conclusion recorded. |