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

package/src/annotations/index.ts

@@ -0,0 +1,37 @@
+export type { CaptureArgs, CapturePlan, ComposeSvgArgs } from './capture';
+export { capturePlan, captureTarget, composeCaptureSvg } from './capture';
+export type { MarkDrawOptions } from './drawOne';
+export { createMarkDrawOne, resolveMarkStyle } from './drawOne';
+export { ExportMenu } from './ExportMenu';
+export type { WorldRect } from './frac';
+export { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+export type { HistoryScene } from './history';
+export { MarkHistory } from './history';
+export type { MarkListProps } from './MarkList';
+export { MarkList } from './MarkList';
+export type { MarkStyle, PaintableMark } from './paint';
+export { markCommands } from './paint';
+export { isStale, seenFrom } from './staleness';
+export type { AnnotationStoreOptions, CaptureDeps, MarkScene } from './store';
+export { annotationsFromJSON, createAnnotationScene, createAnnotationStore } from './store';
+export { markSvgNodes } from './svgNodes';
+export type {
+  Annotation,
+  AnnotationData,
+  AnnotationInit,
+  AnnotationKind,
+  AnnotationMeaning,
+  AnnotationPatch,
+  AnnotationQuery,
+  AnnotationStatus,
+  AnnotationsApi,
+  AnnotationsCapability,
+  AnnotationTarget,
+  AnnotationTargetInfo,
+  CaptureOptions,
+  CaptureResult,
+  CaptureSource,
+  FracPoint,
+  FracRect,
+  SerializedAnnotations,
+} from './types';

package/src/annotations/paint.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { markCommands } from './paint';
+import type { AnnotationData, AnnotationKind, FracPoint } from './types';
+
+const CONTENT = { w: 200, h: 100 };
+const POSE = { x: 20, y: 10, width: 60, height: 40 };
+
+function mark(kind: AnnotationKind, extra: Partial<AnnotationData> = {}) {
+  return { pose: POSE, data: { target: 't', kind, ...extra } as AnnotationData };
+}
+
+/** Every point of the first command's path, in world units. */
+function anchors(cmds: ReturnType<typeof markCommands>): number[] {
+  const cmd = cmds[0];
+  if (cmd?.kind !== 'path') throw new Error('expected a path command');
+  const p = cmd.path as { kind: string; coords?: Float32Array };
+  return p.coords ? [...p.coords] : [];
+}
+
+const ENDS: readonly FracPoint[] = [
+  { x: 0.1, y: 0.2 },
+  { x: 0.6, y: 0.9 },
+];
+
+describe('markCommands', () => {
+  it('draws a rect at the pose', () => {
+    const [cmd] = markCommands(mark('rect'), CONTENT);
+    expect(cmd).toMatchObject({ kind: 'path', path: { kind: 'rect', ...POSE } });
+    expect((cmd as { fill?: unknown }).fill).toBeUndefined();
+  });
+
+  it('draws an ellipse inscribed in the pose', () => {
+    const pts = anchors(markCommands(mark('ellipse'), CONTENT));
+    const xs = pts.filter((_, i) => i % 2 === 0);
+    const ys = pts.filter((_, i) => i % 2 === 1);
+    expect(Math.min(...xs)).toBeCloseTo(POSE.x, 4);
+    expect(Math.max(...xs)).toBeCloseTo(POSE.x + POSE.width, 4);
+    expect(Math.min(...ys)).toBeCloseTo(POSE.y, 4);
+    expect(Math.max(...ys)).toBeCloseTo(POSE.y + POSE.height, 4);
+  });
+
+  it('runs a line between its two stored ends, converted to world', () => {
+    expect(anchors(markCommands(mark('line', { points: ENDS }), CONTENT))).toEqual([
+      0.1 * 200,
+      0.2 * 100,
+      0.6 * 200,
+      0.9 * 100,
+    ]);
+  });
+
+  it('makes an arrow the same line, plus the head as its own command', () => {
+    const cmds = markCommands(mark('arrow', { points: ENDS }), CONTENT);
+    const stroke = (cmds[0] as { stroke?: { markerEnd?: unknown } }).stroke;
+    expect(stroke?.markerEnd).toBe('arrow');
+    expect(anchors([cmds[0]])).toEqual([0.1 * 200, 0.2 * 100, 0.6 * 200, 0.9 * 100]);
+
+    // The head has to be geometry, not just a field: `markerEnd` alone is
+    // inert outside the kit's own node painter, which is what shipped an
+    // arrow with no head.
+    expect(cmds).toHaveLength(2);
+    const head = anchors([cmds[1]]);
+    expect(head.length).toBeGreaterThan(0);
+    // Its vertex is the line's far end — computed, not eyeballed.
+    const near = (v: number, t: number) => Math.abs(v - t) < 1;
+    const xs = head.filter((_, i) => i % 2 === 0);
+    const ys = head.filter((_, i) => i % 2 === 1);
+    expect(xs.some((x, i) => near(x, 120) && near(ys[i] as number, 90))).toBe(true);
+  });
+
+  it('threads a freehand stroke through every point', () => {
+    const pts: FracPoint[] = [
+      { x: 0, y: 0 },
+      { x: 0.5, y: 0.5 },
+      { x: 1, y: 0 },
+    ];
+    expect(anchors(markCommands(mark('stroke', { points: pts }), CONTENT))).toEqual([
+      0, 0, 100, 50, 200, 0,
+    ]);
+  });
+
+  it('falls back to the pose diagonal when a points kind has no points', () => {
+    // A stored mark from a writer that dropped `points` must still draw
+    // something at the right place, not vanish.
+    expect(anchors(markCommands(mark('line'), CONTENT))).toEqual([
+      POSE.x,
+      POSE.y,
+      POSE.x + POSE.width,
+      POSE.y + POSE.height,
+    ]);
+  });
+
+  it('draws text at the pose, carrying the title', () => {
+    const [cmd] = markCommands(mark('text', { title: 'missing edge' }), CONTENT);
+    expect(cmd).toMatchObject({ kind: 'text', x: POSE.x, y: POSE.y });
+    const runs = (cmd as { runs: { text: string }[] }).runs;
+    expect(runs.map((r) => r.text).join('')).toBe('missing edge');
+  });
+
+  it('draws an untitled text mark as nothing rather than an empty run', () => {
+    expect(markCommands(mark('text'), CONTENT)).toEqual([]);
+  });
+});
+
+describe('markCommands styling', () => {
+  it('takes a status colour over the default', () => {
+    const [cmd] = markCommands(mark('rect'), CONTENT, { color: '#30a46c' });
+    expect((cmd as { stroke?: { paint?: { color?: string } } }).stroke?.paint?.color).toBe(
+      '#30a46c',
+    );
+  });
+
+  it('dashes a stale mark rather than hiding it', () => {
+    // A stale mark still describes something; dropping it would lose it.
+    const [fresh] = markCommands(mark('rect'), CONTENT);
+    const [stale] = markCommands(mark('rect'), CONTENT, { stale: true });
+    expect((fresh as { stroke?: { dash?: number[] } }).stroke?.dash).toBeUndefined();
+    expect((stale as { stroke?: { dash?: number[] } }).stroke?.dash).toEqual([6, 4]);
+  });
+
+  it("colours 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

@@ -0,0 +1,130 @@
+import type { DrawCommand, Path, Stroke } from '@weasel-js/core';
+import {
+  ellipsePath,
+  linePath,
+  markerDrawCommands,
+  PathBuilder,
+  rectPath,
+  textCommand,
+} from '@weasel-js/core';
+import type { WorldRect } from './frac';
+import type { AnnotationData, FracPoint } from './types';
+
+/** One loud color, not a themed one: a mark sits over the instrument's own
+ *  picture and has to be legible against whatever that picture is. */
+const MARK_COLOR = '#e5484d';
+/** World units, so a mark thickens with the picture it annotates — and so the
+ *  marker geometry can be resolved here, which needs a resolved width. */
+const MARK_WIDTH = 2;
+const TEXT_SIZE = 14;
+
+/** The subset of a mark's scene node this needs: where it is, and what it is. */
+export interface PaintableMark {
+  pose: WorldRect;
+  data: AnnotationData;
+}
+
+/** 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. */
+  color?: string;
+  /** A mark whose stored position no longer describes the picture. Drawn
+   *  dashed rather than hidden: it still describes *something*, and dropping
+   *  it would lose it. */
+  stale?: boolean;
+}
+
+const toWorld = (p: FracPoint, content: { w: number; h: number }) => ({
+  x: p.x * content.w,
+  y: p.y * content.h,
+});
+
+/** A mark's stored vertices in world units, or the pose's diagonal — a stored
+ *  mark whose `points` did not survive still has to draw somewhere. */
+function vertices(m: PaintableMark, content: { w: number; h: number }): { x: number; y: number }[] {
+  const stored = m.data.points;
+  if (stored && stored.length >= 2) return stored.map((p) => toWorld(p, content));
+  const { x, y, width, height } = m.pose;
+  return [
+    { x, y },
+    { x: x + width, y: y + height },
+  ];
+}
+
+function polyline(points: { x: number; y: number }[]): Path {
+  const b = new PathBuilder();
+  const first = points[0];
+  if (!first) return rectPath(0, 0, 0, 0);
+  b.moveTo(first.x, first.y);
+  for (const p of points.slice(1)) b.lineTo(p.x, p.y);
+  return b.build();
+}
+
+/**
+ * What one mark draws, in its target's world.
+ *
+ * Pure: a node and the target's content box in, draw commands out. Geometry
+ * that a bounding box cannot describe — a line's ends, a stroke's path — comes
+ * from `data.points`, which is in fractions like the bounds.
+ */
+export function markCommands(
+  m: PaintableMark,
+  content: { w: number; h: number },
+  style: MarkStyle = {},
+): DrawCommand[] {
+  const color = style.color ?? MARK_COLOR;
+  const stroke: Stroke = {
+    paint: { color },
+    width: MARK_WIDTH,
+    cap: 'round',
+    join: 'round',
+    ...(style.stale ? { dash: [6, 4] } : {}),
+  };
+
+  switch (m.data.kind) {
+    case 'rect':
+      return [
+        { kind: 'path', path: rectPath(m.pose.x, m.pose.y, m.pose.width, m.pose.height), stroke },
+      ];
+    case 'ellipse':
+      return [{ kind: 'path', path: ellipsePath(m.pose), stroke }];
+    case 'line': {
+      const [a, b] = vertices(m, content);
+      return [{ kind: 'path', path: linePath(a, b), stroke }];
+    }
+    case 'arrow': {
+      const [a, b] = vertices(m, content);
+      // The spec's arrow: a line carrying an end marker, not its own geometry.
+      // Markers are separate commands — a stroke's `markerEnd` is inert unless
+      // something turns it into geometry, and only the kit's own node painter
+      // does that, for the nodes it owns.
+      const marked: Stroke = { ...stroke, markerEnd: 'arrow' };
+      const path = linePath(a, b);
+      return [
+        { kind: 'path', path, stroke: marked },
+        ...markerDrawCommands(path, marked, MARK_WIDTH, undefined),
+      ];
+    }
+    case 'stroke':
+      return [{ kind: 'path', path: polyline(vertices(m, content)), stroke }];
+    case 'text': {
+      const text = m.data.title;
+      if (!text) return [];
+      return [
+        textCommand(
+          m.pose.x,
+          m.pose.y,
+          text,
+          { fontSize: TEXT_SIZE },
+          undefined,
+          undefined,
+          undefined,
+          {
+            fill: { color },
+          },
+        ),
+      ];
+    }
+  }
+}

package/src/annotations/staleness.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { isStale, seenFrom } from './staleness';
+
+const KEYS = ['angle', 'shading', 'shade_style'] as const;
+const CONFIG = { angle: 'iso', shading: 'outline', shade_style: 'flat3', render_px: 512 };
+
+describe('seenFrom', () => {
+  it('snapshots only the declared keys', () => {
+    // render_px is deliberately not declared: the mark is fractional, so
+    // resolution does not move it.
+    expect(seenFrom(CONFIG, KEYS)).toEqual({
+      angle: 'iso',
+      shading: 'outline',
+      shade_style: 'flat3',
+    });
+  });
+
+  it('omits a declared key the config does not carry', () => {
+    expect(seenFrom({ angle: 'top' }, KEYS)).toEqual({ angle: 'top' });
+  });
+
+  it('is empty when nothing is declared', () => {
+    expect(seenFrom(CONFIG, [])).toEqual({});
+  });
+});
+
+describe('isStale', () => {
+  it('is not stale against the config it was taken from', () => {
+    expect(isStale(seenFrom(CONFIG, KEYS), CONFIG, KEYS)).toBe(false);
+  });
+
+  it('is stale when a declared key changed', () => {
+    const seen = seenFrom(CONFIG, KEYS);
+    expect(isStale(seen, { ...CONFIG, angle: 'top' }, KEYS)).toBe(true);
+  });
+
+  it('ignores an undeclared key changing', () => {
+    const seen = seenFrom(CONFIG, KEYS);
+    expect(isStale(seen, { ...CONFIG, render_px: 1024 }, KEYS)).toBe(false);
+  });
+
+  it('ignores a key the stored snapshot never had', () => {
+    // A mark filed before the target declared a new dependency must not go
+    // stale retroactively — nothing can know what that key was at the time.
+    const old = { angle: 'iso' };
+    expect(isStale(old, CONFIG, KEYS)).toBe(false);
+  });
+
+  it('is not stale with no snapshot at all', () => {
+    expect(isStale(undefined, CONFIG, KEYS)).toBe(false);
+  });
+
+  it('is never stale when the target declares no dependencies', () => {
+    expect(isStale(seenFrom(CONFIG, KEYS), { angle: 'top' }, [])).toBe(false);
+  });
+});

package/src/annotations/staleness.ts

@@ -0,0 +1,41 @@
+/**
+ * Whether a stored mark still describes the picture the current config
+ * produces. A target names the config keys its positions depend on; labkit
+ * snapshots and compares them without knowing what any of them mean.
+ */
+
+/** The values of `keys` in `config`, for storing beside a new mark. Keys the
+ *  config does not carry are omitted rather than stored as undefined, so the
+ *  snapshot says what was known rather than what was asked. */
+export function seenFrom(config: unknown, keys: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (config === null || typeof config !== 'object') return out;
+  const src = config as Record<string, unknown>;
+  for (const k of keys) {
+    if (k in src) out[k] = src[k];
+  }
+  return out;
+}
+
+/**
+ * Whether the picture moved under the mark.
+ *
+ * Only keys present in `seen` are compared. A mark filed before its target
+ * declared a new dependency must not go stale retroactively: nothing can know
+ * what that key was at the time, and guessing would grey out every old mark
+ * the first time a target grows a key.
+ */
+export function isStale(
+  seen: Readonly<Record<string, unknown>> | undefined,
+  config: unknown,
+  keys: readonly string[],
+): boolean {
+  if (!seen || keys.length === 0) return false;
+  if (config === null || typeof config !== 'object') return false;
+  const src = config as Record<string, unknown>;
+  for (const k of keys) {
+    if (!(k in seen)) continue;
+    if (!Object.is(seen[k], src[k])) return true;
+  }
+  return false;
+}

package/src/annotations/store.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from 'vitest';
+import { annotationsFromJSON, createAnnotationStore } from './store';
+import type { AnnotationInit, AnnotationTargetInfo } from './types';
+
+const TARGETS: AnnotationTargetInfo[] = [
+  { id: 'naive', content: { w: 256, h: 170 }, positionDependsOn: ['angle', 'shading'] },
+  { id: 'occt', content: { w: 256, h: 170 } },
+];
+
+function makeStore() {
+  return createAnnotationStore({ targets: () => TARGETS });
+}
+
+const RING: AnnotationInit = {
+  target: 'naive',
+  kind: 'rect',
+  frac: { x: 0.3322, y: 0.3581, w: 0.02, h: 0.0861 },
+  title: 'spurious ring at r=12.80',
+  status: 'open',
+  tags: ['geometry'],
+  meta: { engines: ['naive'] },
+};
+
+describe('the annotation store', () => {
+  it('round-trips every field through add and get', () => {
+    const store = makeStore();
+    const id = store.add(RING, { angle: 'iso', shading: 'outline' });
+    const got = store.get(id);
+    expect(got).toMatchObject({
+      id,
+      target: 'naive',
+      kind: 'rect',
+      frac: RING.frac,
+      title: RING.title,
+      status: 'open',
+      tags: ['geometry'],
+      meta: { engines: ['naive'] },
+      seen: { angle: 'iso', shading: 'outline' },
+    });
+  });
+
+  it('dates a mark only by the keys its target declared', () => {
+    const store = makeStore();
+    const onOcct = store.add({ ...RING, target: 'occt' }, { angle: 'iso' });
+    // 'occt' declares no dependencies, so nothing is worth snapshotting.
+    expect(store.get(onOcct)?.seen).toEqual({});
+  });
+
+  it('filters by target, kind, status, tags and a predicate', () => {
+    const store = makeStore();
+    store.add(RING);
+    store.add({ ...RING, target: 'occt', status: 'fixed', tags: ['shading'] });
+    store.add({ ...RING, kind: 'line', tags: ['geometry', 'edge'] });
+
+    expect(store.query({ target: 'naive' })).toHaveLength(2);
+    expect(store.query({ kind: 'line' })).toHaveLength(1);
+    expect(store.query({ status: 'fixed' })).toHaveLength(1);
+    expect(store.query({ tags: ['geometry'] })).toHaveLength(2);
+    // Every listed tag must be present, not just one.
+    expect(store.query({ tags: ['geometry', 'edge'] })).toHaveLength(1);
+    expect(store.query({ where: (a) => a.title === RING.title })).toHaveLength(3);
+    expect(store.query()).toHaveLength(3);
+  });
+
+  it('hit-tests a point, and widens the hit by the tolerance', () => {
+    const store = makeStore();
+    const id = store.add({ ...RING, frac: { x: 0.2, y: 0.2, w: 0.2, h: 0.2 } });
+
+    expect(store.hitTest('naive', { x: 0.3, y: 0.3 }).map((a) => a.id)).toEqual([id]);
+    expect(store.hitTest('naive', { x: 0.15, y: 0.3 })).toHaveLength(0);
+    expect(store.hitTest('naive', { x: 0.15, y: 0.3 }, 0.06)).toHaveLength(1);
+    // A target's marks are its own.
+    expect(store.hitTest('occt', { x: 0.3, y: 0.3 })).toHaveLength(0);
+  });
+
+  it("keeps each target in its own scene, so a pane never sees a neighbour's marks", () => {
+    const store = makeStore();
+    store.add(RING);
+    store.add({ ...RING, target: 'occt' });
+    // Not a filter over one scene: the scene a pane is handed holds only its
+    // own marks, because its hit-test and marquee walk all of what they get.
+    expect(store.sceneFor('naive').renderOrder()).toHaveLength(1);
+    expect(store.sceneFor('occt').renderOrder()).toHaveLength(1);
+    expect(store.query({ target: 'naive' }).map((a) => a.target)).toEqual(['naive']);
+  });
+
+  it('takes what a box encloses, not what it grazes', () => {
+    const store = makeStore();
+    // The box is (0.2,0.2)-(0.6,0.6). `straddling` overlaps it but hangs out
+    // past the far corner — the case that separates enclosure from mere
+    // overlap. Two marks that are both wholly outside would not.
+    const inside = store.add({ ...RING, frac: { x: 0.3, y: 0.3, w: 0.1, h: 0.1 } });
+    store.add({ ...RING, frac: { x: 0.5, y: 0.5, w: 0.3, h: 0.3 } });
+    store.add({ ...RING, frac: { x: 0.7, y: 0.7, w: 0.2, h: 0.2 } });
+
+    const got = store.within('naive', { x: 0.2, y: 0.2, w: 0.4, h: 0.4 });
+    expect(got.map((a) => a.id)).toEqual([inside]);
+  });
+
+  it('patches meaning without moving geometry, and geometry without losing meaning', () => {
+    const store = makeStore();
+    const id = store.add(RING);
+
+    store.update(id, { status: 'fixed' });
+    expect(store.get(id)?.status).toBe('fixed');
+    expect(store.get(id)?.frac).toEqual(RING.frac);
+
+    store.update(id, { frac: { x: 0.1, y: 0.1, w: 0.3, h: 0.3 } });
+    expect(store.get(id)?.frac).toEqual({ x: 0.1, y: 0.1, w: 0.3, h: 0.3 });
+    expect(store.get(id)?.status).toBe('fixed');
+    expect(store.get(id)?.title).toBe(RING.title);
+  });
+
+  it('replaces meta and nothing else', () => {
+    const store = makeStore();
+    const id = store.add(RING);
+    store.setMeta(id, { engines: ['naive', 'occt'] });
+    expect(store.get(id)?.meta).toEqual({ engines: ['naive', 'occt'] });
+    expect(store.get(id)?.title).toBe(RING.title);
+  });
+
+  it('removes a mark', () => {
+    const store = makeStore();
+    const id = store.add(RING);
+    store.remove(id);
+    expect(store.get(id)).toBeUndefined();
+    expect(store.query()).toHaveLength(0);
+  });
+
+  it('answers staleness from the target the mark is on', () => {
+    const store = makeStore();
+    const id = store.add(RING, { angle: 'iso', shading: 'outline' });
+    const mark = store.get(id);
+    if (!mark) throw new Error('unreachable');
+
+    expect(store.isStale(mark, { angle: 'iso', shading: 'outline' })).toBe(false);
+    expect(store.isStale(mark, { angle: 'top', shading: 'outline' })).toBe(true);
+    // render_px is not declared, so it cannot make anything stale.
+    expect(store.isStale(mark, { angle: 'iso', shading: 'outline', render_px: 1 })).toBe(false);
+  });
+
+  it('notifies subscribers on each mutation, and stops after unsubscribe', () => {
+    const store = makeStore();
+    const fn = vi.fn();
+    const off = store.subscribe(fn);
+
+    const id = store.add(RING);
+    store.update(id, { status: 'fixed' });
+    store.remove(id);
+    expect(fn.mock.calls.length).toBeGreaterThanOrEqual(3);
+
+    const before = fn.mock.calls.length;
+    off();
+    store.add(RING);
+    expect(fn.mock.calls.length).toBe(before);
+  });
+
+  it('round-trips through JSON, and the snapshot is JSON-clean', () => {
+    const store = makeStore();
+    const id = store.add(RING, { angle: 'iso', shading: 'outline' });
+
+    const out = store.toJSON();
+    // Assert JSON-safety directly rather than trusting the shape by eye:
+    // labkit stringifies record.state raw, because Instrument.serialize never
+    // runs, so a Map or a class instance in here would be lost silently.
+    expect(JSON.parse(JSON.stringify(out))).toEqual(out);
+    expect(out.version).toBe(1);
+    // One scene per target, and only the ones that hold a mark.
+    expect(Object.keys(out.scenes)).toEqual(['naive']);
+
+    const revived = annotationsFromJSON(JSON.parse(JSON.stringify(out)), () => TARGETS);
+    expect(revived.get(id)).toEqual(store.get(id));
+    expect(revived.query()).toHaveLength(1);
+  });
+});