@cplieger/web-terminal-engine 3.0.6 → 3.2.0

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.0.6",
+  "version": "3.2.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.0.6",
+  "version": "3.2.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -21,13 +21,16 @@
     "esbuild": "0.28.1",
     "eslint": "10.7.0",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.0",
+    "happy-dom": "20.11.1",
     "pngjs": "7.0.0",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.65.0",
     "vitest": "4.1.10"
   },
+  "overrides": {
+    "qs": "^6.15.2"
+  },
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",
   "license": "GPL-3.0-or-later",
   "exports": {

package/src/render.ts

@@ -249,7 +249,7 @@ export function init(opts: {
   }
   flushDrainedThisPass = 0;
   renderNoProgressStreak = 0;
-  startCursorBlink();
+  syncCursorBlink();
 }
 
 /**
@@ -669,8 +669,80 @@ function scheduleFlush(): void {
   pendingFrame = requestAnimationFrame(flushRender);
 }
 
+// --- Read-position anchoring (manual scroll anchoring) ---
+//
+// A flush can change the content height ABOVE the reading position: rows evicted
+// from the top of history once the retention cap is reached, and the trim marker
+// appearing. Every such change moves whatever the user is reading, unless the
+// viewport is shifted by the same amount.
+//
+// Chrome and Firefox do that natively (scroll anchoring, `overflow-anchor`).
+// WebKit does not implement it at all, so on Safari — including the iPad, where
+// this UI mostly runs — a user scrolled up to read had their position dragged
+// one line per evicted row for as long as output kept arriving.
+//
+// The anchor is the first row at or below the viewport top, found by binary
+// search over the container's children: they are in document order, so their
+// offsetTop is monotonic. ~13 reads for a full 5000-row buffer, and only while
+// the user is actually scrolled up — a following viewport takes this path not at
+// all, because the bottom pin owns its position.
+interface ReadAnchor {
+  el: HTMLElement;
+  /** Where the row sat ON SCREEN: offsetTop minus the scroll offset. Measuring
+   *  the screen position rather than the container offset is what makes the
+   *  correction idempotent — see restoreReadAnchor. */
+  screenTop: number;
+}
+
+function captureReadAnchor(): ReadAnchor | null {
+  if (!scroll.isUserScrolledUp()) {
+    return null; // following: stickToBottom owns the position
+  }
+  const kids = output.children;
+  if (kids.length === 0) {
+    return null;
+  }
+  const offset = scroll.currentScrollTop();
+  let lo = 0;
+  let hi = kids.length - 1;
+  let found: HTMLElement | null = null;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const el = kids[mid] as HTMLElement;
+    if (el.offsetTop >= offset) {
+      found = el;
+      hi = mid - 1;
+    } else {
+      lo = mid + 1;
+    }
+  }
+  // Everything is above the viewport top (a shrink already clamped past the
+  // last row): anchor on the last row rather than giving up.
+  const el = found ?? (kids[kids.length - 1] as HTMLElement);
+  return { el, screenTop: el.offsetTop - offset };
+}
+
+function restoreReadAnchor(anchor: ReadAnchor | null): void {
+  if (anchor?.el.parentElement !== output) {
+    return; // not holding, or the anchor row was itself evicted (mass trim)
+  }
+  // Correct by how far the row DRIFTED ON SCREEN, not by how much the content
+  // above it changed. The two differ exactly when the browser already did this
+  // itself: Chrome and Firefox have native scroll anchoring, so their offsetTop
+  // change comes with a matching scrollTop change and the screen position is
+  // already right — this then measures zero drift and does nothing. Correcting
+  // the content delta instead would double-compensate there and throw the view
+  // the other way. On Safari, which has no native anchoring, the drift is the
+  // whole content delta and this is the only thing that fixes it.
+  const drift = anchor.el.offsetTop - scroll.currentScrollTop() - anchor.screenTop;
+  scroll.adjustForContentShift(drift);
+}
+
 function flushRender(): void {
   pendingFrame = undefined;
+  // Measured BEFORE any DOM mutation, so the post-mutation read below reveals
+  // exactly how much the content above the reading position moved.
+  const anchor = captureReadAnchor();
   try {
     flushRenderInner();
     // A clean pass means the error condition (if any) has cleared, so give a
@@ -704,6 +776,12 @@ function flushRender(): void {
       console.error("vterm: giving up render retry after repeated no-progress errors");
     }
   }
+  // Two position invariants, applied after every DOM mutation and in this order:
+  // hold the reader's line against content that shifted above it, then (only if
+  // following) pin to the new bottom. They are mutually exclusive by
+  // construction — the anchor is null while following — so the order is for
+  // readability, not correctness.
+  restoreReadAnchor(anchor);
   // Single auto-follow invariant, applied after every DOM mutation.
   stickToBottomIfFollowing();
 }
