@cplieger/web-terminal-ui 4.0.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,9 +44,12 @@ 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
 

package/css/00-tokens.css

@@ -12,6 +12,16 @@
   --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

@@ -33,6 +33,26 @@
 
 .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 --

package/css/02-terminal.css

@@ -8,6 +8,20 @@
   position: absolute;
   inset: 0;
   overflow: hidden auto;
+  /* Scroll stays in the terminal: reaching the top of scrollback (or the
+     bottom) must not chain the gesture into an embedding page (wt-container
+     mode), and a touch pull inside the terminal must not trigger the host's
+     pull-to-refresh. Full-page hosts already get this via page.css's
+     html/body overscroll-behavior: none; this covers the embedded case. */
+  overscroll-behavior: contain;
+  /* Reserve the scrollbar gutter from the start on classic-scrollbar
+     platforms. Without it the scrollbar pops in when scrollback first
+     exceeds a screen, narrowing the content box -> ResizeObserver -> column
+     recount -> PTY resize -> the running program reflows: a one-time layout
+     jump every fresh session. Real terminals reserve this space permanently;
+     with the boundary's thin dark scrollbars (01-scope.css) the idle gutter
+     is a subtle strip. No-op on overlay-scrollbar platforms. */
+  scrollbar-gutter: stable;
   /* The scroll controller (vterm scroll.ts) is the single owner of
      scrollTop: it pins to the bottom only while the user is following,
      and does nothing while they are scrolled up reading. New output
@@ -236,6 +250,41 @@
   color: var(--text);
 }
 
+/* Caret overlay (engine >= v3): the renderer paints the REAL cursor as one
+   absolutely-positioned element in the scroll container (a sibling of
+   .pred-cursor, below it in the stack), not as a restyled span inside the
+   cursor row — rows stay pure content, so a native text selection survives
+   cursor motion and typing. The engine sets left/top/width/height/line-height
+   inline each flush; the .term-cursor / -underline / -bar variant classes
+   above keep supplying the colors and borders, and the JS-driven
+   .cursor-blink-off toggle (now on the scroll container) keeps driving the
+   block blink. */
+:where(.wt-root) .term-cursor-overlay {
+  position: absolute;
+  pointer-events: none;
+  white-space: pre;
+  overflow: hidden;
+  z-index: 3;
+  box-sizing: border-box;
+}
+
+:where(.wt-root) .term-cursor-overlay:not(.visible) {
+  display: none;
+}
+
+/* DECSCNM reverse video (private mode 5): the engine toggles
+   .term-reverse-video on the scroll container (render.updateReverseVideo);
+   this rule swaps the DEFAULT color pair for the terminal subtree via the
+   captured copies from 00-tokens.css. Everything painted with var(--text)/
+   var(--bg) — default-colored cells, the screen background, the block cursor's
+   inverted cell — follows automatically; explicitly colored cells keep their
+   colors, matching xterm's DECSCNM semantics (the default pair swaps, not a
+   per-pixel inversion). */
+:where(.wt-root) .term.term-reverse-video {
+  --text: var(--bg-default);
+  --bg: var(--text-default);
+}
+
 :where(.wt-root) .term-blink {
   animation: wt-blink-anim 1s step-end infinite;
 }

package/css/10-primitives.css

@@ -41,6 +41,19 @@
   background: var(--text-active);
 }
 
+/* Keyboard-focus ring for every chrome control (all interactive chrome is a
+   real <button>: tabs, +, keyboard, switcher rows, menu items, the FAB).
+   :focus-visible only — a tap/click never shows the ring (the UA heuristic),
+   so the touch-first surfaces stay clean while Tab-key navigation gets the
+   family's accent ring (the vibekit/subflux convention: 2px accent, 2px out).
+   Follows each control's border-radius; themeable via --accent like the "+"
+   glyphs. The terminal's own hidden textarea is not a button and keeps its
+   outline: none (02-terminal.css). */
+:where(.wt-root) button:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
 :where(.wt-root) .wt-btn svg {
   width: var(--icon);
   height: var(--icon);

package/css/30-tabs.css

@@ -13,7 +13,10 @@
 
 :where(.wt-root) .wt-tab-bar {
   /* Absolute against .wt-root, like all chrome (identical geometry in
-     wt-viewport mode; see 01-scope.css). */
+     wt-viewport mode; see 01-scope.css). The bar itself never scrolls: the
+     tabs + "+" scroll inside .wt-tab-scroll (below), so the keyboard button —
+     the bar's last flex item, outside the scroller — stays pinned at the right
+     edge however many tabs are open. */
   position: absolute;
   bottom: var(--safe-bottom);
   left: 0;
@@ -26,17 +29,34 @@
   background: var(--surface);
   backdrop-filter: var(--blur);
   border-top: 1px solid var(--border);
-  overflow-x: auto;
   z-index: 15;
 }
 
