@cplieger/web-terminal-ui 8.6.0-dev.7 → 8.6.0-dev.9

package/README.md

@@ -14,7 +14,7 @@ web-terminal-ui is built for a shell or a coding agent served by web-terminal-en
 
 - One `createTerminal()` call builds the UI inside an element you provide. Four presets cover a single, a touch and two tabbed layouts.
 - On a touchscreen it adds a key bar with Tab, Esc, arrows, Enter and a sticky Ctrl, a long-press paste menu and iOS soft-keyboard handling.
-- Tabs show activity dots from the program's `OSC 9;4` progress reports and raise browser notifications. Two tabs can sit side by side. A full-page terminal gives each tab and each split its own page address, and names the browser tab after the active tab, followed by the page's own title: `fix build · Web Terminal`.
+- Tabs show activity dots from the program's `OSC 7501` status, `OSC 9;4` progress and classified `OSC 9` notifications, and raise browser notifications. Two tabs can sit side by side. A full-page terminal gives each tab and each split its own page address, and names the browser tab after the active tab, followed by the page's own title: `fix build · Web Terminal`.
 - Native text selection, IME input and dictation work, and predictive echo hides latency.
 
 Consider [xterm.js](https://github.com/xtermjs/xterm.js) if you want a terminal component for any PTY backend, such as node-pty. It has an optional GPU-accelerated renderer and a set of addons, and VS Code uses it. To build a UI of your own on web-terminal-engine, depend on the engine alone.

package/css/00-tokens.css

@@ -26,8 +26,8 @@
   /* ===== Themeable tokens (the consumer-configurable "template") =====
      These default to the neutral built-in look; a consumer recolors the UI by
      overriding them via createTerminal's `theme` option (which sets them on the
-     terminal root) or its own CSS. web-terminal-kiro sets a purple palette. Everything
-     above is the fixed design palette; everything here is the public theme API. */
+     terminal root) or its own CSS. Everything above is the fixed design palette;
+     everything here is the public theme API. */
   --accent: oklch(72% 0.15 250deg); /* light blue; themed per consumer */
   --tab-bg: oklch(30% 0 0deg / 90%); /* inactive-tab chip (translucent) */
   --tab-hover-bg: var(--text-active); /* pressed controls / mobile switcher hovers */
@@ -61,10 +61,8 @@
      accent-derived fill (--tab-active-bg) rather than on the bar. Measured
      (sRGB, WCAG 1.4.3 formula, each layer composited over the page's #000):
      8.0:1 against the bar, but only 2.6:1 against the active-tab fill -- under
-     the 3:1 non-text minimum. This comment previously claimed 5.2:1 for the
-     active-tab case, which was wrong by ~2x; a consumer's code review quoted the
-     figure back as its baseline and built a finding on it, so treat the number
-     here as load-bearing and re-measure rather than adjust it by eye.
+     the 3:1 non-text minimum. Treat the number as load-bearing and re-measure
+     rather than adjust it by eye.
 
      Why it is nevertheless not a 1.4.1 failure, and why the fill is not simply
      darkened: hue never carries state on its own here -- working is a travelling
@@ -82,11 +80,12 @@
   --status-working: #52a9fe; /* agent working (waves): the same blue as the default --accent */
   --status-done: #22c55e; /* turn finished: solid green */
   --status-input: #fb923c; /* action required: solid orange + ring */
-  /* OSC 9;4 progress states 4 (warning) and 2 (error). Both render as the SAME
-     object as working -- identical glow + travelling wave, one shared rule and
-     one shared pair of keyframes (30-tabs.css) -- differing ONLY in hue, because
-     the escape code models one progress indicator with several states rather
-     than three unrelated dots. Neither wears a ring: the frozen hard ring is
+  /* The warning and failed statuses (STATUS_WARNING and STATUS_FAILED in
+     features/tabs/model.ts name their sources). Both render as the SAME object
+     as working -- identical glow + travelling wave, one shared rule and one
+     shared pair of keyframes (30-tabs.css) -- differing ONLY in hue, because
+     OSC 9;4 models one progress indicator with several states rather than three
+     unrelated dots. Neither wears a ring: the frozen hard ring is
      --status-input's exclusive meaning ("blocked, waiting on you"), and neither
      warning nor error asks the user to act.
      LIGHTNESS SEPARATION IS LOAD-BEARING, NOT DECORATIVE. Three states that
@@ -102,8 +101,8 @@
      indistinguishable to a colour-blind user, whatever their hues. warning is
      YELLOW, deliberately not amber -- amber would collide with --status-input's
      orange (L 75.8%), which sits between working and warning. */
-  --status-warning: #facc15; /* OSC 9;4 state 4: yellow disc, working's wave */
-  --status-failed: #dc2626; /* OSC 9;4 state 2: red disc, working's wave; crashed reuses it solid and static */
+  --status-warning: #facc15; /* warning: yellow disc, working's wave */
+  --status-failed: #dc2626; /* a reported error: red disc, working's wave; crashed reuses it solid and static */
   --radius: 0.75rem;
   --radius-inner: 0.5rem;
   /* Small square icon buttons (e.g. the 24px tab-close x): at that size the
@@ -173,11 +172,7 @@
      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 marotte's `--dot-beat-dur` (01-tokens.css) for the reason the
-     --status-* inks are: one signal across the two apps, beat included. */
+     retuning one alone desynchronises cues a reader sees side by side. */
   --dot-beat-dur: 1.6s;
   --dur-standard: 0.2s;
   --dur-enter: 0.25s;

package/css/01-scope.css

@@ -44,8 +44,8 @@
   color-scheme: dark;
   /* Design-system scrollbar COLOR on every scroller in the subtree (the
      terminal, the tab scroller, the expanded switcher list): border-grey
-     thumb, no track — the marotte/subflux treatment. scrollbar-color
-     INHERITS, so the boundary is the one place to set it. Where it is not
+     thumb, no track. scrollbar-color INHERITS, so the boundary is the one
+     place to set it. Where it is not
      supported the color-scheme above still renders the UA fallback dark.
      Overlay-scrollbar platforms are unaffected. */
   scrollbar-color: var(--border) transparent;

package/css/02-terminal.css

@@ -68,16 +68,11 @@
     "calt" 0;
   font-kerning: none;
 
-  /* Note: do NOT use `contain: layout style` here. iOS Safari has
-     paint-suppression bugs in WebKit where layout-contained elements
-     receiving frequent replaceChildren() updates can drop paint
-     invalidations for inline children whose styling-only changes
-     don't trigger layout — most visibly the inverse-styled "cursor"
-     span Ink draws inside our rows, which would visually stick at
-     its old column on space/arrow key presses until a content-
-     changing keystroke forced a repaint. Without `contain`, every
-     row update participates in normal paint flow and the cursor
-     cell tracks the column on every flush. */
+  /* No `contain: layout style` here: iOS Safari (WebKit) can drop paint
+     invalidations for inline children of a layout-contained element that
+     replaceChildren() updates, so a program's inverse-styled cursor span
+     would stick at its old column on space or arrow keys until a
+     content-changing keystroke forced a repaint. */
 }
 
 :where(.wt-root) .term-row:empty::after {
@@ -213,17 +208,13 @@
   display: block;
 }
 
