@weasel-js/labkit 1.6.0 → 1.7.0

package/src/lab/LabZoom.test.tsx

@@ -0,0 +1,223 @@
+import { act, fireEvent, render, screen, within } from '@testing-library/react';
+import {
+  ActionsProvider,
+  type ActionsRegistry,
+  ActiveToolContextProvider,
+  DepRegistryProvider,
+  type Tool,
+  useActionsRegistry,
+  useGestureDispatcher,
+} from '@weasel-js/core';
+import { type ReactNode, useEffect } from 'react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from './Lab';
+import { LabContext, type LabContextValue } from './LabContext';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+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 } },
+    maxZoom: 1.5,
+  },
+});
+
+const plain = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Plain',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="plain" />,
+});
+
+let lab: LabContextValue | null = null;
+function Capture({ children }: { children?: ReactNode }) {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        lab = value;
+        return children ?? null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+const zoomBar = () => within(screen.getByRole('toolbar', { name: 'Zoom' }));
+const readout = () => zoomBar().getByRole('button', { name: /^Zoom \d+%|^Zoom unavailable/ });
+const press = (name: string) =>
+  act(() => {
+    fireEvent.click(zoomBar().getByRole('button', { name }));
+  });
+
+const MOD = /mac/i.test(navigator.platform || navigator.userAgent)
+  ? { metaKey: true }
+  : { ctrlKey: true };
+function key(k: string): boolean {
+  let prevented = false;
+  act(() => {
+    prevented = !fireEvent.keyDown(window, { key: k, ...MOD });
+  });
+  return prevented;
+}
+
+const NO_TOOLS: ReadonlyMap<string, Tool> = new Map();
+
+/** A story's own dispatcher, binding Mod+= the way a `<SceneCanvas>` with keyboard zoom does. */
+function StoryZoomKey({ run }: { run: () => void }) {
+  function Bound() {
+    const registry = useActionsRegistry() as ActionsRegistry;
+    useEffect(
+      () =>
+        registry.register({
+          id: 'story.zoom',
+          label: 'Story zoom',
+          defaultBinding: { kind: 'key', key: '=', mods: { mod: true } },
+          invoker: { timing: 'immediate', run: () => run() },
+        }),
+      [registry],
+    );
+    useGestureDispatcher({
+      canvasRef: { current: null },
+      actions: registry,
+      entriesById: NO_TOOLS,
+      channels: { contextMenu: false, ingest: false },
+    });
+    return null;
+  }
+  return (
+    <DepRegistryProvider>
+      <ActionsProvider>
+        <ActiveToolContextProvider>
+          <Bound />
+        </ActiveToolContextProvider>
+      </ActionsProvider>
+    </DepRegistryProvider>
+  );
+}
+
+function stageZoom(container: HTMLElement, index = 0): number {
+  const el = container.querySelectorAll<HTMLElement>('.lk-stage__content')[index];
+  if (!el) throw new Error('no stage content');
+  return Number(el.style.getPropertyValue('--lk-stage-zoom'));
+}
+
+describe("the lab header's zoom controls", () => {
+  it('step the focused trial through its camera and read its zoom back', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    expect(readout()).toHaveTextContent('100%');
+    press('Zoom in');
+    expect(stageZoom(container)).toBeCloseTo(1.25);
+    expect(readout()).toHaveTextContent('125%');
+    press('Zoom out');
+    expect(stageZoom(container)).toBeCloseTo(1);
+    press('Zoom out');
+    expect(readout()).toHaveTextContent('80%');
+  });
+
+  it('reset to actual size from the readout', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    press('Zoom out');
+    press('Zoom out');
+    act(() => {
+      fireEvent.click(readout());
+    });
+    expect(stageZoom(container)).toBe(1);
+    expect(readout()).toHaveTextContent('100%');
+  });
+
+  it("stop at the camera's own limit, and say so", () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    press('Zoom in');
+    press('Zoom in');
+    expect(stageZoom(container)).toBe(1.5);
+    expect(zoomBar().getByRole('button', { name: 'Zoom in' })).toBeDisabled();
+    expect(zoomBar().getByRole('button', { name: 'Zoom out' })).toBeEnabled();
+  });
+
+  it('answer Mod+=, Mod+- and Mod+0, claiming the key from the browser', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    expect(key('=')).toBe(true);
+    expect(stageZoom(container)).toBeCloseTo(1.25);
+    key('-');
+    key('-');
+    expect(stageZoom(container)).toBeCloseTo(0.8);
+    key('0');
+    expect(stageZoom(container)).toBe(1);
+  });
+
+  it('go inert over a trial with no camera, and leave its keys to the browser', () => {
+    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+    for (const name of ['Zoom out', 'Zoom in']) {
+      expect(zoomBar().getByRole('button', { name })).toBeDisabled();
+    }
+    expect(readout()).toBeDisabled();
+    expect(readout()).toHaveTextContent('–');
+    expect(key('=')).toBe(false);
+  });
+
+  it("take the key ahead of a story's own binding in a trial with a camera", () => {
+    const story = vi.fn();
+    const zooming = defineInstrument<Record<string, never>, Record<string, never>>({
+      ...staged,
+      name: 'Zooming',
+      render: () => <StoryZoomKey run={story} />,
+    });
+    const { container } = render(<Lab instruments={[zooming]} defaultInstrument="Zooming" />);
+    key('=');
+    expect(stageZoom(container)).toBeCloseTo(1.25);
+    expect(story).not.toHaveBeenCalled();
+  });
+
+  it("leave the key to a story's own binding in a trial with no camera", () => {
+    const story = vi.fn();
+    const zooming = defineInstrument<Record<string, never>, Record<string, never>>({
+      ...plain,
+      name: 'ZoomingPlain',
+      render: () => <StoryZoomKey run={story} />,
+    });
+    render(<Lab instruments={[zooming]} defaultInstrument="ZoomingPlain" />);
+    key('=');
+    expect(story).toHaveBeenCalledTimes(1);
+  });
+
+  it('follow the focus from trial to trial', () => {
+    const { container } = render(
+      <Lab instruments={[staged, plain]} defaultInstrument="Staged">
+        <Capture />
+      </Lab>,
+    );
+    act(() => lab?.addTrial('Staged'));
+    act(() => lab?.addTrial('Plain'));
+    const [first, second, third] = lab?.trials.map((t) => t.id) ?? [];
+    expect(zoomBar().getByRole('button', { name: 'Zoom in' })).toBeDisabled();
+
+    act(() => lab?.focusTrial(second ?? ''));
+    press('Zoom out');
+    expect(stageZoom(container, 1)).toBeCloseTo(0.8);
+    expect(stageZoom(container, 0)).toBe(1);
+    expect(readout()).toHaveTextContent('80%');
+
+    act(() => lab?.focusTrial(first ?? ''));
+    expect(readout()).toHaveTextContent('100%');
+    key('=');
+    expect(stageZoom(container, 0)).toBeCloseTo(1.25);
+    expect(stageZoom(container, 1)).toBeCloseTo(0.8);
+
+    act(() => lab?.focusTrial(third ?? ''));
+    expect(readout()).toBeDisabled();
+  });
+
+  it('are left out when the lab says so', () => {
+    render(<Lab instruments={[staged]} defaultInstrument="Staged" zoom={false} />);
+    expect(screen.queryByRole('toolbar', { name: 'Zoom' })).toBeNull();
+  });
+});

