@cplieger/web-terminal-ui 8.6.0-dev.8 → 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

@@ -80,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
@@ -100,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

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. */
@@ -660,13 +660,13 @@
 }
 
 /* ===== Activity dots: one .wt-status-dot vocabulary for the strip, the
-   switcher and the overview rows. Eight 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). A dot shows once
-   its session reports OSC 9;4 progress or a classified OSC 9 notification
-   (.wt-reports, set by paintStatusDot), or from creation under tabs'
-   presumeReports option; data-status is set either way. */
+   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;
@@ -688,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
@@ -746,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,

package/css/31-switcher.css

@@ -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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.6.0-dev.8",
+  "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",

package/src/features/tabs/index.ts

@@ -330,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,
@@ -1068,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
@@ -1140,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);
       }
@@ -3344,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
- *  (a state-4 percentage persists under a done latch, which state 4 does not
- *  clear, and would otherwise paint a bar beside a done dot). 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

package/src/features/tabs/strip.ts

@@ -235,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/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

@@ -29,10 +29,11 @@ export interface TabbedPresetOptions {
  *  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
- *  9;4), 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 by presetTabbed and presetAgentTabbed (agent-tabbed.ts). */
+ *  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
  */