-/* Clickable URLs. OSC 8 hyperlinks (base .term-link) underline on HOVER where a
-   pointer can hover: an application can attach one OSC 8 link to a whole
-   padded/bordered region — e.g. a markdown link whose URL wraps inside a table
-   cell, where the terminal keeps the link open across the cell padding, the
-   borders and the empty adjacent column — so a persistent underline risks
-   bleeding across the whole cell and, on wrap, the full row. Hover-only matches
-   iTerm2 / VTE / kitty. The app's own text colour (which the engine renders)
-   keeps the link discoverable at rest.
-   Auto-detected bare URLs (.term-autolink) are tightly scoped to the URL text and
-   never bleed, so they keep a subtle persistent underline. (The engine also only
-   anchors runs with real link text, so the underline hugs the text either way.) */
+/* Clickable URLs. An OSC 8 link (.term-link) underlines on HOVER only, as in
+   iTerm2, VTE and kitty: an application can hold one link open across a table
+   cell's padding, borders and the empty column beside it, so a persistent
+   underline would bleed across the cell and, on wrap, the whole row. The app's
+   own text colour keeps it discoverable at rest. A detected bare URL
+   (.term-autolink) spans only the URL text, so it keeps a subtle persistent
+   underline. */
 :where(.wt-root) .term-link {
   color: inherit;
   text-decoration: none;
@@ -238,25 +229,13 @@
   text-decoration: underline solid;
 }
 
-/* Where nothing can hover, hover-only is no affordance at all: a touch user sees
-   an app-declared link as plain text and has to guess. Measured on kiro-cli at 41
-   columns: it emits OSC 8 for every markdown link (its hyperlink capability
-   unlocks on the TERM_PROGRAM=iTerm.app identity the engine advertises), so a
-   phone session is full of tappable, invisible links. Give them the same subtle
-   dotted underline the auto-detected ones carry.
-
-   The bleed risk above is what kept this off, and it is narrower than it reads:
-   the engine refuses to anchor a run with no real link text, so the padding, the
-   box-drawing borders and the indent cells a wrapped link leaks onto the next row
-   stay unanchored and unmarked (verified against a captured OSC 8 link that wraps
-   mid-URL: the three leaked indent cells carry the href on the wire and get no
-   anchor). What remains is an app leaving one link open across genuine text in an
-   adjacent column, which would be underlined too. On a device that cannot hover,
-   an occasional over-underline beats a link with no affordance.
-
-   `hover: none` is the pointing device's capability, not a viewport width, so a
-   narrow window on a desktop keeps hover styling and a tablet with a trackpad is
-   treated as hoverable. */
+/* Where the primary pointing device cannot hover, a hover-only underline gives
+   a touch interaction no persistent affordance: a TUI that emits OSC 8 for
+   every link it renders (a program may enable hyperlinks for the iTerm2
+   identity the engine advertises) fills a phone session with tappable,
+   invisible links. The bleed risk above stays small because the engine anchors
+   no run without real link text. `hover: none` describes the primary pointing
+   device, not viewport width, so a narrow desktop window keeps hover styling. */
 @media (hover: none) {
   :where(.wt-root) .term-link {
     text-decoration: underline dotted;

package/css/10-primitives.css

@@ -78,7 +78,7 @@
    real <button>: tabs, +, keyboard, switcher rows, menu items, the FAB).
    :focus-visible only — a tap/click never shows the ring (the UA heuristic),
    so the touch-first surfaces stay clean while Tab-key navigation gets the
-   family's accent ring (the marotte/subflux convention: 2px accent, 2px out).
+   accent ring (2px accent, 2px out).
    Follows each control's border-radius; themeable via --accent like the "+"
    glyphs. The terminal's own hidden textarea is not a button and keeps its
    outline: none (02-terminal.css). */

package/css/30-tabs.css

@@ -107,8 +107,8 @@
   width: 300px;
   flex: 0 1 auto;
   min-width: 100px;
-  /* Positioning context for the chip's own overlay: the OSC 9;4 determinate
-     progress bar sits on its bottom edge (see .wt-progress-bar). Nothing else
+  /* Positioning context for the chip's own overlay: the determinate progress
+     bar sits on its bottom edge (see .wt-progress-bar). Nothing else
      inside a chip is absolutely positioned, and the strip's two root-level
      overlays (.wt-tab-ghost, .wt-tab-menu) are children of .wt-root, not of a
      chip, so this cannot capture them. */
@@ -188,7 +188,7 @@
 
 /* The active tab reads clearly above the inactive chips: a stronger fill plus an
    accent-coloured edge (inactive chips carry a faint white --border; the active
-   one gets the accent equivalent). Themeable via --accent (web-terminal-kiro -> purple). */
+   one gets the accent equivalent). Themeable via --accent. */
 :where(.wt-root) .wt-tab-active {
   background: var(--tab-active-bg);
   border-color: var(--tab-active-border);
@@ -659,25 +659,14 @@
   bottom: calc(var(--wt-tabbar-h, 44px) + var(--safe-bottom, 0px));
 }
 
