@weasel-js/labkit 1.4.0 → 1.4.2

package/dist/ui/layers/index.js

@@ -1,4 +1,4 @@
-export { c3 as LayerStack } from '../../chunk-L5WBGUVR.js';
-import '../../chunk-7VW3S44V.js';
+export { c3 as LayerStack } from '../../chunk-ISSVF5PT.js';
+import '../../chunk-54ZWZ5FQ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,10 +1,11 @@
-export { a0 as UndoCapability } from '../_dts/frac-QS7XzvpG.js';
+export { a0 as UndoCapability } from '../_dts/frac-A4R6v4ld.js';
 import 'react';
-import '../_dts/types-C1Zw7s5P.js';
-import '../_dts/PrefsForm-BkUJZx0A.js';
-import '../_dts/types-ChVJJHvk.js';
+import '../_dts/types-lg4TSCb2.js';
+import '../_dts/weasel-canvas-FJTFi3ZZ.js';
+import 'react/jsx-runtime';
+import '../_dts/PrefsForm.d-CgxUequc.js';
+import '../_dts/types-BbXpvQa8.js';
 import '../_dts/types-DJ79Tg5J.js';
-import '../_dts/types-C-gh9Ap-.js';
 
 /** A subscriber to a named event. */
 type EventListener = () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -93,7 +93,7 @@
     "dev:drag": "LABKIT_EXAMPLE=drag-lab vite",
     "dev:weasel": "LABKIT_EXAMPLE=weasel-lab vite",
     "build": "tsup && npm run build:dts && npm run build:css && npm run build:fonts",
-    "build:dts": "NODE_OPTIONS=--max-old-space-size=8192 tsx scripts/build-dts.mts",
+    "build:dts": "NODE_OPTIONS=--max-old-space-size=3072 tsx scripts/build-dts.mts",
     "prepublishOnly": "npm run build",
     "build:css": "node scripts/build-css.mjs",
     "build:fonts": "mkdir -p dist/fonts && cp ../theme/fonts/*.woff2 dist/fonts/",
@@ -114,11 +114,11 @@
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/core": "1.4.0",
-    "@weasel-js/loupe": "1.4.0",
-    "@weasel-js/svg": "1.4.0",
-    "@weasel-js/theme": "1.4.0",
-    "@weasel-js/ui": "1.4.0",
+    "@weasel-js/core": "1.4.2",
+    "@weasel-js/loupe": "1.4.2",
+    "@weasel-js/svg": "1.4.2",
+    "@weasel-js/theme": "1.4.2",
+    "@weasel-js/ui": "1.4.2",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -129,7 +129,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.4.0",
+    "@weasel-js/modes": "1.4.2",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationTargets.tsx

@@ -1,3 +1,4 @@
+import type { TrialInfo } from '../state/types';
 import { AnnotationOverlay } from './AnnotationOverlay';
 import type { AnnotationsApi, AnnotationsCapability } from './types';
 
@@ -6,6 +7,9 @@ export interface AnnotationTargetsProps {
   capability: AnnotationsCapability;
   state: unknown;
   config: unknown;
+  /** The trial these targets belong to. `capability.targets` is told it, so a
+   *  consumer holding per-trial refs can hand back this trial's. */
+  trial: TrialInfo;
   annotations: AnnotationsApi;
   activeToolId: string | null;
 }
