@cplieger/web-terminal-ui 7.3.0 → 7.3.2

package/README.md

@@ -139,16 +139,17 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 - `presetTabbed()`: the generic tabbed UI, `presetTouch()` plus tabs, the
   activity monitor, and animations. Each tab's title is OSC-first: it follows
   the process window title (OSC 0/2) when the program sets one and keeps it
-  updated, otherwise the last command submitted. The per-tab activity dot
+  updated, otherwise a name the server infers from the foreground process or the
+  working directory. The per-tab activity dot
   reveals itself only when a session reports OSC 9;4 progress, so a plain shell
   keeps clean, label-only tabs. Requires a server that speaks the session API
-  (`/api/sessions` and `/ws?session=`), such as `web-terminal-server`.
+  (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
+  such as `web-terminal-server`.
 - `presetAgentTabbed()`: the same feature set as `presetTabbed()`, tuned for an
-  agent shell such as `web-terminal-kiro`. With `preferInputTitle`, each tab's
-  label follows the latest submitted line (persisted server-side and recovered
-  on reload) and the program's OSC 0/2 title is ignored. With `presumeReports`,
-  the idle activity dot shows from tab creation instead of waiting for the
-  session's first OSC 9;4 signal. Its status dots come from the same activity
+  agent shell such as `web-terminal-kiro`, and differing from `presetTabbed()`
+  only in presumed activity reporting. With `presumeReports`, the idle activity
+  dot shows from tab creation instead of waiting for the session's first
+  OSC 9;4 signal. Its status dots come from the same activity
   monitor and cover eight states: the three animated OSC 9;4 progress states
   (working, warning, error), the frozen ringed needs-input dot, two static discs
   (a green finished turn, a red crashed process), and two hollow ones (idle and a

package/css/00-tokens.css

@@ -168,6 +168,17 @@
      the best answer when the measurement cannot run. Do not tune it by eye. */
   --label-ink-shift: 0em;
   --dur-micro: 0.1s;
+  /* The activity vocabulary's one beat period, read by all three animated tab
+     cues — the working dot's glow, its travelling ripple, and the secondary
+     activity mark's breath (30-tabs.css). A token rather than three literals
+     because the three are phase-locked BY sharing it: the ripple launches off the
+     disc as the glow peaks, and the mark beside them reports on the same clock, so
+     retuning one alone desynchronises cues a reader sees side by side. It was a
+     comment saying "change both or neither" until 2026-09, which is the same rule
+     with nothing enforcing it.
+     Shared with vibekit's `--dot-beat-dur` (01-tokens.css) for the reason the
+     --status-* inks are: one signal across the two apps, beat included. */
+  --dot-beat-dur: 1.2s;
   --dur-standard: 0.2s;
   --dur-enter: 0.25s;
   --dur-exit: 0.15s;

package/css/10-primitives.css

@@ -35,6 +35,7 @@
   font: inherit;
   cursor: pointer;
   touch-action: manipulation;
+  -webkit-user-select: none;
   user-select: none;
 }
 

package/css/23-toolbar.css

@@ -111,6 +111,7 @@
     font-weight: 500;
     cursor: pointer;
     touch-action: manipulation;
+    -webkit-user-select: none;
     user-select: none;
     display: flex;
     align-items: center;

package/css/30-tabs.css

@@ -815,7 +815,7 @@
     transparent 92%
   );
   opacity: 0;
-  animation: wt-working-glow 1.2s ease-in-out infinite;
+  animation: wt-working-glow var(--dot-beat-dur) ease-in-out infinite;
   will-change: opacity;
 }
 
@@ -850,7 +850,7 @@
     var(--dot-color) 76%,
     transparent 100%
   );
