@weasel-js/labkit 1.4.4 → 1.5.0

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-QLSV2N3G.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 { c3 as LayerStack } from '../../chunk-S2SHZRD7.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 { as as UndoCapability } from '../_dts/frac-8R6UmlvN.js';
 import 'react';
-import '../_dts/types-B9_zrHmb.js';
+import '../_dts/types-Ca2LCnPq.js';
 import '@weasel-js/core';
 import '../_dts/PrefsForm.d-DDHFANkc.js';
-import '../_dts/types-x92Kfeme.js';
-import '../_dts/types-BP2OCcpg.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.0",
   "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.0",
     "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.0",
+    "@weasel-js/kernel3d": "1.5.0",
+    "@weasel-js/loupe": "1.5.0",
+    "@weasel-js/svg": "1.5.0",
+    "@weasel-js/theme": "1.5.0",
+    "@weasel-js/ui": "1.5.0",
     "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.0",
     "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();
@@ -190,7 +238,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.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) => {
@@ -133,6 +157,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 +285,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/toolMap.ts

@@ -30,9 +30,9 @@ 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[] = [
   { id: 'select', label: 'Select', icon: SelectIcon, group: 'annotate' },
   { id: 'stroke', label: 'Freehand', icon: PencilIcon, group: 'annotate' },

package/src/annotations/types.ts

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

package/src/canvas/CameraWheelContext.ts

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

package/src/canvas/CanvasStack.test.tsx

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