@cplieger/web-terminal-ui 3.4.5 → 4.0.0

package/src/features/tabs/model.ts

@@ -0,0 +1,334 @@
+// tabs/model.ts — the session MODEL half of the tabs feature: the wire type,
+// the per-tab record, the session REST client, the close-tombstone set, and the
+// input-derived-title state machine. No DOM, no chrome, no kernel context —
+// everything here is factory/pure and unit-testable in isolation. The chrome
+// halves are strip.ts (desktop) and switcher.ts (mobile); index.ts wires all
+// three over the kernel context.
+
+import type { LineStore } from "@cplieger/web-terminal-engine";
+import type { SessionInfo } from "@cplieger/web-terminal-engine";
+import type { TabHandle } from "../../kernel/types.js";
+
+// One session's wire shape (SessionInfo) is the ENGINE's exported type — the
+// same repo as the Go terminal.SessionInfo it mirrors, so the cross-language
+// contract has one home. Type-only import: erases at compile, no runtime dep.
+export type { SessionInfo };
+
+// The server-side status of a session whose process has exited (mirrors the
+// engine's terminal.StatusExited). Such a session is viewable history — its
+// final screen replays and the kernel shows "Session ended" — but it can never
+// produce output again, so session selection prefers live sessions everywhere.
+export const STATUS_EXITED = "exited";
+
+// localStorage key for the last active session id, so a page reload reopens the
+// tab the user left on rather than always defaulting to the oldest one.
+export const ACTIVE_TAB_KEY = "wt-active-session";
+
+// One-time "swipe to switch" hint, remembered across loads.
+export const SWIPE_HINT_KEY = "wt-swipe-hint-seen";
+
+export interface Tab {
+  id: string;
+  /** 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). */
+  title: string;
+  /** The computed, de-duplicated label actually shown in the chrome. */
+  display: string;
+  createdAt: string;
+  store: LineStore;
+  el: HTMLElement;
+  label: HTMLElement;
+  dot: HTMLElement;
+  aria: TabHandle;
+  scrollTop: number;
+  following: boolean;
+  /** Sticky: true once this session emitted a genuine activity signal (OSC 9;4).
+   *  Its activity dot is shown only while true; a session that never reports
+   *  activity (a plain shell) keeps a clean, dot-less tab. Fed from the server's
+   *  reportsActivity via applyStatus. */
+  reports: boolean;
+  /** A fallback title derived from the LAST non-empty line the user submitted
+   *  into this tab (updated on every Enter). Used only when the process sets no
+   *  window title of its own: the OSC 0/2 title (`title` above) takes precedence
+   *  when present and keeps updating, and this is what the tab reads as when it
+   *  does not — a plain shell with no PROMPT_COMMAND title, or kiro-cli with its
+   *  cwd-only title disabled. Undefined until the first non-empty submission; see
+   *  baseLabel. */
+  derived?: string;
+  /** The persisted client title reported by the server (its `clientTitle` wire
+   *  field): the last derived title pushed via PUT .../title, surviving reloads.
+   *  In `preferInputTitle` mode this is the reload-recovery source (the live
+   *  `derived` is lost on reload, and `title` is the unreliable OSC value there).
+   *  In the default mode it is the lowest-priority fallback after title/derived. */
+  clientTitle?: string | undefined;
+}
+
+/** baseLabel is a tab's label before de-duplication. Preference order: the
+ *  process window title (OSC 0/2, e.g. a shell's PROMPT_COMMAND title), which
+ *  takes precedence whenever the program sets one and keeps updating as it
+ *  changes (the status SSE re-pushes it); then a fallback derived from the last
+ *  line the user submitted, for a program that sets no title (a bare shell, or
+ *  kiro-cli with its cwd-only title disabled); then a plain "New tab".
+ *  fallback=true marks that last case so relabelAll leaves untitled tabs as
+ *  "New tab" with no numeric suffix.
+ *
+ *  preferInputTitle (agent shell with an unreliable OSC title): show the live
+ *  submitted line, then the persisted client title on reload — the process OSC
+ *  `title` is ignored. Default: OSC title first, then the live derived line,
+ *  then the persisted client title (the latter two are the "latest user
+ *  message" fallback when the program sets no OSC title). */
+export function baseLabel(
+  tab: Tab,
+  preferInputTitle: boolean,
+): { text: string; fallback: boolean } {
+  const derived = tab.derived?.trim() ?? "";
+  const persisted = tab.clientTitle?.trim() ?? "";
+  const real = preferInputTitle ? derived || persisted : tab.title.trim() || derived || persisted;
+  return real ? { text: real, fallback: false } : { text: "New tab", fallback: true };
+}
+
+/** The session REST client (GET/POST/DELETE /api/sessions + PUT .../title),
+ *  bound to an apiBase. Every call is timeout-bounded: fetch has no default
+ *  timeout, and a stalled-but-open server would otherwise leave a bootstrap
+ *  list/create await pending forever (the old permanent-loading-overlay wedge;
+ *  under the v4 session-owner contract the kernel would eventually see nothing,
+ *  but a bounded call recovers into the retry chrome MUCH sooner). */
+export interface SessionAPI {
+  list(): Promise<SessionInfo[]>;
+  create(): Promise<SessionInfo>;
+  close(id: string): Promise<void>;
+  /** Best-effort and fire-and-forget: a failure never disrupts the terminal —
+   *  the locally-derived title still displays, it just is not persisted. */
+  setTitle(id: string, title: string): Promise<void>;
+}
+
+const SESSION_API_TIMEOUT_MS = 15000;
+
+export function createSessionAPI(apiBase: string): SessionAPI {
+  return {
+    async list(): Promise<SessionInfo[]> {
+      const r = await fetch(apiBase, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(SESSION_API_TIMEOUT_MS),
+      });
+      if (!r.ok) {
+        throw new Error(`web-terminal-ui: session list failed (${String(r.status)})`);
+      }
+      const data: unknown = await r.json();
+      // A 200 with a non-array body -- a proxy error object, or a Go server
+      // marshaling a nil session slice as JSON `null` -- must not reach the
+      // bootstrap's `sessions.length` / `for...of` (or the poll's `list.map`)
+      // uncaught. Reject a non-array so the callers' existing catch paths
+      // recover (bootstrap -> [], poll -> skip the tick).
+      if (!Array.isArray(data)) {
+        throw new Error("web-terminal-ui: session list returned a non-array body");
+      }
+      return data as SessionInfo[];
+    },
+    async create(): Promise<SessionInfo> {
+      const r = await fetch(apiBase, {
+        method: "POST",
+        signal: AbortSignal.timeout(SESSION_API_TIMEOUT_MS),
+      });
+      if (!r.ok) {
+        throw new Error(`web-terminal-ui: session create failed (${String(r.status)})`);
+      }
+      return (await r.json()) as SessionInfo;
+    },
+    async close(id: string): Promise<void> {
+      const r = await fetch(`${apiBase}/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+        signal: AbortSignal.timeout(SESSION_API_TIMEOUT_MS),
+      });
+      if (!r.ok) {
+        throw new Error(`web-terminal-ui: session close failed (${String(r.status)})`);
+      }
+    },
+    // Persist the input-derived tab title server-side so it survives a page
+    // reload and shows on other devices. The engine stores it as the session's
+    // fallback title and uses it only when the program emits no OSC title.
+    async setTitle(id: string, title: string): Promise<void> {
+      try {
+        await fetch(`${apiBase}/${encodeURIComponent(id)}/title`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ title }),
+          signal: AbortSignal.timeout(SESSION_API_TIMEOUT_MS),
+        });
+      } catch {
+        /* best-effort persistence; ignore network/timeout errors */
+      }
+    },
+  };
+}
+
+/** Close tombstones: ids the user closed within the TTL, 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 re-adopt (flash back) the
+ *  closed tab. */
+export interface Tombstones {
+  add(id: string): void;
+  /** True while `id` is tombstoned (within the TTL). A hit past the TTL clears
+   *  the entry and reports false (the adopt may proceed). */
+  active(id: string): boolean;
+}
+
+const CLOSE_TOMBSTONE_MS = 15000;
+
+export function createTombstones(ttlMs: number = CLOSE_TOMBSTONE_MS): Tombstones {
+  const recentlyClosed = new Map<string, number>();
+  return {
+    add(id: string): void {
+      const now = Date.now();
+      // Sweep entries whose window already elapsed (active() treats them as
+      // untombstoned anyway) so the map cannot grow without bound over a long
+      // session of opens/closes; then record this close.
+      for (const [k, t] of recentlyClosed) {
+        if (now - t >= ttlMs) {
+          recentlyClosed.delete(k);
+        }
+      }
+      recentlyClosed.set(id, now);
+    },
+    active(id: string): boolean {
+      const closedAt = recentlyClosed.get(id);
+      if (closedAt === undefined) {
+        return false;
+      }
+      if (Date.now() - closedAt < ttlMs) {
+        return true;
+      }
+      recentlyClosed.delete(id);
+      return false;
+    },
+  };
+}
+
+// A generous storage bound for the fallback (input-derived) title. The tab
+// label truncates it visually with max-width + ellipsis in EVERY view — the
+// desktop strip, the mobile active bar, and the mobile list — so this is only a
+// guard against storing a huge paste, not a display cut.
+const MAX_DERIVED = 512;
+
+/** The input-derived-title state machine: a tiny line editor over the kernel's
+ *  accepted outbound bytes. It tracks the current input line (handling
+ *  backspace and skipping the escape sequences arrow keys and bracketed paste
+ *  emit) and reports every non-empty submitted line through `submit`. The
+ *  caller owns what a submission means (update the active tab's derived title,
+ *  persist it, refresh chrome). Best-effort: an odd editing sequence just
+ *  yields no derived title. */
+export interface InputTitleDeriver {
+  /** Feed one accepted outbound byte chunk (a ctx.registerInputObserver hook). */
+  observe(bytes: Uint8Array): void;
+  /** Drop the partial line (a tab switch: a line typed in the old tab must not
+   *  carry over). */
+  reset(): void;
+}
+
+export function createInputTitleDeriver(submit: (line: string) => void): InputTitleDeriver {
+  let lineBytes: number[] = [];
+  let escState = 0; // 0 normal, 1 saw ESC, 2 in CSI, 3 in SS3 (one more byte)
+  let csiParams = ""; // accumulated CSI parameter bytes, to spot paste guards
+  let inPaste = false; // inside a bracketed paste (ESC[200~ … ESC[201~)
+  return {
+    reset(): void {
+      lineBytes = [];
+      escState = 0;
+      csiParams = "";
+      inPaste = false;
+    },
+    observe(bytes: Uint8Array): void {
+      for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        if (b === undefined) {
+          continue;
+        }
+        if (escState === 1) {
+          escState = b === 0x5b ? 2 : b === 0x4f ? 3 : 0; // ESC [ = CSI, ESC O = SS3
+          continue;
+        }
+        if (escState === 2) {
+          if (b >= 0x40 && b <= 0x7e) {
+            // CSI final byte. Recognize the bracketed-paste guards ESC[200~
+            // (start) and ESC[201~ (end) so embedded newlines in a pasted,
+            // often multi-line, message are not read as line submissions.
+            if (b === 0x7e) {
+              if (csiParams === "200") {
+                inPaste = true;
+              } else if (csiParams === "201") {
+                inPaste = false;
+              }
+            }
+            csiParams = "";
+            escState = 0; // CSI final byte
+          } else if (b >= 0x30 && b <= 0x3f) {
+            csiParams += String.fromCharCode(b); // parameter byte (digits, ; ? etc.)
+          }
+          continue;
+        }
+        if (escState === 3) {
+          escState = 0; // SS3 final byte
+          continue;
+        }
+        if (b === 0x1b) {
+          escState = 1; // ESC: start of an escape sequence
+        } else if (b === 0x0d || b === 0x0a) {
+          // A newline is a line SUBMIT only when it terminates the input. It is
+          // folded to a single space (keeping the current line going) when it is
+          // instead a paste-internal break, so a multi-line message becomes one
+          // logical line whose title reflects its START rather than only its
+          // LAST line. Two cases fold:
+          //   - inside a bracketed paste (ESC[200~ … ESC[201~), and
+          //   - a newline FOLLOWED by more printable input in this SAME chunk:
+          //     a human pressing Enter sends the newline as the end of its own
+          //     input event, whereas a paste (even one sent WITHOUT bracketed-
+          //     paste guards — e.g. an agent shell like kiro-cli that keeps a
+          //     pasted multi-line message as one prompt) delivers
+          //     text + newline + text together, so trailing content marks the
+          //     newline as a soft break, not a submit. Without this, such a
+          //     paste left only its last line as the title (the reported
+          //     "the title cut off the start of my message").
+          let softBreak = inPaste;
+          if (!softBreak) {
+            for (let j = i + 1; j < bytes.length; j++) {
+              const nb = bytes[j];
+              if (nb !== undefined && nb >= 0x20) {
+                softBreak = true;
+                break;
+              }
+            }
+          }
+          if (softBreak) {
+            if (lineBytes.length > 0 && lineBytes[lineBytes.length - 1] !== 0x20) {
+              lineBytes.push(0x20);
+            }
+            continue;
+          }
+          const line = new TextDecoder().decode(new Uint8Array(lineBytes)).trim();
+          lineBytes = [];
+          // Every non-empty submitted line updates the fallback title (the
+          // last one wins); a leading "/" counts, since it is a valid shell
+          // command path.
+          if (line) {
+            submit(line.slice(0, MAX_DERIVED));
+          }
+        } else if (b === 0x7f || b === 0x08) {
+          // Backspace: drop one codepoint (pop UTF-8 continuation bytes + lead).
+          while (lineBytes.length > 0) {
+            const last = lineBytes[lineBytes.length - 1];
+            if (last === undefined || (last & 0xc0) !== 0x80) {
+              break;
+            }
+            lineBytes.pop();
+          }
+          lineBytes.pop();
+        } else if (b === 0x03) {
+          lineBytes = []; // Ctrl-C: cancel the current line
+        } else if (b >= 0x20) {
+          lineBytes.push(b); // printable ASCII or a UTF-8 byte
+        }
+      }
+    },
+  };
+}

package/src/features/tabs/strip.ts

@@ -0,0 +1,101 @@
+// tabs/strip.ts — the desktop tab strip's chrome vocabulary: the shared SVG
+// glyphs, the one chip-content builder every chip site reuses, the strip tab
+// template, the shared control markup factories, the status-dot painter, and
+// the required-descendant picker. Everything here is closure-free markup +
+// tiny pure helpers; element construction with event wiring stays in index.ts
+// (it closes over the feature state). The mobile chrome templates live in
+// switcher.ts; the session model in model.ts.
+
+// The +/x/keyboard glyphs are inline SVG (not font glyphs) so they center
+// exactly in their flex-centered buttons and stay symmetric regardless of the UI
+// font's metrics. Each is defined ONCE here and shared by every chip site and
+// control (rather than duplicated across the desktop and mobile markup).
+const CLOSE_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6 18 18M18 6 6 18"/></svg>`;
+const NEW_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>`;
+const KB_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="4" width="16" height="16" rx="3.5"/><path d="M15 15 9.5 9.5M9.5 13V9.5H13"/></svg>`;
+// Two-overlapping-windows glyph for the mobile switcher's dedicated open/close
+// button: the browser-style "tab switcher" icon, more recognisable than the
+// prior swap-arrows (which read like a keyboard Tab key). A latest-wins
+// background-tab notification dot rides on it (see switchButtonHTML). Same
+// viewBox + stroke=currentcolor treatment as the others.
+const SWITCH_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="8" width="13" height="13" rx="2"/><path d="M8 8V6a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-3"/></svg>`;
+
+// chipContent is the ONE builder for a tab chip's content — a status dot, a
+// label, and a close (x) — shared by all three chip sites: the desktop strip
+// (.wt-tab), the mobile active row (.wt-switcher-current), and each expanded
+// mobile list row (.wt-switcher-row). Each site passes its OWN class set (never
+// renamed) so every existing selector — and thus all CSS and all tests — still
+// matches. The one structural difference is WHERE the close sits: the desktop
+// chip nests it flat inside .wt-tab, while the two mobile chips place it as a
+// sibling of the select/swipe button (a button can't nest in a button). So the
+// builder returns two fragments — the dot+label pair and the close — that each
+// site drops into its own structure.
+export function chipContent(v: { dot: string; label: string; close: string; closeAttr?: string }): {
+  dotLabel: string;
+  close: string;
+} {
+  return {
+    dotLabel:
+      `<span class="${v.dot} wt-status-dot" aria-hidden="true"></span>` +
+      `<span class="${v.label}"></span>`,
+    close: `<button type="button" class="${v.close}" aria-label="Close terminal"${v.closeAttr ?? ""}>${CLOSE_SVG}</button>`,
+  };
+}
+
+// The ONE "+" (new-terminal) and keyboard button markup factories, shared by
+// the desktop strip and the mobile switcher — only the class set differs. These
+// build the markup; element construction + event wiring live in makeNewButton /
+// makeKbButton (index.ts), which close over create() and the key-grid toggle.
+export function newButtonHTML(cls: string): string {
+  return `<button type="button" class="${cls}" aria-label="New terminal">${NEW_SVG}</button>`;
+}
+export function kbButtonHTML(cls: string): string {
+  return `<button type="button" class="${cls}" aria-label="Keyboard keys" aria-expanded="false" hidden>${KB_SVG}</button>`;
+}
+// The mobile switcher's dedicated open/close button. It toggles the tab list and
+// carries a latest-wins notification dot (a child span) — amber when a background
+// terminal needs input, green when a background turn finished — cleared when the
+// list opens. Only the mobile switcher builds it (element construction + event
+// wiring live in makeSwitchButton in index.ts); the desktop strip already shows
+// every tab's own status dot, so it needs no aggregate cue.
+export function switchButtonHTML(cls: string): string {
+  return (
+    `<button type="button" class="${cls}" aria-label="Open tab switcher">${SWITCH_SVG}` +
+    `<span class="wt-status-dot wt-switcher-switch-dot" aria-hidden="true"></span></button>`
+  );
+}
+
+// Desktop strip chip: dot + label + close all flat inside .wt-tab (the whole
+// chip is the click/switch target; the close is a nested button). tabindex="-1"
+// keeps the close out of the tab order.
+const TAB_CHIP = chipContent({
+  dot: "wt-tab-dot",
+  label: "wt-tab-label",
+  close: "wt-tab-close",
+  closeAttr: ' tabindex="-1"',
+});
+export const TAB_HTML = `
+<div class="wt-tab">
+  ${TAB_CHIP.dotLabel}
+  ${TAB_CHIP.close}
+</div>`;
+
+/** paintStatusDot applies a status dot's two orthogonal bits: data-status drives
+ *  its appearance (idle / working / done / input / exited via CSS), and the
+ *  .wt-reports class controls its visibility — the dot is hidden by default and
+ *  shown only once the session has reported activity (OSC 9;4 progress or a
+ *  classified OSC 9 notification), so a plain shell's tabs stay clean and
+ *  label-only while an agent's light up. */
+export function paintStatusDot(el: HTMLElement, status: string, reports: boolean): void {
+  el.dataset["status"] = status || "idle";
+  el.classList.toggle("wt-reports", reports);
+}
+
+/** pick returns a required descendant element or throws (static chrome only). */
+export function pick(root: ParentNode, selector: string): HTMLElement {
+  const el = root.querySelector<HTMLElement>(selector);
+  if (!el) {
+    throw new Error(`web-terminal-ui: tabs chrome missing ${selector}`);
+  }
+  return el;
+}

package/src/features/tabs/switcher.ts

@@ -0,0 +1,129 @@
+// tabs/switcher.ts — the mobile bottom-switcher's chrome vocabulary: its
+// templates, the swipe/flick gesture constants, and the closure-free row
+// enter/leave animations. The gesture STATE MACHINE (axis lock, live preview,
+// the release reel) stays in index.ts: it mutates drag state shared with the
+// switch/expand paths, so extracting it would spread one interaction across two
+// files. The desktop chrome vocabulary lives in strip.ts; the session model in
+// model.ts.
+
+import { chipContent } from "./strip.js";
+
+// Swipe recognition on the mobile switcher bar: a mostly-horizontal drag past
+// this distance switches; a near-stationary release is a tap (opens overview).
+export const SWIPE_MIN_PX = 40;
+// Movement (px) before an in-progress bar drag commits to a horizontal
+// (tab-switch preview) or vertical (expand/collapse) axis.
+export const AXIS_LOCK_PX = 8;
+// Flick-to-commit thresholds (from @use-gesture's drag defaults, MIT): a release
+// counts as a flick when the gesture was quick, fast, and travelled enough, so a
+// short fast swipe commits the switch/expand even below the halfway distance.
+export const SWIPE_VELOCITY = 0.5; // px/ms at release
+export const SWIPE_DURATION = 250; // ms, whole-gesture cap for a flick
+// If the finger paused longer than this before lifting, the release velocity is
+// stale (pointerup usually repeats the last pointermove position -> reads ~0),
+// so ignore it and commit by distance instead (@use-gesture issue #332).
+export const VELOCITY_STALE_MS = 32;
+// Live drag preview: while an open list is being swiped, it peeks in the swipe
+// direction by this fraction of the finger's horizontal travel, capped at this
+// many pixels — a hint of the coming rotation, not the full shift (the incoming
+// row only appears on release, so a large move looked wrong). The release reel
+// continues from wherever the peek left the rows.
+export const PREVIEW_DRAG_RATIO = 0.1;
+export const PREVIEW_PEEK_MAX = 10;
+
+// Mobile bottom bar. One element, two parts stacked in a column: the always-
+// visible bar row (active tab as a tap/swipe surface + keyboard + "+") on top,
+// and a list of the OTHER tabs BELOW it. On swipe-up / tap the whole bar slides
+// up and the list fills in beneath it (down to the safe area); swipe-down /
+// tap collapses it back to the bottom. Selecting a listed tab swaps it into the
+// active row. This replaces the old separate modal overview sheet ("one element"
+// per the user): the bar itself lifts rather than opening a distinct surface.
+// The bar is the FIRST child and the list the SECOND: the switcher is bottom-
+// anchored, so a column with the list last grows the container upward, lifting
+// the bar and revealing the list below it (DOM order = visual order top-to-bottom).
+//   - .wt-switcher-current-wrap: the active-tab row — a select/swipe surface
+//     (.wt-switcher-current with dot + label) plus a close (x) overlaid at the
+//     right, mirroring the listed rows. No "n / m" counter: the list below is a
+//     rotating circular queue, so an absolute position number is meaningless.
+//   - The keyboard button (.wt-switcher-kb, opens the key grid above the bar,
+//     only wired + shown when a keyboardToggle feature is provided) and the
+//     accent "+" (.wt-switcher-new, spawns a terminal) are appended to the bar
+//     row from the shared factories in index.ts (see makeKbButton / makeNewButton).
+const CURRENT_CHIP = chipContent({
+  dot: "wt-switcher-dot",
+  label: "wt-switcher-label",
+  close: "wt-switcher-current-close wt-btn",
+});
+export const SWITCHER_HTML = `
+<div class="wt-switcher" role="group" aria-label="Terminal tabs">
+  <div class="wt-switcher-bar">
+    <div class="wt-switcher-current-wrap">
+      <button type="button" class="wt-switcher-current" aria-haspopup="true" aria-expanded="false">
+        <span class="wt-switcher-current-inner">${CURRENT_CHIP.dotLabel}</span>
+      </button>
+      ${CURRENT_CHIP.close}
+    </div>
+  </div>
+  <ul class="wt-switcher-list" role="list"></ul>
+</div>`;
+
+// One row per OTHER tab in the expanded list: a stretched select target (dot +
+// label) with the close (x) laid inside it at the right (two buttons can't nest,
+// so the x is a sibling overlapping the select's reserved right padding).
+const ROW_CHIP = chipContent({
+  dot: "wt-switcher-row-dot",
+  label: "wt-switcher-row-label",
+  close: "wt-switcher-row-close wt-btn",
+});
+export const SWITCHER_ROW_HTML = `
+<li class="wt-switcher-row">
+  <button type="button" class="wt-switcher-row-select">${ROW_CHIP.dotLabel}</button>
+  ${ROW_CHIP.close}
+</li>`;
+
+// animateRowIn / animateRowOut give a listed tab an enter / leave motion:
+// the row's own max-height grows from 0 (fading in) on add, and collapses
+// to 0 (fading out, then removed) on close. The flex list's height follows
+// the row, so adding/closing a tab animates the tray height rather than
+// snapping. Inline-driven (cleared when done); the caller gates motion.
+const ROW_ANIM_MS = 220;
+const ROW_ANIM_EASE = "cubic-bezier(0.2, 0, 0, 1)";
+
+export function animateRowIn(row: HTMLElement): void {
+  const h = row.getBoundingClientRect().height;
+  if (h <= 0) {
+    return;
+  }
+  row.style.overflow = "hidden";
+  row.style.transition = "none";
+  row.style.maxHeight = "0";
+  row.style.opacity = "0";
+  requestAnimationFrame(() => {
+    row.style.transition = `max-height ${String(ROW_ANIM_MS)}ms ${ROW_ANIM_EASE}, opacity ${String(ROW_ANIM_MS)}ms ${ROW_ANIM_EASE}`;
+    row.style.maxHeight = `${String(Math.ceil(h))}px`;
+    row.style.opacity = "1";
+  });
+  window.setTimeout(() => {
+    row.style.transition = "";
+    row.style.maxHeight = "";
+    row.style.opacity = "";
+    row.style.overflow = "";
+  }, ROW_ANIM_MS + 60);
+}
+
+export function animateRowOut(row: HTMLElement): void {
+  const h = row.getBoundingClientRect().height;
+  row.style.overflow = "hidden";
+  row.style.pointerEvents = "none";
+  row.style.transition = "none";
+  row.style.maxHeight = `${String(Math.ceil(h))}px`;
+  row.style.opacity = "1";
+  requestAnimationFrame(() => {
+    row.style.transition = `max-height ${String(ROW_ANIM_MS)}ms ${ROW_ANIM_EASE}, opacity ${String(ROW_ANIM_MS)}ms ${ROW_ANIM_EASE}`;
+    row.style.maxHeight = "0";
+    row.style.opacity = "0";
+  });
+  window.setTimeout(() => {
+    row.remove();
+  }, ROW_ANIM_MS + 60);
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
   TerminalHandle,
   TerminalFeature,
   FeatureInstance,
+  SessionOwnerRegistration,
   TerminalContext,
   TerminalEvents,
   RegionName,

package/src/kernel/a11y.ts

@@ -25,6 +25,11 @@ export interface Announcer {
   destroy(): void;
 }
 
+/** Delay before a cleared live region is re-set with the new message (ms).
+ *  Long enough for assistive tech to register the clear and the set as two
+ *  distinct mutations (a sub-frame gap is not). */
+const REANNOUNCE_DELAY_MS = 100;
+
 /** Build the single pair of live regions inside root. */
 export function createAnnouncer(root: HTMLElement): Announcer {
   const polite = document.createElement("div");
@@ -37,17 +42,37 @@ export function createAnnouncer(root: HTMLElement): Announcer {
   hideVisually(assertive);
   root.append(polite, assertive);
 
+  // Pending re-set timers, one per region, so a rapid follow-up announcement
+  // replaces the pending one instead of interleaving with it.
+  const timers = new Map<HTMLElement, ReturnType<typeof setTimeout>>();
+
   function announce(message: string, politeness: "polite" | "assertive" = "polite"): void {
     const el = politeness === "assertive" ? assertive : polite;
-    // Clear then set on the next frame so a repeat of the same message is
-    // re-announced (screen readers ignore an unchanged live-region value).
+    // Clear then re-set after a short (~100ms) TIMER so a repeat of the same
+    // message is re-announced: screen readers ignore an unchanged live-region
+    // value, and a sub-frame gap (the previous requestAnimationFrame
+    // approach, ~16ms) is too fast for some assistive tech to register two
+    // distinct mutations — the same rationale ui-primitives' announce()
+    // documents for its shared region.
     el.textContent = "";
-    requestAnimationFrame(() => {
-      el.textContent = message;
-    });
+    const pending = timers.get(el);
+    if (pending !== undefined) {
+      clearTimeout(pending);
+    }
+    timers.set(
+      el,
+      setTimeout(() => {
+        timers.delete(el);
+        el.textContent = message;
+      }, REANNOUNCE_DELAY_MS),
+    );
   }
 
   function destroy(): void {
+    for (const t of timers.values()) {
+      clearTimeout(t);
+    }
+    timers.clear();
     polite.remove();
     assertive.remove();
   }

package/src/kernel/conn-state.ts

@@ -33,6 +33,11 @@ export interface ConnStateMachine {
   closed(): void;
   /** Server restarted (epoch mismatch); recent input may be lost. */
   restarted(): void;
+  /** The active session's process exited (the engine's definitive 4001
+   *  close). Unlike closed(), this is not a failure to escalate or retry:
+   *  the state shows immediately and persists until open() (a switch to a
+   *  live session) replaces it. */
+  ended(): void;
   /** First screen frame rendered: the loading overlay is done, so the banner
    *  may show reconnect state from here on. */
   setLoaded(): void;
@@ -54,9 +59,14 @@ export function createConnState(opts: {
 
   function emit(): void {
     // Suppress transient states until the initial load is over (the loading
-    // overlay owns the screen), except "offline" once the initial-failure limit
-    // is reached. connectionBanner renders "open" as hidden.
-    if (!loaded && !(state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT)) {
+    // 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.
+    const passesLoadingGate =
+      state === "ended" || (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
+    if (!loaded && !passesLoadingGate) {
       opts.onState("open"); // nothing to show yet
       return;
     }
@@ -113,6 +123,13 @@ export function createConnState(opts: {
         }
       }, RESTARTED_CLEAR_MS);
     },
+    ended(): void {
+      // A definitive end, not a failure: reset the failure streak so a later
+      // reconnect to a LIVE session starts its escalation ladder from zero,
+      // and show the state immediately (no grace delay — nothing is retrying).
+      consecutiveFailures = 0;
+      setState("ended", 0);
+    },
     setLoaded(): void {
       loaded = true;
     },