@weasel-js/labkit 1.6.0 → 1.6.1

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

@@ -19,12 +19,21 @@ const backdrop = (container: HTMLElement) =>
 
 describe('<Lab nebula>', () => {
   it('draws one blob per literal color', () => {
-    const { container } = render(<Lab instruments={[bare]} defaultInstrument="Bare" mode="dark" nebula={['#ff0000', '#00ff00']} />);
+    const { container } = render(
+      <Lab
+        instruments={[bare]}
+        defaultInstrument="Bare"
+        mode="dark"
+        nebula={['#ff0000', '#00ff00']}
+      />,
+    );
     expect(backdrop(container).match(/radial-gradient/g)).toHaveLength(3);
   });
 
   it('resolves a theme ramp against the lab’s theme', () => {
-    const { container } = render(<Lab instruments={[bare]} defaultInstrument="Bare" mode="dark" nebula={{ ramp: 'swatch' }} />);
+    const { container } = render(
+      <Lab instruments={[bare]} defaultInstrument="Bare" mode="dark" nebula={{ ramp: 'swatch' }} />,
+    );
     const sky = resolveTheme(interstellarTheme, { mode: 'dark' })['--wzl-swatch-sky'];
     expect(backdrop(container)).toContain(sky);
   });

package/src/lab/Lab.test.tsx

@@ -165,7 +165,9 @@ describe('<Lab>', () => {
       storageKey: 's',
     });
     await waitFor(() => expect(labRef?.trials[0]).toBeDefined());
-    expect((labRef?.trials[0]?.state as { seen: Set<string> }).seen).toEqual(new Set(['a']));
+    expect((labRef?.trials[0]?.state as { seen: Set<string> } | undefined)?.seen).toEqual(
+      new Set(['a']),
+    );
   });
 });
 

package/src/lab/Lab.tsx

@@ -12,7 +12,7 @@ import {
 } from 'react';
 import { useStore } from 'zustand/react';
 import { AnnotationPreloadContext } from '../annotations/preload';
