@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/dist/surface/index.d.ts

@@ -0,0 +1,77 @@
+import * as react from 'react';
+
+/** A box in CSS pixels, measured from the surface's own top-left corner. */
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The subset of `DOMRect` this package reads. Accepting the subset rather than
+ *  `DOMRect` is what lets the pure functions be tested without a DOM. */
+interface Box {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+/** Every tile's box expressed against the container's origin. */
+declare function composeRects(container: Box, tiles: ReadonlyMap<string, Box>): Map<string, Rect>;
+declare function rectsEqual(a: Rect | undefined, b: Rect): boolean;
+
+/**
+ * A DOM rect as a GL viewport rect: origin at the bottom-left, every edge snapped
+ * to the device-pixel grid. Still CSS pixels, because three.js applies its own
+ * pixel ratio — snapping here is what stops a tile and its neighbour rounding
+ * apart and leaving a hairline column between them.
+ */
+declare function toDeviceRect(rect: Rect, surfaceHeight: number, dpr: number): Rect;
+
+/** What a surface owner is handed once per animation frame. `rects` carries every
+ *  tile, not only the dirty ones: a scissored draw has to know where it is drawing
+ *  relative to a surface that may have resized under it. */
+interface SurfaceFrame {
+    dirty: ReadonlySet<string>;
+    rects: ReadonlyMap<string, Rect>;
+    dpr: number;
+    size: {
+        width: number;
+        height: number;
+    };
+}
+/** The invalidators and the two ref callbacks that publish geometry. */
+interface SurfaceHandle {
+    /** Mark one tile for redraw. */
+    invalidate: (id: string) => void;
+    /** Mark every tile — what a resize or a tile-set change means. */
+    invalidateAll: () => void;
+    /** Re-measure before the next frame. The escape hatch for a host that knows it
+     *  moved something a ResizeObserver cannot see. */
+    invalidateRects: () => void;
+    registerTile: (id: string, el: HTMLElement | null) => void;
+    containerRef: (el: HTMLElement | null) => void;
+}
+interface UseTiledSurfaceOptions {
+    onFrame: (frame: SurfaceFrame) => void;
+}
+declare function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHandle;
+
+/** Null when no surface owner is above — a lab with no shared surface at all. */
+declare const SurfaceContext: react.Context<SurfaceHandle | null>;
+
+/** The surface above, or null. Use this where a surface is genuinely optional. */
+declare function useSurfaceOptional(): SurfaceHandle | null;
+/** The surface above. Throws where a caller cannot work without one. */
+declare function useSurface(): SurfaceHandle;
+/**
+ * A ref callback that publishes this element's rect to the surface under `id`.
+ *
+ * Attach it to whichever element the surface should draw into — that is not
+ * necessarily the trial's own element, since a trial may hold a drawn pane beside
+ * an undrawn one, or none at all.
+ */
+declare function useSurfaceTile(id: string): (el: HTMLElement | null) => void;
+
+export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface };
+export type { Box, Rect, SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions };

package/dist/surface/index.js

@@ -0,0 +1,4 @@
+export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-HFDVGF4X.js';
+import '../chunk-Z6HJ5FEM.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/surface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/ui/layers/index.js

@@ -1,5 +1,6 @@
-export { LayerStack } from '../../chunk-NRKWVTVT.js';
-import '../../chunk-C6GJKPUI.js';
-import '../../chunk-DJLDIRFN.js';
+export { LayerStack } from '../../chunk-O2BULFHX.js';
+import '../../chunk-TLGRYALP.js';
+import '../../chunk-Z6HJ5FEM.js';
+import '../../chunk-PQJ5B2U2.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,6 +1,9 @@
-export { U as UndoCapability } from '../_dts/index-iAP6XbH3.js';
+export { U as UndoCapability } from '../_dts/index-DgcNdEdh.js';
 import 'react';
