@aitty/browser

Browser-side DOM terminal renderer for aitty sessions.

Use this package inside your web UI to mount a PTY-backed agent session created by @aitty/server.

Install

npm i @aitty/browser

Import the stylesheet once:

import "@aitty/browser/style.css";

Usage

import { mountAitty } from "@aitty/browser";
import "@aitty/browser/style.css";

const terminal = await mountAitty("#terminal", {
  src: sessionUrl,
  config: {
    appearance: {
      fontSize: 16,
      lineHeight: 1.5,
      theme: "light",
      themeTarget: "container"
    }
  },
  onStatusChange(status) {
    console.log(status.connection, status.sessionState, status.message);
  }
});

terminal.updateConfig({
  appearance: {
    theme: "dark"
  }
});

<div id="terminal" style="height: 100dvh"></div>

If the page is served directly from an aitty session URL, src can be omitted. When embedding aitty inside an existing app route, pass src.

By default, @aitty/browser scopes theme writes to the mounted container and does not install the reference shell controls. That keeps host apps in control of their own header, fullscreen UI, theme switcher, status indicator, and page theme. The reference CLI shell opts into document-level theme and shell controls explicitly through its own data-aitty-* attributes.

themeTarget is a mount-time ownership setting. Keep it at "container" for embedded apps; use "document" only for full-page shells.

Main Exports

• mountAitty() mounts the terminal into a selector or element and connects to a session.
• defineAittyTerminalElement() registers the web component wrapper.
• mountTerminalApp() mounts with explicit elements and dependencies for advanced integrations.
• createBufferedTerminalWriter() buffers terminal writes until the renderer is ready.
• BrowserTerminalRenderer exposes the DOM renderer used by aitty.
• normalizeTerminalConfig(), mergeTerminalConfig(), and cloneTerminalConfig() help host apps manage settings state.
• installShellControls() wires the optional reference shell buttons used by the CLI page.
• installTerminalInputPolicies() wires keyboard, IME, paste, and shortcut handling.

Integration Hooks

• Use onStatusChange to render your own header, badge, or connection state UI.
• Use config.appearance and terminal.updateConfig() to keep host UI and terminal state aligned.
• Use scrollAdapter when integrating custom scrollbar libraries such as OverlayScrollbars.
• Use config.behavior.input.resolveKey for agent-specific shortcuts while leaving browser-reserved shortcuts to the browser.

License

Apache-2.0