# Terminal-native instrument interface

The October 16 interface follows the operator's
`/home/roko/Desktop/OPENTUI_INSTRUMENT_STYLEGUIDE.md` and instrumentation reference.
The operator's later instruction to inherit terminal colors takes precedence over
the guide's example RGB palette. Foreground, background, selection and cursor use
terminal defaults. Hierarchy comes from space, thin rules, dots, weight, underline
and inverse focus rather than colored surfaces. Legacy appearance settings
normalize to terminal defaults.

## Deliberate regions

The header keeps identification on the left and actions against the right edge.
Overflow uses a continuous thin rail with a single draggable dot. Native scroll
controls retain layout, pointer capture, wheel handling and keyboard interaction.
The same treatment applies to history, documents, instruments and selectors.

Conversation remains the primary surface. At 110 columns and wider, an optional
instrument rail starts at 38% width, with actual inference readings and a
collapsed session section. Its one-cell divider drags to resize while preserving
at least 40 transcript columns. Dragging fully right collapses it to an arrow
handle; clicking or dragging that handle restores it. On smaller terminals it
starts closed; DETAILS opens a bounded stacked section. Width, collapse and
disclosure choices survive state updates and resizing. Unknown
readings remain `--`; meters show their actual numeric reading. No invented
telemetry, electrical diagrams or decorative targets are displayed.

The input region contains the draft, prompt and actions relevant to that draft.
Idle enhancement is hidden until there is text. Run and media status sit above
the input rule. The footer keeps one set of key hints and existing controls.
No duplicate hint row or telemetry module is placed inside the editor.
The header and input boundaries are straight `─` rules. Their `┬` and `┴`
junctions track the draggable sidebar divider's exact column, including the
collapsed handle at the right edge. When the divider is hidden, both rules run
unbroken. They use dim terminal-default attributes.

Conversation tabs occupy one row at the top, with a pinned New action. Agent
views have their own tabs on the lower divider when sub-agents exist; Main
remains available there. Selected tabs use bold and underline, without diagonal
accents or a change in label width.
Overflow remains horizontally scrollable. Session switches retain separate
drafts, cursors, transcripts and agent views, and defer while work owns turn
admission. Saved native cards and code survive disk-backed session restoration.
Input IPC uses UTF-16 string indices; the frontend converts to and from OpenTUI's
native display-cell offsets with the edit buffer's own text-range and measurement
APIs. Session restoration and conditional completions therefore preserve Unicode
editing positions, including wide characters and multiline drafts.

Configuration and help use native modal controls over the retained conversation.
The underlying page is dimmed through text attributes, with its terminal colors,
links and selection intact. Sparse hard-corner frames reserve their own border
cells, with short connected horizontal and vertical arms. Opening grows a small
center square to the dialog's bounds; closing reverses that motion. Content
layout stays fixed. Outside clicks dismiss the topmost dialog without activating
the underlying page. Animations stop after completion and on disposal.

Standalone session dashboards, broker reports, GPU policy, diagnostics and related
notices use their own native document modals. Read-only reports offer Refresh;
mutating commands never gain an implicit replay action. Scoped output capture
does not divert unrelated assistant/tool work or replace stdout. Stream lifecycle,
token/context counters and voice acknowledgements update structured chrome;
short notices expire after five seconds. Answers and real errors remain durable.

The sidebar's bottom device section normally occupies five rows until expanded,
and reduces its minimum height when the terminal cannot accommodate them. Its
native device list shows measured utilization and memory, with policy controls
using the existing `/gpu` selector and broker eligibility checks. Desktop NVIDIA
telemetry uses nvidia-smi; Jetson uses jtop and explicitly labels unified memory.
Missing sensors remain unknown. Detailed lease notices stay in STATUS's modal,
so they cannot displace device readings. These readings do not assert model-runner
placement. Hardware readings update on the existing collector; policy discovery
is coalesced and throttled separately.
Compact utilization and memory sparklines use actual samples. Expansion exposes
per-device graphs with a 0–100% axis and two seconds per horizontal cell. History
retains at most 120 samples per device and advances only when the collector
completes a new sample; ordinary interface updates do not manufacture history.
Unknown readings remain gaps. Memory percentages use the corresponding sample's
capacity, including explicitly labeled Jetson unified memory. Expanded height is
bounded by the available terminal space and the native device list remains
scrollable.

