@weasel-js/labkit 1.4.4 → 1.5.1

package/src/annotations/types.ts

@@ -29,7 +29,7 @@ export interface AnnotationStatus {
   id: string;
   label: string;
   /** What a mark in this status is drawn in. Omitted, it takes the default
-   *  mark colour — a status is allowed to be a label and nothing more. */
+   *  mark color — a status is allowed to be a label and nothing more. */
   color?: string;
 }
 
@@ -150,9 +150,10 @@ export interface AnnotationTarget extends AnnotationTargetInfo {
 /** Where an instrument keeps its own marks. Declaring this means labkit never
  *  writes its trial slot — for an instrument whose marks belong in a format it
  *  already owns. Both halves are called outside React; `save` is already
- *  debounced by the time it arrives. */
+ *  debounced by the time it arrives. A trial shows an empty body until `load`
+ *  settles. */
 export interface AnnotationStorage {
-  load: () => SerializedAnnotations | null | undefined;
+  load: () => Promise<SerializedAnnotations | null | undefined>;
   save: (doc: SerializedAnnotations) => void;
 }
 
@@ -163,6 +164,8 @@ export interface AnnotationsCapability<TS = unknown, TC = unknown> {
    *  is called once per trial, and its targets are that trial's own. */
   targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
   meaning?: AnnotationMeaning;
+  /** An instrument replacing this one under a live trial must pass the same
+   *  object: the trial keeps the marks it loaded from the first. */
   storage?: AnnotationStorage;
   /** Fires after every finished export, labkit's own chrome included. A
    *  notification, not an interception: a host wanting its own flow calls

package/src/canvas/CameraWheelContext.ts

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+
+/** Where a trial's camera takes a wheel event from outside its own element. */
+export type CameraWheelSlot = { current: ((e: WheelEvent) => void) | null };
+
+/**
+ * The trial's camera, for input that lands outside it. An annotation target's
+ * input box is portalled into the surface container, so a wheel over a mark
+ * never bubbles through the stage or canvas stack it sits on; the box hands
+ * the event here instead.
+ */
+export const CameraWheelContext = createContext<CameraWheelSlot | null>(null);

package/src/canvas/CanvasStack.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { useState } from 'react';
 import { ScaleIndicator } from '../primitives/ScaleIndicator';
 import { CanvasStack } from './CanvasStack';

package/src/canvas/CanvasStack.test.tsx

@@ -106,3 +106,28 @@ describe('<CanvasStack>', () => {
     vi.restoreAllMocks();
   });
 });
