@cplieger/web-terminal-ui 7.0.7 → 7.2.0

package/README.md

@@ -153,9 +153,25 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
   nowhere: no terminal emulator puts a percentage next to a tab label, and a chip
   that shrinks toward a 100px floor has no width to spare. It is likewise never
   written to the browser document title, since one page title cannot represent
-  several sessions. An OSC 9 notification is posted as a browser
-  notification when the user is not already looking at that terminal (permission
-  is requested on a user gesture; a denial degrades silently to the tab dots).
+  several sessions.
+
+  Beside that dot, every chip carries a second mark for a host-reported
+  background activity that outlives a turn (a workflow run, in the
+  `web-terminal-kiro` case). It is a rounded-square ring rather than a disc, so
+  it does not read as another status dot, and band width carries its three
+  states: a 2px band with a breathing glow while a background task is running, a
+  1px band with a halo while one is paused and resumable, and a 2px band with
+  that same halo while one is blocked on the user. The state and the count are
+  announced in the tab's accessible name and repeated as the mark's hover
+  tooltip. The mark is independent of the dot's reveal gate, so a tab can show
+  one and not the other, and it collapses to no width when there is nothing to
+  report: a chip with no background activity measures exactly as it did before
+  the mark existed. It draws from `--status-working` and `--status-input`, so
+  theming the activity-dot palette themes it too and no extra token is needed.
+
+  An OSC 9 notification is posted as a browser notification when the user is not
+  already looking at that terminal (permission is requested on a user gesture; a
+  denial degrades silently to the tab dots).
   Clicking one switches to the session that raised it: the Notifications API's
   own click default already focuses the page, and the handler supplies the
   in-page half. These are non-persistent notifications, so per the API the
@@ -186,7 +202,27 @@ want one, for example Ctrl+L); `reattach()` attaches again to whatever the serve
 serves now, for a session that has ended (see "When a session ends"); and
 `destroy()` tears every feature down and releases the kernel.
 
-### Persisting scrollback across a discard
+### Mouse and focus
+
+A terminal application that turns mouse tracking on receives the clicks, drags
+and wheel gestures a user makes in the browser, as SGR reports. The pointer says
+so while that is happening: at rest the grid carries a text cursor, and while an
+application holds the mouse the grid and any links in it carry an arrow instead,
+because a click is reported to that application rather than selecting text or
+opening the link. Shift-drag still selects and shift-click still opens a link,
+which is the convention xterm set, so nothing becomes unreachable.
+
+Mouse input is best-effort, as it is in every terminal: a report says where the
+pointer is at that moment and carries nothing a receiver could use to notice it
+had gone stale, so a report made while the socket is down is dropped rather than
+delivered late against a screen that has since been repainted. Typed input keeps
+its delivery guarantee and is unaffected.
+
+Focus reporting is the server's answer rather than this UI's. The kernel tells
+the server whether its own terminal widget holds focus and the server decides
+what the application is told, so several devices attached to one session cannot
+contradict each other. A blur that a press causes and that the same gesture's
+click undoes is not reported, because the terminal did not lose focus.
 
 `persistScrollback` takes the storage, not a switch, because storage is a
 decision this library should not make for you. Chrome's page-lifecycle guidance

package/css/02-terminal.css

@@ -149,6 +149,11 @@
      kernel focus handling + contextMenu feature). */
   user-select: text;
   -webkit-touch-callout: default;
+
+  /* Stated rather than inherited: the UA default over text is already an I-beam,
+     but the tracking rule below has to have something deterministic to override
+     (and to hand back to). */
+  cursor: text;
 }
 
 /* IME composition view: floating overlay positioned at the cursor
@@ -327,6 +332,18 @@
   --bg: var(--text-default);
 }
 
+/* An application holds the mouse (DEC 1000/1002/1003) and the kernel toggles
+   .wt-mouse-app on the scroll container. A plain click is reported to that
+   application, so neither the I-beam nor the link's pointer is true any longer:
+   both promise something the click no longer does. Deliberately no
+   `user-select: none` here, because the engine hands a shifted gesture to the
+   browser, so shift+drag selecting and shift+click opening a link are the only
+   ways left to reach either and blanketing selection off would remove them. */
+:where(.wt-root) .term.wt-mouse-app .term-output,
+:where(.wt-root) .term.wt-mouse-app .term-link {
+  cursor: default;
+}
+
 :where(.wt-root) .term-blink {
   animation: wt-blink-anim 1s step-end infinite;
 }

package/css/30-tabs.css

@@ -964,6 +964,120 @@
   border-color: var(--status-failed);
 }
 
