@weasel-js/labkit 1.4.4 → 1.5.1

package/dist/surface/index.d.ts

@@ -42,6 +42,11 @@ interface SurfaceFrame {
         width: number;
         height: number;
     };
+    /** The tile geometry changed this frame — a tile moved, resized, appeared or
+     *  went away, or the dpr did. Every tile is dirty on such a frame, but the
+     *  pixels a tile vacated are in no tile's scissor now, so the owner clears
+     *  the whole buffer. `<Lab>` does; a host owning its own surface must too. */
+    retiled: boolean;
 }
 /** The invalidators and the two ref callbacks that publish geometry. */
 interface SurfaceHandle {
@@ -53,6 +58,12 @@ interface SurfaceHandle {
      *  moved something a ResizeObserver cannot see. */
     invalidateRects: () => void;
     registerTile: (id: string, el: HTMLElement | null) => void;
+    /** Register a tenant's whole-buffer clear. Every one registered runs, before
+     *  any painter, on a frame where the tile geometry changed — the pixels a
+     *  tile vacated are in no scissor now, and only the context that drew them
+     *  can erase them. Backend-agnostic by necessity: labkit owns the canvas,
+     *  never the context. */
+    registerClear: (id: string, clear: SurfaceClear) => () => void;
     /** Subscribe a tile to the frames it is dirty on. A tile paints on its own
      *  loop, so this is how the surface wakes one: a resize of the shared buffer
      *  clears every tile, not only the one that moved. */
@@ -65,6 +76,12 @@ interface SurfaceHandle {
 /** What a tile's painter is handed: where it sits on the surface now, and the
  *  frame that dirtied it. */
 type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
+/** Erase the whole shared buffer. Device pixels, because that is what a GL
+ *  viewport takes. */
+type SurfaceClear = (size: {
+    width: number;
+    height: number;
+}, dpr: number) => void;
 interface UseTiledSurfaceOptions {
     onFrame: (frame: SurfaceFrame) => void;
 }
@@ -72,13 +89,33 @@ declare function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHa
 
 /** Null when no surface owner is above — a lab with no shared surface at all. */
 declare const SurfaceContext: react.Context<SurfaceHandle | null>;
-/** The buffer the surface's tiles paint into. Null until the owner's canvas is
- *  mounted, and for an owner that keeps its surface unpainted. */
-declare const SurfaceCanvasContext: react.Context<HTMLCanvasElement | null>;
+/**
+ * Which of the two stacked buffers a tenant paints into.
+ *
+ * `'over'` sits above the trial DOM: right for marks that annotate an
+ * instrument, which is what the surface was built for and so the default.
+ * `'under'` sits below it, which is what an opaque renderer needs — a tile that
+ * fills its pane hides anything the pane's own DOM draws, so a 3D viewport on
+ * the over-buffer has to paint its own chrome into the backend rather than
+ * putting a label or a button in the pane.
+ *
+ * Both exist for the lifetime of the surface and share one set of tile rects,
+ * so a lab can hold an annotated 2D trial and an opaque 3D one at once.
+ */
+type SurfaceLayer = 'over' | 'under';
+/** The two buffers a surface owner publishes. A member is null until the
+ *  owner's canvas mounts, and for an owner that keeps its surface unpainted. */
+interface SurfaceCanvases {
+    over: HTMLCanvasElement | null;
+    under: HTMLCanvasElement | null;
+}
+/** The buffers the surface's tiles paint into. */
+declare const SurfaceCanvasContext: react.Context<SurfaceCanvases>;
 
-/** The surface's shared buffer, or null where nothing paints one. What a tile
- *  hands to `paintInto`. */
-declare function useSurfaceCanvas(): HTMLCanvasElement | null;
+/** One of the surface's two shared buffers, or null where nothing paints one.
+ *  What a tile hands to `paintInto`. See {@link SurfaceLayer} for which to ask
+ *  for; the default is the one over the trial DOM. */
+declare function useSurfaceCanvas(layer?: SurfaceLayer): HTMLCanvasElement | null;
 /** The surface above, or null. Use this where a surface is genuinely optional. */
 declare function useSurfaceOptional(): SurfaceHandle | null;
 /** The surface above. Throws where a caller cannot work without one. */
@@ -105,4 +142,4 @@ declare function useTileId(id: string): string;
 declare function useSurfaceTile(id: string): (el: HTMLElement | null) => void;
 
 export { SurfaceCanvasContext, SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTiledSurface };
-export type { Box, Rect, SurfaceFrame, SurfaceHandle, TilePainter, UseTiledSurfaceOptions };
+export type { Box, Rect, SurfaceCanvases, SurfaceClear, SurfaceFrame, SurfaceHandle, SurfaceLayer, TilePainter, UseTiledSurfaceOptions };

package/dist/surface/index.js

@@ -1,4 +1,5 @@
-export { SurfaceCanvasContext, SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTiledSurface } from '../chunk-FQMJUVHJ.js';
+export { composeRects, rectsEqual, toDeviceRect, useTiledSurface } from '../chunk-IJJUK4FU.js';
+export { SurfaceCanvasContext, SurfaceContext, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId } from '../chunk-WIG6XHJ7.js';
 import '../chunk-2YILQ7Y5.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/ui/layers/index.js

@@ -1,3 +1,3 @@
-export { c3 as LayerStack } from '../../chunk-W3ECWC2K.js';
+export { c4 as LayerStack } from '../../chunk-T3EC2DXD.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,10 +1,8 @@
-export { a0 as UndoCapability } from '../_dts/frac-z7ker2Vx.js';
+export { at as UndoCapability } from '../_dts/frac-B4okC2lX.js';
 import 'react';
-import '../_dts/types-B9_zrHmb.js';
+import '../_dts/types-DzoNY1pO.js';
 import '@weasel-js/core';
-import '../_dts/PrefsForm.d-DDHFANkc.js';
-import '../_dts/types-x92Kfeme.js';
-import '../_dts/types-BP2OCcpg.js';
+import '../_dts/PrefsForm.d-DPy9I8It.js';
 import '../_dts/types-DJ79Tg5J.js';
 
 /** A subscriber to a named event. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -42,6 +42,10 @@
       "types": "./dist/controls/index.d.ts",
       "import": "./dist/controls/index.js"
     },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
     "./canvas": {
       "types": "./dist/canvas/index.d.ts",
       "import": "./dist/canvas/index.js"
@@ -107,18 +111,21 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "dev:schema": "LABKIT_EXAMPLE=schema-lab vite",
-    "dev:annotate": "LABKIT_EXAMPLE=annotate-lab vite"
+    "dev:annotate": "LABKIT_EXAMPLE=annotate-lab vite",
+    "dev:3d": "LABKIT_EXAMPLE=3d-lab vite"
   },
   "peerDependencies": {
-    "@weasel-js/core": "1.4.4",
+    "@weasel-js/core": "1.5.1",
+    "@weasel-js/theme": "1.5.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/loupe": "1.4.4",
-    "@weasel-js/svg": "1.4.4",
-    "@weasel-js/theme": "1.4.4",
-    "@weasel-js/ui": "1.4.4",
+    "@weasel-js/geom": "1.5.1",
+    "@weasel-js/kernel3d": "1.5.1",
+    "@weasel-js/loupe": "1.5.1",
+    "@weasel-js/svg": "1.5.1",
+    "@weasel-js/ui": "1.5.1",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -129,7 +136,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.4.4",
+    "@weasel-js/modes": "1.5.1",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationOverlay.tsx

@@ -6,8 +6,9 @@ import {
   type View,
   WeaselProvider,
 } from '@weasel-js/core';
-import { type CSSProperties, useEffect, useRef, useState } from 'react';
-import { createPortal } from 'react-dom';
+import { type CSSProperties, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { createPortal, flushSync } from 'react-dom';
+import { CameraWheelContext } from '../canvas/CameraWheelContext';
 import type { Rect } from '../surface/rect';
 import { useSurfaceCanvas, useSurfaceOptional, useTileId } from '../surface/useSurfaceTile';
 import { createMarkDrawOne } from './drawOne';
@@ -34,7 +35,7 @@ export interface AnnotationOverlayProps {
   config: unknown;
   /** The trial's resolved tool slot. */
   activeToolId: string | null;
-  /** The instrument's vocabulary, for a status's colour. */
+  /** The instrument's vocabulary, for a status's color. */
   meaning?: AnnotationMeaning;
 }
 
@@ -123,10 +124,57 @@ export function AnnotationOverlay({
     [surface, tileId],
   );
 
+  // Erases the whole shared buffer when the tiles move: a tile that moved took
+  // its scissor with it, and what it painted last frame stays where it was.
+  // Each renderer on the context re-applies its viewport and scissor per frame,
+  // so resetting them here is safe.
+  // Only once this pane has painted: a bare `getContext` on a buffer no
+  // renderer has opened creates the context without the stencil buffer marks
+  // need, and every later request gets that context back.
+  const painted = useRef(false);
+  const canvasRef = useRef(canvas);
+  if (canvasRef.current !== canvas) painted.current = false;
+  canvasRef.current = canvas;
+  const unsubscribeFrame = useRef<(() => void) | null>(null);
+  const attachSceneCanvas = useCallback((api: SceneCanvasApi | null) => {
+    sceneCanvas.current = api;
+    unsubscribeFrame.current?.();
+    unsubscribeFrame.current = api
+      ? api.subscribeFrame(() => {
+          painted.current = true;
+        })
+      : null;
+  }, []);
+  useEffect(() => {
+    if (!surface) return;
+    return surface.registerClear(tileId, (size, dpr) => {
+      if (!painted.current) return;
+      const gl = canvasRef.current?.getContext('webgl2');
+      if (!gl) return;
+      gl.disable(gl.SCISSOR_TEST);
+      gl.viewport(0, 0, Math.round(size.width * dpr), Math.round(size.height * dpr));
+      gl.clearColor(0, 0, 0, 0);
+      gl.clear(gl.COLOR_BUFFER_BIT | gl.STENCIL_BUFFER_BIT);
+    });
+  }, [surface, tileId]);
+
+  // The box is portalled out of whatever the picture sits in, so a wheel over
+  // a mark would never reach the trial's camera without being handed to it.
+  const wheelSlot = useContext(CameraWheelContext);
+  useEffect(() => {
+    if (!input || !wheelSlot) return;
+    const wheel = (e: WheelEvent): void => wheelSlot.current?.(e);
+    input.addEventListener('wheel', wheel, { passive: false });
+    return () => input.removeEventListener('wheel', wheel);
+  }, [input, wheelSlot]);
+
   useEffect(
     () =>
       surface?.registerPainter(tileId, (next) => {
-        setRect((prev) => (sameRect(prev, next) ? prev : next));
+        // Committed before the redraw is asked for: the renderer reads its
+        // position from the last render, so a redraw landing first repaints the
+        // tile where it was — after this frame's clear, which leaves a ghost.
+        flushSync(() => setRect((prev) => (sameRect(prev, next) ? prev : next)));
         // The shared buffer was cleared if it resized this frame; this pane's
         // own loop has no way to know that.
         sceneCanvas.current?.requestRedraw();
@@ -178,6 +226,9 @@ export function AnnotationOverlay({
         ref={setInput}
         className="lk-annotate__input"
         data-annotation-target={id}
+        // Pass-through while the rail holds a tool that makes no marks, so the
+        // instrument under the overlay stays clickable.
+        data-idle={annotationToolInfo(activeToolId) ? undefined : ''}
         role="application"
         aria-label={`Annotations on ${id}`}
         // biome-ignore lint/a11y/noNoninteractiveTabindex: role="application" IS the interactive case — a region with its own keymap. The rule's allowed-role list stops at the native widget roles and does not include it, and the gesture dispatcher listens on this element, so without focus no tool's keyboard binding ever fires.
@@ -190,7 +241,7 @@ export function AnnotationOverlay({
         <WeaselProvider isolate>
           <ToolBridge toolId={annotationToolInfo(activeToolId)?.weaselTool ?? 'select'} />
           <SceneCanvas<AnnotationData, 'marks', WorldRect>
-            ref={sceneCanvas}
+            ref={attachSceneCanvas}
             scene={scene}
             width={rect.w}
             height={rect.h}

package/src/annotations/Annotations.less

@@ -8,6 +8,10 @@
   width: var(--lk-anno-w);
   height: var(--lk-anno-h);
   z-index: 2;
+
+  &[data-idle] {
+    pointer-events: none;
+  }
 }
 
 // The sidebar list of marks. One row per mark: what it is, where it is, what

package/src/annotations/Annotations.overlay.test.tsx

@@ -8,11 +8,12 @@
  * marks themselves are proved by `paint.test.ts` (pure) and by a screenshot.
  */
 import { act, render } from '@testing-library/react';
-import { StrictMode, useRef } from 'react';
+import { StrictMode, useMemo, useRef } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CameraWheelContext, type CameraWheelSlot } from '../canvas/CameraWheelContext';
 import { TrialIdProvider } from '../state/context';
 import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
-import type { SurfaceHandle } from '../surface/useTiledSurface';
+import type { SurfaceClear, SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { AnnotationTargets } from './AnnotationTargets';
 import { createAnnotationStore } from './store';
@@ -38,10 +39,33 @@ beforeAll(() => {
   ) as unknown as HTMLCanvasElement['getContext'];
 });
 
-function Harness({ toolId = 'rect' }: { toolId?: string }) {
+function Harness({
+  toolId = 'rect',
+  onRegisterClear,
+  canvas = null,
+}: {
+  toolId?: string;
+  /** Told each tile a clear is registered for, and handed the clear. */
+  onRegisterClear?: (id: string, clear: SurfaceClear) => void;
+  /** The shared buffer the overlays paint into. */
+  canvas?: HTMLCanvasElement | null;
+}) {
   const a = useRef<HTMLDivElement | null>(null);
   const b = useRef<HTMLDivElement | null>(null);
-  const surface = useTiledSurface({ onFrame: () => {} });
+  const tiled = useTiledSurface({ onFrame: () => {} });
+  const surface = useMemo<SurfaceHandle>(
+    () =>
+      onRegisterClear
+        ? {
+            ...tiled,
+            registerClear: (id, clear) => {
+              onRegisterClear(id, clear);
+              return tiled.registerClear(id, clear);
+            },
+          }
+        : tiled,
+    [tiled, onRegisterClear],
+  );
   const annotations = useRef(createAnnotationStore({ targets: () => [] })).current;
 
   const capability: AnnotationsCapability = {
@@ -53,7 +77,7 @@ function Harness({ toolId = 'rect' }: { toolId?: string }) {
 
   return (
     <SurfaceContext.Provider value={surface}>
-      <SurfaceCanvasContext.Provider value={null}>
+      <SurfaceCanvasContext.Provider value={{ over: canvas, under: null }}>
         <div
           data-testid="stage"
           ref={(el) => {
@@ -122,6 +146,26 @@ describe('<AnnotationTargets>', () => {
     expect(boxes[1]?.style.getPropertyValue('--lk-anno-h')).toBe('100px');
   });
 
+  it('takes input while a mark tool is held, and passes it through otherwise', () => {
+    const drawing = render(<Harness toolId="rect" />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(drawing.container.querySelector('.lk-annotate__input')?.hasAttribute('data-idle')).toBe(
+      false,
+    );
+    drawing.unmount();
+
+    // `pointer` is in the rail but not in the tool map: the instrument under the overlay stays clickable.
+    const idle = render(<Harness toolId="pointer" />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(idle.container.querySelector('.lk-annotate__input')?.hasAttribute('data-idle')).toBe(
+      true,
+    );
+  });
+
   it('lands the boxes in the surface container, not among the instrument DOM', () => {
     const { container } = render(<Harness />, { wrapper: StrictMode });
     act(() => {
@@ -133,6 +177,61 @@ describe('<AnnotationTargets>', () => {
     }
   });
 
+  it('hands a wheel over a target to the trial camera', () => {
+    // The input box is portalled into the surface container, so the wheel
+    // would otherwise bubble past the stage the picture sits on.
+    const wheel = vi.fn();
+    const slot: CameraWheelSlot = { current: wheel };
+    const { container } = render(
+      <CameraWheelContext.Provider value={slot}>
+        <Harness />
+      </CameraWheelContext.Provider>,
+      { wrapper: StrictMode },
+    );
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    const box = container.querySelector('.lk-annotate__input');
+    box?.dispatchEvent(new WheelEvent('wheel', { bubbles: true, cancelable: true }));
+    expect(wheel).toHaveBeenCalledTimes(1);
+  });
+
+  it('registers a clear for each tile, so a moved mark leaves nothing behind', () => {
+    // A proxy: jsdom has no WebGL2, so the clear itself cannot run here. Without
+    // one registered, a tile that moves leaves its last frame's marks painted
+    // where it used to be — which the surface only erases through a clear.
+    const registered = vi.fn();
+    render(<Harness onRegisterClear={registered} />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(new Set(registered.mock.calls.map((call) => call[0])).size).toBe(2);
+  });
+
+  it('never opens the shared context itself when it clears', () => {
+    // A bare `getContext('webgl2')` on a buffer nobody has opened yet creates
+    // the context with default attributes, and the renderer's later request for
+    // a stencil buffer then gets that one back: every mark paints nothing, with
+    // no error anywhere. jsdom opens no context, so the call is the proxy.
+    const clears: SurfaceClear[] = [];
+    const canvas = document.createElement('canvas');
+    const { unmount } = render(
+      <Harness canvas={canvas} onRegisterClear={(_id, clear) => clears.push(clear)} />,
+      { wrapper: StrictMode },
+    );
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    // The prototype is already a mock file-wide, so the spy arrives holding
+    // the renderer's own attempts to open it.
+    const open = vi.spyOn(canvas, 'getContext');
+    open.mockClear();
+    for (const clear of clears) clear({ width: 800, height: 600 }, 1);
+    expect(open).not.toHaveBeenCalled();
+    // Before the frame stubs come off: the canvas's own loop cancels through them.
+    unmount();
+  });
+
   it('takes its tiles back out on unmount', () => {
     const { container, unmount } = render(<Harness />, { wrapper: StrictMode });
     act(() => {
@@ -206,7 +305,7 @@ describe('two trials of one instrument', () => {
       handle = surface;
       return (
         <SurfaceContext.Provider value={surface}>
-          <SurfaceCanvasContext.Provider value={null}>
+          <SurfaceCanvasContext.Provider value={{ over: null, under: null }}>
             <div
               ref={(el) => {
                 if (!el) return;

package/src/annotations/drawOne.test.ts

@@ -23,7 +23,7 @@ const strokeOf = (cmds: ReturnType<ReturnType<typeof createMarkDrawOne>>) => {
 };
 
 describe('the draw callback marks share between the screen and an export', () => {
-  it("paints a mark in its status's colour", () => {
+  it("paints a mark in its status's color", () => {
     const drawOne = createMarkDrawOne({
       content: CONTENT,
       config: {},

package/src/annotations/drawOne.ts

@@ -12,7 +12,7 @@ export interface MarkDrawOptions {
   positionDependsOn?: readonly string[];
   /** The trial's config at the time of the draw. */
   config: unknown;
-  /** The instrument's vocabulary, for a status's colour. */
+  /** The instrument's vocabulary, for a status's color. */
   meaning?: AnnotationMeaning;
 }
 
@@ -20,7 +20,7 @@ export interface MarkDrawOptions {
  * How one mark is drawn — shared by the pane on screen and by an export.
  *
  * One function rather than two call sites building their own, because an
- * export that resolves a status colour or a stale dash differently from the
+ * export that resolves a status color or a stale dash differently from the
  * screen produces a picture nobody was looking at.
  */
 export function createMarkDrawOne(

package/src/annotations/paint.test.ts

@@ -102,7 +102,7 @@ describe('markCommands', () => {
 });
 
 describe('markCommands styling', () => {
-  it('takes a status colour over the default', () => {
+  it('takes a status color over the default', () => {
     const [cmd] = markCommands(mark('rect'), CONTENT, { color: '#30a46c' });
     expect((cmd as { stroke?: { paint?: { color?: string } } }).stroke?.paint?.color).toBe(
       '#30a46c',
@@ -117,7 +117,7 @@ describe('markCommands styling', () => {
     expect((stale as { stroke?: { dash?: number[] } }).stroke?.dash).toEqual([6, 4]);
   });
 
-  it("colours a text mark's glyphs too, not only the outlines", () => {
+  it("colors a text mark's glyphs too, not only the outlines", () => {
     const [cmd] = markCommands(mark('text', { title: 'x' }), CONTENT, { color: '#30a46c' });
     const runs = (cmd as { runs: { fill?: { color?: string } }[] }).runs;
     expect(runs[0]?.fill?.color).toBe('#30a46c');

package/src/annotations/paint.ts

@@ -27,7 +27,7 @@ export interface PaintableMark {
 /** How a mark is drawn, as opposed to where. Resolved by the overlay from the
  *  instrument's vocabulary and the mark's own staleness. */
 export interface MarkStyle {
-  /** The status's colour, or the default. */
+  /** The status's color, or the default. */
   color?: string;
   /** A mark whose stored position no longer describes the picture. Drawn
    *  dashed rather than hidden: it still describes *something*, and dropping

package/src/annotations/preload.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+/** Marks an instrument keeps in its own `AnnotationStorage`, already loaded by
+ *  `<Lab>` for the trials present when it opened, keyed by trial id. A trial
+ *  missing from it loads its own. */
+export const AnnotationPreloadContext = createContext<ReadonlyMap<string, unknown> | null>(null);

package/src/annotations/store.test.ts

@@ -244,4 +244,22 @@ describe('the annotation store', () => {
     expect(revived.get(id)).toEqual(store.get(id));
     expect(revived.query()).toHaveLength(1);
   });
+
+  it('reads a meaning passed as a thunk at each capture', async () => {
+    let color = '#111111';
+    const store = annotationsFromJSON(null, () => TARGETS, {
+      meaning: () => ({ statuses: [{ id: 'open', label: 'Open', color }] }),
+    });
+    store.add(RING, { angle: 'iso', shading: 'outline' });
+    color = '#222222';
+    const { blob } = await store.capture('naive', { format: 'svg' });
+    // jsdom's Blob has no text().
+    const svg = await new Promise<string>((resolve) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.readAsText(blob);
+    });
+    expect(svg).not.toContain('#111111');
+    expect(svg).toContain('#222222');
+  });
 });

package/src/annotations/store.ts

@@ -43,9 +43,10 @@ export interface AnnotationStoreOptions {
   targets: () => readonly AnnotationTargetInfo[];
   /** Serialized scenes from a previous `toJSON`, keyed by target. */
   restore?: Readonly<Record<string, unknown>>;
-  /** The instrument's vocabulary, so an export draws a mark in the colour its
-   *  status gives it. */
-  meaning?: AnnotationMeaning;
+  /** The instrument's vocabulary, so an export draws a mark in the color its
+   *  status gives it. A thunk is read at each capture, for a vocabulary that
+   *  changes under a store built once. */
+  meaning?: AnnotationMeaning | (() => AnnotationMeaning | undefined);
   /** The trial's live config. A getter for the same reason `targets` is: the
    *  store is built once and the config changes under it. */
   config?: () => unknown;
@@ -314,7 +315,7 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
             content: info.content,
             positionDependsOn: info.positionDependsOn,
             config: opts.config?.(),
-            meaning: opts.meaning,
+            meaning: typeof opts.meaning === 'function' ? opts.meaning() : opts.meaning,
           },
           base: info.base,
           onWarn: (message) => console.warn(`[labkit] capture: ${message}`),

package/src/annotations/svgNodes.test.ts

@@ -39,7 +39,7 @@ describe('a mark as vector', () => {
       expect(node.stroke?.cap).toBe(cmd.stroke?.cap);
       expect(node.stroke?.join).toBe(cmd.stroke?.join);
       // An arrow's head arrives filled and unstroked; the shaft is the other
-      // way round. Whichever paint the command carries is the mark colour.
+      // way round. Whichever paint the command carries is the mark color.
       const paint = node.stroke?.paint ?? node.fill;
       expect(paint).toEqual({ kind: 'solid', color: '#e5484d' });
     }
@@ -65,7 +65,7 @@ describe('a mark as vector', () => {
     );
   });
 
-  it('emits text as text, at the pose, in the mark colour', () => {
+  it('emits text as text, at the pose, in the mark color', () => {
     const m = mark('text', { title: 'missing edge' });
     const [node] = markSvgNodes(m, CONTENT);
     expect(node).toMatchObject({ kind: 'text', text: 'missing edge', x: 10, y: 12 });

package/src/annotations/svgNodes.ts

@@ -27,6 +27,7 @@ function toSvgStroke(stroke: Stroke): SvgStroke {
     ...(stroke.join ? { join: stroke.join } : {}),
     ...(stroke.dash ? { dash: [...stroke.dash] } : {}),
     ...(stroke.miterLimit != null ? { miterLimit: stroke.miterLimit } : {}),
+    ...(stroke.align ? { align: stroke.align } : {}),
   };
 }
 

package/src/annotations/toolMap.test.ts

@@ -6,8 +6,12 @@ import type { AnnotationKind } from './types';
 const KINDS: AnnotationKind[] = ['stroke', 'line', 'arrow', 'rect', 'ellipse', 'text'];
 
 describe('the annotation tool table', () => {
-  it('offers one tool per mark kind, plus select', () => {
-    expect(ANNOTATION_TOOLS.map((t) => t.id)).toEqual(['select', ...KINDS]);
+  it('offers one tool per mark kind, plus pointer and select', () => {
+    expect(ANNOTATION_TOOLS.map((t) => t.id)).toEqual(['pointer', 'select', ...KINDS]);
+  });
+
+  it('gives pointer no entry at all, which is what leaves the overlay idle', () => {
+    expect(annotationToolInfo('pointer')).toBeUndefined();
   });
 
   it('only names weasel tools SceneCanvas will mount', () => {
@@ -15,9 +19,9 @@ describe('the annotation tool table', () => {
     // being built in should fail here rather than in a silent no-op palette.
     const mountable = new Set<string>([...KIT_SHAPE_KINDS, 'select']);
     for (const t of ANNOTATION_TOOLS) {
-      expect(mountable, `${t.id} maps to a tool the kit does not mount`).toContain(
-        annotationToolInfo(t.id)?.weaselTool,
-      );
+      const info = annotationToolInfo(t.id);
+      if (!info) continue;
+      expect(mountable, `${t.id} maps to a tool the kit does not mount`).toContain(info.weaselTool);
     }
   });
 

package/src/annotations/toolMap.ts

@@ -2,6 +2,7 @@ import type { BuiltinToolId } from '@weasel-js/core';
 import {
   ArrowIcon,
   EllipseIcon,
+  HandIcon,
   LineIcon,
   PencilIcon,
   RectIcon,
@@ -30,10 +31,12 @@ const TOOLS: Record<string, AnnotationToolInfo> = {
   text: { weaselTool: 'text', kind: 'text' },
 };
 
-/** The palette an instrument gets for declaring `annotations`. Ids share the
- *  trial's contribution namespace with `instrument.tools`, and one tool slot
- *  holds whichever is active. */
+/** The tools a lab's rail gets when any instrument declares `annotations`.
+ *  Ids share the lab's contribution namespace with its own `tools`, and the
+ *  lab's tool slot holds whichever is active. */
 export const ANNOTATION_TOOLS: readonly TrialTool[] = [
+  // Not in `TOOLS`: an id the map does not carry is what leaves the overlay idle.
+  { id: 'pointer', label: 'Interact', icon: HandIcon, group: 'annotate' },
   { id: 'select', label: 'Select', icon: SelectIcon, group: 'annotate' },
   { id: 'stroke', label: 'Freehand', icon: PencilIcon, group: 'annotate' },
   { id: 'line', label: 'Line', icon: LineIcon, group: 'annotate' },