@weasel-js/labkit 1.4.0-pre.1 → 1.4.1

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,104 @@ 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 });
+  });
+
+  it('ends the drag when capture is lost mid-gesture', () => {
+    const { result, el, getView } = dragSetup();
+    act(() => result.current.onPointerDown(press(el, 100, 100)));
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 150, clientY: 120 });
+    dispatchOn(el, 'lostpointercapture', {});
+    expect(result.current.isDragging()).toBe(false);
+    dispatchOn(document, 'pointermove', { buttons: 1, clientX: 400, clientY: 400 });
+    expect(getView().pan).toEqual({ x: 50, y: 20 });
+  });
+
+  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 };
 }

package/src/config/builder.test.ts

@@ -29,6 +29,11 @@ describe('builder', () => {
     });
   });
 
+  it('annotates a number with a display suffix', () => {
+    const n = f.number(20).suffix('px');
+    expect(n.annotations.suffix).toBe('px');
+  });
+
   it('keeps a custom node kind across a chain', () => {
     const n = f.custom('vector2', { x: 0 }).label('Offset');
     expect(n.kind).toBe('vector2');

package/src/config/builder.ts

@@ -90,6 +90,12 @@ class NumberNode extends BaseNode<number> {
     return this.ann({ step });
   }
 
+  /** A display suffix for the value — `'px'`, `'ms'`, `'°'`. Presentation only:
+   *  it is never parsed, and the stored value stays a plain number. */
+  suffix(suffix: string): this {
+    return this.ann({ suffix });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });

package/src/config/types.ts

@@ -24,6 +24,7 @@ export interface Annotations {
   min?: number;
   max?: number;
   step?: number;
+  suffix?: string;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;

package/src/controls/ControlPanel.test.tsx

@@ -420,3 +420,26 @@ describe('<ControlPanel> packing', () => {
     expect(rowOf('Width')?.className).toMatch(/rowInline/);
   });
 });
+
+describe('<ControlPanel> suffix', () => {
+  const panel = (node: ReturnType<typeof f.number>) =>
+    render(
+      <ControlPanel
+        schema={resolveConfigSchema(f.schema({ width: node.label('Width') }), [])}
+        config={{ width: 20 }}
+        setConfig={vi.fn()}
+      />,
+    );
+
+  it('suffixes a slider readout with the suffix the leaf declares', () => {
+    const { container } = panel(f.number(20).range(0, 100).slider().suffix('px'));
+    expect(container.querySelector('input[type="range"]')).not.toBeNull();
+    expect(container.textContent).toContain('px');
+  });
+
+  it('suffixes a typed number with the suffix the leaf declares', () => {
+    const { container } = panel(f.number(20).input().suffix('px'));
+    expect(container.querySelector('input[type="number"]')).not.toBeNull();
+    expect(container.textContent).toContain('px');
+  });
+});

package/src/controls/ControlPanel.tsx