-import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-AHlQxBNN.js';
+import '../_dts/PrefsForm-BYa6cWnO.js';
+import '../_dts/types-1Sdxy_Pv.js';
+import '../_dts/types-DJ79Tg5J.js';
 
 /** A subscriber to a named event. */
 type EventListener = () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.1.0",
+  "version": "1.3.0-pre.0",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -14,6 +14,9 @@
     "url": "https://github.com/orochi235/weasel/issues"
   },
   "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -27,6 +30,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./chrome": {
+      "types": "./dist/chrome/index.d.ts",
+      "import": "./dist/chrome/index.js"
+    },
     "./primitives": {
       "types": "./dist/primitives/index.d.ts",
       "import": "./dist/primitives/index.js"
@@ -55,6 +62,14 @@
       "types": "./dist/state/index.d.ts",
       "import": "./dist/state/index.js"
     },
+    "./surface": {
+      "types": "./dist/surface/index.d.ts",
+      "import": "./dist/surface/index.js"
+    },
+    "./job": {
+      "types": "./dist/job/index.d.ts",
+      "import": "./dist/job/index.js"
+    },
     "./weasel-ui": {
       "types": "./dist/passthrough/weasel-ui.d.ts",
       "import": "./dist/passthrough/weasel-ui.js"
@@ -81,31 +96,33 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:smoke:consumer": "node scripts/smoke-consumer-bundle.mjs",
-    "lint": "biome check . && tsx scripts/check-class-prefix.ts",
+    "lint": "biome check . && tsx scripts/check-class-prefix.ts && tsx scripts/check-design-tokens.ts",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "dev:schema": "LABKIT_EXAMPLE=schema-lab vite"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/theme": "*",
+    "@weasel-js/core": "1.3.0-pre.0",
+    "@weasel-js/theme": "1.3.0-pre.0",
+    "@weasel-js/ui": "1.3.0-pre.0",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
-    "windease": "^1.2.1",
+    "windease": "^1.3.0",
     "zustand": "^5.0.12"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "*",
-    "@weasel-js/ui": "*",
+    "@weasel-js/modes": "1.3.0-pre.0",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/canvas/AGENTS.md

@@ -2,6 +2,14 @@
 
 The `src/canvas/` directory implements the layered canvas primitive used by the `canvas` instrument capability.
 
+For a renderer labkit does not own — three.js, raw WebGL, anything with its own
+render loop — see `src/surface/AGENTS.md` instead. `CanvasStack` is 2D and
+schedules its own layers; a foreign renderer wants rects and dirtiness only.
+
+`useOrbit` also lives here, as the 3D peer of `usePanZoom`. It produces a trial
+view (`{ yaw, pitch, distance, target }`) rather than a matrix — turning that
+into a camera is the host's job.
+
 ## Files
 
 | File | Role |
@@ -20,6 +28,8 @@ interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];      // { id, visible, render(ctx, view) }
   view: ViewTransform;                  // { zoom, pan: { x, y } }
   onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;                     // default 0.1, forwarded to usePanZoom
+  maxZoom?: number;                     // default 32, forwarded to usePanZoom
   width?: number | string;              // default '100%'
   height?: number | string;             // default '100%'
   className?: string;
@@ -71,6 +81,8 @@ Both are pure. Pan is applied in screen space; zoom multiplies world coordinates
 
 Implemented in `usePanZoom`. Mouse-wheel zoom is anchored at the cursor; primary-button drag pans. `isDragging()` is exposed so consumers can suppress click handlers during a pan.
 
+Zoom is clamped to `[minZoom, maxZoom]` (defaults 0.1 / 32), settable via `CanvasStack`'s props and, for an instrument's own canvas, `CanvasCapability.minZoom` / `maxZoom`. The clamp always widens to admit whatever zoom the canvas opened at — an instrument declaring `initialView.zoom: 1600` with the default range is not clamped down to 32 on the first wheel event.
+
 ## Testing notes
 
 JSDOM does not provide a real `CanvasRenderingContext2D`. Tests in `CanvasStack.test.tsx` rely on the scheduler's defensive checks; they do not assert pixels. For pixel testing, use Storybook's `chromatic` or visual snapshots in a real browser.

