@cplieger/web-terminal-ui 7.3.1 → 8.0.0

package/src/viewport.ts

@@ -1,233 +1,160 @@
-// Viewport stability tracker.
-//
-// Coordinates iOS keyboard transitions, window resizes, font-load reflows,
-// and ResizeObserver fires into a single "transition → settle" lifecycle
-// so the rest of the app can act on stable viewport state without each
-// piece reinventing its own debounce/suppress timers.
-//
-// Behavior:
-//   1. Any viewport-affecting event marks "in transition".
-//   2. While in transition: autoscroll is suppressed, input dimensions
-//      may shift, no resize is sent to the server.
-//   3. After SETTLE_MS of no further events, fire onSettled — the caller
-//      then sends the final size, pins to the bottom if still following, etc.
-//      The follow state is read AT SETTLE (see startTransition): a latch taken
-//      at the start of the burst goes stale, because every further event
-//      extends the window without re-reading it.
+// Viewport stability tracker: iOS keyboard transitions, window resizes,
+// font-load reflows and ResizeObserver fires fold into one "transition, then
+// settle" lifecycle, so nothing else needs its own debounce. While in
+// transition no resize is sent; after SETTLE_MS of quiet onSettled fires and the
+// caller sends the final size.
 
-import { scroll } from "@cplieger/web-terminal-engine";
+import type { ScrollController } from "@cplieger/web-terminal-engine";
+import { windowOf } from "./kernel/realm.js";
 
-// Time to wait after the last viewport-changing event before declaring
-// the viewport "settled". Long enough to bridge the iOS keyboard slide
-// (~250ms) with margin for fonts and reflow.
+// Long enough to bridge the iOS keyboard slide (~250ms) with margin for fonts
+// and reflow.
 const SETTLE_MS = 350;
 