+
+describe('<CanvasStack> zoom invariant', () => {
+  it('hit-tests a view that arrived with zoom 0 to a finite world point', () => {
+    const rect = { left: 0, top: 0, width: 800, height: 600, right: 800, bottom: 600 };
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue(
+      rect as unknown as DOMRect,
+    );
+    const onHitTest = vi.fn();
+    const { container } = render(
+      <CanvasStack
+        layers={makeLayers(1)}
+        view={{ zoom: 0, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+        onHitTest={onHitTest}
+      />,
+    );
+    const host = container.querySelector('.lk-canvas-stack');
+    if (!host) throw new Error('no stack host');
+    fireEvent.pointerDown(host, { button: 0, pointerId: 1, clientX: 500, clientY: 200 });
+    fireEvent.pointerUp(host, { pointerId: 1, clientX: 500, clientY: 200 });
+    const world = onHitTest.mock.calls.at(-1)?.[0] as { x: number; y: number };
+    expect(Number.isFinite(world.x) && Number.isFinite(world.y)).toBe(true);
+    vi.restoreAllMocks();
+  });
+});

package/src/canvas/CanvasStack.tsx

@@ -1,5 +1,15 @@
-import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type CSSProperties,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import type { Point, ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
+import { CameraWheelContext } from './CameraWheelContext';
 import { CanvasStackContext } from './CanvasStackContext';
 import { screenToWorld } from './canvasCoords';
 import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
@@ -31,7 +41,7 @@ export interface CanvasStackProps {
  *  Handles sizing, device pixel ratio, and pan/zoom. */
 export function CanvasStack({
   layers,
-  view,
+  view: viewProp,
   onViewChange,
   worldSpec,
   minZoom,
@@ -43,6 +53,7 @@ export function CanvasStack({
   onHitTest,
   children,
 }: CanvasStackProps) {
+  const view = normalize2DView(viewProp);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const canvasMap = useRef<Map<string, HTMLCanvasElement>>(new Map());
   const [size, setSize] = useState({ width: 0, height: 0, dpr: 1 });
@@ -88,7 +99,24 @@ export function CanvasStack({
     onHitTest(screenToWorld({ x: e.clientX - rect.left, y: e.clientY - rect.top }, view, frame));
   };
 
-  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, onTap });
+  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]);
   useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(
@@ -116,7 +144,6 @@ export function CanvasStack({
         ref={containerRef}
         className={className ? `lk-canvas-stack ${className}` : 'lk-canvas-stack'}
         style={containerStyle}
-        onWheel={handlers.onWheel}
         onPointerDown={handlers.onPointerDown}
       >
         {layers.map((layer) => (

package/src/canvas/Stage.less

@@ -0,0 +1,18 @@
+.lk-stage {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: var(--wzl-surface-sunken);
+  touch-action: none;
+}
+
+.lk-stage__content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--lk-stage-w);
+  height: var(--lk-stage-h);
+  transform-origin: 0 0;
+  transform: translate(var(--lk-stage-x), var(--lk-stage-y)) scale(var(--lk-stage-zoom));
+}

package/src/canvas/Stage.test.tsx

@@ -0,0 +1,186 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { ViewTransform } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
+import { CameraWheelContext, type CameraWheelSlot } from './CameraWheelContext';
+import { fitStage, Stage } from './Stage';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function content(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('.lk-stage__content');
+  if (!el) throw new Error('no stage content');
+  return el;
+}
+
+const zoomOf = (el: HTMLElement): number => Number(el.style.getPropertyValue('--lk-stage-zoom'));
+
+describe('fitStage', () => {
+  it('shrinks content that does not fit, and centers it on the short axis', () => {
+    expect(fitStage({ width: 400, height: 200 }, { width: 200, height: 200 })).toEqual({
+      zoom: 0.5,
+      pan: { x: 0, y: 50 },
+    });
+  });
+
+  it('never enlarges content past its own size', () => {
+    expect(fitStage({ width: 100, height: 50 }, { width: 300, height: 150 })).toEqual({
+      zoom: 1,
+      pan: { x: 100, y: 50 },
+    });
+  });
+
+  it('answers the identity for an unmeasured viewport', () => {
+    expect(fitStage({ width: 100, height: 50 }, { width: 0, height: 0 })).toEqual({
+      zoom: 1,
+      pan: { x: 0, y: 0 },
+    });
+  });
+});
+
+describe('<Stage>', () => {
+  it('draws its content through the camera', () => {
+    const { container } = render(
+      <Stage
+        size={{ width: 300, height: 100 }}
+        view={{ zoom: 2, pan: { x: 10, y: 20 } }}
+        onViewChange={() => {}}
+      >
+        <div data-testid="art" />
+      </Stage>,
+    );
+    const el = content(container);
+    expect(el).toContainElement(screen.getByTestId('art'));
+    expect(zoomOf(el)).toBe(2);
+    expect(el.style.getPropertyValue('--lk-stage-x')).toBe('10px');
+    expect(el.style.getPropertyValue('--lk-stage-y')).toBe('20px');
+    expect(el.style.getPropertyValue('--lk-stage-w')).toBe('300px');
+    expect(el.style.getPropertyValue('--lk-stage-h')).toBe('100px');
+  });
+
+  it('zooms on the wheel', () => {
+    function Host() {
+      const [view, setView] = useState<ViewTransform>({ zoom: 1, pan: { x: 0, y: 0 } });
+      return (
+        <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={setView}>
+          <div />
+        </Stage>
+      );
+    }
+    const { container } = render(<Host />);
+    const host = container.querySelector('.lk-stage');
+    if (!host) throw new Error('no stage');
+    fireEvent.wheel(host, { deltaY: -200, clientX: 0, clientY: 0 });
+    expect(zoomOf(content(container))).toBeGreaterThan(1);
+  });
+
+  it('zooms on a wheel handed to its camera from outside the stage', () => {
+    // What an annotation target's input box does: it is portalled out of the
+    // stage, so its wheel never bubbles here.
+    const slot: CameraWheelSlot = { current: null };
+    function Host() {
+      const [view, setView] = useState<ViewTransform>({ zoom: 1, pan: { x: 0, y: 0 } });
+      return (
+        <CameraWheelContext.Provider value={slot}>
+          <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={setView}>
+            <div />
+          </Stage>
+        </CameraWheelContext.Provider>
+      );
+    }
+    const { container } = render(<Host />);
+    act(() => {
+      slot.current?.(new WheelEvent('wheel', { deltaY: -200, cancelable: true }));
+    });
+    expect(zoomOf(content(container))).toBeGreaterThan(1);
+  });
+
+  it('listens for the wheel actively, so it can keep the page from scrolling', () => {
+    // A proxy: jsdom does not enforce passive listeners, so a preventDefault in
+    // a passive one succeeds here and fails in a browser. React registers its
+    // wheel listeners passive; asserting the registration is what can fail.
+    const add = vi.spyOn(HTMLElement.prototype, 'addEventListener');
+    const { container } = render(
+      <Stage
+        size={{ width: 100, height: 100 }}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={() => {}}
+      >
+        <div />
+      </Stage>,
+    );
+    const host = container.querySelector('.lk-stage');
+    const wheel = add.mock.calls.filter(
+      (call, i) => call[0] === 'wheel' && add.mock.contexts[i] === host,
+    );
+    expect(wheel.map((call) => call[2])).toContainEqual(
+      expect.objectContaining({ passive: false }),
+    );
+    add.mockRestore();
+  });
+
+  it('tells the surface its tiles moved when the camera does', () => {
+    // A transform moves a tile without resizing anything, which is the one
+    // kind of move a ResizeObserver never reports.
+    const invalidateRects = vi.fn();
+    const surface = { invalidateRects } as unknown as SurfaceHandle;
+    const at = (view: ViewTransform) => (
+      <SurfaceContext.Provider value={surface}>
+        <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={() => {}}>
+          <div />
+        </Stage>
+      </SurfaceContext.Provider>
+    );
+    const { rerender } = render(at({ zoom: 1, pan: { x: 0, y: 0 } }));
+    invalidateRects.mockClear();
+    rerender(at({ zoom: 1.5, pan: { x: 0, y: 0 } }));
+    expect(invalidateRects).toHaveBeenCalled();
+  });
+});
+
+const staged = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Staged',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="art" />,
+  stage: { size: { width: 240, height: 160 }, initialView: { zoom: 1, pan: { x: 0, y: 0 } } },
+});
+
+const plain = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Plain',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="art" />,
+});
+
+describe('an instrument that declares a stage', () => {
+  it('renders its DOM on the stage', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    expect(content(container)).toContainElement(screen.getByTestId('art'));
+  });
+
+  it('gets the zoom controls, and they move the stage', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }));
+    });
+    expect(zoomOf(content(container))).toBeCloseTo(1.25);
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Actual size' }));
+    });
+    expect(zoomOf(content(container))).toBe(1);
+  });
+
+  it('is what earns them: DOM content without one gets none', () => {
+    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+    expect(screen.queryByRole('button', { name: 'Zoom in' })).toBeNull();
+  });
+});

