File viewer: drag past the edge autoscrolls and survives blur

- Pure `computeAutoscrollPxPerFrame(pointerY, top, bottom)` returns negative for scroll-up, positive for scroll-down, zero in the safe band. Threshold 30 px, speed scales linearly with distance from the edge, capped at 540 px/frame. Pure: no DOM, no time. 7 tests cover boundary semantics, monotonic scaling, and clamp.
- New `createViewerAutoscroll()` composable in `viewer-autoscroll.svelte.ts` owns the RAF loop. `start()` requests a frame; the tick reads the current pointer Y, the content's bounding rect, applies the px-per-frame delta to `scrollTop`, calls back into the page to re-resolve the caret, and re-queues. Self-terminates when the pointer re-enters the safe band or the content element disappears. 6 tests stub RAF/cancel and drive frames deterministically.
- Page wiring: `pointerdown` calls `setPointerCapture` (try/catch since some webviews refuse it on non-focusable targets; falling through is safe, just no autoscroll past the webview edge). `pointermove` updates the drag's pointer Y and toggles the autoscroll loop based on the current px-per-frame. `pointerup` / `pointercancel` end the drag. Window `blur` is the macOS safety net: if focus hands off to another app mid-drag without firing a pointer event, blur stops the loop.
- Playwright smoke test for drag-past-edge: dispatches synthetic pointer events that exit the viewport via the bottom, then `pointerup` outside, asserts the page didn't crash and `.file-content` is still alive. A full "selection extends past the original buffer" test needs a multi-thousand-line fixture (deferred; the math + controller logic are well-covered at the unit level).

Author: vdavid

.gitignore

@@ -66,4 +66,7 @@ apps/desktop/src-tauri/resources/ai
 .cargo-docker/
 
 # Entire.io
-.entire/docs/specs/file-viewer-selection-progress.md
+.entire/
+
+# Per-milestone progress tracker for in-flight feature work (transient, recovery aid)
+docs/specs/file-viewer-selection-progress.md

apps/desktop/src/routes/viewer/+page.svelte

@@ -34,6 +34,8 @@
     } from './selection.svelte'
     import { createViewerCopy } from './viewer-copy.svelte'
     import { caretFromPoint } from './viewer-pointer'
+    import { computeAutoscrollPxPerFrame } from './viewer-autoscroll'
+    import { createViewerAutoscroll } from './viewer-autoscroll.svelte'
     import { addToast } from '$lib/ui/toast/toast-store.svelte'
     import { formatBytes, type RangeEnd } from '$lib/tauri-commands'
     import ModalDialog from '$lib/ui/ModalDialog.svelte'
@@ -203,6 +205,27 @@
      */
     let dragPointerId: number | null = null
 
+    /** The pointer's most-recent Y position, used by the autoscroll RAF loop. */
+    let dragPointerY: number = 0
+
+    /**
+     * Re-resolves the caret after each autoscroll step. Uses the X position one px
+     * past the left edge of `.file-content` so the caret lands inside the line text
+     * (not the line-number gutter, which sits flush to the left edge).
+     */
+    function reAimAfterAutoscroll(pointerY: number): void {
+        if (!scroll.contentRef) return
+        const rect = scroll.contentRef.getBoundingClientRect()
+        const caret = caretFromPoint(document, rect.left + 1, pointerY)
+        if (caret !== null) selection.setFocus(caret)
+    }
+
+    const autoscroll = createViewerAutoscroll({
+        getContentRef: () => scroll.contentRef,
+        getPointerY: () => dragPointerY,
+        onScrollStep: reAimAfterAutoscroll,
+    })
+
     function handleContentPointerDown(e: PointerEvent): void {
         // Left mouse button only (button 0). Right-click goes to the context menu (M4).
         if (e.button !== 0) return
@@ -211,18 +234,39 @@
         e.preventDefault()
         selection.setAnchor(caret)
         dragPointerId = e.pointerId
+        dragPointerY = e.clientY
+        // Capture so we keep receiving pointer events even if the cursor leaves the
+        // webview (the user dragged past the edge into another macOS window or the
+        // desktop). Without capture, autoscroll would never see a `pointerup` to stop.
+        try {
+            ;(e.currentTarget as Element | null)?.setPointerCapture(e.pointerId)
+        } catch {
+            // Capture can throw on some webviews if the target isn't focusable; ignoring
+            // is safe (the drag still works, just without the safety net).
+        }
     }
 
     function handleContentPointerMove(e: PointerEvent): void {
         if (dragPointerId === null || e.pointerId !== dragPointerId) return
+        dragPointerY = e.clientY
         const caret = caretFromPoint(document, e.clientX, e.clientY)
-        if (caret === null) return
-        selection.setFocus(caret)
+        if (caret !== null) selection.setFocus(caret)
+
+        // Check whether the pointer is near a viewport edge; start/stop autoscroll as needed.
+        if (!scroll.contentRef) return
+        const rect = scroll.contentRef.getBoundingClientRect()
+        const delta = computeAutoscrollPxPerFrame(e.clientY, rect.top, rect.bottom)
+        if (delta !== 0) {
+            autoscroll.start()
+        } else {
+            autoscroll.stop()
+        }
     }
 
     function endDrag(pointerId: number): void {
         if (dragPointerId !== pointerId) return
         dragPointerId = null
+        autoscroll.stop()
     }
 
     function handleContentPointerUp(e: PointerEvent): void {
@@ -233,6 +277,18 @@
         endDrag(e.pointerId)
     }
 
