@cplieger/web-terminal-ui 7.2.2 → 7.3.1

package/src/features/context-menu.ts

@@ -1,51 +1,55 @@
-// contextMenu feature: the Copy / Select All / Paste menu for the terminal
-// surface (design section 22.4), rendered into the overlay region. Copy and Paste
-// need the clipboard feature (ctx.use), and Paste routes through the kernel's
-// sanitizing funnel. Escape-to-close goes through the kernel keydown intercept;
-// outside-click is a document gesture.
-//
-// WHY THIS MENU EXISTS
-// The terminal output is real DOM text, so the browser already does the hard
-// part: drag-select with a mouse, long-press word-select plus the OS copy callout
-// on touch. What no platform can offer is PASTE — the keyboard target is a 1x1
-// pointer-events:none textarea, so there is no editable surface under the pointer
-// for a native paste item to attach to. This menu is the paste path. It carries
-// Copy and Select All because a menu appearing where the platform's would have
-// appeared should not be missing them.
-//
-// THE MODEL: one owner per gesture, and nothing decided mid-gesture.
-//
-//   Mouse / pen — `contextmenu` is an already-classified request for a menu:
-//   preventDefault and open at the pointer. No timers, no heuristics, no
-//   platform branches.
-//
-//   Touch — the platform owns the press while the finger is down. We run no hold
-//   timer against it, open nothing before it finishes, and never cancel its
-//   gesture on WebKit. We classify ONCE, on `touchend`, when every fact is
-//   settled: a single-finger, stationary press held past the tap ceiling
-//   (kernel/gesture.ts, shared with the kernel's tap-to-focus so the two cannot
-//   both claim one press) that selected nothing and did not start on a link is a
-//   press the platform declined — so it is ours, and it is the paste path. A
-//   press that produced a selection belongs to the OS callout; a press on a link
-//   belongs to the platform's link preview; a shorter press is the kernel's tap.
-//
-// WHY AT RELEASE RATHER THAN DURING THE HOLD
-// Opening from a ~550ms hold timer put this feature in a race it cannot win: the
-// timer has to beat the platform's own long-press threshold and then GUESS
-// whether a selection is still coming (iOS 26 registers a word selection well
-// after 550ms). Four mechanisms existed only to referee that guess — a hit test
-// for glyphs under the finger, a selectionchange watch to retract a menu that
-// opened too early, a device sniff, and per-platform contextmenu branching,
-// because WebKit reads preventDefault on a touch contextmenu as "cancel every
-// remaining default of this gesture", the not-yet-registered selection included.
-// Deciding at release deletes all four: the outcome is observed, not predicted.
-//
-// It also fixes the symptom that prompted the rewrite. A touch long-press emits a
-// trailing click on release, and the swallow window that covers that click was
-// armed when the menu OPENED — ~550ms into the press, expiring 350ms later — so
-// holding a beat longer meant the release click landed as an outside click and
-// dismissed the menu the instant the finger lifted. Opened BY the release, the
-// window can only ever start at the release edge.
+/**
+ * contextMenu feature: the Copy / Select All / Paste menu for the terminal
+ * surface, rendered into the overlay region. Copy and Paste
+ * need the clipboard feature (ctx.use), and Paste routes through the kernel's
+ * sanitizing funnel. Escape-to-close goes through the kernel keydown intercept;
+ * outside-click is a document gesture.
+ *
+ * WHY THIS MENU EXISTS
+ * The terminal output is real DOM text, so the browser already does the hard
+ * part: drag-select with a mouse, long-press word-select plus the OS copy callout
+ * on touch. What no platform can offer is PASTE — the keyboard target is a 1x1
+ * pointer-events:none textarea, so there is no editable surface under the pointer
+ * for a native paste item to attach to. This menu is the paste path. It carries
+ * Copy and Select All because a menu appearing where the platform's would have
+ * appeared should not be missing them.
+ *
+ * THE MODEL: one owner per gesture, and nothing decided mid-gesture.
+ *
+ *   Mouse / pen — `contextmenu` is an already-classified request for a menu:
+ *   preventDefault and open at the pointer. No timers, no heuristics, no
+ *   platform branches.
+ *
+ *   Touch — the platform owns the press while the finger is down. We run no hold
+ *   timer against it, open nothing before it finishes, and never cancel its
+ *   gesture on WebKit. We classify ONCE, on `touchend`, when every fact is
+ *   settled: a single-finger, stationary press held past the tap ceiling
+ *   (kernel/gesture.ts, shared with the kernel's tap-to-focus so the two cannot
+ *   both claim one press) that selected nothing and did not start on a link is a
+ *   press the platform declined — so it is ours, and it is the paste path. A
+ *   press that produced a selection belongs to the OS callout; a press on a link
+ *   belongs to the platform's link preview; a shorter press is the kernel's tap.
+ *
+ * WHY AT RELEASE RATHER THAN DURING THE HOLD
+ * Opening from a ~550ms hold timer put this feature in a race it cannot win: the
+ * timer has to beat the platform's own long-press threshold and then GUESS
+ * whether a selection is still coming (iOS 26 registers a word selection well
+ * after 550ms). Four mechanisms existed only to referee that guess — a hit test
+ * for glyphs under the finger, a selectionchange watch to retract a menu that
+ * opened too early, a device sniff, and per-platform contextmenu branching,
+ * because WebKit reads preventDefault on a touch contextmenu as "cancel every
+ * remaining default of this gesture", the not-yet-registered selection included.
+ * Deciding at release deletes all four: the outcome is observed, not predicted.
+ *
+ * It also fixes the symptom that prompted the rewrite. A touch long-press emits a
+ * trailing click on release, and the swallow window that covers that click was
+ * armed when the menu OPENED — ~550ms into the press, expiring 350ms later — so
+ * holding a beat longer meant the release click landed as an outside click and
+ * dismissed the menu the instant the finger lifted. Opened BY the release, the
+ * window can only ever start at the release edge.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { TAP_MAX_MS, TAP_MOVEMENT_PX, isLinkTarget } from "../kernel/gesture.js";
@@ -56,6 +60,12 @@ import { createClickSwallow, placeMenuAt } from "./menu-position.js";
 // swallow all live in the shared point-anchored menu module (menu-position.ts),
 // shared with the tab menu.
 
+/** Options for the contextMenu feature.
+ *
+ *  Pass the SAME clipboard feature value the composition includes, not a second
+ *  `clipboard()` call: `ctx.use` resolves a value to the instance the kernel set
+ *  up, so a value that is not in the feature list resolves to nothing and the
+ *  menu silently loses Copy and Paste. `presetSingle` shows the shape. */
 export interface ContextMenuOptions {
   /** The clipboard feature value, so the menu can offer Copy/Paste through its
    *  API (ctx.use). Omitted: the menu shows only Select All. */
@@ -109,6 +119,16 @@ function selectionText(): string {
  *  so the selection test alone would not keep us out of its way. */
 const onLink = isLinkTarget;
 
+/** Build the contextMenu feature. Exposes no API — the menu is opened by the
+ *  gestures described above, never programmatically by a peer.
+ *
+ *  Hand it the clipboard value the composition also includes (see
+ *  ContextMenuOptions) or it degrades to a Select All-only menu; its own position in
+ *  the feature list is otherwise free, since nothing reads it through `ctx.use`. Its
+ *  items act on the browser selection inside the terminal surface and on the
+ *  kernel's paste funnel, so it holds no session state and survives a tab switch
+ *  unchanged. Teardown removes the menu element and releases the keydown intercept
+ *  along with every surface and document listener. */
 export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
   return {
     name: "contextMenu",

package/src/features/mobile-toolbar.ts

@@ -1,10 +1,14 @@
-// mobileToolbar feature: the on-screen key toolbar (Tab/Esc/arrows/Enter + a
-// collapse toggle and sticky-Ctrl) in the thumb-zone region (design section
-// 22.4). The engine's toolbar.bindMobileToolbar wires the buttons (DECCKM-aware
-// arrows, sticky-Ctrl state; engine >= v3, where the widget moved out of the
-// keyboard module); this feature builds the toolbar chrome, routes its
-// output through the kernel funnel, and registers sticky-Ctrl as an input
-// transform so a typed character is rewritten to its Ctrl byte when armed.
+/**
+ * mobileToolbar feature: the on-screen key toolbar (Tab/Esc/arrows/Enter + a
+ * collapse toggle and sticky-Ctrl) in the thumb-zone region.
+ * The engine's toolbar.bindMobileToolbar wires the buttons (DECCKM-aware
+ * arrows, sticky-Ctrl state; engine >= v3, where the widget moved out of the
+ * keyboard module); this feature builds the toolbar chrome, routes its
+ * output through the kernel funnel, and registers sticky-Ctrl as an input
+ * transform so a typed character is rewritten to its Ctrl byte when armed.
+ *
+ * @module
+ */
 
 import { toolbar } from "@cplieger/web-terminal-engine";
 import type { TerminalFeature } from "../kernel/types.js";
@@ -52,6 +56,19 @@ const TOOLBAR_HTML = `
   <button type="button" id="kb-right" class="kb-key kb-r2c4" aria-label="Right"><svg viewBox="0 0 24 24"><polyline points="9 6 15 12 9 18"/></svg></button>
 </div>`;
 
+/** Build the mobileToolbar feature.
+ *
+ *  The chrome is always built; whether it is VISIBLE is a CSS decision — the keys
+ *  and the toggle are `display: none` and only a coarse pointer restores them
+ *  (`css/23-toolbar.css`) — so a desktop consumer including this feature pays the
+ *  DOM and sees nothing. Order it before `tabs` when `externalToggle` is set, since
+ *  tabs reads the returned API through `ctx.use` to drive the grid from the tab
+ *  bar's keyboard button.
+ *
+ *  Sticky-Ctrl is registered as a kernel INPUT TRANSFORM rather than handled in
+ *  the toolbar's own click path, so it rewrites a character typed on the soft
+ *  keyboard as well as one produced by these buttons. Teardown removes the
+ *  toolbar, drops the transform, and clears every subscriber. */
 export function mobileToolbar(opts: MobileToolbarOptions = {}): TerminalFeature<MobileToolbarApi> {
   return {
     name: "mobileToolbar",

package/src/features/predictive-echo.ts

@@ -1,13 +1,32 @@
-// predictiveEcho feature: Mosh-style local echo (design section 22.4). Wires the
-// predict.ts mini-VT to the kernel input funnel: it advances a predicted cursor
-// on accepted input (an input observer) and owns the col-0 backspace brake (an
-// input transform that drops a lone DEL at the true origin, since the predicted
-// cursor is the authoritative position for that decision). It re-pushes the
-// predicted-cursor overlay on prediction changes and after each render flush.
+/**
+ * predictiveEcho feature: Mosh-style local echo. Wires the
+ * predict.ts mini-VT to the kernel input funnel: it advances a predicted cursor
+ * on accepted input (an input observer) and owns the col-0 backspace brake (an
+ * input transform that drops a lone DEL at the true origin, since the predicted
+ * cursor is the authoritative position for that decision). It re-pushes the
+ * predicted-cursor overlay on prediction changes and after each render flush.
+ *
+ * @module
+ */
 
 import * as predict from "../predict.js";
 import type { TerminalFeature } from "../kernel/types.js";
 
+/** Build the predictiveEcho feature. Exposes no API — its output is the engine
+ *  renderer's predicted-cursor overlay.
+ *
+ *  The prediction state is MODULE-scoped (`../predict.js`), not per instance, so two
+ *  terminals in one page that both include this feature would drive one predicted
+ *  cursor between them. That is within the kernel's existing "call createTerminal
+ *  exactly once" contract, but it is the reason this feature cannot be made
+ *  per-instance by composing it twice.
+ *
+ *  Predictions are advisory: `predict` suspends itself on any byte it cannot
+ *  model, because a wrong prediction is worse than a missing one. The feature
+ *  resets it on a server restart and on a tab switch (`onDetach`), so the outgoing
+ *  session's ghost cursor never paints over the incoming session's screen; the
+ *  next server frame re-arms it. Teardown drops every listener, hides the overlay,
+ *  and clears the prediction. */
 export function predictiveEcho(): TerminalFeature {
   return {
     name: "predictiveEcho",

package/src/features/scroll-to-bottom.ts

@@ -1,8 +1,12 @@
-// scrollToBottom feature: a scroll-to-bottom control in the thumb-zone region,
-// shown only while the user has scrolled up (design section 22.4). The
-// scroll-state signal comes from the kernel's scroll:state event (the kernel
-// owns scroll.init); this feature just renders the affordance and drives
-// scroll.scrollToBottom.
+/**
+ * scrollToBottom feature: a scroll-to-bottom control in the thumb-zone region,
+ * shown only while the user has scrolled up. The
+ * scroll-state signal comes from the kernel's scroll:state event (the kernel
+ * owns scroll.init); this feature just renders the affordance and drives
+ * scroll.scrollToBottom.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { fromHTML, holdFocusOnPress } from "./dom.js";
@@ -12,6 +16,16 @@ const BUTTON_HTML = `
   <svg viewBox="0 0 24 24" aria-hidden="true"><path fill="none" d="M7 13l5 5 5-5M7 6l5 5 5-5"/></svg>
 </button>`;
 
+/** Build the scrollToBottom feature. Exposes no API — the button is the whole
+ *  surface, and a peer that wants the same effect calls `ctx.scroll.scrollToBottom`
+ *  directly.
+ *
+ *  Its job is resuming FOLLOW, not just moving the viewport, which is why it also
+ *  acts when the reader is already at the bottom but holding (an ED3 clamp leaves
+ *  exactly that state). The jump is smooth unless the user asked for reduced
+ *  motion, and it is idempotent, so binding both `pointerdown` (touch presses feel
+ *  immediate) and `click` (keyboard activation) is safe. Teardown unsubscribes and
+ *  removes the button. */
 export function scrollToBottom(): TerminalFeature {
   return {
     name: "scrollToBottom",

package/src/features/tabs/attention.ts

@@ -151,9 +151,9 @@ export function createAttention(env: AttentionEnv): AttentionSurfaces {
   };
 }
 
-/** iconVariantHref rewrites an icon URL to its variant, by the convention the
- *  asset generator writes (the fleet's .kiro/scripts/gen-attention-icons.py, which
- *  serves every consuming app rather than living in this repo): the `favicon` token
+/** 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
@@ -161,7 +161,7 @@ export function createAttention(env: AttentionEnv): AttentionSurfaces {
  *
  *  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 the generator's own naming. */
+ *  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) {

package/src/features/tabs/index.ts

@@ -1,12 +1,16 @@
-// tabs feature: multiple independent terminals over the one kernel (design
-// sections 5, 6, 12, 22.5). It owns the session set (GET/POST/DELETE
-// /api/sessions), a per-tab LineStore switching cache, the reconnect-on-switch
-// swap, and the tab chrome on both form factors: the desktop top-bar strip and
-// the mobile bottom-switcher + modal overview sheet. The kernel drives one
-// active session; switching re-points the renderer at the next tab's cached
-// store (ctx.render.bind) and asks the kernel to reconnect the terminal WS to it
-// (ctx.notifySwitch), so the last-known screen paints instantly and the
-// background delta arrives after.
+/**
+ * tabs feature: multiple independent terminals over the one kernel.
+ * It owns the session set (GET/POST/DELETE
+ * /api/sessions), a per-tab LineStore switching cache, the reconnect-on-switch
+ * swap, and the tab chrome on both form factors: the desktop top-bar strip and
+ * the mobile bottom-switcher + modal overview sheet. The kernel drives one
+ * active session; switching re-points the renderer at the next tab's cached
+ * store (ctx.render.bind) and asks the kernel to reconnect the terminal WS to it
+ * (ctx.notifySwitch), so the last-known screen paints instantly and the
+ * background delta arrives after.
+ *
+ * @module
+ */
 
 import { modes } from "@cplieger/web-terminal-engine";
 import type { SessionRef, TerminalContext, TerminalFeature } from "../../kernel/types.js";
@@ -102,6 +106,20 @@ const TAB_DRAG_TYPE = "application/x-web-terminal-tab";
 // the shared point-anchored positioner (menu-position.ts), shared with the
 // terminal context menu (formerly two hand-synced copies of the same math).
 
+/** The value a peer feature or a host reads through `ctx.use(tabs(...))`: the
+ *  session set as commands, plus a snapshot of the strip.
+ *
+ *  `create` and `close` are server round trips, and NEITHER rejects: a refusal is
+ *  reported to the user as a toast and the promise resolves anyway, so awaiting one
+ *  tells you the attempt finished and not that it succeeded (read `list` for that).
+ *  Both are safe to call more than once per gesture — `create` shares an in-flight
+ *  create, so the duplicate activation an iPad trackpad delivers opens one terminal
+ *  rather than two. `switchTo` is local and synchronous, and ignores an unknown id.
+ *
+ *  `list` is a snapshot, not a live view — it does not update, so re-read it rather
+ *  than holding onto the array, and treat it as display data: the tab a user is
+ *  looking at is this feature's own state and mutating it goes through the members
+ *  above. */
 export interface TabsApi {
   /** Spawn a fresh session and switch to it. Calls made while a create is in
    *  flight share that create, so one gesture opens exactly one terminal. */
@@ -114,6 +132,14 @@ export interface TabsApi {
   list(): readonly { id: string; title: string; active: boolean }[];
 }
 
+/** Options for the tabs feature.
+ *
+ *  The two feature-valued members (`activityMonitor`, `keyboardToggle`) must be the
+ *  SAME values the composition includes and must be ordered before tabs in the
+ *  feature list, since `ctx.use` only resolves a peer the kernel has already set
+ *  up. Both are optional and their absence degrades rather than fails: no monitor
+ *  means polling instead of the status SSE, no toolbar means no keyboard button in
+ *  the mobile bar. `buildTabbed` in presets/tabbed.ts is the worked example. */
 export interface TabsOptions {
   /** REST base for the session API (default "/api/sessions"). */
   apiBase?: string;
@@ -149,10 +175,10 @@ export interface TabsOptions {
    *  `link[rel=icon]` whose filename starts with `favicon`, three variants must
    *  be served alongside it with `-input`, `-done` and `-alert` inserted after
    *  that token (`/favicon.svg` needs `/favicon-input.svg`; `/favicon-32x32.png`
-   *  needs `/favicon-input-32x32.png`). Generate them with
-   *  `.kiro/scripts/gen-attention-icons.py`, which writes exactly those names, and
-   *  assert their presence in the APP's own tests — the library cannot check a
-   *  file it does not ship, and a missing variant is a blank tab icon.
+   *  needs `/favicon-input-32x32.png`). Generate them with whatever tooling you
+   *  like as long as it writes exactly those names, and assert their presence in
+   *  the APP's own tests — the library cannot check a file it does not ship, and
+   *  a missing variant is a blank tab icon.
    *
    *  Not every platform honours it: Safari caches the first icon it fetched and
    *  ignores later changes, and an installed app has no tab icon at all. The
@@ -321,6 +347,20 @@ function looksLikeHardwareKey(ev: KeyboardEvent): boolean {
   }
 }
 
+/** Build the tabs feature.
+ *
+ *  Requires a server that speaks the session API — `GET`/`POST`/`DELETE` on
+ *  `/api/sessions`, `?session=<id>` on the WebSocket, and ideally the status SSE.
+ *  It registers itself as the kernel's `sessionOwner`, so it and not the kernel
+ *  resolves the session the first connect attaches to. At most one feature may claim
+ *  that role, and `createTerminal` throws before any DOM work when two do.
+ *
+ *  The arrangement of the strip is SERVER state (the `order` field), while the
+ *  active tab and the dismissed notification cues are per-viewer and live in
+ *  `localStorage` — so a phone reordering tabs moves them on the desktop, and
+ *  switching tabs on one does not move the other. Teardown removes all chrome,
+ *  releases the per-tab caches, and leaves the sessions themselves running on the
+ *  server; closing a tab is what kills a process. */
 export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
   const apiBase = opts.apiBase ?? DEFAULT_API_BASE;
   const presumeReports = opts.presumeReports ?? false;
@@ -3544,9 +3584,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
 
       // --- Event wiring ---
-      // No input observer. The ENGINE derives a session's name from the input
-      // stream when its host asked for that (terminal.WithInputTitle), so no preset
-      // does per-keystroke title work in the browser, and the name is identical for
+      // No input observer. The ENGINE owns a session's name, so no preset does
+      // per-keystroke title work in the browser, and the name is identical for
       // every client attached to the session — including one that attaches later.
       // Observe (never consume) keydowns to detect a physical keyboard: a
       // hardware-only key latches sawHardwareKey, which upgrades focus-on-switch

package/src/features/tabs/model.ts

@@ -309,7 +309,8 @@ export function worseCue(a: CueStatus | "", b: CueStatus | ""): CueStatus | "" {
 
 /** The icon variant a cue paints, which is NOT one per status: `crashed` and
  *  `failed` both render --status-failed, so they share one asset. An app ships
- *  one icon per name returned here (see .kiro/scripts/gen-attention-icons.py). */
+ *  one icon per name returned here (see TabsOptions.attentionIcons for the
+ *  naming contract those files must satisfy). */
 export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
   if (status === "input" || status === "done") {
     return status;
@@ -532,8 +533,8 @@ export interface Tab {
    *  session (the boot double-create bug). */
   born: number;
   /** The title the SERVER resolved for this session: its pinned name, else the
-   *  input-derived name, else the program's OSC 0/2 window title, else a
-   *  client-pushed label, else the engine's own foreground-process/cwd inference.
+   *  program's OSC 0/2 window title, else a title the host pushed through
+   *  SetSessionTitle, else the engine's own foreground-process/cwd inference.
    *  Possibly empty only against an engine that has none of those. The displayed
    *  label adds a numbered fallback and de-duplication (see relabelAll in
    *  index.ts). */
@@ -603,9 +604,9 @@ export interface Tab {
  *  there is one, otherwise the title the SERVER resolved.
  *
  *  Only two rungs, because the engine now owns every automatic source and folds
- *  them into `title` in precedence order (pinned, input-derived, the program's OSC
- *  window title, a client-pushed label, then its own foreground-process/cwd
- *  inference). A client that re-implemented that ladder could only disagree with
+ *  them into `title` in precedence order (pinned, the program's OSC window title,
+ *  a title the host pushed through SetSessionTitle, then its own
+ *  foreground-process/cwd inference). A client that re-implemented that ladder could only disagree with
  *  the server and with every other client.
  *
  *  The pin is still checked here, even though the server also folds it into

package/src/kernel/kernel.ts

@@ -54,7 +54,23 @@ import type {
 const { mapKeyboardEvent, bracketTextForPaste, prepareTextForTerminal } = keyboard;
 
 const DEFAULT_WS_PATH = "/ws";
+// The family that carries the CELL METRICS, alone: deliberately not --font-mono's
+// list, which leads with the tiling overlay. WebKit resolves load() over a list as
+// soon as the FIRST family whose descriptor covers the sample has loaded
+// (CSSFontFaceSet::matchingFacesExcludingPreinstalledFonts, `if (found) break;`),
+// so naming the overlay would settle the gate on its 11 KB while the companion is
+// still loading — and the overlay copies the companion's metrics and carries no
+// "M", the glyph render.ts measures, so waiting on it defends no number anyway.
 const DEFAULT_FONT_READY = '14px "Monaspace Neon NF"';
+// The deadline on the WHOLE gate below, because neither document.fonts.load nor
+// document.fonts.ready carries one: a response held open leaves both pending for
+// as long as that request lives, and a gate that never settles reports no size at
+// all. The budget is the block period the faces themselves buy with font-display:
+// block (css/page.css declares it on every one; 3s is what CSS Fonts 4 recommends
+// for `block`) — how long an engine withholds glyphs before it paints the
+// fallback. Once it has, the cell on screen IS the fallback cell, so a longer wait
+// defends metrics nobody is looking at.
+const FONT_READY_TIMEOUT_MS = 3000;
 
 const TOAST_MS = 3000;
 // A touch that focuses the input (opens the soft keyboard) must be a genuine
@@ -1383,13 +1399,49 @@ function buildTerminal(
     });
   };
   try {
-    void document.fonts
-      .load(fontReady)
-      .then(onFontSettled)
-      .catch((err: unknown) => {
+    // false once the fonts have landed, true when the deadline opened the gate
+    // without them. The race covers the whole wait, not just the rejection arm: a
+    // request that stalls with nothing rejecting leaves load() ITSELF pending, so a
+    // deadline armed on the rejection would bound one of the ways a font can hang.
+    const landed: Promise<boolean> = document.fonts.load(fontReady).then(
+      () => false,
+      (err: unknown) => {
         console.warn(`web-terminal-ui: web font ${fontReady} failed to load`, err);
-        onFontSettled();
+        // One load() over a comma-separated stack rejects as a UNIT, so settling
+        // here would let an unavailable OPTIONAL family abandon the gate for the
+        // REQUIRED one and announce a size measured on fallback metrics. `ready`
+        // settles the initial load INCLUDING a failed one (the same property
+        // features/tabs/ink-centre.ts relies on), so the families that ARE served
+        // still land their bytes before the first resize is measured.
+        return document.fonts.ready.then(() => false);
+      },
+    );
+    const deadline = new Promise<boolean>((resolve) => {
+      window.setTimeout(() => {
+        resolve(true);
+      }, FONT_READY_TIMEOUT_MS);
+    });
+    // Whichever settles first opens the gate exactly once; the loser is ignored.
+    void Promise.race([landed, deadline]).then((timedOut) => {
+      onFontSettled();
+      if (!timedOut) {
+        return;
+      }
+      // The gate opened on fallback metrics, and the swap period is infinite: bytes
+      // that land after this change the cell width with fontsLoaded already true,
+      // and nothing re-measures until the next viewport transition. So one
+      // corrective announce, through the path the viewport settle uses.
+      // sendResize deduplicates, so a font that never lands costs nothing.
+      void document.fonts.ready.then(() => {
+        // The bytes can arrive arbitrarily late, so this is the one arm of the gate
+        // that outlives its terminal; destroy() wins, as it does for a feature's
+        // un-cancelled async.
+        if (isDestroyed() || measurableSize() === null) {
+          return;
+        }
+        connection.sendResize();
       });
+    }, onFontSettled);
   } catch (err) {
     console.warn(`web-terminal-ui: invalid fontReady ${fontReady}`, err);
     onFontSettled();

package/src/kernel/scrollback-storage.ts

@@ -54,6 +54,18 @@ const DEFAULT_PREFIX = "wt.scrollback.";
  */
 const DEFAULT_MAX_BYTES = 512 * 1024;
 
+/** Options for `localScrollbackStorage`.
+ *
+ *  Four of the five are the kernel's policy rather than this store's: `maxAgeMs`,
+ *  `lines` and `saveIntervalMs` are passed straight through on the returned
+ *  `ScrollbackPersistence`, so the store's own sweep and the kernel's load-time age
+ *  check cannot disagree about a number a caller set once. `maxBytes` is this
+ *  store's alone, since only it can enumerate what it owns.
+ *
+ *  Every value is validated as a positive integer and an invalid one falls back to
+ *  the default rather than being clamped. Sizing `maxBytes` is a decision ABOUT THE
+ *  HOST APPLICATION, not about the terminal: this competes for the origin's
+ *  `localStorage` quota with everything else the page stores. */
 export interface LocalScrollbackStorageOptions {
   /** Key prefix (default `"wt.scrollback."`). */
   prefix?: string;

package/src/kernel/startup-copy.ts

@@ -1,19 +1,21 @@
-// The copy of the "terminal did not start" recovery surface, as DATA.
-//
-// Why this is a module of its own rather than string literals inside the
-// renderer: a full-page consumer needs the same words in a place no module can
-// reach. Its HTML carries an inline bootstrap watchdog whose entire job is to
-// report "the JS bundle never ran" -- a rung below `import`, by definition, or
-// it could not detect its own failure case. That watchdog cannot import these
-// strings at runtime, so a consumer's BUILD substitutes them into its HTML
-// instead, and the words survive as one declaration rather than three
-// hand-agreed copies (the pattern this replaced had web-terminal-kiro's app
-// code, its inline watchdog, and this library all restating them, kept in step
-// by comments asking the next reader to remember).
-//
-// This file therefore imports nothing and touches no DOM, so a Node build script
-// can read it without loading the kernel. It is exported at the package root and
-// at the "./startup-copy" subpath for exactly that use.
+/**
+ * The copy of the "terminal did not start" recovery surface, as DATA.
+ *
+ * Why this is a module of its own rather than string literals inside the
+ * renderer: a full-page consumer needs the same words in a place no module can
+ * reach. Its HTML carries an inline bootstrap watchdog whose entire job is to
+ * report "the JS bundle never ran" -- a rung below `import`, by definition, or
+ * it could not detect its own failure case. That watchdog cannot import these
+ * strings at runtime, so a consumer's BUILD substitutes them into its HTML
+ * instead, and the words survive as one declaration rather than three
+ * hand-agreed copies.
+ *
+ * This file therefore imports nothing and touches no DOM, so a Node build script
+ * can read it without loading the kernel. It is exported at the package root and
+ * at the "./startup-copy" subpath for exactly that use.
+ *
+ * @module
+ */
 
 /** The words the recovery surface shows, whichever startup rung failed.
  *