hop2 0.11.21 → 0.11.22

package/hay/apps/server/src/rooms.ts

@@ -73,15 +73,17 @@ export type RoomSummary = {
   localCliCount: number;
 };
 
-// Raw output retained for reattach snapshots. ~20MB of raw stream reconstructs
-// roughly a full client scrollback (tens of thousands of lines) of plain
-// output; TUI streams are escape-dense and reconstruct less. This is the whole
-// buffer replayed (and parsed by the client) on reattach, so very large values
-// trade memory + reattach-parse time for deeper restored history. Override with
-// HAY_SNAPSHOT_BUFFER_BYTES (bytes of raw stream kept per room).
+// Raw output retained for reattach snapshots. Sized for GC, not just
+// features: rings live on the V8 heap as strings, and at 20MB x 24 rooms the
+// host carried a ~350MB live heap whose major GCs stop the world 3-4s —
+// measured on the fleet (2026-08-17: 340 event-loop stalls in a day, every
+// one freezing typing everywhere; MarkCompact dominated the CPU sample).
+// 6MB still exceeds every reader: the deep-history replay asks 1.5MB, the
+// serialized attach reads the grid, and `hop restore` persists 64KB tails.
+// Override with HAY_SNAPSHOT_BUFFER_BYTES for deeper rings at GC's expense.
 const MAX_BUFFER_SIZE = (() => {
   const env = Number(process.env.HAY_SNAPSHOT_BUFFER_BYTES);
-  return Number.isFinite(env) && env > 0 ? env : 20_000_000;
+  return Number.isFinite(env) && env > 0 ? env : 6_000_000;
 })();
 // Keep rooms alive indefinitely; only explicit kill/remove should end a session.
 const CLEANUP_DELAY_MS = 0;

package/hay/apps/web/src/App.tsx

@@ -366,6 +366,9 @@ const App = () => {
     return null;
   });
   const [sessionLabel, setSessionLabel] = useState(() => initialRoom);
+  // The room's invariant id, as the server reported it in `hello` — the
+  // session.room string is just the display name the page was opened with.
+  const [canonicalRoomId, setCanonicalRoomId] = useState<string | null>(null);
   const [liveCwd, setLiveCwd] = useState<string | null>(null);
   const [status, setStatus] = useState<ConnectionStatus>("idle");
   // What the CHROME shows. Most drops (a tunnel restart, a laptop waking, an
@@ -495,11 +498,19 @@ const App = () => {
     return DEFAULT_SESSION_SWITCH_MODE;
   });
 
+  // The label is DERIVED, never copied: the room key is the session's
+  // invariant id, which equals the display name only until the first rename.
+  // This effect used to write the room key straight into the label, so the
+  // footer (and tab title, share link, bell notification) showed the
+  // pre-rename name forever on any renamed session. The list refresh is the
+  // source of truth; session_renamed messages update it instantly in between.
   useEffect(() => {
-    if (session?.room) {
-      setSessionLabel(session.room);
-    }
-  }, [session?.room]);
+    if (!session?.room) return;
+    const entry = sessions.find((s) =>
+      (s.internalName || s.name) === (canonicalRoomId || session.room)
+      || (s.internalName || s.name) === session.room);
+    setSessionLabel(entry ? (entry.displayName || entry.name) : session.room);
+  }, [session?.room, sessions, canonicalRoomId]);
   const [fontSize, setFontSize] = useState(() => {
     const saved = localStorage.getItem("hay_font_size");
     return saved ? parseInt(saved, 10) : 14;
@@ -1001,6 +1012,41 @@ const App = () => {
     catch { return []; }
   })());
 
