@weasel-js/labkit 1.6.0 → 1.6.1

package/src/canvas/CameraInput.tsx

@@ -0,0 +1,311 @@
+/**
+ * A labkit camera driven by weasel's dispatcher: drag pans, the wheel zooms
+ * about the pointer, a tap reports the world point, and the pointer is
+ * published into the store in scope. What `usePanZoom` used to hand-roll.
+ */
+import {
+  type Action,
+  ActionsProvider,
+  type ActionsRegistry,
+  ActiveToolContextProvider,
+  DepRegistryProvider,
+  makeViewportZoomAction,
+  PointerContextProvider,
+  type PointerWorldPos,
+  type Tool,
+  useActionsRegistry,
+  useDepSource,
+  useGestureDispatcher,
+  usePointerContext,
+  type View,
+  type ViewApi,
+  viewportDragPanAction,
+} from '@weasel-js/core';
+import {
+  createContext,
+  type ReactNode,
+  type RefObject,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import type { Point, ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
+import { CameraWheelContext } from './CameraWheelContext';
+import { clampZoomAbout, frameLocalToWorld, fromCameraView, toCameraView } from './cameraView';
+import type { ViewportSize, WorldFrame } from './worldSpec';
+
+/** The view id the stage publishes its pointer under. */
+export const STAGE_VIEW_ID = 'stage';
+
+/**
+ * A camera, as the things that sit beside it read it: an overview, a loupe, a
+ * linked cursor. Points are *frame-local* — the world with `y` multiplied by
+ * `frame.yDir` — which is the space `view` works in.
+ */
+export interface CameraContextValue {
+  /** The camera as a weasel `ViewApi`, clamped to its zoom range. */
+  view: ViewApi;
+  frame: WorldFrame;
+  /** The element the camera's dispatcher listens on. */
+  element: () => HTMLElement | null;
+  /** The content's own rect, frame-local, when it has one — a `<Stage>`'s. */
+  content?: { x: number; y: number; width: number; height: number };
+}
+
+/** The camera around the caller, or `null` outside one. */
+export const CameraContext = createContext<CameraContextValue | null>(null);
+
+/** Set by a host that already provides one input scope for everything inside
+ *  it — a trial — so the camera, the loupe and an overview share it. */
+export const CameraScopeContext = createContext(false);
+
+/**
+ * The actions and deps a camera routes through: the ones a trial provides, or
+ * an isolated set of its own. Isolated, because an actions registry holds one
+ * dispatcher, and a camera must not take input from a canvas beside it. The
+ * pointer store is the exception — one already in scope is kept, since sharing
+ * it is the point.
+ */
+export function CameraScope({ children }: { children: ReactNode }) {
+  const inScope = useContext(CameraScopeContext);
+  const pointer = usePointerContext();
+  if (inScope) return <>{children}</>;
+  const scoped = <CameraScopeContext.Provider value={true}>{children}</CameraScopeContext.Provider>;
+  return (
+    <DepRegistryProvider>
+      <ActionsProvider>
+        <ActiveToolContextProvider>
+          {pointer ? scoped : <PointerContextProvider>{scoped}</PointerContextProvider>}
+        </ActiveToolContextProvider>
+      </ActionsProvider>
+    </DepRegistryProvider>
+  );
+}
+
+/** Options for {@link useCameraView}. */
+export interface CameraViewOptions {
+  view: ViewTransform;
+  onViewChange: (v: ViewTransform) => void;
+  frame: WorldFrame;
+  hostRef: RefObject<HTMLElement | null>;
+  minZoom?: number;
+  maxZoom?: number;
+}
+
+function isPositiveFinite(n: number): boolean {
+  return Number.isFinite(n) && n > 0;
+}
+
+/**
+ * A labkit camera as a stable `ViewApi`. Its zoom range is widened to keep the
+ * opening zoom reachable — captured once, so a zoom-out cannot shrink the
+ * range and strand the opening view behind it.
+ */
+export function useCameraView({
+  view,
+  onViewChange,
+  frame,
+  hostRef,
+  minZoom = 0.1,
+  maxZoom = 32,
+}: CameraViewOptions): ViewApi {
+  const live = useRef({ view: normalize2DView(view), onViewChange, frame });
+  live.current = { view: normalize2DView(view), onViewChange, frame };
+  const initialZoom = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
+  const bounds = useRef({ min: minZoom, max: maxZoom });
+  const opening = initialZoom.current;
+  bounds.current = {
+    min: opening == null ? minZoom : Math.min(minZoom, opening),
+    max: opening == null ? maxZoom : Math.max(maxZoom, opening),
+  };
+
+  return useMemo<ViewApi>(() => {
+    const get = (): View => toCameraView(live.current.view, live.current.frame);
+    return {
+      get,
+      set: (next: View) => {
+        const { min, max } = bounds.current;
+        const clamped = clampZoomAbout(get(), next, min, max);
+        const vt = fromCameraView(clamped, live.current.frame);
+        // Written ahead of the render, so a second event inside one commit
+        // steps from this one.
+        live.current.view = vt;
+        live.current.onViewChange(vt);
+      },
+      hostSize: () => {
+        const r = hostRef.current?.getBoundingClientRect();
+        return r ? { width: r.width, height: r.height } : null;
+      },
+    };
+  }, [hostRef]);
+}
+
+const TAP_ID = 'camera.tap';
+const NO_TOOLS: ReadonlyMap<string, Tool> = new Map();
+const CHANNELS = { contextMenu: false, ingest: false } as const;
+
+/** Props for `<CameraInput>`. */
+export interface CameraInputProps {
+  hostRef: RefObject<HTMLElement | null>;
+  camera: ViewApi;
+  frame: WorldFrame;
+  /** A primary-button press released without crossing the drag threshold, at
+   *  the world point it landed on. */
+  onTap?: (world: Point) => void;
+}
+
+/**
+ * Mounts the dispatcher on `hostRef` and routes the camera's gestures through
+ * it. Render it inside a `<CameraScope>`; with no actions registry in scope it
+ * renders nothing.
+ */
+export function CameraInput(props: CameraInputProps) {
+  const registry = useActionsRegistry();
+  if (!registry) return null;
+  return <CameraDispatch {...props} registry={registry} />;
+}
+
+function CameraDispatch({
+  hostRef,
+  camera,
+  frame,
+  onTap,
+  registry,
+}: CameraInputProps & { registry: ActionsRegistry }) {
+  const frameRef = useRef(frame);
+  frameRef.current = frame;
+  const onTapRef = useRef(onTap);
+  onTapRef.current = onTap;
+
+  useDepSource('view', () => camera);
+  useDepSource('rootView', () => camera);
+
+  const actions = useMemo<Action[]>(() => {
+    // Unclamped here: `camera.set` clamps, to a range widened around the
+    // opening zoom, and anchors the clamp where the wheel was.
+    const zoom = makeViewportZoomAction({
+      wheel: 'plain',
+      min: 1e-9,
+      max: Number.POSITIVE_INFINITY,
+    });
+    // The wheel and the trackpad's two pinch forms only: the zoom keys listen
+    // on the window, and every trial on a page would take them at once.
+    const wheelOnly = (zoom.defaultBinding as { spec: { kind: string } }[]).filter(
+      (b) => b.spec.kind === 'wheel' || b.spec.kind === 'pinch',
+    );
+    const tap: Action = {
+      id: TAP_ID,
+      label: 'Tap the canvas',
+      defaultBinding: { kind: 'click' },
+      invoker: {
+        timing: 'immediate',
+        run: (_deps, params) => {
+          const p = params as { worldX?: number; worldY?: number } | undefined;
+          if (p?.worldX === undefined || p.worldY === undefined) return;
+          onTapRef.current?.(frameLocalToWorld({ x: p.worldX, y: p.worldY }, frameRef.current));
+        },
+      },
+    };
+    return [
+      viewportDragPanAction,
+      { ...zoom, defaultBinding: wheelOnly as Action['defaultBinding'] },
+      tap,
+    ];
+  }, []);
+
+  useEffect(() => {
+    const offs = actions.map((a) => registry.register(a));
+    return () => {
+      for (const off of offs) off();
+    };
+  }, [registry, actions]);
+
+  const clientToWorld = useMemo(
+    () => (cx: number, cy: number) => {
+      const r = hostRef.current?.getBoundingClientRect();
+      const v = camera.get();
+      return {
+        x: (cx - (r?.left ?? 0)) / v.scale.x + v.x,
+        y: (cy - (r?.top ?? 0)) / v.scale.y + v.y,
+      };
+    },
+    [hostRef, camera],
+  );
+
+  useGestureDispatcher({
+    canvasRef: hostRef,
+    actions: registry,
+    toolsById: NO_TOOLS,
+    clientToWorld,
+    channels: CHANNELS,
+  });
+
+  usePublishPointer(hostRef, clientToWorld, frame, STAGE_VIEW_ID);
+
+  // Input that lands outside the camera's element — an annotation target's
+  // box, portalled into the surface — reaches the dispatcher through here.
+  const wheelSlot = useContext(CameraWheelContext);
+  useEffect(() => {
+    if (!wheelSlot) return;
+    const forward = (e: WheelEvent): void => {
+      hostRef.current?.dispatchEvent(new WheelEvent('wheel', e));
+    };
+    wheelSlot.current = forward;
+    return () => {
+      if (wheelSlot.current === forward) wheelSlot.current = null;
+    };
+  }, [wheelSlot, hostRef]);
+
+  return null;
+}
+
+/**
+ * Publish the pointer over `hostRef` into the store in scope, in the
+ * instrument's world, as `viewId`; clear it when the pointer leaves with no
+ * button held.
+ */
+export function usePublishPointer(
+  hostRef: RefObject<HTMLElement | null>,
+  clientToLocal: (cx: number, cy: number) => Point,
+  frame: WorldFrame,
+  viewId: string,
+): void {
+  const store = usePointerContext();
+  const frameRef = useRef(frame);
+  frameRef.current = frame;
+  const toLocal = useRef(clientToLocal);
+  toLocal.current = clientToLocal;
+  useEffect(() => {
+    const el = hostRef.current;
+    if (!el || !store) return;
+    const onMove = (e: PointerEvent): void => {
+      const w = frameLocalToWorld(toLocal.current(e.clientX, e.clientY), frameRef.current);
+      store.set({ worldX: w.x, worldY: w.y, viewId });
+    };
+    const onLeave = (e: PointerEvent): void => {
+      if (e.buttons !== 0) return;
+      if (store.get()?.viewId === viewId) store.set(null);
+    };
+    el.addEventListener('pointermove', onMove);
+    el.addEventListener('pointerleave', onLeave);
+    return () => {
+      el.removeEventListener('pointermove', onMove);
+      el.removeEventListener('pointerleave', onLeave);
+    };
+  }, [hostRef, store, viewId]);
+}
+
+/** The pointer as a frame-local point, or `null` when there is none or it is
+ *  over `viewId` itself. */
+export function pointerElsewhere(
+  p: PointerWorldPos,
+  viewId: string,
+  frame: WorldFrame,
+): Point | null {
+  if (!p || p.viewId === viewId) return null;
+  return frameLocalToWorld({ x: p.worldX, y: p.worldY }, frame);
+}
+
+export type { ViewportSize };

package/src/canvas/CanvasStack.tsx

@@ -1,19 +1,10 @@
-import {
-  type CSSProperties,
-  type ReactNode,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 import type { Point, ViewTransform } from '../instrument/types';
 import { normalize2DView } from '../state/view';
-import { CameraWheelContext } from './CameraWheelContext';
+import { CameraContext, CameraInput, CameraScope, useCameraView } from './CameraInput';
 import { CanvasStackContext } from './CanvasStackContext';
-import { screenToWorld } from './canvasCoords';
+import { LinkedCursor } from './LinkedCursor';
 import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
-import { usePanZoom } from './usePanZoom';
 import { resolveFrame, type ViewportSize, type WorldSpec } from './worldSpec';
 
 /** Props for `<CanvasStack>`. */
@@ -38,7 +29,8 @@ export interface CanvasStackProps {
 
 /** Stacks one `<canvas>` per layer and drives them from a shared view, so a
  *  layer that changes rarely is not redrawn with one that changes every frame.
- *  Handles sizing, device pixel ratio, and pan/zoom. */
+ *  Handles sizing and device pixel ratio; pan and zoom route through weasel's
+ *  gesture dispatcher (`<CameraInput>`). */
 export function CanvasStack({
   layers,
   view: viewProp,
@@ -92,31 +84,18 @@ export function CanvasStack({
 
   const frame = useMemo(() => resolveFrame(worldSpec, size), [worldSpec, size]);
 
-  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: viewProp, onViewChange, minZoom, maxZoom, frame, onTap });
-  const onWheelRef = useRef(handlers.onWheel);
-  onWheelRef.current = handlers.onWheel;
-  const wheelSlot = useContext(CameraWheelContext);
-
-  // Bound by hand because React registers wheel listeners passive, where
-  // `preventDefault` is refused and the page scrolls under the zoom.
-  useEffect(() => {
-    const el = containerRef.current;
-    if (!el) return;
-    const wheel = (e: WheelEvent): void => onWheelRef.current(e, el);
-    el.addEventListener('wheel', wheel, { passive: false });
-    if (wheelSlot) wheelSlot.current = wheel;
-    return () => {
-      el.removeEventListener('wheel', wheel);
-      if (wheelSlot?.current === wheel) wheelSlot.current = null;
-    };
-  }, [wheelSlot]);
+  const camera = useCameraView({
+    view: viewProp,
+    onViewChange,
+    frame,
+    hostRef: containerRef,
+    minZoom,
+    maxZoom,
+  });
+  const cameraCtx = useMemo(
+    () => ({ view: camera, frame, element: () => containerRef.current }),
+    [camera, frame],
+  );
   useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(
@@ -139,25 +118,30 @@ export function CanvasStack({
   };
 
   return (
-    <CanvasStackContext.Provider value={ctxValue}>
-      <div
-        ref={containerRef}
-        className={className ? `lk-canvas-stack ${className}` : 'lk-canvas-stack'}
-        style={containerStyle}
-        onPointerDown={handlers.onPointerDown}
-      >
-        {layers.map((layer) => (
-          <canvas
-            key={layer.id}
-            ref={(el) => setCanvasRef(layer.id, el)}
-            className="lk-canvas-stack__canvas"
-            width={canvasPx.width}
-            height={canvasPx.height}
-            style={{ ...canvasCss, display: layer.visible ? 'block' : 'none' }}
-          />
-        ))}
-        <div className="lk-canvas-stack__overlay">{children}</div>
-      </div>
-    </CanvasStackContext.Provider>
+    <CameraScope>
+      <CameraContext.Provider value={cameraCtx}>
+        <CanvasStackContext.Provider value={ctxValue}>
+          <CameraInput hostRef={containerRef} camera={camera} frame={frame} onTap={onHitTest} />
+          <div
+            ref={containerRef}
+            className={className ? `lk-canvas-stack ${className}` : 'lk-canvas-stack'}
+            style={containerStyle}
+          >
+            {layers.map((layer) => (
+              <canvas
+                key={layer.id}
+                ref={(el) => setCanvasRef(layer.id, el)}
+                className="lk-canvas-stack__canvas"
+                width={canvasPx.width}
+                height={canvasPx.height}
+                style={{ ...canvasCss, display: layer.visible ? 'block' : 'none' }}
+              />
+            ))}
+            <LinkedCursor />
+            <div className="lk-canvas-stack__overlay">{children}</div>
+          </div>
+        </CanvasStackContext.Provider>
+      </CameraContext.Provider>
+    </CameraScope>
   );
 }

package/src/canvas/LinkedCursor.less

@@ -0,0 +1,16 @@
+.lk-linked-cursor {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  pointer-events: none;
+}
+
+.lk-linked-cursor__halo {
+  fill: rgb(0 0 0 / 60%);
+}
+
+.lk-linked-cursor__bar {
+  fill: var(--wzl-accent, #4c8dff);
+}

package/src/canvas/LinkedCursor.tsx

@@ -0,0 +1,54 @@
+import { crosshairRects, usePointerPosition } from '@weasel-js/core';
+import { useContext } from 'react';
+import { CameraContext, pointerElsewhere, STAGE_VIEW_ID } from './CameraInput';
+
+/** `crosshairRects` returns its four arms in this order. */
+const ARMS = ['left', 'right', 'up', 'down'] as const;
+
+/**
+ * The other side of a linked cursor: a crosshair on the camera's own element
+ * wherever the shared pointer is over some other view — an overview, say. The
+ * same crosshair core paints on a weasel canvas.
+ */
+export function LinkedCursor() {
+  const camera = useContext(CameraContext);
+  const pointer = usePointerPosition();
+  if (!camera) return null;
+  const local = pointerElsewhere(pointer, STAGE_VIEW_ID, camera.frame);
+  if (!local) return null;
+  // `pointerElsewhere` hands back the instrument's world; the camera works
+  // frame-local, and the map is its own inverse.
+  const v = camera.view.get();
+  const x = (local.x - v.x) * v.scale.x;
+  const y = (local.y * camera.frame.yDir - v.y) * v.scale.y;
+  const { halo, bars } = crosshairRects(x, y, 1);
+  const arms = ARMS.map((name, i) => ({ name, halo: halo[i], bar: bars[i] }));
+  return (
+    <svg className="lk-linked-cursor" aria-hidden="true">
+      {arms.map(({ name, halo: r }) =>
+        r ? (
+          <rect
+            key={`halo-${name}`}
+            className="lk-linked-cursor__halo"
+            x={r.x}
+            y={r.y}
+            width={r.w}
+            height={r.h}
+          />
+        ) : null,
+      )}
+      {arms.map(({ name, bar: r }) =>
+        r ? (
+          <rect
+            key={`bar-${name}`}
+            className="lk-linked-cursor__bar"
+            x={r.x}
+            y={r.y}
+            width={r.w}
+            height={r.h}
+          />
+        ) : null,
+      )}
+    </svg>
+  );
+}

package/src/canvas/Stage.tsx

@@ -1,10 +1,10 @@
-import { type CSSProperties, type ReactNode, useContext, useEffect, useRef } from 'react';
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
 import { normalize2DView } from '../state/view';
 import { useSurfaceOptional } from '../surface/useSurfaceTile';
-import { CameraWheelContext } from './CameraWheelContext';
-import { usePanZoom } from './usePanZoom';
-import type { ViewportSize } from './worldSpec';
+import { CameraContext, CameraInput, CameraScope, useCameraView } from './CameraInput';
+import { LinkedCursor } from './LinkedCursor';
+import { DEFAULT_FRAME, type ViewportSize } from './worldSpec';
 
 /** Props for `<Stage>`. */
 export interface StageProps {
@@ -43,7 +43,8 @@ export function fitStage(size: ViewportSize, viewport: ViewportSize): ViewTransf
 
 /**
  * DOM content of a fixed size, panned and zoomed by a camera — what
- * `<CanvasStack>` is for layers drawn to a canvas. The content is laid out at
+ * `<CanvasStack>` is for layers drawn to a canvas. Pan and zoom route through
+ * weasel's gesture dispatcher (`<CameraInput>`). The content is laid out at
  * its own size and transformed, so everything inside keeps its layout and a
  * measurement of any element in it reports where it is actually drawn.
  */
@@ -61,24 +62,23 @@ export function Stage({
   const view = normalize2DView(viewProp);
   const host = useRef<HTMLDivElement | null>(null);
   const surface = useSurfaceOptional();
-  const handlers = usePanZoom({ view: viewProp, onViewChange, minZoom, maxZoom });
-  const onWheelRef = useRef(handlers.onWheel);
-  onWheelRef.current = handlers.onWheel;
-  const wheelSlot = useContext(CameraWheelContext);
-
-  // Bound by hand because React registers wheel listeners passive, where
-  // `preventDefault` is refused and the page scrolls under the zoom.
-  useEffect(() => {
-    const el = host.current;
-    if (!el) return;
-    const wheel = (e: WheelEvent): void => onWheelRef.current(e, el);
-    el.addEventListener('wheel', wheel, { passive: false });
-    if (wheelSlot) wheelSlot.current = wheel;
-    return () => {
-      el.removeEventListener('wheel', wheel);
-      if (wheelSlot?.current === wheel) wheelSlot.current = null;
-    };
-  }, [wheelSlot]);
+  const camera = useCameraView({
+    view: viewProp,
+    onViewChange,
+    frame: DEFAULT_FRAME,
+    hostRef: host,
+    minZoom,
+    maxZoom,
+  });
+  const cameraCtx = useMemo(
+    () => ({
+      view: camera,
+      frame: DEFAULT_FRAME,
+      element: () => host.current,
+      content: { x: 0, y: 0, width: size.width, height: size.height },
+    }),
+    [camera, size.width, size.height],
+  );
 
   const onResizeRef = useRef(onResize);
   onResizeRef.current = onResize;
@@ -108,7 +108,7 @@ export function Stage({
   // The camera changes every frame of a pan, and a transform has nowhere to
   // live but the element's own style: set as custom properties the stylesheet
   // reads.
-  const camera = {
+  const cameraVars = {
     ['--lk-stage-x' as string]: `${view.pan.x}px`,
     ['--lk-stage-y' as string]: `${view.pan.y}px`,
     ['--lk-stage-zoom' as string]: String(view.zoom),
@@ -117,18 +117,23 @@ export function Stage({
   } as CSSProperties;
 
   return (
-    <div
-      ref={(el) => {
-        host.current = el;
-        if (hostRef) hostRef.current = el;
-      }}
-      className="lk-stage"
-      onPointerDown={handlers.onPointerDown}
-    >
-      <div className="lk-stage__content" style={camera}>
-        {children}
-      </div>
-      {overlay}
-    </div>
+    <CameraScope>
+      <CameraContext.Provider value={cameraCtx}>
+        <CameraInput hostRef={host} camera={camera} frame={DEFAULT_FRAME} />
+        <div
+          ref={(el) => {
+            host.current = el;
+            if (hostRef) hostRef.current = el;
+          }}
+          className="lk-stage"
+        >
+          <div className="lk-stage__content" style={cameraVars}>
+            {children}
+          </div>
+          <LinkedCursor />
+          {overlay}
+        </div>
+      </CameraContext.Provider>
+    </CameraScope>
   );
 }

package/src/canvas/cameraView.test.ts

@@ -0,0 +1,60 @@
+import type { View } from '@weasel-js/core';
+import { describe, expect, it } from 'vitest';
+import { clampZoomAbout, frameLocalToWorld, fromCameraView, toCameraView } from './cameraView';
+import { worldToScreen } from './canvasCoords';
+import type { WorldFrame } from './worldSpec';
+
+const UP: WorldFrame = { originPx: { x: 200, y: 150 }, yDir: -1 };
+const vt = { zoom: 2.5, pan: { x: 30, y: -40 } };
+
+/** Where a weasel View puts a frame-local point. */
+const project = (v: View, p: { x: number; y: number }) => ({
+  x: (p.x - v.x) * v.scale.x,
+  y: (p.y - v.y) * v.scale.y,
+});
+
+describe('camera as a weasel View', () => {
+  it.each([
+    ['default frame', undefined],
+    ['moved origin, y up', UP],
+  ] as const)('places every world point where labkit does (%s)', (_, frame) => {
+    const v = toCameraView(vt, frame);
+    for (const w of [
+      { x: 0, y: 0 },
+      { x: 13, y: -7 },
+      { x: -120, y: 44 },
+    ]) {
+      const local = frameLocalToWorld(w, frame);
+      const a = project(v, local);
+      const b = worldToScreen(w, vt, frame);
+      expect(a.x).toBeCloseTo(b.x);
+      expect(a.y).toBeCloseTo(b.y);
+    }
+  });
+
+  it('round-trips', () => {
+    const back = fromCameraView(toCameraView(vt, UP), UP);
+    expect(back.zoom).toBeCloseTo(vt.zoom);
+    expect(back.pan.x).toBeCloseTo(vt.pan.x);
+    expect(back.pan.y).toBeCloseTo(vt.pan.y);
+  });
+});
+
+describe('clampZoomAbout', () => {
+  const prev: View = { x: 0, y: 0, scale: { x: 1, y: 1 } };
+  it('holds the anchor of a zoom that hits the bound', () => {
+    // A 4x zoom about screen (100, 50): world under it stays (100, 50).
+    const next: View = { x: 75, y: 37.5, scale: { x: 4, y: 4 } };
+    const out = clampZoomAbout(prev, next, 0.5, 2);
+    expect(out.scale.x).toBe(2);
+    expect(100 / out.scale.x + out.x).toBeCloseTo(100);
+    expect(50 / out.scale.y + out.y).toBeCloseTo(50);
+  });
+
+  it('passes a zoom inside the bounds and a pan through', () => {
+    const inside: View = { x: 10, y: 5, scale: { x: 1.5, y: 1.5 } };
+    expect(clampZoomAbout(prev, inside, 0.5, 2)).toBe(inside);
+    const pan: View = { x: 10, y: 5, scale: { x: 1, y: 1 } };
+    expect(clampZoomAbout(prev, pan, 0.5, 2)).toBe(pan);
+  });
+});