# TUI browser, editor, and release contract `efo-tui` is a separate terminal interface over `lib_efo`. It browses all six entity collections in HEAD, index (staged), and worktree (editable) state and creates/edits entities in the worktree with explicit save previews. The CLI remains the complete interface for staging, commits, history, relationships, comparison, and recovery. No repository format changes are introduced by the browser. ## Running ```bash cargo install --locked --path tui_efo efo-tui --repository /path/to/world # From a repository root: efo-tui # Monochrome (NO_COLOR also works): efo-tui --no-color ``` The path must identify a repository root; parent-directory discovery is not performed. Both stdin and stdout must be interactive terminals. `--help` and `--version` also work when redirected. For scripts use `efo status` and `efo show`. ## Browsing The header reports HEAD, staged and unstaged changes, writer-lock state, the viewed layer, and its world summary. Start in the worktree. Press `1`, `2`, or `3` to browse HEAD, index, or worktree. Collection counts reflect the viewed layer. Entities sort by lowercase name, then stable UUID, and show a shortened UUID beside their name. Details default to a formatted view with the full UUID, description, properties, metadata, and statistics. Bold headings, aligned labels, and indented nested fields make events and other entities readable. Press `v` to switch between formatted details and the complete, indented raw JSON. The panel title identifies the mode. Switching resets detail scrolling to the top, preserves the selected entity and layer, and keeps the chosen mode while navigating or reloading during the session. Both modes wrap and scroll. Switch to an earlier layer to inspect an entity removed from the worktree. Use `efo diff` or `efo diff --staged` for a complete change comparison. Search applies to the current collection in every layer. It matches name and description using Unicode lowercase matching, or any substring of the UUID (with or without `@`). This is literal substring matching, not a query language or accent-insensitive search. Press `/`, edit the query, and press Enter to keep it. An empty query clears the filter; Escape restores the previous query. While editing, ordinary character keys enter text instead of invoking commands. | Key | Action | | --- | --- | | `Tab`, `Shift-Tab`, `h`/`l`, left/right | Cycle focus: collections, entities, details | | up/down, `j`/`k` | Select a row or scroll details/help | | `Home`, `End` | First/last row or start/end of details/help | | `PageUp`, `PageDown` | Move by approximately one visible page | | `/` | Edit the search filter; Backspace removes a character | | `Enter`, `Esc` during search | Keep filter / restore previous filter | | `1`, `2`, `3` | View HEAD / index / worktree | | `v` | Toggle formatted / raw JSON details | | `a`, `e` | Add to the current collection / edit the selected entity (worktree only) | | `u` | Preview undo of the last TUI save in this session | | `r` | Reload from disk, preserving selection by UUID when present | | `?`, `!` | Open help and the last reload diagnostic | | `?`, `!`, `q`, `Esc` in help | Close help | | `q`, `Esc` outside help/search | Quit | | `Ctrl-C` | Quit the browser/help/search; cancel a form or undo confirmation | At widths of 100 columns and above, the browser shows three panels. Narrower terminals show the focused panel at full width; Tab cycles between them. The minimum usable size is 32×10. Smaller sizes show resize advice. Details wrap within their panel and scrolling stops at the last page, including after a resize. Help and diagnostics scroll independently. Focus, selection, and repository state use text and reverse video as well as optional colour. No Nerd Font is required. `--no-color` or the presence of `NO_COLOR` disables application colours while retaining these selection cues. ## Snapshot and failure behavior The browser reads a snapshot on startup and refreshes only on `r`; external changes never silently move the selection. Successful reload and layer changes keep the selected UUID when it remains in the filtered collection, otherwise clamp to an available row. A failed reload keeps the last loaded snapshot and sets a visible stale-data message. Press `!` and scroll to read the full error, including its path and recovery advice; fix the problem and retry with `r`. Unsupported versions, corrupt data, and unfinished transactions fail startup before raw mode is enabled. A writer lock is displayed, never broken. Use `efo lock status`, `efo status`, or `efo recover` when appropriate. See [recovery](recovery.md) for the CLI safety workflows. ## Architecture and verification The binary owns argument parsing, terminal setup, key mapping, view state, and Ratatui rendering. `lib_efo::workspace::Workspace` owns repository loading and validation and entity-draft parsing. No command changes the process working directory. `Workspace::apply_entity_change` holds the writer lock across a fresh read, comparison of manifest/index/worktree with the editor snapshot, validation, and the existing journalled write operation. It writes only the worktree and updates the browser snapshot only after success. Ratatui's rendered-line measurement bounds wrapped scrolling; its `unstable-rendered-line-info` feature is enabled against the locked version. A terminal guard restores raw mode, cursor visibility, and the alternate screen on normal exit and application errors. The panic hook restores an active terminal before printing the panic, and does not emit terminal controls before terminal setup. Ctrl-C takes the same guarded exit path. Forced process kills cannot run cleanup. Tests cover search, navigation, layer/reload identity, corrupt reload recovery, scrolling, responsive layouts, monochrome rendering, and noninteractive startup. The release gate includes workspace formatting, tests, strict Clippy, default and portable builds, plus a pseudo-terminal navigation/restoration smoke test. On Unix, run it with: ```bash cargo build -p efo-tui --locked python3 tui_efo/tests/terminal_smoke.py ``` The smoke check uses a temporary copy of the curated example. It verifies read-only browsing, creation, multiline paste, save previews, editing, draft cancellation, exact entity undo, unchanged HEAD/index, and terminal restoration on `q` and Ctrl-C. ## Creating and editing entities Select the collection (characters, towns, events, calamities, organisations, or blockers), press `3` for the worktree, and press `a` to add. To edit, select an entity and press `e`. HEAD and index browsing stays read-only: switch to the worktree explicitly before opening a form. The form has seven fields: name, multiline description, exact position, duration, effect mode, bounds, and absolute statistics. Wide terminals show a field list; narrow terminals show the active field. Newly created entities have zero stats, a new stable UUID, and type-specific duration/effect/bounds defaults (events start with one turn and `todo` effects). UUID, type, and existing relationships are preserved while editing; use the CLI for relationship changes. | Form key | Action | | --- | --- | | `Tab` / `Shift-Tab`, up/down | Next / previous field | | left/right, `Home` / `End` | Move the text cursor | | Backspace / Delete | Remove the previous / next character | | `Ctrl-U` | Clear the active field | | Enter | New line in description; next field elsewhere | | Paste | Insert text; multiline descriptions supported | | `Ctrl-S` | Validate and preview the exact worktree change | | `y` in preview | Save the previewed change | | `n` / `Esc` in preview | Return to the draft | | `Esc` / `Ctrl-C` in form | Cancel; changed drafts require `y` to discard | Names must be non-empty and unique (case-insensitively) within their collection. Position uses exact integer `x,y` coordinates, including negative coordinates. Duration accepts `permanent`, `done`, or a non-negative number of turns. Effect accepts `recurring`, `when-present`, `todo`, or `done`. Bounds use `min:max`, with the minimum no greater than the maximum. Statistics use the full field names shown in the form and whitespace-separated `field:value` pairs. These are absolute integer values, including aggregates; omitted fields stay unchanged, and no randomisation or automatic aggregate recalculation occurs. Preview shows the affected entity/type, worktree layer, and before/after values. Scroll with arrows, PageUp/PageDown, or Home/End. Saving clears the browser search so the saved entity remains visible. It does not stage or commit. Use `efo diff`, `efo stage`, and `efo commit` for the rest of the workflow. A save failure retains the draft and gives a scrollable error. Locks are never broken automatically; use `efo lock status`. Interrupted transactions require `efo recover`; then inspect the worktree before retrying, since recovery can complete an already-written save. If another process changed manifest, index, or worktree while the form was open, the save is refused. Cancel the draft, reload with `r`, and reopen the entity to edit the current state. ## Undo and recovery scope After a successful save, `u` previews undo and `y` confirms it. Undo restores the exact previous entity, including any edits that were already unstaged when the form opened, or removes an entity just created by the TUI. Other entities, HEAD, and index are unchanged. Any intervening repository change refuses undo; reloading does not bypass this check. Use `efo status` / `efo diff` to review such changes. Undo is **one step, in this TUI session only**. A later successful save replaces the prior undo record; exiting loses it. For a durable recovery point, stage and commit valuable work before continuing to edit. The CLI's `efo restore --worktree --kind KIND @UUID` restores that entity from the index, which discards all its unstaged edits and is not equivalent to TUI undo. See [recovery](recovery.md). Stage/unstage, commit, relationship editing, general deletion, transaction recovery, and future pruning remain CLI operations. Additional interactive writes require explicit previews, recovery guidance, and tests through the library transaction operations.