fix(web): keep terminal wheel scroll in history

Author: skulidropek

packages/app/src/web/terminal-panel-runtime.ts

@@ -21,6 +21,7 @@ import type {
   TerminalSocketConnectArgs,
   TerminalSocketRef
 } from "./terminal-panel-runtime-types.js"
+import { attachTerminalWheelScroll } from "./terminal-wheel-scroll.js"
 import { isPendingActiveTerminalSession } from "./terminal.js"
 
 type TerminalDisposable = { readonly dispose: () => void }
@@ -34,6 +35,7 @@ type TerminalCleanupFactoryArgs = {
   readonly imageLinkDisposable: TerminalDisposable
   readonly imagePasteDisposable: TerminalDisposable
   readonly inputDisposable: TerminalDisposable
+  readonly wheelScrollDisposable: TerminalDisposable
   readonly sendResize: () => void
 }
 
@@ -44,7 +46,8 @@ const createTerminalCleanup = (
     imageLinkDisposable,
     imagePasteDisposable,
     inputDisposable,
-    sendResize
+    sendResize,
+    wheelScrollDisposable
   }: TerminalCleanupFactoryArgs
 ): () => void =>
 (): void => {
@@ -59,6 +62,7 @@ const createTerminalCleanup = (
     removeInput: () => {
       copyInteractionDisposable.dispose()
       inputDisposable.dispose()
+      wheelScrollDisposable.dispose()
     },
     removeResize: () => {
       globalThis.removeEventListener("resize", sendResize)
@@ -103,6 +107,7 @@ type MountedTerminalDisposables = {
   readonly imageLinkDisposable: TerminalDisposable
   readonly imagePasteDisposable: TerminalDisposable
   readonly inputDisposable: TerminalDisposable
+  readonly wheelScrollDisposable: TerminalDisposable
 }
 
 type MountedTerminalCleanupArgs = {
@@ -131,7 +136,8 @@ const createMountedTerminalDisposables = (
     socketRef,
     terminal
   }),
-  inputDisposable: attachTerminalInput(terminal, socketRef, pasteGuard)
+  inputDisposable: attachTerminalInput(terminal, socketRef, pasteGuard),
+  wheelScrollDisposable: attachTerminalWheelScroll({ host, terminal })
 })
 
 const createMountedTerminalConnector = (
@@ -171,7 +177,8 @@ const createMountedTerminalCleanup = (
     imageLinkDisposable: disposables.imageLinkDisposable,
     imagePasteDisposable: disposables.imagePasteDisposable,
     inputDisposable: disposables.inputDisposable,
-    sendResize
+    sendResize,
+    wheelScrollDisposable: disposables.wheelScrollDisposable
   })
 
 const resolveMountHost = (

packages/app/src/web/terminal-wheel-scroll.ts

@@ -0,0 +1,122 @@
+export type TerminalWheelMouseTrackingMode = "any" | "drag" | "none" | "vt200" | "x10"
+
+export type TerminalWheelScrollTerminal = {
+  readonly modes: {
+    readonly mouseTrackingMode: TerminalWheelMouseTrackingMode
+  }
+  readonly rows: number
+  readonly scrollLines: (amount: number) => void
+}
+
+type TerminalWheelScrollEvent = {
+  readonly deltaMode: number
+  readonly deltaY: number
+  readonly stopImmediatePropagation?: () => void
+  readonly preventDefault: () => void
+  readonly stopPropagation: () => void
+}
+
+type TerminalWheelScrollHost = {
+  readonly addEventListener: (
+    type: "wheel",
+    listener: (event: TerminalWheelScrollEvent) => void,
+    options: AddEventListenerOptions
+  ) => void
+  readonly removeEventListener: (
+    type: "wheel",
+    listener: (event: TerminalWheelScrollEvent) => void,
+    options: boolean
+  ) => void
+}
+
+type TerminalWheelScrollDelta = {
+  readonly deltaMode: number
+  readonly deltaY: number
+  readonly previousPixelDeltaY: number
+  readonly rows: number
+}
+
+export type ResolvedTerminalWheelScrollDelta = {
+  readonly lines: number
+  readonly nextPixelDeltaY: number
+}
+
+type TerminalWheelScrollArgs = {
+  readonly host: TerminalWheelScrollHost
+  readonly terminal: TerminalWheelScrollTerminal
+}
+
+const wheelPixelDeltaMode = 0
+const wheelLineDeltaMode = 1
+const wheelPageDeltaMode = 2
+const pixelsPerTerminalLine = 15
+
+const hasActiveMouseTracking = (terminal: TerminalWheelScrollTerminal): boolean =>
+  terminal.modes.mouseTrackingMode !== "none"
+
+const validTerminalRows = (rows: number): number => {
+  if (!Number.isFinite(rows) || rows < 1) {
+    return 1
+  }
+  return Math.trunc(rows)
+}
+
+const finiteDelta = (delta: number): number => {
+  if (!Number.isFinite(delta)) {
+    return 0
+  }
+  return delta
+}
+
+export const resolveTerminalWheelScrollDelta = (
+  delta: TerminalWheelScrollDelta
+): ResolvedTerminalWheelScrollDelta => {
+  const deltaY = finiteDelta(delta.deltaY)
+  if (delta.deltaMode === wheelLineDeltaMode) {
+    return { lines: Math.trunc(deltaY), nextPixelDeltaY: 0 }
+  }
+  if (delta.deltaMode === wheelPageDeltaMode) {
+    return { lines: Math.trunc(deltaY * validTerminalRows(delta.rows)), nextPixelDeltaY: 0 }
+  }
+  if (delta.deltaMode !== wheelPixelDeltaMode) {
+    return { lines: Math.trunc(deltaY), nextPixelDeltaY: 0 }
+  }
+  const nextPixelDeltaY = finiteDelta(delta.previousPixelDeltaY) + deltaY
+  const lines = Math.trunc(nextPixelDeltaY / pixelsPerTerminalLine)
+  return {
+    lines,
+    nextPixelDeltaY: nextPixelDeltaY - lines * pixelsPerTerminalLine
+  }
+}
+
+export const attachTerminalWheelScroll = (
+  args: TerminalWheelScrollArgs
+): { readonly dispose: () => void } => {
+  let previousPixelDeltaY = 0
+  const onWheel = (event: TerminalWheelScrollEvent): void => {
+    if (!hasActiveMouseTracking(args.terminal)) {
+      return
+    }
+    const scrollDelta = resolveTerminalWheelScrollDelta({
+      deltaMode: event.deltaMode,
+      deltaY: event.deltaY,
+      previousPixelDeltaY,
+      rows: args.terminal.rows
+    })
+    previousPixelDeltaY = scrollDelta.nextPixelDeltaY
+    event.preventDefault()
+    event.stopPropagation()
+    event.stopImmediatePropagation?.()
+    if (scrollDelta.lines !== 0) {
+      args.terminal.scrollLines(scrollDelta.lines)
+    }
+  }
+
+  args.host.addEventListener("wheel", onWheel, { capture: true, passive: false })
+
+  return {
+    dispose: () => {
+      args.host.removeEventListener("wheel", onWheel, true)
+    }
+  }
+}

packages/app/tests/docker-git/terminal-panel-runtime-core.test.ts

@@ -83,15 +83,15 @@ describe("terminal panel runtime core", () => {
     expect(sent).toEqual([JSON.stringify({ data: "a", type: "input" })])
   })
 
-  it("keeps the viewport stable for terminal mouse reports", () => {
+  it("keeps the viewport stable for terminal mouse click reports", () => {
     const input = createTerminalInputHarness()
     const { sent, socketRef } = createOpenSocketRef()
 
     attachTerminalInput(input.terminal, socketRef, passThroughPasteGuard)
-    input.emit("\u001B[<64;10;5M")
+    input.emit("\u001B[<0;10;5M")
 
     expect(input.state.scrolls).toBe(0)
-    expect(sent).toEqual([JSON.stringify({ data: "\u001B[<64;10;5M", type: "input" })])
+    expect(sent).toEqual([JSON.stringify({ data: "\u001B[<0;10;5M", type: "input" })])
   })
 
   it("does not scroll or send input suppressed by the paste guard", () => {