@@ -15,10 +19,11 @@ export function AnnotationTargets({
   capability,
   state,
   config,
+  trial,
   annotations,
   activeToolId,
 }: AnnotationTargetsProps) {
-  const targets = capability.targets(state, config);
+  const targets = capability.targets(state, config, trial);
 
   return (
     <>

package/src/annotations/Annotations.overlay.test.tsx

@@ -82,6 +82,7 @@ function Harness({ toolId = 'rect' }: { toolId?: string }) {
             capability={capability}
             state={{}}
             config={{}}
+            trial={{ id: 'harness', view: null }}
             annotations={annotations}
             activeToolId={toolId}
           />
@@ -170,6 +171,7 @@ function OneTrial({
         capability={capability}
         state={{}}
         config={{}}
+        trial={{ id: trialId, view: null }}
         annotations={annotations}
         activeToolId="rect"
       />

package/src/annotations/types.ts

@@ -1,5 +1,6 @@
 import type { RefObject } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import type { TrialInfo } from '../state/types';
 import type { MarkScene } from './store';
 
 /** A point in fractions of a target's content box. */
@@ -158,7 +159,9 @@ export interface AnnotationStorage {
 /** Declares that an instrument accepts marks: which regions take them,
  *  optionally what a mark is allowed to mean, and optionally where they live. */
 export interface AnnotationsCapability<TS = unknown, TC = unknown> {
-  targets: (state: TS, config: TC) => readonly AnnotationTarget[];
+  /** `trial` is which trial is asking: a declaration made once per instrument
+   *  is called once per trial, and its targets are that trial's own. */
+  targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
   meaning?: AnnotationMeaning;
   storage?: AnnotationStorage;
   /** Fires after every finished export, labkit's own chrome included. A

package/src/canvas/CanvasStack.tsx

@@ -81,7 +81,14 @@ export function CanvasStack({
 
   const frame = useMemo(() => resolveFrame(worldSpec, size), [worldSpec, size]);
 
-  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom, frame });
+  const onTap = (e: PointerEvent) => {
+    const el = containerRef.current;
+    if (!onHitTest || !el) return;
+    const rect = el.getBoundingClientRect();
+    onHitTest(screenToWorld({ x: e.clientX - rect.left, y: e.clientY - rect.top }, view, frame));
+  };
+
+  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, onTap });
   useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(
@@ -103,16 +110,6 @@ export function CanvasStack({
     height: size.height,
   };
 
-  const handlePointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
-    const wasDragging = handlers.isDragging();
-    handlers.onPointerUp(e);
-    if (!wasDragging && onHitTest && containerRef.current) {
-      const rect = containerRef.current.getBoundingClientRect();
-      const screen = { x: e.clientX - rect.left, y: e.clientY - rect.top };
-      onHitTest(screenToWorld(screen, view, frame));
-    }
-  };
-
   return (
     <CanvasStackContext.Provider value={ctxValue}>
       <div
@@ -121,8 +118,6 @@ export function CanvasStack({
         style={containerStyle}
         onWheel={handlers.onWheel}
         onPointerDown={handlers.onPointerDown}
-        onPointerMove={handlers.onPointerMove}
-        onPointerUp={handlePointerUp}
       >
         {layers.map((layer) => (
           <canvas

package/src/canvas/useOrbit.test.ts

@@ -1,5 +1,15 @@
+import { act, renderHook } from '@testing-library/react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
 import { describe, expect, it } from 'vitest';
-import { clampPitch, orbitAfterDrag, orbitAfterWheel, PITCH_LIMIT, wrapYaw } from './useOrbit';
+import {
+  clampPitch,
+  type OrbitView,
+  orbitAfterDrag,
+  orbitAfterWheel,
+  PITCH_LIMIT,
+  useOrbit,
+  wrapYaw,
+} from './useOrbit';
 
 const view = { yaw: 0, pitch: 0, distance: 5, target: { x: 0, y: 0, z: 0 } };
 
@@ -69,3 +79,89 @@ describe('orbitAfterWheel', () => {
     expect(orbitAfterWheel(view, -100_000, 0.5, 50).distance).toBe(0.5);
   });
 });
+
+/** The fields `useOrbit` reads off a React pointerdown, plus the element the
+ *  session hangs its document listeners off. */
+function press(
+  el: HTMLElement,
+  x: number,
+  y: number,
+  init: { pointerId?: number; button?: number; buttons?: number } = {},
+): ReactPointerEvent<HTMLElement> {
+  return {
+    pointerId: init.pointerId ?? 1,
+    button: init.button ?? 0,
+    buttons: init.buttons ?? 1,
+    clientX: x,
+    clientY: y,
+    currentTarget: el,
+  } as unknown as ReactPointerEvent<HTMLElement>;
+}
+
+function dispatchOn(target: EventTarget, type: string, init: PointerEventInit) {
+  act(() => {
+    target.dispatchEvent(new PointerEvent(type, { pointerId: 1, bubbles: true, ...init }));
+  });
+}
+
+function dragSetup() {
+  let current: OrbitView = view;
+  const onViewChange = (v: OrbitView) => {
+    current = v;
+  };
+  const { result, unmount } = renderHook(() => useOrbit({ view, onViewChange }));
+  const el = document.createElement('div');
+  document.body.appendChild(el);
+  return { result, unmount, el, getView: () => current };
+}
+
+describe('useOrbit dragging', () => {
+  it('turns from a move the element never sees', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 200, clientY: 150 });
+    expect(getView()).toEqual(orbitAfterDrag(view, 100, 50));
+  });
+
+  it('ends the drag on a release dispatched off the element', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 200, clientY: 150 });
+    dispatchOn(document, 'pointerup', { clientX: 200, clientY: 150 });
+    expect(result.current.isDragging()).toBe(false);
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView()).toEqual(orbitAfterDrag(view, 100, 50));
+  });
+
+  // The other half of the rule — a detached origin does cancel — is owned by
+  // pointerSession.test.ts, which exercises it without React in the way.
+  it('keeps turning when capture is lost and the element is still in the document', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 200, clientY: 150 });
+    // Chrome releases capture a beat before it delivers pointerup, so ending
+    // here throws away a release that has already been dispatched.
+    dispatchOn(el, 'lostpointercapture', {});
+    expect(result.current.isDragging()).toBe(true);
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView()).toEqual(orbitAfterDrag(view, 300, 300));
+  });
+
+  it('reads a move with nothing held as the release that never arrived', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100, { buttons: 1 })));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 200, clientY: 150 });
+    expect(getView()).toEqual(orbitAfterDrag(view, 100, 50));
+    dispatchOn(document, 'pointermove', { buttons: 0, clientX: 400, clientY: 400 });
+    expect(getView()).toEqual(orbitAfterDrag(view, 100, 50));
+    expect(result.current.isDragging()).toBe(false);
+  });
+
+  it('drops its listeners when the hook unmounts mid-drag', () => {
+    const { result, el, unmount, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    unmount();
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView()).toEqual(view);
+  });
+});

