@cplieger/web-terminal-ui 3.5.0 → 4.1.0

package/README.md

@@ -31,7 +31,8 @@ with opt-in feature modules that own everything above the raw terminal:
 - **predictive local echo**, **IME / composition** (CJK, dictation,
   autocorrect), and **viewport + keyboard-inset** handling for the iOS soft
   keyboard, rotation, and font-load reflows
-- a connection-status banner and a copy toast
+- a connection-status banner, including a persistent protocol-incompatibility
+  state, and a copy toast
 
 It is published as TypeScript source (no build step) to npm and JSR, alongside
 the CSS bundle and a reference HTML page. Consumers who want a different UI should
@@ -43,17 +44,35 @@ depend on the engine directly and skip this package.
 npm install @cplieger/web-terminal-ui @cplieger/web-terminal-engine
 ```
 
-`@cplieger/web-terminal-engine` is a peer dependency — the UI is built on the engine,
-and both halves of the wire protocol must stay in lockstep, so the consumer
-pins the engine version explicitly.
+`@cplieger/web-terminal-engine` is a peer dependency — the UI is built on the
+engine, so the consumer pins the engine version explicitly. Pairing compatibility
+is governed by the engine's
+[directional wire contract](https://github.com/cplieger/web-terminal-engine#wire-protocol),
+not strict package-version equality; the UI surfaces a terminal incompatibility
+through its connection banner.
 
 ## Usage
 
-Serve the bundled CSS (`css/` concatenated per `css/MANIFEST` into the
-`style.css` your page links) plus a minimal HTML page that has one empty
-container element for the terminal, then call `createTerminal(root, { features })`
-from your entry module. Feature bundles (presets) live at the `./presets`
-sub-path:
+Serve a CSS bundle matching how you embed the terminal, plus a minimal HTML
+page that has one empty container element, then call
+`createTerminal(root, { features })` from your entry module.
+
+**Full-page host** (the terminal IS the page — `web-terminal-server`,
+`web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
+links. That reference bundle is `css/page.css` (the page kit: `html/body`
+reset + the terminal web font's `@font-face`, expecting the font files at
+`/vendor/fonts/`) plus the complete component set.
+
+**Embedder** (the terminal lives inside your app's layout — a panel, a pane):
+concatenate the per-preset manifest matching your composition instead —
+`css/MANIFEST.single`, `css/MANIFEST.touch`, or `css/MANIFEST.tabbed`. These
+contain ONLY root-scoped component styles: no page reset, no fonts, no
+document-level rules, nothing to quarantine. Pass `layout: "container"` so the
+terminal fills (and positions its chrome against) your container element
+instead of the viewport.
+
+Feature bundles (presets) live at the `./presets` sub-path, with per-preset
+entry modules beside it:
 
 ```html
 <div id="terminal"></div>
@@ -81,14 +100,22 @@ sub-path:
 
 `createTerminal(root, opts?)` builds the entire terminal subtree (the kernel
 plus every feature's chrome) inside `root` itself — there is no element-id
-contract for the host page to reproduce. Call it exactly once; the engine's
+contract for the host page to reproduce, and every style and CSS custom
+property is scoped to the `wt-root` class it stamps on your element (removed
+again by `destroy()`). Call it exactly once; the engine's
 render/connection/scroll modules are single-instance per page (tabs multiplex
 sessions over the one kernel). `scaffold/index.html` is a complete reference page
 to copy and adapt.
 
-Four presets are provided (import from `@cplieger/web-terminal-ui/presets`); each
-is a plain feature-array factory, so you can spread and edit it, or hand-pick
-individual features instead:
+Four presets are provided; each is a plain feature-array factory, so you can
+spread and edit it. Import the barrel (`@cplieger/web-terminal-ui/presets`) for
+convenience, or a per-preset entry module for the minimal delivered import
+graph — `…/presets/single`, `…/presets/touch`, `…/presets/tabbed`,
+`…/presets/agent-tabbed` (the barrel statically reaches every feature; the
+touch entry, for example, never imports the tabs module). Individual features
+are importable from `…/features/<name>` (`clipboard`, `context-menu`,
+`scroll-to-bottom`, `predictive-echo`, `connection-banner`, `mobile-toolbar`,
+`tabs`, `activity-monitor`, `animations`) for hand-picked compositions:
 
 - `presetSingle()` — single-pane desktop UI (context menu, clipboard,
   scroll-to-bottom, predictive echo, connection banner).
@@ -110,25 +137,31 @@ individual features instead:
 
 ### Options
 
-| Option      | Default                    | Purpose                                                                                                                                                               |
-| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `features`  | _(none — bare kernel)_     | The feature list. Omitted or empty builds only the terminal (no chrome). Use a preset from `./presets` or a hand-picked array.                                        |
-| `wsPath`    | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                                                       |
-| `fontReady` | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                           |
-| `loading`   | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.          |
-| `theme`     | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`. The library ships neutral defaults. |
+| Option      | Default                    | Purpose                                                                                                                                                                                                                                        |
+| ----------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `features`  | _(none — bare kernel)_     | The feature list. Omitted or empty builds only the terminal (no chrome). Use a preset from `./presets` or a hand-picked array.                                                                                                                 |
+| `layout`    | `"viewport"`               | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case). |
+| `wsPath`    | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                |
+| `fontReady` | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                                                                                                    |
+| `loading`   | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.                                                                                   |
+| `theme`     | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-bg`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`, `--tab-active-border`. The library ships neutral defaults.                                       |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
-(and opens the soft keyboard on touch), and `destroy()` tears every feature down
-and releases the kernel.
+(and opens the soft keyboard on touch); `send(bytes)` sends bytes to the active
+session through the kernel's sanitizing input funnel (the supported host path
+for a "type this command" affordance); `reset()` drops the local scrollback and
+screen without injecting keystrokes (send a redraw keystroke yourself if you
+want one — e.g. Ctrl+L); and `destroy()` tears every feature down and releases
+the kernel.
 
 ## What ships
 