+/* ===== Secondary activity mark (a host's background-activity channel) =====
+   A SECOND per-tab mark, orthogonal to the activity dot beside it: the dot
+   reports the session's turn, this reports a background task that outlives one.
+   Three states (working / waiting / input) and it WITHDRAWS when there is none.
+
+   It is a rounded-SQUARE RING, never a filled disc and never a pictogram, and
+   that silhouette is the WCAG 1.4.1 channel: the round dot sits 8px away at all
+   three chip sites, and the two share a hue vocabulary (--status-input is input's
+   dot colour too), so shape is what separates them at 9px. Between the mark's OWN
+   three states the channel is BAND WIDTH, in a deliberate 2:1 ratio, because
+   waiting and input share one ink.
+
+   A literal 3px radius, not --radius-sm: the smallest token rung is 4px, which on
+   a 9px box reads as a circle and defeats the silhouette.
+
+   It costs ZERO layout while no state is set. The footprint cancel is a negative
+   inline-start margin of exactly the box plus the chip's own flex gap, so the
+   label's box does not move when the element is added to a chip that has nothing
+   to report; setting data-activity zeroes the margin and the label shifts right by
+   that same amount. The gap term is per-site (31-switcher.css sets --sp-2 for the
+   two mobile chips), so it must stay a var() reference — a literal breaks whichever
+   site it does not match. box-sizing: border-box is global under .wt-root, so a
+   band change never moves layout either. */
+:where(.wt-root) .wt-activity-mark {
+  --wt-mark-size: 9px;
+  --wt-mark-gap: var(--sp-1);
+  /* waiting and input both speak through this ink and separate by band alone;
+     working overrides it. */
+  --wt-mark-ink: var(--status-input);
+
+  width: var(--wt-mark-size);
+  height: var(--wt-mark-size);
+  flex: none;
+  position: relative;
+  border-radius: 3px;
+  /* Zero-width at rest, so the ring is drawn entirely by a state's band. The
+     colour rides --wt-mark-ink here rather than in each state, so a state sets
+     one variable and one width. */
+  border: 0 solid var(--wt-mark-ink);
+  background: transparent;
+  opacity: 0;
+  /* While collapsed the box overlaps the status dot, and a title-less span over
+     the dot would eat the dot's own hover tooltip. Restored with the state. */
+  pointer-events: none;
+  margin-inline-start: calc(-1 * (var(--wt-mark-size) + var(--wt-mark-gap)));
+  /* Two lists, because the two directions are not symmetric. This one is the EXIT:
+     the mark fades out first and the space closes behind it, so nothing is still on
+     screen while the row reclaims its width. The ENTRY is on the [data-activity]
+     rule below, and it is what the tuck exists for.
+
+     The space is carried by a LAYOUT property on purpose: no transform moves the
+     label, and the label being pushed IS the reveal. Bounded to one flex line and
+     one mark plus one gap, once per state change. */
+  transition:
+    opacity var(--dur-exit) var(--ease-exit),
+    margin-inline-start var(--dur-standard) var(--ease-standard) var(--dur-exit);
+}
+
+/* The ENTRY, the reverse of the tuck's list: the space opens, and the mark fades in
+   after it on a delay equal to that same duration, so a reader sees the label make
+   room and then the mark arrive in the room it made. */
+:where(.wt-root) .wt-activity-mark[data-activity] {
+  margin-inline-start: 0;
+  opacity: 1;
+  pointer-events: auto;
+  transition:
+    margin-inline-start var(--dur-standard) var(--ease-standard),
+    opacity var(--dur-enter) var(--ease-enter) var(--dur-standard);
+}
+
+/* Working: the heavier bare band, plus a breathing glow. Its own compositing
+   layer for the reason the status dot's rule records — a nested overlay layer
+   snaps to device pixels independently of a fractional parent position, which at
+   this size reads as an off-centre pulse. */
+:where(.wt-root) .wt-activity-mark[data-activity="working"] {
+  --wt-mark-ink: var(--status-working);
+
+  border-width: 2px;
+  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). */
+:where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
+  content: "";
+  position: absolute;
+  inset: -1px;
+  border-radius: 4px;
+  background: radial-gradient(
+    closest-side,
+    color-mix(in oklch, var(--wt-mark-ink) 78%, #fff) 0 70%,
+    transparent 92%
+  );
+  opacity: 0;
+  animation: wt-activity-breath 1.2s ease-in-out infinite;
+  will-change: opacity;
+}
+
+/* Waiting: the thin band plus a static halo. Stopped and resumable, nobody being
+   asked — so no motion, and the lightest band of the three. */
+:where(.wt-root) .wt-activity-mark[data-activity="waiting"] {
+  border-width: 1px;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--wt-mark-ink) 30%, transparent);
+}
+
+/* Input: the same ink and the same halo as waiting, at TWICE its band. The pair
+   is the only place two states share one ink, which is why the ratio is 2:1
+   rather than a hairline apart. */
+:where(.wt-root) .wt-activity-mark[data-activity="input"] {
+  border-width: 2px;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--wt-mark-ink) 30%, transparent);
+}
+
 /* The disc's glow beat: base -> brighter -> base, then a rest until the next
    cycle — expressed as the opacity envelope of the pre-painted bright overlay
    (the ::before rule above), so the beat costs compositing, not repaints.
@@ -1019,6 +1133,21 @@
   }
 }
 
+/* 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. */
+@keyframes wt-activity-breath {
+  0%,
+  70%,
+  100% {
+    opacity: 0;
+  }
+
+  35% {
+    opacity: 1;
+  }
+}
+
 /* Reduced-motion: drop the animated states' motion (glow + ripple), keep color.
    All three degrade the same way, since they are one object with three hues. */
 @media (prefers-reduced-motion: reduce) {
@@ -1045,6 +1174,28 @@
   :where(.wt-root) .wt-status-dot[data-status="failed"]::after {
     content: none;
   }
+
+  /* Both of the mark's transition lists carry a DELAY on their second property,
+     and 01-scope.css zeroes animation and transition DURATIONS inside .wt-root
+     while saying nothing about delay — so an un-zeroed delay parks the fade with
+     the space already open, or the close with the mark already gone. The state
+     selector is listed because its own `transition` shorthand outranks the base
+     rule's delay and would otherwise keep the entry's. */
+  :where(.wt-root) .wt-activity-mark,
+  :where(.wt-root) .wt-activity-mark[data-activity] {
+    transition-delay: 0s;
+  }
+
+  /* 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). */
+  :where(.wt-root) .wt-activity-mark[data-activity="working"] {
+    border-width: 3px;
+  }
+
+  :where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
+    content: none;
+  }
 }
 
 /* ===== Catching-up cue (tabs feature, sections 12/13) =====

package/css/31-switcher.css

@@ -194,6 +194,17 @@
   min-width: 0;
 }
 
+/* The secondary activity mark's footprint cancel is "the box plus the chip's own
+   flex gap" (30-tabs.css), and these two chips lay their parts out on --sp-2
+   where the desktop chip uses --sp-1 — so the collapsed mark would leave 4px of
+   layout behind at both mobile sites. This is the one per-site value; the rendered
+   geometry test in features/tabs/chip-geometry.test.ts measures all three sites,
+   which is what stops it drifting. */
+:where(.wt-root) .wt-switcher-current-inner .wt-activity-mark,
+:where(.wt-root) .wt-switcher-row-select .wt-activity-mark {
+  --wt-mark-gap: var(--sp-2);
+}
+
 /* Ink-centring geometry, identical to .wt-tab-label: a symmetric ink allowance
    the ellipsis clipping needs, plus a bottom margin of twice --label-ink-shift
    that lifts the CAP band (cap top to baseline, never cap-to-descender) to the row

package/css/40-animations.css

@@ -45,9 +45,17 @@
 
 /* The chip's content dissolves as it becomes the drop slot, and comes back when the
    drag ends (30-tabs.css fades every child to nothing). One rule on the children,
-   not four per-part rules: the label, the status dot, the progress bar and the close
-   all leave together, because they leave for one reason. */
-:where(.wt-root.wt-animate) .wt-tab > * {
+   not a per-part rule each: the label, the status dot, the progress bar and the
+   close all leave together, because they leave for one reason.
+
+   The activity mark is the fifth child and is deliberately NOT one of them: it
+   animates on its own timing (30-tabs.css), a delayed fade that follows the
+   footprint snap. Both declarations are `transition` at equal specificity and this
+   file loads later, so dropping the :not() silently resets the mark's reveal at the
+   desktop chip while the two mobile chips, which are not .wt-tab children, keep it
+   — one element revealing two ways. chip-geometry.test.ts measures the resolved
+   values under .wt-animate at all three sites. */
+:where(.wt-root.wt-animate) .wt-tab > *:not(.wt-activity-mark) {
   transition: opacity var(--dur-micro) var(--ease-standard);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.7",
+  "version": "7.2.0",
   "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",
@@ -40,7 +40,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^5.0.3"
+    "@cplieger/web-terminal-engine": "^5.1.0"
   },
   "overrides": {
     "qs": "^6.15.2"
@@ -50,15 +50,15 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.4.1",
+    "@types/node": "26.5.1",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/browser": "5.0.0",
     "@vitest/browser-playwright": "5.0.0",
     "@vitest/coverage-v8": "5.0.0",
     "eslint": "10.10.0",
     "fast-check": "4.9.0",
-    "html-validate": "11.14.0",
-    "knip": "6.34.0",
+    "html-validate": "11.15.0",
+    "knip": "6.35.1",
     "playwright": "1.63.0",
     "prettier": "3.9.6",
     "stylelint": "17.15.0",

package/src/features/tabs/index.ts

@@ -29,10 +29,13 @@ import {
   compareTabOrder,
   createSessionAPI,
   createTombstones,
+  foldedCueStatus,
   hasPinnedName,
   isCueStatus,
   isEndedStatus,
   isUnseenCue,
+  normalizeActivity,
+  normalizeActivityCount,
   normalizeProgress,
   orderedInsertIndex,
   parseCueSeen,
@@ -54,6 +57,7 @@ import {
   TAB_HTML,
   kbButtonHTML,
   newButtonHTML,
+  paintActivityMark,
   paintProgress,
   paintStatusDot,
   pick,
@@ -498,6 +502,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // every expanded list row carries a .wt-progress-bar of its own, so an
       // unscoped pick would be ambiguous the moment the list is populated.
       const swProgress = pick(switcher, ".wt-switcher-current .wt-progress-bar");
+      // The active row's secondary activity mark, scoped for the same reason.
+      const swActivity = pick(switcher, ".wt-switcher-current .wt-activity-mark");
       const swClose = pick(switcher, ".wt-switcher-current-close");
       // The active-tab elements that translate together during a horizontal
       // swipe: the content (dot + label) and the close (x). Moving both keeps the
@@ -652,12 +658,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // is one: there is no state of its own to get out of step, so no path can
       // leave it stale, and it is cheap enough to run on every tick (a loop over a
       // handful of tabs, then sinks that no-op when nothing changed). The dot is
-      // the store — statusOf reads each tab's status back off it — so this reads
-      // exactly what the user is looking at.
+      // the store — cueStatusOf reads each tab's status back off it — so this and
+      // the raise in applyStatus fold the same value.
       function paintAttention(): void {
         attention.apply(
           summarize(
-            tabList.map((t) => ({ id: t.id, status: statusOf(t) })),
+            tabList.map((t) => ({ id: t.id, status: cueStatusOf(t) })),
             cueSeen,
           ),
         );
@@ -928,7 +934,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // is a 2px line with no text, so without this a screen-reader user
           // cannot tell a working tab from a crashed one, or hear how far along
           // a determinate one is.
-          t.aria.setLabel(tabAccessibleName(display, statusOf(t), shownProgress(t)));
+          t.aria.setLabel(
+            tabAccessibleName({
+              label: display,
+              status: statusOf(t),
+              progress: shownProgress(t),
+              activity: t.activity,
+              activityCount: t.activityCount,
+            }),
+          );
         }
       }
 
@@ -939,6 +953,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         return t.dot.dataset["status"] ?? "idle";
       }
 
+      /** cueStatusOf folds a tab for the cue surfaces (foldedCueStatus). Off the
+       *  DOT rather than the wire status, so a server's empty status arrives here
+       *  as "idle" and cannot be mistaken for the blanked-cue sentinel. */
+      function cueStatusOf(t: Tab): string {
+        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
@@ -1041,6 +1062,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         swLabel.textContent = active ? active.display : "";
         paintStatusDot(swDot, active ? statusOf(active) : "idle", active?.reports ?? false);
         paintProgress(swProgress, active ? shownProgress(active) : PROGRESS_ABSENT);
+        paintActivityMark(swActivity, active?.activity ?? "", active?.activityCount ?? 0);
         // The aggregate background-notification cue rides the dedicated switch
         // button's dot (paintSwitchDot), not the active surface (it did not fit
         // there).
@@ -1066,6 +1088,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function updateRow(row: HTMLElement, t: Tab): void {
         paintStatusDot(pick(row, ".wt-switcher-row-dot"), statusOf(t), t.reports);
         paintProgress(pick(row, ".wt-progress-bar"), shownProgress(t));
+        paintActivityMark(pick(row, ".wt-activity-mark"), t.activity, t.activityCount);
         pick(row, ".wt-switcher-row-label").textContent = t.display;
       }
       // renderSwitcherList reconciles the expanded list to a row per OTHER tab
@@ -1444,9 +1467,10 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         const el = fromHTML(TAB_HTML);
         const label = el.querySelector<HTMLElement>(".wt-tab-label");
         const dot = el.querySelector<HTMLElement>(".wt-tab-dot");
+        const activityEl = el.querySelector<HTMLElement>(".wt-activity-mark");
         const progressEl = el.querySelector<HTMLElement>(".wt-progress-bar");
         const close = el.querySelector<HTMLButtonElement>(".wt-tab-close");
-        if (!label || !dot || !progressEl || !close) {
+        if (!label || !dot || !activityEl || !progressEl || !close) {
           throw new Error("web-terminal-ui: tab chrome missing parts");
         }
         paintStatusDot(dot, info.status, reportsOf(info.reportsActivity));
@@ -1482,21 +1506,31 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           el,
           label,
           dot,
+          activityEl,
           progressEl,
           // A percentage exists only on the status STREAM, so a tab adopted from
           // the REST list starts with none; the first status event fills it in.
           progress: normalizeProgress(info.progressValue),
+          activity: normalizeActivity(info.activity),
+          activityCount: normalizeActivityCount(info.activityCount),
           aria,
           view: null,
           reports: reportsOf(info.reportsActivity),
         };
         paintProgress(progressEl, renderedProgress(info.status, tab.progress));
+        paintActivityMark(activityEl, tab.activity, tab.activityCount);
         // Set an initial label immediately (relabelAll refines it with de-dup
         // once the tab is in tabList and syncChrome runs).
         tab.display = baseLabel(tab).text;
         label.textContent = tab.display;
         aria.setLabel(
-          tabAccessibleName(tab.display, info.status, renderedProgress(info.status, tab.progress)),
+          tabAccessibleName({
+            label: tab.display,
+            status: info.status,
+            progress: renderedProgress(info.status, tab.progress),
+            activity: tab.activity,
+            activityCount: tab.activityCount,
+          }),
         );
         el.addEventListener("click", (e) => {
           if ((e.target as HTMLElement).closest(".wt-tab-close")) {
@@ -3307,6 +3341,18 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           t.progress = normalizeProgress(rec.progressValue);
         }
         paintProgress(t.progressEl, shownProgress(t));
+        // The host's secondary activity, read with the same PRESENT-only guard and
+        // for the same reason: the polling fallback lists SessionInfo, and a
+        // pre-release server carries neither field at all, so reading absence as
+        // "no background task" would blank a live mark on every tick. An empty
+        // string IS the withdrawal, and it arrives explicitly.
+        if (rec.activity !== undefined) {
+          t.activity = normalizeActivity(rec.activity);
+        }
+        if (rec.activityCount !== undefined) {
+          t.activityCount = normalizeActivityCount(rec.activityCount);
+        }
+        paintActivityMark(t.activityEl, t.activity, t.activityCount);
         // A session that reports activity is a session whose program speaks OSC 9,
         // so it is also one that may post a notification: arm the permission
         // request for the next user gesture (see notify.ts).
@@ -3327,9 +3373,17 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // dismissal stick across those is cueSeen — a latch this viewer already
         // acknowledged raises nothing, while a status that moved on drops the
         // acknowledgement so the next latch is a fresh cue.
-        if (!isCueStatus(rec.status)) {
-          forgetCueSeen(rec.id);
-        } else if (rec.id === activeId && pageVisible()) {
+        //
+        // Two inputs, one per question, and the ORDER keeps them apart. The
+        // acknowledgement asks whether this reader has SEEN the tab's real state:
+        // RAW status, first, and only for a cue — a non-cue one has nothing to
+        // acknowledge and has to reach the forget below. The raise and the forget
+        // ask whether anything should be ANNOUNCED: folded. Off the fold the
+        // acknowledgement misses a watched turn until its task ends; off the raw
+        // status the forget makes the "" sentinel pointless.
+        const raw = statusOf(t);
+        const cue = cueStatusOf(t);
+        if (rec.id === activeId && pageVisible() && isCueStatus(raw)) {
           // The user is looking at this terminal as it latches, so there is
           // nothing to notify — and nothing to re-raise once they move away.
           //
@@ -3340,9 +3394,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // it is precisely the case the out-of-page surfaces exist for, so a
           // latch arriving on a HIDDEN page now raises them and is acknowledged
           // when the user comes back (see onPageVisible).
-          markCueSeen(rec.id, rec.status);
-        } else if (isUnseenCue(rec.status, rec.id, cueSeen)) {
-          switchNotify = rec.status;
+          markCueSeen(rec.id, raw);
+        } else if (cue === "") {
+          // A blanked cue is NO INFORMATION, not a state, so nothing is raised and
+          // the acknowledgement map is left alone: forgetting here would re-raise
+          // the cue from scratch the moment the background task ended.
+        } else if (!isCueStatus(cue)) {
+          forgetCueSeen(rec.id);
+        } else if (isUnseenCue(cue, rec.id, cueSeen)) {
+          switchNotify = cue;
           switchNotifyId = rec.id;
           paintSwitchDot();
         }

package/src/features/tabs/model.ts

@@ -20,8 +20,19 @@ export type { SessionInfo };
  *  (SessionStatus.progressValue). Both status sources flow through one code path
  *  this way, and the optionality is meaningful: the polling fallback lists
  *  SessionInfo with no percentage at all, which means "no information" and must
- *  not be read as "the percentage was cleared". */
-export type StatusRecord = SessionInfo & { readonly progressValue?: number };
+ *  not be read as "the percentage was cleared".
+ *
+ *  `activity`/`activityCount` are declared here as a FORWARD declaration: the
+ *  published engine's SessionInfo does not carry them yet. Drop both from this
+ *  intersection once it does, so the wire shape has one home again — if the
+ *  intersection then narrows anything, the engine's declaration is the wrong
+ *  one. Both are `string`/`number` rather than unions for the same reason
+ *  `status` is: the stream is parsed, not validated. */
+export type StatusRecord = SessionInfo & {
+  readonly progressValue?: number;
+  readonly activity?: string;
+  readonly activityCount?: number;
+};
 
 // The status vocabulary, module-private on purpose: every consumer asks one of
 // the predicates below (isEndedStatus / statusRevealsDot / isCueStatus /
@@ -161,6 +172,63 @@ export function renderedProgress(status: string, progress: number): number {
   return statusOwnsProgress(status) ? progress : PROGRESS_ABSENT;
 }
 
+// The secondary-activity vocabulary: a host-reported background activity that
+// OUTLIVES the turn, orthogonal to the status above. Module-private for the same
+// reason the status vocabulary is — every consumer asks a predicate, so a state's
+// MEANING has one home.
+//
+// A background task is running.
+const ACTIVITY_WORKING = "working";
+// Stopped and resumable; nobody is being asked for anything.
+const ACTIVITY_WAITING = "waiting";
+// A background task is blocked on the user.
+const ACTIVITY_INPUT = "input";
+
+/** normalizeActivity cleans the wire value into the closed set, or "" for no
+ *  mark. Anything outside it — an unknown state from a newer server, a
+ *  non-string, absent — is "": an unrecognised state must fail toward NO mark
+ *  rather than toward a lit one whose meaning this build cannot name. */
+export function normalizeActivity(value: unknown): string {
+  if (value === ACTIVITY_WORKING || value === ACTIVITY_WAITING || value === ACTIVITY_INPUT) {
+    return value;
+  }
+  return "";
+}
+
+/** normalizeActivityCount cleans the count off the wire: a non-integer, a
+ *  negative or an absent value is 0. The engine documents count >= 1 whenever
+ *  the state is non-empty, so 0 beside a live state is a server that does not
+ *  count, which activityPhrase reads as one. */
+export function normalizeActivityCount(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    return 0;
+  }
+  return value;
+}
+
+/** activityPhrase is the human wording for the mark, used for BOTH its hover
+ *  tooltip and the suffix in a tab's accessible name — one definition, so what a
+ *  sighted user reads on hover and what a screen reader announces cannot
+ *  disagree (the statusPhrase rule). "" for no mark.
+ *
+ *  It cannot say "workflow": the secondary channel is generic, so the wording has
+ *  to be true for whatever a host puts on it. */
+export function activityPhrase(state: string, count: number): string {
+  const normalized = normalizeActivity(state);
+  if (normalized === "") {
+    return "";
+  }
+  const n = Math.max(1, normalizeActivityCount(count));
+  const subject = `${String(n)} background task${n === 1 ? "" : "s"}`;
+  if (normalized === ACTIVITY_WORKING) {
+    return `${subject} running`;
+  }
+  if (normalized === ACTIVITY_WAITING) {
+    return `${subject} paused`;
+  }
+  return `${subject} waiting for you`;
+}
+
 /** tabAccessibleName is a tab's announced name: its rendered label plus the
  *  session's state, and the percentage when one is showing.
  *
@@ -173,16 +241,23 @@ export function renderedProgress(status: string, progress: number): number {
  *
  *  Pass PROGRESS_ABSENT for progress to announce the state alone. Callers hand in
  *  renderedProgress's output, so a percentage the tab is not showing is not
- *  announced either. */
-export function tabAccessibleName(
-  renderedLabel: string,
-  status: string,
-  progress: number = PROGRESS_ABSENT,
-): string {
-  const state = statusPhrase(status);
-  return progress < 0
-    ? `${renderedLabel} — ${state}`
-    : `${renderedLabel} — ${state}, ${String(progress)}%`;
+ *  announced either.
+ *
+ *  A RECORD rather than positional arguments: `label` and `status` are adjacent
+ *  same-typed strings, so a transposition compiles. */
+export function tabAccessibleName(v: {
+  readonly label: string;
+  readonly status: string;
+  readonly progress?: number;
+  readonly activity?: string;
+  readonly activityCount?: number;
+}): string {
+  const state = statusPhrase(v.status);
+  const progress = v.progress ?? PROGRESS_ABSENT;
+  const head =
+    progress < 0 ? `${v.label} — ${state}` : `${v.label} — ${state}, ${String(progress)}%`;
+  const activity = activityPhrase(v.activity ?? "", v.activityCount ?? 0);
+  return activity === "" ? head : `${head} (${activity})`;
 }
 
 // localStorage key for the last active session id, so a page reload reopens the
@@ -251,6 +326,37 @@ export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
   return "alert";
 }
 
+/** The cue statuses that mean the session's own turn is OVER WITHOUT INCIDENT, and
+ *  therefore the only ones a live background task may blank.
+ *
+ *  Narrow on purpose, and `done` is the whole set. Every other cue status is
+ *  something the viewer has to be told AT ONCE, so none of them may wait on a task:
+ *  `crashed` and `exited` mean the PROCESS is gone (and a task belonging to a dead
+ *  session is dead too), `input` IS what the viewer is being pointed at whatever
+ *  else the session is doing, and `failed` is an error the program declared, which
+ *  does not become less urgent because something else is still running. On this
+ *  engine's path `failed` is OSC 9;4 state 2 rather than a turn verdict, so it is
+ *  deliberately NOT treated the way vibekit's settle probe treats its own `failed`
+ *  (see web-terminal-engine.md). */
+const SETTLED_CUES: ReadonlySet<string> = new Set<CueStatus>(["done"]);
+
+/** foldedCueStatus is the status the CUE surfaces see for a session: its own
+ *  status, unless a settled turn's background task is still running, in which
+ *  case "". Nothing about the status DOT changes — the strip keeps rendering the
+ *  turn's real state; only the cue's view of it is blanked.
+ *
+ *  "" and NOT "idle", and the difference is load-bearing: "" means NO
+ *  INFORMATION, so a caller must leave the wt-cue-seen map alone, where "idle" is
+ *  a real non-cue state that FORGETS the acknowledgement. Blanking with "idle"
+ *  would drop the dismissal and re-raise the cue from scratch the moment the task
+ *  ended, even for a session the viewer had already visited. */
+export function foldedCueStatus(status: string, activity: string): string {
+  if (!SETTLED_CUES.has(status) || normalizeActivity(activity) === "") {
+    return status;
+  }
+  return "";
+}
+
 /** isUnseenCue reports whether a session's CURRENT status is a cue this viewer
  *  has not acknowledged. The single predicate behind both the raise and the
  *  attention count, so a dot can never light for a session the count omits.
@@ -460,6 +566,16 @@ export interface Tab {
    *  question (renderedProgress), and the prefix it produces is never stored on
    *  any title field. */
   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
+   *  arrives. */
+  activityEl: HTMLElement;
+  /** The host's secondary activity state for this session, normalised to the
+   *  closed set ("" for none). Independent of `status` and of `reports`: a
+   *  background task can be running while the turn that launched it is finished. */
+  activity: string;
+  /** How many sources produced that state, 0 when the server does not count. */
+  activityCount: number;
   aria: TabHandle;
   /** This tab's saved reading position: the absolute LINE at the viewport top
    *  plus its on-screen offset and the follow state, as captureViewMemory()

package/src/features/tabs/strip.ts

@@ -10,7 +10,7 @@
 // The status vocabulary itself (which statuses reveal a dot, and how each one is
 // worded for a human) lives in the DOM-free model, so the painters here and the
 // accessible names index.ts builds read one definition.
-import { statusPhrase, statusRevealsDot } from "./model.js";
+import { activityPhrase, normalizeActivity, statusPhrase, statusRevealsDot } from "./model.js";
 
 // --- Reorder preview -------------------------------------------------------
 // Every chip in this strip is the same width (see .wt-tab in 30-tabs.css: a
@@ -121,6 +121,13 @@ const SWITCH_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="8
 // class (.wt-progress-bar) styles it everywhere and every chip site gets it for
 // free. It starts `hidden` — a session with no percentage must render NO bar
 // (paintProgress).
+//
+// The secondary activity mark (.wt-activity-mark) rides here for the same reason
+// and takes no per-site class either. It carries NO `hidden` attribute, unlike
+// the bar: `hidden` is display:none, and an element out of layout cannot animate
+// into it. Absence is the absence of `data-activity`, which the CSS answers by
+// cancelling the mark's own footprint (see 30-tabs.css), so a chip with no
+// secondary activity measures exactly as it did before this element existed.
 export function chipContent(v: { dot: string; label: string; close: string; closeAttr?: string }): {
   dotLabel: string;
   close: string;
@@ -128,6 +135,7 @@ export function chipContent(v: { dot: string; label: string; close: string; clos
   return {
     dotLabel:
       `<span class="${v.dot} wt-status-dot" aria-hidden="true"></span>` +
+      `<span class="wt-activity-mark" aria-hidden="true"></span>` +
       `<span class="${v.label}"></span>` +
       `<span class="wt-progress-bar" aria-hidden="true" hidden></span>`,
     close: `<button type="button" class="${v.close}" aria-label="Close terminal"${v.closeAttr ?? ""}>${CLOSE_SVG}</button>`,
@@ -195,6 +203,27 @@ export function paintStatusDot(el: HTMLElement, status: string, reports: boolean
   el.title = statusPhrase(value);
 }
 
+/** paintActivityMark applies the secondary mark's two bits: data-activity drives
+ *  its appearance (working / waiting / input via CSS) and `title` gives it a
+ *  hover tooltip, worded by activityPhrase so hover text and announced text
+ *  cannot drift. No state REMOVES the attribute, which is what collapses the
+ *  mark's footprint to zero.
+ *
+ *  The reveal is the mark's OWN state, deliberately not the status dot's
+ *  reportsActivity gate: a background run is a fact about the session that is
+ *  independent of whether its program ever spoke OSC 9, which is the whole point
+ *  of a second mark. */
+export function paintActivityMark(el: HTMLElement, state: string, count: number): void {
+  const phrase = activityPhrase(state, count);
+  if (phrase === "") {
+    delete el.dataset["activity"];
+    el.removeAttribute("title");
+    return;
+  }
+  el.dataset["activity"] = normalizeActivity(state);
+  el.title = phrase;
+}
+
 /** paintProgress renders one chip's determinate progress bar from a percentage.
  *
  *  An absent percentage (PROGRESS_ABSENT / any negative) renders NO bar: the

package/src/kernel/kernel.ts

@@ -13,12 +13,11 @@
 // still single-instance, so createTerminal is called once per page (tabs
 // multiplex sessions over the one kernel, section 22.5).
 //
-// Mouse tracking (engine `mouse` module) is intentionally NOT wired here yet:
-// the design adds it (section 22.3), but wiring it also brings DEC 1004 focus
-// emission, which must be suppressed under the keep-unfocused model (section
-// 7.2). Not wiring it keeps the client emitting no focus bytes (the safe
-// default the previous UI already had); adding mouse tracking with focus
-// suppression is a tracked follow-up.
+// The kernel owns the terminal widget's DOM, so it owns the widget's focus: it
+// REPORTS focus and blur to the transport (`connection.setClientFocus`) and
+// never writes DEC 1004 bytes itself. The server derives the answer for the
+// session from every attached client's report plus its own hold, which is the
+// only place the question can be answered once a second device attaches.
 
 import {
   render,
@@ -26,6 +25,7 @@ import {
   connection,
   keyboard,
   modes,
+  mouse,
   LineStore,
 } from "@cplieger/web-terminal-engine";
 import * as composition from "../composition.js";
@@ -400,9 +400,9 @@ function buildTerminal(
     // output never does (the scroll controller's follow/hold job is unchanged),
     // so scrolling up to read while output streams is preserved. A no-op on the
     // alt screen (no scrollback) and when already following. NOTE: every caller
-    // of sendBytes today is genuine user input (typed keys, paste, mobile
-    // toolbar); if mouse tracking is ever wired through ctx.send, its motion
-    // bytes must NOT come through here or the view would snap on every move.
+    // of sendBytes is genuine user input (typed keys, paste, mobile toolbar);
+    // mouse reports deliberately bypass this funnel and go out as ephemeral
+    // input, or the view would snap on every motion report.
     scroll.scrollToBottom();
     for (const obs of inputObservers) {
       obs(out);
@@ -575,6 +575,100 @@ function buildTerminal(
   });
   render.updateFontMetrics();
 
+  // A mouse report is BEST-EFFORT and never enters the reliable outbox: it
+  // carries no sequence number, so one retransmitted after a resume describes a
+  // screen since repainted, and `sendEphemeral` refuses rather than queues. Not
+  // sendBytes either: that funnel snaps the view to the bottom on every accepted
+  // byte, so a motion report would jump the viewport. The listeners belong on the
+  // scroll container (a click in its padding or over the reserved scrollbar
+  // gutter never reaches a row, and the wheel has to be cancellable there); the
+  // coordinate frame is the row container, whose box IS the grid.
+  const disposeMouse = mouse.init({
+    sendReport: (data) => connection.sendEphemeral(data),
+    cellSize: render.cellSize,
+    termElement: () => termWrap,
+    gridElement: () => outputEl,
+    // The RENDERED grid, not computeSize(): the row hit test anchors on its
+    // height, and this client's own measurement disagrees with the negotiated
+    // screen whenever a second device is attached or a local resize has not been
+    // answered yet, which would shift every reported row.
+    gridSize: render.gridSize,
+  });
+
+  // A press over the display-only output takes focus off the hidden textarea and
+  // the click handler below puts it back, so that blur/focus pair is an artifact
+  // of this input model, not a focus change the application should be told about.
+  // xterm.js never emits one because its textarea keeps focus through a click on
+  // the terminal. So a blur raised inside a press is withheld and the gesture's
+  // REAL end state is reported once it resolves: nothing when focus came back,
+  // one report when it did not (a live selection, a link and a bare touch tap all
+  // decline to restore it). Measured before this: 3600 focus reports in 90s of
+  // clicking, which reaches an application as FocusLost/FocusGained per click.
+  let pressHoldsFocus = false;
+  let focusResolve: ReturnType<typeof setTimeout> | null = null;
+
+  function reportFocusNow(): void {
+    connection.setClientFocus(
+      document.activeElement !== null && termWrap.contains(document.activeElement),
+    );
+  }
+
+  // Scheduled rather than read at pointerup: the focus restore happens in the
+  // `click` handler, which the browser dispatches after pointerup within the same
+  // task, so a task boundary is the first point where the end state is settled.
+  function endPressFocusGesture(): void {
+    if (focusResolve !== null) {
+      clearTimeout(focusResolve);
+    }
+    focusResolve = setTimeout(() => {
+      focusResolve = null;
+      pressHoldsFocus = false;
+      reportFocusNow();
+    }, 0);
+  }
+
+  // The keyboard target is the hidden textarea INSIDE termWrap, so the widget's
+  // own focus events bubble to here. What goes out is the widget's STATE, not
+  // DEC 1004 bytes: the server derives the answer from this report plus every
+  // other attached client's plus its own hold.
+  termWrap.addEventListener(
+    "focusin",
+    () => {
+      connection.setClientFocus(true);
+    },
+    { signal },
+  );
+  termWrap.addEventListener(
+    "focusout",
+    (ev) => {
+      if (ev.relatedTarget instanceof Node && termWrap.contains(ev.relatedTarget)) {
+        return; // focus moving WITHIN the terminal is not a blur
+      }
+      if (pressHoldsFocus) {
+        return; // this gesture's own doing; endPressFocusGesture reports the truth
+      }
+      connection.setClientFocus(false);
+    },
+    { signal },
+  );
+  // Seeded once, so a terminal mounted with its textarea already focused does not
+  // report blurred until the first real focusin.
+  reportFocusNow();
+
+  // The kernel is the toggler, and the class goes on the scroll container rather
+  // than on the rows: `.term-output` is replaced wholesale by the renderer, and
+  // `.term` is the element that survives every rebuild. What the shape MEANS is
+  // at the CSS rule it drives (css/02-terminal.css).
+  function updateMousePointer(): void {
+    termWrap.classList.toggle("wt-mouse-app", modes.getMouseMode() !== 0);
+  }
+
+  // Derived once here as well as from the two triggers below: the modes module is
+  // a singleton that outlives a terminal, so a re-created terminal on a page
+  // whose mirror already holds a tracking mode would otherwise show the resting
+  // pointer until the next frame.
+  updateMousePointer();
+
   composition.init({
     textarea: input,
     compositionView: compositionViewEl,
@@ -698,6 +792,7 @@ function buildTerminal(
         bus.emit("wire:title", { session: activeSession?.id ?? "", title: msg.title });
       } else if (msg.type === "modes") {
         render.updateReverseVideo();
+        updateMousePointer();
         bus.emit("wire:modes", msg);
       } else if (msg.type === "clipboard") {
         // Inbound OSC 52. With no clipboard feature subscribed this is a no-op
@@ -969,9 +1064,13 @@ function buildTerminal(
       pointerDownX = e.clientX;
       pointerDownY = e.clientY;
       pointerDownTime = e.timeStamp;
+      pressHoldsFocus = true;
     },
     { passive: true, signal },
   );
+  for (const end of ["pointerup", "pointercancel", "lostpointercapture"] as const) {
+    termWrap.addEventListener(end, endPressFocusGesture, { passive: true, signal });
+  }
   termWrap.addEventListener(
     "pointerup",
     (e) => {
@@ -1476,6 +1575,11 @@ function buildTerminal(
     // detach here and the onSwitch attach below.
     composition.cancelComposition();
     resetToPlaceholder(input);
+    // A held mouse gesture is latched input too, and the mouse module is per
+    // TERMINAL while sessions multiplex over it: a record kept across the switch
+    // would let the incoming session's first open synthesize a release for a
+    // press its application never saw.
+    mouse.disarmGesture();
     for (const { instance } of instances) {
       instance.onDetach?.();
     }
@@ -1483,6 +1587,9 @@ function buildTerminal(
     // Reconnect the terminal WS to this session using its per-tab resume
     // state; the renderer was already pointed at its store by the owner.
     connection.setSession(session.id);
+    // setSession restores the incoming session's mode mirror synchronously and
+    // delivers no modes frame, so nothing else re-derives the pointer here.
+    updateMousePointer();
     // The owned first connect has happened (session id is now on the WS URL);
     // wake-reconnect handlers may fire from here on.
     connectionInitiated = true;
@@ -1671,12 +1778,17 @@ function buildTerminal(
     // Reset the composition singleton: a failure during an IME cycle must not
     // leave module state or a deferred send alive for a later terminal mount.
     composition.teardown();
+    disposeMouse();
     connection.disconnect();
     connState.destroy();
     if (toastTimer !== null) {
       clearTimeout(toastTimer);
       toastTimer = null;
     }
+    if (focusResolve !== null) {
+      clearTimeout(focusResolve);
+      focusResolve = null;
+    }
     for (const off of subscriptions) {
       off();
     }

package/src/kernel/scrollback.ts

@@ -115,7 +115,11 @@ interface StoredEntry {
  * neither could be observed: 15 of the file's 19 surviving mutants were those
  * two guards and their bodies.
  */
-function readStoredEntry(entry: NonNullable<unknown>): StoredEntry | null {
+// Spelled `{}` rather than `NonNullable<unknown>`: the two are the same type, and
+// only the second is a type OPERATION, which `no-generated-empty-object-type`
+// (typescript-eslint 8.70+) reports even where resolving to `{}` is the point.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- "any non-nullish value" is the intended type; the paragraph above says why there is no object test here
+function readStoredEntry(entry: {}): StoredEntry | null {
   const rec = entry as Record<string, unknown>;
   const savedAt = rec["savedAt"];
   // Finite, not merely a number: the age comparison below is a subtraction, and