package/src/canvas/useOrbit.ts

@@ -1,4 +1,11 @@
-import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
+import { openPointerSession, type PointerSession } from '@weasel-js/core';
+import {
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  type WheelEvent,
+} from 'react';
 
 /** A point in the space the instrument works in. */
 export interface Vec3 {
@@ -70,15 +77,12 @@ export interface UseOrbitOptions {
 
 export interface OrbitHandlers {
   onWheel: (e: WheelEvent<HTMLElement>) => void;
-  onPointerDown: (e: PointerEvent<HTMLElement>) => void;
-  onPointerMove: (e: PointerEvent<HTMLElement>) => void;
-  onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+  onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
   onDoubleClick: () => void;
   isDragging: () => boolean;
 }
 
 interface DragState {
-  pointerId: number;
   startX: number;
   startY: number;
   startView: OrbitView;
@@ -95,8 +99,11 @@ export function useOrbit({
   maxDistance = 1000,
 }: UseOrbitOptions): OrbitHandlers {
   const dragRef = useRef<DragState | null>(null);
+  const sessionRef = useRef<PointerSession | null>(null);
   const viewRef = useRef(view);
   viewRef.current = view;
+  const onViewChangeRef = useRef(onViewChange);
+  onViewChangeRef.current = onViewChange;
   const homeRef = useRef(home ?? view);
   if (home) homeRef.current = home;
 
@@ -108,42 +115,42 @@ export function useOrbit({
     [onViewChange, minDistance, maxDistance],
   );
 
-  const onPointerDown = useCallback((e: PointerEvent<HTMLElement>) => {
-    if (e.button !== 0) return;
-    e.currentTarget.setPointerCapture(e.pointerId);
-    dragRef.current = {
-      pointerId: e.pointerId,
-      startX: e.clientX,
-      startY: e.clientY,
-      startView: viewRef.current,
-      moved: false,
-    };
+  const clearDrag = useCallback(() => {
+    dragRef.current = null;
+    sessionRef.current = null;
   }, []);
 
-  const onPointerMove = useCallback(
-    (e: PointerEvent<HTMLElement>) => {
-      const drag = dragRef.current;
-      if (!drag || drag.pointerId !== e.pointerId) return;
-      const dx = e.clientX - drag.startX;
-      const dy = e.clientY - drag.startY;
-      if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
-      drag.moved = true;
-      onViewChange(orbitAfterDrag(drag.startView, dx, dy));
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLElement>) => {
+      if (e.button !== 0) return;
+      const drag: DragState = {
+        startX: e.clientX,
+        startY: e.clientY,
+        startView: viewRef.current,
+        moved: false,
+      };
+      dragRef.current = drag;
+      sessionRef.current = openPointerSession(e.currentTarget, e, {
+        onMove: (ev) => {
+          const dx = ev.clientX - drag.startX;
+          const dy = ev.clientY - drag.startY;
+          if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+          drag.moved = true;
+          onViewChangeRef.current(orbitAfterDrag(drag.startView, dx, dy));
+        },
+        onEnd: clearDrag,
+        // A cancelled turn keeps where it got to: every move was committed as
+        // it arrived, so there is nothing left to undo.
+        onCancel: clearDrag,
+      });
     },
-    [onViewChange],
+    [clearDrag],
   );
 
-  const onPointerUp = useCallback((e: PointerEvent<HTMLElement>) => {
-    const drag = dragRef.current;
-    if (!drag || drag.pointerId !== e.pointerId) return;
-    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
-      e.currentTarget.releasePointerCapture(e.pointerId);
-    }
-    dragRef.current = null;
-  }, []);
+  useEffect(() => () => sessionRef.current?.cancel(), []);
 
   const onDoubleClick = useCallback(() => onViewChange(homeRef.current), [onViewChange]);
   const isDragging = useCallback(() => dragRef.current?.moved === true, []);
 
-  return { onWheel, onPointerDown, onPointerMove, onPointerUp, onDoubleClick, isDragging };
+  return { onWheel, onPointerDown, onDoubleClick, isDragging };
 }

package/src/canvas/usePanZoom.test.ts

@@ -1,5 +1,5 @@
 import { act, renderHook } from '@testing-library/react';
-import type { WheelEvent } from 'react';
+import type { PointerEvent as ReactPointerEvent, WheelEvent } from 'react';
 import { describe, expect, it } from 'vitest';
 import type { ViewTransform } from '../instrument/types';
 import { screenToWorld } from './canvasCoords';
@@ -109,3 +109,108 @@ describe('usePanZoom', () => {
     });
   });
 });
+
+/** The fields `usePanZoom` reads off a React pointerdown, plus the element the
+ *  session hangs its document listeners off. */
+function press(
+  el: HTMLElement,
+  x: number,
+  y: number,
+  init: { pointerId?: number; button?: number; buttons?: number } = {},
+): ReactPointerEvent<HTMLElement> {
+  return {
+    pointerId: init.pointerId ?? 1,
+    button: init.button ?? 0,
+    buttons: init.buttons ?? 1,
+    clientX: x,
+    clientY: y,
+    currentTarget: el,
+  } as unknown as ReactPointerEvent<HTMLElement>;
+}
+
+function dispatchOn(target: EventTarget, type: string, init: PointerEventInit) {
+  act(() => {
+    target.dispatchEvent(new PointerEvent(type, { pointerId: 1, bubbles: true, ...init }));
+  });
+}
+
+function dragSetup(options?: Partial<UsePanZoomOptions>) {
+  let view: ViewTransform = { zoom: 1, pan: { x: 0, y: 0 } };
+  const onViewChange = (v: ViewTransform) => {
+    view = v;
+  };
+  const { result, unmount } = renderHook(() =>
+    usePanZoom({ ...options, view, onViewChange } as UsePanZoomOptions),
+  );
+  const el = document.createElement('div');
+  document.body.appendChild(el);
+  return { result, unmount, el, getView: () => view };
+}
+
+describe('usePanZoom dragging', () => {
+  it('pans from a move the element never sees', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    expect(getView().pan).toEqual({ x: 50, y: 20 });
+  });
+
+  it('ends the drag on a release dispatched off the element', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    dispatchOn(document, 'pointerup', { clientX: 150, clientY: 120 });
+    expect(result.current.isDragging()).toBe(false);
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView().pan).toEqual({ x: 50, y: 20 });
+  });
+
+  // The other half of the rule — a detached origin does cancel — is owned by
+  // pointerSession.test.ts, which exercises it without React in the way.
+  it('keeps panning when capture is lost and the element is still in the document', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    // Chrome releases capture a beat before it delivers pointerup, so ending
+    // here throws away a release that has already been dispatched.
+    dispatchOn(el, 'lostpointercapture', {});
+    expect(result.current.isDragging()).toBe(true);
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView().pan).toEqual({ x: 300, y: 300 });
+  });
+
+  it('reads a move with nothing held as the release that never arrived', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100, { buttons: 1 })));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    expect(getView().pan).toEqual({ x: 50, y: 20 });
+    dispatchOn(document, 'pointermove', { buttons: 0, clientX: 300, clientY: 300 });
+    expect(getView().pan).toEqual({ x: 50, y: 20 });
+    expect(result.current.isDragging()).toBe(false);
+  });
+
+  it('reports a release that never crossed the threshold as a tap', () => {
+    const taps: number[] = [];
+    const { result, el } = dragSetup({ onTap: (e) => taps.push(e.clientX) });
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointerup', { clientX: 101, clientY: 100 });
+    expect(taps).toEqual([101]);
+  });
+
+  it('does not report a tap when the pointer panned', () => {
+    const taps: number[] = [];
+    const { result, el } = dragSetup({ onTap: (e) => taps.push(e.clientX) });
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    dispatchOn(document, 'pointerup', { clientX: 150, clientY: 120 });
+    expect(taps).toEqual([]);
+  });
+
+  it('drops its listeners when the hook unmounts mid-drag', () => {
+    const { result, el, unmount, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    unmount();
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView().pan).toEqual({ x: 0, y: 0 });
+  });
+});

