Merge pull request #5608 from nodetool-ai/claude/macos-timeline-zoom-gestures-cd0z6g

feat(timeline): zoom on a macOS trackpad pinch in WebKit

Author: georgi

web/src/components/timeline/README.md

@@ -28,6 +28,10 @@ a keyboard layout the user picks in the shortcut sheet (`?`):
   asset, then Append, Insert or Overwrite it at the playhead.
 - **Playback**: J/K/L shuttle, I/O mark a loop range shown on the ruler, M
   adds a marker, Up/Down step between cuts.
+- **Zoom and pan**: Ctrl/Cmd+wheel zooms at the cursor, and so does a macOS
+  trackpad pinch — Chromium reports one as a synthetic ctrlKey wheel, Safari as
+  WebKit gesture events, and both land on the same anchored zoom. A two-finger
+  horizontal swipe or Shift+wheel pans the lanes.
 
 ## Phone layout
 

web/src/components/timeline/Tracks/TracksRegion.tsx

@@ -33,8 +33,10 @@
  * ../TimelineShortcutsDialog.tsx — keep the two in sync when a shortcut
  * changes.
  *
- * Zoom: Ctrl/Cmd+wheel (or a trackpad pinch) on the lane area changes msPerPx,
- *   anchored at the cursor.
+ * Zoom: Ctrl/Cmd+wheel on the lane area changes msPerPx, anchored at the
+ *   cursor. A macOS trackpad pinch arrives as that same synthetic ctrlKey
+ *   wheel in Chromium and as WebKit gesture events in Safari; both routes land
+ *   on the same anchored zoom.
  * Horizontal scroll: a trackpad two-finger horizontal swipe or Shift+wheel
  *   scrolls the lanes left/right. The handler takes the gesture over so the
  *   browser's back/forward swipe never fires at the scroll edges; a plain
@@ -101,6 +103,11 @@ import { deserializeDragData } from "../../../lib/dragdrop";
 import { assetMediaType } from "../dnd/assetToClipAdapter";
 import { buildTypedIndexMap } from "./trackVisuals";
 import { partitionTimelineWheel, normalizeWheelDeltaPx } from "./timelineWheel";
