@cplieger/web-terminal-ui 2.1.4 → 3.0.1

package/src/index.ts

@@ -1,11 +1,32 @@
-// @cplieger/web-terminal-ui — the reference touch-first browser UI built on
-// the @cplieger/web-terminal-engine engine. The public surface is a single
-// mount(root) call that builds the whole terminal subtree inside a
-// host-provided element; scaffold/index.html + css/ are a reference page to copy.
+// @cplieger/web-terminal-ui — the reference touch-first browser UI built on the
+// @cplieger/web-terminal-engine engine.
 //
-// Consumers who want a different UI should depend on @cplieger/web-terminal-engine
-// directly and wire the engine's render/scroll/connection/keyboard modules
-// to their own DOM.
+// 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 { mount } from "./mount.js";
-export type { MountOptions, TerminalUI } from "./mount.js";
+export { createTerminal } from "./kernel/kernel.js";
+export type {
+  CreateTerminalOptions,
+  TerminalHandle,
+  TerminalFeature,
+  FeatureInstance,
+  TerminalContext,
+  TerminalEvents,
+  RegionName,
+  RegionSlot,
+  RenderHandle,
+  ScrollHandle,
+  SessionRef,
+  SessionView,
+  ConnState,
+  TablistController,
+  TabHandle,
+  Unsubscribe,
+} from "./kernel/types.js";

package/src/kernel/a11y.ts

@@ -0,0 +1,102 @@
+// 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.
+
+import type { TablistController, TabHandle } from "./types.js";
+
+/** Visually-hidden style applied inline so it holds without external CSS
+ *  (tests run without the stylesheet). Standard sr-only clip technique. */
+function hideVisually(el: HTMLElement): void {
+  const s = el.style;
+  s.position = "absolute";
+  s.width = "1px";
+  s.height = "1px";
+  s.margin = "-1px";
+  s.padding = "0";
+  s.overflow = "hidden";
+  s.clipPath = "inset(50%)";
+  s.whiteSpace = "nowrap";
+  s.border = "0";
+}
+
+export interface Announcer {
+  announce(message: string, politeness?: "polite" | "assertive"): void;
+  destroy(): void;
+}
+
+/** Build the single pair of live regions inside root. */
+export function createAnnouncer(root: HTMLElement): Announcer {
+  const polite = document.createElement("div");
+  polite.setAttribute("aria-live", "polite");
+  polite.setAttribute("aria-atomic", "true");
+  hideVisually(polite);
+  const assertive = document.createElement("div");
+  assertive.setAttribute("aria-live", "assertive");
+  assertive.setAttribute("aria-atomic", "true");
+  hideVisually(assertive);
+  root.append(polite, assertive);
+
+  function announce(message: string, politeness: "polite" | "assertive" = "polite"): void {
+    const el = politeness === "assertive" ? assertive : polite;
+    // Clear then set on the next frame so a repeat of the same message is
+    // re-announced (screen readers ignore an unchanged live-region value).
+    el.textContent = "";
+    requestAnimationFrame(() => {
+      el.textContent = message;
+    });
+  }
+
+  function destroy(): void {
+    polite.remove();
+    assertive.remove();
+  }
+
+  return { announce, destroy };
+}
+
+let panelSeq = 0;
+let tabSeq = 0;
+
+/** Wire the ARIA tablist/tabpanel seam on the kernel's output surface. */
+export function createTablist(panel: HTMLElement): TablistController {
+  panelSeq += 1;
+  const panelId = panel.id || `wt-panel-${String(panelSeq)}`;
+  panel.id = panelId;
+  panel.setAttribute("role", "tabpanel");
+
+  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");
+
+    return {
+      setSelected(selected: boolean): void {
+        tab.setAttribute("aria-selected", selected ? "true" : "false");
+        if (selected) {
+          // The panel is labelled by whichever tab is currently selected.
+          panel.setAttribute("aria-labelledby", tabId);
+        }
+      },
+      setLabel(text: string): void {
+        tab.setAttribute("aria-label", text);
+      },
+      remove(): void {
+        tab.removeAttribute("role");
+        tab.removeAttribute("aria-controls");
+        tab.removeAttribute("aria-selected");
+        if (panel.getAttribute("aria-labelledby") === tabId) {
+          panel.removeAttribute("aria-labelledby");
+        }
+      },
+    };
+  }
+
+  return {
+    panelId: () => panelId,
+    registerTab,
+  };
+}

package/src/kernel/bus.ts