package/src/canvas/CanvasStack.tsx

@@ -10,6 +10,8 @@ export interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];
   view: ViewTransform;
   onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;
+  maxZoom?: number;
   width?: number | string;
   height?: number | string;
   className?: string;
@@ -24,6 +26,8 @@ export function CanvasStack({
   layers,
   view,
   onViewChange,
+  minZoom,
+  maxZoom,
   width = '100%',
   height = '100%',
   className,
@@ -59,8 +63,8 @@ export function CanvasStack({
     return () => ro.disconnect();
   }, []);
 
-  const handlers = usePanZoom({ view, onViewChange });
-  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size });
+  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom });
+  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(() => ({ view }), [view]);
 

package/src/canvas/useLayerScheduler.ts

@@ -1,3 +1,4 @@
+import { useVisibleRaf } from '@weasel-js/core';
 import { type RefObject, useEffect, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
 
@@ -14,11 +15,19 @@ interface SchedulerOptions {
   view: ViewTransform;
   canvasRefs: RefObject<Map<string, HTMLCanvasElement>>;
   size: { width: number; height: number; dpr: number };
+  /** The element the stack occupies. Given one, the scheduler also stops while
+   *  the stack sits outside the viewport. */
+  host?: RefObject<Element | null>;
 }
 
-export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerOptions): void {
+export function useLayerScheduler({
+  layers,
+  view,
+  canvasRefs,
+  size,
+  host,
+}: SchedulerOptions): void {
   const dirty = useRef<Set<string>>(new Set());
-  const rafId = useRef<number | null>(null);
   const lastRenderRef = useRef<Map<string, CanvasLayerDescriptor['render']>>(new Map());
 
   useEffect(() => {
@@ -37,9 +46,11 @@ export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerO
     for (const layer of layers) dirty.current.add(layer.id);
   }, [view, size, layers]);
 
-  useEffect(() => {
-    const tick = () => {
-      rafId.current = null;
+  // Painting only what is dirty is not the same as doing nothing: a hidden tab
+  // still commits React updates, and the effect above marks every layer dirty
+  // on any view or size change. The gate is what actually stops the work.
+  const frameLoop = useVisibleRaf(
+    () => {
       if (dirty.current.size === 0) return;
       const map = canvasRefs.current;
       if (!map) {
@@ -60,15 +71,11 @@ export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerO
         ctx.restore();
       }
       dirty.current.clear();
-    };
-    if (dirty.current.size > 0 && rafId.current === null) {
-      rafId.current = requestAnimationFrame(tick);
-    }
-    return () => {
-      if (rafId.current !== null) {
-        cancelAnimationFrame(rafId.current);
-        rafId.current = null;
-      }
-    };
+    },
+    { target: host },
+  );
+
+  useEffect(() => {
+    if (dirty.current.size > 0) frameLoop.request();
   });
 }

package/src/canvas/useOrbit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { clampPitch, orbitAfterDrag, orbitAfterWheel, PITCH_LIMIT, wrapYaw } from './useOrbit';
+
+const view = { yaw: 0, pitch: 0, distance: 5, target: { x: 0, y: 0, z: 0 } };
+
+describe('clampPitch', () => {
+  it('stops just short of the poles, where azimuth becomes undefined', () => {
+    expect(clampPitch(Math.PI)).toBeCloseTo(PITCH_LIMIT);
+    expect(clampPitch(-Math.PI)).toBeCloseTo(-PITCH_LIMIT);
+    expect(PITCH_LIMIT).toBeLessThan(Math.PI / 2);
+  });
+
+  it('leaves an in-range pitch alone', () => {
+    expect(clampPitch(0.3)).toBe(0.3);
+  });
+});
+
+describe('wrapYaw', () => {
+  it('wraps into (-PI, PI] so a value cannot drift without bound', () => {
+    expect(wrapYaw(3 * Math.PI)).toBeCloseTo(Math.PI);
+    expect(wrapYaw(-3 * Math.PI)).toBeCloseTo(Math.PI);
+    expect(wrapYaw(0.5)).toBeCloseTo(0.5);
+  });
+
+  it('keeps a full turn equivalent to no turn', () => {
+    expect(wrapYaw(2 * Math.PI)).toBeCloseTo(0);
+  });
+});
+
+describe('orbitAfterDrag', () => {
+  it('turns horizontal movement into yaw and vertical into pitch', () => {
+    const next = orbitAfterDrag(view, 100, 50);
+    expect(next.yaw).not.toBe(view.yaw);
+    expect(next.pitch).not.toBe(view.pitch);
+  });
+
+  it('is absolute against the drag start, so re-applying does not compound', () => {
+    const once = orbitAfterDrag(view, 100, 50);
+    const twice = orbitAfterDrag(view, 100, 50);
+    expect(twice).toEqual(once);
+  });
+
+  it('clamps pitch rather than tumbling past the pole', () => {
+    const next = orbitAfterDrag(view, 0, 100_000);
+    expect(Math.abs(next.pitch)).toBeLessThanOrEqual(PITCH_LIMIT);
+  });
+
+  it('leaves distance and target untouched', () => {
+    const next = orbitAfterDrag(view, 100, 50);
+    expect(next.distance).toBe(view.distance);
+    expect(next.target).toEqual(view.target);
+  });
+});
+
+describe('orbitAfterWheel', () => {
+  it('moves the camera in and out', () => {
+    expect(orbitAfterWheel(view, 100, 0.5, 50).distance).toBeGreaterThan(view.distance);
+    expect(orbitAfterWheel(view, -100, 0.5, 50).distance).toBeLessThan(view.distance);
+  });
+
+  it('is multiplicative, so a step feels the same at every distance', () => {
+    const near = orbitAfterWheel({ ...view, distance: 2 }, 100, 0.5, 50);
+    const far = orbitAfterWheel({ ...view, distance: 20 }, 100, 0.5, 50);
+    expect(far.distance / 20).toBeCloseTo(near.distance / 2);
+  });
+
+  it('honours its bounds', () => {
+    expect(orbitAfterWheel(view, 100_000, 0.5, 50).distance).toBe(50);
+    expect(orbitAfterWheel(view, -100_000, 0.5, 50).distance).toBe(0.5);
+  });
+});

package/src/canvas/useOrbit.ts

@@ -0,0 +1,149 @@
+import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
+
+/** A point in the space the instrument works in. */
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** An orbit camera as a trial view: where it looks from, and what it looks at.
+ *  labkit does not turn this into a matrix — the host's renderer does. */
+export interface OrbitView {
+  yaw: number;
+  pitch: number;
+  distance: number;
+  target: Vec3;
+}
+
+/** Just short of the pole. At exactly ±PI/2 the azimuth is undefined and the
+ *  camera rolls, which reads as the model jumping rather than as a limit. */
+export const PITCH_LIMIT = Math.PI / 2 - 0.01;
+
+const YAW_PER_PX = 0.008;
+const PITCH_PER_PX = 0.008;
+const DISTANCE_PER_NOTCH = 0.0015;
+const DRAG_THRESHOLD = 3;
+
+export function clampPitch(pitch: number): number {
+  return Math.min(PITCH_LIMIT, Math.max(-PITCH_LIMIT, pitch));
+}
+
+export function wrapYaw(yaw: number): number {
+  const wrapped = ((((yaw + Math.PI) % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI)) - Math.PI;
+  return wrapped === -Math.PI ? Math.PI : wrapped;
+}
+
+/** The view a drag of (dx, dy) from `start` produces. Absolute against the drag
+ *  start, so it can be re-applied any number of times without compounding. */
+export function orbitAfterDrag(start: OrbitView, dx: number, dy: number): OrbitView {
+  return {
+    ...start,
+    yaw: wrapYaw(start.yaw + dx * YAW_PER_PX),
+    pitch: clampPitch(start.pitch + dy * PITCH_PER_PX),
+  };
+}
+
+/** Multiplicative, so one notch covers the same proportion of the distance
+ *  whether the camera is near or far. */
+export function orbitAfterWheel(
+  view: OrbitView,
+  deltaY: number,
+  minDistance: number,
+  maxDistance: number,
+): OrbitView {
+  const factor = Math.exp(deltaY * DISTANCE_PER_NOTCH);
+  return {
+    ...view,
+    distance: Math.min(maxDistance, Math.max(minDistance, view.distance * factor)),
+  };
+}
+
+export interface UseOrbitOptions {
+  view: OrbitView;
+  onViewChange: (v: OrbitView) => void;
+  /** Restored on double-click. Defaults to the view the hook first saw. */
+  home?: OrbitView;
+  minDistance?: number;
+  maxDistance?: number;
+}
+
+export interface OrbitHandlers {
+  onWheel: (e: WheelEvent<HTMLElement>) => void;
+  onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+  onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+  onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+  onDoubleClick: () => void;
+  isDragging: () => boolean;
+}
+
+interface DragState {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  startView: OrbitView;
+  moved: boolean;
+}
+
+/** Pointer gestures over an orbit view: drag to turn, wheel or pinch to dolly,
+ *  double-click to go home. The 3D peer of `usePanZoom`. */
+export function useOrbit({
+  view,
+  onViewChange,
+  home,
+  minDistance = 0.1,
+  maxDistance = 1000,
+}: UseOrbitOptions): OrbitHandlers {
+  const dragRef = useRef<DragState | null>(null);
+  const viewRef = useRef(view);
+  viewRef.current = view;
+  const homeRef = useRef(home ?? view);
+  if (home) homeRef.current = home;
+
+  const onWheel = useCallback(
+    (e: WheelEvent<HTMLElement>) => {
+      e.preventDefault();
+      onViewChange(orbitAfterWheel(viewRef.current, e.deltaY, minDistance, maxDistance));
+    },
+    [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 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));
+    },
+    [onViewChange],
+  );
+
+  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;
+  }, []);
+
+  const onDoubleClick = useCallback(() => onViewChange(homeRef.current), [onViewChange]);
+  const isDragging = useCallback(() => dragRef.current?.moved === true, []);
+
+  return { onWheel, onPointerDown, onPointerMove, onPointerUp, onDoubleClick, isDragging };
+}

