Web TUI

The web command is a TUI that provides browser chrome — URL bar, navigation, modes — inside a terminal pane. It connects to the GUI (Wezboard) via the TermSurf protocol and controls browser engine processes (Roamium) to render web pages.

Usage

Open a URL in the current pane:

web ryanxcharles.com

The browser appears inline. You start in Control mode. Press Enter to switch to Browse mode and interact with the page. Press Esc to return to Control mode.

Modes

The TUI has four modes. The GUI only tracks a boolean (browsing or not) — it does not distinguish between Control, Edit, and Command.

Mode	Behavior
Control	Terminal keybindings active. Default on startup.
Browse	Keyboard and mouse go to the browser.
Edit	Vim-style URL editing with Normal/Insert/Visual submodes.
Command	Command entry prefixed with `:`.

Keybindings

Control Mode

Key	Action
`Enter`	Switch to Browse mode
`i`	Edit URL (insert at cursor)
`A`	Edit URL (insert at end)
`I`	Edit URL (insert at start)
`n`	Edit URL (normal mode)
`v`	Edit URL (visual mode)
`V`	Edit URL (visual line select)
`:`	Enter Command mode
`q`	Quit

Browse Mode

Key	Action
`Esc`	Switch to Control mode
`Cmd+[`	Back
`Cmd+]`	Forward
`Cmd+R`	Reload

All other keys in Browse mode go directly to the browser — typing, scrolling, clicking, and standard web shortcuts all work as expected.

Edit Mode

Key	Action
`Enter`	Navigate to URL, switch to Browse mode
`Esc`	Exit to Control mode (from Normal submode)

The URL editor uses vim-style keybindings (via edtui): h, l, w, b, x, d, y, p, etc. System clipboard integration is built in.

Any Mode

Key	Action
`Ctrl+C`	Force quit

Commands

Enter Command mode by pressing : in Control mode. Commands use exact matching — no subsequence shortcuts.

Command	Shortcut	Action
`:quit`	`:q`	Quit
`:dark`	`:da`	Toggle dark mode
`:dark on\|off\|s`	`:da on`	Force dark on, off, or system
`:devtools [dir]`	`:de`	Open DevTools in a split pane

DevTools Directions

The :devtools command accepts a direction for the split: right (default), down, left, or up. Shortcuts: r, d, l, u.

Mode Synchronization

Mode state is shared between the TUI and GUI via mode_changed protobuf messages. Both sides send and receive:

TUI changes mode (Esc, Enter) → sends mode_changed to GUI
GUI changes mode (Esc in Browse mode) → sends mode_changed to TUI
Initial mode is set via the browsing field in the SetOverlay message

Loading Screen

When a browser is first launched, the TUI displays a loading log in the viewport showing each startup stage:

✓ Connected to GUI
✓ Starting browser engine
⠋ Waiting for Chromium (12s) — animated spinner with elapsed time
✓ Loading page
✓ Ready

On first launch, Chromium takes ~60 seconds to initialize (GPU process, shader compilation, browser context creation). Subsequent launches are much faster. If Chromium takes longer than 30 seconds, a note appears: "First launch is slow — Chromium is initializing." If it exceeds 120 seconds, the stage shows an error suggesting Roamium may not be installed.

The loading screen disappears automatically when the browser overlay appears.

Direct Browser Connection

After the browser engine starts, the GUI sends a BrowserReady message to the TUI containing the browser's listen socket path. The TUI connects directly to the browser for navigation and color scheme commands, bypassing the GUI for content messages.