package/src/canvas/usePanZoom.ts

@@ -1,4 +1,11 @@
-import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
+import { openPointerSession, type PointerSession } from '@weasel-js/core';
+import {
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  type WheelEvent,
+} from 'react';
 import type { ViewTransform } from '../instrument/types';
 import { zoomAt } from './camera';
 import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
@@ -14,18 +21,19 @@ export interface UsePanZoomOptions {
    *  wheel anchors in this frame; omitting it anchors at the element's
    *  top-left, which is what labkit did before a frame could be declared. */
   frame?: WorldFrame;
+  /** A primary-button press released without ever crossing the drag
+   *  threshold. The pointer session owns the release, so the gesture's end is
+   *  reported here rather than left for a consumer's own `onPointerUp`. */
+  onTap?: (e: PointerEvent) => void;
 }
 
 export interface PanZoomHandlers {
   onWheel: (e: WheelEvent<HTMLElement>) => void;
-  onPointerDown: (e: PointerEvent<HTMLElement>) => void;
-  onPointerMove: (e: PointerEvent<HTMLElement>) => void;
-  onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+  onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
   isDragging: () => boolean;
 }
 
 interface DragState {
-  pointerId: number;
   startScreenX: number;
   startScreenY: number;
   startPan: { x: number; y: number };
@@ -44,10 +52,16 @@ export function usePanZoom({
   minZoom = 0.1,
   maxZoom = 32,
   frame = DEFAULT_FRAME,
+  onTap,
 }: UsePanZoomOptions): PanZoomHandlers {
   const dragRef = useRef<DragState | null>(null);
+  const sessionRef = useRef<PointerSession | null>(null);
   const viewRef = useRef(view);
   viewRef.current = view;
+  const onViewChangeRef = useRef(onViewChange);
+  onViewChangeRef.current = onViewChange;
+  const onTapRef = useRef(onTap);
+  onTapRef.current = onTap;
   // Captured once, from the view the canvas opened at — not the current view,
   // which would let a prior zoom-out shrink the range and trap the opening
   // view unreachable behind it.
@@ -74,44 +88,48 @@ export function usePanZoom({
     [onViewChange, minZoom, maxZoom, frame],
   );
 
-  const onPointerDown = useCallback((e: PointerEvent<HTMLElement>) => {
-    if (e.button !== 0) return;
-    e.currentTarget.setPointerCapture(e.pointerId);
-    dragRef.current = {
-      pointerId: e.pointerId,
-      startScreenX: e.clientX,
-      startScreenY: e.clientY,
-      startPan: { ...viewRef.current.pan },
-      moved: false,
-    };
+  const clearDrag = useCallback(() => {
+    dragRef.current = null;
+    sessionRef.current = null;
   }, []);
 
-  const onPointerMove = useCallback(
-    (e: PointerEvent<HTMLElement>) => {
-      const drag = dragRef.current;
-      if (!drag || drag.pointerId !== e.pointerId) return;
-      const dx = e.clientX - drag.startScreenX;
-      const dy = e.clientY - drag.startScreenY;
-      if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
-      drag.moved = true;
-      onViewChange({
-        zoom: viewRef.current.zoom,
-        pan: { x: drag.startPan.x + dx, y: drag.startPan.y + dy },
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLElement>) => {
+      if (e.button !== 0) return;
+      const drag: DragState = {
+        startScreenX: e.clientX,
+        startScreenY: e.clientY,
+        startPan: { ...viewRef.current.pan },
+        moved: false,
+      };
+      dragRef.current = drag;
+      sessionRef.current = openPointerSession(e.currentTarget, e, {
+        onMove: (ev) => {
+          const dx = ev.clientX - drag.startScreenX;
+          const dy = ev.clientY - drag.startScreenY;
+          if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+          drag.moved = true;
+          onViewChangeRef.current({
+            zoom: viewRef.current.zoom,
+            pan: { x: drag.startPan.x + dx, y: drag.startPan.y + dy },
+          });
+        },
+        onEnd: (ev) => {
+          const tapped = !drag.moved;
+          clearDrag();
+          if (tapped) onTapRef.current?.(ev);
+        },
+        // A cancelled pan keeps whatever it had already applied: every move
+        // was committed as it arrived, so there is nothing left to undo.
+        onCancel: clearDrag,
       });
     },
-    [onViewChange],
+    [clearDrag],
   );
 
-  const onPointerUp = useCallback((e: PointerEvent<HTMLElement>) => {
-    const drag = dragRef.current;
-    if (!drag || drag.pointerId !== e.pointerId) return;
-    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
-      e.currentTarget.releasePointerCapture(e.pointerId);
-    }
-    dragRef.current = null;
-  }, []);
+  useEffect(() => () => sessionRef.current?.cancel(), []);
 
   const isDragging = useCallback(() => dragRef.current?.moved === true, []);
 
-  return { onWheel, onPointerDown, onPointerMove, onPointerUp, isDragging };
+  return { onWheel, onPointerDown, isDragging };
 }