-import { ANNOTATION_TOOLS } from '../annotations/toolMap';
+import { labAnnotationTools } from '../annotations/toolMap';
 import {
   LabAsideRegion,
   LabFooterRegion,
@@ -478,10 +478,10 @@ function LabRuntime({
   // of them silently losing.
   // Declaring `annotations` on any instrument puts the drawing tools here, in
   // the lab's rail: one tool is armed across every trial.
-  const annotates = instruments.some((i) => i.annotations != null);
+  const annotationTools = useMemo(() => labAnnotationTools(instruments), [instruments]);
   const labChromeAll = useMemo(
-    () => labContributions([...(annotates ? ANNOTATION_TOOLS : []), ...(tools ?? [])], labChrome),
-    [annotates, tools, labChrome],
+    () => labContributions([...annotationTools, ...(tools ?? [])], labChrome),
+    [annotationTools, tools, labChrome],
   );
   const hasFooterChrome = labChromeAll.some((c) => c.region === 'footer');
   const hasPaneChrome = labChromeAll.some((c) => c.region === 'sidebar' || c.region === 'aside');

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(() => {
@@ -50,18 +52,21 @@ function LoupeDispatch({
     actions: registry,
     toolsById: 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.

package/src/overview/OverviewMarks.test.tsx

@@ -0,0 +1,100 @@
+/**
+ * The overview draws every target's marks where that target sits on the stage,
+ * and redraws when one is added. jsdom lays nothing out, so the target's rect
+ * and the stage's are mocked; the stage's camera is the identity there.
+ */
+import { act, render } from '@testing-library/react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { useAnnotations } from '../annotations/AnnotationsContext';
+import type { AnnotationsApi } from '../annotations/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { TrialOverview } from './TrialOverview';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+const rect = (left: number, top: number, width: number, height: number) =>
+  ({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+  }) as DOMRect;
+
+let restore: (() => void) | null = null;
+afterEach(() => restore?.());
+
+/** Stage 400×300, the pane at stage (50, 20) and 200×100. */
+function mount() {
+  const pane = { current: null as HTMLDivElement | null };
+  let api: AnnotationsApi | null = null;
+  function Body() {
+    api = useAnnotations();
+    return (
+      <div
+        ref={(el) => {
+          pane.current = el;
+        }}
+        data-testid="pane"
+      />
+    );
+  }
+  const marked = defineInstrument<Record<string, never>, Record<string, never>>({
+    name: 'Marked',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: () => <Body />,
+    stage: {
+      size: { width: 400, height: 300 },
+      overlay: () => <TrialOverview width={200} height={150} render={() => <div />} />,
+    },
+    annotations: {
+      targets: () => [{ id: 'pane', ref: pane, content: { w: 200, h: 100 } }],
+    },
+  });
+  const original = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    if (this === pane.current) return rect(50, 20, 200, 100);
+    return rect(0, 0, 0, 0);
+  };
+  restore = () => {
+    HTMLElement.prototype.getBoundingClientRect = original;
+  };
+  const r = render(<Lab instruments={[marked]} defaultInstrument="Marked" />);
+  return { ...r, api: () => api as AnnotationsApi };
+}
+
+const px = (el: HTMLElement, name: string) => Number.parseFloat(el.style.getPropertyValue(name));
+
+describe('marks on the overview', () => {
+  it('draws nothing for a target with no marks', () => {
+    const h = mount();
+    expect(h.container.querySelector('.lk-overview__marks')).toBeNull();
+  });
+
+  it("places a target's marks at the target's rect, through the fit", () => {
+    const h = mount();
+    act(() => {
+      h.api().add({ target: 'pane', kind: 'rect', frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 } });
+    });
+    const marks = h.container.querySelector<HTMLElement>('.lk-overview__marks[data-target="pane"]');
+    expect(marks).not.toBeNull();
+    if (!marks) return;
+    // Content 400×300 into 200×150, 6px in: scale 0.46, camera at
+    // (200 - 100 / 0.46, 150 - 75 / 0.46).
+    const s = 0.46;
+    expect(px(marks, '--lk-overview-mx')).toBeCloseTo((50 - (200 - 100 / s)) * s);
+    expect(px(marks, '--lk-overview-my')).toBeCloseTo((20 - (150 - 75 / s)) * s);
+    expect(px(marks, '--lk-overview-mw')).toBeCloseTo(200 * s);
+    expect(px(marks, '--lk-overview-mh')).toBeCloseTo(100 * s);
+    expect(marks.querySelector('svg path')).not.toBeNull();
+  });
+});

package/src/overview/OverviewMarks.tsx

@@ -0,0 +1,93 @@
+/**
+ * Every annotation target's marks, drawn read-only on the overview through the
+ * export's own vector path: `markSvgNodes`, then `serializeSvg`.
+ */
+import type { View } from '@weasel-js/core';
+import { serializeSvg } from '@weasel-js/svg';
+import { type CSSProperties, type RefObject, useEffect, useReducer } from 'react';
+import { useAnnotationsOptional } from '../annotations/AnnotationsContext';
+import { markSvgNodes } from '../annotations/svgNodes';
+import type { AnnotationsApi } from '../annotations/types';
+import type { CameraContextValue } from '../canvas/CameraInput';
+
+/** A target's box, in the camera's frame-local units. */
+interface LocalRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** Where `el` sits in the camera's frame-local units: its screen rect,
+ *  measured against the camera's element, through the camera. */
+function localRectOf(el: HTMLElement, camera: CameraContextValue): LocalRect | null {
+  const host = camera.element();
+  if (!host) return null;
+  const r = el.getBoundingClientRect();
+  const h = host.getBoundingClientRect();
+  const v = camera.view.get();
+  return {
+    x: (r.left - h.left) / v.scale.x + v.x,
+    y: (r.top - h.top) / v.scale.y + v.y,
+    w: r.width / v.scale.x,
+    h: r.height / v.scale.y,
+  };
+}
+
+/** The element a target's marks sit on. The capability's targets carry their
+ *  `ref`; the store's type names only the half it reads. */
+function elementOf(target: object): HTMLElement | null {
+  return (target as { ref?: RefObject<HTMLElement | null> }).ref?.current ?? null;
+}
+
+function markupOf(api: AnnotationsApi, target: string, content: { w: number; h: number }): string {
+  const painted = api.paintedMarks(target);
+  if (painted.length === 0) return '';
+  const nodes = painted.flatMap(({ mark, style }) => markSvgNodes(mark, content, style));
+  return serializeSvg(nodes, { viewBox: { x: 0, y: 0, width: content.w, height: content.h } });
+}
+
+/** Props for `<OverviewMarks>`. */
+export interface OverviewMarksProps {
+  fit: View;
+  camera: CameraContextValue;
+}
+
+/**
+ * The marks of every target in the annotations store in scope, placed where
+ * each target's element sits on the stage. Draws nothing outside an annotating
+ * trial, and takes no input.
+ */
+export function OverviewMarks({ fit, camera }: OverviewMarksProps) {
+  const api = useAnnotationsOptional();
+  const [, redraw] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => api?.subscribe(redraw), [api]);
+  if (!api) return null;
+  const s = fit.scale.x;
+  return (
+    <>
+      {api.targets().map((t) => {
+        const el = elementOf(t);
+        const box = el ? localRectOf(el, camera) : null;
+        const markup = box ? markupOf(api, t.id, t.content) : '';
+        if (!box || !markup) return null;
+        const place = {
+          ['--lk-overview-mx' as string]: `${(box.x - fit.x) * s}px`,
+          ['--lk-overview-my' as string]: `${(box.y - fit.y) * s}px`,
+          ['--lk-overview-mw' as string]: `${box.w * s}px`,
+          ['--lk-overview-mh' as string]: `${box.h * s}px`,
+        } as CSSProperties;
+        return (
+          <div
+            key={t.id}
+            className="lk-overview__marks"
+            style={place}
+            data-target={t.id}
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: the export's SVG serializer is the one vector path marks have; re-deriving React nodes would be a second.
+            dangerouslySetInnerHTML={{ __html: markup }}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/overview/TrialOverview.less

@@ -0,0 +1,53 @@
+.lk-overview__title {
+  padding: 2px 6px 4px;
+  font-size: var(--wzl-font-size-sm);
+  color: var(--wzl-fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  cursor: grab;
+}
+
+.lk-overview__box {
+  position: relative;
+  width: var(--lk-overview-w);
+  height: var(--lk-overview-h);
+  overflow: hidden;
+  background: var(--wzl-surface-sunken);
+  touch-action: none;
+  cursor: crosshair;
+}
+
+.lk-overview__content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--lk-overview-cw);
+  height: var(--lk-overview-ch);
+  transform-origin: 0 0;
+  transform: translate(var(--lk-overview-x), var(--lk-overview-y)) scale(var(--lk-overview-zoom));
+  pointer-events: none;
+}
+
+.lk-overview__canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+
+.lk-overview__marks {
+  position: absolute;
+  left: var(--lk-overview-mx);
+  top: var(--lk-overview-my);
+  width: var(--lk-overview-mw);
+  height: var(--lk-overview-mh);
+  pointer-events: none;
+}
+
+.lk-overview__marks > svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}

package/src/overview/TrialOverview.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useState } from 'react';
+import { Stage } from '../canvas/Stage';
+import type { ViewTransform } from '../instrument/types';
+import { TrialOverview } from './TrialOverview';
+
+const meta: Meta<typeof TrialOverview> = {
+  title: 'labkit/Overview/TrialOverview',
+  component: TrialOverview,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof TrialOverview>;
+
+const SIZE = { width: 640, height: 420 };
+const DOTS = [40, 120, 200, 280, 360, 440, 520, 600];
+
+/** A picture bigger than the stage at 2×, so there is somewhere to go. */
+function Picture() {
+  return (
+    <svg viewBox="0 0 640 420" width={SIZE.width} height={SIZE.height} role="img" aria-label="Grid">
+      <title>Grid</title>
+      <rect width="640" height="420" fill="#f4f1ea" />
+      {DOTS.map((x, i) => (
+        <circle key={x} cx={x} cy={40 + i * 48} r="24" fill="#8b98a8" />
+      ))}
+    </svg>
+  );
+}
+
+function Harness() {
+  const [view, setView] = useState<ViewTransform>({ zoom: 2, pan: { x: -200, y: -120 } });
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Stage
+        size={SIZE}
+        view={view}
+        onViewChange={setView}
+        overlay={<TrialOverview width={200} height={140} render={() => <Picture />} />}
+      >
+        <Picture />
+      </Stage>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <Harness />,
+};

package/src/overview/TrialOverview.test.tsx

@@ -0,0 +1,116 @@
+/**
+ * A trial's overview: a press in it moves the stage's camera there, and the
+ * pointer over it is published as the overview's, which the stage then draws.
+ *
+ * jsdom lays nothing out, so every rect measures zero: a client point is
+ * already box-relative, and the stage's viewport has no size to center in —
+ * centering puts the pressed world point at the stage's origin instead.
+ */
+
+import { act, render } from '@testing-library/react';
+import type { PointerContextValue } from '@weasel-js/core';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { TrialOverview } from './TrialOverview';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+  const proto = HTMLElement.prototype as unknown as Record<string, unknown>;
+  proto.setPointerCapture = vi.fn();
+  proto.releasePointerCapture = vi.fn();
+  proto.hasPointerCapture = vi.fn(() => true);
+});
+
+function pointer(el: Element, type: string, x: number, y: number, buttons = 1) {
+  el.dispatchEvent(
+    new PointerEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      pointerId: 1,
+      clientX: x,
+      clientY: y,
+      button: 0,
+      buttons,
+    }),
+  );
+}
+
+/** Content 400×300 in a 200×150 box, 6px in: scale 0.46, so box (100, 75)
+ *  is content (200, 150). */
+function mount() {
+  let store: PointerContextValue | null = null;
+  const pictured = defineInstrument<Record<string, never>, Record<string, never>>({
+    name: 'Pictured',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: (ctx) => {
+      store = ctx.trial.pointer;
+      return <div data-testid="picture" />;
+    },
+    stage: {
+      size: { width: 400, height: 300 },
+      overlay: () => (
+        <TrialOverview width={200} height={150} render={() => <div data-testid="thumb" />} />
+      ),
+    },
+  });
+  const r = render(<Lab instruments={[pictured]} defaultInstrument="Pictured" />);
+  const box = r.container.querySelector('.lk-overview__box');
+  const content = r.container.querySelector('.lk-stage__content') as HTMLElement | null;
+  if (!box || !content) throw new Error('no overview or stage');
+  return { ...r, box, content, store: () => store as PointerContextValue | null };
+}
+
+const px = (el: HTMLElement, name: string) => Number.parseFloat(el.style.getPropertyValue(name));
+
+describe('<TrialOverview>', () => {
+  it('draws the instrument-supplied content, not the instrument itself', () => {
+    const h = mount();
+    expect(h.box.querySelector('[data-testid="thumb"]')).not.toBeNull();
+    expect(h.box.querySelector('[data-testid="picture"]')).toBeNull();
+  });
+
+  it('moves the stage camera to the pressed point', () => {
+    const h = mount();
+    act(() => {
+      pointer(h.box, 'pointerdown', 100, 75);
+      pointer(h.box, 'pointerup', 100, 75, 0);
+    });
+    expect(px(h.content, '--lk-stage-x')).toBeCloseTo(-200);
+    expect(px(h.content, '--lk-stage-y')).toBeCloseTo(-150);
+  });
+
+  it('follows a drag with the camera, and never pans the stage by it', () => {
+    const h = mount();
+    act(() => {
+      pointer(h.box, 'pointerdown', 100, 75);
+      pointer(h.box, 'pointermove', 110, 75);
+      pointer(h.box, 'pointermove', 123, 75);
+      pointer(h.box, 'pointerup', 123, 75, 0);
+    });
+    // Box x 123 is content x 250 — a stage pan by the 23px drag would land
+    // elsewhere.
+    expect(px(h.content, '--lk-stage-x')).toBeCloseTo(-250);
+  });
+
+  it("publishes the pointer over it as the overview's, and the stage draws it", () => {
+    const h = mount();
+    act(() => pointer(h.box, 'pointermove', 100, 75, 0));
+    const p = h.store()?.get();
+    expect(p?.viewId).toBe('overview');
+    expect(p?.worldX).toBeCloseTo(200);
+    expect(p?.worldY).toBeCloseTo(150);
+    expect(h.container.querySelector('.lk-stage .lk-linked-cursor')).not.toBeNull();
+  });
+
+  it("publishes the stage's pointer as the stage's, so the stage draws none", () => {
+    const h = mount();
+    const host = h.container.querySelector('.lk-stage') as HTMLElement;
+    act(() => pointer(host, 'pointermove', 10, 10, 0));
+    expect(h.store()?.get()?.viewId).toBe('stage');
+    expect(h.container.querySelector('.lk-stage .lk-linked-cursor')).toBeNull();
+  });
+});