Ordinary left-button dragging selects transcript text, including multiline
Unicode, Markdown links and code. Fast drags across nested turns widen the native
selection to their common container. Text selection does not activate tool
buttons or disclosures. Right-clicking a selection opens a small native COPY
popover; Escape and outside clicks dismiss it while preserving the selection and
draft. Copy uses OpenTUI's native host clipboard, with terminal OSC52 as an
available fallback. A confirmed host write reports COPIED; an unconfirmed
terminal request reports COPY SENT TO TERMINAL. Clipboard failures receive their
own status instead of a success claim.

JSON and fenced code share native syntax attributes over terminal-default colors.
JSON formatting changes whitespace only, preserving numeric and string lexemes.
Incomplete streams retain their source text. Headings and code disclosures remain
nested under their originating turn, with independent collapse state retained
during streamed updates. Bundled Tree-sitter grammars and a lexical fallback
require no grammar downloads.

`/vim [on|off|status]` controls the native composer, following the normal/insert
mode distinction in the [official Codex command documentation](https://learn.chatgpt.com/docs/developer-commands).
Esc enters normal mode; i/a/I/A return to insertion. Native buffer operations
support movement, counts, deletion/change/yank/paste, undo/redo, selection, find
and search without replacing the renderer or reparsing raw terminal input.
`/neovim [file]` and `/nvim` retain the project editor in an embedded native
terminal, with built-in file browsing, scoped terminal-default styling and no
automatic plugin downloads. Normal exit preserves unsaved buffers; only actual
application shutdown force-cleans the child process.

Set `OMNIUS_TUI_REDUCE_MOTION=1` (or `REDUCE_MOTION=1`) to paint the final
corner frame immediately.

## Interaction and implementation

- F1 opens help. DETAILS or Ctrl+Shift+I toggles the instrument rail.
- With an empty draft, Tab and Shift+Tab traverse native controls; a nonempty
  draft retains existing completion behavior. Enter or Space activates buttons
  and disclosures. Escape returns to editing or closes a popup.
- Popup selectors retain filtering, arrows, confirmation, nested navigation and
  secret masking. Documents, cards and modal actions participate in keyboard
  traversal. Native focus uses inverse video.
- Updates retain semantic component identity and expansion state. Inactive
  panels do not rebuild on every token or metadata update.
- Ctrl+Shift+C copies the current native selection. Right-click COPY uses the
  same clipboard path and preserves composer text, cursor, focus and scroll.
- OpenTUI owns the render tree, layout, selection, editing and input. Small
  component paint hooks supply dot rails and corner arms. Visible-buffer
  attribute hooks repair default-color selection contrast and dim popup
  underlays without replacing the renderer or rewriting stored history.
- The worker resets its cursor color to the operator's default through ordered,
  coalesced NativeSession writes, including suspend/resume and shutdown.

The [complete command and menu audit](instrument-command-surface-audit.md) maps
all 119 catalog entries, their aliases and 356 signatures to shared presentation
paths. It distinguishes 106 implemented commands from 13 planned entries and
indexes all 94 inspected selector call sites. Runtime menu items use the same
components. The audit also repairs Help-to-editor handoff, the blocked network
menu, nested pause ownership and remaining diagnostic/dashboard framing. It does
not claim to execute destructive or model-loading commands for visual checks.

## Verification

The focused test set includes native rendering, Unicode editing and selection,
hyperlinks, cursor restoration and output pressure, resize and dot dragging,
real telemetry projection, retained disclosures, existing terminal features and
the daemon's framed stream, delayed failure, subprocess failure and managed Stop
checks. Native layout is exercised at 60×20, 80×24, 100×30, 120×36 and 160×48.

`scripts/test-tui-instrument-live.mjs` starts the production CLI in an isolated
GNOME/VTE terminal on a private display and D-Bus session. It captures actual
terminal screenshots and exercises keyboard and pointer interactions. It permits
local model metadata and blocks inference and model-loading requests. It does
not change the operator's terminal profile or GPU workloads.

The earlier instrument baseline passed **599 tests across 75 focused files**,
including all required daemon transport checks. Current native checks also cover
the draggable sidebar, device monitor, code disclosures and Vim composer.
The earlier curated regression set passed **767 CLI tests across 95 files plus
five Jetson telemetry tests**, with source hashes unchanged during execution.
The retained editor also passed a real installed Neovim 0.11.6 PTY check.
The earlier production GNOME/VTE baseline passed all **17 checks with 27 actual screenshots**,
with default foreground/background
intent on every visible cell in both dark and light profiles. No model generation
or model loading was requested for this interface change. It verified real
utilization/memory history, both divider motifs and ordinary transcript dragging.
Right-click Copy was confirmed by reading back the exact selected text from the
private GTK desktop clipboard; Escape and outside dismissal preserved the draft
and selection. The final curated regression set passed **818 CLI tests across
103 files plus five Jetson telemetry tests**, with source hashes unchanged during
execution. Browser presentation and media verification are recorded separately.

- [Targeted verification](evidence/instrument-targeted-verification-20261016.json)
- [Updated targeted verification](evidence/instrument-targeted-verification-20261016-updated.json)
- [Final interface regressions](evidence/interface-targeted-verification-20261016-final.json)
- [Native scenarios and timing limits](evidence/instrument-semantic-components-20261016.json)
- [Actual terminal run](evidence/instrument-production-terminal-live.json)
- [Sidebar resizing](evidence/instrument-divider-resized-160x48.png), [collapsed handle](evidence/instrument-divider-collapsed-160x48.png)
- [Device monitor](evidence/instrument-devices-expanded-120x36.png), [GPU policy report](evidence/instrument-report-gpu-120x36.png)
- [Vim composer](evidence/instrument-vim-composer-120x36.png)
- [Native selection](evidence/instrument-transcript-selection-120x36.png), [Copy popover](evidence/instrument-selection-copy-menu-120x36.png), [confirmed Copy](evidence/instrument-selection-copied-120x36.png)
- [Wide layout](evidence/instrument-120x36.png), [narrow layout](evidence/instrument-60x20.png)
- [Dark popup](evidence/instrument-popup-dark-120x36.png), [light popup](evidence/instrument-popup-light-120x36.png)
- [Configuration](evidence/instrument-popup-config-120x36.png), [network](evidence/instrument-popup-network-120x36.png), [nested input](evidence/instrument-popup-api-input-120x36.png)

All workspace packages were cleaned and rebuilt before bundling. A fresh tarball
passed README/metadata, native worker and artifact checks, followed by six actual
terminal checks in a fresh isolated installation. Installed Node help, SQLite,
Bun and OpenTUI also passed. Only Bun and SQLite install scripts were enabled;
the application's service setup did not run. The package was not published to
npm. The operator's existing tracked publishing and catalog changes were restored
and verified byte for byte after the build.

- [Package artifact](evidence/instrument-package-artifact-20261016.json)
- [Fresh installation and actual terminal](evidence/instrument-package-install-20261016.json)

The session-tab update adds separate conversation and agent navigation and
canonical Unicode cursor conversion. Its verification
includes the real OpenTUI widget suite, production session lifecycle tests, and
actual source CLI and packaged CLI terminal scenarios. The GNOME/VTE run covers
saved native documents, draft/caret restoration, keyboard selection and narrow
navigation in four checks with two actual screenshots. Footer agent tabs are
covered by real native component tests; the GUI fixtures do not fabricate agents.

- [Session lifecycle](evidence/native-session-lifecycle-verification-20261016.json)
- [Native tabs, geometry, Unicode editing and Vim](evidence/native-session-widget-verification-20261016.json)
- [Regression and workspace build](evidence/native-session-regression-verification-20261016.json)
- [Source terminal scenarios](evidence/native-sessions-production-pty-20261016.json)
- [GNOME/VTE session checks](evidence/native-sessions-production-vte-20261016.json)
- [Restored session](evidence/instrument-sessions-restored-120x36.png), [narrow session](evidence/instrument-sessions-narrow-60x20.png)
- [Exact package verification](evidence/session-tabs-package-verification-20261016.json)
- [Installed terminal scenarios](evidence/native-sessions-installed-pty-20261016.json)
- [Local installation](evidence/session-tabs-installation-20261016.json)

The subsequent straight-boundary correction removes the diagonal tab accents
and joins `─` rules to the draggable divider with `┬` and `┴`, including the
collapsed right-edge handle. Thirteen tests across five native test files and
the CLI typecheck passed, covering five sizes, pointer dragging, collapse/reopen,
keyboard resizing, tab interaction and transcript selection. Earlier screenshots
above retain the historical stepped design. Publishing remains operator-owned.

- [Straight-boundary verification](evidence/native-straight-boundaries-verification-20261016.json)

The previous renderer and local inference repair are documented in
[native-tui-renderer.md](native-tui-renderer.md). Its October 15 measurements are
historical. This visual change does not claim a new model-inference benchmark or
a pass of the entire CLI suite.

The [desktop indicator report](desktop-projects.md) covers the project dropdown,
monochrome assets and actual native menu-to-terminal launches.