package/src/canvas/usePanZoom.test.ts

@@ -0,0 +1,80 @@
+import { act, renderHook } from '@testing-library/react';
+import type { WheelEvent } from 'react';
+import { describe, expect, it } from 'vitest';
+import type { ViewTransform } from '../instrument/types';
+import { type UsePanZoomOptions, usePanZoom } from './usePanZoom';
+
+function wheelEvent(deltaY: number): WheelEvent<HTMLElement> {
+  return {
+    deltaY,
+    clientX: 0,
+    clientY: 0,
+    preventDefault: () => {},
+    currentTarget: { getBoundingClientRect: () => ({ left: 0, top: 0, width: 0, height: 0 }) },
+  } as unknown as WheelEvent<HTMLElement>;
+}
+
+/** Renders the hook the way `CanvasStack` drives it: `view` lives in the
+ *  test, `onViewChange` writes it, and each wheel call re-renders the hook
+ *  with the updated view before returning it. */
+function setup(initialView: ViewTransform, options?: Partial<UsePanZoomOptions>) {
+  let view = initialView;
+  const onViewChange = (v: ViewTransform) => {
+    view = v;
+  };
+  const { result, rerender } = renderHook(
+    (props: { view: ViewTransform }) => usePanZoom({ ...options, view: props.view, onViewChange }),
+    { initialProps: { view: initialView } },
+  );
+  const wheel = (deltaY: number): ViewTransform => {
+    act(() => result.current.onWheel(wheelEvent(deltaY)));
+    rerender({ view });
+    return view;
+  };
+  return { wheel, getView: () => view };
+}
+
+describe('usePanZoom', () => {
+  it('does not collapse a canvas opening far outside the default range on the first wheel event', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } });
+    const next = wheel(-1); // zoom in slightly
+    expect(next.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('keeps the opening zoom reachable after zooming away from it', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } });
+    // Zoom far out.
+    for (let i = 0; i < 20; i++) wheel(1000);
+    const zoomedOut = wheel(1000);
+    expect(zoomedOut.zoom).toBeLessThan(1600);
+    // Zoom back in — the opening view must still be reachable.
+    for (let i = 0; i < 40; i++) wheel(-1000);
+    const zoomedIn = wheel(-1000);
+    expect(zoomedIn.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('admits the opening zoom even when an explicit maxZoom is lower than it', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } }, { maxZoom: 32 });
+    const next = wheel(-1);
+    expect(next.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('falls back to the plain defaults when the opening zoom is non-finite or zero', () => {
+    const nanCase = setup({ zoom: Number.NaN, pan: { x: 0, y: 0 } });
+    const nanResult = nanCase.wheel(-100000);
+    expect(nanResult.zoom).toBeCloseTo(32, 5);
+    expect(Number.isNaN(nanResult.zoom)).toBe(false);
+
+    const zeroCase = setup({ zoom: 0, pan: { x: 0, y: 0 } });
+    const zeroResult = zeroCase.wheel(100000);
+    expect(zeroResult.zoom).toBeCloseTo(0.1, 5);
+  });
+
+  it('still clamps ordinary views to the default range', () => {
+    const { wheel } = setup({ zoom: 1, pan: { x: 0, y: 0 } });
+    const zoomedIn = wheel(-1_000_000);
+    expect(zoomedIn.zoom).toBeCloseTo(32, 5);
+    const zoomedOut = wheel(1_000_000);
+    expect(zoomedOut.zoom).toBeCloseTo(0.1, 5);
+  });
+});