@@ -739,7 +817,11 @@ function flushRenderInner(): void {
   cursorCol = win.cursorCol;
   cursorHidden = win.cursorHidden;
   cursorStyleVal = win.cursorStyle;
-  setCursorBlink(win.cursorBlink);
+  blinkEnabled = win.cursorBlink;
+  // Reconcile the blink interval with the fresh cursor state (blink mode and
+  // DECTCM visibility may both have changed this frame); no-op when the
+  // resulting mode is unchanged.
+  syncCursorBlink();
 
   // Alt screen: render the ephemeral grid instead of the absolute buffer.
   // Returning here skips the dirtyLines queueing below — safe by invariant:
@@ -954,8 +1036,20 @@ function stickToBottomIfFollowing(): void {
 
 // --- Cursor blink ---
 const CURSOR_BLINK_MS = 530;
+// While the application hides the cursor (DECTCM — e.g. a full-screen TUI
+// that paints its own cursor cell, like an agent front-end), the fast toggle
+// would only restyle a display:none overlay, so the interval downshifts to
+// this slow re-check: still polling for the cursor's return (a self-healing
+// backstop even if a transition frame were somehow missed — the flush hook is
+// the primary, instant restart), at a fraction of the 530ms blink's wakeups.
+// For agent consumers the hidden-cursor state is the session's steady state.
+const CURSOR_RECHECK_MS = 4000;
 let blinkInterval: ReturnType<typeof setInterval> | null = null;
 let blinkEnabled = true;
+// What the running interval (if any) is configured as. syncCursorBlink()
+// reconfigures only on mode change, so it is safe to call on every flush.
+type BlinkMode = "off" | "idle" | "fast";
+let blinkMode: BlinkMode = "off";
 
 // hiddenDoc reports whether the page is currently background/hidden. The blink
 // interval is gated on it: rAF-driven flushes already freeze in a hidden tab,
@@ -965,25 +1059,42 @@ function hiddenDoc(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
 
-function startCursorBlink(): void {
-  if (blinkInterval !== null || !blinkEnabled || hiddenDoc()) {
-    return;
+// desiredBlinkMode folds the three gates into an interval mode: no timer at
+// all when blinking is disabled or the page is hidden (both have event-driven
+// restarts — the next mode frame's flush and visibilitychange), the fast
+// phase toggle when the cursor is visible, and the slow re-check while the
+// application hides it.
+function desiredBlinkMode(): BlinkMode {
+  if (!blinkEnabled || hiddenDoc()) {
+    return "off";
   }
-  // The blink class lives on termWrap: the caret overlay is a termWrap child
-  // (not inside output), and the `.cursor-blink-off .term-cursor` descendant
-  // selector must reach it.
-  termWrap.classList.remove("cursor-blink-off");
-  blinkInterval = setInterval(() => {
-    termWrap.classList.toggle("cursor-blink-off");
-  }, CURSOR_BLINK_MS);
+  return cursorHidden ? "idle" : "fast";
 }
 
-function stopCursorBlink(): void {
+// syncCursorBlink reconciles the interval with the current gate state; every
+// mode change resets the phase to solid. Called from the flush (blink mode +
+// DECTCM state), the visibilitychange listener, init(), and the idle re-check
+// itself. The blink class lives on termWrap: the caret overlay is a termWrap
+// child (not inside output), and the `.cursor-blink-off .term-cursor`
+// descendant selector must reach it.
+function syncCursorBlink(): void {
+  const mode = desiredBlinkMode();
+  if (mode === blinkMode) {
+    return;
+  }
+  blinkMode = mode;
   if (blinkInterval !== null) {
     clearInterval(blinkInterval);
     blinkInterval = null;
   }
   termWrap.classList.remove("cursor-blink-off");
+  if (mode === "fast") {
+    blinkInterval = setInterval(() => {
+      termWrap.classList.toggle("cursor-blink-off");
+    }, CURSOR_BLINK_MS);
+  } else if (mode === "idle") {
+    blinkInterval = setInterval(syncCursorBlink, CURSOR_RECHECK_MS);
+  }
 }
 
 // Pause the interval while hidden; resume (cursor solid, phase reset) when the
@@ -995,33 +1106,13 @@ if (typeof document !== "undefined") {
     if ((termWrap as HTMLElement | undefined) === undefined) {
       return;
     }
-    if (hiddenDoc()) {
-      // Stop the timer only: blinkEnabled keeps the server-driven state so
-      // foregrounding can restart without waiting for the next mode frame.
-      if (blinkInterval !== null) {
-        clearInterval(blinkInterval);
-        blinkInterval = null;
-      }
-      termWrap.classList.remove("cursor-blink-off");
-      return;
-    }
-    startCursorBlink();
+    // blinkEnabled/cursorHidden keep their server-driven state across a
+    // background stint, so foregrounding restores the right mode without
+    // waiting for the next frame.
+    syncCursorBlink();
   });
 }
 
-/** Called from the flush when cursorBlink state changes. */
-function setCursorBlink(enabled: boolean): void {
-  if (enabled === blinkEnabled) {
-    return;
-  }
-  blinkEnabled = enabled;
-  if (enabled) {
-    startCursorBlink();
-  } else {
-    stopCursorBlink();
-  }
-}
-
 // --- Font metrics & sizing ---
 /**
  * Re-measure the cell width/height from the rendered DOM. Call after any font

package/src/scroll.ts

@@ -10,8 +10,13 @@
 // failure mode; see the #web-terminal-engine steering doc, "Design rationale").
 //
 // The renderer calls stickToBottom() once after each flush: if following, pin
-// to the new bottom; if holding, do nothing and let native scroll anchoring
-// (overflow-anchor) hold the reading position when history is inserted above.
+// to the new bottom; if holding, do nothing. Holding the reading position when
+// content ABOVE it changes height (top-of-history eviction at the retention cap,
+// the trim marker appearing) is adjustForContentShift's job, called by the
+// renderer around its DOM mutations. That used to be left to native scroll
+// anchoring (overflow-anchor), which WebKit has never shipped — so on Safari and
+// iPadOS the read position slid up one line per evicted row while the user was
+// scrolled up reading.
 // Appending content at the bottom does not fire a scroll event, so following
 // stays true across new output and the post-flush pin lands correctly. Pinning
 // to the bottom produces a scroll event whose recomputation yields
@@ -148,6 +153,34 @@ export function currentScrollTop(): number {
   return scrollEl ? scrollEl.scrollTop : 0;
 }
 
+/**
+ * Shift the viewport by a content-height change that happened ABOVE the reading
+ * position, so the user keeps looking at the same line. A no-op while following
+ * (the bottom pin owns the position then) and when the delta is zero.
+ *
+ * This is scroll anchoring, done by hand. Chrome and Firefox do it natively
+ * (`overflow-anchor`), and this module's design leaned on that: "if holding, do
+ * nothing and let native scroll anchoring hold the reading position when history
+ * is inserted above". WebKit has never shipped scroll anchoring, so on Safari
+ * — including iPadOS, where this UI mostly lives — nothing compensated, and
+ * every row evicted from the top of history while the user was scrolled up
+ * reading slid their reading position one line further up. Over a streaming
+ * agent session at the retention cap that reads as "the view scrolls itself
+ * while I am trying to read".
+ *
+ * `following` is deliberately NOT touched, and neither is `lastScrollTop`: the
+ * state stays derived purely from the resulting scroll event, exactly as it is
+ * for the bottom pin. Both directions recompute to holding (an upward shift
+ * leaves a gap below; a downward one is not at the bottom), so there is no churn
+ * and no follow flip.
+ */
+export function adjustForContentShift(deltaPx: number): void {
+  if (!scrollEl || following || deltaPx === 0) {
+    return;
+  }
+  scrollEl.scrollTop += deltaPx;
+}
+
 /**
  * Restore a previously saved scroll offset (per-view scroll memory: a tabbed
  * shell re-entering a tab whose user had scrolled up to read). The offset is

package/src/status-stream.ts

@@ -9,16 +9,28 @@ import { nextBackoffDelay } from "./reconnect.js";
 
 /** SessionInfo is one session's wire shape: the JSON object the session REST
  *  API (GET/POST /api/sessions) returns per session. Mirrors the Go
- *  terminal.SessionInfo — the two are kept in lockstep by hand (single 6-field
- *  type; flip to wiregen if this surface grows). */
+ *  terminal.SessionInfo — the two are kept in lockstep by hand (single 7-field
+ *  type; flip to wiregen if this surface grows).
+ *
+ *  Three of the fields are title-shaped and they are not interchangeable:
+ *  `title` is the RESOLVED display title, `pinnedTitle` is the USER's name (set
+ *  and cleared only by a human action, outranking everything else), and
+ *  `clientTitle` is a CLIENT-DERIVED automatic title a client asked the server to
+ *  remember. */
 export interface SessionInfo {
   readonly id: string;
   readonly status: "working" | "idle" | "input" | "done" | "exited";
   readonly title: string;
-  /** the raw client-set title (before the OSC fallback baked into `title`); a
-   *  consumer that treats the program's OSC window title as unreliable reads
-   *  this instead of `title`. */
+  /** the raw client-derived automatic title (before the precedence baked into
+   *  `title`); a consumer that treats the program's OSC window title as
+   *  unreliable reads this instead of `title`. */
   readonly clientTitle?: string;
+  /** the user's pinned name, set through PUT /api/sessions/{id}/pinned-title and
+   *  cleared through DELETE on the same path. It outranks every automatic source
+   *  in `title`; it is carried raw so a UI can tell that a pin EXISTS (to offer
+   *  the automatic name again) rather than only seeing its effect. Absent or
+   *  empty means the session has no user-set name. */
+  readonly pinnedTitle?: string;
   readonly createdAt: string;
   /** true once the session has emitted a genuine activity signal — OSC 9;4
    *  progress (kiro-cli, Claude Code, …) or a classified OSC 9 notification.