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

package/src/annotations/store.ts

@@ -0,0 +1,317 @@
+import {
+  asNodeId,
+  createScene,
+  type Scene,
+  type SerializedScene,
+  sceneFromJSON,
+} from '@weasel-js/core';
+import { captureTarget } from './capture';
+import type { WorldRect } from './frac';
+import { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+import { MarkHistory } from './history';
+import { isStale as isStaleAgainst, seenFrom } from './staleness';
+import type {
+  Annotation,
+  AnnotationData,
+  AnnotationInit,
+  AnnotationMeaning,
+  AnnotationPatch,
+  AnnotationQuery,
+  AnnotationsApi,
+  AnnotationTargetInfo,
+  CaptureOptions,
+  CaptureResult,
+  FracPoint,
+  FracRect,
+  SerializedAnnotations,
+} from './types';
+
+/** A mark's box in its target's world. Matches weasel's default `RectPose`. */
+type MarkPose = WorldRect;
+
+/** The scene one target's marks live in. */
+export type MarkScene = Scene<AnnotationData, 'marks', MarkPose>;
+
+/** A mark scene: one layer, because marks do not stack in tiers. */
+export function createAnnotationScene(): MarkScene {
+  return createScene<AnnotationData, 'marks', MarkPose>({ systemLayers: [{ id: 'marks' }] });
+}
+
+export interface AnnotationStoreOptions {
+  /** Re-read on every call, so a target resizing or gaining a dependency takes
+   *  effect without rebuilding the store. */
+  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 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;
+  /** Notified after every finished export. */
+  onCapture?: (result: CaptureResult) => void;
+}
+
+/** Everything a capture needs that is not the store's own state. Split out so
+ *  `capture.ts` takes data rather than reaching back into the store. */
+export interface CaptureDeps {
+  scene: MarkScene;
+  target: AnnotationTargetInfo;
+  meaning?: AnnotationMeaning;
+  config: unknown;
+}
+
+const NO_CONTENT = { w: 0, h: 0 };
+
+/** A mark's id is its target and its node. One scene per target, so a node id
+ *  is only unique within one — and an annotation is addressed by both. */
+function splitId(id: string): { target: string; node: string } | undefined {
+  const at = id.lastIndexOf('/');
+  return at <= 0 ? undefined : { target: id.slice(0, at), node: id.slice(at + 1) };
+}
+
+/**
+ * A facade over one weasel scene per target: the scenes are the truth, this
+ * answers questions about them. Everything crossing this boundary is in
+ * fractions of a target's content box; the scenes hold world units.
+ *
+ * A scene per target rather than one scene with a `target` field, because a
+ * pane's hit-test, marquee and paint all walk the whole scene it is given and
+ * take no filter — one shared scene puts every other pane's marks under the
+ * pointer.
+ */
+export function createAnnotationStore(opts: AnnotationStoreOptions): AnnotationsApi {
+  const { targets, restore } = opts;
+  const scenes = new Map<string, MarkScene>();
+  const subs = new Set<() => void>();
+  const history = new MarkHistory();
+  const notify = (): void => {
+    for (const fn of subs) fn();
+  };
+
+  const sceneFor = (target: string): MarkScene => {
+    const known = scenes.get(target);
+    if (known) return known;
+    const raw = restore?.[target];
+    const scene = raw
+      ? sceneFromJSON<AnnotationData, 'marks', MarkPose>(
+          raw as SerializedScene<AnnotationData, 'marks', MarkPose>,
+          {},
+        )
+      : createAnnotationScene();
+    scenes.set(target, scene);
+    history.track(target, scene);
+    scene.subscribe(() => {
+      history.observe(target, scene);
+      notify();
+    });
+    return scene;
+  };
+
+  /** Only for scenes that exist: asking for one would create it, and the
+   *  ordering never names a target it has not seen. */
+  const historySceneAt = (target: string) => scenes.get(target);
+
+  // Restored scenes are materialized up front: everything below reads
+  // `scenes`, and a mark that only appears once its pane asks for its scene is
+  // a mark a sidebar cannot list.
+  for (const target of Object.keys(restore ?? {})) sceneFor(target);
+
+  const targetOf = (id: string): AnnotationTargetInfo | undefined =>
+    targets().find((t) => t.id === id);
+
+  const contentOf = (id: string) => targetOf(id)?.content ?? NO_CONTENT;
+
+  const project = (target: string, node: string): Annotation | undefined => {
+    const found = scenes.get(target)?.get(asNodeId(node));
+    if (!found) return undefined;
+    return {
+      ...found.data,
+      target,
+      id: `${target}/${node}`,
+      frac: roundFrac(worldToFrac(found.pose as MarkPose, contentOf(target))),
+    };
+  };
+
+  /** Every target with a scene, in declaration order — then any whose target
+   *  the instrument has since stopped declaring, so its marks are not lost. */
+  const liveTargets = (): string[] => {
+    const declared = targets().map((t) => t.id);
+    const rest = [...scenes.keys()].filter((id) => !declared.includes(id));
+    return [...declared, ...rest];
+  };
+
+  const marksOn = (target: string): Annotation[] => {
+    const scene = scenes.get(target);
+    if (!scene) return [];
+    const out: Annotation[] = [];
+    for (const id of scene.renderOrder()) {
+      const a = project(target, String(id));
+      if (a) out.push(a);
+    }
+    return out;
+  };
+
+  const all = (): Annotation[] => liveTargets().flatMap(marksOn);
+
+  const matches = (a: Annotation, q: AnnotationQuery): boolean => {
+    if (q.target !== undefined && a.target !== q.target) return false;
+    if (q.kind !== undefined && a.kind !== q.kind) return false;
+    if (q.status !== undefined && a.status !== q.status) return false;
+    if (q.tags !== undefined) {
+      const have = a.tags ?? [];
+      for (const t of q.tags) if (!have.includes(t)) return false;
+    }
+    if (q.where && !q.where(a)) return false;
+    return true;
+  };
+
+  /** The node behind a public id, or undefined. */
+  const nodeOf = (id: string) => {
+    const parts = splitId(id);
+    if (!parts) return undefined;
+    const scene = scenes.get(parts.target);
+    const node = scene?.get(asNodeId(parts.node));
+    return node && scene ? { ...parts, scene, node } : undefined;
+  };
+
+  return {
+    sceneFor,
+
+    targets,
+
+    get(id) {
+      const parts = splitId(id);
+      return parts ? project(parts.target, parts.node) : undefined;
+    },
+
+    query(q) {
+      return q ? all().filter((a) => matches(a, q)) : all();
+    },
+
+    hitTest(target, pt: FracPoint, tol = 0) {
+      return marksOn(target)
+        .filter((a) => fracContains(a.frac, pt, tol))
+        .reverse();
+    },
+
+    within(target, box: FracRect) {
+      return marksOn(target).filter((a) => fracIntersects(box, a.frac));
+    },
+
+    isStale(a, config) {
+      const keys = targetOf(a.target)?.positionDependsOn ?? [];
+      return isStaleAgainst(a.seen, config, keys);
+    },
+
+    canUndo() {
+      return history.canUndo(historySceneAt);
+    },
+
+    canRedo() {
+      return history.canRedo(historySceneAt);
+    },
+
+    undo() {
+      return history.undo(historySceneAt);
+    },
+
+    redo() {
+      return history.redo(historySceneAt);
+    },
+
+    subscribe(fn) {
+      subs.add(fn);
+      return () => {
+        subs.delete(fn);
+      };
+    },
+
+    add(init: AnnotationInit, config?: unknown) {
+      const target = targetOf(init.target);
+      const data: AnnotationData = {
+        target: init.target,
+        kind: init.kind,
+        ...(init.points ? { points: init.points } : {}),
+        ...(init.title !== undefined ? { title: init.title } : {}),
+        ...(init.status !== undefined ? { status: init.status } : {}),
+        ...(init.tags !== undefined ? { tags: init.tags } : {}),
+        ...(init.meta !== undefined ? { meta: init.meta } : {}),
+        seen: seenFrom(config, target?.positionDependsOn ?? []),
+      };
+      const node = sceneFor(init.target).add({
+        kind: 'leaf',
+        layer: 'marks',
+        pose: fracToWorld(roundFrac(init.frac), target?.content ?? NO_CONTENT),
+        data,
+      });
+      return `${init.target}/${String(node)}`;
+    },
+
+    update(id, patch: AnnotationPatch) {
+      const found = nodeOf(id);
+      if (!found) return;
+      const { frac, ...meaning } = patch;
+      const nid = asNodeId(found.node.id);
+      if (Object.keys(meaning).length > 0) {
+        found.scene.update(nid, { data: { ...found.node.data, ...meaning } });
+      }
+      if (frac) {
+        found.scene.setPose(nid, fracToWorld(roundFrac(frac), contentOf(found.target)));
+      }
+    },
+
+    setMeta(id, meta) {
+      const found = nodeOf(id);
+      if (!found) return;
+      found.scene.update(asNodeId(found.node.id), { data: { ...found.node.data, meta } });
+    },
+
+    remove(id) {
+      const found = nodeOf(id);
+      if (found) found.scene.remove(asNodeId(found.node.id));
+    },
+
+    async capture(target: string, captureOpts?: CaptureOptions) {
+      const info = targetOf(target);
+      if (!info) throw new Error(`[labkit] no annotation target called '${target}'`);
+      const result = await captureTarget(
+        {
+          target,
+          scene: sceneFor(target),
+          draw: {
+            content: info.content,
+            positionDependsOn: info.positionDependsOn,
+            config: opts.config?.(),
+            meaning: opts.meaning,
+          },
+          base: info.base,
+          onWarn: (message) => console.warn(`[labkit] capture: ${message}`),
+        },
+        captureOpts,
+      );
+      opts.onCapture?.(result);
+      return result;
+    },
+
+    toJSON(): SerializedAnnotations {
+      const out: Record<string, unknown> = {};
+      for (const [target, scene] of scenes) out[target] = scene.toJSON();
+      return { version: 1, scenes: out };
+    },
+  };
+}
+
+/** Rebuild a store from what `toJSON` wrote. Unknown or future versions give
+ *  an empty store rather than throwing: a lab that cannot read its marks
+ *  should still open. */
+export function annotationsFromJSON(
+  raw: unknown,
+  targets: () => readonly AnnotationTargetInfo[],
+  rest: Omit<AnnotationStoreOptions, 'targets' | 'restore'> = {},
+): AnnotationsApi {
+  const doc = raw as Partial<SerializedAnnotations> | null;
+  if (doc?.version !== 1 || !doc.scenes) return createAnnotationStore({ targets, ...rest });
+  return createAnnotationStore({ targets, restore: doc.scenes, ...rest });
+}

package/src/annotations/svgNodes.test.ts

@@ -0,0 +1,77 @@
+import { serializeSvg } from '@weasel-js/svg';
+import { describe, expect, it } from 'vitest';
+import { markCommands } from './paint';
+import { markSvgNodes } from './svgNodes';
+import type { AnnotationData, AnnotationKind } from './types';
+
+const CONTENT = { w: 100, h: 60 };
+
+const mark = (kind: AnnotationKind, extra: Partial<AnnotationData> = {}) => ({
+  pose: { x: 10, y: 12, width: 30, height: 20 },
+  data: {
+    target: 'flat',
+    kind,
+    points: [
+      { x: 0.1, y: 0.2 },
+      { x: 0.5, y: 0.6 },
+    ],
+    ...extra,
+  } as AnnotationData,
+});
+
+const KINDS: AnnotationKind[] = ['rect', 'ellipse', 'line', 'arrow', 'stroke'];
+
+describe('a mark as vector', () => {
+  it.each(KINDS)('emits %s off the same geometry the screen draws', (kind) => {
+    const m = mark(kind);
+    const cmds = markCommands(m, CONTENT);
+    const nodes = markSvgNodes(m, CONTENT);
+    expect(nodes).toHaveLength(cmds.length);
+    for (const [i, cmd] of cmds.entries()) {
+      if (cmd.kind !== 'path') throw new Error('expected path commands');
+      const node = nodes[i];
+      if (node?.kind !== 'path') throw new Error('expected path nodes');
+      // Same geometry, kind for kind. A second switch over `data.kind` would
+      // drift from this one the moment either changed, which is what the
+      // emitter mapping over `markCommands` output rules out.
+      expect(node.path).toEqual(cmd.path);
+      expect(node.stroke?.width).toBe(cmd.stroke?.width);
+      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.
+      const paint = node.stroke?.paint ?? node.fill;
+      expect(paint).toEqual({ kind: 'solid', color: '#e5484d' });
+    }
+  });
+
+  it('carries a stale mark′s dash through', () => {
+    const [node] = markSvgNodes(mark('rect'), CONTENT, { stale: true });
+    if (node?.kind !== 'path') throw new Error('expected a path node');
+    expect(node.stroke?.dash).toEqual([6, 4]);
+  });
+
+  it("drops the arrow's marker reference, because its head is already a node", () => {
+    const nodes = markSvgNodes(mark('arrow'), CONTENT);
+    expect(nodes.length).toBeGreaterThan(1);
+    for (const node of nodes) {
+      if (node.kind !== 'path') throw new Error('expected path nodes');
+      // Keeping `markerEnd` would make the serializer emit a <marker> def as
+      // well, and the head would be drawn twice.
+      expect(node.stroke?.markerEnd).toBeUndefined();
+    }
+    expect(serializeSvg(nodes, { viewBox: { x: 0, y: 0, width: 100, height: 60 } })).not.toContain(
+      '<marker',
+    );
+  });
+
+  it('emits text as text, at the pose, in the mark colour', () => {
+    const m = mark('text', { title: 'missing edge' });
+    const [node] = markSvgNodes(m, CONTENT);
+    expect(node).toMatchObject({ kind: 'text', text: 'missing edge', x: 10, y: 12 });
+  });
+
+  it('emits nothing for a text mark with no words', () => {
+    expect(markSvgNodes(mark('text'), CONTENT)).toEqual([]);
+  });
+});

package/src/annotations/svgNodes.ts

@@ -0,0 +1,74 @@
+import type { DrawCommand, FillStyle, Stroke } from '@weasel-js/core';
+import { resolveStrokeWidth } from '@weasel-js/core';
+import type { SvgNode, SvgPaint, SvgStroke } from '@weasel-js/svg';
+import { type MarkStyle, markCommands, type PaintableMark } from './paint';
+
+const NO_PAINT: SvgPaint = { kind: 'none' };
+
+function toSvgPaint(paint: FillStyle | undefined): SvgPaint {
+  if (!paint) return NO_PAINT;
+  if ('color' in paint && typeof paint.color === 'string') {
+    return {
+      kind: 'solid',
+      color: paint.color,
+      ...(paint.opacity != null ? { opacity: paint.opacity } : {}),
+    };
+  }
+  return { kind: 'gradient', paint };
+}
+
+/** Marker references are deliberately dropped: `markCommands` already resolves
+ *  a marker into its own path command, and keeping the reference would make
+ *  the serializer emit a `<marker>` def that draws the head a second time. */
+function toSvgStroke(stroke: Stroke): SvgStroke {
+  return {
+    paint: toSvgPaint(stroke.paint),
+    width: resolveStrokeWidth(stroke.width ?? 1, 1),
+    ...(stroke.cap ? { cap: stroke.cap } : {}),
+    ...(stroke.join ? { join: stroke.join } : {}),
+    ...(stroke.dash ? { dash: [...stroke.dash] } : {}),
+    ...(stroke.miterLimit != null ? { miterLimit: stroke.miterLimit } : {}),
+  };
+}
+
+function toSvgNode(cmd: DrawCommand, m: PaintableMark): SvgNode {
+  if (cmd.kind === 'path') {
+    return {
+      kind: 'path',
+      path: cmd.path,
+      fill: toSvgPaint(cmd.fill),
+      ...(cmd.stroke ? { stroke: toSvgStroke(cmd.stroke) } : {}),
+    };
+  }
+  if (cmd.kind === 'text') {
+    return {
+      kind: 'text',
+      x: cmd.x,
+      y: cmd.y,
+      width: m.pose.width,
+      height: m.pose.height,
+      text: cmd.runs.map((run) => run.text).join(''),
+      style: cmd.style,
+      ...(cmd.runs[0]?.fill ? { fill: cmd.runs[0].fill } : {}),
+    };
+  }
+  // Unreachable while `markCommands` emits only paths and text. A throw rather
+  // than a skip: a new mark kind silently vanishing from every export is a
+  // worse afternoon than a loud one.
+  throw new Error(`[labkit] a mark drew a '${cmd.kind}' command, which has no vector form`);
+}
+
+/**
+ * One mark as SVG nodes, converted from the very commands the pane paints.
+ *
+ * Deliberately not a second switch over `data.kind`: geometry has one source,
+ * and this is a translation of it. `serializeSvg` turns the result into a
+ * document.
+ */
+export function markSvgNodes(
+  m: PaintableMark,
+  content: { w: number; h: number },
+  style: MarkStyle = {},
+): SvgNode[] {
+  return markCommands(m, content, style).map((cmd) => toSvgNode(cmd, m));
+}

package/src/annotations/toolMap.test.ts

@@ -0,0 +1,36 @@
+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';
+
+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('only names weasel tools SceneCanvas will mount', () => {
+    // Against the kit's own list, not a retyped copy: a tool id that stops
+    // 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,
+      );
+    }
+  });
+
+  it('gives select no kind, because it makes no mark', () => {
+    expect(annotationToolInfo('select')).toEqual({ weaselTool: 'select' });
+  });
+
+  it('rides line and pencil for the two kinds with no tool of their own', () => {
+    expect(annotationToolInfo('arrow')).toEqual({ weaselTool: 'line', kind: 'arrow' });
+    expect(annotationToolInfo('stroke')).toEqual({ weaselTool: 'pencil', kind: 'stroke' });
+  });
+
+  it('answers undefined for a tool id that is not one of ours', () => {
+    expect(annotationToolInfo('hand')).toBeUndefined();
+  });
+});

