@weasel-js/labkit 1.6.0 → 1.6.1

package/dist/undo/index.d.ts

@@ -1,9 +1,9 @@
-export { au as UndoCapability } from '../_dts/frac-DTRq7Xpb.js';
+export { az as UndoCapability } from '../_dts/types-B7yBTTF9.js';
+import '@weasel-js/core';
 import 'react';
 import '../_dts/PrefsRow.d-DFpPIeIC.js';
 import '@weasel-js/theme';
-import '@weasel-js/core';
-import '../_dts/types-B7y8hX1D.js';
+import '../_dts/types-DTuViBvc.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.6.0",
+  "version": "1.6.1",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -74,6 +74,10 @@
       "types": "./dist/job/index.d.ts",
       "import": "./dist/job/index.js"
     },
+    "./overview": {
+      "types": "./dist/overview/index.d.ts",
+      "import": "./dist/overview/index.js"
+    },
     "./weasel-ui": {
       "types": "./dist/passthrough/weasel-ui.d.ts",
       "import": "./dist/passthrough/weasel-ui.js"
@@ -111,17 +115,17 @@
     "dev:3d": "LABKIT_EXAMPLE=3d-lab vite"
   },
   "peerDependencies": {
-    "@weasel-js/core": "1.6.0",
-    "@weasel-js/theme": "1.6.0",
+    "@weasel-js/core": "1.6.1",
+    "@weasel-js/theme": "1.6.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/geom": "1.6.0",
-    "@weasel-js/kernel3d": "1.6.0",
-    "@weasel-js/loupe": "1.6.0",
-    "@weasel-js/svg": "1.6.0",
-    "@weasel-js/ui": "1.6.0",
+    "@weasel-js/geom": "1.6.1",
+    "@weasel-js/kernel3d": "1.6.1",
+    "@weasel-js/loupe": "1.6.1",
+    "@weasel-js/svg": "1.6.1",
+    "@weasel-js/ui": "1.6.1",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -132,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.6.0",
+    "@weasel-js/modes": "1.6.1",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/index.ts

@@ -28,6 +28,7 @@ export type {
   AnnotationsCapability,
   AnnotationTarget,
   AnnotationTargetInfo,
+  AnnotationToolId,
   CaptureOptions,
   CaptureResult,
   CaptureSource,

package/src/annotations/store.test.ts

@@ -294,3 +294,29 @@ describe('the annotation store', () => {
     expect(svg).toContain('#222222');
   });
 });
+
+describe('paintedMarks', () => {
+  it("hands over a target's marks in world units with their resolved style", () => {
+    let config: Record<string, string> = { angle: 'iso', shading: 'outline' };
+    const store = createAnnotationStore({
+      targets: () => TARGETS,
+      meaning: { statuses: [{ id: 'open', label: 'Open', color: '#123456' }] },
+      config: () => config,
+    });
+    store.add(RING, config);
+    const [painted] = store.paintedMarks('naive');
+    expect(painted?.mark.data.kind).toBe('rect');
+    expect(painted?.mark.pose.x).toBeCloseTo(0.3322 * 256);
+    expect(painted?.style).toEqual({ color: '#123456', stale: false });
+
+    // A config the mark no longer describes draws it dashed, as the pane does.
+    config = { angle: 'top', shading: 'outline' };
+    expect(store.paintedMarks('naive')[0]?.style.stale).toBe(true);
+  });
+
+  it('answers nothing for a target with no marks or no declaration', () => {
+    const store = makeStore();
+    expect(store.paintedMarks('occt')).toEqual([]);
+    expect(store.paintedMarks('nowhere')).toEqual([]);
+  });
+});

package/src/annotations/store.ts

@@ -6,6 +6,7 @@ import {
   sceneFromJSON,
 } from '@weasel-js/core';
 import { captureTarget } from './capture';
+import { type MarkDrawOptions, resolveMarkStyle } from './drawOne';
 import type { WorldRect } from './frac';
 import { fracContains, fracEncloses, fracToWorld, roundFrac, worldToFrac } from './frac';
 import { MarkHistory } from './history';