+    /**
+     * Window `blur` safety net: macOS may hand focus to another app mid-drag without
+     * firing a `pointerup` or `pointercancel`. Without this, the autoscroll RAF loop
+     * would keep running indefinitely.
+     */
+    function handleWindowBlur(): void {
+        if (dragPointerId !== null) {
+            dragPointerId = null
+        }
+        autoscroll.stop()
+    }
+
     // Fetch lines when visible range changes (debounced)
     $effect(() => {
         scroll.runFetchEffect()
@@ -700,7 +756,7 @@
     })
 </script>
 
-<svelte:window on:keydown={handleKeyDown} />
+<svelte:window on:keydown={handleKeyDown} on:blur={handleWindowBlur} />
 
 <main
     class="viewer-container"

apps/desktop/src/routes/viewer/viewer-autoscroll.svelte.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
+
+import { createViewerAutoscroll } from './viewer-autoscroll.svelte'
+
+/**
+ * Stub `requestAnimationFrame` / `cancelAnimationFrame` so tests can drive the loop
+ * deterministically. Each `start()` queues a tick; the test then calls `runOneFrame()`
+ * to fire it.
+ */
+let scheduledTick: (() => void) | null = null
+let nextRafId = 1
+
+function rafStub(cb: FrameRequestCallback): number {
+  scheduledTick = () => cb(performance.now())
+  return nextRafId++
+}
+
+function cancelStub(_id: number): void {
+  scheduledTick = null
+}
+
+function runOneFrame(): void {
+  const fn = scheduledTick
+  scheduledTick = null
+  fn?.()
+}
+
+let originalRaf: typeof requestAnimationFrame
+let originalCaf: typeof cancelAnimationFrame
+
+beforeEach(() => {
+  originalRaf = globalThis.requestAnimationFrame
+  originalCaf = globalThis.cancelAnimationFrame
+  globalThis.requestAnimationFrame = rafStub as unknown as typeof requestAnimationFrame
+  globalThis.cancelAnimationFrame = cancelStub as unknown as typeof cancelAnimationFrame
+  scheduledTick = null
+  nextRafId = 1
+})
+
+afterEach(() => {
+  globalThis.requestAnimationFrame = originalRaf
+  globalThis.cancelAnimationFrame = originalCaf
+})
+
+function makeContent(rectTop: number, rectBottom: number): { el: HTMLElement; getScrollTop: () => number } {
+  const el = document.createElement('div')
+  // jsdom doesn't lay anything out, so stub getBoundingClientRect.
+  el.getBoundingClientRect = () =>
+    ({
+      top: rectTop,
+      bottom: rectBottom,
+      left: 0,
+      right: 100,
+      width: 100,
+      height: rectBottom - rectTop,
+      x: 0,
+      y: rectTop,
+      toJSON: () => ({}),
+    }) as DOMRect
+  return { el, getScrollTop: () => el.scrollTop }
+}
+
+describe('createViewerAutoscroll', () => {
+  it('start() requests a frame; stop() cancels it', () => {
+    const { el } = makeContent(0, 400)
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => el,
+      getPointerY: () => 200,
+      onScrollStep: () => {},
+    })
+
+    expect(ctrl.isRunning()).toBe(false)
+    ctrl.start()
+    expect(ctrl.isRunning()).toBe(true)
+    ctrl.stop()
+    expect(ctrl.isRunning()).toBe(false)
+  })
+
+  it('start() is idempotent: second call is a no-op', () => {
+    const { el } = makeContent(0, 400)
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => el,
+      getPointerY: () => 200,
+      onScrollStep: () => {},
+    })
+    ctrl.start()
+    const firstTick = scheduledTick
+    ctrl.start()
+    expect(scheduledTick).toBe(firstTick)
+  })
+
+  it('loop scrolls and calls onScrollStep when the pointer is near the edge', () => {
+    const { el } = makeContent(0, 400)
+    const onStep = vi.fn()
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => el,
+      getPointerY: () => 395, // 5 px from the bottom edge → autoscroll down.
+      onScrollStep: onStep,
+    })
+
+    ctrl.start()
+    runOneFrame()
+    expect(el.scrollTop).toBeGreaterThan(0)
+    expect(onStep).toHaveBeenCalledTimes(1)
+    expect(onStep).toHaveBeenCalledWith(395)
+    // The tick re-queued itself for the next frame.
+    expect(ctrl.isRunning()).toBe(true)
+  })
+
+  it('loop self-terminates when the pointer re-enters the safe band', () => {
+    const { el } = makeContent(0, 400)
+    let y = 5
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => el,
+      getPointerY: () => y,
+      onScrollStep: () => {},
+    })
+
+    ctrl.start()
+    runOneFrame() // First frame: pointer is at y=5 (near top), so we scroll up.
+    expect(ctrl.isRunning()).toBe(true)
+    y = 200 // Move pointer back to the middle.
+    runOneFrame() // delta = 0, loop terminates.
+    expect(ctrl.isRunning()).toBe(false)
+  })
+
+  it('loop self-terminates when the content ref disappears (unmount mid-drag)', () => {
+    let contentRef: HTMLElement | undefined = makeContent(0, 400).el
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => contentRef,
+      getPointerY: () => 5,
+      onScrollStep: () => {},
+    })
+
+    ctrl.start()
+    expect(ctrl.isRunning()).toBe(true)
+    contentRef = undefined
+    runOneFrame()
+    expect(ctrl.isRunning()).toBe(false)
+  })
+
+  it('stop() during a tick prevents the next frame', () => {
+    const { el } = makeContent(0, 400)
+    const ctrl = createViewerAutoscroll({
+      getContentRef: () => el,
+      getPointerY: () => 5,
+      onScrollStep: () => {},
+    })
+
+    ctrl.start()
+    runOneFrame() // First frame fires and re-queues.
+    expect(ctrl.isRunning()).toBe(true)
+    ctrl.stop()
+    expect(ctrl.isRunning()).toBe(false)
+    // No more frames will fire.
+    expect(scheduledTick).toBeNull()
+  })
+})