package/src/canvas/Stage.tsx

@@ -0,0 +1,134 @@
+import { type CSSProperties, type ReactNode, useContext, useEffect, 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';
+
+/** Props for `<Stage>`. */
+export interface StageProps {
+  /** The content's own size in CSS pixels, at zoom 1. */
+  size: ViewportSize;
+  view: ViewTransform;
+  onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;
+  maxZoom?: number;
+  /** Fired whenever the stage's viewport is measured at a non-zero size. */
+  onResize?: (viewport: ViewportSize) => void;
+  /** Handed the viewport element, for a consumer tracking the pointer over it. */
+  hostRef?: { current: HTMLDivElement | null };
+  /** Drawn over the content in viewport pixels, outside the camera. */
+  overlay?: ReactNode;
+  children?: ReactNode;
+}
+
+/**
+ * The camera a stage opens at: the content centered in its viewport, shrunk to
+ * fit if it has to be and never enlarged past its own size.
+ */
+export function fitStage(size: ViewportSize, viewport: ViewportSize): ViewTransform {
+  if (!(size.width > 0 && size.height > 0 && viewport.width > 0 && viewport.height > 0)) {
+    return { zoom: 1, pan: { x: 0, y: 0 } };
+  }
+  const zoom = Math.min(1, viewport.width / size.width, viewport.height / size.height);
+  return {
+    zoom,
+    pan: {
+      x: (viewport.width - size.width * zoom) / 2,
+      y: (viewport.height - size.height * zoom) / 2,
+    },
+  };
+}
+
+/**
+ * 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
+ * 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.
+ */
+export function Stage({
+  size,
+  view: viewProp,
+  onViewChange,
+  minZoom,
+  maxZoom,
+  onResize,
+  hostRef,
+  overlay,
+  children,
+}: StageProps) {
+  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 onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  useEffect(() => {
+    const el = host.current;
+    if (!el) return;
+    const measure = () => {
+      const rect = el.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        onResizeRef.current?.({ width: rect.width, height: rect.height });
+      }
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // A transform moves every tile inside the content without resizing anything,
+  // and a ResizeObserver reports only resizes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the camera is the trigger, not an input — the effect re-measures whenever it moves.
+  useEffect(() => {
+    surface?.invalidateRects();
+  }, [surface, view.zoom, view.pan.x, view.pan.y]);
+
+  // 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 = {
+    ['--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),
+    ['--lk-stage-w' as string]: `${size.width}px`,
+    ['--lk-stage-h' as string]: `${size.height}px`,
+  } 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>
+  );
+}

package/src/canvas/camera.test.ts

@@ -41,11 +41,18 @@ describe('zoomAt', () => {
     expect(screenToWorld(at, next).x).toBeCloseTo(before.x, 10);
   });
 
-  it('treats a non-finite zoom as 1 rather than propagating NaN', () => {
+  it('keeps a view that arrived with a non-finite zoom finite', () => {
     const next = zoomAt({ zoom: Number.NaN, pan: { x: 0, y: 0 } }, 2, { x: 10, y: 10 });
-    expect(next.zoom).toBe(2);
+    expect(next.zoom > 0 && Number.isFinite(next.zoom)).toBe(true);
     expect(Number.isFinite(next.pan.x)).toBe(true);
   });
+
+  it('keeps the zoom positive when a factor and bound would drive it to 0', () => {
+    const at = { x: 10, y: 10 };
+    const next = zoomAt(view, 0, at, { min: 0 });
+    expect(next.zoom > 0 && Number.isFinite(next.zoom)).toBe(true);
+    expect(Number.isFinite(screenToWorld(at, next).x)).toBe(true);
+  });
 });
 
 describe('centerOn', () => {
@@ -76,3 +83,11 @@ describe('centerOn', () => {
     expect(centerOn({ x: 0, y: 0 }, 6, { width: 10, height: 10 }, DEFAULT_FRAME).zoom).toBe(6);
   });
 });
+
+describe('centerOn zoom invariant', () => {
+  it('builds a camera with a positive zoom from a zoom of 0', () => {
+    const v = centerOn({ x: 1, y: 1 }, 0, { width: 100, height: 100 });
+    expect(v.zoom > 0 && Number.isFinite(v.zoom)).toBe(true);
+    expect(Number.isFinite(screenToWorld({ x: 5, y: 5 }, v).x)).toBe(true);
+  });
+});

package/src/canvas/camera.ts

@@ -1,3 +1,4 @@
+import { normalizeZoom } from '@weasel-js/core';
 import type { Point, ViewTransform } from '../instrument/types';
 import { DEFAULT_FRAME, type ViewportSize, type WorldFrame } from './worldSpec';
 
@@ -10,10 +11,6 @@ export interface ZoomAtOptions {
   max?: number;
 }
 
-function usableZoom(zoom: number): number {
-  return Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
-}
-
 /**
  * Zoom a view by `factor` about a fixed point, so whatever world coordinate
  * `at` was over stays under it.
@@ -32,8 +29,10 @@ export function zoomAt(
   // drifts by `(1 - ratio) * originPx` per step on any frame that moves it.
   const anchorX = at.x - frame.originPx.x;
   const anchorY = at.y - frame.originPx.y;
-  const current = usableZoom(view.zoom);
-  const zoom = Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? 0, current * factor));
+  const current = normalizeZoom(view.zoom);
+  const zoom = normalizeZoom(
+    Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? 0, current * factor)),
+  );
   const ratio = zoom / current;
   return {
     zoom,
@@ -52,11 +51,12 @@ export function centerOn(
   size: ViewportSize,
   frame: WorldFrame = DEFAULT_FRAME,
 ): ViewTransform {
+  const z = normalizeZoom(zoom);
   return {
-    zoom,
+    zoom: z,
     pan: {
-      x: size.width / 2 - frame.originPx.x - world.x * zoom,
-      y: size.height / 2 - frame.originPx.y - world.y * zoom * frame.yDir,
+      x: size.width / 2 - frame.originPx.x - world.x * z,
+      y: size.height / 2 - frame.originPx.y - world.y * z * frame.yDir,
     },
   };
 }

package/src/canvas/index.ts

@@ -1,3 +1,5 @@
+export type { CameraWheelSlot } from './CameraWheelContext';
+export { CameraWheelContext } from './CameraWheelContext';
 export type { CanvasStackProps } from './CanvasStack';
 export { CanvasStack } from './CanvasStack';
 export type { CanvasStackContextValue, CanvasStackSurface } from './CanvasStackContext';
@@ -5,6 +7,8 @@ export { CanvasStackContext } from './CanvasStackContext';
 export type { ZoomAtOptions } from './camera';
 export { centerOn, zoomAt } from './camera';
 export { screenToWorld, worldToScreen } from './canvasCoords';
+export type { StageProps } from './Stage';
+export { fitStage, Stage } from './Stage';
 export type { CanvasLayerDescriptor } from './useLayerScheduler';
 export type { OrbitHandlers, OrbitView, UseOrbitOptions, Vec3 } from './useOrbit';
 export {

package/src/canvas/usePanZoom.test.ts

@@ -37,6 +37,34 @@ function setup(initialView: ViewTransform, options?: Partial<UsePanZoomOptions>)
 }
 
 describe('usePanZoom', () => {
+  it('stacks two wheel events that land before a re-render', () => {
+    const { wheel } = setup({ zoom: 1, pan: { x: 0, y: 0 } });
+    const once = wheel(-100).zoom;
+
+    const views: ViewTransform[] = [];
+    const { result } = renderHook(() =>
+      usePanZoom({ view: { zoom: 1, pan: { x: 0, y: 0 } }, onViewChange: (v) => views.push(v) }),
+    );
+    act(() => {
+      result.current.onWheel(wheelEvent(-100));
+      result.current.onWheel(wheelEvent(-100));
+    });
+    expect(views[1].zoom).toBeCloseTo(once * once, 10);
+  });
+
+  it('lets the view prop win at the next render', () => {
+    const views: ViewTransform[] = [];
+    const { result, rerender } = renderHook(
+      (props: { view: ViewTransform }) =>
+        usePanZoom({ view: props.view, onViewChange: (v) => views.push(v) }),
+      { initialProps: { view: { zoom: 1, pan: { x: 0, y: 0 } } } },
+    );
+    act(() => result.current.onWheel(wheelEvent(-100)));
+    rerender({ view: { zoom: 2, pan: { x: 0, y: 0 } } });
+    act(() => result.current.onWheel(wheelEvent(0)));
+    expect(views[1].zoom).toBeCloseTo(2, 10);
+  });
+
   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