package/src/lab/LabZoom.tsx

@@ -0,0 +1,170 @@
+import {
+  type Action,
+  ActionDisabledReason,
+  ActionsProvider,
+  type ActionsRegistry,
+  ActiveToolContextProvider,
+  DepRegistryProvider,
+  makeViewportZoomAction,
+  type Tool,
+  useActionsRegistry,
+  useDepSource,
+  useGestureDispatcher,
+  type ViewApi,
+} from '@weasel-js/core';
+import { ZoomInIcon, ZoomOutIcon } from '@weasel-js/ui';
+import { useContext, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useStore } from 'zustand/react';
+import type { CameraView } from '../canvas/CameraInput';
+import { CameraRegistryContext } from '../canvas/cameraRegistry';
+import { atScale, viewMiddle } from '../canvas/cameraZoom';
+import { formatShortcut } from '../passthrough/weasel-ui';
+import { Toolbar } from '../primitives/Toolbar';
+import { LabStoreContext } from '../state/context';
+import { as2DView } from '../state/view';
+import { useLabContext } from './LabContext';
+
+const ZOOM_ID = 'viewport.zoom';
+const NO_TOOLS: ReadonlyMap<string, Tool> = new Map();
+const CHANNELS = { contextMenu: false, ingest: false } as const;
+const NO_ELEMENT = { current: null };
+
+type ZoomKind = 'in' | 'out' | 'reset';
+
+interface KeyBinding {
+  spec: { kind: string; key?: string; mods?: { mod?: boolean; shift?: boolean | 'optional' } };
+  opts?: { params?: { kind?: string } };
+}
+
+// Core's zoom with only its keys: the wheel and pinch belong to each trial's
+// own dispatcher. The clamp is left to the camera, which knows its range.
+const BASE = makeViewportZoomAction({ min: 1e-9, max: Number.POSITIVE_INFINITY });
+const KEY_BINDINGS = (BASE.defaultBinding as KeyBinding[]).filter((b) => b.spec.kind === 'key');
+
+function shortcutFor(kind: ZoomKind): string | undefined {
+  const spec = KEY_BINDINGS.find((b) => b.opts?.params?.kind === kind)?.spec;
+  return spec?.key ? formatShortcut({ key: spec.key, mod: spec.mods?.mod }) : undefined;
+}
+
+/** The focused trial's camera, with the zoom's reset meaning actual size about
+ *  the middle of the view. */
+function forZoom(camera: CameraView): ViewApi {
+  return {
+    get: camera.get,
+    set: camera.set,
+    hostSize: camera.hostSize,
+    recenter: () => atScale(camera.get(), 1, viewMiddle(camera)),
+  };
+}
+
+const percent = new Intl.NumberFormat(undefined, { style: 'percent', maximumFractionDigits: 0 });
+
+/**
+ * Zoom out, the zoom as a percentage, and zoom in, for whichever trial has the
+ * focus. The percentage resets to actual size. They route through core's
+ * `viewport.zoom` action, on a dispatcher of their own that listens for its
+ * keys — Mod+=, Mod+- and Mod+0 — so the buttons and the keys are one path.
+ * Over a trial with no camera the group stays, disabled, so the header does not
+ * reflow as the focus moves.
+ */
+export function LabZoom() {
+  return (
+    <DepRegistryProvider>
+      <ActionsProvider>
+        <ActiveToolContextProvider>
+          <LabZoomControls />
+        </ActiveToolContextProvider>
+      </ActionsProvider>
+    </DepRegistryProvider>
+  );
+}
+
+function LabZoomControls() {
+  const registry = useActionsRegistry() as ActionsRegistry;
+  const { focusedTrialId } = useLabContext();
+  const cameras = useContext(CameraRegistryContext);
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] <LabZoom> requires <LabStoreProvider>');
+
+  const camera = useSyncExternalStore(cameras?.subscribe ?? noSubscribe, () =>
+    cameras && focusedTrialId ? cameras.get(focusedTrialId) : null,
+  );
+  const zoom = useStore(storeCtx.store, (s) => {
+    const record = s.trials.find((t) => t.id === focusedTrialId);
+    return as2DView(record?.view)?.zoom ?? null;
+  });
+
+  const live = zoom !== null && camera !== null;
+  const view = useMemo(() => (camera ? forZoom(camera) : null), [camera]);
+  const viewRef = useRef(view);
+  viewRef.current = live ? view : null;
+
+  useDepSource('view', () => viewRef.current as ViewApi);
+
+  useEffect(() => {
+    const action: Action = {
+      ...BASE,
+      defaultBinding: KEY_BINDINGS as Action['defaultBinding'],
+      enabled: () => (viewRef.current ? true : ActionDisabledReason.NotApplicable),
+    };
+    return registry.register(action);
+  }, [registry]);
+
+  // First, so a story's own zoom keys do not also fire over a trial with a
+  // camera; over one without, the action is disabled and the keys pass on.
+  useGestureDispatcher({
+    canvasRef: NO_ELEMENT,
+    actions: registry,
+    entriesById: NO_TOOLS,
+    channels: CHANNELS,
+    keyboard: 'first',
+  });
+
+  const range = camera?.zoomRange();
+  // A step that lands within rounding of a limit has reached it.
+  const canIn = zoom !== null && range !== undefined && zoom < range.max * (1 - 1e-9);
+  const canOut = zoom !== null && range !== undefined && zoom > range.min * (1 + 1e-9);
+  const run = (kind: ZoomKind) => () => {
+    registry.trigger(ZOOM_ID, { kind });
+  };
+  const hint = (label: string, kind: ZoomKind): string => {
+    const keys = shortcutFor(kind);
+    return keys ? `${label} (${keys})` : label;
+  };
+  const shown = live && zoom !== null ? percent.format(zoom) : null;
+
+  return (
+    <Toolbar aria-label="Zoom">
+      <Toolbar.Group aria-label="Zoom">
+        <Toolbar.Button
+          iconOnly
+          aria-label="Zoom out"
+          title={hint('Zoom out', 'out')}
+          disabled={!canOut}
+          onClick={run('out')}
+        >
+          <ZoomOutIcon size={16} />
+        </Toolbar.Button>
+        <Toolbar.Button
+          aria-label={shown ? `Zoom ${shown} — reset to actual size` : 'Zoom unavailable'}
+          title={live ? hint('Actual size', 'reset') : 'This trial has no camera'}
+          disabled={!live}
+          onClick={run('reset')}
+        >
+          <span className="lk-lab-zoom__readout">{shown ?? '–'}</span>
+        </Toolbar.Button>
+        <Toolbar.Button
+          iconOnly
+          aria-label="Zoom in"
+          title={hint('Zoom in', 'in')}
+          disabled={!canIn}
+          onClick={run('in')}
+        >
+          <ZoomInIcon size={16} />
+        </Toolbar.Button>
+      </Toolbar.Group>
+    </Toolbar>
+  );
+}
+
+const noSubscribe = (): (() => void) => () => {};