apps/desktop/src/routes/viewer/viewer-autoscroll.svelte.ts

@@ -0,0 +1,69 @@
+/**
+ * Drag-autoscroll loop driver for the viewer.
+ *
+ * Owns the RAF id and the running flag. The page wires the rest: it tells the loop
+ * the current pointer Y on each move, picks the scroll target (`contentRef`), and the
+ * loop tells the page when to re-resolve the caret after each scroll step. Pure
+ * functions go in `viewer-autoscroll.ts`; the side-effecting bits (RAF, scrollTop
+ * mutation) live here.
+ */
+
+import { computeAutoscrollPxPerFrame } from './viewer-autoscroll'
+
+interface AutoscrollDeps {
+  /** Returns the scrollable element to mutate. Re-read every frame so an unmount
+   *  during the loop bails cleanly. */
+  getContentRef: () => HTMLElement | undefined
+  /** Returns the pointer's most-recent clientY. Re-read every frame. */
+  getPointerY: () => number
+  /** Called after each scroll step so the page can update the selection focus. */
+  onScrollStep: (pointerY: number) => void
+}
+
+export interface AutoscrollController {
+  /** Idempotently starts the loop. No-op if already running. */
+  start(): void
+  /** Stops the loop if running. Safe to call from anywhere (pointerup, blur, unmount). */
+  stop(): void
+  /** Returns whether the loop is currently running. Test-only hook. */
+  isRunning(): boolean
+}
+
+export function createViewerAutoscroll(deps: AutoscrollDeps): AutoscrollController {
+  let rafId: number | null = null
+
+  function tick(): void {
+    const content = deps.getContentRef()
+    if (!content) {
+      rafId = null
+      return
+    }
+    const rect = content.getBoundingClientRect()
+    const y = deps.getPointerY()
+    const delta = computeAutoscrollPxPerFrame(y, rect.top, rect.bottom)
+    if (delta === 0) {
+      rafId = null
+      return
+    }
+    content.scrollTop += delta
+    deps.onScrollStep(y)
+    rafId = requestAnimationFrame(tick)
+  }
+
+  function start(): void {
+    if (rafId !== null) return
+    rafId = requestAnimationFrame(tick)
+  }
+
+  function stop(): void {
+    if (rafId === null) return
+    cancelAnimationFrame(rafId)
+    rafId = null
+  }
+
+  function isRunning(): boolean {
+    return rafId !== null
+  }
+
+  return { start, stop, isRunning }
+}