-  animation: wt-working-ripple 1.2s linear infinite;
+  animation: wt-working-ripple var(--dot-beat-dur) linear infinite;
 }
 
 /* Agent done / ready: solid disc (--status-done), no motion. The default green
@@ -983,27 +983,80 @@
    this size reads as an off-centre pulse. */
 :where(.wt-root) .wt-activity-mark[data-activity="working"] {
   --wt-mark-ink: var(--status-working);
+  /* The band, named because the MASK below has to know it: the overlay's hole is
+     the mark's inradius less this. Paired with the declaration it describes so the
+     two cannot drift apart on width. */
+  --wt-mark-band: 2px;
 
-  border-width: 2px;
+  border-width: var(--wt-mark-band);
   transform: translateZ(0);
 }
 
 /* The breath: a pre-painted radial animating OPACITY only, never colours, so the
    beat costs compositing rather than a repaint per frame for as long as a
-   background task runs (the battery reason the dot's glow overlay records). */
+   background task runs (the battery reason the dot's glow overlay records).
+
+   PLUS A MASK, which is the one thing a ring needs and a disc does not, and whose
+   absence was a real defect rather than a missing nicety. Over a solid disc the
+   overlay's bright core has almost no headroom above its own backdrop; over a
+   ring's transparent HOLE it has all of it, so an unmasked core FILLED the hole at
+   the peak and the mark rendered as a solid rounded square. That is the one thing
+   this element may never be: the mark and the activity dot 8px away share their ink
+   at zero hue distance, so the ring-against-disc silhouette is the entire WCAG
+   1.4.1 channel between them, and a fill collapses it for the brightest third of
+   every cycle. Masked, the beat lights the BAND and the hole's four corners, so
+   what a reader sees is the hole morphing between a square and the circle inscribed
+   in it — the ring survives the peak.
+
+   EVERY NUMBER HERE IS A RELATION, and the port that copied vibekit's LITERALS is
+   what left this rule running with nothing visible to show. Two of them were
+   arithmetic for an 8px mark with a 2px band: `inset: -1px` put the overlay on that
+   mark's own border box, and the core stop `70%` is where the core reaches the
+   hole's CORNER there — sqrt(2) * (size / 2 - band) / (size / 2) = 70.71%. At 9px
+   and 2px the same relation is 78.57%, so the copied 70% ended the solid core at
+   2.45px while the mask opens only at 2.5px: core and visible mask did not
+   intersect at all, the beat lit nothing the mask kept, and 4 pixels of a 9x9 mark
+   moved between trough and peak against vibekit's 20 (measured at dpr 1, both
+   marks, sRGB). Written as relations they survive any size: the inset IS the band,
+   the core stop IS the hole's corner radius, the mask's hole IS its inradius. So
+   port vibekit's `.tab-run-dot` (`12-tabs.css`, "THE GLOW BEAT") — the same mark
+   solving the same problem, with the mask from the start — by its relations, never
+   by its numbers. sqrt(2) is spelled to four decimals because the synced stylelint
+   sets `number-max-precision: 4` outside colour functions.
+
+   NOTHING HERE EXTENDS PAST THE MARK. `box-sizing: border-box` (01-scope.css) puts
+   the padding box — an absolutely positioned child's containing block — INSIDE the
+   band, so `inset: calc(-1 * var(--wt-mark-band))` grows the overlay back out to
+   exactly the mark's own border box and no further. Read it as "fill the mark", not
+   as "overhang it": a larger inset would reach outside, where a feathered edge's
+   visible radius moves with the beat and renders differently at every pixel
+   density. `border-radius: 50%` is the same discipline on the last literal, and it
+   is inert BY CONSTRUCTION rather than by measurement, which is why no assertion
+   pins it: for side S and radius r the clip's 45° boundary is (S/2 - r) * sqrt(2) + r,
+   monotonically decreasing in r, so the inscribed circle is the WORST case for
+   reaching the hole's corners — and it still clears them for any band at or above
+   S/2 * (1 - 1/sqrt(2)), 1.32px here against 2px. Do not assert it, and do not drop
+   it either: it is what keeps a literal radius out of a rule whose whole defect was
+   literals. */
 :where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
   content: "";
   position: absolute;