-/* ===== Activity dots (activityMonitor via tabs) =====
-   Eight-state, distinguishable without color (shape + motion, not hue alone),
-   per section 12 / WCAG 1.4.1: three ANIMATED progress states (working /
-   warning / failed — one object, three hues, spread across lightness so they
-   survive greyscale and deuteranopia), a frozen ringed disc (input), two static
-   discs (green done, red crashed), and two hollow ones (idle, dim exited).
-   The one .wt-status-dot vocabulary is shared by the desktop strip, the mobile
-   switcher, and the overview sheet rows.
-
-   Revealed PER TAB: the dot is hidden until its own session reports activity
-   (OSC 9;4 progress, or a classified OSC 9 notification), at which point the
-   tabs feature adds .wt-reports to that dot (paintStatusDot). A program that
-   emits no OSC 9 signal (a plain bash/sh) has no activity concept, so its tabs
-   stay clean, label-only; a progress-reporting agent (kiro-cli, Claude Code)
-   lights up. An agent-shell consumer can PRESUME the report instead (tabs'
-   presumeReports option, on in presetAgentTabbed): .wt-reports is then set
-   from tab creation, so the idle dot shows immediately rather than popping in
-   after the agent's first signal. The element stays in the DOM either way (JS
-   sets data-status regardless), so revealing it is a pure CSS switch. */
+/* ===== Activity dots: one .wt-status-dot vocabulary for the strip, the
+   switcher and the overview rows. Eight built-in states told apart without
+   colour (WCAG 1.4.1, by shape and motion): three animated progress hues
+   (working, warning, failed) spread across lightness, a ringed disc (input), two
+   static discs (done, crashed) and two hollow ones (idle, exited); any other
+   status keeps the default hollow dot below. A dot shows once its session
+   reports activity (.wt-reports, set by paintStatusDot) or from creation under
+   tabs' presumeReports option; data-status is set either way. */
 :where(.wt-root) .wt-status-dot {
   display: none;
   width: 9px;
@@ -699,12 +688,10 @@
   animation: none;
 }
 
-/* ===== Determinate progress bar (OSC 9;4 percentage) =====
-   The second display mode the specs name for a progress report (iTerm2 calls it
-   a progress bar; ConEmu also puts the value on the taskbar, which is the
-   document-title prefix's job). One 2px line on the chip's bottom edge, shared
-   by all three chip sites (desktop strip chip, mobile active row, expanded list
-   row) because it ships in the one chipContent builder.
+/* ===== Determinate progress bar (the session's percentage: OSC 7501 progress, else OSC 9;4) =====
+   One 2px line on the chip's bottom edge, shared by all three chip sites
+   (desktop strip chip, mobile active row, expanded list row) because it ships
+   in the one chipContent builder.
 
    The ACCENT colour, not a per-state tint: the bar answers "how far", the dot
    answers "in what state", and tinting the bar per state would say the same
@@ -757,8 +744,8 @@
    the element), which read as a blink and coupled the layers — an element's
    opacity always multiplies onto its pseudos, so true independence requires
    animating disc COLORS, not element opacity. Server-side this is driven by the
-   OSC 9;4 progress signal, so it tracks agent activity, not the user typing at
-   the prompt.
+   program's own status reports, so it tracks agent activity, not the user
+   typing at the prompt.
 
    WORKING, WARNING AND FAILED SHARE THIS RULE, AND BOTH KEYFRAMES, VERBATIM.
    OSC 9;4 models ONE progress indicator with several states (1/3 active,
@@ -876,8 +863,8 @@
 }
 
 /* Agent done / ready: solid disc (--status-done), no motion. The default green
-   matches Kiro IDE's "Ready" (#22c55e). It sits at almost exactly working's
-   default lightness now that working is the accent blue (both ~72% OKLab L), so
+   (#22c55e) sits at almost exactly working's default lightness now that
+   working is the accent blue (both ~72% OKLab L), so
    the pair separates by hue plus the wave's motion rather than by lightness —
    and under prefers-reduced-motion by shape, since working becomes a donut. */
 :where(.wt-root) .wt-status-dot[data-status="done"] {
@@ -885,17 +872,11 @@
   border-color: var(--status-done);
 }
 