package/src/canvas/usePanZoom.ts

@@ -4,6 +4,8 @@ import type { ViewTransform } from '../instrument/types';
 export interface UsePanZoomOptions {
   view: ViewTransform;
   onViewChange: (v: ViewTransform) => void;
+  /** The opening `view.zoom` always stays reachable, widening these past
+   *  whatever is passed here if it would otherwise exclude it. */
   minZoom?: number;
   maxZoom?: number;
 }
@@ -26,6 +28,10 @@ interface DragState {
 
 const DRAG_THRESHOLD = 3;
 
+function isPositiveFinite(n: number): boolean {
+  return Number.isFinite(n) && n > 0;
+}
+
 export function usePanZoom({
   view,
   onViewChange,
@@ -35,6 +41,10 @@ export function usePanZoom({
   const dragRef = useRef<DragState | null>(null);
   const viewRef = useRef(view);
   viewRef.current = view;
+  // 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.
+  const initialZoomRef = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
 
   const onWheel = useCallback(
     (e: WheelEvent<HTMLElement>) => {
@@ -43,9 +53,13 @@ export function usePanZoom({
       const cursorX = e.clientX - rect.left;
       const cursorY = e.clientY - rect.top;
       const v = viewRef.current;
+      const initialZoom = initialZoomRef.current;
+      const effectiveMin = initialZoom == null ? minZoom : Math.min(minZoom, initialZoom);
+      const effectiveMax = initialZoom == null ? maxZoom : Math.max(maxZoom, initialZoom);
       const factor = Math.exp(-e.deltaY * 0.001);
-      const nextZoom = Math.min(maxZoom, Math.max(minZoom, v.zoom * factor));
-      const ratio = nextZoom / v.zoom;
+      const rawZoom = isPositiveFinite(v.zoom) ? v.zoom : 1;
+      const nextZoom = Math.min(effectiveMax, Math.max(effectiveMin, rawZoom * factor));
+      const ratio = nextZoom / rawZoom;
       const nextPan = {
         x: cursorX - (cursorX - v.pan.x) * ratio,
         y: cursorY - (cursorY - v.pan.y) * ratio,