@cplieger/web-terminal-ui 7.3.2 → 8.0.0

package/src/composition.ts

@@ -1,78 +1,24 @@
-// IME / composition support.
-//
-// Mirrors xterm.js's CompositionHelper. The browser fires
-// compositionstart → compositionupdate(s) → compositionend when an IME
-// (Japanese / Korean / Chinese / Vietnamese / dictation / autocorrect
-// suggestion bar) is active. Without a handler, the user sees nothing
-// while typing because keydown/input fire only when the composed
-// phrase is finalised.
-//
-// What this module does:
-//   1. On compositionstart, mark composing=true and capture textarea
-//      selection bounds. Show the floating compositionView at the
-//      cursor with the in-progress text.
-//   2. On compositionupdate, mirror the in-progress text into
-//      compositionView (\u200E LTR markers, RTL CSS direction so long
-//      compositions track their tail).
-//   3. On compositionend, set a setTimeout(0) finaliser. The
-//      compositionend.data property is unreliable on Chromium (Korean
-//      ending consonant moves to next char on vowel input, etc.); the
-//      textarea value at next tick has the truth.
-//   4. While composing, callers' keydown handler must early-return
-//      (handled via isComposing()). xterm.js takes the same approach.
-//
-// Positioning: the compositionView is absolutely positioned inside
-// `termWrap`. The IME UI (browser-rendered popup with candidate words)
-// uses the textarea as its anchor; we move the textarea to the cursor
-// for the same reason.
+// IME / composition support, after xterm.js's CompositionHelper: the browser
+// fires compositionstart, compositionupdate(s) and compositionend while an IME
+// (CJK, Vietnamese, dictation, an autocorrect bar) is active, and without a
+// handler the user sees nothing until the phrase is finalised. The in-progress
+// text is mirrored into a floating view at the cursor; the textarea is moved
+// there too because the IME's candidate popup anchors on it. compositionend's
+// `data` is unreliable on Chromium, so the textarea value is read one tick later.
 
 import { resetToPlaceholder } from "./input-placeholder.js";
-
-let textarea: HTMLTextAreaElement;
-let compositionView: HTMLElement;
-let getCursorPx: () => { left: number; top: number; cellH: number };
-let send: (bytes: string) => void;
-let paste: (text: string) => void;
-
-let composing = false;
-let sendingComposition = false;
-let compositionStart = 0;
-let compositionSuffix = "";
-
-// A composition that never ENDS used to stop the terminal accepting input at
-// all. `composing` gates both the kernel's `input` and `keydown` listeners, and
-// nothing cleared it: no blur handler, no timer. So a keyboard that opened a
-// composition and never closed it left every subsequent keystroke, Enter
-// included, dropped on the floor — reported on Android Chrome with SwiftKey as
-// "typing does not work", recoverable only by tapping a word suggestion, which
-// is what finally fired compositionend.
-//
-// Not a SwiftKey quirk to special-case. Chromium has a filed defect for
-// compositionend going missing (crbug 446714223, in EditContext rather than a
-// textarea, so it is adjacent evidence and not proof of this exact path), and
-// CodeMirror synthesises the event outright for Safari dead keys, which is a
-// working implementation treating the same absence as real.
-//
-// The fix is a STALENESS READ rather than a timer. A composition the user is
-// typing into keeps firing compositionupdate, so its clock keeps refreshing; an
-// abandoned one stops and ages out, releasing the gate. UI Events promises one
-// or more compositionupdate events and one whenever the DOM is updated as part
-// of the composition, not strictly one per key, so this is a heuristic about
-// activity rather than a guaranteed per-keystroke signal. Deliberately NOT
-// refreshed by `input` events: in this failure the user IS typing and those
-// events ARE arriving, so refreshing there would defeat the mechanism.
-//
-// Five seconds is the number Slate's android-input-manager uses for its own
-// composition-gone-quiet bound (a DOM flush decision, not an input gate, so the
-// value is borrowed and the job is not the same). It is generous because the
-// residual risk runs the other way: a composition paused longer than this and
-// then resumed can duplicate its first character. That trade is deliberate —
-// the failure being replaced loses ALL input until an unrelated event fires.
+import { windowOf } from "./kernel/realm.js";
+
+/** A composition that never ends would gate every later keystroke out, and it
+ *  happens: Android Chrome with SwiftKey fires no compositionend until a word
+ *  suggestion is tapped (crbug 446714223 is adjacent evidence). So the latch is
+ *  read against a STALENESS clock refreshed by compositionupdate alone, never by
+ *  `input` (in this failure the user IS typing). Five seconds is Slate's
+ *  composition-gone-quiet bound; the residual risk is one duplicated character
+ *  after a pause, against losing all input until an unrelated event fires. */
 const COMPOSITION_IDLE_MS = 5000;
 
