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

package/src/canvas/camera.ts

@@ -0,0 +1,62 @@
+import type { Point, ViewTransform } from '../instrument/types';
+import { DEFAULT_FRAME, type ViewportSize, type WorldFrame } from './worldSpec';
+
+/** Bounds and coordinate system a {@link zoomAt} works in. */
+export interface ZoomAtOptions {
+  /** The instrument's coordinate system, resolved against the viewport.
+   *  Omitted, `at` is measured from the element's top-left. */
+  frame?: WorldFrame;
+  min?: number;
+  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.
+ *
+ * `at` is in the element's own pixels — a cursor position, or the centre of a
+ * lens. The clamp is applied before the pan is solved, so a zoom that hits a
+ * bound still anchors on the zoom it actually reached.
+ */
+export function zoomAt(
+  view: ViewTransform,
+  factor: number,
+  at: Point,
+  { frame = DEFAULT_FRAME, min, max }: ZoomAtOptions = {},
+): ViewTransform {
+  // `pan` is measured from the frame's origin, so anchoring at the raw point
+  // 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 ratio = zoom / current;
+  return {
+    zoom,
+    pan: {
+      x: anchorX - (anchorX - view.pan.x) * ratio,
+      y: anchorY - (anchorY - view.pan.y) * ratio,
+    },
+  };
+}
+
+/** The view that puts a world point at the centre of a `size` viewport, at
+ *  `zoom`. What a lens showing a region around one point renders through. */
+export function centerOn(
+  world: Point,
+  zoom: number,
+  size: ViewportSize,
+  frame: WorldFrame = DEFAULT_FRAME,
+): ViewTransform {
+  return {
+    zoom,
+    pan: {
+      x: size.width / 2 - frame.originPx.x - world.x * zoom,
+      y: size.height / 2 - frame.originPx.y - world.y * zoom * frame.yDir,
+    },
+  };
+}

package/src/canvas/canvasCoords.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { screenToWorld, worldToScreen } from './canvasCoords';
+import { resolveFrame } from './worldSpec';
 
 describe('canvasCoords', () => {
   it('identity: zoom=1 pan=0 leaves coords unchanged', () => {
@@ -27,4 +28,29 @@ describe('canvasCoords', () => {
     expect(back.x).toBeCloseTo(p.x, 10);
     expect(back.y).toBeCloseTo(p.y, 10);
   });
+
+  describe('under a declared frame', () => {
+    const size = { width: 800, height: 600 };
+
+    it('centres world (0,0) when the origin is the middle of the viewport', () => {
+      const frame = resolveFrame({ origin: { x: 0.5, y: 0.5 } }, size);
+      const v = { zoom: 1, pan: { x: 0, y: 0 } };
+      expect(worldToScreen({ x: 0, y: 0 }, v, frame)).toEqual({ x: 400, y: 300 });
+    });
+
+    it('runs y upward when the frame says so', () => {
+      const frame = resolveFrame({ yAxis: 'up' }, size);
+      const v = { zoom: 2, pan: { x: 0, y: 0 } };
+      expect(worldToScreen({ x: 3, y: 5 }, v, frame)).toEqual({ x: 6, y: -10 });
+    });
+
+    it('round-trips through a centred, y-up frame', () => {
+      const frame = resolveFrame({ origin: { x: 0.5, y: 0.5 }, yAxis: 'up' }, size);
+      const v = { zoom: 1.5, pan: { x: 7, y: -3 } };
+      const p = { x: 12.34, y: 56.78 };
+      const back = screenToWorld(worldToScreen(p, v, frame), v, frame);
+      expect(back.x).toBeCloseTo(p.x, 10);
+      expect(back.y).toBeCloseTo(p.y, 10);
+    });
+  });
 });

package/src/canvas/canvasCoords.ts

@@ -1,17 +1,30 @@
 import type { Point, ViewTransform } from '../instrument/types';
+import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 
-/** Project a world point into screen coordinates under a view. */
-export function worldToScreen(world: Point, view: ViewTransform): Point {
+/** Project a world point into screen coordinates under a view.
+ *
+ *  `frame` is the instrument's declared coordinate system, resolved against the
+ *  viewport; omitting it gives labkit's original one — origin at the top-left,
+ *  y downward. */
+export function worldToScreen(
+  world: Point,
+  view: ViewTransform,
+  frame: WorldFrame = DEFAULT_FRAME,
+): Point {
   return {
-    x: world.x * view.zoom + view.pan.x,
-    y: world.y * view.zoom + view.pan.y,
+    x: frame.originPx.x + view.pan.x + world.x * view.zoom,
+    y: frame.originPx.y + view.pan.y + world.y * view.zoom * frame.yDir,
   };
 }
 
 /** Unproject a screen point back to world coordinates under a view. */
-export function screenToWorld(screen: Point, view: ViewTransform): Point {
+export function screenToWorld(
+  screen: Point,
+  view: ViewTransform,
+  frame: WorldFrame = DEFAULT_FRAME,
+): Point {
   return {
-    x: (screen.x - view.pan.x) / view.zoom,
-    y: (screen.y - view.pan.y) / view.zoom,
+    x: (screen.x - frame.originPx.x - view.pan.x) / view.zoom,
+    y: (screen.y - frame.originPx.y - view.pan.y) / (view.zoom * frame.yDir),
   };
 }

package/src/canvas/index.ts

@@ -1,6 +1,10 @@
 export type { CanvasStackProps } from './CanvasStack';
 export { CanvasStack } from './CanvasStack';
-export type { CanvasStackContextValue } from './CanvasStackContext';
+export type { CanvasStackContextValue, CanvasStackSurface } from './CanvasStackContext';
 export { CanvasStackContext } from './CanvasStackContext';
+export type { ZoomAtOptions } from './camera';
+export { centerOn, zoomAt } from './camera';
 export { screenToWorld, worldToScreen } from './canvasCoords';
 export type { CanvasLayerDescriptor } from './useLayerScheduler';
+export type { ViewportSize, WorldFrame, WorldSpec } from './worldSpec';
+export { applyCamera, DEFAULT_FRAME, resolveFrame } from './worldSpec';

package/src/canvas/useLayerScheduler.ts

@@ -1,18 +1,21 @@
 import { useVisibleRaf } from '@weasel-js/core';
 import { type RefObject, useEffect, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */
 export interface CanvasLayerDescriptor {
   id: string;
   visible: boolean;
-  render: (ctx: CanvasRenderingContext2D, view: ViewTransform) => void;
+  render: (ctx: CanvasRenderingContext2D, view: ViewTransform, frame: WorldFrame) => void;
 }
 
 interface SchedulerOptions {
   layers: CanvasLayerDescriptor[];
   view: ViewTransform;
+  /** The instrument's coordinate system, resolved against `size`. */
+  frame?: WorldFrame;
   canvasRefs: RefObject<Map<string, HTMLCanvasElement>>;
   size: { width: number; height: number; dpr: number };
   /** The element the stack occupies. Given one, the scheduler also stops while
@@ -23,6 +26,7 @@ interface SchedulerOptions {
 export function useLayerScheduler({
   layers,
   view,
+  frame = DEFAULT_FRAME,
   canvasRefs,
   size,
   host,
@@ -44,7 +48,7 @@ export function useLayerScheduler({
   // biome-ignore lint/correctness/useExhaustiveDependencies: re-mark dirty when view or size changes
   useEffect(() => {
     for (const layer of layers) dirty.current.add(layer.id);
-  }, [view, size, layers]);
+  }, [view, frame, size, layers]);
 
   // 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
@@ -67,7 +71,7 @@ export function useLayerScheduler({
         ctx.save();
         ctx.setTransform(size.dpr, 0, 0, size.dpr, 0, 0);
         ctx.clearRect(0, 0, size.width, size.height);
-        layer.render(ctx, view);
+        layer.render(ctx, view, frame);
         ctx.restore();
       }
       dirty.current.clear();

package/src/canvas/usePanZoom.test.ts

@@ -2,13 +2,15 @@ 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 { screenToWorld } from './canvasCoords';
 import { type UsePanZoomOptions, usePanZoom } from './usePanZoom';
+import { resolveFrame } from './worldSpec';
 
-function wheelEvent(deltaY: number): WheelEvent<HTMLElement> {
+function wheelEvent(deltaY: number, cursor = { x: 0, y: 0 }): WheelEvent<HTMLElement> {
   return {
     deltaY,
-    clientX: 0,
-    clientY: 0,
+    clientX: cursor.x,
+    clientY: cursor.y,
     preventDefault: () => {},
     currentTarget: { getBoundingClientRect: () => ({ left: 0, top: 0, width: 0, height: 0 }) },
   } as unknown as WheelEvent<HTMLElement>;
@@ -26,8 +28,8 @@ function setup(initialView: ViewTransform, options?: Partial<UsePanZoomOptions>)
     (props: { view: ViewTransform }) => usePanZoom({ ...options, view: props.view, onViewChange }),
     { initialProps: { view: initialView } },
   );
-  const wheel = (deltaY: number): ViewTransform => {
-    act(() => result.current.onWheel(wheelEvent(deltaY)));
+  const wheel = (deltaY: number, cursor?: { x: number; y: number }): ViewTransform => {
+    act(() => result.current.onWheel(wheelEvent(deltaY, cursor)));
     rerender({ view });
     return view;
   };
@@ -77,4 +79,33 @@ describe('usePanZoom', () => {
     const zoomedOut = wheel(1_000_000);
     expect(zoomedOut.zoom).toBeCloseTo(0.1, 5);
   });
+
+  describe('under a declared frame', () => {
+    const size = { width: 1430, height: 870 };
+
+    it('keeps the world point under the cursor fixed in a centred, y-up frame', () => {
+      const frame = resolveFrame({ origin: { x: 0.5, y: 0.5 }, yAxis: 'up' }, size);
+      const start: ViewTransform = { zoom: 1600, pan: { x: 0, y: 0 } };
+      const { wheel } = setup(start, { frame });
+      const cursor = { x: 900, y: 200 };
+
+      const before = screenToWorld(cursor, start, frame);
+      const after = screenToWorld(cursor, wheel(120, cursor), frame);
+
+      expect(after.x).toBeCloseTo(before.x, 6);
+      expect(after.y).toBeCloseTo(before.y, 6);
+    });
+
+    it('anchors on the element top-left when no frame is declared', () => {
+      const start: ViewTransform = { zoom: 4, pan: { x: 0, y: 0 } };
+      const { wheel } = setup(start);
+      const cursor = { x: 300, y: 120 };
+
+      const before = screenToWorld(cursor, start);
+      const after = screenToWorld(cursor, wheel(-120, cursor));
+
+      expect(after.x).toBeCloseTo(before.x, 6);
+      expect(after.y).toBeCloseTo(before.y, 6);
+    });
+  });
 });

package/src/canvas/usePanZoom.ts

@@ -1,5 +1,7 @@
 import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import { zoomAt } from './camera';
+import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 
 export interface UsePanZoomOptions {
   view: ViewTransform;
@@ -8,6 +10,10 @@ export interface UsePanZoomOptions {
    *  whatever is passed here if it would otherwise exclude it. */
   minZoom?: number;
   maxZoom?: number;
+  /** The instrument's coordinate system, resolved against the viewport. The
+   *  wheel anchors in this frame; omitting it anchors at the element's
+   *  top-left, which is what labkit did before a frame could be declared. */
+  frame?: WorldFrame;
 }
 
 export interface PanZoomHandlers {
@@ -37,6 +43,7 @@ export function usePanZoom({
   onViewChange,
   minZoom = 0.1,
   maxZoom = 32,
+  frame = DEFAULT_FRAME,
 }: UsePanZoomOptions): PanZoomHandlers {
   const dragRef = useRef<DragState | null>(null);
   const viewRef = useRef(view);
@@ -50,23 +57,21 @@ export function usePanZoom({
     (e: WheelEvent<HTMLElement>) => {
       e.preventDefault();
       const rect = e.currentTarget.getBoundingClientRect();
-      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 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,
-      };
-      onViewChange({ zoom: nextZoom, pan: nextPan });
+      onViewChange(
+        zoomAt(
+          viewRef.current,
+          Math.exp(-e.deltaY * 0.001),
+          { x: e.clientX - rect.left, y: e.clientY - rect.top },
+          {
+            frame,
+            min: initialZoom == null ? minZoom : Math.min(minZoom, initialZoom),
+            max: initialZoom == null ? maxZoom : Math.max(maxZoom, initialZoom),
+          },
+        ),
+      );
     },
-    [onViewChange, minZoom, maxZoom],
+    [onViewChange, minZoom, maxZoom, frame],
   );
 
   const onPointerDown = useCallback((e: PointerEvent<HTMLElement>) => {

package/src/canvas/worldSpec.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { worldToScreen } from './canvasCoords';
+import { applyCamera, DEFAULT_FRAME, resolveFrame } from './worldSpec';
+
+const SIZE = { width: 800, height: 600 };
+
+describe('resolveFrame', () => {
+  it('defaults to labkit original convention: origin top-left, y down', () => {
+    expect(resolveFrame(undefined, SIZE)).toEqual(DEFAULT_FRAME);
+  });
+
+  it('places a fractional origin at that fraction of the viewport', () => {
+    const frame = resolveFrame({ origin: { x: 0.5, y: 0.5 } }, SIZE);
+    expect(frame.originPx).toEqual({ x: 400, y: 300 });
+  });
+
+  it('reads yAxis up as a negated y direction', () => {
+    expect(resolveFrame({ yAxis: 'up' }, SIZE).yDir).toBe(-1);
+    expect(resolveFrame({ yAxis: 'down' }, SIZE).yDir).toBe(1);
+  });
+});
+
+/** Records the transform calls and reports where a world point lands, so the
+ *  camera can be checked against `worldToScreen` without a real 2D context. */
+function recordingCtx() {
+  let m = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+  return {
+    translate(x: number, y: number) {
+      m = { ...m, e: m.e + m.a * x + m.c * y, f: m.f + m.b * x + m.d * y };
+    },
+    scale(x: number, y: number) {
+      m = { ...m, a: m.a * x, b: m.b * x, c: m.c * y, d: m.d * y };
+    },
+    project(p: { x: number; y: number }) {
+      return { x: m.a * p.x + m.c * p.y + m.e, y: m.b * p.x + m.d * p.y + m.f };
+    },
+  };
+}
+
+describe('applyCamera', () => {
+  const size = { width: 800, height: 600 };
+  const view = { zoom: 1.5, pan: { x: 7, y: -3 } };
+  const world = { x: 12, y: 34 };
+
+  it('lands a world point where worldToScreen says, with no frame', () => {
+    const ctx = recordingCtx();
+    applyCamera(ctx as unknown as CanvasRenderingContext2D, view);
+    const got = ctx.project(world);
+    const want = worldToScreen(world, view);
+    expect(got.x).toBeCloseTo(want.x, 10);
+    expect(got.y).toBeCloseTo(want.y, 10);
+  });
+
+  it('lands a world point where worldToScreen says, in a centred y-up frame', () => {
+    const frame = resolveFrame({ origin: { x: 0.5, y: 0.5 }, yAxis: 'up' }, size);
+    const ctx = recordingCtx();
+    applyCamera(ctx as unknown as CanvasRenderingContext2D, view, frame);
+    const got = ctx.project(world);
+    const want = worldToScreen(world, view, frame);
+    expect(got.x).toBeCloseTo(want.x, 10);
+    expect(got.y).toBeCloseTo(want.y, 10);
+  });
+});

package/src/canvas/worldSpec.ts

@@ -0,0 +1,48 @@
+import type { Point, ViewTransform } from '../instrument/types';
+
+/** How an instrument's world sits on the canvas, independent of the camera.
+ *  The defaults reproduce the convention labkit shipped before this existed:
+ *  world (0,0) at the element's top-left, y growing downward. */
+export interface WorldSpec {
+  /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.
+   *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */
+  origin?: Point;
+  /** Which way the world y axis runs on screen. Default `'down'`. */
+  yAxis?: 'down' | 'up';
+}
+
+/** A viewport's CSS-pixel size. */
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+
+/** A `WorldSpec` resolved against a viewport: what the coordinate helpers,
+ *  the camera and the wheel all read. */
+export interface WorldFrame {
+  /** Screen position of world (0,0) at `pan` zero. */
+  originPx: Point;
+  yDir: 1 | -1;
+}
+
+export const DEFAULT_FRAME: WorldFrame = { originPx: { x: 0, y: 0 }, yDir: 1 };
+
+export function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame {
+  if (!spec) return DEFAULT_FRAME;
+  const origin = spec.origin ?? { x: 0, y: 0 };
+  return {
+    originPx: { x: origin.x * size.width, y: origin.y * size.height },
+    yDir: spec.yAxis === 'up' ? -1 : 1,
+  };
+}
+
+/** Put a 2D context into the instrument's world coordinates, so a layer's
+ *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */
+export function applyCamera(
+  ctx: CanvasRenderingContext2D,
+  view: ViewTransform,
+  frame: WorldFrame = DEFAULT_FRAME,
+): void {
+  ctx.translate(frame.originPx.x + view.pan.x, frame.originPx.y + view.pan.y);
+  ctx.scale(view.zoom, view.zoom * frame.yDir);
+}

package/src/chrome/builtins.test.ts

@@ -8,6 +8,9 @@ import type { TrialChromeContext } from './types';
 
 const ctx: TrialChromeContext = {
   trialId: 't1',
+  undockedPanels: [],
+  undockPanel: () => {},
+  dockPanel: () => {},
   instrumentName: 'Stub',
   isLastTrial: false,
   zoom: 1,
@@ -16,6 +19,8 @@ const ctx: TrialChromeContext = {
   canRedo: false,
   undo: () => {},
   redo: () => {},
+  loupeOn: false,
+  toggleLoupe: () => {},
   configFields: [],
   configSchema: fromConfigFields([]),
   config: {},
@@ -47,7 +52,13 @@ function ids(instrument: Instrument, c: TrialChromeContext = ctx): string[] {
 
 describe('builtinContributions', () => {
   it('always contributes the trial actions', () => {
-    expect(ids(bare)).toEqual(['snapshot', 'clone', 'reset', 'close']);
+    expect(ids(bare)).toEqual(['clone', 'reset', 'snapshot', 'close']);
+  });
+
+  it('puts snapshot in the title bar with clone and reset, not the toolbar', () => {
+    const snapshot = builtinContributions(bare, ctx).find((c) => c.id === 'snapshot');
+    expect(snapshot?.region).toBe('titlebar');
+    expect(snapshot?.end).toBe(true);
   });
 
   it('contributes undo and redo only when the instrument declares undo', () => {
@@ -56,6 +67,25 @@ describe('builtinContributions', () => {
     expect(ids({ ...bare, undo: {} })).toContain('redo');
   });
 
+  it('contributes the loupe toggle only when the instrument declares one', () => {
+    expect(ids(bare)).not.toContain('loupe');
+    expect(ids({ ...bare, loupe: true })).toContain('loupe');
+    expect(ids({ ...bare, loupe: { render: () => null } })).toContain('loupe');
+  });
+
+  it('offers the loupe to a DOM instrument, which declares no canvas', () => {
+    const contributions = builtinContributions({ ...bare, loupe: true }, ctx);
+    const loupe = contributions.find((c) => c.id === 'loupe');
+    expect(loupe?.region).toBe('toolbar');
+  });
+
+  it('reports the loupe switch position, so the button reads as held', () => {
+    const off = builtinContributions({ ...bare, loupe: true }, ctx);
+    const on = builtinContributions({ ...bare, loupe: true }, { ...ctx, loupeOn: true });
+    expect(off.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: false });
+    expect(on.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: true });
+  });
+
   it('puts zoom controls in the viewport region, not the toolbar', () => {
     const zoomIn = builtinContributions(withCanvas, ctx).find((c) => c.id === 'zoom-in');
     expect(zoomIn?.region).toBe('viewport');

package/src/chrome/builtins.tsx

@@ -2,6 +2,7 @@ import {
   CloneIcon,
   CloseIcon,
   FitIcon,
+  LoupeIcon,
   RedoIcon,
   ResetIcon,
   SnapshotIcon,
@@ -9,6 +10,9 @@ import {
   ZoomInIcon,
   ZoomOutIcon,
 } from '@weasel-js/ui';
+import { ExportMenu } from '../annotations/ExportMenu';
+import { MarkList } from '../annotations/MarkList';
+import { ANNOTATION_TOOLS } from '../annotations/toolMap';
 import type { ControlRenderer } from '../config/types';
 import { ControlPanel } from '../controls/ControlPanel';
 import type { Instrument } from '../instrument/types';
@@ -33,7 +37,9 @@ export function builtinContributions(
   const out: TrialContribution[] = [];
   const zoom = ctx.zoom;
 
-  if (instrument.undo != null) {
+  // Weasel history is the undo authority for marks, so declaring `annotations`
+  // gets the buttons whether or not the instrument also declares `undo`.
+  if (instrument.undo != null || instrument.annotations != null) {
     out.push({
       id: 'undo',
       region: 'toolbar',
@@ -60,10 +66,16 @@ export function builtinContributions(
     });
   }
 
+  // Declaring `annotations` provides the drawing palette, the way declaring
+  // `tools` provides the instrument's own; both write the same tool slot.
   // A tool id shares the contribution namespace, so a tool called `close`
-  // collides with the built-in close button and throws. Both are contributions
-  // to one trial's chrome.
-  for (const t of instrument.tools?.tools ?? []) {
+  // collides with the built-in close button and throws — and so do two tools
+  // of the same name from these two sources.
+  const tools = [
+    ...(instrument.annotations ? ANNOTATION_TOOLS : []),
+    ...(instrument.tools?.tools ?? []),
+  ];
+  for (const t of tools) {
     out.push({
       id: t.id,
       region: 'palette',
@@ -72,6 +84,20 @@ export function builtinContributions(
     });
   }
 
+  if (instrument.loupe != null) {
+    out.push({
+      id: 'loupe',
+      region: 'toolbar',
+      group: 'view',
+      item: {
+        icon: LoupeIcon,
+        label: 'Loupe',
+        pressed: ctx.loupeOn,
+        onActivate: ctx.toggleLoupe,
+      },
+    });
+  }
+
   // Zoom acts on the view of the trial, so it is a viewport control. A trial
   // holding a non-2D view reports zoom as null and gets none of this.
   if (instrument.canvas != null && zoom !== null) {
@@ -122,6 +148,26 @@ export function builtinContributions(
     });
   }
 
+  if (instrument.annotations != null) {
+    // A popover, so it takes the `render` escape: the panel picks a target,
+    // and an icon button cannot ask which one.
+    out.push({
+      id: 'export',
+      region: 'toolbar',
+      group: 'trial',
+      end: true,
+      render: () => <ExportMenu />,
+    });
+    out.push({
+      id: 'marks',
+      region: 'sidebar',
+      item: {
+        title: 'Marks',
+        body: <MarkList meaning={instrument.annotations.meaning} config={ctx.config} />,
+      },
+    });
+  }
+
   if (Object.keys(ctx.configSchema.group.children).length > 0) {
     out.push({
       id: 'settings',
@@ -140,17 +186,6 @@ export function builtinContributions(
     });
   }
 
-  out.push({
-    id: 'snapshot',
-    region: 'toolbar',
-    group: 'history',
-    item: {
-      icon: SnapshotIcon,
-      label: 'Save snapshot',
-      shortcut: 'Mod+S',
-      onActivate: () => ctx.saveSnapshot(),
-    },
-  });
   if (ctx.savedSnapshots.length > 0) {
     // A picker is not an icon button, so it takes the render escape. Held at
     // `selectedKey={null}` so it stays a "load one" action rather than
@@ -176,18 +211,27 @@ export function builtinContributions(
   }
   out.push({
     id: 'clone',
-    region: 'toolbar',
-    group: 'trial',
+    region: 'titlebar',
     end: true,
     item: { icon: CloneIcon, label: 'Clone trial', onActivate: ctx.clone },
   });
   out.push({
     id: 'reset',
-    region: 'toolbar',
-    group: 'trial',
+    region: 'titlebar',
     end: true,
     item: { icon: ResetIcon, label: 'Reset trial', onActivate: ctx.reset },
   });
+  out.push({
+    id: 'snapshot',
+    region: 'titlebar',
+    end: true,
+    item: {
+      icon: SnapshotIcon,
+      label: 'Save snapshot',
+      shortcut: 'Mod+S',
+      onActivate: () => ctx.saveSnapshot(),
+    },
+  });
   out.push({
     id: 'close',
     region: 'titlebar',

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import type { TrialChromeContext, TrialContribution } from '../types';
 import { PaletteRegion } from './PaletteRegion';
@@ -33,4 +33,25 @@ describe('PaletteRegion', () => {
     screen.getByRole('button', { name: 'brush' }).click();
     expect(setActiveTool).toHaveBeenCalledWith('brush');
   });
+
+  it('puts exactly one tool in the tab order', () => {
+    render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
+    expect(screen.getByRole('button', { name: 'brush' })).toHaveAttribute('tabindex', '0');
+    expect(screen.getByRole('button', { name: 'eraser' })).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('walks the vertical strip with ArrowDown, and leaves ArrowRight to the page', () => {
+    render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
+    const strip = screen.getByRole('toolbar', { name: 'Tools' });
+    const brush = screen.getByRole('button', { name: 'brush' });
+    const eraser = screen.getByRole('button', { name: 'eraser' });
+
+    brush.focus();
+    fireEvent.keyDown(strip, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(eraser);
+    expect(eraser).toHaveAttribute('tabindex', '0');
+
+    fireEvent.keyDown(strip, { key: 'ArrowRight' });
+    expect(document.activeElement).toBe(eraser);
+  });
 });