+/* The scrolling tab list inside the bar: the tabs plus the "+", which floats
+   right of the last tab and scrolls with the list. Horizontal scrolling lives
+   HERE, not on the bar, so the strip-end keyboard button never scrolls away.
+   flex: 1 + min-width: 0 make it shrink to leave room for the keyboard button
+   when that is shown (a wide touchscreen) and stretch to the full bar width
+   when it is hidden (a fine-pointer desktop), so the tabs reclaim the space. */
+:where(.wt-root) .wt-tab-scroll {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-1);
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-x: auto;
+  /* A wheel/trackpad/touch scroll that runs out of tabs must not chain into
+     an embedding page (wt-container mode). */
+  overscroll-behavior-x: contain;
+}
+
 :where(.wt-root) .wt-tab {
   display: inline-flex;
   align-items: center;
   gap: var(--sp-1);
   /* Browser-style tabs: up to 300px per tab when there is room, shrinking toward
-     a 100px floor as the strip fills; past the floor the bar scrolls horizontally
-     (.wt-tab-bar has overflow-x: auto). flex-grow is 0, so the 300px basis is a
+     a 100px floor as the strip fills; past the floor the list scrolls horizontally
+     (.wt-tab-scroll has overflow-x: auto). flex-grow is 0, so the 300px basis is a
      hard cap — every tab is the same size and never stretches past it, whatever
      its title; the label truncates instead. box-sizing keeps the basis a true
      total. */
@@ -202,14 +222,16 @@
    landscape), where there is no mobile switcher to carry one. Built + wired by
    the SAME factory as the mobile switcher's keyboard button (see makeKbButton
    in tabs.ts). Uses the shared .wt-btn primitive for its 44px box + centered