@@ -159,6 +159,7 @@ function ControlRow<TC extends Record<string, unknown>>({
       const min = extra<number>(leaf, 'min');
       const max = extra<number>(leaf, 'max');
       const step = extra<number>(leaf, 'step');
+      const suffix = extra<string>(leaf, 'suffix');
       if (extra<string>(leaf, 'control') === 'slider' && min !== undefined && max !== undefined) {
         return (
           <SliderRow
@@ -167,6 +168,7 @@ function ControlRow<TC extends Record<string, unknown>>({
             min={min}
             max={max}
             step={step}
+            unit={suffix}
             onChange={write}
             layout={layout}
             span={wide}
@@ -186,6 +188,7 @@ function ControlRow<TC extends Record<string, unknown>>({
           min={min}
           max={max}
           step={step}
+          unit={suffix}
           onChange={(n) => write(Math.min(hi, Math.max(lo, n)))}
           layout={layout}
           description={description}

package/src/job/useJob.ts

@@ -111,7 +111,7 @@ export function useJob<TS, TC, TItem>({
     lastKey.current = key;
     started.current = true;
     start();
-  }, [auto, key, start]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [auto, key, start]);
 
   useEffect(
     () => () => {

package/src/lab/Lab.surface.test.tsx

@@ -12,7 +12,7 @@ import type { ReactNode } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { SurfaceContext } from '../surface/SurfaceContext';
-import { useSurfaceOptional, useSurfaceTile } from '../surface/useSurfaceTile';
+import { useSurfaceOptional, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
 import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { Lab } from './Lab';
@@ -39,9 +39,13 @@ beforeAll(() => {
 });
 
 let seen: SurfaceHandle | null | 'not-rendered' = 'not-rendered';
+/** The key the probe's tile is actually registered under: a tile inside a
+ *  trial is scoped by it, and the trial's id is minted by the store. */
+let paneTileId = 'pane';
 
 function Probe() {
   seen = useSurfaceOptional();
+  paneTileId = useTileId('pane');
   const tile = useSurfaceTile('pane');
   return <div data-testid="pane" ref={tile} />;
 }
@@ -146,7 +150,7 @@ describe('<Lab> tile round trip', () => {
 
     act(() => {
       handle?.invalidateRects();
-      handle?.invalidate('pane');
+      handle?.invalidate(paneTileId);
     });
     act(() => {
       vi.advanceTimersByTime(64);
@@ -156,7 +160,8 @@ describe('<Lab> tile round trip', () => {
     // that passes because nothing ran is the failure mode this arc keeps
     // hitting.
     expect(frames.length).toBeGreaterThan(0);
-    const rect = frames[frames.length - 1]?.rects.get('pane');
+    expect(paneTileId).not.toBe('pane');
+    const rect = frames[frames.length - 1]?.rects.get(paneTileId);
     expect(rect).toEqual({ x: 240, y: 100, w: 320, h: 200 });
   });
 });

package/src/lab/LabHeader.test.tsx

@@ -39,4 +39,16 @@ describe('<LabHeader>', () => {
       expect(screen.getByRole('radio', { name: label })).toBeInTheDocument();
     }
   });
+
+  it('draws each color mode as a glyph, with the word only as its name', () => {
+    // The assertion above passes whether the segment holds text or an icon,
+    // because both routes produce the same accessible name. This is the one
+    // that can tell them apart.
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    for (const label of ['Auto', 'Light', 'Dark']) {
+      const segment = screen.getByRole('radio', { name: label });
+      expect(segment.querySelector('svg')).not.toBeNull();
+      expect(segment).toHaveTextContent('');
+    }
+  });
 });

package/src/lab/LabHeader.tsx

@@ -1,14 +1,22 @@
-import { AddIcon } from '@weasel-js/ui';
+import { AddIcon, ModeAutoIcon, ModeDarkIcon, ModeLightIcon } from '@weasel-js/ui';
 import { Select, ToggleBar } from '../passthrough/weasel-ui';
 import type { LabMode } from '../state/types';
 import { useLabContext } from './LabContext';
 
-const MODES: { value: LabMode; label: string }[] = [
-  { value: 'auto', label: 'Auto' },
-  { value: 'light', label: 'Light' },
-  { value: 'dark', label: 'Dark' },
+// The glyph is the segment's content and the word is its accessible name, so
+// the bar stays a three-way radiogroup announcing Auto / Light / Dark.
+const MODES = [
+  { value: 'auto' as LabMode, label: 'Auto', glyph: <ModeAutoIcon size={14} /> },
+  { value: 'light' as LabMode, label: 'Light', glyph: <ModeLightIcon size={14} /> },
+  { value: 'dark' as LabMode, label: 'Dark', glyph: <ModeDarkIcon size={14} /> },
 ];
 
+const MODE_ITEMS = MODES.map(({ value, label, glyph }) => ({
+  value,
+  label: glyph,
+  ariaLabel: label,
+}));
+
 /** The controls `<Lab>` puts in its header: add a trial, and choose the color
  *  mode. Both drive `LabContext`, which carried them with no UI at all — so
  *  every consumer rebuilt these two. Rendered before a consumer's own header
@@ -46,7 +54,9 @@ export function LabHeader() {
       <ToggleBar
         className="lk-lab-header__mode"
         ariaLabel="Color mode"
-        items={MODES}
+        size="sm"
+        variant="flat"
+        items={MODE_ITEMS}
         value={lab.mode}
         onChange={(next) => {
           if (next) lab.setMode(next);

package/src/lab/Workspace.tsx

@@ -210,7 +210,7 @@ export function Workspace({
     if (!surface) return;
     surface.invalidateRects();
     return store.events.on('node.placementChanged', () => surface.invalidateRects());
-  }, [store, surface, nodeIds]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [store, surface, nodeIds]);
 
   useEffect(() => {
     if (!onLayoutChange) return;

package/src/layers/LayerList.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import type { LayerDescriptor } from '../instrument/types';
 import { LayerList } from './LayerList';
@@ -47,3 +47,74 @@ describe('<LayerList>', () => {
     expect(onToggle).toHaveBeenCalledWith('a', false);
   });
 });
+
+const twoLayers: LayerDescriptor[] = [
+  { id: 'a', label: 'A' },
+  { id: 'b', label: 'B' },
+];
+
+function dispatchOn(target: EventTarget, type: string, init: PointerEventInit) {
+  act(() => {
+    target.dispatchEvent(new PointerEvent(type, { pointerId: 1, bubbles: true, ...init }));
+  });
+}
+
+/** jsdom measures every row at zero height, so `startDrag` falls back to a
+ *  pitch of 1: one pixel of travel is one row. */
+function renderDraggable(onReorder = vi.fn()) {
+  const result = render(
+    <LayerList
+      layers={twoLayers}
+      visibility={{ a: true, b: true }}
+      onReorder={onReorder}
+      onToggle={vi.fn()}
+    />,
+  );
+  return { ...result, onReorder, handle: screen.getByLabelText('Reorder A') };
+}
+
+describe('<LayerList> reordering', () => {
+  it('reorders from a release that lands off the handle', () => {
+    const { onReorder, handle } = renderDraggable();
+    fireEvent.pointerDown(handle, { pointerId: 1, buttons: 1, clientY: 0 });
+    dispatchOn(document, 'pointermove', { buttons: 1, clientY: 1 });
+    dispatchOn(document, 'pointerup', { clientY: 1 });
+    expect(onReorder).toHaveBeenCalledTimes(1);
+    expect(onReorder.mock.calls[0][0].map((l: LayerDescriptor) => l.id)).toEqual(['b', 'a']);
+  });
+
+  it('abandons the reorder when capture is lost mid-drag', () => {
+    const { onReorder, handle, container } = renderDraggable();
+    fireEvent.pointerDown(handle, { pointerId: 1, buttons: 1, clientY: 0 });
+    dispatchOn(document, 'pointermove', { buttons: 1, clientY: 1 });
+    dispatchOn(handle, 'lostpointercapture', {});
+    expect(onReorder).not.toHaveBeenCalled();
+    expect(container.querySelector('.lk-layer-list__row--dragging')).toBeNull();
+  });
+
+  it('reads a move with nothing held as the release that never arrived', () => {
+    const { onReorder, handle } = renderDraggable();
+    fireEvent.pointerDown(handle, { pointerId: 1, buttons: 1, clientY: 0 });
+    dispatchOn(document, 'pointermove', { buttons: 1, clientY: 1 });
+    dispatchOn(document, 'pointermove', { buttons: 0, clientY: 40 });
+    expect(onReorder).toHaveBeenCalledTimes(1);
+    expect(onReorder.mock.calls[0][0].map((l: LayerDescriptor) => l.id)).toEqual(['b', 'a']);
+  });
+
+  it('drops its listeners when the list unmounts mid-drag', () => {
+    const { onReorder, handle, unmount } = renderDraggable();
+    fireEvent.pointerDown(handle, { pointerId: 1, buttons: 1, clientY: 0 });
+    dispatchOn(document, 'pointermove', { buttons: 1, clientY: 1 });
+    unmount();
+    dispatchOn(document, 'pointerup', { clientY: 1 });
+    expect(onReorder).not.toHaveBeenCalled();
+  });
+
+  it('does not capture a second pointer into the same drag', () => {
+    const { onReorder, handle } = renderDraggable();
+    fireEvent.pointerDown(handle, { pointerId: 1, buttons: 1, clientY: 0 });
+    dispatchOn(document, 'pointermove', { pointerId: 2, buttons: 1, clientY: 40 });
+    dispatchOn(document, 'pointerup', { pointerId: 1, clientY: 0 });
+    expect(onReorder).not.toHaveBeenCalled();
+  });
+});

package/src/layers/LayerList.tsx

@@ -1,4 +1,5 @@
-import { type PointerEvent, useRef, useState } from 'react';
+import { openPointerSession, type PointerSession } from '@weasel-js/core';
+import { type PointerEvent as ReactPointerEvent, useEffect, useRef, useState } from 'react';
 import type { LayerDescriptor } from '../instrument/types';
 import { DragHandleGlyph } from '../passthrough/weasel-ui';
 
@@ -12,8 +13,8 @@ export interface LayerListProps {
 }
 
 interface DragState {
-  pointerId: number;
   fromIndex: number;
+  toIndex: number;
   startY: number;
   /** Row height plus row gap, measured when the drag starts. */
   pitch: number;
@@ -26,6 +27,13 @@ export function LayerList({ layers, visibility, onReorder, onToggle, className }
   const pinned = layers.filter((l) => l.alwaysOn);
   const [dragIndex, setDragIndex] = useState<number | null>(null);
   const dragRef = useRef<DragState | null>(null);
+  const sessionRef = useRef<PointerSession | null>(null);
+  // The session's callbacks outlive the render that opened them, so the commit
+  // reads its inputs here rather than from that render's closure.
+  const commitRef = useRef({ reorderable, pinned, onReorder });
+  commitRef.current = { reorderable, pinned, onReorder };
+
+  useEffect(() => () => sessionRef.current?.cancel(), []);
 
   if (layers.length === 0) {
     return (
@@ -35,45 +43,47 @@ export function LayerList({ layers, visibility, onReorder, onToggle, className }
     );
   }
 
-  const startDrag = (e: PointerEvent<HTMLElement>, index: number) => {
-    e.currentTarget.setPointerCapture(e.pointerId);
+  const clearDrag = () => {
+    dragRef.current = null;
+    sessionRef.current = null;
+    setDragIndex(null);
+  };
+
+  const startDrag = (e: ReactPointerEvent<HTMLElement>, index: number) => {
     // Measured at grab time rather than hardcoded: a restyle that changes row
     // height or gap would otherwise silently skew every drag distance.
     const row = e.currentTarget.closest('.lk-layer-list__row');
     const list = row?.parentElement;
     const gap = list ? Number.parseFloat(getComputedStyle(list).rowGap) || 0 : 0;
     const pitch = row ? row.getBoundingClientRect().height + gap : 0;
-    dragRef.current = {
-      pointerId: e.pointerId,
+    const drag: DragState = {
       fromIndex: index,
+      toIndex: index,
       startY: e.clientY,
       pitch: pitch > 0 ? pitch : 1,
     };
+    dragRef.current = drag;
     setDragIndex(index);
-  };
-
-  const moveDrag = (e: PointerEvent<HTMLElement>) => {
-    const drag = dragRef.current;
-    if (!drag || drag.pointerId !== e.pointerId) return;
-    const delta = Math.round((e.clientY - drag.startY) / drag.pitch);
-    const target = Math.min(reorderable.length - 1, Math.max(0, drag.fromIndex + delta));
-    setDragIndex(target);
-  };
-
-  const endDrag = (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);
-    }
-    if (dragIndex !== null && dragIndex !== drag.fromIndex) {
-      const next = [...reorderable];
-      const [moved] = next.splice(drag.fromIndex, 1);
-      if (moved) next.splice(dragIndex, 0, moved);
-      onReorder([...next, ...pinned]);
-    }
-    dragRef.current = null;
-    setDragIndex(null);
+    sessionRef.current = openPointerSession(e.currentTarget, e, {
+      onMove: (ev) => {
+        const delta = Math.round((ev.clientY - drag.startY) / drag.pitch);
+        const last = commitRef.current.reorderable.length - 1;
+        drag.toIndex = Math.min(last, Math.max(0, drag.fromIndex + delta));
+        setDragIndex(drag.toIndex);
+      },
+      onEnd: () => {
+        const { reorderable: rows, pinned: locked, onReorder: commit } = commitRef.current;
+        const { fromIndex, toIndex } = drag;
+        clearDrag();
+        if (toIndex === fromIndex) return;
+        const next = [...rows];
+        const [moved] = next.splice(fromIndex, 1);
+        if (moved) next.splice(toIndex, 0, moved);
+        commit([...next, ...locked]);
+      },
+      // An interrupted drag never named a destination, so it reorders nothing.
+      onCancel: clearDrag,
+    });
   };
 
   return (
@@ -92,8 +102,6 @@ export function LayerList({ layers, visibility, onReorder, onToggle, className }
               className="lk-layer-list__handle"
               aria-label={`Reorder ${layer.label}`}
               onPointerDown={(e) => startDrag(e, i)}
-              onPointerMove={moveDrag}
-              onPointerUp={endDrag}
             >
               <DragHandleGlyph size={13} />
             </button>