@cplieger/web-terminal-engine 3.10.2 → 4.0.1

package/README.md

@@ -106,7 +106,7 @@ curl -fsSL https://jsr.io/@cplieger/web-terminal-engine/<version>/wire-compatibi
 ```json
 {
   "schemaVersion": 1,
-  "generatedBy": "web/src/wire-manifest.ts",
+  "generatedBy": "web/src/test-helpers/wire-manifest.ts",
   "wireCompatibility": {
     "protocolVersion": 4,
     "minimumServerProtocolVersion": 3,

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.10.2",
+  "version": "4.0.1",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"
@@ -14,7 +14,8 @@
     ],
     "exclude": [
       "src/**/*.test.ts",
-      "src/**/__test-helpers__/**"
+      "src/**/*-setup.ts",
+      "src/**/test-helpers/**"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.10.2",
+  "version": "4.0.1",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -67,8 +67,8 @@
   "files": [
     "src/",
     "!src/**/*.test.ts",
-    "!src/**/test-helpers",
-    "!src/**/fc-strict-setup.ts",
+    "!src/**/*-setup.ts",
+    "!src/**/test-helpers/**",
     "jsr.json",
     "LICENSE",
     "wire-compatibility.json"

package/src/render.ts

@@ -494,6 +494,11 @@ function queueRowsViewportFirst(): void {
  * history; the existing per-frame budget spreads a large backlog across frames
  * so the switch never janks. Used by bind(); also safe to call directly to
  * force a full repaint of the current store.
+ *
+ * The wipe covers content space in full: the rows AND the four overlays anchored
+ * into it (see collapseContentSpaceOverlays). Leaving the overlays behind left
+ * the container a measured 81081px of scroll range over zero rows of content,
+ * which is a black pane the bottom pin refuses to correct.
  */
 export function rebuild(): void {
   // The wipe is the largest content shrink this module performs, and it happens
@@ -515,6 +520,9 @@ export function rebuild(): void {
   // Fresh surface: a stale give-up streak from a prior store must not deny the
   // rebuilt surface its full transient-retry budget.
   renderNoProgressStreak = 0;
+  // The rows are not the only thing in content space. Collapse the overlays
+  // with them, BEFORE the offset below is read.
+  collapseContentSpaceOverlays();
   // Alt screen paints from the ephemeral grid in the flush, so it needs no
   // absolute-index queueing here.
   if (!store.isAlt()) {
@@ -524,6 +532,60 @@ export function rebuild(): void {
   scheduleFlush();
 }
 
+/**
+ * Drop every CONTENT-SPACE overlay's hold on the scroll container, as part of a
+ * wipe. Four elements sit INSIDE the container carrying a `top` in content
+ * coordinates — the caret, the predicted cursor, the IME view and the consumer's
+ * hidden textarea — so each one holds the container's scrollable overflow at the
+ * offset it was last placed at. `output.replaceChildren()` removes the rows and
+ * leaves all four.
+ *
+ * Measured on a 4769-row tab in Chromium: after the wipe the scroller had ZERO
+ * rows of content and an 81081px scroll range, held by the caret and the
+ * textarea still sitting at 81064px, with the viewport parked at 80281px over
+ * nothing. Two consequences, and the second is why this is not cosmetic:
+ *
+ *   - The reader sees that empty region, which paints the terminal's background:
+ *     a black pane, and then a partial row clipped to the top edge once the
+ *     drain's growing block reaches the parked offset.
+ *   - `stickToBottom` is DISARMED. It measures `distanceFromBottom()` against
+ *     the phantom height, reads 0 — already at the bottom — and pins nothing, so
+ *     the invariant that would otherwise rescue the view refuses to act for
+ *     exactly as long as the phantom height survives.
+ *
+ * The renderer heals all four at the END of the first flush
+ * (`positionCursorOverlay` plus `onCursorMove`), so the window is normally one
+ * frame and invisible. It stops being one frame whenever that tail does not
+ * run on time: a long frame (the wipe tears down thousands of rows), a throw
+ * mid-drain (the catch skips the tail and the bounded give-up can stop
+ * rescheduling), or a full reset arriving with the switch's reconnect. The
+ * reported symptom is a scroll tick clearing it, which fits: a scroll re-enters
+ * the built block, and the block sits at the TOP of the phantom range.
+ *
+ * Collapsing here also makes the wipe's clamp SYNCHRONOUS, which two callers
+ * need. `noteContentShrink` arms only when it observes the position actually
+ * move, so a deferred clamp left the wipe — the largest shrink this module
+ * performs — with nothing to announce. And `bind` records
+ * `pendingRestore.lastWrote` from the same offset, so a deferred clamp
+ * (measured: 80281 -> 4346) then read as a 76000px foreign write and threw away
+ * the reading position the switch was restoring.
+ */
+function collapseContentSpaceOverlays(): void {
+  // `cursorAbs` is -1 by now, which is the state positionCursorOverlay already
+  // hides for; go through it rather than restating the class name here.
+  positionCursorOverlay(undefined);
+  // The outgoing session's prediction cannot describe the incoming screen
+  // either. The consumer re-pushes it from the `onCursorMove` below, which is
+  // its call to make and cannot re-inflate anything: `rowEls` is empty, so
+  // setPredictedCursor's own fallback places it at the content origin.
+  predCursorEl?.classList.remove("visible");
+  // The IME view and the hidden textarea are the CONSUMER's, reachable only
+  // through the cursor seam — and after a wipe the cursor genuinely has no row,
+  // so the seam is accurate rather than borrowed. `getCursorPx` reports the
+  // content origin while `rowEls` is empty, so the handler moves them there.
+  onCursorMove?.();
+}
+
 /**
  * Highest absolute line index the client holds, or -1 if empty. This is the
  * resume `haveThrough` value (it replaces the old DOM-row count). Exposed so

package/src/scroll.ts

@@ -265,14 +265,16 @@ function writePreservingFollow(next: number): void {
  * absolutely-positioned overlay) — and a lingering arm swallows the next real
  * gesture.
  *
- * That last case is live in this codebase rather than illustrative: the caret
- * overlay, the predicted cursor, the IME composition view and the consumer's
- * hidden textarea all sit inside the scroll container carrying a `top` in CONTENT
- * coordinates. Nothing resets them on a wipe: the renderer's `init` drops the two
- * it owns (the caret and the predicted cursor), a full consumer remount recreates
- * the other two, and `rebuild` does neither. So a wipe can leave scrollHeight held
- * above the built content by a stale overlay, the clamp never happens, and there
- * is nothing for this arm to cover. See `docs/tab-switch-repaint.md` §6.2.
+ * That last case used to be live here rather than illustrative, and it is why
+ * the caller's ORDER matters: the caret, the predicted cursor, the IME view and
+ * the consumer's hidden textarea all sit inside the scroll container carrying a
+ * `top` in CONTENT coordinates, so any one of them left at the old offset holds
+ * scrollHeight above the built content and the clamp never happens. `rebuild`
+ * now collapses all four as part of its wipe, before it calls this
+ * (`render.ts` collapseContentSpaceOverlays), so the clamp it announces is real.
+ * A caller that removes content without collapsing whatever else is anchored in
+ * that space arms nothing and gets no announcement. See
+ * `docs/tab-switch-repaint.md` §6.2.
  *
  * A native-scroll-anchoring adjustment (Chrome/Firefox lowering scrollTop as
  * rows are removed above the viewport) also moves the position and also arms

package/wire-compatibility.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedBy": "web/src/wire-manifest.ts",
+  "generatedBy": "web/src/test-helpers/wire-manifest.ts",
   "wireCompatibility": {
     "protocolVersion": 4,
     "minimumServerProtocolVersion": 3,

package/src/wire-manifest.ts

@@ -1,77 +0,0 @@
-// Generator for the published, language-neutral wire-compatibility manifest
-// (`web/wire-compatibility.json`).
-//
-// Why it exists: the wire revision and directional floor are published as
-// TypeScript constants (wire-compatibility.ts) and as Go constants
-// (terminal.WireProtocolVersion / MinSupportedClientWireVersion). A consumer
-// that is neither — a Dockerfile, a shell release gate, a Python CI script —
-// had no machine-readable surface to read them from and resorted to scraping
-// the TypeScript source with `sed`, which breaks silently on any reformat.
-//
-// This module renders that surface FROM the existing WIRE_COMPATIBILITY export,
-// so the numbers keep exactly one source of truth in the TypeScript half. The
-// rendered text is checked into the repo (see the drift guard in
-// wire-manifest.test.ts) because the publish pipeline runs no build step: npm
-// and JSR publish the working tree as-is, so a manifest generated at publish
-// time would never exist in the tarball.
-//
-// The manifest deliberately does NOT carry the package version. `npm pkg set
-// version` injects that at publish time, after checkout, with no regeneration
-// step — an embedded version would be frozen at the repo's placeholder (0.1.0)
-// in every published artifact. Consumers read the package version from
-// package.json / jsr.json, which the pipeline does rewrite.
-//
-// Public-artifact contract: see the "Wire compatibility manifest" section of
-// web/README.md for what a consumer may rely on and what counts as a breaking
-// change.
-
-import { WIRE_COMPATIBILITY, type WireCompatibility } from "./wire-compatibility.js";
-
-/**
- * Schema revision of the manifest FILE, independent of the wire protocol
- * revision it reports. A consumer must reject a `schemaVersion` it does not
- * understand rather than guess at the shape. Bumped only for a breaking
- * change to the manifest's own layout (a removed or repurposed field).
- */
-export const WIRE_MANIFEST_SCHEMA_VERSION = 1;
-
-/** Path of the checked-in artifact this module renders, relative to `web/`. */
-export const WIRE_MANIFEST_PATH = "wire-compatibility.json";
-
-/** Shape of the generated wire-compatibility manifest. */
-export interface WireManifest {
-  /** Schema revision of this file's layout (see WIRE_MANIFEST_SCHEMA_VERSION). */
-  readonly schemaVersion: number;
-  /** Informational provenance note; not part of the parsed contract. */
-  readonly generatedBy: string;
-  /** The same values the TypeScript `WIRE_COMPATIBILITY` export carries. */
-  readonly wireCompatibility: WireCompatibility;
-}
-
-/**
- * Builds the manifest object from the live TypeScript constants. Nesting the
- * protocol values under `wireCompatibility` keeps file-level metadata
- * (`schemaVersion`) in a separate namespace from the payload, so a future
- * metadata field can never collide with a protocol field name.
- */
-export function buildWireManifest(): WireManifest {
-  return {
-    schemaVersion: WIRE_MANIFEST_SCHEMA_VERSION,
-    generatedBy: "web/src/wire-manifest.ts",
-    wireCompatibility: {
-      protocolVersion: WIRE_COMPATIBILITY.protocolVersion,
-      minimumServerProtocolVersion: WIRE_COMPATIBILITY.minimumServerProtocolVersion,
-      incompatibleCloseCode: WIRE_COMPATIBILITY.incompatibleCloseCode,
-    },
-  };
-}
-
-/**
- * Renders the exact bytes of the checked-in manifest: two-space indentation and
- * a trailing newline, which is what `prettier --check` requires of a JSON file
- * in this repo. Comparing rendered text (not parsed objects) is what makes the
- * drift guard able to fail on a hand edit that happens to parse the same.
- */
-export function renderWireManifest(): string {
-  return `${JSON.stringify(buildWireManifest(), null, 2)}\n`;
-}