-   icon, borderless like the switcher's — the old fixed-overlay styling gave it
-   a border and pinned it right of the "+", which read as a different control
-   the moment a phone rotated to landscape. Now an ordinary flex item inside the
-   strip, before the "+" (kb-then-new, mirroring the mobile switcher's order).
-   Hidden on a fine-pointer desktop (a real keyboard is present) and until a
-   keyboardToggle feature is wired ([hidden]); shown only on a coarse pointer at
-   strip widths (the .wt-narrow complement below; the breakpoint itself is the
-   kernel's, mirrored as the root class). */
+   icon, borderless like the switcher's. The bar's LAST flex item, OUTSIDE the
+   tab scroller: pinned at the bar's right edge in the same column as the
+   scroll-to-bottom button floating above it (both 44px boxes whose right edge
+   sits --sp-2 from the root's right edge), where an overflowing tab list can
+   never push or scroll it away; the "+" stays with the tabs inside the
+   scroller. Hidden on a fine-pointer desktop (a real keyboard is present; the
+   scroller then stretches to the full bar width) and until a keyboardToggle
+   feature is wired ([hidden]); shown only on a coarse pointer at strip widths
+   (the .wt-narrow complement below; the breakpoint itself is the kernel's,
+   mirrored as the root class). */
 :where(.wt-root) .wt-tab-kb {
   display: none;
   flex: none;

package/css/31-switcher.css

@@ -82,6 +82,10 @@
      clear of the soft keyboard. */
   max-height: var(--wt-list-h, 50dvh);
   overflow-y: auto;
+  /* Reaching the list's end must not hand the touch scroll to an embedding
+     page (wt-container mode) — the tray sits over the terminal, and a chained
+     scroll behind an open tray is disorienting. */
+  overscroll-behavior-y: contain;
   /* No top padding: the bar's --sp-2 bottom padding already sits between the
      active tab and the first row, so the seam equals the --sp-2 inter-row gap. */
   padding-top: 0;
@@ -318,12 +322,19 @@
    In the tabbed presets the mobile toolbar hides its own toggle (a tab-chrome
    keyboard button drives it — the switcher's on a narrow phone, the strip's
    .wt-tab-kb on a wide touchscreen) and the grid docks bottom-right above the
-   tab chrome, to the left of where scroll-to-bottom sits. It collapses to
-   fully hidden, since there is no in-grid toggle to keep visible. The BASE
-   rules here are the wide-touchscreen (strip) placement — above --wt-tabbar-h;
-   the .wt-narrow override below re-anchors above the switcher bar instead
-   (--wt-switcher-h). Everything else (toggle hidden, right offset, grid
-   columns, collapsed fully hidden) is identical in both modes. */
+   tab chrome, its RIGHT edge aligned with the keyboard button that opened it,
+   so the popup visually hangs off its toggle in every mode (it may overlap the
+   scroll-to-bottom button — deliberate: the grid is transient and on top). It
+   collapses to fully hidden, since there is no in-grid toggle to keep visible.
+   The BASE rules here are the wide-touchscreen (strip) placement — above
+   --wt-tabbar-h, right-aligned to the strip's .wt-tab-kb (the bar's last flex
+   item, inset --sp-2 by the bar padding); the .wt-narrow overrides below
+   re-anchor above the switcher bar (--wt-switcher-h) and shift left past the
+   bar controls sitting right of the switcher's kb button: the "+" (always)
+   and, once a second tab reveals it, the switch button (.wt-switcher-multi
+   from the tabs feature, read here via :has() since the grid is a sibling
+   region of the switcher). Everything else (toggle hidden, grid columns,
+   collapsed fully hidden) is identical in all modes. */
 @media (pointer: coarse) {
   :where(.wt-root) .wt-toolbar-external .kb-toggle {
     display: none;
@@ -331,7 +342,7 @@
 
   :where(.wt-root) .key-toolbar.wt-toolbar-external {
     top: auto;
-    right: calc(var(--sp-3) + var(--touch-target) + var(--sp-2));
+    right: var(--sp-2);
     bottom: calc(
       var(--wt-tabbar-h, 44px) + var(--safe-bottom, 0px) + var(--kb-inset, 0px) + var(--sp-2)
     );
@@ -342,12 +353,21 @@
     display: none;
   }
 
-  /* Narrow phone (mobile switcher mode): dock above the switcher bar. */
+  /* Narrow phone (mobile switcher mode): dock above the switcher bar,
+     right-aligned to the switcher's kb button — one 44px control (+ gap)
+     in from the edge past the "+"... */
   :where(.wt-root.wt-narrow) .key-toolbar.wt-toolbar-external {
+    right: calc(var(--sp-2) + var(--touch-target) + var(--sp-1));
     bottom: calc(
       var(--wt-switcher-h) + var(--safe-bottom, 0px) + var(--kb-inset, 0px) + var(--sp-2)
     );
   }
+
+  /* ...and a second control in once the switch button is revealed (>= 2 tabs).
+     Ordered after the single-tab rule so it wins when both match. */
+  :where(.wt-root.wt-narrow:has(.wt-switcher-multi)) .key-toolbar.wt-toolbar-external {
+    right: calc(var(--sp-2) + 2 * (var(--touch-target) + var(--sp-1)));
+  }
 }
 
 /* ===== Expanded tab-list rows (tabs feature) =====

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.0.0",
+  "version": "4.1.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": "GPL-3.0-or-later",
@@ -38,7 +38,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^2.8.0"
+    "@cplieger/web-terminal-engine": "^3.0.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -52,7 +52,7 @@
     "fast-check": "4.9.0",
     "happy-dom": "20.10.6",
     "html-validate": "11.5.6",
-    "knip": "6.26.0",
+    "knip": "6.27.0",
     "prettier": "3.9.5",
     "stylelint": "17.14.0",
     "stylelint-config-standard": "40.0.0",

package/src/features/activity-monitor.ts

@@ -3,8 +3,11 @@
 // session's live status through its API (design sections 7, 22.4, 22.5). It is a
 // pure data source with no chrome of its own; the tabs feature consumes it via
 // ctx.use to render per-tab activity dots and drop exited/removed tabs. The
-// server pushes an initial snapshot on every (re)open, so no explicit resync is
-// needed here.
+// server pushes an initial snapshot on every (re)open — but the snapshot
+// carries no tombstones for sessions a REPLACEMENT server never knew (manager
+// restart), so the stream-open signal is surfaced via onStreamOpen and the
+// consumer (tabs) runs a one-shot GET /api/sessions reconcile there to drop
+// zombie tabs.
 
 import { connectStatusStream } from "@cplieger/web-terminal-engine";
 import type { SessionStatus } from "@cplieger/web-terminal-engine";
@@ -18,6 +21,13 @@ export interface ActivityMonitorApi {
   onStatus(cb: (s: SessionStatus) => void): Unsubscribe;
   /** The last known status for a session, or undefined. */
   current(id: string): SessionStatus | undefined;
+  /** Subscribe to stream (re)open events — fired on the initial SSE connect
+   *  and every reconnect (including the reopen against a restarted server,
+   *  whose fresh snapshot cannot tombstone sessions it never knew). A
+   *  subscriber attaching after an open has already happened is called
+   *  immediately (catch-up), so a late consumer never misses the initial
+   *  open. Optional so alternative monitor implementations remain valid. */
+  onStreamOpen?(cb: () => void): Unsubscribe;
 }
 
 export function activityMonitor(
@@ -29,8 +39,20 @@ export function activityMonitor(
       const path = opts.eventsPath ?? DEFAULT_EVENTS_PATH;
       const statuses = new Map<string, SessionStatus>();
       const subs = new Set<(s: SessionStatus) => void>();
+      const openSubs = new Set<() => void>();
+      let opens = 0;
 
       const stream = connectStatusStream(path, {
+        onOpen() {
+          opens++;
+          for (const cb of [...openSubs]) {
+            try {
+              cb();
+            } catch (err) {
+              console.error("web-terminal-ui: activityMonitor open subscriber threw", err);
+            }
+          }
+        },
         onStatus(s) {
           if (s.removed) {
             statuses.delete(s.id);
@@ -59,10 +81,18 @@ export function activityMonitor(
           current(id) {
             return statuses.get(id);
           },
+          onStreamOpen(cb) {
+            openSubs.add(cb);
+            if (opens > 0) {
+              cb(); // catch-up: the stream opened before this subscriber attached
+            }
+            return () => openSubs.delete(cb);
+          },
         },
         teardown() {
           stream.close();
           subs.clear();
+          openSubs.clear();
           statuses.clear();
         },
       };

package/src/features/connection-banner.ts

@@ -14,6 +14,7 @@ const TEXT: Partial<Record<ConnState, string>> = {
   // The session's process exited (definitive; nothing is retrying). The final
   // screen stays rendered behind the banner; open a new tab to keep working.
   ended: "Session ended",
+  incompatible: "Terminal protocol mismatch; update the server or reload this page",
 };
 
 export function connectionBanner(): TerminalFeature {

package/src/features/mobile-toolbar.ts

@@ -1,15 +1,16 @@
 // mobileToolbar feature: the on-screen key toolbar (Tab/Esc/arrows/Enter + a
 // collapse toggle and sticky-Ctrl) in the thumb-zone region (design section
-// 22.4). The engine's keyboard.bindMobileToolbar wires the buttons (DECCKM-aware
-// arrows, sticky-Ctrl state); this feature builds the toolbar chrome, routes its
+// 22.4). The engine's toolbar.bindMobileToolbar wires the buttons (DECCKM-aware
+// arrows, sticky-Ctrl state; engine >= v3, where the widget moved out of the
+// keyboard module); this feature builds the toolbar chrome, routes its
 // output through the kernel funnel, and registers sticky-Ctrl as an input
 // transform so a typed character is rewritten to its Ctrl byte when armed.
 
-import { keyboard } from "@cplieger/web-terminal-engine";
+import { toolbar } from "@cplieger/web-terminal-engine";
 import type { TerminalFeature } from "../kernel/types.js";
 import { fromHTML } from "./dom.js";
 
-const { bindMobileToolbar } = keyboard;
+const { bindMobileToolbar } = toolbar;
 
 /** mobileToolbar's public API, so a peer feature (tabs) can drive the key grid
  *  from a button it owns instead of the toolbar's own toggle. */

package/src/features/tabs/index.ts

@@ -48,13 +48,15 @@ import {
 
 const DEFAULT_API_BASE = "/api/sessions";
 // The mobile bottom-switcher (a single full-width active-tab chip + swipe) is
-// used ONLY on a narrow coarse-pointer device (a phone). A wide touchscreen (an
-// iPad) and every fine-pointer device (a desktop, or an iPad with a trackpad /
-// Magic Keyboard) get the multi-tab top strip instead — the switcher's
-// single-giant-tab layout wastes a big screen (an iPad was getting the phone
-// UI). The narrow half of that fact is the kernel's .wt-narrow root class /
-// ctx.layout().narrow (ONE breakpoint constant, kernel-owned, root-width
-// driven); CSS pairs it with (pointer: coarse) where touch matters.
+// used ONLY on a narrow coarse-pointer device (a phone — in EITHER
+// orientation: a landscape phone is wide but short, and the kernel's narrow
+// fact covers both). A big touchscreen (an iPad) and every fine-pointer device
+// (a desktop, or an iPad with a trackpad / Magic Keyboard) get the multi-tab
+// top strip instead — the switcher's single-giant-tab layout wastes a big
+// screen (an iPad was getting the phone UI). The narrow half of that fact is
+// the kernel's .wt-narrow root class / ctx.layout().narrow (kernel-owned
+// breakpoint constants, root-size driven); CSS pairs it with
+// (pointer: coarse) where touch matters.
 // Default cadence for the no-activityMonitor polling fallback.
 const DEFAULT_POLL_MS = 4000;
 // Tab context-menu viewport clamping + the flip-above-the-pointer gap live in
@@ -222,24 +224,30 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
 
       // --- Desktop tab strip (top-bar region) ---
+      // Two layers: the bar itself never scrolls; an inner scroller
+      // (.wt-tab-scroll, the tablist) holds the tabs plus the "+", which floats
+      // right of the tab list and scrolls WITH it when many tabs overflow. The
+      // keyboard button sits OUTSIDE the scroller as the bar's last flex item,
+      // pinned at the bar's right edge in the scroll-to-bottom button's column
+      // (an overflowing tab list can never push or scroll it away). On a fine
+      // pointer it is display:none (CSS), and the scroller stretches to the
+      // full bar width so the tabs reclaim that space. Both controls are built
+      // + wired by the same shared factories as the mobile switcher's; the kb
+      // button is CSS-gated to a wide touchscreen and un-hidden below only when
+      // a keyboardToggle is wired. addTabChrome inserts each tab before newBtn,
+      // keeping the scroller [tabs… +].
       const slot = ctx.region("top-bar", "tabs");
       const bar = document.createElement("div");
       bar.className = "wt-tab-bar";
-      bar.setAttribute("role", "tablist");
       slot.appendChild(bar);
-      // Strip-end controls, both flex items INSIDE the strip so they flow after
-      // the tabs (appending them to the slot flowed them out of the strip):
-      // the keyboard button first, then the "+" — mirroring the mobile
-      // switcher's kb-before-new order, so rotating a phone to landscape (which
-      // swaps in this strip) keeps the keyboard button LEFT of the "+" rather
-      // than jumping to its right. Built + wired by the same shared factories
-      // as the mobile switcher's; the kb button is CSS-gated to a wide
-      // touchscreen and un-hidden below only when a keyboardToggle is wired.
-      // addTabChrome inserts each tab before deskKb, keeping [tabs… kb +].
+      const scroller = document.createElement("div");
+      scroller.className = "wt-tab-scroll";
+      scroller.setAttribute("role", "tablist");
+      bar.appendChild(scroller);
+      const newBtn = makeNewButton("wt-tab-new");
+      scroller.appendChild(newBtn);
       const deskKb = makeKbButton("wt-tab-kb wt-btn");
       bar.appendChild(deskKb);
-      const newBtn = makeNewButton("wt-tab-new");
-      bar.appendChild(newBtn);
 
       // Pull the terminal surface up off the docked BOTTOM strip on desktop so
       // the bar does not overlap the last rows. The surface is absolute
@@ -400,6 +408,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       ctx.region("overlay", "tab-menu").appendChild(tabMenu);
 
       const tabList: Tab[] = [];
+      // Monotonic local-mutation counter stamped onto each adopted tab (Tab.born)
+      // and snapshotted by reconcileOnce before its GET /api/sessions, so a
+      // stale listing can never drop a tab adopted while it was in flight (the
+      // boot race: the bootstrap's create vs the SSE stream-open reconcile).
+      let tabEpoch = 0;
       // Close tombstones (model.ts): ids the user closed recently, so a stale
       // server listing (the SSE re-open snapshot, or the poll's GET
       // /api/sessions) that predates the server reaping the session does not
@@ -855,9 +868,9 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
         paintStatusDot(dot, info.status, info.reportsActivity ?? false);
         const aria = tablist.registerTab(el);
-        // Insert before the strip-end controls (keyboard button, then "+") so
-        // they stay the last items in the strip.
-        bar.insertBefore(el, deskKb);
+        // Insert before the "+" so it stays the last item of the scrolling tab
+        // list (the keyboard button lives outside the scroller, at the bar end).
+        scroller.insertBefore(el, newBtn);
         // Runtime-added tabs animate in; initial tabs do not (see `started`).
         // The timer (not animationend) also clears the class on the hidden mobile
         // strip, where the animation never fires.
@@ -870,6 +883,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
 
         const tab: Tab = {
           id: info.id,
+          born: ++tabEpoch,
           title: info.title,
           clientTitle: info.clientTitle,
           display: "",
@@ -959,11 +973,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             slide = to > from ? "next" : "prev";
           }
         }
-        const surface = ctx.surface();
         // Detach the current tab: save its scroll memory (keep its cache).
+        // Read through the engine's scroll seam, never surface.scrollTop —
+        // the controller owns the container's scroll geometry.
         const cur = tabList.find((t) => t.id === activeId);
         if (cur) {
-          cur.scrollTop = surface.scrollTop;
+          cur.scrollTop = ctx.scroll.currentScrollTop();
           cur.following = !ctx.scroll.isUserScrolledUp();
         }
         // Decide whether to animate the expanded list as a rotation: only a
@@ -1025,7 +1040,9 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           if (following) {
             ctx.scroll.scrollToBottom();
           } else {
-            surface.scrollTop = savedTop;
+            // The write half of scroll memory goes through the same seam; the
+            // controller re-derives hold from the resulting scroll event.
+            ctx.scroll.restoreScrollTop(savedTop);
           }
         });
         ctx.announce(`Switched to ${next.display}`);
@@ -1125,11 +1142,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
 
       // dragTargetBefore returns the first tab whose horizontal midpoint is past
       // x (the element the dragged tab should sit before), or null to drop at the
-      // end (before the strip-end controls). syncOrderFromDom rebuilds tabList to
+      // end (before the "+"). syncOrderFromDom rebuilds tabList to
       // match the strip's DOM order after a drag, so position indicators, the
       // switcher, and close-to-the-right/left all follow the visible order.
       function dragTargetBefore(x: number): HTMLElement | null {
-        for (const el of bar.querySelectorAll<HTMLElement>(".wt-tab:not(.wt-tab-dragging)")) {
+        for (const el of scroller.querySelectorAll<HTMLElement>(".wt-tab:not(.wt-tab-dragging)")) {
           const rect = el.getBoundingClientRect();
           if (x < rect.left + rect.width / 2) {
             return el;
@@ -1139,7 +1156,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
       function syncOrderFromDom(): void {
         const order: Tab[] = [];
-        for (const el of bar.querySelectorAll<HTMLElement>(".wt-tab")) {
+        for (const el of scroller.querySelectorAll<HTMLElement>(".wt-tab")) {
           const t = tabList.find((x) => x.el === el);
           if (t) {
             order.push(t);
@@ -1494,7 +1511,66 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // drop; the poll additionally learns of a background exit the SSE would
       // have pushed (section 22.5).
       let offStatus: (() => void) | undefined;
+      let offStreamOpen: (() => void) | undefined;
       let pollTimer: ReturnType<typeof setInterval> | null = null;
+      // One-shot list reconcile shared by both status sources: adopt every
+      // session the server lists, then drop tabs it no longer lists. The poll
+      // fallback runs it on a timer; the SSE path runs it on every stream
+      // (re)open — the reopen against a RESTARTED manager is the moment
+      // zombie tabs must drop, because the fresh server's snapshot carries no
+      // tombstones for sessions it never knew, so those tabs would otherwise
+      // spin "Reconnecting…" forever (judgement finding sf-2).
+      // Guarded against overlapping runs: a server slower than the trigger
+      // cadence (but within the 15s API timeout) would otherwise race tabList
+      // mutation. Skip the extra run instead.
+      let reconciling = false;
+      const reconcileOnce = async (): Promise<void> => {
+        if (reconciling) {
+          return;
+        }
+        reconciling = true;
+        try {
+          // Snapshot the mutation epoch BEFORE the list round-trip: the listing
+          // is authoritative only for tabs that already existed when it was
+          // requested. A tab adopted while the GET was in flight (the boot
+          // race: the bootstrap's create vs this stream-open reconcile) is
+          // invisible to the returned snapshot, and dropping it here cascaded
+          // into a duplicate replacement session (dropTab's last-tab intercept
+          // spawns one) — the double-create boot bug.
+          const epochAtList = tabEpoch;
+          let list: SessionInfo[];
+          try {
+            list = await api.list();
+          } catch {
+            return; // transient; try again on the next trigger
+          }
+          const seen = new Set(list.map((s) => s.id));
+          for (const info of list) {
+            adoptSession(info); // add sessions created elsewhere (no local tab)
+            applyStatus(
+              info.id,
+              info.status,
+              info.title,
+              info.clientTitle,
+              info.reportsActivity ?? false,
+            );
+          }
+          // A tab the server no longer lists was reaped/closed elsewhere (or
+          // died with a restarted manager): drop it locally (no DELETE — it
+          // is already gone). Tabs born after the list snapshot are spared this
+          // round; the next reconcile sees the server truth for them.
+          const gone = tabList
+            .filter((t) => !seen.has(t.id) && t.born <= epochAtList)
+            .map((t) => t.id);
+          for (const id of gone) {
+            await dropTab(id, false);
+          }
+          ensureActive();
+          syncChrome();
+        } finally {
+          reconciling = false;
+        }
+      };
       if (monitor) {
         offStatus = monitor.onStatus((s) => {
           if (s.removed) {
@@ -1514,50 +1590,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           ensureActive();
           syncChrome();
         });
+        offStreamOpen = monitor.onStreamOpen?.(() => {
+          void reconcileOnce();
+        });
       } else {
         const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
-        // Guard against overlapping runs: a server slower than pollMs (but
-        // within the 15s API timeout) would otherwise let setInterval start
-        // a second pollOnce while the first is still awaiting, racing tabList
-        // mutation. Skip the tick instead.
-        let polling = false;
-        const pollOnce = async (): Promise<void> => {
-          if (polling) {
-            return;
-          }
-          polling = true;
-          try {
-            let list: SessionInfo[];
-            try {
-              list = await api.list();
-            } catch {
-              return; // transient; try again next tick
-            }
-            const seen = new Set(list.map((s) => s.id));
-            for (const info of list) {
-              adoptSession(info); // add sessions created elsewhere (no local tab)
-              applyStatus(
-                info.id,
-                info.status,
-                info.title,
-                info.clientTitle,
-                info.reportsActivity ?? false,
-              );
-            }
-            // A tab the server no longer lists was reaped/closed elsewhere: drop it
-            // locally (no DELETE — it is already gone).
-            const gone = tabList.filter((t) => !seen.has(t.id)).map((t) => t.id);
-            for (const id of gone) {
-              await dropTab(id, false);
-            }
-            ensureActive();
-            syncChrome();
-          } finally {
-            polling = false;
-          }
-        };
         pollTimer = setInterval(() => {
-          void pollOnce();
+          void reconcileOnce();
         }, pollMs);
       }
 
@@ -1584,7 +1623,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         if (e.dataTransfer) {
           e.dataTransfer.dropEffect = "move";
         }
-        bar.insertBefore(draggingEl, dragTargetBefore(e.clientX) ?? deskKb);
+        scroller.insertBefore(draggingEl, dragTargetBefore(e.clientX) ?? newBtn);
       });
       // Active-row close (x): closes the current tab (mirrors a listed row's x).
       // stopPropagation so it is not read as a tap/swipe on the row surface.
@@ -2125,6 +2164,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         teardown() {
           resolveImpl = null;
           offStatus?.();
+          offStreamOpen?.();
           offInput();
           offHwKey();
           offArmed?.();

package/src/features/tabs/model.ts

@@ -29,6 +29,14 @@ export const SWIPE_HINT_KEY = "wt-swipe-hint-seen";
 
 export interface Tab {
   id: string;
+  /** Local mutation epoch at which this tab was adopted (a monotonic counter,
+   *  not a timestamp). The list reconcile snapshots the counter BEFORE its GET
+   *  /api/sessions and drops a server-unlisted tab only when the tab predates
+   *  that snapshot — a tab born while the list was in flight (the bootstrap's
+   *  create racing the SSE stream-open reconcile) is invisible to that stale
+   *  listing, and dropping it would cascade into a duplicate replacement
+   *  session (the boot double-create bug). */
+  born: number;
   /** The raw server title (the OSC 0/2 window title the process set), possibly
    *  empty before the process sets one. The displayed label is derived from it
    *  with a numbered fallback and de-duplication (see relabelAll in index.ts). */

package/src/kernel/conn-state.ts

@@ -38,6 +38,9 @@ export interface ConnStateMachine {
    *  the state shows immediately and persists until open() (a switch to a
    *  live session) replaces it. */
   ended(): void;
+  /** The engine refused an explicitly incompatible wire revision. This
+   *  terminal state bypasses the loading gate and persists until open(). */
+  incompatible(): void;
   /** First screen frame rendered: the loading overlay is done, so the banner
    *  may show reconnect state from here on. */
   setLoaded(): void;
@@ -59,13 +62,14 @@ export function createConnState(opts: {
 
   function emit(): void {
     // Suppress transient states until the initial load is over (the loading
-    // overlay owns the screen), with two exceptions that must show through:
-    // "offline" once the initial-failure limit is reached, and "ended" (a
-    // definitive process exit — nothing further will ever fire, so suppressing
-    // it would hide the only explanation the page will get). connectionBanner
-    // renders "open" as hidden.
+    // overlay owns the screen). Terminal states ("ended" and "incompatible")
+    // must pass through because no later frame or reconnect will explain the
+    // failure; "offline" also passes once the initial-failure limit is reached.
+    // connectionBanner renders "open" as hidden.
     const passesLoadingGate =
-      state === "ended" || (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
+      state === "ended" ||
+      state === "incompatible" ||
+      (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
     if (!loaded && !passesLoadingGate) {
       opts.onState("open"); // nothing to show yet
       return;
@@ -130,6 +134,12 @@ export function createConnState(opts: {
       consecutiveFailures = 0;
       setState("ended", 0);
     },
+    incompatible(): void {
+      // Wire refusal is terminal for this page instance. Like ended, it is not
+      // part of the failure ladder and must remain visible without a timer.
+      consecutiveFailures = 0;
+      setState("incompatible", 0);
+    },
     setLoaded(): void {
       loaded = true;
     },

package/src/kernel/kernel.ts

@@ -49,14 +49,24 @@ const TAP_MOVEMENT_PX = 10;
 // native text selection / the context menu — so tap-to-focus bows out above
 // this duration and never steals a long-press or a selection.
 const TAP_MAX_MS = 500;
-// The narrow-layout breakpoint, in ROOT-width pixels. The single source of the
-// number: the kernel mirrors it into the .wt-narrow root class for CSS (paired
-// there with pointer-coarseness media queries where touch matters) and features
-// read the same fact via ctx.layout(). Root width — not viewport width — so an
-// embedded terminal in a narrow panel counts as narrow. For every full-page
-// consumer root width equals viewport width, so the behavior matches the old
-// (max-width: 600px) media queries exactly.
+// The narrow-layout breakpoints, in ROOT pixels. The single source of the
+// numbers: the kernel mirrors the resulting fact into the .wt-narrow root
+// class for CSS (paired there with pointer-coarseness media queries where
+// touch matters) and features read the same fact via ctx.layout(). Root
+// dimensions — not viewport dimensions — so an embedded terminal in a narrow
+// panel counts as narrow. For every full-page consumer root size equals
+// viewport size, so the width half matches the old (max-width: 600px) media
+// queries exactly.
 const NARROW_MAX_PX = 600;
+// A root can be compact by HEIGHT as well as width: a large phone rotated to
+// landscape (e.g. an iPhone 14 Pro Max at 932x430) is wider than
+// NARROW_MAX_PX, but its short viewport is still a phone in the hand — the
+// thumb-reach switcher bar is the right UX and the desktop strip wastes
+// scarce rows. Tablets are never this short (the smallest iPad is 744 CSS px
+// tall in landscape), so height <= 500 cleanly separates "landscape phone"
+// from "tablet/desktop" with margin on both sides (the tallest current
+// phones are ~440 in landscape, less with browser chrome).
+const SHORT_MAX_PX = 500;
 
 // Kernel-owned core subtree: the display-only output, the hidden textarea (the
 // single keyboard target), and the IME composition view. No chrome; features
@@ -133,8 +143,12 @@ export function createTerminal(
   const announcer = createAnnouncer(root);
   const tablistController = createTablist(outputEl);
 
-  // --- Narrow-layout driver (.wt-narrow mirrors root width for CSS) ---
-  const isNarrow = (): boolean => root.clientWidth <= NARROW_MAX_PX;
+  // --- Narrow-layout driver (.wt-narrow mirrors root size for CSS) ---
+  // Narrow = compact in EITHER dimension: skinny (a phone in portrait, a
+  // narrow embedded panel) or short (a phone in landscape). The one
+  // ResizeObserver below fires on both width and height changes.
+  const isNarrow = (): boolean =>
+    root.clientWidth <= NARROW_MAX_PX || root.clientHeight <= SHORT_MAX_PX;
   function updateNarrow(): void {
     root.classList.toggle("wt-narrow", isNarrow());
   }
@@ -365,6 +379,13 @@ export function createTerminal(
       markReady();
       connState.ended();
     },
+    onWireIncompatible() {
+      // Compatibility refusal is terminal for this page instance. Lower the
+      // pre-JS overlay even if no screen frame arrived, then leave the
+      // actionable banner visible while the engine suppresses reconnects.
+      markReady();
+      connState.incompatible();
+    },
     onServerRestart() {
       render.resetScrollback();
       render.resetScreen();

package/src/kernel/types.ts

@@ -60,7 +60,10 @@ export type ConnState =
   // The active session's process has EXITED (the engine's definitive 4001
   // close): not a connectivity problem, so no reconnect is coming. Cleared
   // only by connecting somewhere live (a tab switch / a new session).
-  | "ended";
+  | "ended"
+  // The engine refused an explicitly incompatible wire revision. This is a
+  // terminal state, not a transient disconnect; page reload/update is required.
+  | "incompatible";
 
 // --- Engine drive handles ---
 //
@@ -89,6 +92,13 @@ export interface RenderHandle {
 export interface ScrollHandle {
   scrollToBottom(): void;
   isUserScrolledUp(): boolean;
+  /** The viewport's current scroll offset — the read half of per-tab scroll
+   *  memory. The engine's scroll controller owns the container's scrollTop;
+   *  features go through this seam, never the DOM element (engine >= v3). */
+  currentScrollTop(): number;
+  /** Restore a saved offset; follow/hold re-derives from the resulting scroll
+   *  event exactly as for a user scroll — the write half of scroll memory. */
+  restoreScrollTop(top: number): void;
 }
 
 // --- Typed event bus payloads (section 22.4) ---
@@ -202,11 +212,13 @@ export interface TerminalContext {
   tablist(): TablistController;
 
   /** The current layout facts a feature keys touch-vs-desktop behavior on.
-   *  `narrow` is ROOT width at or below the kernel's single breakpoint (the
-   *  same fact the .wt-narrow root class exposes to CSS — root width, not
-   *  viewport width, so an embedded terminal in a narrow panel counts as
-   *  narrow). `coarse` is the primary pointer's coarseness (a live media-query
-   *  read). Read lazily at interaction time. */
+   *  `narrow` is a ROOT compact in EITHER dimension against the kernel's
+   *  breakpoints: skinny (width, a portrait phone or a narrow embedded panel)
+   *  or short (height, a landscape phone) — the same fact the .wt-narrow root
+   *  class exposes to CSS; root size, not viewport size, so an embedded
+   *  terminal in a narrow panel counts as narrow. `coarse` is the primary
+   *  pointer's coarseness (a live media-query read). Read lazily at
+   *  interaction time. */
   layout(): { narrow: boolean; coarse: boolean };
 
   /** Switch the live terminal to a session. tabs binds the renderer to the