Skip to main content

Terminal interface principles and review

The TUI is an Operate surface: users must understand the active task and act without losing their context. Preserve the i3-like window model, terminal cell geometry, character graphics and replaceable plugin presentation. Web typography, DOM accessibility and SVG-icon advice cannot be applied literally to Ink cells.

The 2026-11-10 review used Impeccable 4.3.1 and tui-visual-check. Independent assessment A reviewed design and heuristics; B collected detector/PTY evidence without seeing A. A separate controls review examined editing and focus. The baseline scored 27/40 on Nielsen's heuristics. This is a baseline opinion, not an automatic score or a measured post-change usability result. The archived critique is under .impeccable/critique/; it records provenance and all ten scores.

Decisions by segment​

SegmentPrinciple and implementation
Windows/workspacesProject each saved split into readable child rectangles (24 columns, 6 rows). Collapse toward content focus only when both children cannot fit. Ratios and trees stay unchanged, directional keys reach hidden panes, and widening restores geometry. Composer focus preserves fullscreen. Arrange exposes the key map beside the selected window; the Windows finder identifies open/closed views and workspaces, and restores the existing conversation identity. Navigation keeps resident drafts, form cursors and undo state intact.
Transcript/Markdown/toolsKeep the verified message hierarchy, Markdown and compact tool states. Prefer whole-word wrapping even when the previous word occupies less than half a row. Keep literal command/input characters distinct from rendered assistant Markdown.
Composer/slash/statusName an approval or question explicitly. Show waiting status and interaction-specific shortcuts. Keep the hint row when context details do not fit. Toolbar hitboxes only exist for visible complete labels; wrapped workspace tabs retain mouse access.
HistoryKeep local search/preview/resume and current/archive markers. Call an empty current session New chat. Pin the search-field label; scroll long values inside its remaining width, rather than dropping the label or placeholder beginning.
Providers/auth/proxyShared form focus, required markers and validation provide consistent native editing. Offscreen actions are reachable and scrolled into view. Show effective routing separately from when-enabled settings; diagnostics are explicitly disclosed and keep host credential redaction.
Questions/approvalsShift+Tab reverses navigation; text fields have real cursor editing and horizontal viewports. Approval identity and scopes stay pinned while all action details scroll. Enter defaults to deny; Y/A/P/N and mouse controls remain explicit.
PlacementUse visible focus, reversed Tab, field-specific guidance and safe Escape. Closing an in-flight save does not claim to cancel its side effect. Preserve user-controlled placement and plugin overrides.
Todos/agents/workflows/mascotApply readable projection, whole-word wrapping, action navigation and overflow cues through shared contracts. Preserve task order, independent agent behavior, workflow lifecycle and supplied mascot assets.

The configured OpenTUI frontend keeps Alt+W Arrange, Windows and Alt+0 Main stable as its window strip scrolls horizontally. Its workspace bar precedes navigation and the window strip; occupied workspaces carry a literal * marker as well as the palette distinction. Nine fixed-width workspace targets remain available at 38 columns. The strip contains only open windows on the current workspace, including collapsed tiles; the finder retains the complete inventory. Empty-workspace guidance points to F2. Arrange names the selected window and zoom state, with exit, typing and Windows access readable at narrow widths. A warm heavy divider and a separate target line identify the same nearest split that keyboard actions change. Saved proportions stay distinct from minimum-size-clamped cell geometry; hidden targets explain zoom or size limits instead of highlighting a different ancestor. The line uses an existing border cell, preserves child titles and adds no mouse hit target. Finder and pointer gestures suppress the keyboard cue. Its modal input ownership protects resident editors and pending questions/approvals. The native finder searches only titles and public command names; its query is bounded to 512 UTF-16 units. Queries and private form values stay outside model messages and journals. Route activation requires a fresh view from the current owner; cancellation or a new selection invalidates an older opening. Navigation preserves the saved window tree, ratios and closed-window state. Narrow viewports keep every split that fits the shared 24-column/6-row minimum child rectangle. Only insufficient split areas collapse to their focused branch; a narrow terminal can still show multiple row tiles. The deterministic preview retains its separate key map.

An available selected editor owns its F2 binding only in focused Main Draft. The Windows button and Alt+W then W keep window navigation accessible; Answer mode, other windows and unavailable editors retain F2 Windows. Editor frames fit their measured composer rectangle beside the original character. Visible Accepted, Queued and restored-draft feedback refer to actual input admission, independent of the model's later result. Zoomed windows keep a visible workspace status and an Alt+W then F return-to-tiles hint outside Arrange, so a fullscreen window remains recognizably part of the same tiling workspace.

Passive first publication does not take focus unless an explicit placement preference requests it. User-opened results respect newer window-navigation intent, including selecting the already-focused Main window. Window creation, paint and layout saving do not count as new user navigation. A delayed request can remain available without interrupting the editor the user selected next.

Private request windows name the actual requesting plugin. Each UI operation keeps its own FIFO and resident native question/form state; background input opens passively with a separate lifetime. Shared approval cards retain exact literal action details and explicit once-only decisions. Only the current source/request and focused window admit an answer. Closing preserves the request; validation does not reopen a hidden window. Main's selected answer and draft remain separate, and private form values stay outside Finder/model/journal.

Shared plugin contract​

Catalog 0.17 adds optional colors.selectionText, UiTextView.hint and UiTextView.input.label. Existing plugins remain valid. A selected row uses the foreground/background token pair, including rich cells. Mono uses explicit RGB values because bold ANSI black may be rendered as bright black by terminals; using ANSI gray behind it can make the text invisible despite different names.

Semantic action navigation uses unique action IDs across the complete view, not only visible rows. Focused actions scroll into view. Overflow reports the visible range and Page Up/Down/fullscreen controls. ui.render receives the full semantic lines plus scroll metadata, so replacement styling does not remove offscreen keyboard access. Search fields keep their local literal prefix outside that rendered body. Native forms and composer/approval text render literally.

Plugins can replace views and hints, supply field labels and theme tokens, and continue to control placement through the existing services. No plugin-specific layout rules or mandatory Ghost behavior were added to core.

Verification and limits​

npm run visual:ux exercises the actual app in an isolated POSIX PTY at 100x30, 80x24 and 60x24, including hidden-pane focus, fullscreen composer, offscreen provider actions, reverse form navigation, long-command approval and monochrome selection. Its print-only tool fixture is always denied. The compiled binary uses the same loopback model contract. Existing history/settings/questions/ workflow/presentation and broad interaction scenarios remain maintained.

The web detector was attempted once against the Ink frontend and returned zero findings without scannable markup coverage. It is not an accessibility clearance. No DOM overlay on the xterm diagnostic host is presented as product evidence. Native GNOME Terminal pointer/font behavior, screen readers and live providers were not measured. The inspection found real word-wrap, search-prefix and ANSI selection issues; targeted functional confirmation followed the two main visual batches rather than continuing cosmetic polishing.