@cplieger/web-terminal-ui 7.3.2 → 8.0.0

package/README.md

@@ -1,11 +1,6 @@
 # @cplieger/web-terminal-ui
 
-[![npm](https://img.shields.io/npm/v/@cplieger/web-terminal-ui)](https://www.npmjs.com/package/@cplieger/web-terminal-ui)
-[![JSR](https://jsr.io/badges/@cplieger/web-terminal-ui)](https://jsr.io/@cplieger/web-terminal-ui)
-[![Test coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/coverage.json)](https://github.com/cplieger/web-terminal-ui/actions/workflows/coverage.yml)
-[![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/mutation-ts.json)](https://github.com/cplieger/web-terminal-ui/issues?q=label%3Astryker-tracker)
-[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13431/badge)](https://www.bestpractices.dev/projects/13431)
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/web-terminal-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/web-terminal-ui)
+[![npm](https://img.shields.io/npm/v/@cplieger/web-terminal-ui)](https://www.npmjs.com/package/@cplieger/web-terminal-ui) [![JSR](https://jsr.io/badges/@cplieger/web-terminal-ui)](https://jsr.io/@cplieger/web-terminal-ui) [![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/mutation-ts.json)](https://github.com/cplieger/web-terminal-ui/issues?q=label%3Astryker-tracker)
 
 The reference touch-first browser UI for
 [`@cplieger/web-terminal-engine`](https://github.com/cplieger/web-terminal-engine).
@@ -20,7 +15,7 @@ terminal:
 - a **display-only** terminal output (native text selection survives redraws)
   and a hidden `<textarea>` that owns the keyboard and IME (the kernel)
 - **tabs**: multiple independent terminals with a desktop strip, a mobile
-  bottom switcher, and a modal overview sheet
+  bottom switcher, a modal overview sheet, and an opt-in two-pane split view
 - an **activity monitor** that drives per-tab status dots (working / idle /
   needs-input / exited) from the server's status stream
 - a **mobile key toolbar** (Tab / Esc / arrows / Enter / sticky-Ctrl) and a
@@ -118,10 +113,13 @@ an **element** only when you already hold one you created yourself. The
 difference matters; see "Startup failures" below. There is no element-id
 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.
+again by `destroy()`). Call it at most once per document while the previous
+terminal is alive: the document title, the loading overlay, the status stream and
+the notification permission are properties of the document, so one terminal owns
+them, and a second call reports a `kernel-init` failure and throws without
+touching the page (see "Startup failures"); `destroy()` the first terminal before
+building another, or use the `split` option for a second pane.
+`scaffold/index.html` is a complete reference page to copy and adapt.
 
 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
@@ -199,6 +197,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 | `onFatalError`      | _(built-in recovery)_        | Called with a `TerminalStartupFailure` after a fatal startup failure, in either phase (`feature-setup` or `kernel-init`); behavior below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `onSessionEnded`    | _(none)_                     | Called when the active session's process has ended and nothing is retrying: the fact the banner renders as "Session ended". Wire it only if you can act on it: the recovery move is `handle.reattach()`, and whether that helps depends on what your endpoint does on the next connect (see "When a session ends"). Observation only; everything the kernel does about the end happens first and happens regardless, and a handler that throws is logged rather than allowed to take the banner down with it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `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`, plus the activity-dot palette `--status-working`, `--status-done`, `--status-input`, `--status-warning`, `--status-failed`. The library ships neutral defaults. If you retheme the animated trio (`--status-working` / `--status-warning` / `--status-failed`), keep their LIGHTNESS spread: they differ only in hue, so equal-lightness replacements collapse into one another in greyscale and under deuteranopia.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `split`             | _(off)_                      | Two panes side by side, opened and closed from the tab chrome (see "Split view"). Requires the tabs feature (`tabs()` or a tabbed preset) in `features`; a terminal without it, or a value other than `true` or `false`, fails at `kernel-init`. Without the option the DOM is exactly what it was before the option existed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
 (and opens the soft keyboard on touch); `send(bytes)` sends bytes to the active
@@ -207,7 +206,9 @@ 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, for example Ctrl+L); `reattach()` attaches again to whatever the server
 serves now, for a session that has ended (see "When a session ends"); and
-`destroy()` tears every feature down and releases the kernel.
+`destroy()` tears every feature down and releases the kernel. With `split: true`
+the handle also carries `split`, the controller of the "Split view" section;
+`focus()`, `send()`, `reset()` and `reattach()` act on the selected pane.
 
 ### Mouse and focus
 
@@ -424,17 +425,32 @@ the library entirely and leaves the page spinning under your overlay with nothin
 but a console error. Those were the two failures every consumer used to
 hand-build its own dialog for.
 
-One case has no panel by design: an embedded terminal (`layout: "container"`)
-whose mount target does not exist. It is one panel inside a host application that
+Two cases have no panel by design, both `kernel-init` with `surface: undefined`
+to say there is nowhere to render. An embedded terminal (`layout: "container"`)
+whose mount target does not exist: it is one panel inside a host application that
 is otherwise working, so claiming the viewport to report its own failure would
-break a healthy page. The failure is still delivered to `onFatalError` and still
-rethrown, with `surface: undefined` to say there is nowhere to render.
+break a healthy page. And a second `createTerminal` while the document already
+holds a live terminal, in either layout: the root it names may be the first
+terminal's, so nothing is written to the page and no overlay is faded. Both are
+still delivered to `onFatalError` and still rethrown.
+
+Under `split: true` a failure in the SECOND pane (its kernel or one of its pane
+features, at the first open) is not the terminal's failure: the first pane keeps
+running, the panel renders into the failed pane's own root, non-modally, with its
+one Reload button, and `onFatalError` receives it with that pane root as
+`surface`. The shared split button in the tab row closes the split and discards
+the failed pane, and the next open builds a fresh one. A pane feature that
+rejects only after the split has already closed finds no place for a panel: the
+healthy pane fills the view again, takes over the tab the failed pane was
+showing, and the failed pane is discarded at once, so `onFatalError` receives
+that failure with `surface: undefined` and nothing is rendered.
 
 `onFatalError` receives the failure after cleanup. Discriminate on `phase`:
 `feature-setup` names the offending `feature`, `kernel-init` does not, because
 feature composition never began. `surface` names the element the built-in panel
-would fill, and is the element to render into if you claim it. Return `true` only
-when you have rendered replacement recovery UI there.
+would fill, and is the element to render into if you claim it; it is `undefined`
+in the cases above where nothing is rendered, so check it first. Return `true`
+only when you have rendered replacement recovery UI there.
 
 If your page also carries an inline bootstrap watchdog (a script that reports
 "the JS bundle never loaded at all", a rung below `import`), it cannot import
@@ -443,6 +459,86 @@ the package root and at `@cplieger/web-terminal-ui/startup-copy`, which imports
 nothing and touches no DOM so a build script can read it) and substitute the
 strings into your HTML at build time, rather than restating them by hand.
 
+### Split view
+
+`split: true` lets the person show two tabs side by side. It requires the tabs
+feature, because everything that drives it lives there: the shared tab row, the
+split button, the snap items and the layout record. Your root becomes the shell
+root holding one root per pane and the shared chrome; each pane is a complete
+terminal with its own engine, so an open split holds up to two WebSocket
+connections, one per shown pane. Opening, closing and resizing the split
+is a display re-arrangement only: no tab or session is ever created or closed by
+it, and a tab that leaves a pane stays in the row as an ordinary tab.
+
+Three ways in, all in the tab chrome, none a key chord:
+
+- **The split button** at the right edge of the tab row (and in the mobile
+  switcher bar on a touchscreen) toggles the split. Opening puts the shown tab in
+  the left pane with the right pane empty; the next tab clicked, or the next "+",
+  fills the empty pane. Closing keeps the SELECTED pane's tab and hides the
+  other pane. It is an ordinary button: Tab reaches it, Enter or Space toggles
+  it, `aria-expanded` is its state.
+- **"Snap to left" and "Snap to right"** in a tab's context menu, on a
+  right-click, a touch long-press, or the keyboard (the context-menu key or
+  Shift+F10 on the focused tab, where the browser raises the menu event; Safari
+  binds no key to it, so a keyboard-only person there reaches the menu through
+  an assistive technology's own command). A snapped tab shows on the named side,
+  whatever was there becomes an ordinary tab, and the tab's old side is left
+  empty.
+- **Dragging a tab** out of the row onto the left or right half of the terminal
+  area, which highlights the half under the pointer while the drag lasts.
+
+A tab click follows one rule: an empty pane fills first, otherwise the selected
+pane's tab is replaced. The selected pane is the one that receives typing, the
+last one clicked, touched or typed in. The grip handle between the panes shows
+it: a 6 px pill in the 10 px gutter whose accent edge faces the selected pane,
+and the selected pane keeps the filled blinking cursor while the other pane's is
+hollow and steady. The tab row does not change for selection; both shown tabs
+render identically active. A screen reader hears "Left terminal selected" or
+"Right terminal selected" as a polite announcement, and each pane's tabpanel is
+described by its side and whether it is selected.
+
+While the split is open each shown pane's input is a stop in the Tab order, so
+Tab runs left pane, divider, right pane, then the tab row; an empty pane adds no
+stop. With the split closed the one pane is entered by typing or a click and Tab
+from outside the terminal lands on the tab row.
+
+The handle is a focusable `role="separator"` with `aria-valuenow`, `aria-valuemin`
+and `aria-valuemax` as percentages of the left share. Dragging it (mouse or
+touch, a 24 px hit area) resizes both panes as the pointer moves; the shells are
+told their new size at most every 100 ms and once on release. A pane squeezed
+under 360 px dims, and releasing there closes that pane; releasing above 360 px
+after such a dip snaps the handle back to where the drag started. From the
+keyboard ArrowLeft and ArrowRight nudge the divider by 16 px and Home and End take
+it to the bounds, and every key stops AT the 360 px minimum rather than closing a
+pane; the record is written when the key is released. The default is 50/50.
+
+Under 730 px of pane-row width (two minimum panes and the gutter) the split
+buttons hide, the snap items are disabled, a drop does nothing, and an OPEN split
+collapses to the selected pane, restoring itself when the row is wide again. At
+730 px or wider a window resize keeps both panes at or over 360 px by clamping the
+displayed share; the share the person chose is remembered and comes back when
+the row is wide enough for it.
+
+The arrangement is remembered on the server, beside the tab order, as
+`GET`/`PUT /api/sessions/layout`: the session in each pane, the handle share, the
+selected pane and whether the split is open. It is read once at load, written on
+every change, and dies with the session list, so a reload or another device
+restores the same panes; the active tab is the selected pane's session and is no
+longer kept in `localStorage`. Against a server without the route the split still
+works and nothing is remembered; one console warning says so.
+
+Two rules for a `features` function under `split: true`, both checked at
+`kernel-init`. It is invoked once per pane and must return FRESH feature objects
+every time, because a feature object's `api` and its `ctx.use` identity belong to
+one pane; a saved array (`const f = presetTabbed(); features: () => f`) is
+refused, naming the reused feature. A feature that must exist once per terminal
+rather than once per pane (the built-in tabs, mobile toolbar, activity monitor
+and animations) declares `scope: "shell"`: it is set up once, from the first
+invocation, with a context whose `surface`, `render`, `scroll`, `modes`,
+`session`, `send` and `paste` resolve to the selected pane at call time and whose
+`ctx.shell.pane(side)` reaches one pane explicitly.
+
 ### When a session ends
 
 A session whose process exits is over: the engine closes with its definitive

package/css/30-tabs.css

@@ -433,6 +433,27 @@
   }
 }
 
+:where(.wt-root) .wt-tab-split {
+  flex: none;
+  margin-left: auto;
+}
+
+/* .wt-btn's display would otherwise outrank the attribute. */
+:where(.wt-root) .wt-tab-split[hidden] {
+  display: none;
+}
+
+/* Two auto margins would share the free space between the two buttons. */
+:where(.wt-root) .wt-tab-split:not([hidden]) ~ .wt-tab-kb {
+  margin-left: 0;
+}
+
+@media (any-hover: hover) {
+  :where(.wt-root) .wt-tab-split:hover {
+    background: var(--tab-hover-bg);
+  }
+}
+
 /* ===== Reorder drop slot (tabs feature, desktop drag) =====
    The dragged chip stays in the strip's flow for the whole gesture and renders as
    the SLOT it will land in: an empty dashed outline in the accent over a faint

package/css/31-switcher.css

@@ -287,6 +287,21 @@
   pointer-events: none;
 }
 
+:where(.wt-root) .wt-switcher-split {
+  flex: none;
+  width: var(--touch-target);
+}
+
+@media (any-hover: hover) {
+  :where(.wt-root) .wt-switcher-split:hover {
+    background: var(--tab-hover-bg);
+  }
+}
+
+:where(.wt-root) .wt-switcher-split[hidden] {
+  display: none;
+}
+
 /* Tab-switcher button: toggles the list open/closed, sitting between the
    keyboard and "+" buttons. position: relative anchors its notification dot,
    absolutely placed in the top-right corner. It only earns its place with ≥2

package/css/32-split.css

@@ -0,0 +1,176 @@
+:where(.wt-root.wt-split) {
+  --wt-split-gutter: 10px;
+  --wt-split-ratio: 0.5;
+
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+}
+
+:where(.wt-root.wt-split.wt-split-open) {
+  grid-template-columns:
+    calc((100% - var(--wt-split-gutter)) * var(--wt-split-ratio)) var(--wt-split-gutter)
+    minmax(0, 1fr);
+}
+
+/* Two panes given the same column (the collapse) would otherwise be auto-placed
+   into a second row. */
+:where(.wt-root.wt-split) > .wt-split-pane {
+  grid-row: 1;
+  min-inline-size: 0;
+  min-block-size: 0;
+}
+
+:where(.wt-root.wt-split) > .wt-split-pane.wt-side-left {
+  grid-column: 1;
+}
+
+:where(.wt-root.wt-split) > .wt-split-pane.wt-side-right {
+  grid-column: 3;
+}
+
+:where(.wt-root.wt-split) > .wt-split-pane.wt-pane-hidden {
+  display: none;
+}
+
+:where(.wt-root.wt-split) > .wt-split-pane.wt-pane-closing {
+  opacity: 0.4;
+}
+
+/* 02-terminal.css draws the cursor from the textarea's focus; while the split is
+   open the selection class outranks it in both directions. */
+:where(.wt-root.wt-split.wt-split-open) .wt-pane-selected .term:not(.focus) .term-cursor {
+  background: var(--text);
+  color: var(--bg);
+  box-shadow: none;
+}
+
+:where(.wt-root.wt-split.wt-split-open) .wt-pane-selected .term:not(.focus) .term-cursor-underline {
+  border-bottom: 2px solid var(--text);
+  box-shadow: none;
+}
+
+:where(.wt-root.wt-split.wt-split-open) .wt-pane-selected .term:not(.focus) .term-cursor-bar {
+  border-left: 2px solid var(--text);
+  box-shadow: none;
+}
+
+/* Same specificity as the filled rule above and later in the cascade, so the
+   blink phase still shows. */
+:where(.wt-root.wt-split.wt-split-open .wt-pane-selected)
+  .term:not(.focus).cursor-blink-off
+  .term-cursor {
+  background: transparent;
+  color: var(--text);
+}
+
+:where(.wt-root.wt-split.wt-split-open) .wt-split-pane:not(.wt-pane-selected) .term .term-cursor,
+:where(.wt-root.wt-split.wt-split-open)
+  .wt-split-pane:not(.wt-pane-selected)
+  .term
+  .term-cursor-underline,
+:where(.wt-root.wt-split.wt-split-open)
+  .wt-split-pane:not(.wt-pane-selected)
+  .term
+  .term-cursor-bar {
+  background: transparent;
+  color: var(--text);
+  border: none;
+  box-shadow: inset 0 0 0 1px var(--text);
+  animation: none;
+}
+
+:where(.wt-root.wt-split) > .wt-split-handle {
+  display: none;
+}
+
+:where(.wt-root.wt-split.wt-split-open) > .wt-split-handle {
+  display: block;
+  grid-column: 2;
+  grid-row: 1;
+  position: relative;
+  justify-self: center;
+  inline-size: 24px;
+  margin-inline: -7px;
+  cursor: col-resize;
+  touch-action: none;
+  z-index: 4;
+}
+
+:where(.wt-root.wt-split) .wt-split-handle::before {
+  content: "";
+  position: absolute;
+  inset-inline-start: 9px;
+  inline-size: 6px;
+  inset-block: 12px calc(var(--wt-tabbar-h, 0px) + 12px);
+  border-radius: 3px;
+  background: var(--tab-bg);
+  border-inline: 1px solid var(--border);
+}
+
+:where(.wt-root.wt-split) .wt-split-handle[data-faces="left"]::before {
+  border-inline-start: 2px solid var(--accent);
+}
+
+:where(.wt-root.wt-split) .wt-split-handle[data-faces="right"]::before {
+  border-inline-end: 2px solid var(--accent);
+}
+
+:where(.wt-root.wt-split) .wt-split-handle.wt-handle-held::before {
+  background: color-mix(in oklch, var(--tab-bg), var(--text) 25%);
+}
+
+/* 10-primitives.css scopes the focus ring to button:focus-visible; the handle is
+   a div, and the ring goes on the pill so it follows the visible control. */
+:where(.wt-root.wt-split) .wt-split-handle:focus-visible {
+  outline: none;
+}
+
+:where(.wt-root.wt-split) .wt-split-handle:focus-visible::before {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* Collapsed, the unselected pane is hidden in place rather than display: none:
+   what it measures is the width it will have if the split closes, so no
+   zero-size frame reaches its PTY. */
+:where(.wt-root.wt-split.wt-split-open.wt-split-collapsed) {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+/* Both side classes named, so this outranks the per-side column rules above. */
+:where(.wt-root.wt-split.wt-split-open.wt-split-collapsed) > .wt-split-pane.wt-side-left,
+:where(.wt-root.wt-split.wt-split-open.wt-split-collapsed) > .wt-split-pane.wt-side-right {
+  grid-column: 1;
+}
+
+:where(.wt-root.wt-split.wt-split-open.wt-split-collapsed) > .wt-split-handle {
+  display: none;
+}
+
+:where(.wt-root.wt-split.wt-split-open.wt-split-collapsed) > .wt-split-pane:not(.wt-pane-selected) {
+  visibility: hidden;
+  pointer-events: none;
+}
+
+:where(.wt-root.wt-split.wt-drop-left)::before,
+:where(.wt-root.wt-split.wt-drop-right)::after {
+  content: "";
+  position: absolute;
+  inset-block: 0 var(--wt-tabbar-h, 0);
+  inline-size: 50%;
+  background: color-mix(in oklch, var(--accent) 12%, transparent);
+  pointer-events: none;
+  z-index: 5;
+}
+
+:where(.wt-root.wt-split.wt-drop-left)::before {
+  inset-inline-start: 0;
+}
+
+:where(.wt-root.wt-split.wt-drop-right)::after {
+  inset-inline-start: 50%;
+}
+
+:where(.wt-root.wt-split.wt-animate.wt-split-closing) {
+  transition: grid-template-columns var(--dur-standard) var(--ease-standard);
+}

package/css/MANIFEST

@@ -17,4 +17,5 @@ page.css
 23-toolbar.css
 30-tabs.css
 31-switcher.css
+32-split.css
 40-animations.css

package/css/MANIFEST.tabbed

@@ -13,4 +13,5 @@
 23-toolbar.css
 30-tabs.css
 31-switcher.css
+32-split.css
 40-animations.css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.3.2",
+  "version": "8.0.0",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -40,7 +40,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^5.2.0"
+    "@cplieger/web-terminal-engine": "^6.0.0"
   },
   "overrides": {
     "qs": "^6.15.2"
@@ -50,22 +50,22 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "5.0.0",
-    "@vitest/browser-playwright": "5.0.0",
-    "@vitest/coverage-v8": "5.0.0",
+    "@vitest/browser": "5.0.1",
+    "@vitest/browser-playwright": "5.0.1",
+    "@vitest/coverage-v8": "5.0.1",
     "eslint": "10.10.0",
-    "fast-check": "4.10.0",
-    "html-validate": "11.15.0",
-    "knip": "6.35.1",
+    "fast-check": "4.10.1",
+    "html-validate": "11.16.0",
+    "knip": "6.36.0",
     "playwright": "1.63.0",
-    "prettier": "3.9.6",
+    "prettier": "3.9.7",
     "stylelint": "17.15.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -97,6 +97,7 @@
     "LICENSE",
     "README.md",
     "!src/**/*.test.ts",
-    "!src/**/*-setup.ts"
+    "!src/**/*-setup.ts",
+    "!src/**/test-helpers/**"
   ]
 }