-let termWrap: HTMLElement;
-// The terminal root (.wt-root): the geometry CSS vars (--kb-inset, --vv-top)
-// are published here so the terminal subtree — and nothing else on the host
-// page — inherits them. Falls back to termWrap if init was somehow given no
-// root (never in practice; the kernel always passes it).
-let varTarget: HTMLElement;
-let onSettled: ((wasAtBottom: boolean) => void) | null = null;
-let inTransition = false;
-let settleTimer: ReturnType<typeof setTimeout> | null = null;
-// When true, ignore the visualViewport keyboard geometry entirely (a hardware
-// keyboard/trackpad is present, so the soft keyboard never opens). Set at init
-// from the kernel's hasFinePointer; see the onChange note below.
-let suppressKeyboardInset: () => boolean = () => false;
-// Removals for every listener/observer init() attaches, so teardown() can
-// release them on kernel destroy(). Without it the window/visualViewport/
-// screen.orientation listeners and the ResizeObserver survive destroy() and a
-// re-created terminal double-binds them.
-let cleanup: (() => void)[] = [];
-
-function startTransition(): void {
-  inTransition = true;
-  if (settleTimer !== null) {
-    clearTimeout(settleTimer);
-  }
-  settleTimer = setTimeout(() => {
-    settleTimer = null;
-    inTransition = false;
-    // Read the follow state AT SETTLE, not at the start of the burst. Every
-    // viewport event re-arms this timer without re-reading, and on iOS a wake or
-    // keyboard slide emits a stream of them, so a latch captured at the start
-    // stays true across a user scrolling up mid-burst and then yanks them back
-    // down. Asking now is only safe because a content shrink can no longer
-    // corrupt the follow state on its own (the engine's scroll controller
-    // re-engages follow only on a downward user move); before that, this snap
-    // was accidentally repairing the corruption it was also causing.
-    const stillFollowing = !scroll.isUserScrolledUp();
-    if (stillFollowing) {
-      // Pin, do not force. A geometry change can leave scrollTop stale short of
-      // the bottom, which the pin fixes; scrollToBottom would additionally
-      // OVERRIDE the follow state, which is not this handler's call to make.
-      scroll.stickToBottom();
-    }
-    if (onSettled) {
-      onSettled(stillFollowing);
-    }
-  }, SETTLE_MS);
-}
-
-/**
- * Whether a viewport transition is in flight (an iOS keyboard slide, a rotation,
- * a font-load reflow). Geometry measured now is provisional, so a caller that
- * puts a measurement on the wire should wait for the settle instead.
- */
-export function isInTransition(): boolean {
-  return inTransition;
-}
-
-export function init(opts: {
+export interface ViewportOptions {
   termWrap: HTMLElement;
-  /** The terminal root (.wt-root): receives the geometry CSS vars the sibling
-   *  chrome reads (--kb-inset, --vv-top), so they scope to the terminal
-   *  subtree instead of leaking onto the host document. */
+  /** The terminal root: receives the geometry CSS vars the sibling chrome reads
+   *  (--kb-inset, --vv-top), so they scope to the terminal subtree instead of
+   *  leaking onto the host document. */
   root?: HTMLElement;
+  /** This pane's scroll controller, read at settle. */
+  scroll: Pick<ScrollController, "isUserScrolledUp" | "stickToBottom">;
   onSettled: (wasAtBottom: boolean) => void;
   /** Ignore the visualViewport keyboard geometry (a hardware-keyboard device
    *  has no soft keyboard to accommodate); only reserved bottom chrome insets
-   *  the terminal. The kernel passes its hasFinePointer here. */
+   *  the terminal. */
   suppressKeyboardInset?: () => boolean;
-}): void {
-  termWrap = opts.termWrap;
-  varTarget = opts.root ?? opts.termWrap;
-  onSettled = opts.onSettled;
-  suppressKeyboardInset = opts.suppressKeyboardInset ?? (() => false);
+}
+
+/** One pane's viewport tracker. */
+export interface Viewport {
+  /** Whether a transition is in flight, so geometry measured now is provisional. */
+  isInTransition(): boolean;
+  /** Release every listener and observer, stop the settle timer, and clear the
+   *  CSS vars published on the root. */
+  teardown(): void;
+}
+
+export function createViewport(opts: ViewportOptions): Viewport {
+  const { termWrap, scroll } = opts;
+  const varTarget = opts.root ?? opts.termWrap;
+  const suppressKeyboardInset = opts.suppressKeyboardInset ?? ((): boolean => false);
+  // The terminal's own window: its viewport, its keyboard and its rotation, not
+  // the importing page's.
+  const win = windowOf(termWrap.ownerDocument);
+  let inTransition = false;
+  let settleTimer: number | null = null;
+  // Every listener and the observer push their release as they are acquired,
+  // so a registration that throws drains what came before it.
+  const cleanup: (() => void)[] = [];
+  function listen(target: EventTarget, type: string, handler: () => void): void {
+    target.addEventListener(type, handler);
+    cleanup.push(() => {
+      target.removeEventListener(type, handler);
+    });
+  }
+  function release(): void {
+    while (cleanup.length > 0) {
+      cleanup.pop()?.();
+    }
+    if (settleTimer !== null) {
+      win.clearTimeout(settleTimer);
+      settleTimer = null;
+    }
+    varTarget.style.removeProperty("--kb-inset");
+    varTarget.style.removeProperty("--vv-top");
+    inTransition = false;
+  }
+
+  function startTransition(): void {
+    inTransition = true;
+    if (settleTimer !== null) {
+      win.clearTimeout(settleTimer);
+    }
+    settleTimer = win.setTimeout(() => {
+      settleTimer = null;
+      inTransition = false;
+      // Read at SETTLE, not at the start of the burst: every further event
+      // re-arms the timer without re-reading, and on iOS a wake emits a stream
+      // of them, so a latch taken at the start would yank a reader who scrolled
+      // up mid-burst back down.
+      const stillFollowing = !scroll.isUserScrolledUp();
+      if (stillFollowing) {
+        scroll.stickToBottom();
+      }
+      opts.onSettled(stillFollowing);
+    }, SETTLE_MS);
+  }
 
-  // iOS soft keyboard. interactive-widget=resizes-content makes the
-  // layout viewport shrink; we still apply a manual bottom inset as
-  // fallback for older iOS / other mobile browsers.
-  if (window.visualViewport) {
-    const vv = window.visualViewport;
+  function keyboardInsets(vv: VisualViewport): void {
     const onChange = (): void => {
-      // Pin the terminal's fixed box to the exact region the VISUAL viewport
-      // occupies inside the layout viewport. On iOS the soft keyboard shrinks
-      // (and can offset) the visual viewport WITHOUT resizing the layout
-      // viewport — interactive-widget=resizes-content is not honored on iOS
-      // Safari — so a `position: fixed; inset: 0` terminal keeps the full-screen
-      // height (keyboard overlaying the bottom) while iOS scrolls the focused
-      // input into view and shifts the fixed box up, sliding the output and
-      // prompt behind the keyboard (the "content jumps up, hidden until I
-      // scroll" symptom). Driving top AND bottom from visualViewport keeps the
-      // terminal exactly over the visible area in every browser, so nothing is
-      // left behind the keyboard for iOS to scroll to.
-      // suppressKeyboardInset (set at init from the kernel's hasFinePointer): on
-      // a device with a hardware keyboard/trackpad (a desktop, or an iPad with a
-      // Magic Keyboard) the on-screen keyboard never opens, so there is no
-      // keyboard geometry to accommodate. iPadOS has been seen to briefly report
-      // a keyboard-sized visualViewport shrink with no keyboard shown, which this
-      // handler then pinned as a bottom inset and left stuck (the terminal "moved
-      // up ~50%", black below, surviving tab switches because nothing recomputes
-      // it — only a reload cleared it). Ignore the keyboard geometry there and
-      // keep the terminal full-height; only the reserved bottom chrome applies.
+      // iOS shrinks (and can offset) the visual viewport without resizing the
+      // layout viewport, so a `position: fixed; inset: 0` box keeps the
+      // full-screen height behind the keyboard; driving top and bottom from
+      // visualViewport keeps the terminal over the visible area everywhere.
+      // iPadOS has been seen to report a keyboard-sized shrink with no keyboard
+      // shown and pin it, which is what suppressKeyboardInset defends against.
       const offsetTop = suppressKeyboardInset() ? 0 : Math.max(0, Math.round(vv.offsetTop));
       const bottomInset = suppressKeyboardInset()
         ? 0
-        : Math.max(0, Math.round(window.innerHeight - vv.offsetTop - vv.height));
-      // Reserved bottom chrome (a bottom tab bar) the content must clear, on top
-      // of the keyboard inset. A feature sets --wt-reserve-bottom (px) on the
-      // root, 0 when none; viewport owns the terminal's fixed-box geometry, so it
-      // folds the reserve into the bottom offset here. The reserve excludes the
-      // keyboard (it is measured with the keyboard closed), so adding it to
-      // bottomInset does not double-count.
-      // Read the reserve off the terminal itself: tabs publishes it on the
-      // root (.wt-root), and termWrap inherits it — nothing terminal-scoped
-      // lives on the document root anymore.
+        : Math.max(0, Math.round(win.innerHeight - vv.offsetTop - vv.height));
+      // A feature sets --wt-reserve-bottom (px) on the root for bottom chrome the
+      // content must clear; it is measured with the keyboard closed, so adding it
+      // to the keyboard inset does not double-count.
       const rawReserve = Math.max(
         0,
         Math.round(
-          parseFloat(getComputedStyle(termWrap).getPropertyValue("--wt-reserve-bottom")) || 0,
+          parseFloat(win.getComputedStyle(termWrap).getPropertyValue("--wt-reserve-bottom")) || 0,
         ),
       );
-      // Sanity cap: the reserve is bottom chrome (a tab bar), tens of px. A value
-      // near half the screen is a bad measurement — e.g. the switcher bar
-      // measured while a phantom keyboard inset had lifted it — that would
-      // otherwise strand the lower half of the terminal black. Never let it
-      // exceed a third of the viewport height.
-      const reserve = Math.min(rawReserve, Math.round(window.innerHeight / 3));
+      // The reserve is a tab bar, tens of px; a value near half the screen is a
+      // bad measurement that would strand the lower half of the terminal black.
+      const reserve = Math.min(rawReserve, Math.round(win.innerHeight / 3));
       const bottom = bottomInset + reserve;
       termWrap.style.top = offsetTop > 0 ? `${offsetTop}px` : "";
       termWrap.style.bottom = bottom > 0 ? `${bottom}px` : "";
-      // Expose the same geometry as CSS vars for the sibling chrome, on the
-      // terminal ROOT (scoped: the host page never sees them): --kb-inset
-      // lifts the bottom banner above the keyboard; --vv-top lets the top key
-      // toolbar follow the visual viewport's offset (otherwise it scrolls off
-      // the top when iOS shifts the layout up).
       varTarget.style.setProperty("--kb-inset", `${bottomInset}px`);
       varTarget.style.setProperty("--vv-top", `${offsetTop}px`);
       startTransition();
     };
-    vv.addEventListener("resize", onChange);
-    vv.addEventListener("scroll", onChange);
-    // Self-heal a stuck inset (see the fine-pointer note above): recompute when
-    // the window regains focus or is restored from the bfcache, so a one-off bad
-    // visualViewport reading that got pinned clears on the next natural
-    // interaction instead of surviving until a full page reload.
-    window.addEventListener("focus", onChange);
-    window.addEventListener("pageshow", onChange);
-    cleanup.push(() => {
-      window.removeEventListener("focus", onChange);
-      window.removeEventListener("pageshow", onChange);
-    });
-    cleanup.push(() => {
-      vv.removeEventListener("resize", onChange);
-      vv.removeEventListener("scroll", onChange);
-    });
+    listen(vv, "resize", onChange);
+    listen(vv, "scroll", onChange);
+    // Recompute on focus and bfcache restore, so a one-off bad visualViewport
+    // reading clears on the next natural interaction instead of at reload.
+    listen(win, "focus", onChange);
+    listen(win, "pageshow", onChange);
     onChange();
   }
 
-  // Term wrap dimension changes: window resize, font load, devtools dock.
-  const ro = new ResizeObserver(startTransition);
-  ro.observe(termWrap);
-  window.addEventListener("resize", startTransition);
-  cleanup.push(() => {
-    ro.disconnect();
-    window.removeEventListener("resize", startTransition);
-  });
+  try {
+    if (win.visualViewport) {
+      keyboardInsets(win.visualViewport);
+    }
 
-  // Orientation change on mobile. iOS Safari often emits the
-  // window.resize event late or not at all on rotation while
-  // visualViewport.resize fires reliably; screen.orientation.change is
-  // the canonical signal that survives both. Modern browsers expose it
-  // on screen.orientation; older Safari falls back to the deprecated
-  // window.orientationchange event.
-  const orientation = (screen as Screen & { orientation?: ScreenOrientation }).orientation;
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for older Safari without screen.orientation
-  if (orientation) {
-    orientation.addEventListener("change", startTransition);
+    const ro = new win.ResizeObserver(startTransition);
     cleanup.push(() => {
-      orientation.removeEventListener("change", startTransition);
+      ro.disconnect();
     });
-  } else if ("onorientationchange" in window) {
-    window.addEventListener("orientationchange", startTransition);
-    cleanup.push(() => {
-      window.removeEventListener("orientationchange", startTransition);
-    });
-  }
-}
+    ro.observe(termWrap);
+    listen(win, "resize", startTransition);
 
-// Release every listener/observer init() attached and stop the settle timer.
-// The kernel calls this from destroy() so a create->destroy->create remount
-// does not leave stale global listeners double-bound.
-export function teardown(): void {
-  for (const fn of cleanup) {
-    fn();
-  }
-  cleanup = [];
-  if (settleTimer !== null) {
-    clearTimeout(settleTimer);
-    settleTimer = null;
-  }
-  // Clear the CSS vars onChange published on the terminal root, so a destroy
-  // without a remount (which would recompute them) leaves no stale inset.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- teardown may run before any init in tests
-  if (varTarget) {
-    varTarget.style.removeProperty("--kb-inset");
-    varTarget.style.removeProperty("--vv-top");
+    // iOS Safari often emits window.resize late or not at all on rotation while
+    // screen.orientation.change survives; older Safari has only the deprecated
+    // window event.
+    const orientation = (win.screen as Screen & { orientation?: ScreenOrientation }).orientation;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for older Safari without screen.orientation
+    if (orientation) {
+      listen(orientation, "change", startTransition);
+    } else if ("onorientationchange" in win) {
+      listen(win, "orientationchange", startTransition);
+    }
+  } catch (err) {
+    release();
+    throw err;
   }
-  inTransition = false;
-  onSettled = null;
-  suppressKeyboardInset = () => false;
+
+  return {
+    isInTransition: () => inTransition,
+    teardown: release,
+  };
 }

package/src/features/tabs/attention.ts

@@ -1,250 +0,0 @@
-// tabs/attention.ts — the unseen-cue set, rendered onto the surfaces that exist
-// OUTSIDE this page's chrome: the browser tab title, the installed app's icon
-// badge, and the tab icon.
-//
-// Why these are needed at all: a tab holding a latched status paints a dot on its
-// chip, and that dot is not reliably on screen. The desktop strip scrolls
-// horizontally once it is full, a narrow coarse-pointer device hides the strip
-// entirely (only the active row plus the switcher's aggregate dot remain), and a
-// hidden page shows no chrome at all. notify.ts already covers the last case with
-// a browser Notification, but that API is absent on iOS Safari outside an
-// installed web app, which is exactly where this UI spends its time.
-//
-// STATE, not events. A notification fires once per occurrence and is deduped on a
-// sequence number; everything here is a pure render of what is currently true, so
-// it is safe to recompute on every status sweep and each sink no-ops when nothing
-// changed. That split is why this module and notify.ts stay separate.
-//
-// The set is CueStatus and nothing else, so these surfaces cannot disagree with
-// the switcher's aggregate dot about what wants the user; the fold and the raise
-// share isUnseenCue (model.ts).
-//
-// DOM-free by construction, like notify.ts: every capability arrives through
-// AttentionEnv, so the fold, the idempotence and the degradation paths are driven
-// in the tests by plain recorder functions, and browserAttentionEnv() below is the
-// only function here that reads a global (globalThis.navigator, document).
-//
-// That last clause is a reading of the source, and nothing enforces it — on
-// purpose, not by omission. An ambient-absence test would assert the RUNTIME
-// rather than this module: the only importer is tabs/index.ts, the node project
-// holds one file and it reads stylesheets off disk, so nothing here loads this
-// module outside a browser and no test can observe an absent `document` without
-// passing for a third wrong reason (.kiro/steering/testing-ts.md,
-// "Capability-absence is NOT a project selection"). The half that does ship IS
-// enforced, and at the site: attention.test.ts shadows the whole `navigator`
-// object and drives the real browserAttentionEnv through it. The mechanism that
-// could enforce the load-time half is an AST scan of this file's top-level
-// statements — vibekit carries one for its ported copy, where a node-project test
-// statically imports the module and a module-scope global read really does break
-// something. Copy it here the day anything needs this module to load without a
-// document.
-
-import { type CueStatus, cueIconName, isUnseenCue, worseCue } from "./model.js";
-
-/** What the fold reads per tab. A structural type, so the caller passes its own
- *  tab objects without this module knowing what else they carry. */
-export interface CueCandidate {
-  readonly id: string;
-  readonly status: string;
-}
-
-/** The whole attention state, and the only thing the sinks are allowed to see. */
-export interface Attention {
-  /** How many sessions hold an unacknowledged cue. */
-  readonly count: number;
-  /** The most severe of them, or "" when there is none. */
-  readonly worst: CueStatus | "";
-}
-
-export const NO_ATTENTION: Attention = { count: 0, worst: "" };
-
-/** summarize folds the tab list and this viewer's acknowledgements into the one
- *  value every surface renders.
- *
- *  A COUNT for the title and the badge, a single WORST for the icon. That split
- *  is deliberate: a count is set-valued, so it needs no rule for choosing among
- *  sessions, and severity is a total order, so the icon's choice is not arbitrary
- *  either. Neither surface can name a session, which is the standing constraint
- *  on anything written to a page-wide surface here (see the decision against
- *  per-session progress in the document title, index.ts). */
-export function summarize(
-  tabs: readonly CueCandidate[],
-  seen: ReadonlyMap<string, CueStatus>,
-): Attention {
-  let count = 0;
-  let worst: CueStatus | "" = "";
-  for (const tab of tabs) {
-    if (!isUnseenCue(tab.status, tab.id, seen)) {
-      continue;
-    }
-    count += 1;
-    worst = worseCue(worst, tab.status);
-  }
-  return { count, worst };
-}
-
-/** The capabilities the sinks need, all injected, all optional except the title.
- *
- *  An absent capability is an absent sink and therefore a silent no-op, the same
- *  contract notify.ts uses for a missing Notification constructor: an unsupported
- *  surface is a normal state of the world, not an error to report.
- *
- *  Two of these can also fail INVISIBLY, and that is accepted rather than
- *  handled. `setBadge` resolves on Linux where the desktop paints no badge at
- *  all, and `setIcon` assigns an href that Safari ignores because it caches the
- *  first icon it fetched. Neither is detectable, and neither costs anything when
- *  it fails, because the title is not gated on any capability and so is the
- *  floor: every platform that renders a title at all gets the count. Do not
- *  arrange these into a fallback ladder where the title only appears if the
- *  others are missing — on those two platforms the detection would report
- *  success and the user would be left with nothing. */
-export interface AttentionEnv {
-  /** Set (or clear, with "") the document-title prefix. The kernel's composing
-   *  writer, so this cannot be erased by a program's OSC 0/2 window title. */
-  titlePrefix: (text: string) => void;
-  /** Set the installed app's icon badge to a count, or clear it at zero. */
-  setBadge?: ((count: number) => void) | undefined;
-  /** Point the page's icon links at a variant, or restore them with null. */
-  setIcon?: ((variant: "input" | "done" | "alert" | null) => void) | undefined;
-}
-
-export interface AttentionSurfaces {
-  /** Render an attention state. Idempotent: a value equal to the last one
-   *  applied touches nothing. */
-  apply(next: Attention): void;
-}
-
-/** titlePrefixFor is the title text for a count, and the format is load-bearing
- *  enough to name: the count goes FIRST, because a browser tab strip truncates a
- *  title to its first few characters and a suffix would be the part that is cut.
- *  Parenthesised digits are also the convention every mail and chat client uses,
- *  so it needs no legend. */
-export function titlePrefixFor(count: number): string {
-  return count > 0 ? `(${String(count)}) ` : "";
-}
-
-export function createAttention(env: AttentionEnv): AttentionSurfaces {
-  // Last applied, so each sink is called only on a real change. This matters
-  // beyond cost: the document title doubles as the browser-tab label and the
-  // bookmark name, and re-assigning an icon href makes some browsers re-fetch it.
-  let applied: Attention = NO_ATTENTION;
-  let first = true;
-
-  return {
-    apply(next: Attention): void {
-      const countChanged = first || next.count !== applied.count;
-      const worstChanged = first || next.worst !== applied.worst;
-      first = false;
-      applied = next;
-
-      if (countChanged) {
-        env.titlePrefix(titlePrefixFor(next.count));
-        // The badge takes the SAME number as the title, which is the whole
-        // reason both read one fold: two surfaces disagreeing about how many
-        // things want you is worse than either being absent.
-        env.setBadge?.(next.count);
-      }
-      if (worstChanged) {
-        env.setIcon?.(next.worst === "" ? null : cueIconName(next.worst));
-      }
-    },
-  };
-}
-
-/** iconVariantHref rewrites an icon URL to its variant, by the naming convention
- *  the variant assets must follow (they are the consuming app's own files, served
- *  alongside its icons rather than shipped by this library): the `favicon` token
- *  of the filename gains `-<variant>`, so `/favicon.svg` becomes
- *  `/favicon-input.svg` and `/favicon-32x32.png` becomes
- *  `/favicon-input-32x32.png`. The extension is preserved, so each link keeps
- *  pointing at its own format and no `type` attribute has to change.
- *
- *  A URL whose filename does not start with `favicon` is returned unchanged,
- *  which leaves that link alone rather than pointing it at a 404. Exported for
- *  the test that pins this against that naming convention. */
-export function iconVariantHref(href: string, variant: string): string | null {
-  const match = /(^|\/)favicon(?=[-.])/.exec(href);
-  if (!match) {
-    return null;
-  }
-  const at = match.index + match[0].length;
-  return `${href.slice(0, at)}-${variant}${href.slice(at)}`;
-}
-
-/** browserAttentionEnv binds the sinks to the real browser, given the kernel's
- *  title setter. Everything optional is decided HERE, once, so the core never
- *  probes for a capability.
- *
- *  `icons` opts the icon sink in. It is off unless the consumer asks for it,
- *  because it needs asset files the library cannot ship: the dot's colour comes
- *  from the app's own `--status-*` theme, so the variants are per-app artifacts.
- */
-export function browserAttentionEnv(
-  titlePrefix: (text: string) => void,
-  icons: boolean,
-): AttentionEnv {
-  const env: AttentionEnv = { titlePrefix };
-
-  // The Badging API, read through `unknown` for the same reason notify.ts reads
-  // Notification that way: it is absent on most browsers and must degrade rather
-  // than be asserted. Installed apps only — a badge lives on an app icon, which
-  // exists only after the app is installed.
-  const nav: unknown = globalThis.navigator;
-  const setAppBadge = (nav as { setAppBadge?: unknown } | undefined)?.setAppBadge;
-  const clearAppBadge = (nav as { clearAppBadge?: unknown } | undefined)?.clearAppBadge;
-  if (typeof setAppBadge === "function") {
-    env.setBadge = (count: number): void => {
-      // Always a NUMBER, never the spec's bare flag form: iOS renders nothing at
-      // all for `setAppBadge()` with no argument. Zero clears, via clearAppBadge
-      // where it exists (the documented way) and setAppBadge(0) otherwise.
-      //
-      // Both return promises that reject on an unsupported platform, so the
-      // rejection is swallowed: a badge the OS declines to paint is not an error
-      // this page can do anything about, and an unhandled rejection in a status
-      // sweep would be reported as a page fault.
-      try {
-        const call =
-          count > 0
-            ? (setAppBadge as (n: number) => unknown).call(nav, count)
-            : typeof clearAppBadge === "function"
-              ? (clearAppBadge as () => unknown).call(nav)
-              : (setAppBadge as (n: number) => unknown).call(nav, 0);
-        void Promise.resolve(call).catch(() => {
-          /* an OS that will not paint a badge is a title-only OS */
-        });
-      } catch {
-        /* a synchronous throw is the same non-event */
-      }
-    };
-  }
-
-  if (icons) {
-    // Every icon link, not one of them: which link a browser picks differs
-    // between browsers (Chrome prefers the SVG), so mutating a single element is
-    // unreliable. apple-touch-icon is deliberately NOT matched — `rel~="icon"`
-    // does not select it — because that icon and the manifest's are cached by the
-    // OS when the app is installed and a swap cannot reach them.
-    const links = [...document.querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')];
-    const originals = new Map<HTMLLinkElement, string>();
-    for (const link of links) {
-      originals.set(link, link.getAttribute("href") ?? "");
-    }
-    if (links.length > 0) {
-      env.setIcon = (variant): void => {
-        for (const link of links) {
-          const original = originals.get(link) ?? "";
-          if (variant === null) {
-            link.setAttribute("href", original);
-            continue;
-          }
-          const next = iconVariantHref(original, variant);
-          if (next !== null) {
-            link.setAttribute("href", next);
-          }
-        }
-      };
-    }
-  }
-
-  return env;
-}