@@ -123,6 +124,14 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
     targets().find((t) => t.id === id);
 
   const contentOf = (id: string) => targetOf(id)?.content ?? NO_CONTENT;
+  /** How a target's marks are drawn right now — one answer for the pane, an
+   *  export and an overview, so none can disagree on a color or a dash. */
+  const drawOptionsFor = (info: AnnotationTargetInfo): MarkDrawOptions => ({
+    content: info.content,
+    positionDependsOn: info.positionDependsOn,
+    config: opts.config?.(),
+    meaning: typeof opts.meaning === 'function' ? opts.meaning() : opts.meaning,
+  });
 
   const project = (target: string, node: string): Annotation | undefined => {
     const found = scenes.get(target)?.get(asNodeId(node));
@@ -304,6 +313,21 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
       if (found) found.scene.remove(asNodeId(found.node.id));
     },
 
+    paintedMarks(target) {
+      const info = targetOf(target);
+      const scene = scenes.get(target);
+      if (!info || !scene) return [];
+      const draw = drawOptionsFor(info);
+      return [...scene.renderOrder()].flatMap((id) => {
+        const node = scene.get(asNodeId(String(id)));
+        if (!node) return [];
+        const data = node.data as AnnotationData;
+        return [
+          { mark: { pose: node.pose as MarkPose, data }, style: resolveMarkStyle(data, draw) },
+        ];
+      });
+    },
+
     async capture(target: string, captureOpts?: CaptureOptions) {
       const info = targetOf(target);
       if (!info) throw new Error(`[labkit] no annotation target called '${target}'`);
@@ -311,12 +335,7 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
         {
           target,
           scene: sceneFor(target),
-          draw: {
-            content: info.content,
-            positionDependsOn: info.positionDependsOn,
-            config: opts.config?.(),
-            meaning: typeof opts.meaning === 'function' ? opts.meaning() : opts.meaning,
-          },
+          draw: drawOptionsFor(info),
           base: info.base,
           onWarn: (message) => console.warn(`[labkit] capture: ${message}`),
         },

package/src/annotations/toolMap.test.ts

@@ -1,7 +1,9 @@
 import { KIT_SHAPE_KINDS } from '@weasel-js/core';
 import { describe, expect, it } from 'vitest';
-import { ANNOTATION_TOOLS, annotationToolInfo } from './toolMap';
-import type { AnnotationKind } from './types';
+import type { InstrumentList } from '../instrument/types';
+import { resolveLabTool } from '../tools/labTool';
+import { ANNOTATION_TOOLS, annotationToolInfo, labAnnotationTools } from './toolMap';
+import type { AnnotationKind, AnnotationToolId } from './types';
 
 const KINDS: AnnotationKind[] = ['stroke', 'line', 'arrow', 'rect', 'ellipse', 'text'];
 
@@ -38,3 +40,36 @@ describe('the annotation tool table', () => {
     expect(annotationToolInfo('hand')).toBeUndefined();
   });
 });
+
+describe('the tools a lab rail carries', () => {
+  const ids = (instruments: InstrumentList) => labAnnotationTools(instruments).map((t) => t.id);
+  const inst = (annotations?: { tools?: AnnotationToolId[] }) =>
+    ({
+      annotations: annotations && { targets: () => [], ...annotations },
+    }) as unknown as InstrumentList[number];
+
+  it('carries none when no instrument annotates', () => {
+    expect(ids([inst()])).toEqual([]);
+  });
+
+  it('carries every tool for an instrument that names none', () => {
+    expect(ids([inst({})])).toEqual(ANNOTATION_TOOLS.map((t) => t.id));
+  });
+
+  it('carries only the named tools, in the kit order', () => {
+    expect(ids([inst({ tools: ['select', 'pointer'] })])).toEqual(['pointer', 'select']);
+  });
+
+  it('carries the union across annotating instruments', () => {
+    expect(ids([inst({ tools: ['pointer'] }), inst({ tools: ['rect'] }), inst()])).toEqual([
+      'pointer',
+      'rect',
+    ]);
+  });
+
+  it('starts the lab in pointer when the rail has it, else in its first tool', () => {
+    expect(resolveLabTool(null, [inst({ tools: ['select', 'pointer'] })])).toBe('pointer');
+    expect(resolveLabTool(null, [inst({ tools: ['text', 'select'] })])).toBe('select');
+    expect(resolveLabTool(null, [inst()])).toBeNull();
+  });
+});