-  inset: -1px;
-  border-radius: 4px;
+  inset: calc(-1 * var(--wt-mark-band));
+  border-radius: 50%;
   background: radial-gradient(
     closest-side,
-    color-mix(in oklch, var(--wt-mark-ink) 78%, #fff) 0 70%,
+    color-mix(in oklch, var(--wt-mark-ink) 78%, #fff) 0
+      calc(1.4142 * (var(--wt-mark-size) / 2 - var(--wt-mark-band))),
     transparent 92%
   );
   opacity: 0;
-  animation: wt-activity-breath 1.2s ease-in-out infinite;
+  animation: wt-activity-breath var(--dot-beat-dur) ease-in-out infinite;
   will-change: opacity;
+  mask: radial-gradient(
+    closest-side,
+    transparent 0 calc(var(--wt-mark-size) / 2 - var(--wt-mark-band)),
+    #000 calc(var(--wt-mark-size) / 2 - var(--wt-mark-band))
+  );
 }
 
 /* Waiting: the thin band plus a static halo. Stopped and resumable, nobody being
@@ -1054,8 +1107,10 @@
      usable weight through the travel. The ramp-in is short enough to read as
      instant while stopping the emission from popping in.
 
-   The disc's own glow shares this 1.2s period so the two cues stay phase-locked;
-   change both or neither. */
+   The disc's own glow shares this period so the two cues stay phase-locked, and
+   since 2026-09 that is STRUCTURAL rather than a request: all three animated cues
+   read `--dot-beat-dur` (00-tokens.css), so there is no longer a pair of literals
+   to change both of. */
 @keyframes wt-working-ripple {
   0% {
     transform: scale(1);
@@ -1076,9 +1131,16 @@
   }
 }
 
-/* The activity mark's breath, same envelope as the dot's glow: rest, one bright
-   swell, rest. Opacity only — a colour keyframe here would reintroduce the
-   per-frame repaint this shape exists to avoid. */
+/* The activity mark's breath: rest, one swell, rest. Opacity only — a colour
+   keyframe here would reintroduce the per-frame repaint this shape exists to avoid.
+
+   The dot's glow ENVELOPE, at a lower CEILING, and the ceiling is where the two
+   deliberately part. 0.55 rather than 1 is vibekit's number for the same mark
+   (`12-tabs.css`), and it is what keeps a strip of busy tabs reading as one pulse
+   instead of a row of flashes — the dot can afford 1 because its overlay lifts a
+   solid disc of its own hue and has almost no headroom above its own backdrop,
+   while this one is masked onto a 2px band over the page and has all of it. Used by
+   the mark alone, so the value moves nothing else. */
 @keyframes wt-activity-breath {
   0%,
   70%,
@@ -1087,7 +1149,7 @@
   }
 
   35% {
-    opacity: 1;
+    opacity: 0.55;
   }
 }
 