-| Path                     | Purpose                                                                                                         |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `src/**/*.ts`            | The UI modules: the kernel (`kernel/`), opt-in features (`features/`), presets, IME, predictive echo, viewport. |
-| `css/*.css` + `MANIFEST` | The default theme + layout; concatenate in MANIFEST order.                                                      |
-| `scaffold/index.html`    | A reference HTML page: `<head>` + one empty root element + importmap.                                           |
+| Path                    | Purpose                                                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/**/*.ts`           | The UI modules: the kernel (`kernel/`), opt-in features (`features/`), per-preset entries (`presets/`), IME, predictive echo, viewport.                                                                                   |
+| `css/*.css` + manifests | Root-scoped component styles. `MANIFEST` = the reference full-page bundle (`page.css` + the tabbed set); `MANIFEST.single/touch/tabbed` = component-only per-preset bundles for embedders. Concatenate in manifest order. |
+| `css/page.css`          | The page kit (full-page hosts only): `html/body` reset + the terminal web font's `@font-face`.                                                                                                                            |
+| `scaffold/index.html`   | A reference full-page HTML host: `<head>` + one empty root element + importmap.                                                                                                                                           |
 
 ## Related projects
 

package/css/00-tokens.css

@@ -1,11 +1,27 @@
-/* ===== Tokens ===== */
-:root {
+/* ===== Tokens =====
+   Every token defaults on .wt-root (the class createTerminal stamps on the
+   consumer's root element), never on the document :root: the terminal subtree
+   inherits them, the host page never does, and a host page's identically-named
+   custom properties never reach the terminal (the class definition wins for the
+   subtree). The `theme` option overrides them as inline style on the same
+   element — the consumer contract is unchanged. */
+.wt-root {
   interpolate-size: allow-keywords;
 
   --bg: oklch(0% 0 0deg);
   --surface: oklch(16% 0.005 280deg / 70%);
   --border: oklch(100% 0 0deg / 15%);
   --text: oklch(90% 0.005 280deg);
+
+  /* Captured copies of the default color pair, resolved HERE (custom
+     properties substitute var() at computed-value time, so descendants
+     inherit the resolved colors, not the references). The DECSCNM
+     reverse-video rule in 02-terminal.css swaps --text/--bg on .term by
+     reading these — a direct self-referential swap (--text: var(--bg))
+     would be a cycle and invalidate both. Theme overrides (inline custom
+     properties on this element, or a consumer rule) are captured too. */
+  --text-default: var(--text);
+  --bg-default: var(--bg);
   --text-active: color-mix(in oklch, var(--text) 15%, transparent);
   /* ===== Themeable tokens (the consumer-configurable "template") =====
      These default to the neutral built-in look; a consumer recolors the UI by

package/css/01-scope.css

@@ -0,0 +1,76 @@
+/* ===== Component scope + layout modes =====
+   Everything here is scoped under .wt-root — the class createTerminal stamps on
+   the consumer's root element. The library never styles the host document: page
+   concerns (html/body reset, fonts, viewport meta behavior) live in page.css,
+   served only by full-page hosts. This file owns the boundary itself: the
+   scoped box-sizing + font-smoothing baseline, the two layout modes, and the
+   scoped reduced-motion kill-switch. */
+
+/* Layout mode: how the root claims space (kernel stamps exactly one).
+   wt-viewport — the root IS the page surface: a fixed full-viewport box (the
+   full-page product; geometrically identical to the pre-v4 fixed-inset .term).
+   wt-container — the root fills its parent, which becomes the boundary: the
+   embedded case. overflow: clip keeps absolute chrome (menus, banners, the
+   switcher) inside the box, so an embedder needs no containment workarounds. */
+.wt-root.wt-viewport {
+  position: fixed;
+  inset: 0;
+}
+
+.wt-root.wt-container {
+  position: relative;
+  inline-size: 100%;
+  block-size: 100%;
+  overflow: clip;
+}
+
+.wt-root,
+.wt-root *,
+.wt-root *::before,
+.wt-root *::after {
+  box-sizing: border-box;
+}
+
+.wt-root {
+  -webkit-font-smoothing: antialiased;
+  /* The terminal subtree is dark regardless of the host page's scheme, and
+     UA-rendered bits inside it (classic scrollbars, selection tints) must
+     match — page.css declares this on html for full-page hosts, but an
+     embedded root (wt-container) inherits the HOST's scheme without this. */
+  color-scheme: dark;
+  /* Design-system scrollbar COLOR on every scroller in the subtree (the
+     terminal, the tab scroller, the expanded switcher list): border-grey
+     thumb, no track — the vibekit/subflux treatment. scrollbar-color
+     INHERITS, so the boundary is the one place to set it. Where it is not
+     supported the color-scheme above still renders the UA fallback dark.
+     Overlay-scrollbar platforms are unaffected. */
+  scrollbar-color: var(--border) transparent;
+}
+
+/* scrollbar-width does NOT inherit (unlike scrollbar-color), so the thin
+   variant is applied to every element in the boundary: a no-op for anything
+   that does not scroll, and any scroller a future feature adds is covered
+   automatically instead of joining an explicit list nobody remembers. */
+.wt-root * {
+  scrollbar-width: thin;
+}
+
+/* stylelint-disable declaration-no-important, time-min-milliseconds --
+   Canonical prefers-reduced-motion override. !important and near-zero
+   durations are required to forcibly defeat any animation/transition rule
+   regardless of specificity, which is the whole point of this a11y reset.
+   Scoped to the terminal subtree: the host page's own motion policy is the
+   host's business (pre-v4 this hit `*` and silently flattened the embedding
+   app's animations). */
+@media (prefers-reduced-motion: reduce) {
+  .wt-root,
+  .wt-root *,
+  .wt-root *::before,
+  .wt-root *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+/* stylelint-enable declaration-no-important, time-min-milliseconds */