@@ -0,0 +1,61 @@
+// Typed event bus for the kernel/feature contract. A small pub/sub keyed by the
+// TerminalEvents map, so a subscriber gets the exact payload type for its event
+// and the kernel emits with the same guarantee (no `unknown`, section 22.4).
+//
+// The bus itself does not attribute errors to features; the kernel wraps each
+// feature's ctx.on handler with a try/catch that routes to ctx.onError with the
+// feature name, so a throwing handler is isolated and named there.
+
+import type { TerminalEvents, Unsubscribe } from "./types.js";
+
+/** A typed event bus over TerminalEvents. */
+export interface TypedBus {
+  on<K extends keyof TerminalEvents>(e: K, fn: (p: TerminalEvents[K]) => void): Unsubscribe;
+  emit<K extends keyof TerminalEvents>(e: K, p: TerminalEvents[K]): void;
+  /** Drop every listener (used on kernel destroy). */
+  clear(): void;
+}
+
+// A handler for any event. `(p: never) => void` is the bottom of the
+// contravariant handler lattice: every concrete `(p: TerminalEvents[K]) => void`
+// is assignable to it, so one Set can hold handlers for a single key uniformly.
+// The exact payload type is recovered with a single controlled cast at emit.
+type AnyHandler = (p: never) => void;
+
+export function createBus(): TypedBus {
+  const listeners = new Map<keyof TerminalEvents, Set<AnyHandler>>();
+
+  function on<K extends keyof TerminalEvents>(
+    e: K,
+    fn: (p: TerminalEvents[K]) => void,
+  ): Unsubscribe {
+    let set = listeners.get(e);
+    if (!set) {
+      set = new Set<AnyHandler>();
+      listeners.set(e, set);
+    }
+    set.add(fn);
+    return () => {
+      listeners.get(e)?.delete(fn);
+    };
+  }
+
+  function emit<K extends keyof TerminalEvents>(e: K, p: TerminalEvents[K]): void {
+    const set = listeners.get(e);
+    if (!set) {
+      return;
+    }
+    // Snapshot so a handler that subscribes/unsubscribes during dispatch does
+    // not mutate the set we are iterating. The cast recovers the payload type
+    // this key's handlers were registered with.
+    for (const fn of [...set]) {
+      (fn as (p: TerminalEvents[K]) => void)(p);
+    }
+  }
+
+  function clear(): void {
+    listeners.clear();
+  }
+
+  return { on, emit, clear };
+}

package/src/kernel/conn-state.ts

@@ -0,0 +1,133 @@
+// 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;
+
+// Consecutive failed initial connects (before the first screen frame) after
+// which "Offline" is allowed through even while the loading overlay is up, so a
+// never-connecting page does not sit on a silent "Loading..." forever. Aligned
+// with the post-load escalation threshold (>3).
+const INITIAL_FAILURE_LIMIT = 4;
+
+const RESTARTED_CLEAR_MS = 4000;
+
+export interface ConnStateMachine {
+  /** Connection opened. */
+  open(): void;
+  /** Reconnect attempt in progress. */
+  reconnecting(): void;
+  /** Connection closed / outbox full. */
+  closed(): void;
+  /** Server restarted (epoch mismatch); recent input may be lost. */
+  restarted(): void;
+  /** First screen frame rendered: the loading overlay is done, so the banner
+   *  may show reconnect state from here on. */
+  setLoaded(): void;
+  /** Current state. */
+  current(): ConnState;
+  /** Clear timers (kernel destroy). */
+  destroy(): void;
+}
+
+export function createConnState(opts: {
+  onState: (s: ConnState) => void;
+  onGiveUp?: () => void;
+}): ConnStateMachine {
+  let state: ConnState = "connecting";
+  let stableTimer: ReturnType<typeof setTimeout> | null = null;
+  let restartedTimer: ReturnType<typeof setTimeout> | null = null;
+  let consecutiveFailures = 0;
+  let loaded = false;
+
+  function emit(): void {
+    // Suppress transient states until the initial load is over (the loading
+    // overlay owns the screen), except "offline" once the initial-failure limit
+    // is reached. connectionBanner renders "open" as hidden.
+    if (!loaded && !(state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT)) {
+      opts.onState("open"); // nothing to show yet
+      return;
+    }
+    opts.onState(state);
+  }
+
+  function setState(next: ConnState, delay: number): void {
+    if (stableTimer !== null) {
+      clearTimeout(stableTimer);
+      stableTimer = null;
+    }
+    if (delay === 0) {
+      state = next;
+      emit();
+      return;
+    }
+    stableTimer = setTimeout(() => {
+      stableTimer = null;
+      state = next;
+      emit();
+    }, delay);
+  }
+
+  return {
+    open(): void {
+      consecutiveFailures = 0;
+      setState("open", 0);
+    },
+    reconnecting(): void {
+      if (!loaded) {
+        return;
+      }
+      setState("reconnecting", CONNECTING_GRACE_MS);
+    },
+    closed(): void {
+      consecutiveFailures++;
+      if (!loaded && consecutiveFailures < INITIAL_FAILURE_LIMIT) {
+        return;
+      }
+      if (!loaded) {
+        opts.onGiveUp?.();
+      }
+      setState(consecutiveFailures > 3 ? "offline" : "reconnecting", CONNECTING_GRACE_MS);
+    },
+    restarted(): void {
+      setState("restarted", 0);
+      if (restartedTimer !== null) {
+        clearTimeout(restartedTimer);
+      }
+      restartedTimer = setTimeout(() => {
+        restartedTimer = null;
+        if (state === "restarted") {
+          setState("open", 0);
+        }
+      }, RESTARTED_CLEAR_MS);
+    },
+    setLoaded(): void {
+      loaded = true;
+    },
+    current(): ConnState {
+      return state;
+    },
+    destroy(): void {
+      if (stableTimer !== null) {
+        clearTimeout(stableTimer);
+        stableTimer = null;
+      }
+      if (restartedTimer !== null) {
+        clearTimeout(restartedTimer);
+        restartedTimer = null;
+      }
+    },
+  };
+}