@cplieger/web-terminal-ui 7.2.2 → 7.3.1

package/README.md

@@ -63,10 +63,16 @@ page that has one empty container element, then call
 **Full-page host** (the terminal IS the page, as in `web-terminal-server` and
 `web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
 links. That reference bundle is `css/page.css` (the page kit: `html/body`
-reset + the bundled web font's `@font-face`, expecting the font files at
-`/vendor/fonts/`) plus the complete component set. The bundled font backs both
-the terminal display and the chrome text, so serving those files is not
-optional for a full-page host.
+reset + the `@font-face` rules for two families, expecting the font files at
+`/vendor/fonts/`) plus the complete component set. The set is the four
+`MonaspaceNeonNF-*.woff2` faces, which back both the terminal display and the
+chrome text, plus `WebTerminalGlyphs.woff2` — a tiling overlay that supplies the
+box-drawing, block, braille and powerline cells the terminal draws — served
+alongside that font's `LICENSE` and `NOTICE`. Serving the Monaspace faces is not
+optional for a full-page host. A host that has not yet added the overlay file
+degrades cleanly rather than breaking: the face errors out, and the terminal
+renders exactly as it did before, with the tiling ranges coming from Monaspace
+and the system font.
 
 **Embedder** (the terminal lives inside your app's layout, as a panel or pane):
 concatenate the per-preset manifest matching your composition instead:
@@ -133,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
@@ -185,7 +192,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 | `features`          | _(none; bare kernel)_        | A FUNCTION returning the feature list. Omitted builds only the terminal (no chrome). Pass a preset by name (`features: presetTabbed`) or a factory of your own; it is called inside the startup-failure boundary, so a preset that throws is handled rather than escaping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `layout`            | `"viewport"`                 | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `wsPath`            | `"/ws"`                      | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `fontReady`         | `'14px "Monaspace Neon NF"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `fontReady`         | `'14px "Monaspace Neon NF"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback. Only the family that CARRIES those metrics is named: the tiling overlay copies them and holds no letter for the width probe to measure, and naming it as well would open the gate on the overlay alone in WebKit (Safari, every iOS browser), while Monaspace was still loading. The wait is bounded at 3s whatever the fonts do, the `font-display: block` period the bundled faces declare, so a request that stalls leaves the terminal sized on fallback metrics rather than never sized at all, and a font that lands after the bound costs one corrective resize.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `scrollbackLines`   | _(engine default)_           | Retained scrollback lines per terminal, and per tab under the tabs feature (every per-tab cache is built through the same budget). This is the page's dominant memory dial: it bounds the styled-run arrays each session retains AND the DOM rows the renderer keeps (one row element per retained line), so a memory-constrained host (iOS Safari, where the content process is reclaimed under system pressure) passes a smaller budget at the price of a shorter scroll-back. A history budget floored at the live screen: the engine never evicts the current window, so a value at or below the terminal height keeps the full screen with no scrollback, but choose a value comfortably above the largest expected terminal height (a few multiples), since near or below it the batched eviction degrades to per-line churn. Non-integer or non-positive values are ignored. Left unset, the engine decides, and it decides twice: 5000 against a server that cannot serve history back, dropping to a 1500-line resident tail plus an on-demand cache once a server declares demand-paged scrollback. Prefer leaving it unset: the depth then lives on the server and the phone holds a working set. An explicit value opts OUT of that flip: it is an explicit memory decision and holds in both states. |
 | `persistScrollback` | _(off)_                      | Persist each session's scrollback across a page discard, through storage YOU supply. A page that is discarded and reloaded otherwise resumes holding nothing, so it asks the server for everything and refills its whole buffer over the wire (the normal case on iOS, where Safari evicts backgrounded tabs under memory pressure and returning to one re-runs the page). With a snapshot restored, the resume asks only for what was printed while the tab was gone. It helps the FRESH-LOAD case only: a warm reconnect and an in-page tab switch already replay nothing. Off by default because `localStorage` is a shared, origin-wide, quota-limited resource and this library is embedded in applications that keep their own state there: an application decides durability for its own users, a library does not decide it for an embedder. Applies to a single terminal and to every tab alike. See below.                                                                                                                                                                                                                                                                                                                                                                                              |
 | `loading`           | _(none)_                     | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -485,7 +492,7 @@ about your server rather than about this terminal.
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/**/*.ts`           | The UI modules: the kernel (`kernel/`), opt-in features (`features/`), per-preset entries (`presets/`), IME, predictive echo, viewport.                                                                                   |
 | `css/*.css` + manifests | Root-scoped component styles. `MANIFEST` = the reference full-page bundle (`page.css` + the tabbed set); `MANIFEST.single/touch/tabbed` = component-only per-preset bundles for embedders. Concatenate in manifest order. |
-| `css/page.css`          | The page kit (full-page hosts only): `html/body` reset + the terminal web font's `@font-face`.                                                                                                                            |
+| `css/page.css`          | The page kit (full-page hosts only): `html/body` reset + the `@font-face` rules for the terminal's two web fonts, `Monaspace Neon NF` and the `Web Terminal Glyphs` tiling overlay.                                       |
 | `scaffold/index.html`   | A reference full-page HTML host: `<head>` + one empty root element + importmap.                                                                                                                                           |
 
 ## Related projects
@@ -518,3 +525,9 @@ This project was built with AI-assisted tooling using [Claude](https://claude.co
 ## License
 
 MPL-2.0. See [LICENSE](LICENSE).
+
+The `Web Terminal Glyphs` tiling overlay named in `css/page.css` is a separate
+Apache-2.0 work, and its licence travels with the FONT FILE — which this package
+does not ship, it only names the URL. So no new obligation lands on an npm or JSR
+consumer; the obligation is the serving host's, which is why the full-page host
+notes above ask for the font's `LICENSE` and `NOTICE` beside the `.woff2`.

package/css/00-tokens.css

@@ -141,13 +141,44 @@
      strip (MANIFEST.touch excludes 30-tabs.css), so nothing metric-dependent
      rides on that fallback. */
   --font-ui: "Monaspace Neon NF", ui-monospace, monospace;
-  --font-mono: "Monaspace Neon NF", monospace;
+  /* The terminal display is an OVERLAY over a companion: "Web Terminal Glyphs"
+     is a tiling-only face (box drawing, blocks, braille, powerline — 1,098
+     codepoints, no letters, no digits, not even a space), so the browser takes
+     those cells from it and everything else from Monaspace by ordinary family
+     fallback. It leads deliberately, so its cell-exact glyphs win where the
+     companion also has a codepoint; carrying no text glyphs, it cannot move the
+     companion's metrics or its look. page.css declares the four faces and owns
+     the rest of the reasoning.
+
+     --font-ui above does NOT get the overlay, and that is a scope choice rather
+     than an omission: the chrome renders labels and never a tiling codepoint, so
+     the overlay would be a family the browser consults on every glyph and never
+     draws from. It would not cost a label geometry to add it — the overlay's
+     vertical metrics are copied from the companion (the upstream font's
+     dist/cell.json, 1890/-400/200 with USE_TYPO_METRICS set on both), so the
+     line box is the same either way. The reason to keep the chrome's stack at one
+     family is least mechanism, and --label-ink-shift below is why that matters:
+     it is written from the line box the engine actually built
+     (src/features/tabs/ink-centre.ts), so anything that DOES move the chrome's
+     metrics lands straight in the chip labels. */
+  --font-mono: "Web Terminal Glyphs", "Monaspace Neon NF", monospace;
   /* Pre-measurement default for the chip labels' ink centring; the tabs feature
      writes a measured px value per site (src/features/tabs/ink-centre.ts owns
      why). Zero: flex centring already lands within 0.4px of the cap band, and is
      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/02-terminal.css

@@ -45,7 +45,9 @@
   touch-action: pan-x pan-y;
   font-family: var(--font-mono);
   /* Bold and italic are real faces (page.css); a synthesized stand-in must
-     never be drawn in their place. */
+     never be drawn in their place. Not redundant with those declarations: Blink
+     obliques an italic run over the tiling overlay despite its exact italic face,
+     so this line is the only thing keeping box drawing upright there. */
   font-synthesis: none;
   font-size: 14px;
   /* The cell height. The engine reads it (render.ts updateFontMetrics) and sizes

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,14 +983,44 @@
    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.
+
+   The divisor is the arithmetic rather than a literal, for the reason the footprint
+   cancel above is: the size is a variable and the band is now one too, so a literal
+   would be right until either moved. Ported from vibekit's `.tab-run-dot`
+   (`12-tabs.css`, "THE GLOW BEAT"), which is the same mark solving the same problem
+   and had the mask from the start.
+
+   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 on a 9px mark with a 2px band that box is 5x5 and `inset: -1px` resolves
+   to 7x7, still inside the border box. Read it as "fill the mark", not as "overhang
+   it": the same declaration on a mark with no band would reach outside, where a
+   feathered edge's visible radius moves with the beat and renders differently at
+   every pixel density. */
 :where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
   content: "";
   position: absolute;
@@ -1002,8 +1032,13 @@
     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 +1089,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 +1113,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 +1131,7 @@
   }
 
   35% {
-    opacity: 1;
+    opacity: 0.55;
   }
 }
 