+import {
+  pinchMsPerPx,
+  supportsWebKitGestures,
+  type WebKitGestureEvent
+} from "./timelineGesture";
 import { resolveTimelineAction } from "../timelineKeymap";
 import { performSourceEdit } from "../sourceEdit";
 import {
@@ -483,6 +490,9 @@ export const TracksRegion: React.FC<TracksRegionProps> = memo(
     const pendingZoomFactorRef = useRef(1);
     const pendingZoomClientXRef = useRef(0);
     const zoomRafIdRef = useRef<number | null>(null);
+    // Set while a WebKit pinch is in flight so a stray ctrlKey wheel can't
+    // apply a second, compounding zoom on top of the gesture's own scale.
+    const webkitGestureActiveRef = useRef(false);
 
     useEffect(() => {
       const el = scrollableRef.current;
@@ -520,6 +530,7 @@ export const TracksRegion: React.FC<TracksRegionProps> = memo(
 
         if (e.ctrlKey || e.metaKey) {
           e.preventDefault();
+          if (webkitGestureActiveRef.current) return;
           pendingZoomFactorRef.current *= 1 + zoomDelta * ZOOM_SENSITIVITY;
           pendingZoomClientXRef.current = e.clientX;
           if (zoomRafIdRef.current === null) {
@@ -560,6 +571,86 @@ export const TracksRegion: React.FC<TracksRegionProps> = memo(
       };
     }, [uiStoreApi]);
 
+    // Pinch-to-zoom (macOS trackpad, WebKit). Chromium turns a pinch into the
+    // ctrlKey wheel the handler above already routes to zoom; Safari instead
+    // fires gesture events with a cumulative scale and no wheel at all, so
+    // without this a pinch over the timeline zooms the page. Feeds the same
+    // setZoom + `zoomAnchorRef` path, so the time under the fingers stays put.
+    useEffect(() => {
+      const el = scrollableRef.current;
+      if (!el || !supportsWebKitGestures(window)) return;
+
+      let startMsPerPx = 0;
+      let pendingScale = 1;
+      let pendingClientX = 0;
+      let rafId: number | null = null;
+
+      const applyGesture = () => {
+        rafId = null;
+        if (startMsPerPx === 0) return;
+        const current = uiStoreApi.getState().msPerPx;
+        const next = pinchMsPerPx(
+          startMsPerPx,
+          pendingScale,
+          MIN_MS_PER_PX,
+          MAX_MS_PER_PX
+        );
+        if (next === current) return;
+
+        const rect = el.getBoundingClientRect();
+        const cursorPx = pendingClientX - rect.left;
+        zoomAnchorRef.current = {
+          timeMs: (el.scrollLeft + cursorPx) * current,
+          cursorPx
+        };
+        uiStoreApi.getState().setZoom(next);
+      };
+
+      const onGestureStart = (event: Event) => {
+        const e = event as WebKitGestureEvent;
+        // Claim the pinch before Safari applies its own page zoom.
+        e.preventDefault();
+        webkitGestureActiveRef.current = true;
+        startMsPerPx = uiStoreApi.getState().msPerPx;
+        pendingScale = 1;
+        pendingClientX = e.clientX;
+      };
+
+      const onGestureChange = (event: Event) => {
+        const e = event as WebKitGestureEvent;
+        e.preventDefault();
+        if (startMsPerPx === 0) return;
+        pendingScale = e.scale;
+        pendingClientX = e.clientX;
+        // A pinch delivers several events per frame; batch to one setZoom per
+        // frame so the lanes/clips/ruler re-render once.
+        if (rafId === null) rafId = requestAnimationFrame(applyGesture);
+      };
+
+      const endGesture = (event: Event) => {
+        event.preventDefault();
+        webkitGestureActiveRef.current = false;
+        startMsPerPx = 0;
+        if (rafId !== null) {
+          cancelAnimationFrame(rafId);
+          rafId = null;
+        }
+      };
+
+      // Non-passive so preventDefault() actually suppresses Safari's own page
+      // zoom.
+      el.addEventListener("gesturestart", onGestureStart, { passive: false });
+      el.addEventListener("gesturechange", onGestureChange, { passive: false });
+      el.addEventListener("gestureend", endGesture, { passive: false });
+      return () => {
+        el.removeEventListener("gesturestart", onGestureStart);
+        el.removeEventListener("gesturechange", onGestureChange);
+        el.removeEventListener("gestureend", endGesture);
+        webkitGestureActiveRef.current = false;
+        if (rafId !== null) cancelAnimationFrame(rafId);
+      };
+    }, [uiStoreApi]);
+
     // Pinch-to-zoom (touch). The desktop route to zoom is Ctrl+wheel, which a
     // phone has no way to produce; without this the only zoom on a phone is the
     // status-bar buttons, and trimming to a frame needs a scale you can reach

web/src/components/timeline/Tracks/__tests__/TracksRegionGesture.test.tsx

@@ -0,0 +1,127 @@
+/**
+ * TracksRegion pinch-to-zoom over WebKit gesture events (macOS trackpad in
+ * Safari). jsdom has no GestureEvent, so the events are synthesized with the
+ * fields WebKit sends: a cumulative `scale` and the gesture centroid.
+ */
+import { describe, it, expect, jest, beforeEach, afterEach } from "@jest/globals";
+import { act, render } from "@testing-library/react";
+import { ThemeProvider } from "@mui/material/styles";
+
+import mockTheme from "../../../../__mocks__/themeMock";
+import { TracksRegion } from "../TracksRegion";
+import { TimelineProvider } from "../../../../stores/timeline/TimelineInstance";
+import { useTimelineUIStore } from "../../../../stores/timeline/TimelineUIStore";
+
+jest.mock("../../../../lib/rest-fetch", () => ({
+  restFetch: jest.fn()
+}));
+
+type GestureInit = { scale: number; clientX: number };
+
+const gesture = (type: string, init: GestureInit): Event => {
+  const event = new Event(type, { bubbles: true, cancelable: true });
+  Object.assign(event, { ...init, clientY: 0, rotation: 0 });
+  return event;
+};
+
+/** Run the pending rAF callback the zoom batches into. */
+const flushFrame = (frames: Array<FrameRequestCallback>) => {
+  const pending = frames.splice(0, frames.length);
+  act(() => {
+    for (const frame of pending) frame(0);
+  });
+};
+
+describe("TracksRegion WebKit pinch zoom", () => {
+  let frames: Array<FrameRequestCallback>;
+  let rafSpy: jest.SpiedFunction<typeof window.requestAnimationFrame>;
+
+  beforeEach(() => {
+    frames = [];
+    // Feature detection: only a browser that dispatches gesture events (Safari)
+    // gets the listeners.
+    (window as unknown as { ongesturechange: unknown }).ongesturechange = null;
+    rafSpy = jest
+      .spyOn(window, "requestAnimationFrame")
+      .mockImplementation((cb: FrameRequestCallback) => {
+        frames.push(cb);
+        return frames.length;
+      });
+  });
+
+  afterEach(() => {
+    rafSpy.mockRestore();
+    delete (window as unknown as { ongesturechange?: unknown }).ongesturechange;
+  });
+
+  const setup = () => {
+    const result = render(
+      <ThemeProvider theme={mockTheme}>
+        <TimelineProvider>
+          <TracksRegion heightPx={400} />
+        </TimelineProvider>
+      </ThemeProvider>
+    );
+    act(() => {
+      useTimelineUIStore.getState().setZoom(10);
+    });
+    const el = result.getByTestId("tracks-scroll-area");
+    return el;
+  };
+
+  it("zooms in as the fingers move apart and out as they close", () => {
+    const el = setup();
+
+    act(() => {
+      el.dispatchEvent(gesture("gesturestart", { scale: 1, clientX: 100 }));
+      el.dispatchEvent(gesture("gesturechange", { scale: 2, clientX: 100 }));
+    });
+    flushFrame(frames);
+    expect(useTimelineUIStore.getState().msPerPx).toBe(5);
+
+    // Still the same gesture: `scale` is cumulative, so 0.5 is half the scale
+    // it started at, not half of the last frame.
+    act(() => {
+      el.dispatchEvent(gesture("gesturechange", { scale: 0.5, clientX: 100 }));
+    });
+    flushFrame(frames);
+    expect(useTimelineUIStore.getState().msPerPx).toBe(20);
+  });
+
+  it("takes the gesture over so Safari does not zoom the page", () => {
+    const el = setup();
+    const start = gesture("gesturestart", { scale: 1, clientX: 100 });
+    const change = gesture("gesturechange", { scale: 1.5, clientX: 100 });
+
+    act(() => {
+      el.dispatchEvent(start);
+      el.dispatchEvent(change);
+    });
+    expect(start.defaultPrevented).toBe(true);
+    expect(change.defaultPrevented).toBe(true);
+  });
+
+  it("ignores a gesturechange after the gesture ended", () => {
+    const el = setup();
+
+    act(() => {
+      el.dispatchEvent(gesture("gesturestart", { scale: 1, clientX: 100 }));
+      el.dispatchEvent(gesture("gestureend", { scale: 2, clientX: 100 }));
+      el.dispatchEvent(gesture("gesturechange", { scale: 4, clientX: 100 }));
+    });
+    flushFrame(frames);
+    expect(useTimelineUIStore.getState().msPerPx).toBe(10);
+  });
+
+  it("leaves the zoom to the wheel route where gesture events don't exist", () => {
+    delete (window as unknown as { ongesturechange?: unknown }).ongesturechange;
+    const el = setup();
+
+    act(() => {
+      el.dispatchEvent(gesture("gesturestart", { scale: 1, clientX: 100 }));
+      el.dispatchEvent(gesture("gesturechange", { scale: 2, clientX: 100 }));
+    });
+    flushFrame(frames);
+    expect(useTimelineUIStore.getState().msPerPx).toBe(10);
+  });
+});

web/src/components/timeline/Tracks/__tests__/timelineGesture.test.ts

@@ -0,0 +1,52 @@
+/**
+ * macOS trackpad pinch, WebKit route.
+ *
+ * Pins the pinch scale math and the feature detection that keeps the gesture
+ * listeners off browsers that report a pinch as a ctrlKey wheel instead.
+ */
+
+import { pinchMsPerPx, supportsWebKitGestures } from "../timelineGesture";
+
+const MIN = 0.5;
+const MAX = 500;
+
+describe("pinchMsPerPx", () => {
+  it("zooms in when the fingers move apart (scale > 1)", () => {
+    expect(pinchMsPerPx(10, 2, MIN, MAX)).toBe(5);
+  });
+
+  it("zooms out when the fingers move together (scale < 1)", () => {
+    expect(pinchMsPerPx(10, 0.5, MIN, MAX)).toBe(20);
+  });
+
+  it("holds the scale at a gesture that has not moved yet", () => {
+    expect(pinchMsPerPx(10, 1, MIN, MAX)).toBe(10);
+  });
+
+  it("clamps to the zoom bounds", () => {
+    expect(pinchMsPerPx(10, 1000, MIN, MAX)).toBe(MIN);
+    expect(pinchMsPerPx(10, 0.001, MIN, MAX)).toBe(MAX);
+  });
+
+  it("falls back to the start scale for a zero or non-finite scale", () => {
+    expect(pinchMsPerPx(10, 0, MIN, MAX)).toBe(10);
+    expect(pinchMsPerPx(10, -1, MIN, MAX)).toBe(10);
+    expect(pinchMsPerPx(10, Number.NaN, MIN, MAX)).toBe(10);
+  });
+
+  it("is cumulative, not incremental — the same scale gives the same result", () => {
+    expect(pinchMsPerPx(10, 1.5, MIN, MAX)).toBe(pinchMsPerPx(10, 1.5, MIN, MAX));
+  });
+});
+
+describe("supportsWebKitGestures", () => {
+  it("detects a browser that dispatches gesture events", () => {
+    expect(
+      supportsWebKitGestures({ ongesturechange: null } as unknown as Window)
+    ).toBe(true);
+  });
+
+  it("reports false where a pinch arrives as a ctrlKey wheel instead", () => {
+    expect(supportsWebKitGestures({} as unknown as Window)).toBe(false);
+  });
+});

web/src/components/timeline/Tracks/timelineGesture.ts

@@ -0,0 +1,48 @@
+/**
+ * macOS trackpad pinch, WebKit route.
+ *
+ * Chromium reports a trackpad pinch as a synthetic ctrlKey wheel, which
+ * `partitionTimelineWheel` already routes to zoom. WebKit does not: Safari
+ * fires `gesturestart` / `gesturechange` / `gestureend` carrying a cumulative
+ * `scale` and emits no wheel event at all, so without this route a pinch over
+ * the timeline zooms the page instead of the lanes.
+ *
+ * The math is pure so it can be tested without a WebKit-only event.
+ */
+
+/**
+ * WebKit's non-standard GestureEvent. Not in lib.dom, so it is declared here.
+ * `scale` is cumulative since `gesturestart` (1 = unchanged, >1 = fingers
+ * apart).
+ */
+export interface WebKitGestureEvent extends UIEvent {
+  readonly scale: number;
+  readonly rotation: number;
+  readonly clientX: number;
+  readonly clientY: number;
+}
+
+/** True when the browser dispatches WebKit gesture events (Safari). */
+export function supportsWebKitGestures(win: Window): boolean {
+  return "ongesturechange" in win;
+}
+
+/**
+ * Scale (ms per pixel) for a cumulative pinch scale, clamped to the zoom
+ * bounds. Fingers apart (scale > 1) zooms in, so msPerPx shrinks.
+ */
+export function pinchMsPerPx(
+  startMsPerPx: number,
+  scale: number,
+  minMsPerPx: number,
+  maxMsPerPx: number
+): number {
+  const clamp = (value: number) =>
+    Math.min(maxMsPerPx, Math.max(minMsPerPx, value));
+  // A zero or non-finite scale would blow up the division; Safari sends 0 for
+  // a gesture that ends the instant it starts.
+  if (!Number.isFinite(scale) || scale <= 0) {
+    return clamp(startMsPerPx);
+  }
+  return clamp(startMsPerPx / scale);
+}