-let lastCompositionActivity = 0;
-
-export function init(opts: {
+export interface CompositionOptions {
   textarea: HTMLTextAreaElement;
   compositionView: HTMLElement;
   getCursorPx: () => { left: number; top: number; cellH: number };
@@ -80,191 +26,173 @@ export function init(opts: {
   /** The kernel's single bracketed-paste+normalize funnel; the native iOS-callout
    *  paste routes through it rather than re-composing the funnel here. */
   paste: (text: string) => void;
-}): void {
-  textarea = opts.textarea;
-  compositionView = opts.compositionView;
-  getCursorPx = opts.getCursorPx;
-  send = opts.send;
-  paste = opts.paste;
+}
 
-  textarea.addEventListener("compositionstart", onStart);
-  textarea.addEventListener("compositionupdate", onUpdate);
-  textarea.addEventListener("compositionend", onEnd);
-  textarea.addEventListener("paste", onPaste);
+/** One pane's IME state: the latch every input listener gates on, the floating
+ *  view, and the textarea placement. */
+export interface Composition {
+  /** True while an IME composition is in progress, reconciled first: a
+   *  composition quiet for COMPOSITION_IDLE_MS is expired here. */
+  isComposing(): boolean;
+  /** The RAW latch: is a composition open at all, regardless of staleness. Read
+   *  before `isComposing()` by the keydown guard, because keyCode 229 means "an
+   *  IME claimed this key" only while a composition is genuinely open. */
+  isCompositionOpen(): boolean;
+  /** Abort any in-flight composition without sending, and clear the textarea.
+   *  Also neutralizes a just-fired compositionend whose deferred send is still
+   *  pending, so it cannot land on whoever is active after a switch. */
+  cancelComposition(): void;
+  /** Place the view and the textarea at the terminal cursor. */
+  positionCompositionView(): void;
+  /** Release the listeners and any pending send. */
+  teardown(): void;
 }
 
-/** True while an IME composition is in progress, RECONCILED first: a composition
- *  whose clock has not been refreshed for COMPOSITION_IDLE_MS is expired here,
- *  clearing the latch, the clock and the overlay, so a keyboard that never fires
- *  compositionend cannot strand the terminal or leave a stale panel on screen.
- *  A late compositionend still delivers its text — `onEnd` snapshots what it
- *  needs and does not require `composing` to have stayed true.
- *
- *  `sendingComposition` is exempt: that window is bounded by a setTimeout(0)
- *  this module owns. */
-export function isComposing(): boolean {
-  if (sendingComposition) {
-    return true;
+export function createComposition(opts: CompositionOptions): Composition {
+  const { textarea, compositionView, getCursorPx, send, paste } = opts;
+  // The textarea's own clock and timers: the deferred send belongs to the
+  // document the terminal is mounted in, not the importing page.
+  const win = windowOf(textarea.ownerDocument);
+  let composing = false;
+  let compositionStart = 0;
+  let compositionSuffix = "";
+  let lastCompositionActivity = 0;
+  let pendingSend: number | null = null;
+
+  function expireComposition(): void {
+    composing = false;
+    lastCompositionActivity = 0;
+    compositionView.textContent = "";
+    compositionView.classList.remove("active");
   }
-  if (!composing) {
+
+  function isComposing(): boolean {
+    if (pendingSend !== null) {
+      return true;
+    }
+    if (!composing) {
+      return false;
+    }
+    if (win.Date.now() - lastCompositionActivity <= COMPOSITION_IDLE_MS) {
+      return true;
+    }
+    expireComposition();
     return false;
   }
-  if (Date.now() - lastCompositionActivity <= COMPOSITION_IDLE_MS) {
-    return true;
-  }
-  expireComposition();
-  return false;
-}
 
-/** The RAW latch: is a composition open at all, regardless of whether it has
- *  gone quiet. Read before the reconciling `isComposing()` by the keydown guard,
- *  because the keyCode 229 signal only means "an IME claimed this key" while a
- *  composition is genuinely open — on Android it is the value for nearly every
- *  soft-keyboard key. */
-export function isCompositionOpen(): boolean {
-  return composing || sendingComposition;
-}
+  function clearPendingSend(): void {
+    if (pendingSend !== null) {
+      win.clearTimeout(pendingSend);
+      pendingSend = null;
+    }
+  }
 
-/** Drop a composition that has gone quiet: the latch, the clock and the visible
- *  overlay together. Without the overlay half the gate would say no composition
- *  while `.composition-view.active` still said there was one, leaving a stale
- *  panel over the terminal for as long as the missing compositionend never
- *  arrived. Does NOT touch the textarea: a late compositionend still reads it. */
-function expireComposition(): void {
-  composing = false;
-  lastCompositionActivity = 0;
-  compositionView.textContent = "";
-  compositionView.classList.remove("active");
-}
+  function cancelComposition(): void {
+    composing = false;
+    clearPendingSend();
+    lastCompositionActivity = 0;
+    compositionView.textContent = "";
+    compositionView.classList.remove("active");
+    resetToPlaceholder(textarea);
+  }
 
-/** Abort any in-flight composition without sending, and clear the textarea.
- *  The kernel calls this on a tab switch (detach) and on blur: committing
- *  half-composed IME text to either the outgoing or the incoming session is
- *  wrong, so we discard it (design 5.1, "end any composition ... or cancel").
- *  Clearing sendingComposition also neutralizes a just-fired compositionend
- *  whose deferred send is still pending on the microtask/timeout queue, so it
- *  cannot land on whoever is active after the switch. */
-export function cancelComposition(): void {
-  composing = false;
-  sendingComposition = false;
-  lastCompositionActivity = 0;
-  compositionView.textContent = "";
-  compositionView.classList.remove("active");
-  resetToPlaceholder(textarea);
-}
+  function positionCompositionView(): void {
+    const { left, top, cellH } = getCursorPx();
+    compositionView.style.left = `${left}px`;
+    compositionView.style.top = `${top}px`;
+    compositionView.style.height = `${cellH}px`;
+    compositionView.style.lineHeight = `${cellH}px`;
+    // The textarea shares the view's content coordinates and .term is pinned to
+    // the visual viewport, so this keeps the focused input at the VISIBLE cursor,
+    // above the keyboard, where iOS wants it and does not scroll the page.
+    textarea.style.left = `${left}px`;
+    textarea.style.top = `${top}px`;
+    textarea.style.height = `${cellH}px`;
+  }
 
-/** Release init()-attached listeners and drop the captured kernel closures on kernel
- *  destroy(), so a destroy without a remount does not retain the old textarea + the
- *  kernel send/paste closure graph. Mirrors viewport.teardown(). */
-export function teardown(): void {
-  cancelComposition(); // neutralize a pending finalizer + reset composing state
-  textarea.removeEventListener("compositionstart", onStart);
-  textarea.removeEventListener("compositionupdate", onUpdate);
-  textarea.removeEventListener("compositionend", onEnd);
-  textarea.removeEventListener("paste", onPaste);
-  // Drop references to the old kernel instance so its closure graph is GC-eligible
-  // (the detached textarea/compositionView are overwritten on the next init()).
-  send = () => {
-    /* no-op after teardown */
-  };
-  paste = () => {
-    /* no-op after teardown */
-  };
-  getCursorPx = () => ({ left: 0, top: 0, cellH: 0 });
-}
+  function onStart(): void {
+    composing = true;
+    lastCompositionActivity = win.Date.now();
+    const start = textarea.selectionStart;
+    const end = textarea.selectionEnd;
+    compositionStart = Math.min(start, end);
+    const compositionEnd = Math.max(start, end);
+    compositionSuffix = textarea.value.substring(compositionEnd);
+    compositionView.textContent = "";
+    compositionView.classList.add("active");
+    positionCompositionView();
+  }
 
-function onStart(): void {
-  composing = true;
-  lastCompositionActivity = Date.now();
-  const start = textarea.selectionStart;
-  const end = textarea.selectionEnd;
-  compositionStart = Math.min(start, end);
-  const compositionEnd = Math.max(start, end);
-  compositionSuffix = textarea.value.substring(compositionEnd);
-  compositionView.textContent = "";
-  compositionView.classList.add("active");
-  positionCompositionView();
-}
+  function onUpdate(ev: CompositionEvent): void {
+    lastCompositionActivity = win.Date.now();
+    // LTR marks plus direction:rtl on the view show a long composition's tail
+    // instead of clipping its start (xterm.js's pattern).
+    compositionView.textContent = `\u200E${ev.data}\u200E`;
+    positionCompositionView();
+  }
 
-function onUpdate(ev: CompositionEvent): void {
-  // Every keystroke of a live composition lands here, which is what keeps its
-  // staleness clock fresh (see COMPOSITION_IDLE_MS). An abandoned composition
-  // stops firing this and ages out of the gate.
-  lastCompositionActivity = Date.now();
-  // \u200E (LTR mark) wrappers + CSS direction:rtl on the view make
-  // long compositions show their trailing edge instead of being
-  // clipped at the start. Pattern from xterm.js.
-  compositionView.textContent = `\u200E${ev.data}\u200E`;
-  positionCompositionView();
-}
+  function onEnd(): void {
+    compositionView.classList.remove("active");
+    composing = false;
+    lastCompositionActivity = 0;
+    clearPendingSend();
+    const startSnapshot = compositionStart;
+    const suffixSnapshot = compositionSuffix;
+    pendingSend = win.setTimeout(() => {
+      pendingSend = null;
+      const value = textarea.value;
+      const valueEnd =
+        suffixSnapshot.length > 0 && value.endsWith(suffixSnapshot)
+          ? value.length - suffixSnapshot.length
+          : value.length;
+      const composed = value
+        .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
+        .replace(/\u00A0/g, " ");
+      if (composed.length > 0) {
+        send(composed);
+      }
+      resetToPlaceholder(textarea);
+    }, 0);
+  }
 
-function onEnd(): void {
-  compositionView.classList.remove("active");
-  composing = false;
-  lastCompositionActivity = 0;
-  // The compositionend event fires before the textarea reflects the
-  // final value on most browsers (Chromium especially). Defer one tick
-  // and read the textarea then; xterm.js's pattern.
-  sendingComposition = true;
-  const startSnapshot = compositionStart;
-  const suffixSnapshot = compositionSuffix;
-  setTimeout(() => {
-    if (!sendingComposition) {
+  function onPaste(ev: ClipboardEvent): void {
+    // iOS has no Ctrl+Shift+V; its callout menu fires this on the focused textarea.
+    if (!ev.clipboardData) {
       return;
     }
-    sendingComposition = false;
-    const value = textarea.value;
-    const valueEnd =
-      suffixSnapshot.length > 0 && value.endsWith(suffixSnapshot)
-        ? value.length - suffixSnapshot.length
-        : value.length;
-    const composed = value
-      .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
-      .replace(/\u00A0/g, " ");
-    if (composed.length > 0) {
-      send(composed);
+    const raw = ev.clipboardData.getData("text/plain");
+    if (raw === "") {
+      return;
     }
+    ev.preventDefault();
+    ev.stopPropagation();
+    paste(raw);
     resetToPlaceholder(textarea);
-  }, 0);
-}
+  }
 
-function onPaste(ev: ClipboardEvent): void {
-  // Native `paste` event handler. Required for iOS where Ctrl+Shift+V
-  // is unavailable; users invoke paste from the iOS callout menu and
-  // it fires this event on the focused textarea.
-  if (!ev.clipboardData) {
-    return;
+  // One signal over every listener, so a registration that throws leaves the
+  // ones before it released with it.
+  const wired = new AbortController();
+  const { signal } = wired;
+  function teardown(): void {
+    cancelComposition();
+    wired.abort();
   }
-  const raw = ev.clipboardData.getData("text/plain");
-  if (raw === "") {
-    return;
+  try {
+    textarea.addEventListener("compositionstart", onStart, { signal });
+    textarea.addEventListener("compositionupdate", onUpdate, { signal });
+    textarea.addEventListener("compositionend", onEnd, { signal });
+    textarea.addEventListener("paste", onPaste, { signal });
+  } catch (err) {
+    teardown();
+    throw err;
   }
-  ev.preventDefault();
-  ev.stopPropagation();
-  paste(raw);
-  // Restore the placeholder so the subsequent `input` event (some
-  // browsers fire it after paste) and held-Backspace auto-repeat keep
-  // working.
-  resetToPlaceholder(textarea);
-}
 
-/** Position the composition view (and the helper textarea, which
- *  anchors the IME popup) at the current terminal cursor pixel
- *  position. iOS keyboards open without scrolling the layout when
- *  the focused textarea is on screen at a sane location. */
-export function positionCompositionView(): void {
-  const { left, top, cellH } = getCursorPx();
-  compositionView.style.left = `${left}px`;
-  compositionView.style.top = `${top}px`;
-  compositionView.style.height = `${cellH}px`;
-  compositionView.style.lineHeight = `${cellH}px`;
-  // The textarea is position:absolute in the same scroll/content space as the
-  // composition view (see the .term-input CSS note), so the cursor's content
-  // coordinates place it at the cursor row directly. Because .term is pinned to
-  // the visual viewport (viewport.ts), that keeps the textarea at the VISIBLE
-  // cursor, above the keyboard — where iOS wants the focused input so it doesn't
-  // scroll the page to reveal it.
-  textarea.style.left = `${left}px`;
-  textarea.style.top = `${top}px`;
-  textarea.style.height = `${cellH}px`;
+  return {
+    isComposing,
+    isCompositionOpen: () => composing || pendingSend !== null,
+    cancelComposition,
+    positionCompositionView,
+    teardown,
+  };
 }

package/src/features/activity-monitor.ts

@@ -1,77 +1,45 @@
-/**
- * activityMonitor feature: subscribes to the server's status SSE
- * (/api/sessions/events via the engine's connectStatusStream) and exposes each
- * session's live status through its API. 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 — 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.
- *
- * @module
- */
+// The server's snapshot on a (re)open carries no tombstones for sessions a
+// REPLACEMENT server never knew, so the open is surfaced through onStreamOpen
+// for a consumer to reconcile on.
 
-import { connectStatusStream } from "@cplieger/web-terminal-engine";
 import type { SessionStatus } from "@cplieger/web-terminal-engine";
 import type { TerminalFeature, Unsubscribe } from "../kernel/types.js";
 
 const DEFAULT_EVENTS_PATH = "/api/sessions/events";
 
-/** The value a peer feature reads through `ctx.use(activityMonitor(...))`: the
- *  live status of every session the server knows about.
- *
- *  Read-only — nothing here starts, stops or mutates a session. `current` answers
- *  from the last event seen rather than from the network, so it is undefined for
- *  a session no event has covered yet (the initial snapshot arrives
- *  asynchronously after setup) and for one the stream has since reported
- *  `removed`. A caller that needs "eventually" rather than "now" subscribes. */
+/** The live status of every session the server knows about. `current` answers
+ *  from the last event seen, so it is undefined for a session no event has
+ *  covered yet and for one reported `removed`; a caller that needs "eventually"
+ *  subscribes. */
 export interface ActivityMonitorApi {
-  /** Subscribe to every status update (idle/working/warning/failed/input/done/
-   *  exited/crashed, plus removed), including the OSC 9;4 percentage and any OSC
-   *  9 notification the event carries. Fired for the initial snapshot and each
-   *  change. */
+  /** Every status update, the initial snapshot included. */
   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. */
+  /** Every stream (re)open; a subscriber attaching after one has happened is
+   *  called at once. Optional so an alternative monitor stays valid. */
   onStreamOpen?(cb: () => void): Unsubscribe;
 }
 
-/** Build the activityMonitor feature.
- *
- *  Requires a server that serves the status SSE endpoint; on a server without one
- *  the stream never opens, every `current` stays undefined and no subscriber ever
- *  fires, which is why `tabs` treats the monitor as optional and polls
- *  `GET /api/sessions` instead when it is absent.
- *
- *  `eventsPath` overrides the endpoint (default `/api/sessions/events`). Order it
- *  BEFORE any feature that reads its API through `ctx.use`, since a feature's
- *  setup can only see peers already set up. Teardown closes the stream and drops
- *  every subscriber and cached status.
- *
- *  A throwing subscriber is caught and logged rather than propagated: it must not
- *  skip the remaining subscribers, and it must not reach the engine's SSE reader
- *  and kill the stream for everyone. */
+/** Build the activityMonitor feature. On a server without the SSE endpoint the
+ *  stream never opens and no subscriber fires, which is why `tabs` treats the
+ *  monitor as optional. Order it BEFORE any feature that reads it through
+ *  `ctx.use`. A throwing subscriber is logged, never propagated: it must not
+ *  skip the remaining subscribers or kill the stream for everyone. */
 export function activityMonitor(
   opts: { eventsPath?: string } = {},
 ): TerminalFeature<ActivityMonitorApi> {
   return {
     name: "activityMonitor",
-    setup() {
+    scope: "shell",
+    setup(ctx) {
       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, {
+      const offStream = ctx.shell.subscribeStatus(path, {
         onOpen() {
           opens++;
           for (const cb of [...openSubs]) {
@@ -92,14 +60,12 @@ export function activityMonitor(
             try {
               cb(s);
             } catch (err) {
-              // Isolate a throwing subscriber so it neither skips the
-              // remaining subscribers nor propagates into the engine's
-              // SSE reader (mirrors the kernel bus's ctx.on wrapping).
               console.error("web-terminal-ui: activityMonitor subscriber threw", err);
             }
           }
         },
       });
+      ctx.defer(offStream);
 
       return {
         api: {
@@ -113,13 +79,12 @@ export function activityMonitor(
           onStreamOpen(cb) {
             openSubs.add(cb);
             if (opens > 0) {
-              cb(); // catch-up: the stream opened before this subscriber attached
+              cb();
             }
             return () => openSubs.delete(cb);
           },
         },
         teardown() {
-          stream.close();
           subs.clear();
           openSubs.clear();
           statuses.clear();

package/src/features/animations.ts

@@ -1,45 +1,27 @@
-/**
- * animations feature: opt-in motion for the chrome surfaces.
- * Without it the chrome surfaces are instant (no transitions); with
- * it, and when the user has not asked for reduced motion, it enables the shared
- * animation vocabulary by marking the terminal root, which the feature
- * stylesheets key their transitions off. A few pieces of motion animate
- * unconditionally regardless of this feature (terminal-core cursor/SGR blink and
- * the mobile key toolbar open/close in 02-app.css, plus the working-status-dot
- * pulse in 05-tabs.css, its WCAG non-hue cue), though prefers-reduced-motion
- * still defeats all of it. It tracks prefers-reduced-motion live so toggling the
- * OS setting takes effect.
- *
- * @module
- */
-
+import { windowOf } from "../kernel/realm.js";
 import type { TerminalFeature } from "../kernel/types.js";
 
-/** Build the animations feature. Exposes no API — its whole effect is the
- *  `wt-animate` class on the terminal root, which the shipped stylesheets gate
- *  their transitions on, so a composition either includes it or gets instant
- *  chrome.
- *
- *  Position in the feature list does not matter (nothing reads it through
- *  `ctx.use`). The class is applied during setup, re-evaluated whenever the
- *  `prefers-reduced-motion` media query changes, and removed on teardown along
- *  with the listener. */
+/** Build the animations feature. Exposes no API; its whole effect is the
+ *  `wt-animate` class on the shell root, which the shipped stylesheets gate their
+ *  transitions on, tracking prefers-reduced-motion live. */
 export function animations(): TerminalFeature {
   return {
     name: "animations",
+    scope: "shell",
     setup(ctx) {
-      // The root is the surface's parent (regions + surface are its children).
-      const root = ctx.surface().parentElement;
-      const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+      const root = ctx.shell.root;
+      const mq = windowOf(root.ownerDocument).matchMedia("(prefers-reduced-motion: reduce)");
       const apply = (): void => {
-        root?.classList.toggle("wt-animate", !mq.matches);
+        root.classList.toggle("wt-animate", !mq.matches);
       };
       apply();
       mq.addEventListener("change", apply);
+      ctx.defer(() => {
+        mq.removeEventListener("change", apply);
+      });
       return {
         teardown() {
-          mq.removeEventListener("change", apply);
-          root?.classList.remove("wt-animate");
+          root.classList.remove("wt-animate");
         },
       };
     },