TUI Panels

TUI mode presents one full-width content area with three tabs, a cascade overlay, and a persistent frame of header, status bar, and help bar around them.

Layout

┌─────────────────────────────────────────────┐
│  My Table    ● Running   v1.0               │  ← Header (F4 to expand)
│  /path/to/config.cade                       │
├─────────────────────────────────────────────┤
│  ● Ball In Play  P1  1,000  Ball 1/3        │  ← Status bar (F5 to toggle)
├─────────────────────────────────────────────┤
│  [Logs]  Events  Console                    │  ← Tab bar (F1–F3)
├─────────────────────────────────────────────┤
│                                             │
│  Log output...                              │
│                                             │
├─────────────────────────────────────────────┤
│  q quit  F1-F3 tabs  F4 header  F5 status   │  ← Help bar
└─────────────────────────────────────────────┘

The Cascade viewer is an overlay rather than a tab — press F7 (or Ctrl+E) to open it over the content area, and again to dismiss. See Cascade Visualization.

Logs Tab

Streams structured log output as a scrollable, color-coded list.

12:13:44.205 DEBUG [audio.mixer] Parsed use block for voice=synth.plunger

• Timestamp — millisecond precision, from the log record
• Level — DEBUG, INFO, WARN, ERROR; color-coded by severity
• Source — the component that emitted the log. Nested components render as dotted paths (e.g. audio.mixer). When a record has no source the bracketed segment is omitted entirely — you never see empty [] brackets
• Message — the formatted message followed by any structured key/value fields

Filter, Search, and Pause

Three independent modes for working through high-volume output:

Text filter (/) — hides non-matching lines. Press /, type a substring, press Enter. Matching is case-insensitive against the message, source, and structured fields. Press / again or Esc to clear.

Search (Ctrl+F) — highlights matches in place without hiding other lines. Use n / N to jump between matches. Filter and search compose: search highlights within the filtered view.

Source filter (s) — opens a picker listing the sources currently present. Select with Space, commit with Enter, dismiss with Esc or q.

Pause (p) — freezes the visible feed while new entries continue to buffer. Press p again to resume; buffered entries drain in order. Pause is independent of autoscroll.

Logs Tab Shortcuts

The Logs tab is the one view with a built-in help overlay — press ? for a two-column reference, and any key to dismiss it.

Events Tab

A live, hierarchical tree of game events organized by span — game sessions, balls, and active modes. The tree updates in real time and supports collapsing, filtering, and detail inspection.

Tree Structure

Full Example Table · ● RUNNING · localhost:50052 ● · v0.1.0
./cade/docs/examples/full-example-table-with-modes
────────────────────────────────────────────────────────────────────────
● Ball in Play  player1  17,000  Ball 1/3
switch.hit ▁▁▁▁█▁▂▁▁▁ 31  flipper.pressed ▁▁▁▁▁█▁▁▁▁ 14
────────────────────────────────────────────────────────────────────────
· [-] Player 1  Ball 1/1  Score: 17K  Events: 59
╰── · [-] Ball 1  Score: 17K  (34s)  Events: 59
    ├── · [-] Active Modes (1)
    │   ╰── · +23.078s — multiball pri:200
    ├── ▸ ... 43 earlier ...
    ├── · +11.577s device.Kicker1.activated [switch] +10K
    ├── · +11.577s mode.multiball.started
    ├── · +11.596s ball_device.unhit <BallRelease>
    ├── · +11.610s switch.hit <StartBallControl> held 651ms
    ├── · +12.612s switch.pressed <launch_ball> held 1.5s
    ├── · +14.662s device.Gate.activated [switch]
    ├── · +15.111s system.ball.drain
    ├── · +15.152s system.game.end
    ╰── · [-] lifecycle
        ╰── · +11.577s — mode.multiball.started

Each span can be collapsed ([+]) or expanded ([-]) independently. Active modes are grouped into an Active Modes subtree below their ball span. Events carry a relative offset from ball start (+11.577s) and are annotated with points (+10K), device context (<BallRelease>), and held duration for merged pairs (held 651ms). Cascade durations under 0.05 ms are hidden to reduce noise; under 1 ms renders dim, 1 ms and above renders in a warning color to flag slow cascades.

