improvise/context/code/tui.md

The terminal front end (src/)

The root crate is the ratatui binary: src/draw.rs (event loop and frame composition), src/ui/*.rs (the widgets), src/main.rs (clap). It is one of two front ends, and design-principles §5 is the rule it is judged by — it paints and wires, and every decision with a silently wrong answer is made in improvise-protocol so the browser cannot answer it differently.

Test narratives live in context/test-evidence/tui.md. Facts about GridCache, AxisFrame, Projection and the Command/Effect layer belong to context/code/protocol.md and context/code/command.md; this file cites them and does not restate them.

---

src/ui/grid.rs — GridWidget

The grid is drawn from a GridCache (improvise-n10).

No &Model. Every value the grid paints — each cell's text, whether it is an aggregate, the column widths, the page bar and the totals strip — arrives already decided, on the cache. A widget that cannot reach the model cannot quietly answer a question differently from the way the browser client answers it, and that divergence is the whole thing projecting exists to prevent.

The frame comes off the cache too (improvise-anr9). GridCache carries an AxisFrame per axis — the header levels, the label tuples and the groups with their collapse state — so the multi-level headers, the repeat suppression, the group spans and the pieces below are all read rather than derived, and a browser painting the same frame paints the same thing. It used to be derived here from GridLayout + View::is_group_collapsed while the protocol carried GridLayout::row_label's slash-joined form — the rendering two_row_categories_produce_cross_product_labels asserts must not appear — so the browser drew Food/Alice.

Two things are still not on the cache and are passed separately, each a different kind of absence:

• layout resolves a records-mode column (record_col), and only that. It keys drill_state's pending edits, so it is session-local by design and correct to keep off the wire (gotcha 1).
• drill_state is session-local residue (gotcha 30). Pending drill edits belong to whoever staged them and are deliberately not projected, so they shadow the cache rather than being on it.

The cache is expected to cover the whole grid — offsets zero, every row and every column — so a position in it is an absolute position and the widget's scrolling arithmetic is unchanged.

Inside render_grid

GridWidget::cursor is this client's cursor in the active view (improvise-8uz), passed in rather than read off View, which no longer carries per-client state.

Everything about the frame is the cache's answer (improvise-anr9): how many header levels, what each level's label is, which group a position sits in and whether that group is collapsed. Nothing in render_grid reads GridLayout or View, so a browser folding the same AxisFrame draws the same header.

The bulk forms are built once per frame, and that is not a micro-optimisation. header_labels(offset), groups() and shares_ancestry(sel_col) each make one pass. The per-position accessors (item, label, shows_level, group_of, same_prefix) scan the frame from the start, so asking them inside the draw loops is quadratic in the grid and, at a deep scroll offset, grows with the offset. col_lines transposes header_labels to level-major because the column header is drawn one line per level while header_labels answers per column.

The underline on the column header marks columns sharing sel_col's ancestor group through each level: at the bottom level that is only sel_col, at higher levels it spans all the sub-columns.

Pending drill edits shadow the projected value. They are this session's uncommitted typing and by construction are not on the cache (gotcha 30).

Aggregate cells are drawn in italic to signal "drill to edit", and the fact is not re-derived here: the projection already named what each cell is, and CellId::Aggregate is exactly that fact (ADR 002), decided once by the side that holds the model. The widget used to walk none_cats × kind.is_regular() — a second hand-rolled copy of project::cell_id.

Whether there is a total row at all is the cache's answer. An empty totals strip means "no totals" (records mode, or an empty grid), which is why the widget does not read is_records_mode a second time.

The collapse glyph (indicator) is the one thing that is legitimately local: the fact — whether the group is collapsed — is on the frame; only its spelling is the terminal's (design-principles §5).

---

src/draw.rs

The key-event boundary

convert_key_event / convert_key_code / convert_modifiers are the only place crossterm's key types and the crate's own command::key types may both appear. Three rules:

• The event loop converts every incoming Event::Key regardless of KeyEventKind (Press/Repeat/Release), matching the pre-conversion behaviour, which never inspected the kind.
• Codes the command layer does not model (media keys, Insert, …) become KeyCode::Null, which no keymap binds.
• SHIFT/CONTROL/ALT survive; every other modifier bit (SUPER, HYPER, META) is dropped.

Semantic-to-terminal colour, and the one that is wrong

This file holds the mapping design-principles §5 names as the shape everything else should imitate: the decision lives in the shared layer as a semantic enum, and only the last translation is local.

• axis_fg(AxisColor) -> Color — Axis::color is the single place each axis's accent is decided; this is the single place axis colouring is rendered (improvise-rml, gotcha 26). Before it, the tile bar and the category panel each carried their own copy of the colour table with nothing keeping them in agreement.
• minibuf_fg(MinibufColor) -> Color — the same shape for the minibuffer.
• src/ui/import_wizard_ui.rs::field_kind_fg(WizardFieldKind) -> Color — the same shape again. improvise-protocol must not name a ratatui Color.

mode_style(&AppMode) -> Style stays here for the same reason (Style and Color are ratatui types and improvise-command, where AppMode lives, carries no rendering-framework dependency), and since improvise-zx8t it is exhaustive: the thirteen variants that take the default chrome are spelled out rather than swept up by a _ => wildcard, so adding an AppMode fails the build here until someone chooses its colour. The arithmetic is the check a prose count does not get: 13 + Editing/RecordsEditing + CommandMode + TileSelect = 17, which is AppMode's variant count. It read fourteen until 2026-09-22, and nothing could have caught that — a count written in prose is checked by no one.

It is still not quite the same shape as axis_fg and its two siblings, and the difference is deliberate rather than pending. Those three map a semantic enum the shared layer owns; mode_style matches AppMode itself, because there is no ModeColor. improvise-zx8t offered making one, and it was declined here for two reasons: the colour is the only thing at stake, and the ticket says to decide it together with improvise-k099, which asks the same question of hint_text/label and is not in this unit. Exhaustiveness is what the repo map's "the compiler names every one you must fill in" promise needed; a semantic enum is a separate, larger answer and is still open.

The guard is the compiler, not a test. Nothing asserts the colours, and a test enumerating the variants would not fail when a fifteenth is added — only the missing match arm does. Verified by deleting the AppMode::Help arm: error[E0004]: non-exhaustive patterns: &AppMode::Help not covered.

The minibuffer shares the bottom row with the status line

draw_bottom_bar used to render the minibuffer instead of draw_status, so a status message written while any text-entry mode was open was never drawn (improvise-mai9, and the stranding gotcha 21 describes). minibuffer_line composes both: the prompt and buffer on the left, any pending status_msg right-aligned. The alternatives and why they lost are in context/test-evidence/tui.md.

fill_line — which segment yields is a per-call-site decision

Three rows in the TUI are one left segment and one right segment sharing a line: the title bar, minibuffer_line and draw_status. fill_line composes them, and it owes two things that it did not originally do — it must measure in display cells (it padded with left.len(), bytes, and the title's own · is two of them, so every document's right segment sat one cell in from its edge) and it must truncate, because concatenating and letting ratatui clip clips the right.

What clipping the right costs depends on the row, which is why Keeps is a parameter and not a rule:

• The title bar keeps the right. Its left segment is decoration whose length is unbounded — a document name plus a filename — and its right segment is the fixed " ?:help :q quit ", the only thing on screen telling a stuck user how to get out. Unconditional left priority made the escape hatch the first thing sacrificed, at 100 columns with an ordinary document name (improvise-t14d).
• Both bottom-bar rows keep the left, which is what they already did. There the left is the user's own typing plus the cursor (minibuffer_line) or the status message (draw_status), and the right is a view badge or the message's own margin. Right priority there would let a long message eat the text being edited — the same mistake in the other direction.

So the rule is not "the right wins" but "the affordance wins over the decoration", and which is which is local. Truncation goes through ui::text::truncate (improvise-8l0c), so an overflow is a … rather than a mid-token clip of ?:.

One key table on screen, and it is the one derived from the keymap

The TUI stacks the tile bar (row 3) directly above the status bar (row 4), and the import wizard's overlay sits above the status bar too, so a mode can put two key tables on screen at once. When it does, they disagree — different notation, different content, and in one case a flat contradiction.

The rule is not "the overlay wins" or "the status bar wins". It is keep whichever table is derived from the thing it describes (improvise-rr8n):

• Tile select: the status bar wins. hint_line(&mode) is read off the keymap, so it cannot go stale, and it is a strict superset of what the tile bar's literal carried — Space, h/l and Tab were only ever on the derived line. The tile bar's own hints are therefore deleted, both of them, and TileBar::render now advertises no keys at all. The one it drew in Normal was false: it named Ctrl+↑↓←→ as "to move tiles" while those four keys are bound to enter-tile-select, which moves nothing.
• The import wizard: the overlay wins. hint_line(&AppMode::ImportWizard) is derived too, but from the wrong input — the wizard's real keys are resolved per step inside HandleWizardKey, and one static line off the mode's keymap is wrong on four of its eight steps, including telling the user Esc cancels on Done where Esc goes back. So draw_status suppresses its hint fallback for that one mode and lets the overlay's per-step hints stand alone.

Two things worth keeping from how this survived. every_hint_key_resolves_in_its_mode checks AppMode::hint_text() against the keymaps and cannot see a string literal in a widget, which is the same blind spot improvise-wk18 names for help.rs. And the widget's own characterization test renders at 80 columns, where the hint does not fit and is never drawn — so the test that pins this widget's output was structurally incapable of showing either hint. A fixture width is part of what a test can see.

The longer-term shape the ticket names is still open: the wizard's per-step keys belong in advertised() keyed by step, which would make them derived like everything else and let the status bar carry them correctly instead of being switched off.

The caches are built here, per frame

project::formulas_of, category_tree_of, view_list_of, tile_bar_of, grid_of and wizard_of are all called from draw/draw_content against the authoritative App. This is the temporary half of improvise-35e: when the TUI becomes a client it will hold each cache and fold the matching Projection into it, and none of the widgets change either way.

Two consequences today:

• The grid's viewport covers the whole grid, so a cache position is an absolute position (gotcha 44). Only the viewport narrows when the TUI becomes a client.
• The wizard is built here rather than sent: it is session-local and has no Projection (improvise-764). It still goes through project, so the widget sees the same shape a browser wizard would.

draw renders overlays last so they appear on top. The which-key popup's armed prefix is stored as the key that opened it and resolved back to a sub-keymap by the keymap set (improvise-jc8, gotcha 13).

---

src/ui/import_wizard_ui.rs — ImportWizardWidget

Drawn from a WizardCache (improvise-764).

No ImportWizard, no ImportPipeline, no Workbook. The widget used to hold the live wizard and read through it into improvise-io types and into the model — it called regular_category_names() and measure_item_names() on the built Workbook to write its one-line confirmation summary. Everything it draws now arrives already decided, from project::wizard_of.

The cache is not a Projection, and that is the ticket's answer to where wizard state lives: a half-open import dialogue belongs to the session that opened it, not to every connected client. WizardCache's own documentation carries the argument.

Smaller facts the drawing depends on: the root array path is already spelled (root) by the projection, so both ends say it the same way; the date components arrive in the order the wizard offers them, already paired with whether they are on, so the cursor index counts exactly those rows; and on Done the workbook is built but not yet installed, so the step shows what the user is about to accept, warnings included (improvise-907).

set_bottom_line — one writer for the bottom row

That row has two writers — each step's key hint, and the wizard message that overrides it while present — and they write in that order to the same y. Buffer::set_string writes exactly as many cells as the string has and leaves the rest alone, so a message shorter than the hint it replaced left the hint's tail sitting beside it: something went wrongcel, the cel from Esc: cancel (improvise-q0vb).

Padding here rather than at each site is the point. The bug is not that one of the five writers forgot; it is that the row had five writers and no one of them owned clearing it.

The padding is measured in terminal cells, not characters. Buffer lays a string out by display width, so a char count over-pads a message carrying a wide character — enough to run past the panel and overwrite the border — and under-pads a combining mark, which is how a sliver of the hint would be left behind. src/ui/grid.rs measures the same way.

truncate / prefix — bytes, deliberately

truncate cuts by byte length. prefix returns the longest prefix at most max bytes that ends on a char boundary, because every string truncate cuts can carry a field name, a formula or a message the user typed — and a multi-byte character straddling the cut used to panic the whole TUI on a slice at a non-boundary index. Walking down to the nearest boundary is the smallest change that cannot: for ASCII, which is what every fixture in this file holds, max is already a boundary and the result is byte-identical, so the characterization tests keep saying what they said.

It is bytes and not columns deliberately. Byte length is the measure truncate has always used, and changing it to display width would move where every line wraps — a different question from not crashing, and one that belongs with the hint-line padding it travels with. Bytes are never fewer than cells, so truncate cutting by bytes and set_bottom_line padding by cells cannot together overrun.

The blind spot, stated because the fixtures cannot state it: the eight exact-frame characterization fixtures in this file are entirely ASCII. They are therefore blind to every question about display width — a change to either measure is invisible to them, and the evidence for those has to be built directly (see set_bottom_line_clears_every_cell_it_covers_and_no_more).

---

src/ui/help.rs

~600 lines of mostly-static content: five pages of styled (key, description) lines, a tab bar and a footer. improvise-ktv1 proposes moving that content into the shared layer so a browser help overlay is not a second copy of it. Until then it is TUI-only and help_page is already in ViewState, which is why gotcha 32 says the overlay needs no Projection.

The panel widgets

src/ui/panel.rs holds the PanelContent trait and the generic Panel widget. The one non-obvious member is panel(): each impl declares its own identity, and the widget compares it against AppMode::panel() to decide whether to draw itself as active, instead of restating the mode match per panel.

category_panel.rs, formula_panel.rs, view_panel.rs and tile_bar.rs each draw one cache and nothing else. Two facts worth keeping:

• The category panel draws one flattened tree — the axis travels on the entry (improvise-edp), so there is no View in it.
• The view panel's "which view is this client on" is read off ViewState, not the workbook: the active view is per-client and is deliberately absent from ViewListCache (improvise-8uz, gotcha 29).

tile_bar.rs scrolls by whole tiles: it finds the smallest start index at which the selected tile still fits in the available width, and draws ‹/› overflow indicators. That is the file's only piece of real arithmetic and it is local geometry, not a shared derivation.

, walks the view history forward (improvise-htl6)

view-forward was bound in no keymap, in either front end, from the day it was written. The TUI reached it as :view-forward and a browser could not reach it at all, because declined() refuses to enter CommandMode at the door. It survived because pressing < twice is the only way to observe the forward stack in the first place, and until PR #115 no client maintained one.

The key is ,, and > is why the obvious answer is wrong. < is view-back and > is drill-into-cell, so the pair that looks symmetric is not one — > moves within the grid, < moves between views. Binding the forward half to anything that reads as >'s partner would deepen exactly the confusion that hid the gap. , is the unshifted twin of <, so both halves of the history sit on one physical key, and it carries no direction-in-the-grid meaning to collide with.

It is deliberately not a Ctrl- key. Ctrl-R, the universal "forward through a history" spelling, is browser reload; Ctrl-S and Ctrl-W are already bound here and Ctrl-S is already a filed bug for precisely that reason (improvise-clso, "Ctrl-S saves and also opens the browser's own save dialog"). The keymap is shared between the two front ends, so a binding chosen for the terminal is a binding the browser must also live with, and adding a second instance of an open bug is not a thing to do by accident.

Nothing else moved. help.rs keys its lines off the command name and looks the key up in the keymap, so the overlay and the hint line follow the binding; every_bound_command_name_is_registered already covers the new entry. The absence assertion PR #117 put in resolve::tests::the_forward_step_mirrors_its_cmd_and_no_key_reaches_it was inverted rather than deleted — the test is renamed …_and_one_key_reaches_it and now asserts the binding exists, with view-back kept as the control so it cannot pass against a table that binds everything or nothing. Coming there and saying so was the point of that assertion, and an inverted guard keeps the property under watch where deleting it would have let the key quietly go away again.

, is not advertised in AppMode::Normal's hint line, and neither is <: the hint is width-constrained and the history lives on help page 5 under "View history" with both halves. That is the #149 lesson — a hint that does not fit is never drawn, so the test pinning the widget cannot see it.

A status message lasts until the next key (improvise-cq3d)

draw_status draws status_msg instead of the mode's derived hint, and nothing in production ever cleared status_msg: it was only replaced by the next message. So after the first "Saved", "Loaded" or error of a session, the derived key hint (the one key table on screen, improvise-rr8n) was never drawn again, in any mode.

The rule: a message expires at the start of the next keypress. draw.rs::press applies SetStatus("") and then dispatches the key, so:

• a message a key produces is drawn after that key, whatever it is, errors included. It stays until the user presses something, which is the moment they have acted on it. An error is never wiped before it has been drawn.
• a message that arrives outside a key, such as one from startup or an import, also stands until the next key.
• the next key clears it before its own effects run. So a key that writes a new message shows that message, and a key that writes none shows the hint.

Rejected alternatives.

• Expire on mode change. This fails the ticket's own case: a message written in Normal would stand in Normal indefinitely.
• Expire on the next successful command. Effects carry no notion of success, and a failed command would leave the stale message in place. That is exactly the case where the user most needs the hint back.
• Clear after dispatch. Every message would be wiped before it is drawn. The test's middle step exists to catch that.
• Compose message and hint on one line. A long message still eats the hint, and the stale message still stands forever.

Why here and not in App::dispatch_key. dispatch_key is shared with the lockstep harness (reduce_key), which compares status_msg on the host and the browser after every key. Expiring there without changing the browser's resolver too would make the two ends disagree. The expiry is also a presentation decision about the TUI's one-line status row, so it belongs to the TUI front end.

The browser already behaves this way. Its status_msg is state that is never cleared either, but web/app.js shows it in a toast that hides after TOAST_MS (web/shell.js::createToasts), and #hint is a separate element that is always drawn. So a browser user sees a message briefly and never loses the hint. The TUI now does the same, on a keypress rather than a timer, because a terminal status row has one line to share and a keypress is the event the TUI already has.

Except while a minibuffer stays open under it (improvise-su4u)

In a text-entry mode minibuffer_line draws the message to the right of the prompt. Since improvise-v4hg, a formula that does not parse keeps the user in FormulaEdit with the error. Under the plain rule, the error vanished on the first correcting key: one Backspace and the user was fixing text they could no longer see the complaint about. The same happened to any refusal that leaves the user in a minibuffer.

The rule: a key that leaves the user in the same editor, and says nothing of its own, puts the stale message back. press remembers the editor session and the message, clears the message as before, dispatches the key, and then restores the message only if all three of these hold:

• a text-entry mode was open before the key;
• the same editor session is open after it (below);
• the key wrote no message of its own.

So:

• editing keys keep the refusal on screen until the user acts on it;
• a key's own message always wins, so a second refused Enter shows the new error, not the old one;
• leaving the minibuffer, by a successful commit or by Esc, drops it, exactly as the plain rule does.

Rejected alternatives.

• Expire only on the commit key. That needs to know which keys commit, which is the keymap's knowledge (TextEntry::commit), and a second copy of it in the TUI loop. "The mode did not change" is observed rather than predicted, like gotcha 31's ReturnToNormalUnlessMoved.
• Never clear in a text-entry mode. The message would then outlive Esc and stand in the mode the user returns to, which is the cq3d bug again.
• Compare the message after the key with the stale one. A key that wrote the same text would be indistinguishable from a key that wrote none. Clearing first and restoring only an empty slot has no such ambiguity.

What "the same editor" means (improvise-sx7h)

The first version of this rule compared modes: an equal AppMode before and after the key meant the same editor. That is false for the two cell editors. Editing and RecordsEditing commit with CommitAndAdvance, which drops to Normal, writes the cell, moves the cursor and re-opens the editor through EnterEditAtCursor, which sets an equal AppMode. So after an Enter or Tab that committed and moved on, the mode looked unchanged, and the stale message was restored beside a different cell's editor. It came back again on every later commit until Esc. The reviewer's repro was R, o, 5, Tab, 7: "Added new record row" survived the Tab, and so did o's refusal "That record row is already here…" after the Tab that filled the row in. FormulaEdit could not show it, because its successful commit leaves the mode and writes a message of its own.

An editor session is one opening of a minibuffer. The TUI loop cannot see openings, so EditorSession compares what an opening sets:

• the whole AppMode, not only its variant: an ItemAdd for Month is not the ItemAdd for Region it replaced;
• the cursor cell, which is a cell editor's target, so a commit that advances is a new editor. The prompt modes do not move the cursor while the user types, so for them this is inert;
• the editor's seed (opened_editor.seed). EnterEditAtCursor re-seeds from the cell. So a commit that re-opens on the same cell, such as Tab in the last column, is a new editor too, because the seed is now the committed text.

What it cannot see: a commit that re-opens on the same cell with the same seed. That means the user committed the text the cell already held, which writes nothing. Restoring a message across a commit that changed nothing is harmless.

Rejected: an editor generation counter. It would be exact, but an editor is opened by more than one effect (EnterEditAtCursor, and ChangeMode from enter-mode). A counter bumped in each is a hand-kept list of the places a mode is written, which is the shape gotcha 24 retired. The three fields are set by the opening itself, so they need no list.

Not included: the active view. The cursor is per view, so in principle the view belongs with the cell. But no key a minibuffer binds can switch the view and stay in the minibuffer: a : line that switches view settles back to Normal. So nothing could test the field, and an untestable field is a claim no test can check.

The browser is not covered by this. There, status_msg is a toast that hides after TOAST_MS (six seconds), and the minibuffer element draws only the prompt and the text. A refusal therefore disappears on a timer, whatever the user is doing. That is a different mechanism and has not been changed here.