@cplieger/web-terminal-ui 7.3.2 → 8.0.0

package/src/features/tabs/strip.ts

@@ -1,18 +1,11 @@
-// tabs/strip.ts — the desktop tab strip's chrome vocabulary: the reorder-preview
-// constants, 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 and its gesture constants live in switcher.ts; the session model in
-// model.ts.
+// Closure-free markup and pure helpers only; element construction with event
+// wiring stays in index.ts, where it closes over the feature state.
 
 // The status vocabulary itself (which statuses reveal a dot, and how each one is
 // worded for a human) lives in the DOM-free model, so the painters here and the
 // accessible names index.ts builds read one definition.
 import { activityPhrase, normalizeActivity, statusPhrase, statusRevealsDot } from "./model.js";
 
-// --- Reorder preview -------------------------------------------------------
 // Every chip in this strip is the same width (see .wt-tab in 30-tabs.css: a
 // definite 300px with flex-grow 0, so a title changes the label and never the
 // box). That is what makes a reorder hard to read: the chip a release would
@@ -22,33 +15,18 @@ import { activityPhrase, normalizeActivity, statusPhrase, statusRevealsDot } fro
 // the same split switcher.ts keeps for the mobile swipe.
 
 /** How long (ms) the pointer must have been un-moved before a stationary `dragover` is
- *  believed as "stopped".
- *
- *  This is the number that decides how fast the slot opens, and it is small because a
- *  `dragover` at an UNCHANGED position is positive evidence of rest — far better
- *  evidence than the absence of events, which is all the fallback below has. The drag
- *  loop keeps delivering events while the pointer is held still, so a genuinely stopped
- *  pointer announces itself; this only filters the coincidence where one event of a
- *  sweep happens to land within REORDER_MOVE_EPS_PX of the previous one (a direction
- *  reversal, or a frame where the motion was almost entirely vertical). */
+ *  believed as "stopped". Small, because a `dragover` at an UNCHANGED position is
+ *  positive evidence of rest (the drag loop keeps delivering events while the pointer
+ *  is held still); this only filters the coincidence where one event of a sweep lands
+ *  within REORDER_MOVE_EPS_PX of the previous one. */
 export const REORDER_STILL_MS = 50;
 
 /** Fallback guard (ms): commit the pending slot this long after the last MOVEMENT, for
- *  the case where `dragover` stops arriving altogether and no stationary event ever
- *  confirms the stop.
- *
- *  **Its floor is set by the platform, not by taste, and this is the timer that floor
- *  applies to.** HTML5 drag-and-drop only guarantees a `dragover` every 350ms — the drag
- *  loop runs on that cadence, not per mouse movement — so a guard at or below it can
- *  expire BETWEEN two events of a fast sweep, and the strip then commits every slot the
- *  pointer crosses. Measured in production: at 120ms a quick pass over five tabs moved
- *  all five.
- *
- *  A pure quiet-window design has to make this ONE number carry both jobs, which is why
- *  it could not be shortened — the same timer that decides responsiveness was the one
- *  that had to out-wait the cadence, so 500ms was safe and felt slow. Splitting rest
- *  DETECTION (the stationary event above) from the no-events NET (here) lets each be
- *  sized for its own job. This one is rarely the deciding signal at all. */
+ *  the case where `dragover` stops arriving altogether. Its floor is the platform's:
+ *  HTML5 drag-and-drop only guarantees a `dragover` every 350ms, so a guard at or
+ *  below it can expire BETWEEN two events of a fast sweep and commit every slot the
+ *  pointer crosses (measured: at 120ms a quick pass over five tabs moved all five).
+ *  Rest DETECTION is the stationary event above, so this net can stay slow. */
 export const REORDER_REST_MS = 450;
 
 /** Movement (px) between two dragover events below which the pointer counts as still.
@@ -57,19 +35,12 @@ export const REORDER_REST_MS = 450;
 export const REORDER_MOVE_EPS_PX = 3;
 
 /** The one transition both preview stages use (the lean, and the slide that
- *  commits it).
- *
- *  --dur-standard and --ease-standard written out as literals. JS-driven motion
- *  in this package does not read tokens back out of the cascade; the switcher's
- *  release reel spells its own transition the same way. Keep the two in step: a
- *  token edit has to be mirrored here by hand.
- *
- *  The property is `translate`, NOT `transform`, and that is load-bearing rather
- *  than stylistic. Declarations from a running CSS animation out-rank every normal
- *  author declaration, inline style included, so a chip in the middle of
- *  `wt-slot-in` or `wt-tab-in` (both animate `transform: scale`) would ignore an
- *  inline `transform` outright and refuse to move. `translate` is a separate
- *  property that composes with `transform` instead of competing for it. */
+ *  commits it): --dur-standard and --ease-standard as literals, since JS-driven
+ *  motion here reads no token back out of the cascade (mirror a token edit by
+ *  hand). The property is `translate`, NOT `transform`: declarations from a
+ *  running CSS animation out-rank inline style, so a chip mid `wt-slot-in` or
+ *  `wt-tab-in` (both animate `transform: scale`) would ignore an inline
+ *  `transform`; `translate` composes with it instead of competing for it. */
 export const REORDER_SHIFT_TRANS = "translate 0.2s cubic-bezier(0.2, 0, 0, 1)";
 
 /** When (ms after the slide starts) the inline transform and transition come off
@@ -103,31 +74,17 @@ const KB_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="4" wi
 // 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, a determinate progress bar, 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.
-//
-// The progress bar rides in the dotLabel fragment rather than taking a per-site
-// class: it is positioned against the chip, not laid out in its flex row, so one
-// class (.wt-progress-bar) styles it everywhere and every chip site gets it for
-// free. It starts `hidden` — a session with no percentage must render NO bar
-// (paintProgress).
-//
-// The secondary activity mark (.wt-activity-mark) rides here for the same reason
-// and takes no per-site class either. It carries NO `hidden` attribute, unlike
-// the bar: `hidden` is display:none, and an element out of layout cannot animate
-// into it. Absence is the absence of `data-activity`, which the CSS answers by
-// cancelling the mark's own footprint (see 30-tabs.css), so a chip with no
-// secondary activity measures exactly as it did before this element existed.
+// Two rectangles side by side, the same glyph whether the split is open or
+// closed: the button's state is its aria-expanded, not its icon.
+const SPLIT_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="5" width="8" height="14" rx="2"/><rect x="13" y="5" width="8" height="14" rx="2"/></svg>`;
+
+/** The ONE builder for a tab chip's content (status dot, label, progress bar,
+ *  close), shared by the strip chip, the mobile active row and each mobile list
+ *  row. Two fragments, because the mobile chips place the close as a SIBLING of
+ *  their button (a button cannot nest in a button). The bar starts `hidden` (no
+ *  percentage renders no bar); the activity mark carries no `hidden`, since an
+ *  element out of layout cannot animate into it, and its absence is the absence
+ *  of `data-activity`, which the CSS answers by cancelling its footprint. */
 export function chipContent(v: { dot: string; label: string; close: string; closeAttr?: string }): {
   dotLabel: string;
   close: string;
@@ -152,6 +109,12 @@ export function newButtonHTML(cls: string): string {
 export function kbButtonHTML(cls: string): string {
   return `<button type="button" class="${cls}" aria-label="Keyboard keys" aria-expanded="false" hidden>${KB_SVG}</button>`;
 }
+/** The split-view toggle: a stable label with `aria-expanded` as its state, the
+ *  keyboard button's pattern, so a screen reader hears the change on the focused
+ *  button after a keyboard toggle. */
+export function splitButtonHTML(cls: string): string {
+  return `<button type="button" class="${cls}" aria-label="Split view" aria-expanded="false">${SPLIT_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
@@ -180,22 +143,12 @@ export const TAB_HTML = `
   ${TAB_CHIP.close}
 </div>`;
 
-/** paintStatusDot applies a status dot's three orthogonal bits: data-status
- *  drives its appearance (idle / working / warning / failed / done / input /
- *  exited / crashed via CSS), the .wt-reports class controls its visibility, and
- *  `title` gives it a hover tooltip naming the state — the dots are decoration
- *  (aria-hidden), and a colour vocabulary that grew to eight states needs a way
- *  to be read rather than memorised. The tooltip wording is statusPhrase, the
- *  same source the tab's accessible name uses, so hover text and announced text
- *  cannot drift.
- *
- *  Visibility: the dot is hidden by default and shown 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. The
- *  reveal is FLOORED by the status itself (statusRevealsDot) for the states that
- *  are self-evidently news — a plain shell that crashes never reported activity
- *  in its life, and hiding its red dot would hide the only signal it ever
- *  produced. */
+/** A status dot's three orthogonal bits: data-status drives its appearance, the
+ *  .wt-reports class its visibility, and `title` a tooltip worded by statusPhrase,
+ *  the source the tab's accessible name uses, so hover and announced text cannot
+ *  drift. Hidden until the session reports activity, so a plain shell's tabs stay
+ *  label-only; FLOORED by the status itself for the states that are news on their
+ *  own, since a plain shell that crashes never reported activity in its life. */
 export function paintStatusDot(el: HTMLElement, status: string, reports: boolean): void {
   const value = status || "idle";
   el.dataset["status"] = value;
@@ -203,16 +156,11 @@ export function paintStatusDot(el: HTMLElement, status: string, reports: boolean
   el.title = statusPhrase(value);
 }
 
-/** paintActivityMark applies the secondary mark's two bits: data-activity drives
- *  its appearance (working / waiting / input via CSS) and `title` gives it a
- *  hover tooltip, worded by activityPhrase so hover text and announced text
- *  cannot drift. No state REMOVES the attribute, which is what collapses the
- *  mark's footprint to zero.
- *
- *  The reveal is the mark's OWN state, deliberately not the status dot's
- *  reportsActivity gate: a background run is a fact about the session that is
- *  independent of whether its program ever spoke OSC 9, which is the whole point
- *  of a second mark. */
+/** The secondary mark's two bits: data-activity drives its appearance and `title`
+ *  a tooltip worded by activityPhrase. No state REMOVES the attribute, which is
+ *  what collapses the mark's footprint to zero. The reveal is the mark's OWN
+ *  state, not the status dot's reportsActivity gate: a background run is a fact
+ *  independent of whether the program ever spoke OSC 9. */
 export function paintActivityMark(el: HTMLElement, state: string, count: number): void {
   const phrase = activityPhrase(state, count);
   if (phrase === "") {

package/src/features/tabs/switcher.ts

@@ -1,11 +1,8 @@
-// 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.
+// The swipe state machine (axis lock, live preview, the release reel) stays in
+// index.ts: it mutates drag state shared with the switch and expand paths, so
+// extracting it would spread one interaction across two files.
 
+import { windowOf } from "../../kernel/realm.js";
 import { chipContent } from "./strip.js";
 
 // Swipe recognition on the mobile switcher bar: a mostly-horizontal drag past
@@ -31,24 +28,11 @@ export const VELOCITY_STALE_MS = 32;
 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).
+// Mobile bottom bar: one element, the always-visible bar row (active tab as a
+// tap/swipe surface, keyboard, "+") FIRST and the list of the other tabs SECOND.
+// The switcher is bottom-anchored, so a column with the list last grows upward
+// on swipe-up and lifts the bar to reveal the list beneath it. No "n / m"
+// counter: the list is a rotating circular queue, so a position is meaningless.
 const CURRENT_CHIP = chipContent({
   dot: "wt-switcher-dot",
   label: "wt-switcher-label",
@@ -85,45 +69,83 @@ export const SWITCHER_ROW_HTML = `
 // 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.
+// snapping. Inline-driven (cleared when done); the caller gates motion, and
+// its `signal` ends a motion still running when the owner goes away.
 const ROW_ANIM_MS = 220;
 const ROW_ANIM_EASE = "cubic-bezier(0.2, 0, 0, 1)";
 
-export function animateRowIn(row: HTMLElement): void {
+/** The frame that writes the "to" state and the timer that ends the motion,
+ *  both cancelled by `signal`. The timer also cancels the frame: a background
+ *  tab suspends frames while timers run, and a frame released after `finish()`
+ *  would write the "to" state onto a row nobody owns any more. A motion that
+ *  finished releases its abort listener so a long-lived signal collects nothing. */
+function rowMotion(
+  row: HTMLElement,
+  signal: AbortSignal,
+  toState: () => void,
+  finish: () => void,
+): void {
+  const win = windowOf(row.ownerDocument);
+  const frame = win.requestAnimationFrame(toState);
+  const timer = win.setTimeout(() => {
+    win.cancelAnimationFrame(frame);
+    signal.removeEventListener("abort", cancel);
+    finish();
+  }, ROW_ANIM_MS + 60);
+  const cancel = (): void => {
+    win.cancelAnimationFrame(frame);
+    win.clearTimeout(timer);
+  };
+  signal.addEventListener("abort", cancel, { once: true });
+}
+
+export function animateRowIn(row: HTMLElement, signal: AbortSignal): void {
   const h = row.getBoundingClientRect().height;
-  if (h <= 0) {
+  if (h <= 0 || signal.aborted) {
     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);
+  rowMotion(
+    row,
+    signal,
+    () => {
+      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";
+    },
+    () => {
+      row.style.transition = "";
+      row.style.maxHeight = "";
+      row.style.opacity = "";
+      row.style.overflow = "";
+    },
+  );
 }
 
-export function animateRowOut(row: HTMLElement): void {
+export function animateRowOut(row: HTMLElement, signal: AbortSignal): void {
+  if (signal.aborted) {
+    row.remove();
+    return;
+  }
   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);
+  rowMotion(
+    row,
+    signal,
+    () => {
+      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";
+    },
+    () => {
+      row.remove();
+    },
+  );
 }

package/src/index.ts

@@ -1,16 +1,3 @@
-// @cplieger/web-terminal-ui — the reference touch-first browser UI built on the
-// @cplieger/web-terminal-engine engine.
-//
-// v3 entry: createTerminal(root, { features }) builds a small kernel (display
-// output, hidden textarea, IME, engine wiring, input funnel, connection-state,
-// layout regions) plus opt-in feature modules. Feature bundles live at
-// "@cplieger/web-terminal-ui/presets" (presetSingle / presetTouch /
-// presetTabbed); a consumer that hand-picks features imports them individually.
-//
-// A consumer who wants a different UI depends on @cplieger/web-terminal-engine
-// directly and wires the engine's render/scroll/connection/keyboard modules to
-// their own DOM.
-
 export { createTerminal } from "./kernel/kernel.js";
 export { localScrollbackStorage } from "./kernel/scrollback-storage.js";
 export type { LocalScrollbackStorageOptions } from "./kernel/scrollback-storage.js";
@@ -26,6 +13,19 @@ export type {
   PersistedScrollback,
   ScrollbackPersistence,
   SessionOwnerRegistration,
+  PaneLayoutOwnerRegistration,
+  PaneSide,
+  PaneHandle,
+  ShellContext,
+  AttentionOptions,
+  AttentionState,
+  AttentionReporter,
+  NotificationEvent,
+  NotificationView,
+  Notifier,
+  SplitState,
+  SplitController,
+  ModeReaders,
   TerminalContext,
   TerminalEvents,
   RegionName,

package/src/kernel/a11y.ts

@@ -1,9 +1,10 @@
-// Kernel-owned accessibility primitives (design sections 12, 22.4): one polite
-// and one assertive live region so features never spawn competing aria-live
-// regions, and one tablist/tabpanel controller wired on the kernel's output
-// surface so `tabs` gets the ARIA seam without crossing into kernel-owned DOM.
+// Kernel-owned accessibility primitives: one polite and one assertive live
+// region so features never spawn competing aria-live regions, and one
+// tablist/tabpanel controller wired on the kernel's output surface so `tabs`
+// gets the ARIA seam without crossing into kernel-owned DOM.
 
-import type { TablistController, TabHandle } from "./types.js";
+import type { PaneSide, TablistController, TabHandle } from "./types.js";
+import { windowOf } from "./realm.js";
 
 /** Visually-hidden style applied inline so it holds without external CSS
  *  (tests run without the stylesheet). Standard sr-only clip technique. */
@@ -32,11 +33,13 @@ 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");
+  const doc = root.ownerDocument;
+  const win = windowOf(doc);
+  const polite = doc.createElement("div");
   polite.setAttribute("aria-live", "polite");
   polite.setAttribute("aria-atomic", "true");
   hideVisually(polite);
-  const assertive = document.createElement("div");
+  const assertive = doc.createElement("div");
   assertive.setAttribute("aria-live", "assertive");
   assertive.setAttribute("aria-atomic", "true");
   hideVisually(assertive);
@@ -44,7 +47,7 @@ export function createAnnouncer(root: HTMLElement): Announcer {
 
   // 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>>();
+  const timers = new Map<HTMLElement, number>();
 
   function announce(message: string, politeness: "polite" | "assertive" = "polite"): void {
     const el = politeness === "assertive" ? assertive : polite;
@@ -57,11 +60,11 @@ export function createAnnouncer(root: HTMLElement): Announcer {
     el.textContent = "";
     const pending = timers.get(el);
     if (pending !== undefined) {
-      clearTimeout(pending);
+      win.clearTimeout(pending);
     }
     timers.set(
       el,
-      setTimeout(() => {
+      win.setTimeout(() => {
         timers.delete(el);
         el.textContent = message;
       }, REANNOUNCE_DELAY_MS),
@@ -70,7 +73,7 @@ export function createAnnouncer(root: HTMLElement): Announcer {
 
   function destroy(): void {
     for (const t of timers.values()) {
-      clearTimeout(t);
+      win.clearTimeout(t);
     }
     timers.clear();
     polite.remove();
@@ -83,37 +86,111 @@ export function createAnnouncer(root: HTMLElement): Announcer {
 let panelSeq = 0;
 let tabSeq = 0;
 
-/** Wire the ARIA tablist/tabpanel seam on the kernel's output surface. */
-export function createTablist(panel: HTMLElement): TablistController {
+/** One pane's tabpanel: labelled by the tab it shows, described by the shell's
+ *  selection text. */
+export interface PaneTablist {
+  panelId(): string;
+  labelBy(tabId: string): void;
+  /** Drop the label when `tabId` is the tab labelling the panel. */
+  unlabel(tabId: string): void;
+  /** The panel's `aria-describedby` text; empty removes it. */
+  setDescription(text: string): void;
+}
+
+/** Wire the tabpanel half of the ARIA seam on a pane's output surface. */
+export function createPaneTablist(panel: HTMLElement): PaneTablist {
   panelSeq += 1;
   const panelId = panel.id || `wt-panel-${String(panelSeq)}`;
   panel.id = panelId;
   panel.setAttribute("role", "tabpanel");
+  let description: HTMLElement | null = null;
+
+  return {
+    panelId: () => panelId,
+    labelBy(tabId) {
+      panel.setAttribute("aria-labelledby", tabId);
+    },
+    unlabel(tabId) {
+      if (panel.getAttribute("aria-labelledby") === tabId) {
+        panel.removeAttribute("aria-labelledby");
+      }
+    },
+    setDescription(text) {
+      if (text === "") {
+        description?.remove();
+        description = null;
+        panel.removeAttribute("aria-describedby");
+        return;
+      }
+      if (description === null) {
+        description = panel.ownerDocument.createElement("span");
+        description.id = `${panelId}-description`;
+        hideVisually(description);
+        panel.parentElement?.appendChild(description);
+        panel.setAttribute("aria-describedby", description.id);
+      }
+      description.textContent = text;
+    },
+  };
+}
 
+/** Wire the tab-row half of the ARIA seam. `panelFor(side)` answers the pane
+ *  showing a tab, and `panelFor(null)` the pane a click on an unshown tab would
+ *  fill; either may be null before that pane is built. */
+export function createTablist(
+  panelFor: (side: PaneSide | null) => PaneTablist | null,
+): TablistController {
   function registerTab(tab: HTMLElement): TabHandle {
     tabSeq += 1;
     const tabId = tab.id || `wt-tab-${String(tabSeq)}`;
     tab.id = tabId;
     tab.setAttribute("role", "tab");
-    tab.setAttribute("aria-controls", panelId);
     tab.setAttribute("aria-selected", "false");
     // Roving tabindex (WAI-ARIA APG Tabs pattern): only the selected tab is in
     // the Tab sequence; the others are focusable programmatically (arrow keys).
     tab.tabIndex = -1;
+    let side: PaneSide | null = null;
+    let selected = false;
+    let labelled: PaneTablist | null = null;
+    function paintPanel(): void {
+      const panel = panelFor(side);
+      if (panel === null) {
+        tab.removeAttribute("aria-controls");
+      } else {
+        tab.setAttribute("aria-controls", panel.panelId());
+      }
+      // A panel is labelled by the selected tab that controls it, and by nothing else.
+      const labelling = selected ? panel : null;
+      if (labelling !== labelled) {
+        labelled?.unlabel(tabId);
+        labelling?.labelBy(tabId);
+        labelled = labelling;
+      }
+    }
+    paintPanel();
 
     return {
-      setSelected(selected: boolean): void {
-        tab.setAttribute("aria-selected", selected ? "true" : "false");
-        tab.tabIndex = selected ? 0 : -1;
-        if (selected) {
-          // The panel is labelled by whichever tab is currently selected.
-          panel.setAttribute("aria-labelledby", tabId);
+      setSelected(on: boolean): void {
+        selected = on;
+        tab.setAttribute("aria-selected", on ? "true" : "false");
+        tab.tabIndex = on ? 0 : -1;
+        paintPanel();
+      },
+      setPanel(next: PaneSide | null): void {
+        side = next;
+        paintPanel();
+      },
+      setExpanded(state: boolean | null): void {
+        if (state === null) {
+          tab.removeAttribute("aria-expanded");
+        } else {
+          tab.setAttribute("aria-expanded", state ? "true" : "false");
         }
       },
       setLabel(text: string): void {
         tab.setAttribute("aria-label", text);
       },
-      setEditing(editing: boolean, selected: boolean): void {
+      setEditing(editing: boolean, on: boolean): void {
         if (editing) {
           // Drop the tab semantics while a textbox lives inside the chip, and
           // take the chip out of the roving sequence so Tab moves past it to the
@@ -125,24 +202,26 @@ export function createTablist(panel: HTMLElement): TablistController {
           tab.tabIndex = -1;
           return;
         }
+        selected = on;
         tab.setAttribute("role", "tab");
-        tab.setAttribute("aria-selected", selected ? "true" : "false");
-        tab.tabIndex = selected ? 0 : -1;
+        tab.setAttribute("aria-selected", on ? "true" : "false");
+        tab.tabIndex = on ? 0 : -1;
+        paintPanel();
       },
       remove(): void {
         tab.removeAttribute("role");
         tab.removeAttribute("aria-controls");
         tab.removeAttribute("aria-selected");
+        tab.removeAttribute("aria-expanded");
         tab.removeAttribute("tabindex");
-        if (panel.getAttribute("aria-labelledby") === tabId) {
-          panel.removeAttribute("aria-labelledby");
-        }
+        labelled?.unlabel(tabId);
+        labelled = null;
       },
     };
   }
 
   return {
-    panelId: () => panelId,
+    panelId: () => panelFor(null)?.panelId() ?? "",
     registerTab,
   };
 }