@@ -1131,9 +1193,13 @@
 
   /* Working loses its breath, so it takes the HEAVIEST band instead: motion is
      REPLACED by a channel rather than removed, and the three states then separate
-     by band alone (3px bare / 1px halo / 2px halo). */
+     by band alone (3px bare / 1px halo / 2px halo).
+
+     Re-pointing --wt-mark-band rather than declaring `border-width` keeps the number
+     in the one place the state's own rule reads it from, the mask's divisor included
+     — which is moot here only because the overlay is gone one rule below. */
   :where(.wt-root) .wt-activity-mark[data-activity="working"] {
-    border-width: 3px;
+    --wt-mark-band: 3px;
   }
 
   :where(.wt-root) .wt-activity-mark[data-activity="working"]::before {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.3.0",
+  "version": "7.3.2",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",

package/src/features/activity-monitor.ts

@@ -1,13 +1,17 @@
-// activityMonitor feature: subscribes to the server's status SSE
-// (/api/sessions/events via the engine's connectStatusStream) and exposes each
-// session's live status through its API (design sections 7, 22.4, 22.5). It is a
-// pure data source with no chrome of its own; the tabs feature consumes it via
-// ctx.use to render per-tab activity dots and drop exited/removed tabs. The
-// server pushes an initial snapshot on every (re)open — but the snapshot
-// carries no tombstones for sessions a REPLACEMENT server never knew (manager
-// restart), so the stream-open signal is surfaced via onStreamOpen and the
-// consumer (tabs) runs a one-shot GET /api/sessions reconcile there to drop
-// zombie tabs.
+/**
+ * activityMonitor feature: subscribes to the server's status SSE
+ * (/api/sessions/events via the engine's connectStatusStream) and exposes each
+ * session's live status through its API. It is a
+ * pure data source with no chrome of its own; the tabs feature consumes it via
+ * ctx.use to render per-tab activity dots and drop exited/removed tabs. The
+ * server pushes an initial snapshot on every (re)open — but the snapshot
+ * carries no tombstones for sessions a REPLACEMENT server never knew (manager
+ * restart), so the stream-open signal is surfaced via onStreamOpen and the
+ * consumer (tabs) runs a one-shot GET /api/sessions reconcile there to drop
+ * zombie tabs.
+ *
+ * @module
+ */
 
 import { connectStatusStream } from "@cplieger/web-terminal-engine";
 import type { SessionStatus } from "@cplieger/web-terminal-engine";
@@ -15,6 +19,14 @@ import type { TerminalFeature, Unsubscribe } from "../kernel/types.js";
 
 const DEFAULT_EVENTS_PATH = "/api/sessions/events";
 
+/** The value a peer feature reads through `ctx.use(activityMonitor(...))`: the
+ *  live status of every session the server knows about.
+ *
+ *  Read-only — nothing here starts, stops or mutates a session. `current` answers
+ *  from the last event seen rather than from the network, so it is undefined for
+ *  a session no event has covered yet (the initial snapshot arrives
+ *  asynchronously after setup) and for one the stream has since reported
+ *  `removed`. A caller that needs "eventually" rather than "now" subscribes. */
 export interface ActivityMonitorApi {
   /** Subscribe to every status update (idle/working/warning/failed/input/done/
    *  exited/crashed, plus removed), including the OSC 9;4 percentage and any OSC
@@ -32,6 +44,21 @@ export interface ActivityMonitorApi {
   onStreamOpen?(cb: () => void): Unsubscribe;
 }
 
+/** Build the activityMonitor feature.
+ *
+ *  Requires a server that serves the status SSE endpoint; on a server without one
+ *  the stream never opens, every `current` stays undefined and no subscriber ever
+ *  fires, which is why `tabs` treats the monitor as optional and polls
+ *  `GET /api/sessions` instead when it is absent.
+ *
+ *  `eventsPath` overrides the endpoint (default `/api/sessions/events`). Order it
+ *  BEFORE any feature that reads its API through `ctx.use`, since a feature's
+ *  setup can only see peers already set up. Teardown closes the stream and drops
+ *  every subscriber and cached status.
+ *
+ *  A throwing subscriber is caught and logged rather than propagated: it must not
+ *  skip the remaining subscribers, and it must not reach the engine's SSE reader
+ *  and kill the stream for everyone. */
 export function activityMonitor(
   opts: { eventsPath?: string } = {},
 ): TerminalFeature<ActivityMonitorApi> {

package/src/features/animations.ts

@@ -1,16 +1,29 @@
-// animations feature: opt-in motion for the chrome surfaces (design sections
-// 13, 22.4). Without it the chrome surfaces are instant (no transitions); with
-// it, and when the user has not asked for reduced motion, it enables the shared
-// animation vocabulary by marking the terminal root, which the feature
-// stylesheets key their transitions off. A few pieces of motion animate
-// unconditionally regardless of this feature (terminal-core cursor/SGR blink and
-// the mobile key toolbar open/close in 02-app.css, plus the working-status-dot
-// pulse in 05-tabs.css, its WCAG non-hue cue), though prefers-reduced-motion
-// still defeats all of it. It tracks prefers-reduced-motion live so toggling the
-// OS setting takes effect.
+/**
+ * animations feature: opt-in motion for the chrome surfaces.
+ * Without it the chrome surfaces are instant (no transitions); with
+ * it, and when the user has not asked for reduced motion, it enables the shared
+ * animation vocabulary by marking the terminal root, which the feature
+ * stylesheets key their transitions off. A few pieces of motion animate
+ * unconditionally regardless of this feature (terminal-core cursor/SGR blink and
+ * the mobile key toolbar open/close in 02-app.css, plus the working-status-dot
+ * pulse in 05-tabs.css, its WCAG non-hue cue), though prefers-reduced-motion
+ * still defeats all of it. It tracks prefers-reduced-motion live so toggling the
+ * OS setting takes effect.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 
+/** Build the animations feature. Exposes no API — its whole effect is the
+ *  `wt-animate` class on the terminal root, which the shipped stylesheets gate
+ *  their transitions on, so a composition either includes it or gets instant
+ *  chrome.
+ *
+ *  Position in the feature list does not matter (nothing reads it through
+ *  `ctx.use`). The class is applied during setup, re-evaluated whenever the
+ *  `prefers-reduced-motion` media query changes, and removed on teardown along
+ *  with the listener. */
 export function animations(): TerminalFeature {
   return {
     name: "animations",

package/src/features/clipboard.ts

@@ -1,10 +1,23 @@
-// clipboard feature: copy/paste helpers, the desktop Ctrl+Shift+C/V shortcuts,
-// and OSC 52 mirroring (design section 22.4). Exposes a typed API so contextMenu
-// can offer Copy/Paste through it (ctx.use). With this feature absent, inbound
-// OSC 52 has no subscriber and is intentionally a no-op.
+/**
+ * clipboard feature: copy/paste helpers, the desktop Ctrl+Shift+C/V shortcuts,
+ * and OSC 52 mirroring. Exposes a typed API so contextMenu
+ * can offer Copy/Paste through it (ctx.use). With this feature absent, inbound
+ * OSC 52 has no subscriber and is intentionally a no-op.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 
+/** The value a peer feature reads through `ctx.use(clipboard())` — contextMenu's
+ *  Copy and Paste items are this API behind a button.
+ *
+ *  Both members are fire-and-forget: the underlying Clipboard API calls are async
+ *  and their outcome is reported to the user as a toast rather than returned, so a
+ *  caller cannot await or branch on success. Both require a secure context
+ *  (`navigator.clipboard` is absent on a plain-HTTP non-loopback host, a supported
+ *  web-terminal-server deployment), where they toast "Clipboard unavailable" and
+ *  do nothing. */
 export interface ClipboardApi {
   /** Write text to the system clipboard (surfaces a toast on success/failure). */
   copy(text: string): void;
@@ -12,6 +25,15 @@ export interface ClipboardApi {
   paste(): void;
 }
 
+/** Build the clipboard feature.
+ *
+ *  It claims three things for the lifetime of the terminal: a kernel keydown
+ *  intercept (Ctrl+Shift+C copies the browser selection, Ctrl+Shift+V pastes, and
+ *  a plain Ctrl+V is consumed WITHOUT preventDefault so the browser's own paste
+ *  event reaches the hidden textarea instead of being mapped to `\x16`), the
+ *  `wire:clipboard` event that mirrors an application's OSC 52 copy to the system
+ *  clipboard, and a document `copy` listener that toasts "Copied" for a selection
+ *  inside the terminal surface only. Teardown releases all three. */
 export function clipboard(): TerminalFeature<ClipboardApi> {
   return {
     name: "clipboard",

package/src/features/connection-banner.ts

@@ -1,8 +1,12 @@
-// connectionBanner feature: renders the kernel's connection state as a visible
-// banner (design sections 22.3, 22.4). The state machine, the loading
-// lifecycle, and the give-up hook are kernel-owned; this feature is a pure
-// renderer subscribing to connection:state. It uses the kernel's single
-// announcer (ctx.announce) rather than spawning its own aria-live region.
+/**
+ * connectionBanner feature: renders the kernel's connection state as a visible
+ * banner. The state machine, the loading
+ * lifecycle, and the give-up hook are kernel-owned; this feature is a pure
+ * renderer subscribing to connection:state. It uses the kernel's single
+ * announcer (ctx.announce) rather than spawning its own aria-live region.
+ *
+ * @module
+ */
 
 import type { ConnState, TerminalFeature } from "../kernel/types.js";
 
@@ -17,6 +21,15 @@ const TEXT: Partial<Record<ConnState, string>> = {
   incompatible: "Terminal protocol mismatch; update the server or reload this page",
 };
 
+/** Build the connectionBanner feature. Exposes no API — it owns one element in
+ *  the kernel's "banner" region and nothing else reads from it.
+ *
+ *  Only the states with copy above are shown; `connected` and any other state
+ *  hides the banner, so it is a transient surface rather than a permanent status
+ *  line. `restarted`, `ended` and `incompatible` are the terminal ones a user
+ *  cannot wait out. Each change is announced once through `ctx.announce`, so a
+ *  flaky link re-entering the same state does not repeat itself to a screen
+ *  reader. Teardown unsubscribes and removes the element. */
 export function connectionBanner(): TerminalFeature {
   return {
     name: "connectionBanner",

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/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.
  *

package/src/kernel/style-contract.ts

@@ -1,36 +1,38 @@
-// The names that cross this package's boundary as STRINGS, published as data.
-//
-// Two surfaces of this library are addressed by name rather than by type, so no
-// compiler on either side of the boundary checks them:
-//
-//   - `theme` is `Readonly<Record<string, string>>`. The kernel copies every key
-//     onto the terminal root verbatim, so a consumer that names a token this
-//     library renamed or retired gets a live declaration nothing reads: no
-//     error, no warning, just the library's own defaults where the consumer's
-//     brand was meant to be.
-//   - The loading overlay is the CONSUMER's element (it must paint before this
-//     module loads), styled by `css/page.css` purely because the markup opts in
-//     by class. Those classes are usually hardcoded in a static HTML file no
-//     compiler reads at all.
-//
-// Both were previously prose — a doc comment on the option, a sentence in the
-// README — which a consumer could only agree with by remembering. Published as
-// data they can be ASSERTED against instead: web-terminal-kiro's app.test.ts
-// checks its theme keys and its overlay markup against these exports the same
-// way it already checks its bootstrap watchdog's wording against
-// STARTUP_FAILURE_COPY. Same reason, same shape: this file imports nothing and
-// touches no DOM, so a test or a Node build script can read it without loading
-// the kernel.
-//
-// These lists are HAND-WRITTEN on purpose. They are the public contract — a
-// decision about what this library promises to support — not a fact derived
-// from the stylesheets. What IS derived from the stylesheets is the
-// verification that the promise holds: `src/css-contract.node.test.ts` generates the
-// declared/referenced token inventory from the CSS itself and fails if any
-// token named here is not both DECLARED and READ by a rule. A token that is
-// declared but never read is the silent-no-op case above, reached from the
-// library's side instead of the consumer's, and no hand-maintained list can
-// catch it.
+/**
+ * The names that cross this package's boundary as STRINGS, published as data.
+ *
+ * Two surfaces of this library are addressed by name rather than by type, so no
+ * compiler on either side of the boundary checks them:
+ *
+ *   - `theme` is `Readonly<Record<string, string>>`. The kernel copies every key
+ *     onto the terminal root verbatim, so a consumer that names a token this
+ *     library renamed or retired gets a live declaration nothing reads: no
+ *     error, no warning, just the library's own defaults where the consumer's
+ *     brand was meant to be.
+ *   - The loading overlay is the CONSUMER's element (it must paint before this
+ *     module loads), styled by `css/page.css` purely because the markup opts in
+ *     by class. Those classes are usually hardcoded in a static HTML file no
+ *     compiler reads at all.
+ *
+ * Both are published as data, so they can be ASSERTED against: a consumer can
+ * check its own theme keys and its own overlay markup against these exports in
+ * its own test, the same way it can check its bootstrap watchdog's wording
+ * against `STARTUP_FAILURE_COPY` on the `./startup-copy` entrypoint. This file
+ * imports nothing and touches no DOM, so a test or a Node build script can read
+ * it without loading the kernel.
+ *
+ * These lists are HAND-WRITTEN on purpose. They are the public contract — a
+ * decision about what this library promises to support — not a fact derived
+ * from the stylesheets. What IS derived from the stylesheets is the
+ * verification that the promise holds: an internal test generates the
+ * declared/referenced token inventory from the CSS itself and fails if any
+ * token named here is not both DECLARED and READ by a rule. A token that is
+ * declared but never read is the silent-no-op case above, reached from the
+ * library's side instead of the consumer's, and no hand-maintained list can
+ * catch it.
+ *
+ * @module
+ */
 
 /** CSS custom properties a consumer may set through `CreateTerminalOptions.theme`.
  *

package/src/presets/agent-tabbed.ts

@@ -1,20 +1,23 @@
-// presetAgentTabbed: the tabbed composition tuned for an agent shell.
+/**
+ * presetAgentTabbed: the tabbed composition tuned for an agent shell.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { type TabbedPresetOptions, buildTabbed } from "./tabbed.js";
 
-/** Tabbed UI for an agent shell (web-terminal-kiro). Same features as
- *  presetTabbed, tuned for sessions that ARE agents:
+/** Tabbed UI for an agent shell. Same features as presetTabbed, tuned for
+ *  sessions that ARE agents:
  *  - `presumeReports`: every session's program is an agent that WILL report
  *    OSC 9;4 progress, so the idle activity dot shows from tab creation
  *    instead of popping in seconds later when the agent has booted far enough
  *    to first report; the server's sticky reportsActivity flag then merely
  *    confirms. (presetTabbed keeps the evidence-driven reveal instead: a
  *    plain shell never grows a meaningless dot.)
- *  Two agent-vs-generic distinctions live SERVER-side rather than here: the
- *  status classifier that maps OSC 9 notifications to done/needs-input, and the
- *  input-derived session name (terminal.WithInputTitle), which the agent host
- *  enables because its program's own window title is not worth showing. */
+ *  One agent-vs-generic distinction lives SERVER-side rather than here: the
+ *  status classifier that maps OSC 9 notifications to done/needs-input. Tab
+ *  names are server-side too but are not agent-specific — see buildTabbed. */
 export function presetAgentTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
   return buildTabbed(true, opts);
 }

package/src/presets/single.ts

@@ -1,8 +1,12 @@
-// presetSingle: the single-pane desktop composition. Its own entry module so a
-// consumer importing "@cplieger/web-terminal-ui/presets/single" pulls in ONLY
-// this feature graph — none of the toolbar/tabs modules (the ./presets barrel
-// statically reaches everything; these per-preset entries are the
-// graph-minimal imports).
+/**
+ * presetSingle: the single-pane desktop composition. Its own entry module so a
+ * consumer importing "@cplieger/web-terminal-ui/presets/single" pulls in ONLY
+ * this feature graph — none of the toolbar/tabs modules (the ./presets barrel
+ * statically reaches everything; these per-preset entries are the
+ * graph-minimal imports).
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { clipboard } from "../features/clipboard.js";

package/src/presets/tabbed.ts

@@ -1,7 +1,11 @@
-// presetTabbed (and the shared tabbed composition builder): the full
-// multi-session UI. Requires a server that speaks the session API
-// (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
-// such as `web-terminal-server` or `web-terminal-kiro`.
+/**
+ * presetTabbed (and the shared tabbed composition builder): the full
+ * multi-session UI. Requires a server that speaks the session API
+ * (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
+ * such as `web-terminal-server` or `web-terminal-kiro`.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { mobileToolbar } from "../features/mobile-toolbar.js";
@@ -18,7 +22,7 @@ export interface TabbedPresetOptions {
   /** Swap the page's icon links to a status variant while a background session
    *  wants the user. Off by default, and enabling it is a promise that the
    *  variant assets are served — see TabsOptions.attentionIcons for the naming
-   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
+   *  contract those files must satisfy. */
   attentionIcons?: boolean;
 }
 
@@ -33,10 +37,9 @@ export interface TabbedPresetOptions {
  *  via ctx.use. Shared by presetTabbed and presetAgentTabbed (agent-tabbed.ts),
  *  which now differ only in presumed activity reporting (presumeReports).
  *
- *  Titles are no longer a preset concern. The ENGINE resolves a session's name —
- *  its pinned name, an input-derived name when the host asked for one
- *  (terminal.WithInputTitle), the program's OSC window title, or its own
- *  foreground-process/cwd inference — and both presets render what it reports. A
+ *  Titles are not a preset concern. The ENGINE resolves a session's name — its
+ *  pinned name, a title its host pushed, the program's OSC window title, or its
+ *  own foreground-process/cwd inference — and both presets render what it reports. A
  *  browser that re-derived any of that could only disagree with the server and
  *  with every other client attached to the same session. */
 export function buildTabbed(

package/src/presets/touch.ts

@@ -1,7 +1,11 @@
-// presetTouch: the touch-first composition (single + the on-screen key
-// toolbar). Its own entry module so a touch consumer's delivered import graph
-// excludes the tabs/activity/animations modules entirely (vibekit's embedded
-// panel imports exactly this).
+/**
+ * presetTouch: the touch-first composition (single + the on-screen key
+ * toolbar). Its own entry module so a touch consumer's delivered import graph
+ * excludes the tabs/activity/animations modules entirely (an embedded panel
+ * imports exactly this).
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { mobileToolbar } from "../features/mobile-toolbar.js";

package/src/presets.ts

@@ -1,20 +1,26 @@
-// Feature presets: the barrel. Presets are plain feature-array factories, so
-// they are spreadable and editable: a consumer can drop or add a feature with a
-// filter/spread. This barrel statically imports EVERY preset (and therefore
-// every feature); a consumer that wants the minimal delivered import graph for
-// its composition imports the per-preset entry module instead —
-// "@cplieger/web-terminal-ui/presets/single" | "/presets/touch" |
-// "/presets/tabbed" | "/presets/agent-tabbed" — or hand-picks individual
-// features from "@cplieger/web-terminal-ui/features/<name>".
-//
-// The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
-// set (both include the activity monitor, whose per-tab dot reveals itself only
-// on OSC 9;4 progress, so a plain shell never shows one). They differ in the
-// title source: presetAgentTabbed sets preferInputTitle (the agent's program
-// emits a useless OSC title, so the label follows the latest submitted line),
-// while presetTabbed is OSC-first. The generic-vs-agent STATUS distinction stays
-// server-side — an agent server sets a classifier mapping OSC 9 notifications to
-// done/needs-input.
+/**
+ * Feature presets: the barrel. Presets are plain feature-array factories, so
+ * they are spreadable and editable: a consumer can drop or add a feature with a
+ * filter/spread. This barrel statically imports EVERY preset (and therefore
+ * every feature); a consumer that wants the minimal delivered import graph for
+ * its composition imports the per-preset entry module instead —
+ * "@cplieger/web-terminal-ui/presets/single" | "/presets/touch" |
+ * "/presets/tabbed" | "/presets/agent-tabbed" — or hand-picks individual
+ * features from "@cplieger/web-terminal-ui/features/<name>".
+ *
+ * The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
+ * set (both include the activity monitor, which drives the per-tab activity
+ * dot). They differ in one flag, `presumeReports`: presetAgentTabbed presumes
+ * every session's program is an agent that WILL report OSC 9;4 progress, so the
+ * idle dot shows from tab creation instead of appearing seconds later on the
+ * first report, while presetTabbed keeps the evidence-driven reveal so a plain
+ * shell never grows a meaningless dot. Session NAMES are not a preset concern:
+ * the engine resolves them, including a title its host pushes.
+ * The generic-vs-agent STATUS distinction stays server-side — an agent server
+ * sets a classifier mapping OSC 9 notifications to done/needs-input.
+ *
+ * @module
+ */
 
 export { presetSingle } from "./presets/single.js";
 export { presetTouch } from "./presets/touch.js";