@@ -1131,9 +1175,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/css/page.css

@@ -236,7 +236,33 @@ body {
    monospace stack.
 
    No face carries ascent-override or descent-override: the terminal's cell
-   background is the run padding in 02-terminal.css, never these metrics. */
+   background is the run padding in 02-terminal.css, never these metrics.
+
+   The tiling overlay, "Web Terminal Glyphs", is the second family below, and it
+   is ONE file declared under FOUR descriptor sets. The released face is a single
+   upright 400 weight, so a lone rule would leave the engine free to synthesise a
+   stand-in for a bold or italic run. What the four sets (400/700 x normal/italic)
+   against the same URL foreclose is the EMBOLDENED stand-in, in Blink and in
+   Gecko both: a bold run resolves a real face where the same asset under one rule
+   is thickened. They do NOT foreclose the OBLIQUE one in Blink, which honours the
+   italic descriptor for face SELECTION and slants the run anyway; the only thing
+   keeping an italic box-drawing corner upright there is font-synthesis: none on
+   .term (02-terminal.css). Both mechanisms are load-bearing and neither is the
+   whole guarantee. All four rules point at one file, so the bytes download once.
+
+   No overlay face declares unicode-range, and that absence is deliberate: the
+   font's own cmap IS its range (1,098 tiling codepoints, no letters, no digits,
+   no space), so a letter falls through to Monaspace by ordinary family fallback,
+   and a range here would only narrow that fallback to a list somebody has to
+   maintain against the next release of the font.
+
+   The overlay is listed FIRST in --font-mono and never in --font-ui
+   (00-tokens.css owns why). A full-page host must serve
+   WebTerminalGlyphs.woff2 beside the Monaspace faces, along with that font's
+   LICENSE and NOTICE: it is a separate Apache-2.0 work, and §4 binds whoever
+   ships the bytes. This package ships none, it only names the URL — so a host
+   that has not caught up errors the face out and renders exactly as it did
+   before, with the tiling ranges coming from Monaspace and the system font. */
 @font-face {
   font-family: "Monaspace Neon NF";
   src: url("/vendor/fonts/MonaspaceNeonNF-Regular.woff2") format("woff2");
@@ -268,3 +294,35 @@ body {
   font-style: italic;
   font-display: block;
 }
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 400;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Web Terminal Glyphs";
+  src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");
+  font-weight: 700;
+  font-style: italic;
+  font-display: block;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.2.2",
+  "version": "7.3.1",
   "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",