package/src/lab/index.ts

@@ -11,5 +11,6 @@ export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
 export type { LabPage, LabSwitcherProps } from './LabSwitcher';
 export { currentPage, LabSwitcher } from './LabSwitcher';
+export { LabZoom } from './LabZoom';
 export type { PanelDescriptor, TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

package/src/loupe/AGENTS.md

@@ -14,7 +14,7 @@ This directory binds that model to a labkit trial and draws it.
 | `types.ts` | `LoupeCapability`, and `resolveLoupe` filling in every default |
 | `useLoupe.ts` | The model over a host element, and pointer aiming |
 | `loupeActions.ts` | `loupe.peek` and `loupe.magnify`, as `Action` descriptors |
-| `LoupeGestures.tsx` | Registers those and mounts the dispatcher on the host |
+| `LoupeGestures.tsx` | Registers those, and mounts a dispatcher on the host when no camera has one there |
 | `TrialLoupe.tsx` | Picks the painter and mounts the lens |
 | `LoupeBubble.tsx` | The circular clip, positioned on the aim |
 | `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
@@ -46,11 +46,12 @@ StrictMode mounts / unmounts / mounts every effect — so disposing in the
 cleanup leaves a magnifier that draws but silently ignores every aim. It owns
 no resources; unmounting only reports the lens gone.
 
-**The wheel is taken from pan/zoom by declining it, not by capturing it.**
-`loupe.magnify`'s `enabled` returns a disabled reason while the lens is down, so
-the dispatcher leaves the event unhandled and `usePanZoom` — a React handler on
-the same element — sees it as usual. While the lens is up the action fires, the
-dispatcher stops propagation, and React's root listener never runs.
+**The wheel is taken from the camera by rank, and handed back by declining.**
+In a trial the loupe's actions join the camera's dispatcher (`CameraInput`).
+`loupe.magnify` sits in the hotkey tier, so while the lens is up it outranks
+the camera's wheel zoom; while it is down its `enabled` returns a disabled
+reason and the dispatcher falls through to the zoom. Outside a camera — the DOM
+`.lk-trial__loupe-host` — `<LoupeGestures>` mounts a dispatcher of its own.
 
 **Aiming is a plain listener because a hover is not a gesture.**
 `GESTURE_DESCRIPTORS` names no continuous-motion gesture, so `pointermove` /

package/src/loupe/LoupeGestures.tsx

@@ -1,7 +1,7 @@
 /**
- * Mounts the gesture dispatcher on a loupe's host and registers the loupe's
- * actions on it, so the peek key and the wheel route the way every other
- * weasel binding does.
+ * Registers the loupe's actions, and mounts the gesture dispatcher on the
+ * loupe's host when no camera already has one there, so the peek key and the
+ * wheel route the way every other weasel binding does.
  *
  * Three of the dispatcher's four element channels are off. Only `wheel` is
  * wanted here; `contextMenu` suppresses the native menu unconditionally and
@@ -14,7 +14,8 @@ import {
   useActionsRegistry,
   useGestureDispatcher,
 } from '@weasel-js/core';
-import { type RefObject, useEffect, useMemo } from 'react';
+import { type RefObject, useContext, useEffect, useMemo } from 'react';
+import { CameraContext } from '../canvas/CameraInput';
 import { createLoupeActions, type LoupeInputApi } from './loupeActions';
 
 /** Props for `<LoupeGestures>`. */
@@ -35,7 +36,8 @@ function LoupeDispatch({
   input,
   peekKey,
   registry,
-}: LoupeGesturesProps & { registry: ActionsRegistry }) {
+  ownDispatcher,
+}: LoupeGesturesProps & { registry: ActionsRegistry; ownDispatcher: boolean }) {
   const actions = useMemo(() => createLoupeActions(input, peekKey), [input, peekKey]);
 
   useEffect(() => {
@@ -48,20 +50,23 @@ function LoupeDispatch({
   useGestureDispatcher({
     canvasRef: hostRef,
     actions: registry,
-    toolsById: NO_TOOLS,
+    entriesById: NO_TOOLS,
     channels: CHANNELS,
+    enabled: ownDispatcher,
   });
 
   return null;
 }
 
 /**
- * The loupe's input, routed. Render it inside a `<WeaselProvider isolate>` —
- * with no registry in scope it renders nothing rather than registering
- * actions that could never fire.
+ * The loupe's input, routed. Inside a camera (`<CanvasStack>`, `<Stage>`) its
+ * actions join the camera's dispatcher, which already listens on the host;
+ * elsewhere it mounts a dispatcher of its own. With no registry in scope it
+ * renders nothing rather than registering actions that could never fire.
  */
 export function LoupeGestures(props: LoupeGesturesProps) {
   const registry = useActionsRegistry();
+  const camera = useContext(CameraContext);
   if (!registry) return null;
-  return <LoupeDispatch {...props} registry={registry} />;
+  return <LoupeDispatch {...props} registry={registry} ownDispatcher={camera === null} />;
 }

package/src/loupe/TrialLoupe.tsx

@@ -1,5 +1,5 @@
-import { WeaselProvider } from '@weasel-js/core';
 import { type RefObject, useContext, useMemo } from 'react';
+import { CameraScope } from '../canvas/CameraInput';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 import type { WorldSpec } from '../canvas/worldSpec';
 import type { ViewTransform } from '../instrument/types';
@@ -63,12 +63,12 @@ export function TrialLoupe({
 
   // The gestures mount outside the visibility gate: hold-to-peek is what
   // raises a lens that is down, so its binding has to be live while it is.
-  // One isolated scope per loupe, for the reason `<AnnotationOverlay>` gives
-  // — an actions registry holds one dispatcher.
+  // In a trial they join the trial's scope, and with it the camera's
+  // dispatcher; outside one, `<CameraScope>` gives them an isolated scope.
   const gestures = (
-    <WeaselProvider isolate>
+    <CameraScope>
       <LoupeGestures hostRef={host} input={loupe.input} peekKey={capability.peekKey ?? null} />
-    </WeaselProvider>
+    </CameraScope>
   );
 
   if (!loupe.visible) return gestures;

package/src/loupe/index.ts

@@ -1,3 +1,4 @@
+export type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
 export type { CanvasLoupeProps } from './CanvasLoupe';
 export { CanvasLoupe } from './CanvasLoupe';
 export type { LensCamera, SourceRect } from './canvasLens';

package/src/loupe/loupeActions.ts

@@ -21,8 +21,8 @@ export const WHEEL_RATE = 0.002;
  *  registration. */
 export interface LoupeInputApi {
   /** Whether the lens is up. The wheel belongs to the loupe only while it is;
-   *  otherwise `loupe.magnify` declines and the dispatcher leaves the event
-   *  unhandled, which is what hands it back to the lab's own pan/zoom. */
+   *  otherwise `loupe.magnify` declines and the dispatcher falls through to
+   *  the trial camera's zoom. */
   shown: () => boolean;
   /** Raise or drop the hold-to-peek flag. */
   setPeeking: (on: boolean) => void;
@@ -43,6 +43,10 @@ export function createLoupeActions(
     id: LOUPE_MAGNIFY_ID,
     label: 'Magnify (loupe)',
     group: 'loupe',
+    // Hotkey scope, so while the lens is up it outranks the trial camera's
+    // wheel zoom on the same dispatcher; while it is down `enabled` declines
+    // and the zoom runs.
+    scope: 'hotkey',
     // Every modifier optional: the lens claims the wheel whenever it is up,
     // which is what the hand-rolled capture-phase listener did. A bare spec
     // would forbid modifiers and hand Cmd+wheel back to the lab mid-peek.

package/src/overview/AGENTS.md

@@ -0,0 +1,38 @@
+# Overview — Agent Guide
+
+`src/overview/` is `@weasel-js/labkit/overview`: `<TrialOverview>`, a trial's
+whole content in a floating panel. Its own bundle entry; nothing in the main
+bundle imports it.
+
+| File | Role |
+|---|---|
+| `TrialOverview.tsx` | The panel: content, chrome canvas, and its own dispatcher |
+| `OverviewMarks.tsx` | Every annotation target's marks, read-only, as SVG |
+
+## How it reads the trial
+
+Only through `CameraContext`, which `<CanvasStack>` and `<Stage>` set: the
+camera as a weasel `ViewApi` over frame-local coordinates, the frame, the
+camera's element, a stage's content rect. A canvas instrument's layers come
+from `CanvasStackContext`, marks from `AnnotationsContext`. So it works
+anywhere inside a camera — `stage.overlay`, or a canvas instrument's `render`.
+
+Input is core's `minimap.center` / `minimap.pan` on a dispatcher of its own,
+with the camera as `rootView`; the pointer store is the trial's, shared.
+
+## Traps
+
+**It sits inside the stage's element.** Every event that bubbles out of the box
+reaches the stage's dispatcher, the loupe's aim and the stage's pointer
+publisher. The box stops them; drop that and a drag in the overview also pans
+the stage, and the pointer flips between `'overview'` and `'stage'` each move.
+
+**Marks are placed by measuring.** A target's rect on the overview is its
+element's rect against the camera's element, through the camera — never the
+target's content size, which is the mark's world and not where it is drawn.
+jsdom measures zero; a test mocks `getBoundingClientRect`, and the picture is a
+screenshot.
+
+**Never render the instrument's own `render` in it.** Its effects — a pane
+ref, an annotation target — would run twice. `render` is a separate, lighter
+copy the instrument supplies.