@cplieger/web-terminal-ui 7.3.2 → 8.0.0

package/src/kernel/attention.ts

@@ -0,0 +1,157 @@
+import type { AttentionOptions, AttentionReporter, AttentionState } from "./types.js";
+
+const NO_ATTENTION: AttentionState = { count: 0, icon: null };
+
+/** The sinks a render writes, every one injected. An absent optional sink is a
+ *  silent no-op: an unsupported surface is a normal state of the world. Two can
+ *  also fail INVISIBLY (`setBadge` resolves on a desktop that paints no badge,
+ *  `setIcon` assigns an href Safari ignores), which is why the title is gated on
+ *  no capability and is the floor: never arrange these as a fallback ladder. */
+export interface AttentionSinks {
+  /** Set the mark the document title starts with, or clear it with "". */
+  setTitleMark: (text: string) => void;
+  setBadge?: ((count: number) => void) | undefined;
+  setIcon?: ((variant: string | null) => void) | undefined;
+}
+
+/** The reporter plus its release. */
+export interface AttentionSurface extends AttentionReporter {
+  /** Restore every surface and stop following the page lifecycle. */
+  dispose(): void;
+}
+
+/** The count goes FIRST because a browser tab strip truncates a title to its
+ *  first few characters; parenthesised digits are the convention every mail and
+ *  chat client uses, so it needs no legend. */
+export function titleMarkFor(count: number): string {
+  return count > 0 ? `(${String(count)}) ` : "";
+}
+
+/** iconVariantHref rewrites an icon URL to its variant: the `favicon` token of
+ *  the filename gains `-<variant>`, keeping the extension so each link keeps its
+ *  own format. Null for a filename that does not start with `favicon`, which
+ *  leaves that link alone rather than pointing it at a 404. */
+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)}`;
+}
+
+/** Render reports onto `sinks`, change-gated on the last rendered value: the
+ *  title doubles as the browser-tab label and the bookmark name, and
+ *  re-assigning an icon href makes some browsers re-fetch it. `pagehide` restores
+ *  the surfaces (a browser remembers ONE icon per URL for the bookmark and the
+ *  history row, so a tab closed on a lit cue would leave a status variant standing
+ *  in for the app), `pageshow` repaints the last report for a page that came back
+ *  from the back-forward cache, and `freeze` changes nothing because a frozen tab
+ *  is still in the strip rendering its icon. */
+export function createAttention(sinks: AttentionSinks, win: Window): AttentionSurface {
+  let reported: AttentionState = NO_ATTENTION;
+  let rendered: AttentionState | null = null;
+
+  function render(next: AttentionState): void {
+    const countChanged = next.count !== rendered?.count;
+    const iconChanged = next.icon !== rendered?.icon;
+    rendered = next;
+    if (countChanged) {
+      sinks.setTitleMark(titleMarkFor(next.count));
+      sinks.setBadge?.(next.count);
+    }
+    if (iconChanged) {
+      sinks.setIcon?.(next.icon);
+    }
+  }
+
+  function onPageGone(): void {
+    render(NO_ATTENTION);
+  }
+  function onPageBack(): void {
+    render(reported);
+  }
+  const listeners = new AbortController();
+  const { signal } = listeners;
+  try {
+    win.addEventListener("pagehide", onPageGone, { signal });
+    win.addEventListener("pageshow", onPageBack, { signal });
+  } catch (err) {
+    listeners.abort();
+    throw err;
+  }
+
+  return {
+    report(state) {
+      reported = state;
+      render(state);
+    },
+    dispose() {
+      listeners.abort();
+      render(NO_ATTENTION);
+    },
+  };
+}
+
+/** Bind the sinks to `doc`'s browser realm. Every capability decision is made
+ *  HERE, once, so the render never probes. */
+export function browserAttentionSinks(
+  setTitleMark: (text: string) => void,
+  opts: AttentionOptions,
+  doc: Document,
+): AttentionSinks {
+  const sinks: AttentionSinks = { setTitleMark };
+
+  // Read through `unknown` because the Badging API is absent on most browsers
+  // and exists only on an installed app's icon.
+  const nav: unknown = doc.defaultView?.navigator;
+  const setAppBadge = (nav as { setAppBadge?: unknown } | undefined)?.setAppBadge;
+  const clearAppBadge = (nav as { clearAppBadge?: unknown } | undefined)?.clearAppBadge;
+  if (typeof setAppBadge === "function") {
+    sinks.setBadge = (count: number): void => {
+      // Always a NUMBER, never the spec's bare flag form: iOS renders nothing for
+      // `setAppBadge()` with no argument. Zero clears through clearAppBadge where
+      // it exists and setAppBadge(0) otherwise (Chrome shipped the former later).
+      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);
+        // A rejection is an OS that will not paint a badge, not a page fault.
+        void Promise.resolve(call).catch(() => undefined);
+      } catch {
+        /* a synchronous throw is the same non-event */
+      }
+    };
+  }
+
+  if (opts.icons) {
+    // Every icon link, because which one a browser picks differs (Chrome prefers
+    // the SVG). `rel~="icon"` deliberately skips apple-touch-icon: the OS caches
+    // it at install time, so a swap cannot reach it.
+    const links = [...doc.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) {
+      sinks.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 sinks;
+}

package/src/kernel/conn-state.ts

@@ -1,17 +1,3 @@
-// Connection-state machine (kernel-owned, design section 22.3). The state, the
-// never-connects give-up, and the loading lifecycle are kernel; the visible
-// banner is the connectionBanner feature, which renders whatever state this
-// emits. This is the DOM-free half of the old status.ts (its banner/toast
-// rendering became the connectionBanner feature and the kernel toast surface).
-//
-// State machine:
-//   open         -> no banner.
-//   connecting   -> "Reconnecting..." (initial connect, before first open).
-//   reconnecting -> "Reconnecting..." (after a close, during retry);
-//                   escalates to offline after >3 consecutive failures.
-//   offline      -> "Offline".
-//   restarted    -> "Server restarted - recent input may have been lost".
-
 import type { ConnState } from "./types.js";
 
 const CONNECTING_GRACE_MS = 600;
@@ -41,6 +27,9 @@ export interface ConnStateMachine {
   /** The engine refused an explicitly incompatible wire revision. This
    *  terminal state bypasses the loading gate and persists until open(). */
   incompatible(): void;
+  /** The pane holds no session: nothing is connecting and nothing is retrying.
+   *  Left by open() on the next attach. */
+  idle(): void;
   /** First screen frame rendered: the loading overlay is done, so the banner
    *  may show reconnect state from here on. */
   setLoaded(): void;
@@ -50,13 +39,22 @@ export interface ConnStateMachine {
   destroy(): void;
 }
 
+/** The timers the machine schedules on: the mounted window's, so a grace delay
+ *  runs on the terminal's own clock. */
+export interface ConnStateTimers {
+  setTimeout(handler: () => void, ms: number): number;
+  clearTimeout(id: number): void;
+}
+
 export function createConnState(opts: {
   onState: (s: ConnState) => void;
   onGiveUp?: () => void;
+  timers: ConnStateTimers;
 }): ConnStateMachine {
+  const { timers } = opts;
   let state: ConnState = "connecting";
-  let stableTimer: ReturnType<typeof setTimeout> | null = null;
-  let restartedTimer: ReturnType<typeof setTimeout> | null = null;
+  let stableTimer: number | null = null;
+  let restartedTimer: number | null = null;
   let consecutiveFailures = 0;
   let loaded = false;
 
@@ -79,7 +77,7 @@ export function createConnState(opts: {
 
   function setState(next: ConnState, delay: number): void {
     if (stableTimer !== null) {
-      clearTimeout(stableTimer);
+      timers.clearTimeout(stableTimer);
       stableTimer = null;
     }
     if (delay === 0) {
@@ -87,7 +85,7 @@ export function createConnState(opts: {
       emit();
       return;
     }
-    stableTimer = setTimeout(() => {
+    stableTimer = timers.setTimeout(() => {
       stableTimer = null;
       state = next;
       emit();
@@ -118,9 +116,9 @@ export function createConnState(opts: {
     restarted(): void {
       setState("restarted", 0);
       if (restartedTimer !== null) {
-        clearTimeout(restartedTimer);
+        timers.clearTimeout(restartedTimer);
       }
-      restartedTimer = setTimeout(() => {
+      restartedTimer = timers.setTimeout(() => {
         restartedTimer = null;
         if (state === "restarted") {
           setState("open", 0);
@@ -140,6 +138,14 @@ export function createConnState(opts: {
       consecutiveFailures = 0;
       setState("incompatible", 0);
     },
+    idle(): void {
+      consecutiveFailures = 0;
+      if (restartedTimer !== null) {
+        timers.clearTimeout(restartedTimer);
+        restartedTimer = null;
+      }
+      setState("idle", 0);
+    },
     setLoaded(): void {
       loaded = true;
     },
@@ -148,11 +154,11 @@ export function createConnState(opts: {
     },
     destroy(): void {
       if (stableTimer !== null) {
-        clearTimeout(stableTimer);
+        timers.clearTimeout(stableTimer);
         stableTimer = null;
       }
       if (restartedTimer !== null) {
-        clearTimeout(restartedTimer);
+        timers.clearTimeout(restartedTimer);
         restartedTimer = null;
       }
     },

package/src/kernel/fatal.ts

@@ -0,0 +1,76 @@
+import { STARTUP_FAILURE_COPY } from "./startup-copy.js";
+import { reloadPage } from "./navigation.js";
+import { windowOf } from "./realm.js";
+
+/** Fade out and remove a consumer-supplied loading overlay. */
+export function fadeOutOverlay(ld: HTMLElement | undefined): void {
+  if (!ld) {
+    return;
+  }
+  ld.classList.add("fade");
+  const removeOverlay = (): void => {
+    ld.remove();
+  };
+  ld.addEventListener("transitionend", removeOverlay, { once: true });
+  windowOf(ld.ownerDocument).setTimeout(removeOverlay, 1500);
+}
+
+export interface FatalPanelOptions {
+  message?: string;
+  /** `showModal()` (the terminal IS the page) or the bare `open` attribute (an
+   *  embedded panel, or a pane beside a live one). */
+  modal: boolean;
+  /** Appended to the panel's two element ids, so two panels in one document keep
+   *  their `aria-labelledby` targets unique. */
+  idSuffix?: string;
+}
+
+/** Render the "Terminal failed to start" panel into `root`, replacing its children. */
+export function renderFatalStartupInto(root: HTMLElement, opts: FatalPanelOptions): void {
+  const suffix = opts.idSuffix ?? "";
+  const doc = root.ownerDocument;
+  const surface = doc.createElement("dialog");
+  surface.className = "wt-fatal";
+  // alertdialog over the implicit `dialog` role: an urgent message to act on. No
+  // `aria-modal`: showModal() conveys modality, and an authored value can
+  // contradict the UA.
+  surface.setAttribute("role", "alertdialog");
+  surface.setAttribute("aria-labelledby", `wt-fatal-title${suffix}`);
+  surface.setAttribute("aria-describedby", `wt-fatal-message${suffix}`);
+  // Nothing is behind this panel, so reload is the only recovery; Escape must not
+  // close it.
+  surface.addEventListener("cancel", (ev) => {
+    ev.preventDefault();
+  });
+
+  const card = doc.createElement("div");
+  card.className = "wt-fatal-card";
+  const title = doc.createElement("h2");
+  title.id = `wt-fatal-title${suffix}`;
+  title.className = "wt-fatal-title";
+  title.textContent = STARTUP_FAILURE_COPY.title;
+  const messageEl = doc.createElement("p");
+  messageEl.id = `wt-fatal-message${suffix}`;
+  messageEl.className = "wt-fatal-message";
+  messageEl.textContent = opts.message ?? STARTUP_FAILURE_COPY.message;
+  const reloadButton = doc.createElement("button");
+  reloadButton.className = "wt-btn wt-fatal-reload";
+  reloadButton.type = "button";
+  reloadButton.textContent = STARTUP_FAILURE_COPY.reloadLabel;
+  reloadButton.addEventListener("click", () => {
+    reloadPage(windowOf(doc));
+  });
+  card.append(title, messageEl, reloadButton);
+  surface.appendChild(card);
+  root.replaceChildren(surface);
+
+  // showModal() requires a connected element in a document that has a window; a
+  // detached root or a created document arrives here from a typed call, where a
+  // throw would bury the real startup cause.
+  if (opts.modal && surface.isConnected && doc.defaultView !== null) {
+    surface.showModal();
+  } else {
+    surface.open = true;
+  }
+  reloadButton.focus();
+}

package/src/kernel/feature-host.ts

@@ -0,0 +1,136 @@
+import type { FeatureInstance, TerminalContext, TerminalFeature, Unsubscribe } from "./types.js";
+
+/** Releases run last-in first-out: what one feature acquired, or what a pane or
+ *  the shell holds. */
+export interface CleanupScope {
+  /** Hold `release` until the drain. After the drain it runs at once, so a setup
+   *  still running past its owner's teardown cannot leave anything behind. */
+  push(release: Unsubscribe): void;
+  drain(): void;
+}
+
+export function createCleanupScope(reportError: (err: unknown) => void): CleanupScope {
+  const releases: Unsubscribe[] = [];
+  let drained = false;
+  const run = (release: Unsubscribe): void => {
+    try {
+      release();
+    } catch (err) {
+      reportError(err);
+    }
+  };
+  return {
+    push(release) {
+      if (drained) {
+        run(release);
+        return;
+      }
+      releases.push(release);
+    },
+    drain() {
+      drained = true;
+      while (releases.length > 0) {
+        const release = releases.pop();
+        if (release) {
+          run(release);
+        }
+      }
+    },
+  };
+}
+
+export type FeatureSetupOutcome =
+  | { readonly status: "ready" }
+  | { readonly status: "aborted" }
+  | { readonly status: "failed"; readonly feature: string; readonly cause: unknown };
+
+interface Entry {
+  readonly feature: TerminalFeature<unknown>;
+  readonly instance: FeatureInstance<unknown>;
+  readonly scope: CleanupScope;
+}
+
+export interface FeatureHost {
+  /** Set one feature up. The scope exists before `setup` runs, so a throw drains
+   *  what the feature acquired; a `destroyed()` true after the await tears the
+   *  instance down instead of registering it. */
+  setup(
+    feature: TerminalFeature<unknown>,
+    makeContext: (scope: CleanupScope) => TerminalContext,
+    destroyed: () => boolean,
+  ): Promise<FeatureSetupOutcome>;
+  /** The set-up instances, in setup order. */
+  instances(): readonly FeatureInstance<unknown>[];
+  /** The api of a set-up feature, or undefined. */
+  use(feature: TerminalFeature<unknown>): unknown;
+  /** The scope of every setup still pending, then every instance's `teardown()`
+   *  in reverse order, each followed by its scope. */
+  teardownAll(): void;
+}
+
+export function createFeatureHost(
+  reportError: (feature: string, err: unknown) => void,
+): FeatureHost {
+  const entries: Entry[] = [];
+  const pending = new Set<CleanupScope>();
+  const apiMap = new Map<TerminalFeature<unknown>, unknown>();
+
+  return {
+    async setup(feature, makeContext, destroyed) {
+      // A feature enters `entries` only after `setup` returns, so the scope is
+      // the one owner of what a throwing or still-pending `setup` acquired.
+      const scope = createCleanupScope((err) => {
+        reportError(feature.name, err);
+      });
+      pending.add(scope);
+      try {
+        const instance = await feature.setup(makeContext(scope));
+        pending.delete(scope);
+        if (destroyed()) {
+          try {
+            instance.teardown();
+          } catch (err) {
+            reportError(feature.name, err);
+          }
+          scope.drain();
+          return { status: "aborted" };
+        }
+        entries.push({ feature, instance, scope });
+        (feature as { api?: unknown }).api = instance.api;
+        apiMap.set(feature, instance.api);
+      } catch (cause) {
+        pending.delete(scope);
+        scope.drain();
+        if (destroyed()) {
+          return { status: "aborted" };
+        }
+        reportError(feature.name, cause);
+        console.error(`web-terminal-ui: feature "${feature.name}" setup failed`, cause);
+        return { status: "failed", feature: feature.name, cause };
+      }
+      return { status: "ready" };
+    },
+    instances: () => entries.map((e) => e.instance),
+    use: (feature) => apiMap.get(feature),
+    teardownAll() {
+      for (const scope of pending) {
+        scope.drain();
+      }
+      pending.clear();
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!entry) {
+          continue;
+        }
+        try {
+          entry.instance.teardown();
+        } catch (err) {
+          reportError(entry.feature.name, err);
+        }
+        entry.scope.drain();
+      }
+      entries.length = 0;
+      apiMap.clear();
+    },
+  };
+}

package/src/kernel/gesture.ts

@@ -16,17 +16,13 @@ export const TAP_MOVEMENT_PX = 10;
  *  belongs to native text selection or the context menu. */
 export const TAP_MAX_MS = 500;
 
-/**
- * Whether a press landed on a LINK, in which case neither handler claims it: the
- * platform's own link affordances (preview on hold, activate on tap) win.
- *
- * Shared for the same reason the thresholds are, and it was NOT: the kernel
- * matched `.term-link` only while the menu matched `a[href], .term-link`, so an
- * ordinary anchor in the output was a link to one half of the boundary and not the
- * other — the menu stood down for the platform while tap-to-focus stole the press.
- * `.term-link` is the engine linkifier's class; `a[href]` covers anchors a consumer
- * or an application wrote itself.
- */
-export function isLinkTarget(target: EventTarget | null): boolean {
-  return target instanceof Element && target.closest("a[href], .term-link") !== null;
+/** Whether a press landed on a LINK, in which case neither handler claims it:
+ *  the platform's own link affordances (preview on hold, activate on tap) win.
+ *  One matcher for both halves of the boundary: the kernel once matched
+ *  `.term-link` (the engine linkifier's class) while the menu also matched
+ *  `a[href]`, so an ordinary anchor was a link to one half and not the other.
+ *  `win` is the target's own realm: an element from another document is not an
+ *  `Element` of the importing one. */
+export function isLinkTarget(win: Window & typeof globalThis, target: EventTarget | null): boolean {
+  return target instanceof win.Element && target.closest("a[href], .term-link") !== null;
 }