apps/desktop/src/routes/viewer/viewer-autoscroll.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+
+import { EDGE_AUTOSCROLL_PX, computeAutoscrollPxPerFrame } from './viewer-autoscroll'
+
+describe('computeAutoscrollPxPerFrame', () => {
+  // Use a notional viewport of [100, 500] (height 400) for these tests.
+  const top = 100
+  const bottom = 500
+
+  it('returns 0 when the pointer is comfortably inside the viewport', () => {
+    expect(computeAutoscrollPxPerFrame(300, top, bottom)).toBe(0)
+    expect(computeAutoscrollPxPerFrame(top + EDGE_AUTOSCROLL_PX + 1, top, bottom)).toBe(0)
+    expect(computeAutoscrollPxPerFrame(bottom - EDGE_AUTOSCROLL_PX - 1, top, bottom)).toBe(0)
+  })
+
+  it('returns 0 right at the threshold (closed interval on the safe side)', () => {
+    // Exactly at the threshold: still safe. (distanceFromTop = EDGE_AUTOSCROLL_PX → not less than).
+    expect(computeAutoscrollPxPerFrame(top + EDGE_AUTOSCROLL_PX, top, bottom)).toBe(0)
+    expect(computeAutoscrollPxPerFrame(bottom - EDGE_AUTOSCROLL_PX, top, bottom)).toBe(0)
+  })
+
+  it('returns a small negative value near the top edge', () => {
+    // 5 px inside the threshold: ratio = (30 - 25) / 30 = 1/6. So roughly -90.
+    const v = computeAutoscrollPxPerFrame(top + 25, top, bottom)
+    expect(v).toBeLessThan(0)
+    expect(v).toBeGreaterThan(-100)
+  })
+
+  it('returns a small positive value near the bottom edge', () => {
+    const v = computeAutoscrollPxPerFrame(bottom - 25, top, bottom)
+    expect(v).toBeGreaterThan(0)
+    expect(v).toBeLessThan(100)
+  })
+
+  it('returns the maximum speed when the pointer is exactly at the edge', () => {
+    expect(computeAutoscrollPxPerFrame(top, top, bottom)).toBe(-540)
+    expect(computeAutoscrollPxPerFrame(bottom, top, bottom)).toBe(540)
+  })
+
+  it('clamps to the maximum when the pointer is past the edge', () => {
+    expect(computeAutoscrollPxPerFrame(top - 100, top, bottom)).toBe(-540)
+    expect(computeAutoscrollPxPerFrame(bottom + 100, top, bottom)).toBe(540)
+  })
+
+  it('scales monotonically: closer to the edge → faster', () => {
+    const a = computeAutoscrollPxPerFrame(bottom - 25, top, bottom)
+    const b = computeAutoscrollPxPerFrame(bottom - 10, top, bottom)
+    const c = computeAutoscrollPxPerFrame(bottom - 1, top, bottom)
+    expect(a).toBeLessThan(b)
+    expect(b).toBeLessThan(c)
+  })
+})