A mode that just ended lingers in Active Modes for a couple of seconds, greyed out with its score frozen, before rolling off. If the same mode restarts while the prior activation is still fading, both appear as separate rows; only the live one keeps accumulating.

Collapse state resets when a new game starts.

Archived Games

Finished games are retained in a bounded ring above the live game so you can scroll back without leaving the TUI.

· [+] Game started +01:23:45  Player 1: 42K  Player 2: 18K
· [+] Game started +01:41:07  Player 1: 12K
· [-] Game  (live)
╰── · [-] Player 1  Ball 2/3  Score: 6000  Events: 18
    ╰── ...

• Up to three archived games are retained; a fourth evicts the oldest.
• Collapsed by default — expand with l or Space.
• Summaries only. Archived entries keep the player leaderboard, per-ball summaries, completed-mode history, and lifecycle entries. Raw per-event leaves are dropped, so the ball node shows an aggregate count (Events: N) but has no event children — a large memory saving in exchange for losing per-event inspection after the game ends.

The active game is never archived while in progress.

Event Compression

Related event pairs are automatically merged into single entries:

• Hit/unhit pairs — a switch or ball device firing both hit and unhit in the same span becomes one entry showing held duration (left_inlane held 234ms). Cross-span pairs are not merged.
• Switch press/release pairs — merged the same way.
• Flipper pairs — a full press sequence (flipper press + staged press + both releases) compresses from four events into one, dramatically reducing flipper noise.

Press p to toggle expand mode, which injects synthetic rows for the closing half of each merged pair. This is display-only; the underlying data is unchanged.

Overflow Expansion

When a span exceeds the per-span display limit, older events hide behind an overflow node (▸ ... N earlier ...). Press Enter or l on it to reveal the next 16, repeatedly to page through. Collapse and re-expand the span to reset.

Sibling-Lock Mode

Sibling-lock constrains j/k to one depth level — useful for scanning all completed modes without diving into their children. Press s to lock to the current node’s parent:

[LOCK] j/k:siblings  g/G:first/last  esc:unlock

While locked, j/k move between siblings, g/G jump to first/last, and h/l/Space/Enter still collapse, expand, and open details. Esc unlocks. The lock releases automatically if the locked parent stops being visible.

Memory Management

The event tree caps retained entries (default 10,000). At the cap, the oldest completed game span and its events are evicted. At least two game spans must exist before eviction, and the active game is never removed.

Events Tab Shortcuts

The filter bar accepts structured clauses — see Filtering Events for the syntax.

Console Tab

The REPL. Contains the cade:debug> prompt and a scrollback view of command results and scoring output.

The input line offers ghost-text completion suggestions, history navigation, and readline-style editing:

Note: q quits the console from the Logs and Events tabs, but not from the Console tab — there it types the letter q into your command. Use Ctrl+C to quit from anywhere.

Chrome

Header

Shows table identity and engine status. F4 toggles between two modes:

• Compact (default, 2 lines) — table name, engine status, platform health, and Cade version on line 1; config path on line 2.
• Regular (4 lines) — table name and engine status; config path; platform address and connection status; Cade version.

Game Status Bar

Toggled with F5. When visible it shows:

• Game phase — ● Ball In Play, ○ Starting, ■ Game Over, or idle
• Player, Score (comma-separated), and Ball (e.g. Ball 1/3)
• Event sparklines — event activity over the last 60 seconds

The status bar drops lower-priority fields when the terminal is narrow.

Tab Bar

A single line showing the three tabs. The active tab is bold and bracketed; inactive tabs are dimmed. Press the matching F-key to switch instantly.

Help Bar

A single line at the bottom showing the global key hints: q quit, F1-F3 tabs, F4 header, F5 status.

Global Shortcuts

Copied log text uses the same format as the display, including the source bracket only when a source is present — you never get stray [] in copied output.

Themes

The TUI ships these built-in themes:

Pick one at launch:

cade console --theme dark

The theme system adapts to terminal color capability — TrueColor (24-bit), 256-color, 16-color, and 8-color — degrading gracefully.

Separately, the console’s own output colors (prompt, values, errors) are set by the colors block in the console config file, which offers default, solarized, monokai, and custom. See Configuration.