+  // ── Stale-bundle self-healing ─────────────────────────────────────────
+  // Deploys replace the hashed bundle, but an open tab reconnects forever on
+  // the code it loaded — every fix shipped "didn't work" until each tab was
+  // manually reloaded (the scroll dead-zone report was a tab three bundles
+  // behind). Poll our own index.html for the bundle it now names; when it
+  // differs from the one running, reload — but only while the tab is HIDDEN
+  // and the terminal has no buffered input, so nobody ever sees it happen.
+  const staleBundleRef = useRef(false);
+  useEffect(() => {
+    let disposed = false;
+    const loadedBundle = (() => {
+      try { return new URL(import.meta.url).pathname.split("/").pop() || null; }
+      catch { return null; }
+    })();
+    if (!loadedBundle) return;
+    const check = async () => {
+      try {
+        const res = await fetch("/", { cache: "no-store" });
+        const html = await res.text();
+        const current = (html.match(/assets\/(index-[^"']+\.js)/) || [])[1];
+        if (!disposed && current && current !== loadedBundle) staleBundleRef.current = true;
+      } catch { /* offline — try again next tick */ }
+    };
+    const maybeReload = () => {
+      if (staleBundleRef.current && document.hidden) window.location.reload();
+    };
+    const interval = window.setInterval(() => { void check().then(maybeReload); }, 5 * 60 * 1000);
+    document.addEventListener("visibilitychange", maybeReload);
+    return () => {
+      disposed = true;
+      window.clearInterval(interval);
+      document.removeEventListener("visibilitychange", maybeReload);
+    };
+  }, []);
+
   useEffect(() => {
     activeSessionRoomRef.current = session?.room ?? null;
     const room = session?.room;
@@ -1510,6 +1556,8 @@ const App = () => {
 
   const connect = (nextSession: { name: string; room: string }) => {
     const targetRoom = nextSession.room;
+    // A new target invalidates the previous room's id; hello re-supplies it.
+    setCanonicalRoomId(null);
     // Clear any pending reconnect
     if (reconnectTimerRef.current) {
       window.clearTimeout(reconnectTimerRef.current);
@@ -1652,6 +1700,11 @@ const App = () => {
           setClientId(message.clientId);
           setCollabMode(message.collabMode);
           setControllerId(message.controllerId);
+          // The server names the room by its INVARIANT id here. The page
+          // itself only knows the display name it was opened under, which
+          // goes stale on the first rename — this is the durable key the
+          // label derivation matches the session list against.
+          if (message.roomId) setCanonicalRoomId(message.roomId);
           break;
         case "presence":
           // Presence broadcasts arrive on every peer keystroke (typing

package/hay/apps/web/src/components/SessionSwitcher.tsx

@@ -2361,7 +2361,7 @@ export const SessionSwitcher = ({
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ name: next, type: "terminal", port: null })
       });
-      const data = await res.json().catch(() => ({} as { name?: string; error?: string }));
+      const data = await res.json().catch(() => ({} as { name?: string; displayName?: string; internalName?: string; error?: string }));
       if (!res.ok || !data.name) {
         // A name collision is the common failure, and "already in use" alone
         // leaves the user hunting: the holder may be filed in another folder,
@@ -2425,7 +2425,7 @@ export const SessionSwitcher = ({
         await fetch("/api/sessions/move", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ internalName: data.name, folderId: createInFolder.id })
+          body: JSON.stringify({ internalName: data.internalName || data.name, folderId: createInFolder.id })
         }).catch(() => { /* filing is best-effort; the session exists */ });
         setCreateInFolder(null);
       }
@@ -2433,8 +2433,10 @@ export const SessionSwitcher = ({
       // the exact accidental mode-entry the hotkey inversion removed from
       // clicks. The new tile becomes current and goes live in place as soon
       // as the session reports active.
-      onFocusSession?.({ name: data.name, displayName: data.name, active: false, starting: true, internalName: data.name });
-      setFocusedKey(data.name);
+      // The id is minted server-side now; the display name is what the user
+      // typed. Keys ride on the id, labels on the name.
+      onFocusSession?.({ name: data.displayName || data.name, displayName: data.displayName || data.name, active: false, starting: true, internalName: data.internalName || data.name });
+      setFocusedKey(data.internalName || data.name);
       onRefresh();
     } catch {
       onNotice("Failed to create session");

package/hay/apps/web/src/utils/scrollFlywheel.ts

@@ -9,10 +9,19 @@
 // trackpad feel.
 //
 // Safety rules (why this is a util and not three lines):
-// - Normal buffer only. On the alternate screen xterm translates wheel to
-//   arrow keys / mouse reports for the app — inertia there would spray
-//   keystrokes into vim/claude/less after the user stopped scrolling.
-// - Discrete wheels only (see isDiscreteWheel) — trackpads keep native feel.
+// - Normal buffer only for LOCAL momentum. On the alternate screen xterm
+//   translates wheel to arrow keys / mouse reports for the app — local
+//   inertia there would spray keystrokes into vim/claude/less after the
+//   user stopped scrolling.
+// - In LOCAL scrollback, discrete wheels only (see isDiscreteWheel) —
+//   trackpads keep the OS's native glide; doubling it felt drunk.
+// - In APP-OWNED scrolling the rule inverts for trackpads: the OS momentum
+//   stream is hundreds of events, each of which xterm turns into a wire
+//   mouse-report costing a network round trip. Forwarded 1:1 it floods a
+//   remote app into scroll LAG (the transcript keeps moving long after the
+//   fingers stop). So there we take ownership: coalesce the stream into
+//   line-sized steps and pace them by the app's own acknowledgements —
+//   instant when local, matched to the link when remote.
 // - A single notch never glides: momentum engages only for a sustained spin
 //   (3+ events in a burst), so precise one-line nudges stay precise.
 // - Any keypress or click kills the glide instantly, and so does hitting
@@ -107,7 +116,17 @@ export const attachScrollFlywheel = (
   // wire format — whatever it sends for a real notch is exactly what it sends
   // for ours.
   const APP_STEPS_PER_NOTCH = 3;
-  const APP_MAX_RATE = 90; // steps/sec — fast, still ordered
+  const APP_MAX_RATE = 70; // steps/sec — fast, still ordered
+  // Remote scrolling physics: every step is a round trip (report up, full
+  // repaint down) and the app repaints ONCE per input batch it drains. So:
+  // batch lines per dispatch in proportion to speed (one repaint moves
+  // several lines instead of one), and keep a small window of unacked
+  // bursts in flight to hide the RTT — serialized one-line-per-RTT was the
+  // jerk. Slow speeds still step one line per burst: precision unharmed.
+  const APP_ACK_WINDOW = 2;   // bursts in flight before we hold
+  const APP_MAX_BURST = 5;    // lines per burst at full speed
+  const burstFor = (vel: number) =>
+    Math.max(1, Math.min(APP_MAX_BURST, Math.round(Math.abs(vel) / 20)));
   let appVel = 0;
   let appCarry = 0;
   let appRaf = 0;
@@ -125,6 +144,9 @@ export const attachScrollFlywheel = (
     appVel = 0;
     appCarry = 0;
     appBurst = 0;
+    panPx = 0;
+    panPending = 0;
+    unacked = 0;
   };
 
   const stop = () => { stopLocal(); stopApp(); };
@@ -149,11 +171,24 @@ export const attachScrollFlywheel = (
   };
 
   let lastStepAt = 0;
+  let unacked = 0; // bursts dispatched with no output seen since
   const appGlide = (t: number) => {
     appRaf = 0;
     const term = getTerm();
     // Mode flipped (app exited, screen switched) or run out of speed.
-    if (!term || terminalOwnsScrolling(term) || Math.abs(appVel) < 4) return stopApp();
+    if (!term || terminalOwnsScrolling(term)) return stopApp();
+    if (panPending === 0 && Math.abs(appVel) < coastMin()) {
+      // Out of momentum. Rest the machinery but PRESERVE the sub-line
+      // accumulation in every case: the quantum is one whole line, and a
+      // slow precise drag only crosses it across many events and pauses —
+      // any wipe on this path is a low-speed dead zone (shipped one twice).
+      // panPx dies only on direction flip, a 2s-still gesture break, a
+      // keypress/click kill, or dispose.
+      appRaf = 0;
+      appVel = 0;
+      appCarry = 0;
+      return;
+    }
     const dt = lastFrameAt ? Math.min(0.05, (t - lastFrameAt) / 1000) : 0.016;
     lastFrameAt = t;
     // ACK pacing: after each synthetic step, wait for the app to answer
@@ -161,20 +196,128 @@ export const attachScrollFlywheel = (
     // the link's real rhythm instead of flooding a slow one. 300ms cap so
     // an app that repaints invisibly (no bytes for us) can't stall the
     // glide forever.
+    // Windowed ACK pacing: any output since the last burst clears the
+    // window (the app is keeping up); otherwise up to APP_ACK_WINDOW bursts
+    // may be in flight before we hold. The 300ms cap keeps an app that
+    // repaints invisibly (no bytes for us) from stalling the glide forever.
     const ackAt = opts.lastOutputAt ? opts.lastOutputAt() : Infinity;
-    const waitingForAck = lastStepAt > 0 && ackAt < lastStepAt && performance.now() - lastStepAt < 300;
+    if (ackAt > lastStepAt) unacked = 0;
+    const waitingForAck = lastStepAt > 0 && unacked >= APP_ACK_WINDOW
+      && performance.now() - lastStepAt < 300;
     if (!waitingForAck) {
-      appCarry += Math.abs(appVel) * dt;
-      let steps = Math.trunc(appCarry);
-      appCarry -= steps;
-      if (steps > 0) lastStepAt = performance.now();
-      while (steps-- > 0) dispatchStep();
-      appVel *= Math.exp(-dt / 0.35);
+      if (panPending !== 0) {
+        // Finger-driven lines first: drain the coalesced pan queue in
+        // speed-proportional bursts — the app repaints once per burst, so
+        // a burst of 4 costs one round trip where 4 singles cost four.
+        const spend = Math.sign(panPending)
+          * Math.min(Math.abs(panPending), burstFor(appVel || panPending));
+        panPending -= spend;
+        if (spend !== 0) {
+          lastStepAt = performance.now();
+          unacked += 1;
+          if (appProto) appProto.deltaY = Math.sign(spend) * 120;
+          for (let i = 0; i < Math.abs(spend); i++) dispatchStep();
+        }
+      } else {
+        appCarry += Math.min(APP_MAX_RATE, Math.abs(appVel)) * dt;
+        const steps = Math.min(Math.trunc(appCarry), burstFor(appVel));
+        if (steps > 0) {
+          appCarry -= steps;
+          lastStepAt = performance.now();
+          unacked += 1;
+          if (appProto) appProto.deltaY = Math.sign(appVel) * 120;
+          for (let i = 0; i < steps; i++) dispatchStep();
+        }
+        appVel *= Math.exp(-dt / 0.24);
+      }
     }
     appRaf = requestAnimationFrame(appGlide);
   };
 
+  // ---- App-owned TRACKPAD panning -----------------------------------------
+  // The finger stream is coalesced into whole-line steps and drained by the
+  // same ACK-paced loop the wheel coast uses. panPx carries the sub-line
+  // remainder, so slow precise drags still land exactly one step as they
+  // cross each line boundary.
+  let panPx = 0;
+  let panPending = 0; // signed whole steps waiting to be dispatched
+  let panLastAt = 0;
+  let panMode = false; // last input was a finger stream, not a wheel
+  // Trackpads NEVER self-coast: macOS keeps emitting decaying momentum
+  // events after the fingers lift — that stream IS the coast, and it feeds
+  // the pan queue. Adding our own decay on top gave every flick two glides
+  // stacked, which read as overshoot. Only discrete wheels (no OS momentum)
+  // earn a synthetic coast, from 4 steps/s past their burst gate.
+  const coastMin = () => (panMode ? Infinity : 4);
+
+  const trackpadPan = (e: WheelEvent) => {
+    panMode = true;
+    appTarget = e.target;
+    // One line's worth of delta per synthetic event, in the pan's direction —
+    // xterm emits one wire report per event regardless of magnitude.
+    appProto = { deltaY: Math.sign(e.deltaY) * 120, clientX: e.clientX, clientY: e.clientY };
+
+    const now = e.timeStamp || performance.now();
+    const gap = now - panLastAt;
+    panLastAt = now;
+    const stepPx = Math.max(1, opts.lineHeightPx());
+    const px = e.deltaMode === 1 ? e.deltaY * stepPx : e.deltaY;
+    // Direction flip: dump everything queued the other way, instantly.
+    if (Math.sign(px) !== Math.sign(panPx + panPending) && (panPx !== 0 || panPending !== 0)) {
+      panPx = 0;
+      panPending = 0;
+      appVel = 0;
+    }
+    // The remainder SURVIVES slow pacing: a precise drag emits small
+    // deltas with long gaps, and wiping between them made low-speed
+    // scrolling move nothing at all (the quantum is one line; 3px events
+    // could never reach it). Only a genuinely new gesture — seconds of
+    // stillness — starts from zero.
+    if (gap > 2000) { panPx = 0; }
+    panPx += px;
+    const steps = Math.trunc(panPx / stepPx);
+    if (steps !== 0) {
+      panPx -= steps * stepPx;
+      panPending += steps;
+    }
+    // Velocity for the post-stream coast, in steps/sec, from the px rate.
+    const rate = (px / stepPx) / (Math.min(Math.max(gap, 8), 200) / 1000);
+    appVel = Math.sign(rate) === Math.sign(appVel) ? 0.5 * rate + 0.5 * appVel : rate;
+    appVel = Math.max(-APP_MAX_RATE, Math.min(APP_MAX_RATE, appVel));
+
+    // Leading edge dispatches INLINE: a precise first movement must not
+    // wait out an animation frame — latency is what precision feels like.
+    // The rAF loop takes over for everything after, where pacing matters.
+    if (panPending !== 0 && unacked < APP_ACK_WINDOW) {
+      const spend = Math.sign(panPending)
+        * Math.min(Math.abs(panPending), burstFor(appVel || panPending));
+      panPending -= spend;
+      lastStepAt = performance.now();
+      unacked += 1;
+      if (appProto) appProto.deltaY = Math.sign(spend) * 120;
+      for (let i = 0; i < Math.abs(spend); i++) dispatchStep();
+    }
+    if (!appRaf) {
+      lastFrameAt = 0;
+      appRaf = requestAnimationFrame(appGlide);
+    }
+    if (appIdle) window.clearTimeout(appIdle);
+    appIdle = window.setTimeout(() => {
+      appIdle = 0;
+      // The OS stream paused. Rest the velocity, but PRESERVE the sub-line
+      // remainder — this fires 120ms after every event of a slow drag, and
+      // sweeping panPx here was half of the low-speed dead zone. The next
+      // event continues the accumulation; the 2s gate above decides when a
+      // pause is actually a new gesture.
+      if (!appRaf && panPending === 0 && Math.abs(appVel) < coastMin()) {
+        appVel = 0;
+        appCarry = 0;
+      }
+    }, 120);
+  };
+
   const appWheel = (e: WheelEvent) => {
+    panMode = false;
     appTarget = e.target;
     appProto = { deltaY: e.deltaY, clientX: e.clientX, clientY: e.clientY };
     if (appRaf) { cancelAnimationFrame(appRaf); appRaf = 0; }
@@ -220,7 +363,7 @@ export const attachScrollFlywheel = (
       term.scrollLines(lines);
       if (term.buffer.active.viewportY === before) return stop(); // hit an edge
     }
-    vel *= Math.exp(-dt / 0.35); // ~350ms decay time-constant
+    vel *= Math.exp(-dt / 0.24); // ~240ms decay: brisk, not a runaway
     raf = requestAnimationFrame(glide);
   };
 
@@ -236,8 +379,20 @@ export const attachScrollFlywheel = (
     // still does all the scrolling; we only shape the event rate.
     if (!terminalOwnsScrolling(term)) {
       stopLocal();
-      if (isDiscreteWheel(e)) appWheel(e);
-      else stopApp(); // trackpad: the OS already sends a dense glide
+      // Pinch-zoom and sideways pans are not scrolling — leave them alone.
+      if (e.ctrlKey || Math.abs(e.deltaX) > Math.abs(e.deltaY)) return;
+      if (isDiscreteWheel(e)) {
+        appWheel(e);
+      } else {
+        // Trackpad: take the stream over entirely. Without this, xterm
+        // forwards every one of the OS's momentum events as its own wire
+        // report and a remote app drowns (scroll lag, overshoot). We
+        // preventDefault + stopPropagation the raw events and re-emit
+        // line-sized, ACK-paced synthetic ones instead.
+        e.preventDefault();
+        e.stopPropagation();
+        trackpadPan(e);
+      }
       return;
     }
     stopApp();
@@ -255,7 +410,7 @@ export const attachScrollFlywheel = (
     const rate = notchLines / (Math.min(Math.max(gap, 30), 200) / 1000);
     // Same direction: blend toward the new rate. Direction flip: hard reset.
     vel = Math.sign(rate) === Math.sign(vel) ? 0.6 * rate + 0.4 * vel : rate;
-    const CAP = 2500; // lines/s — fast, but never a teleport
+    const CAP = 1400; // lines/s — fast, but never a teleport
     vel = Math.max(-CAP, Math.min(CAP, vel));
 
     if (idleTimer) window.clearTimeout(idleTimer);
@@ -272,13 +427,15 @@ export const attachScrollFlywheel = (
   };
 
   const kill = () => stop();
-  // CAPTURE phase, but strictly observational (passive: we never
-  // preventDefault). Capture is REQUIRED: when the app is tracking the
+  // CAPTURE phase. Capture is REQUIRED: when the app is tracking the
   // mouse, xterm's own handler calls stopPropagation() on the way out, so a
   // bubble-phase listener on this ancestor never runs at all — which is why
   // the app-scroll shaping below silently did nothing. Observing first lets
   // xterm do exactly what it always did, and lets us add steps around it.
-  el.addEventListener("wheel", onWheel, { capture: true, passive: true });
+  // capture (see below) and NON-passive: the app-owned trackpad branch
+  // preventDefaults the raw stream it replaces. Every other path still never
+  // cancels anything.
+  el.addEventListener("wheel", onWheel, { capture: true, passive: false });
   el.addEventListener("mousedown", kill, true);
   window.addEventListener("keydown", kill, true);
   return () => {

package/hay/apps/web/test/scrollFlywheel.test.ts

@@ -111,3 +111,215 @@ describe("attachScrollFlywheel", () => {
     dispose();
   });
 });
+
+describe("app-owned trackpad panning", () => {
+  // A term in the state every Claude session runs: alt screen + tracking.
+  const mkAppTerm = () => ({
+    scrolled: [] as number[],
+    scrollLines() { /* app-owned: local scroll must never happen */ },
+    buffer: { active: { type: "alternate", viewportY: 0 } },
+    modes: { mouseTrackingMode: "drag" }
+  });
+
+  let el: HTMLElement;
+  let rafCbs: FrameRequestCallback[];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    el = document.createElement("div");
+    document.body.appendChild(el);
+    rafCbs = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => (rafCbs.push(cb), rafCbs.length));
+    vi.stubGlobal("cancelAnimationFrame", () => { rafCbs = []; });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+    el.remove();
+  });
+
+  const pan = (deltaY: number, timeStamp: number, extra: Partial<WheelEvent> = {}) => {
+    const e = new Event("wheel", { cancelable: true }) as WheelEvent;
+    Object.defineProperties(e, {
+      deltaY: { value: deltaY },
+      deltaX: { value: (extra as { deltaX?: number }).deltaX ?? 0 },
+      ctrlKey: { value: (extra as { ctrlKey?: boolean }).ctrlKey ?? false },
+      deltaMode: { value: 0 }, // pixel mode, small deltas: a trackpad
+      timeStamp: { value: timeStamp },
+      clientX: { value: 10 },
+      clientY: { value: 10 }
+    });
+    el.dispatchEvent(e);
+    return e;
+  };
+
+  const drainFrames = (frames: number, stepMs = 16) => {
+    let t = performance.now();
+    for (let i = 0; i < frames && rafCbs.length; i++) {
+      const cbs = rafCbs;
+      rafCbs = [];
+      t += stepMs;
+      for (const cb of cbs) cb(t);
+    }
+  };
+
+  it("takes ownership of the raw stream and re-emits paced line steps", () => {
+    const term = mkAppTerm();
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20
+    });
+
+    // Synthetic (our own) wheel events reach the app; count them.
+    let forwarded = 0;
+    el.addEventListener("wheel", (e) => { if (!e.defaultPrevented) forwarded++; });
+
+    // A fast flick: 30 raw events of 15px each (0.75 lines apiece).
+    let cancelled = 0;
+    for (let i = 0; i < 30; i++) {
+      const e = pan(15, i * 8);
+      if (e.defaultPrevented) cancelled++;
+    }
+    expect(cancelled).toBe(30); // every RAW event was consumed, none leaked
+    // Count arrivals per drained frame to verify pacing.
+    let inFrame = 0;
+    let maxPerFrame = 0;
+    el.addEventListener("wheel", (e) => { if (!e.defaultPrevented) inFrame++; });
+    for (let f = 0; f < 40 && rafCbs.length; f++) {
+      inFrame = 0;
+      drainFrames(1);
+      maxPerFrame = Math.max(maxPerFrame, inFrame);
+    }
+
+    // 450px of finger = 22 whole lines, plus a momentum coast on top (the
+    // point of the feature). What must hold: lines flow as bounded BURSTS —
+    // at most one speed-proportional burst per frame (each costing the app
+    // one repaint), never the raw flood re-emitted wholesale.
+    expect(forwarded).toBeGreaterThan(10);
+    const maxBurst = 5; // APP_MAX_BURST
+    expect(maxPerFrame).toBeLessThanOrEqual(maxBurst);
+    expect(term.scrolled.length).toBe(0); // and nothing scrolled locally
+    dispose();
+  });
+
+  it("a slow precise drag lands exactly one step per line crossed", () => {
+    const term = mkAppTerm();
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20
+    });
+    let forwarded = 0;
+    el.addEventListener("wheel", (e) => { if (!e.defaultPrevented) forwarded++; });
+
+    // 5px at a time: three events accumulate 15px — under one line, nothing
+    // moves; the fourth crosses 20px and yields exactly one step.
+    pan(5, 0); pan(5, 30); pan(5, 60);
+    drainFrames(4);
+    expect(forwarded).toBe(0);
+    pan(5, 90);
+    drainFrames(4);
+    expect(forwarded).toBe(1);
+    dispose();
+  });
+
+  it("holds after two unacked bursts when the remote goes silent", () => {
+    // The pipelining contract: bursts fly while output flows; a remote that
+    // stops answering gets at most APP_ACK_WINDOW bursts in flight, then we
+    // hold (until the 300ms stall cap) instead of flooding its input queue.
+    const term = mkAppTerm();
+    let lastOutput = 0; // frozen: the remote never answers
+    // A clock that actually advances: the hold logic compares real
+    // timestamps, and vitest's frozen performance.now() (0) disarms it.
+    let clock = 1000;
+    const nowSpy = vi.spyOn(performance, "now").mockImplementation(() => clock);
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20,
+      lastOutputAt: () => lastOutput
+    });
+    let bursts = 0;
+    let prevCount = 0;
+    let count = 0;
+    el.addEventListener("wheel", (e) => { if (!e.defaultPrevented) count++; });
+
+    for (let i = 0; i < 30; i++) { clock += 8; pan(15, clock); }
+    const inFlight = count; // leading-edge bursts, dispatched inline
+    expect(inFlight).toBeGreaterThan(0);
+    expect(inFlight).toBeLessThanOrEqual(10); // ≤ APP_ACK_WINDOW bursts of ≤5
+
+    for (let f = 0; f < 15 && rafCbs.length; f++) {
+      prevCount = count;
+      clock += 16;
+      drainFrames(1);
+      if (count > prevCount) bursts++;
+    }
+    // Held: the silent remote gets at most the one stall-cap release, never
+    // the queued flood (22 lines are still waiting).
+    expect(bursts).toBeLessThanOrEqual(1);
+
+    // The remote answers: the window clears and bursts resume.
+    lastOutput = clock + 1;
+    prevCount = count;
+    clock += 16;
+    drainFrames(3);
+    expect(count).toBeGreaterThan(prevCount);
+    nowSpy.mockRestore();
+    dispose();
+  });
+
+  it("leaves pinch-zoom and horizontal pans alone", () => {
+    const term = mkAppTerm();
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20
+    });
+    const zoom = pan(15, 0, { ctrlKey: true } as Partial<WheelEvent>);
+    const sideways = pan(3, 20, { deltaX: 40 } as Partial<WheelEvent>);
+    expect(zoom.defaultPrevented).toBe(false);
+    expect(sideways.defaultPrevented).toBe(false);
+    dispose();
+  });
+
+  it("local-scrollback trackpads keep the native feel — untouched", () => {
+    let viewportY = 5000;
+    const term = {
+      scrolled: [] as number[],
+      scrollLines(n: number) { this.scrolled.push(n); viewportY += n; },
+      buffer: { active: { type: "normal", get viewportY() { return viewportY; } } }
+    };
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20
+    });
+    const e = pan(15, 0);
+    expect(e.defaultPrevented).toBe(false); // xterm's own handling stands
+    expect(term.scrolled.length).toBe(0);   // and we add no glide of our own
+    dispose();
+  });
+
+
+  it("low-speed scrolling accumulates linearly — no dead zone", () => {
+    // The regression: slow drags emit small deltas with LONG gaps, and the
+    // accumulator was wiped both by a 250ms gap reset and by the gesture-
+    // idle sweep — so low-speed scrolling moved nothing, ever. Friction
+    // model: linear accumulation at any speed, one step per line crossed.
+    const term = mkAppTerm();
+    const dispose = attachScrollFlywheel(el, () => term as never, {
+      linesPerNotch: 4,
+      lineHeightPx: () => 20
+    });
+    let forwarded = 0;
+    el.addEventListener("wheel", (e) => { if (!e.defaultPrevented) forwarded++; });
+
+    // 5px every 300ms — a deliberate, slow, precise drag. The idle timer
+    // fires between every pair of events.
+    for (let i = 0; i < 4; i++) {
+      pan(5, i * 300);
+      vi.advanceTimersByTime(300); // lets the 120ms idle sweep run
+      drainFrames(2);
+    }
+    // 4 × 5px = 20px = exactly one line: exactly one step, not zero.
+    expect(forwarded).toBe(1);
+    dispose();
+  });
+});