@cplieger/web-terminal-engine 3.0.7 → 3.2.0

package/jsr.json

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

package/package.json

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

@@ -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();
 }

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.