terminal library

The browser terminal: an xterm.js surface wired to a live OmnyShell session.

This is the reusable heart of OmnyShell Web. Any web app that can reach an OmnyShell broker — including the OmnyServer dashboard, whose Hub hosts one on the same port — can embed a real remote shell with it, rather than re-implementing the parts that are genuinely hard: PTY sizing, soft-keyboard insets, line editing, history and flow control.

The wiring, end to end:

final term = XtermTerminalView(hostElement);
final session = await service.openShell(nodeId: id, cols: 80, rows: 24);
final shell = WebShellHost(
  term: term,
  session: session,
  principal: 'alice',
  nodeId: id,
  commands: null, // a plain remote shell: no :ai, no :ide
);
mount(accessorySlot, TerminalAccessoryBar(
  keys: shell,
  term: term,
  clipboardRead: defaultClipboardRead,
  clipboardWrite: defaultClipboardWrite,
  onToast: showToast,
).element);
TerminalFitter(
  term: term,
  host: hostElement,
  accessory: accessorySlot,
  scaleTarget: screenRoot,
).attach();

The session type itself (ShellSessionPort, RemoteSession) comes from package:omnyshell/omnyshell_client_web.dart, not from here.

The xterm.js bundle and stylesheet are assets, and pub does not serve a dependency's web/ directory to a consuming app. Install them with:

dart run omnyshell_web:copy_assets

Classes

AiSetupCommand: A placeholder :ai shown when no provider is configured; points at Settings.
CommandHistory: Persistent, per-key command history backed by a KeyValueStore.
DeviceMetrics: A device's screen boxes in both orientations, used to suggest fitting dimensions regardless of how the device is currently held.
OrientationBox: One orientation's usable screen box in CSS pixels.
TerminalAccessoryBar: An on-screen key bar for the terminal, giving touch devices the keys a soft keyboard lacks — Esc, Tab, arrows, Home/End/PgUp/PgDn, common symbols — plus Copy/Paste and a Ctrl combinations menu. Keys inject their byte sequences through the TerminalKeys surface (the interactive shell), and taps avoid stealing focus from the terminal so typing continues uninterrupted.
TerminalFitter: Keeps a terminal correctly sized as the page around it changes.
TerminalKeys: The key-input surface the on-screen accessory bar drives: inject raw key sequences and toggle a sticky Ctrl modifier. Implemented by WebShellHost.
TerminalView: A terminal surface the app can write bytes to and receive input/resize from. Abstracted so the host wiring (WebShellHost) is testable with a fake, while the production implementation (XtermTerminalView) wraps xterm.js.
WebIdeCommand: The browser :ide command. The native equivalent lives in the dart:io barrel (ide_command.dart); this version drives the same dart:io-free engine over a RemoteWorkspace and an XtermTerminalDriver.
WebShellHost: The browser host for an InteractiveShellController: it drives the shared LineEditor over an xterm.js TerminalView, exactly as the CLI's connect loop drives it over a real TTY.
XtermTerminalView: A TerminalView backed by xterm.js. Requires the xterm UMD bundle + fit addon to be loaded on the page (see web/index.html; tool/copy_assets.dart installs them into a consuming app).
XtermTheme: The colours xterm renders with.

Enums

DimensionPreset: How the PTY dimensions for a new session are chosen.
TerminalTextSize: The terminal text-size preference. auto derives the font from the chosen columns so they fit the container width; the others adjust that baseline.

Constants

kCellHeightRatio → const double: Approximate monospace line-box height as a fraction of the font size.
kCellWidthRatio → const double: Approximate monospace cell width as a fraction of the font size.
kHorizontalChrome → const double: Horizontal chrome (terminal card padding + borders) subtracted from a box.
kMaxCols → const int
kMaxFontPx → const int
kMaxRows → const int
kMinCols → const int: Smallest/largest selectable column counts.
kMinFontPx → const int: Bounds for the rendered terminal font (px) when scaling a fixed grid to fit its container. Wide enough that a fixed grid can both shrink onto a phone and grow to fill a desktop window, so the terminal tracks the window size.
kMinRows → const int: Smallest/largest selectable row counts.
kRefFontPx → const int: The reference font size (px) the device presets are computed at. The live terminal font then rescales to make those columns fit the real container, which is why presets don't depend on the eventual font (no circularity).
kVerticalChrome → const double: Vertical chrome (header, toolbar, key bar, gaps) subtracted from a box.

Functions

computeFitDims(OrientationBox box, {int fontPx = kRefFontPx}) → ({int cols, int rows}): Computes the columns/rows that fit box at fontPx, after reserving the terminal chrome, clamped to the selectable range.
defaultClipboardRead() → Future<String?>: The default clipboard reader over navigator.clipboard (secure contexts).
defaultClipboardWrite(String text) → Future<void>: The default clipboard writer over navigator.clipboard.
deviceMetrics() → DeviceMetrics: Reads this device's screen boxes in both orientations from the browser.
registerAiCommand({required LocalCommandRegistry registry, required SettingsStore settings, required OmnyShellService service, required void openSettings()}) → Future<void>: Builds and registers the :ai command on registry from the user's stored AI settings and the Hub's advertised default.
registerIdeCommand({required LocalCommandRegistry registry, required TerminalView term, required Stream<void> resizeEvents, required OmnyShellService service, required SettingsStore settings}) → void: Registers the :ide command (alias :edit) on registry.
resolveAiWiring({required SettingsStore settings, required OmnyShellService service}) → Future<({AiConfig config, HubHttpClient httpClient})?>: Resolves the AI provider config and the Hub-routed HTTP client for the connected session, mirroring :ai's precedence:

Typedefs

ClipboardReader = Future<String?> Function(): Reads the system clipboard (used by the Paste key). Returns null when empty or unavailable.
ClipboardWriter = Future<void> Function(String text): Writes text to the system clipboard (used by the Copy key).

terminal library

Classes

Enums

Constants

Functions

Typedefs

omnyshell_web package

terminal library