package/src/annotations/toolMap.ts

@@ -9,6 +9,7 @@ import {
   SelectIcon,
   TextIcon,
 } from '@weasel-js/ui';
+import type { InstrumentList } from '../instrument/types';
 import type { TrialTool } from '../tools/types';
 import type { AnnotationKind } from './types';
 
@@ -46,6 +47,18 @@ export const ANNOTATION_TOOLS: readonly TrialTool[] = [
   { id: 'text', label: 'Text', icon: TextIcon, group: 'annotate' },
 ];
 
+/** The annotation tools a lab's rail carries for these instruments: none
+ *  without an annotating instrument, else the union of what each asks for. */
+export function labAnnotationTools(instruments: InstrumentList): readonly TrialTool[] {
+  const wanted = new Set<string>();
+  for (const i of instruments) {
+    if (i.annotations == null) continue;
+    if (i.annotations.tools == null) return ANNOTATION_TOOLS;
+    for (const id of i.annotations.tools) wanted.add(id);
+  }
+  return ANNOTATION_TOOLS.filter((t) => wanted.has(t.id));
+}
+
 /** What `id` drives, or undefined for a tool that is not one of these. */
 export function annotationToolInfo(id: string | null): AnnotationToolInfo | undefined {
   return id === null ? undefined : TOOLS[id];

package/src/annotations/types.ts

@@ -1,6 +1,7 @@
 import type { RefObject } from 'react';
 import type { ViewTransform } from '../instrument/types';
 import type { TrialInfo } from '../state/types';
+import type { MarkStyle, PaintableMark } from './paint';
 import type { MarkScene } from './store';
 
 /** A point in fractions of a target's content box. */
@@ -160,10 +161,25 @@ export interface AnnotationStorage {
 
 /** Declares that an instrument accepts marks: which regions take them,
  *  optionally what a mark is allowed to mean, and optionally where they live. */
+/** The annotation tools a lab's rail can carry. */
+export type AnnotationToolId =
+  | 'pointer'
+  | 'select'
+  | 'stroke'
+  | 'line'
+  | 'arrow'
+  | 'rect'
+  | 'ellipse'
+  | 'text';
+
 export interface AnnotationsCapability<TS = unknown, TC = unknown> {
   /** `trial` is which trial is asking: a declaration made once per instrument
    *  is called once per trial, and its targets are that trial's own. */
   targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
+  /** Which annotation tools the lab's rail offers. The rail is shared, so it
+   *  carries every tool any annotating instrument asks for, in the kit's own
+   *  order; an instrument that leaves this unset asks for all of them. */
+  tools?: readonly AnnotationToolId[];
   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. */
@@ -183,6 +199,12 @@ export interface SerializedAnnotations {
   scenes: Record<string, unknown>;
 }
 
+/** One mark, as `AnnotationsApi.paintedMarks` hands it over. */
+export interface PaintedMark {
+  mark: PaintableMark;
+  style: MarkStyle;
+}
+
 /** Everything a host can ask or tell labkit about the marks on its targets. */
 export interface AnnotationsApi {
   /** The scene a target's marks live in, created on first ask. One per target
@@ -222,6 +244,11 @@ export interface AnnotationsApi {
   undo(): boolean;
   redo(): boolean;
 
+  /** A target's marks as its pane paints them, in scene order: geometry in
+   *  the target's content box, each with the style its status and staleness
+   *  resolve to. For a painter outside the pane — an overview. */
+  paintedMarks(target: string): PaintedMark[];
+
   /** Export a target's picture with its marks on it. Rejects on an id the
    *  instrument does not declare. */
   capture(target: string, opts?: CaptureOptions): Promise<CaptureResult>;

package/src/canvas/AGENTS.md

@@ -6,18 +6,16 @@ For a renderer labkit does not own — three.js, raw WebGL, anything with its ow
 render loop — see `src/surface/AGENTS.md` instead. `CanvasStack` is 2D and
 schedules its own layers; a foreign renderer wants rects and dirtiness only.
 
-`useOrbit` also lives here, as the 3D peer of `usePanZoom`. It produces a trial
-view (`{ yaw, pitch, distance, target }`) rather than a matrix — turning that
-into a camera is the host's job.
-
 ## Files
 
 | File | Role |
 |---|---|
-| `CanvasStack.tsx` | Layered `<canvas>` container; owns sizing, pan/zoom handlers, and per-layer canvas refs |
+| `CanvasStack.tsx` | Layered `<canvas>` container; owns sizing and per-layer canvas refs |
 | `CanvasStackContext.ts` | React context exposing the current `view` to descendants |
 | `useLayerScheduler.ts` | DPR-aware rAF scheduler; redraws dirty layers on view/state changes |
-| `usePanZoom.ts` | Pointer + wheel handlers that mutate `view` via `onViewChange` |
+| `CameraInput.tsx` | Pan, zoom and tap routed through weasel's gesture dispatcher; `CameraContext`; publishes the pointer |
+| `cameraView.ts` | The camera as a weasel `View` over frame-local coordinates, and the anchored zoom clamp |
+| `LinkedCursor.tsx` | The crosshair on the camera's element while the pointer is over another view |
 | `camera.ts` | `zoomAt` (fixed-point zoom) and `centerOn` (put a world point at a viewport's middle) |
 | `canvasCoords.ts` | Pure `screenToWorld` / `worldToScreen` helpers |
 | `worldSpec.ts` | The instrument's declared coordinate system, and the camera derived from it |
@@ -32,8 +30,8 @@ interface CanvasStackProps {
   onViewChange: (v: ViewTransform) => void;
   worldSpec?: WorldSpec;                // origin + y direction; default top-left, y down
   onResize?: (size: ViewportSize) => void;
-  minZoom?: number;                     // default 0.1, forwarded to usePanZoom
-  maxZoom?: number;                     // default 32, forwarded to usePanZoom
+  minZoom?: number;                     // default 0.1; the opening zoom stays reachable
+  maxZoom?: number;                     // default 32
   width?: number | string;              // default '100%'
   height?: number | string;             // default '100%'
   className?: string;
@@ -93,11 +91,11 @@ convention: origin at the element's top-left, y downward.
 `resolveFrame(spec, size)` turns a spec plus a measured viewport into a
 `WorldFrame` — `{ originPx, yDir }` — which is what the rest of the directory
 actually consumes. `CanvasStack` owns the measurement, so it owns the frame and
-hands it to `usePanZoom`, to the scheduler, and to every `render`.
+hands it to the camera (`useCameraView`), to the scheduler, and to every `render`.
 
 **Every world↔screen path must go through the frame.** There are four, and each
 one is a silent wrong answer if it is missed: `worldToScreen` / `screenToWorld`,
-the camera (`applyCamera`), the wheel anchor in `usePanZoom`, and
+the camera (`applyCamera`), the camera as a weasel `View` (`cameraView.ts`), and
 `DragDropRuntime`'s drop position. A miss produces geometry that is off by a
 constant, or a wheel that drifts — never an error.
 

package/src/canvas/CameraInput.test.tsx

@@ -0,0 +1,136 @@
+/**
+ * A labkit camera on weasel's dispatcher: drag pans by the screen delta, the
+ * zoom range holds with the opening zoom kept reachable, and the pointer is
+ * published in the instrument's world.
+ */
+
+import { act, render } from '@testing-library/react';
+import { createPointerStore, PointerContextProvider } from '@weasel-js/core';
+import { useState } from 'react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import type { ViewTransform } from '../instrument/types';
+import { CanvasStack } from './CanvasStack';
+import { Stage } from './Stage';
+
+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 lastOf<T>(list: readonly T[]): T {
+  const item = list[list.length - 1];
+  if (item === undefined) throw new Error('nothing recorded');
+  return item;
+}
+
+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,
+    }),
+  );
+}
+
+function mountStage(initial: ViewTransform, opts: { minZoom?: number; maxZoom?: number } = {}) {
+  const seen: ViewTransform[] = [];
+  function Host() {
+    const [view, setView] = useState(initial);
+    return (
+      <Stage
+        size={{ width: 100, height: 100 }}
+        view={view}
+        onViewChange={(v) => {
+          seen.push(v);
+          setView(v);
+        }}
+        {...opts}
+      >
+        <div />
+      </Stage>
+    );
+  }
+  const { container } = render(<Host />);
+  const host = container.querySelector('.lk-stage') as HTMLElement;
+  return { host, seen };
+}
+
+describe('camera input', () => {
+  it('pans by the screen delta of a drag', () => {
+    const { host, seen } = mountStage({ zoom: 2, pan: { x: 10, y: 20 } });
+    act(() => {
+      pointer(host, 'pointerdown', 50, 50);
+      pointer(host, 'pointermove', 60, 55);
+      pointer(host, 'pointermove', 80, 70);
+      pointer(host, 'pointerup', 80, 70, 0);
+    });
+    const last = lastOf(seen);
+    expect(last.zoom).toBeCloseTo(2);
+    expect(last.pan.x).toBeCloseTo(40);
+    expect(last.pan.y).toBeCloseTo(40);
+  });
+
+  it('stops the zoom at the bound, anchored on the pointer', () => {
+    const { host, seen } = mountStage({ zoom: 1, pan: { x: 0, y: 0 } }, { maxZoom: 1.2 });
+    act(() => {
+      host.dispatchEvent(
+        new WheelEvent('wheel', {
+          bubbles: true,
+          cancelable: true,
+          deltaY: -2000,
+          clientX: 40,
+          clientY: 30,
+        }),
+      );
+    });
+    const last = lastOf(seen);
+    expect(last.zoom).toBeCloseTo(1.2);
+    // The world point under (40, 30) stayed there.
+    expect((40 - last.pan.x) / last.zoom).toBeCloseTo(40);
+    expect((30 - last.pan.y) / last.zoom).toBeCloseTo(30);
+  });
+
+  it('keeps the opening zoom reachable past a narrower range', () => {
+    const { host, seen } = mountStage({ zoom: 4, pan: { x: 0, y: 0 } }, { maxZoom: 2 });
+    act(() => {
+      host.dispatchEvent(
+        new WheelEvent('wheel', {
+          bubbles: true,
+          cancelable: true,
+          deltaY: 100,
+          clientX: 0,
+          clientY: 0,
+        }),
+      );
+    });
+    // Zooming out from 4 lands between 2 and 4, not snapped to 2.
+    expect(lastOf(seen).zoom).toBeGreaterThan(2);
+  });
+
+  it("publishes the pointer in the instrument's world as the stage", () => {
+    const store = createPointerStore();
+    const { container } = render(
+      <PointerContextProvider store={store}>
+        <CanvasStack
+          layers={[]}
+          view={{ zoom: 2, pan: { x: 0, y: 0 } }}
+          onViewChange={() => {}}
+          worldSpec={{ yAxis: 'up' }}
+        />
+      </PointerContextProvider>,
+    );
+    const host = container.querySelector('.lk-canvas-stack') as HTMLElement;
+    act(() => pointer(host, 'pointermove', 40, 30, 0));
+    expect(store.get()).toEqual({ worldX: 20, worldY: -15, viewId: 'stage' });
+  });
+});