-/* User action required (permission / approval): a solid dot inside a static,
-   HARD-edged 2px ring, motionless (--status-input; the default orange is
-   shifted away from the old amber so it separates from both blue working and
-   green done). The stillness plus the hard edge is the message: the
-   agent's turn is mid-flight but blocked on you, and the surround is a fixed
-   outline rather than working's soft travelling wave. (Before the wave landed,
-   working's ripple was a 2px ring too and this state was literally that ping
-   frozen at its birth frame; the two now differ by edge quality as well as
-   motion, which reads more distinctly at 9px.) The ring derives from the same
-   token as the dot, so a theme override recolors both together. It persists
-   until you act on or switch into the tab. */
+/* User action required: a solid dot inside a static, hard-edged 2px ring
+   (--status-input). Stillness and the hard edge separate it from working's
+   soft travelling wave. The ring derives from the dot's token, so a theme
+   override recolors both. It persists until you act on or switch into the
+   tab. */
 :where(.wt-root) .wt-status-dot[data-status="input"] {
   background: var(--status-input);
   border-color: var(--status-input);

package/css/31-switcher.css

@@ -140,7 +140,7 @@
   /* Right padding reserves room for the close (x) overlaid inside the row. */
   padding: 0 var(--touch-target) 0 var(--sp-2);
   /* The bar row always represents the active tab, so it wears the active-tab
-     fill/foreground the desktop strip uses (themeable; purple in web-terminal-kiro). */
+     fill/foreground the desktop strip uses (themeable). */
   background: var(--tab-active-bg);
   color: var(--tab-active-fg);
   border: 1px solid var(--tab-active-border);
@@ -360,7 +360,7 @@
    process crashed or reported an error. Those four only (CueStatus) — the rule
    the user set is "only states that want the user, like a notification", so the
    ongoing progress states (working / warning) never raise it. `failed` DOES,
-   because OSC 9;4 state 2 is a result the program parked rather than a phase in
+   because a reported error is a result the program parked rather than a phase in
    progress; the override below is what keeps it looking like a notification here.
    Reuses the exact .wt-status-dot rules (30-tabs.css, --status-* tokens) so it
    matches the per-tab dots. Hidden until the tabs feature sets data-status;
@@ -410,7 +410,7 @@
 
 /* Mobile "+": the primary action, carried in the accent colour so it reads as
    permanent and prominent. Hover fill is gated on any-hover (see the note in
-   10-primitives.css): on a bare touchscreen any-hover is none, so the purple
+   10-primitives.css): on a bare touchscreen any-hover is none, so the accent
    cannot linger after a tap and the press feedback comes from :active; a trackpad
    or Pencil reports hover and gets the wash, which a (hover: hover) gate denied it.
    */

package/css/MANIFEST

@@ -1,7 +1,7 @@
 # web-terminal-ui CSS — the REFERENCE FULL-PAGE bundle.
-# What the full-page product serves (web-terminal-server, web-terminal-kiro,
-# scaffold/index.html): the page kit (page.css — html/body reset + @font-face;
-# full-page hosts ONLY) plus the complete tabbed component set. An EMBEDDING
+# What a full-page host serves (as scaffold/index.html does): the page kit
+# (page.css — html/body reset + @font-face; full-page hosts ONLY) plus the
+# complete tabbed component set. An EMBEDDING
 # consumer must NOT serve this file's bundle — it concatenates the per-preset
 # manifest matching its composition instead (MANIFEST.single / MANIFEST.touch /
 # MANIFEST.tabbed), which contains no page-level rules.

package/css/MANIFEST.touch

@@ -1,6 +1,6 @@
 # Component bundle for presetTouch() compositions (single + the mobile key
 # toolbar). Library styles only — root-scoped, no page-level rules; the host
-# page owns its own reset/fonts (marotte's embedded panel serves exactly this).
+# page owns its own reset/fonts (an embedded panel serves exactly this).
 # Files concatenate in declared order; the order IS the cascade.
 00-tokens.css
 01-scope.css

package/css/page.css

@@ -1,9 +1,9 @@
 /* ===== Page kit (full-page hosts ONLY — never ship this to an embedder) =====
    The page-level half of the full-page terminal product: what the HOST PAGE
-   owns when the terminal IS the page (web-terminal-server, web-terminal-kiro,
-   scaffold/index.html). The component bundle (00-10) never touches the host
-   document; everything here is deliberately page-scoped. An embedding consumer
-   (marotte) serves a per-preset manifest instead and owns its own page.
+   owns when the terminal IS the page (as in scaffold/index.html). The component
+   bundle (00-10) never touches the host document; everything here is
+   deliberately page-scoped. An embedding consumer serves a per-preset manifest
+   instead and owns its own page.
    Concatenated FIRST by the reference MANIFEST. */
 
 *,
@@ -39,30 +39,13 @@ body {
 }
 
 /* ===== The pre-JS loading overlay =====
-   ONE definition of the loading screen, owned here. Before this, the library
-   only PRESCRIBED it in scaffold/index.html and every full-page consumer carried
-   its own copy in an inline <style> — web-terminal-server's was byte-identical to
-   the scaffold's, web-terminal-kiro's had drifted (renamed keyframe, extra
-   states) — so the "one" loading screen existed three times and none of them
-   could be improved without editing three files.
-
-   Why it can live in a stylesheet at all, since the overlay's whole job is to be
-   on screen before the app is: a full-page host loads this bundle through a plain
-   render-blocking <link rel="stylesheet"> in <head>, so NOTHING paints until it
-   arrives. An inline copy buys no earlier paint. What an inline copy does buy is
-   the case where this stylesheet FAILS to load, which a consumer's own bootstrap
-   watchdog reports — so a consumer keeps a deliberately minimal inline fallback
-   for that failure surface only, not a second copy of everything below.
-
-   Consumer overrides work the same way the component tokens do, except simpler:
-   the overlay is the consumer's OWN element, so it sets the tokens on #loading in
-   its own CSS and needs no JS. web-terminal-kiro already did exactly this with
-   --accent before any of this was tokenised.
-
-   Selected by CLASS, never by the consumer's `id`: the library owns .wt-loading*
-   and must not reach into a host document's own identifiers (the same
-   no-element-id-contract rule the kernel follows for the terminal subtree), and
-   an unnamespaced `.bar` in a host page would collide with anything. */
+   The one definition, so a full-page consumer links it rather than carrying a
+   drifting inline copy. A full-page host loads this bundle render-blocking in
+   <head>, so an inline copy paints no earlier; a consumer keeps only a minimal
+   inline fallback for a failed stylesheet load. The overlay is the consumer's
+   own element, so it overrides by setting the tokens on it. Selected by CLASS,
+   never by id: the library owns .wt-loading* and does not reach into the host
+   document's identifiers, and an unnamespaced .bar would collide. */
 .wt-loading {
   /* The overlay's accent: the bar and the status text derive from it, so one
      override recolors the whole screen. Defaults to the component --accent
@@ -225,44 +208,12 @@ body {
 }
 
 /* ===== Fonts =====
-   The bundled web font, served by the full-page host at /vendor/fonts (both
-   web-terminal-server and web-terminal-kiro ship these files there; see their
-   Dockerfiles). It backs BOTH --font-mono (the terminal display) and --font-ui
-   (the chrome), the latter deliberately: chip-label ink centring is a per-font
-   constant, so the chrome cannot afford a system-font stack that resolves to a
-   different typeface per engine (see --label-ink-shift in 00-tokens.css). An
-   embedder does not serve these files and never inherits these URLs, so it
-   either ships its own @font-face or lets both tokens fall back to the platform
-   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.
-
-   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. */
+   The bundled faces, served by the full-page host at /vendor/fonts
+   (docs/host-page.md owns the files and their licences). They back BOTH
+   --font-mono and --font-ui: chip-label ink centring is a per-font constant
+   (--label-ink-shift, 00-tokens.css), so the chrome cannot take a system stack
+   that resolves differently per engine. No face sets ascent- or
+   descent-override: the cell background is the run padding in 02-terminal.css. */
 @font-face {
   font-family: "Monaspace Neon NF";
   src: url("/vendor/fonts/MonaspaceNeonNF-Regular.woff2") format("woff2");
@@ -295,6 +246,14 @@ body {
   font-display: block;
 }
 
+/* "Web Terminal Glyphs" is ONE upright 400 file under FOUR descriptor sets, so
+   a bold run resolves a real face instead of an emboldened stand-in (Blink and
+   Gecko). Blink still slants an italic run; font-synthesis: none on .term
+   (02-terminal.css) keeps it upright, and both are needed. The bytes download
+   once. No unicode-range: the font's cmap is its range (tiling codepoints
+   only), so letters fall through to Monaspace by family fallback, and a list
+   here would need upkeep against each font release. 00-tokens.css owns why it
+   is first in --font-mono and absent from --font-ui. */
 @font-face {
   font-family: "Web Terminal Glyphs";
   src: url("/vendor/fonts/WebTerminalGlyphs.woff2") format("woff2");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.6.0-dev.7",
+  "version": "8.6.0-dev.9",
   "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",
@@ -63,7 +63,7 @@
     "fast-check": "4.10.2",
     "html-validate": "11.16.2",
     "knip": "6.41.0",
-    "playwright": "1.64.0",
+    "playwright": "1.64.1",
     "prettier": "3.9.10",
     "stylelint": "17.16.0",
     "stylelint-config-standard": "40.0.0",

package/scaffold/index.html

@@ -16,7 +16,7 @@
      arrives with /style.css above, which is render-blocking, so nothing paints
      before it either way. A consumer that also wants a failure surface for the
      case where /style.css itself fails to load adds its own minimal inline block
-     for that (web-terminal-kiro does); a bare host does not need one. -->
+     for that; a bare host does not need one. -->
 </head>
 <body>
 <!-- createTerminal() builds the entire terminal UI inside this single root

package/src/features/tabs/index.ts

@@ -173,12 +173,11 @@ export interface TabsOptions {
 
 /** The layout read, the session list and session creation can be TEMPORARILY
  *  refused: a host answers 503 with `Retry-After` and a body message while it
- *  installs tools on first boot or restores its sessions, a window that can run
- *  twenty minutes. Only 503 retries, on the server's own
- *  schedule and repeating its own explanation. The bound is ELAPSED TIME, not an
- *  attempt count, which at `Retry-After: 5` would give up in a minute; every
- *  iteration sleeps at least the hint, so this is never a hot loop, and the user
- *  is re-told periodically. */
+ *  starts up or restores its sessions, a window that can run twenty minutes.
+ *  Only 503 retries, on the server's own schedule and repeating its own
+ *  explanation. The bound is ELAPSED TIME, not an attempt count, which at
+ *  `Retry-After: 5` would give up in a minute; every iteration sleeps at least
+ *  the hint, so this is never a hot loop, and the user is re-told periodically. */
 const CREATE_RETRY_MAX_TOTAL_MS = 1200000;
 const CREATE_RETRY_FALLBACK_MS = 5000;
 const CREATE_RETRY_REANNOUNCE_MS = 60000;
@@ -331,14 +330,13 @@ class SettleCreateFailed extends Error {
 }
 
 /** Read the layout, then list, then (when nothing live is listed) create one
- *  session, starting the turn again after any 503, so a
- *  create refused mid-restore never adds a tab beside the restored ones. A
- *  non-503 layout read proves the host was not restoring when it was served, so
- *  a list issued after it sees the whole restored set. Past
- *  `CREATE_RETRY_MAX_TOTAL_MS` a refused layout read or list returns the last
- *  good list, or rethrows the 503; a create that fails for good, a spent 503
- *  included, throws `SettleCreateFailed` carrying the list, an abort its
- *  reason. */
+ *  session, starting the turn again after any 503, so a create refused
+ *  mid-restore never adds a tab beside the restored ones. A non-503 layout read
+ *  proves the host was not restoring when it was served, so a list issued after
+ *  it sees the whole restored set. Past `CREATE_RETRY_MAX_TOTAL_MS` a refused
+ *  layout read or list returns the last good list, or rethrows the 503; a create
+ *  that fails for good, a spent 503 included, throws `SettleCreateFailed`
+ *  carrying the list, an abort its reason. */
 async function settleSessionSet(
   api: SessionAPIClient,
   ctx: TerminalContext,
@@ -1008,9 +1006,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           pageTitle.release();
         });
       }
-      // Twin of marotte static-src/tabs-drag.ts; when changing drag behaviour or its
-      // constants, check the other app. Both judge a live drag's viewport against the
-      // PRESS-time frame, so a move a hold lifted across still ends the drag.
+      // A live drag's viewport is judged against the PRESS-time frame, so a move a
+      // hold lifted across still ends the drag.
       let draggingEl: HTMLElement | null = null;
       // The chips currently carrying an inline displacement from the commit slide.
       // A set plus one settle function, so whatever a slide wrote can always be handed
@@ -1070,9 +1067,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       const prefersReduce = (): boolean =>
         win.matchMedia("(prefers-reduced-motion: reduce)").matches;
 
-      // Recomputes every display label with de-duplication. The percentage prefix
-      // is applied at render time and stored nowhere, so de-duplication and the
-      // rename field see real names and clearing it needs no cleanup.
+      // Recomputes every display label with de-duplication.
       function relabelAll(): void {
         // The "(k)" suffix is numbered by the session's AGE, never by its slot:
         // numbered by encounter order, the labels stayed put while the sessions
@@ -1142,11 +1137,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         return foldedCueStatus(statusOf(t), t.activity);
       }
 
-      /** shownProgress is a tab's percentage as it may currently be DISPLAYED:
-       *  the last value the server reported, dropped unless the current status is
-       *  one the progress channel owns. Those are the only two ways a percentage
-       *  stops showing — the program's own OSC 9;4;0 (an explicit -1) and a status
-       *  from another channel; see renderedProgress for why there is no third. */
+      /** shownProgress is a tab's percentage as it may currently be DISPLAYED;
+       *  renderedProgress owns when that is. */
       function shownProgress(t: Tab): number {
         return renderedProgress(statusOf(t), t.progress);
       }
@@ -3346,8 +3338,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           t.seenSeq = seen;
           closeReadSurfaces(t);
         }
-        // A program that speaks OSC 9 may also post a notification: arm the
-        // permission request for the next user gesture.
+        // A program that reports activity may also post an OSC 9 notification:
+        // arm the permission request for the next user gesture.
         if (reports) {
           ctx.shell.notifications.arm();
         }

package/src/features/tabs/model.ts

@@ -19,7 +19,9 @@ export type StatusRecord = SessionInfo & {
 };
 
 // The status vocabulary is module-private so a status's MEANING has one home:
-// every consumer asks a predicate below instead of comparing strings.
+// every consumer asks a predicate below instead of comparing strings. The
+// protocol states named below are the built-in sources; a classified OSC 9
+// notification may set any status.
 //
 // An exited session is viewable history that can never produce output again, so
 // session selection prefers live sessions everywhere.
@@ -30,11 +32,14 @@ const STATUS_EXITED = "exited";
  *  restart never paints as a failure. Terminal, like "exited". */
 const STATUS_CRASHED = "crashed";
 
-/** OSC 9;4 progress state 2, the error state (iTerm2 semantics). A STATE that
- *  persists until the program reports another, or the process dies. */
+/** An error the program reported: OSC 7501 state `error`, or OSC 9;4 progress
+ *  state 2 (iTerm2 semantics). A STATE that persists until the program reports
+ *  another, or the process dies. */
 const STATUS_FAILED = "failed";
 
-/** OSC 9;4 progress state 4, the warning state (iTerm2 semantics). */
+/** OSC 9;4 progress state 4, the warning state (iTerm2 semantics). OSC 9;4
+ *  cannot set it once the session has sent an OSC 7501 report, until a
+ *  terminal reset (RIS): OSC 7501 outranks OSC 9;4 until a RIS forgets it. */
 const STATUS_WARNING = "warning";
 
 /** Whether the session's process is GONE, whichever way it went: reloading onto
@@ -51,8 +56,9 @@ export function statusRevealsDot(status: string): boolean {
 }
 
 /** The human wording for a status, for BOTH the dot's tooltip and the tab's
- *  accessible name, so they cannot disagree. An unknown status (a newer server)
- *  falls back to the raw value rather than being hidden. */
+ *  accessible name, so they cannot disagree. A status outside the built-in
+ *  vocabulary (a host classifier's, or a newer server's) falls back to the raw
+ *  value rather than being hidden. */
 export function statusPhrase(status: string): string {
   switch (status) {
     case "working":
@@ -94,22 +100,16 @@ export function normalizeProgress(value: unknown): number {
   return Math.min(100, Math.round(value));
 }
 
-/** Whether the OSC 9;4 progress channel is speaking through this status; only
- *  these may show a bar. The server keeps sending the last percentage while the
- *  state persists, and `input`, `done`, `idle`, `exited` and `crashed` come from
- *  other channels, so a percentage under them is a claim about the wrong one. */
-export function statusOwnsProgress(status: string): boolean {
-  return status === "working" || status === STATUS_FAILED || status === STATUS_WARNING;
-}
-
-/** The percentage a status may SHOW. Two things clear it: the program's own
- *  OSC 9;4;0 (arriving as PROGRESS_ABSENT) and a status the channel does not own
- *  (kiro-cli parks state 4 at its context-usage percentage when idle, which once
- *  painted a done dot beside a 72% bar). Deliberately no third clear: 100% is a
- *  STATE that persists, and a timeout would assert a change the program never
- *  reported. */
+/** The percentage a status may SHOW. Under any live status it is the server's
+ *  value, because the status and the percentage can come from different
+ *  channels: OSC 7501 or a notification can set the status while OSC 9;4
+ *  supplies the percentage. Two things clear it: the server's PROGRESS_ABSENT
+ *  (the program cleared or never reported a percentage, e.g. OSC 9;4;0) and an
+ *  ended process, whose percentage nothing will ever clear. No timeout clears
+ *  it: 100% is a STATE that persists, and a timeout would assert a change the
+ *  program never reported. */
 export function renderedProgress(status: string, progress: number): number {
-  return statusOwnsProgress(status) ? progress : PROGRESS_ABSENT;
+  return isEndedStatus(status) ? PROGRESS_ABSENT : progress;
 }
 
 // The secondary-activity vocabulary: a host-reported background activity that
@@ -221,8 +221,8 @@ export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
 
 /** The cue statuses meaning the turn is OVER WITHOUT INCIDENT, the only ones a
  *  live background task may blank. `done` is the whole set: every other cue must
- *  reach the viewer AT ONCE, and `failed` here is OSC 9;4 state 2 rather than a
- *  turn verdict. */
+ *  reach the viewer AT ONCE, and `failed` is an error the program reported,
+ *  not a clean end of the turn. */
 const SETTLED_CUES: ReadonlySet<string> = new Set<CueStatus>(["done"]);
 
 /** The status the CUE surfaces see: the session's own, unless a settled turn's
@@ -380,10 +380,9 @@ export interface Tab {
   /** The chip's determinate progress bar (the 2px line on its bottom edge).
    *  Present on every chip, hidden until a percentage exists. */
   progressEl: HTMLElement;
-  /** The last OSC 9;4 percentage the server reported for this session, or
+  /** The last percentage the server reported for this session, or
    *  PROGRESS_ABSENT. Held raw: whether it is currently SHOWN is a render-time
-   *  question (renderedProgress), and the prefix it produces is never stored on
-   *  any title field. */
+   *  question (renderedProgress). */
   progress: number;
   /** The chip's secondary activity mark (the rounded-square ring beside the
    *  status dot). Present on every chip, and costing no layout until a state
@@ -403,9 +402,10 @@ export interface Tab {
    *  offset away, and it stopped meaning the same line once the session produced
    *  output while backgrounded. In memory only. */
   view: ViewMemory | null;
-  /** Sticky: true once this session emitted a genuine activity signal (OSC 9;4).
-   *  Its activity dot is shown only while true; a session that never reports
-   *  activity (a plain shell) keeps a clean, dot-less tab. Fed from the server's
+  /** Sticky: true once this session emitted a genuine activity signal (OSC 7501
+   *  status, OSC 9;4 progress or a classified OSC 9 notification). Its activity
+   *  dot is shown only while true; a session that never reports activity (a
+   *  plain shell) keeps a clean, dot-less tab. Fed from the server's
    *  reportsActivity via applyStatus. */
   reports: boolean;
   /** The user's pinned name (the server's `pinnedTitle` wire field). Outranks
@@ -565,8 +565,8 @@ const SESSION_API_TIMEOUT_MS = 15000;
 
 /** A non-2xx response from the session API, carrying what the server said. A
  *  host may TEMPORARILY refuse session creation (a 503 with `Retry-After` and a
- *  body message while it installs tools on first boot), and a caller that only
- *  saw an `Error` read that as a broken page. */
+ *  body message while it starts up), and a caller that only saw an `Error`
+ *  read that as a broken page. */
 export class SessionAPIError extends Error {
   /** HTTP status, so a caller can branch on 503 (retry) vs 429 vs 5xx. */
   readonly status: number;

package/src/features/tabs/strip.ts

@@ -14,7 +14,6 @@ import { activityPhrase, normalizeActivity, statusPhrase, statusRevealsDot } fro
 // motion is spelled in — index.ts owns the mechanism, strip.ts owns the values,
 // the same split switcher.ts keeps for the mobile swipe.
 
-// Twin of marotte static-src/tabs-drag.ts's constants; change both or neither.
 /** How long (ms) the pointer must have been un-moved before a position report at an
  *  unchanged position (a `dragover`, or the pointer path's re-report on this tick) is
  *  believed as "stopped". Small, because such a report is positive evidence of rest;
@@ -236,7 +235,7 @@ export function paintStatusDot(el: HTMLElement, status: string, reports: boolean
  *  a tooltip worded by activityPhrase. No state REMOVES the attribute, which is
  *  what collapses the mark's footprint to zero. The reveal is the mark's OWN
  *  state, not the status dot's reportsActivity gate: a background run is a fact
- *  independent of whether the program ever spoke OSC 9. */
+ *  independent of whether the program ever reported status. */
 export function paintActivityMark(el: HTMLElement, state: string, count: number): void {
   const phrase = activityPhrase(state, count);
   if (phrase === "") {

package/src/predict.ts

@@ -86,7 +86,7 @@ export function createPredictor(): Predictor {
           if (predCol > 0) {
             predCol--;
           } else if (predRow > 0) {
-            // kiro-cli's prompt wraps a Backspace at col 0 to the previous row.
+            // A line editor wraps a Backspace at col 0 to the previous row.
             predRow--;
             predCol = cols - 1;
           }

package/src/presets/agent-tabbed.ts

@@ -10,14 +10,12 @@ import { type TabbedPresetOptions, buildTabbed } from "./tabbed.js";
 /** 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.)
- *  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. */
+ *    activity (OSC 7501 status, OSC 9;4 progress or a classified OSC 9
+ *    notification), so the idle activity dot
+ *    shows from tab creation instead of popping in when the agent first
+ *    reports; the server's sticky reportsActivity flag then merely confirms.
+ *    (presetTabbed keeps the evidence-driven reveal: a plain shell never grows
+ *    a meaningless dot.) */
 export function presetAgentTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
   return buildTabbed(true, opts);
 }

package/src/presets/tabbed.ts

@@ -1,8 +1,7 @@
 /**
  * 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`.
+ * (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`).
  *
  * @module
  */
@@ -26,22 +25,15 @@ export interface TabbedPresetOptions {
   attentionIcons?: boolean;
 }
 
-/** buildTabbed composes the tabbed UI: the single-pane touch features, an
- *  externally-driven mobile toolbar (its grid is opened from a keyboard button
- *  in the tab bar, not its own toggle), the activity monitor (the status-SSE
- *  data source), tabs wired to both, and animations. The activity dot reveals
- *  itself per tab only when a session reports activity (OSC 9;4) — or from tab
- *  creation when the agent composition presumes it — so the monitor is always
- *  included; a plain shell under presetTabbed just never shows a dot. The
- *  toolbar and monitor are ordered before tabs because tabs reads their APIs
- *  via ctx.use. Shared by presetTabbed and presetAgentTabbed (agent-tabbed.ts),
- *  which now differ only in presumed activity reporting (presumeReports).
- *
- *  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. */
+/** buildTabbed composes the tabbed UI: the single-pane touch features, a mobile
+ *  toolbar opened from the tab bar's keyboard button, the activity monitor (the
+ *  status SSE), tabs wired to both, and animations. The monitor is always
+ *  included: a tab's dot shows only once its session reports activity (OSC
+ *  7501 status, OSC 9;4 progress or a classified OSC 9 notification), or from
+ *  creation under presumeReports.
+ *  The toolbar and monitor precede tabs, which reads their APIs via ctx.use.
+ *  Titles are the engine's: a browser that re-derived one would disagree with
+ *  the server and every other client. Shared with presetAgentTabbed. */
 export function buildTabbed(
   agentShell: boolean,
   opts: TabbedPresetOptions = {},

package/src/presets.ts

@@ -11,13 +11,14 @@
  * 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.
+ * every session's program is an agent that WILL report activity (OSC 7501
+ * status, OSC 9;4 progress or a classified OSC 9 notification), 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. Which status a session holds is the server's: the UI
+ * renders the status it is sent.
  *
  * @module
  */