package/src/annotations/toolMap.ts

@@ -0,0 +1,54 @@
+import type { BuiltinToolId } from '@weasel-js/core';
+import {
+  ArrowIcon,
+  EllipseIcon,
+  LineIcon,
+  PencilIcon,
+  RectIcon,
+  SelectIcon,
+  TextIcon,
+} from '@weasel-js/ui';
+import type { TrialTool } from '../tools/types';
+import type { AnnotationKind } from './types';
+
+/** Which weasel tool an annotation tool drives, and what kind of mark that
+ *  makes. `select` makes none. */
+export interface AnnotationToolInfo {
+  weaselTool: BuiltinToolId;
+  kind?: AnnotationKind;
+}
+
+// `arrow` and `stroke` have no weasel tool of their own, so the kind cannot be
+// read back from the insert — the overlay takes it from the tool id it holds.
+const TOOLS: Record<string, AnnotationToolInfo> = {
+  select: { weaselTool: 'select' },
+  stroke: { weaselTool: 'pencil', kind: 'stroke' },
+  line: { weaselTool: 'line', kind: 'line' },
+  arrow: { weaselTool: 'line', kind: 'arrow' },
+  rect: { weaselTool: 'rect', kind: 'rect' },
+  ellipse: { weaselTool: 'ellipse', kind: 'ellipse' },
+  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. */
+export const ANNOTATION_TOOLS: readonly TrialTool[] = [
+  { id: 'select', label: 'Select', icon: SelectIcon, group: 'annotate' },
+  { id: 'stroke', label: 'Freehand', icon: PencilIcon, group: 'annotate' },
+  { id: 'line', label: 'Line', icon: LineIcon, group: 'annotate' },
+  { id: 'arrow', label: 'Arrow', icon: ArrowIcon, group: 'annotate' },
+  { id: 'rect', label: 'Rectangle', icon: RectIcon, group: 'annotate' },
+  { id: 'ellipse', label: 'Ellipse', icon: EllipseIcon, group: 'annotate' },
+  { id: 'text', label: 'Text', icon: TextIcon, group: 'annotate' },
+];
+
+/** 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];
+}
+
+/** Every weasel tool the overlay has to mount for this palette to work. */
+export const ANNOTATION_WEASEL_TOOLS: readonly BuiltinToolId[] = [
+  ...new Set(Object.values(TOOLS).map((t) => t.weaselTool)),
+];