@weasel-js/labkit 1.6.1 → 1.7.1

package/src/annotations/store.test.ts

@@ -1,6 +1,8 @@
+import { asNodeId } from '@weasel-js/core';
 import { describe, expect, it, vi } from 'vitest';
+import { markCommands } from './paint';
 import { annotationsFromJSON, createAnnotationStore } from './store';
-import type { AnnotationInit, AnnotationTargetInfo } from './types';
+import type { AnnotationInit, AnnotationsApi, AnnotationTargetInfo, FracPoint } from './types';
 
 const TARGETS: AnnotationTargetInfo[] = [
   { id: 'naive', content: { w: 256, h: 170 }, positionDependsOn: ['angle', 'shading'] },
@@ -162,7 +164,7 @@ describe('the annotation store', () => {
   // because jsdom has no WebGL2 and the overlay's canvas never paints or
   // hit-tests. That the canvas is bound to this scene is core's claim.
   it('merges the selection across targets, and maps it back to annotation ids', () => {
-    const store = makeStore();
+    const store = createAnnotationStore({ targets: () => TARGETS, selection: 'per-target' });
     const onNaive = store.add(RING);
     const onOcct = store.add({ ...RING, target: 'occt' });
 
@@ -227,6 +229,86 @@ describe('the annotation store', () => {
     expect(fn.mock.calls.length).toBe(before);
   });
 
+  describe('across targets', () => {
+    /** Selects a mark the way its pane's canvas does: on that target's scene. */
+    const click = (store: AnnotationsApi, id: string): void => {
+      const [target, node] = id.split('/') as [string, string];
+      store.sceneFor(target).setSelection([asNodeId(node)]);
+    };
+
+    it('clears a selection standing in one target when a mark is selected in another', () => {
+      const store = makeStore();
+      const onNaive = store.add(RING);
+      const onOcct = store.add({ ...RING, target: 'occt' });
+
+      click(store, onNaive);
+      click(store, onOcct);
+      expect(store.selection()).toEqual([onOcct]);
+      expect(store.sceneFor('naive').getSelection()).toEqual([]);
+    });
+
+    it('tells subscribers once, after the other target is already cleared', () => {
+      const store = makeStore();
+      const onNaive = store.add(RING);
+      const onOcct = store.add({ ...RING, target: 'occt' });
+      click(store, onNaive);
+
+      const seen: (readonly string[])[] = [];
+      store.subscribe(() => seen.push(store.selection()));
+      click(store, onOcct);
+      expect(seen).toEqual([[onOcct]]);
+    });
+
+    it('keeps a setSelection naming two targets to the first one, in one event', () => {
+      const store = makeStore();
+      const onNaive = store.add(RING);
+      const onOcct = store.add({ ...RING, target: 'occt' });
+      click(store, onNaive);
+
+      const fn = vi.fn();
+      store.subscribe(fn);
+      store.setSelection([onOcct, onNaive]);
+      expect(store.selection()).toEqual([onOcct]);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('leaves the other target alone for a change that selects nothing new', () => {
+      const store = makeStore();
+      const onNaive = store.add(RING);
+      store.add({ ...RING, target: 'occt' });
+      click(store, onNaive);
+
+      store.add({ ...RING, target: 'occt' });
+      store.sceneFor('occt').setSelection([]);
+      expect(store.selection()).toEqual([onNaive]);
+    });
+
+    it("keeps each target's own selection under `selection: 'per-target'`", () => {
+      const store = createAnnotationStore({ targets: () => TARGETS, selection: 'per-target' });
+      const onNaive = store.add(RING);
+      const onOcct = store.add({ ...RING, target: 'occt' });
+
+      click(store, onNaive);
+      click(store, onOcct);
+      expect(store.selection()).toEqual([onNaive, onOcct]);
+
+      store.setSelection([onOcct, onNaive]);
+      expect(store.selection()).toEqual([onNaive, onOcct]);
+    });
+
+    it('reads the mode at each change, for a capability swapped under a live store', () => {
+      let mode: 'exclusive' | 'per-target' = 'per-target';
+      const store = createAnnotationStore({ targets: () => TARGETS, selection: () => mode });
+      const onNaive = store.add(RING);
+      const onOcct = store.add({ ...RING, target: 'occt' });
+
+      click(store, onNaive);
+      mode = 'exclusive';
+      click(store, onOcct);
+      expect(store.selection()).toEqual([onOcct]);
+    });
+  });
+
   it('round-trips through JSON, and the snapshot is JSON-clean', () => {
     const store = makeStore();
     const id = store.add(RING, { angle: 'iso', shading: 'outline' });
@@ -295,6 +377,134 @@ describe('the annotation store', () => {
   });
 });
 
+/** What a target's first mark draws, as its path's points in fractions of the
+ *  content box — the drawn side, to hold against what the store hit-tests. */
+function drawn(store: AnnotationsApi, target = 'naive'): FracPoint[] {
+  const { w, h } = TARGETS.find((t) => t.id === target)?.content ?? { w: 0, h: 0 };
+  const [painted] = store.paintedMarks(target);
+  if (!painted) throw new Error('no mark painted');
+  const [cmd] = markCommands(painted.mark, painted.style);
+  if (cmd?.kind !== 'path') throw new Error('expected a path command');
+  const coords = [...((cmd.path as { coords?: Float32Array }).coords ?? [])];
+  const out: FracPoint[] = [];
+  for (let i = 0; i < coords.length; i += 2) {
+    out.push({ x: (coords[i] ?? 0) / w, y: (coords[i + 1] ?? 0) / h });
+  }
+  return out;
+}
+
+const centerOf = (pts: FracPoint[]): FracPoint => {
+  const xs = pts.map((p) => p.x);
+  const ys = pts.map((p) => p.y);
+  return {
+    x: (Math.min(...xs) + Math.max(...xs)) / 2,
+    y: (Math.min(...ys) + Math.max(...ys)) / 2,
+  };
+};
+
+const expectNear = (got: readonly FracPoint[], want: readonly FracPoint[]) => {
+  expect(got).toHaveLength(want.length);
+  got.forEach((p, i) => {
+    expect(p.x).toBeCloseTo(want[i]?.x ?? Number.NaN, 3);
+    expect(p.y).toBeCloseTo(want[i]?.y ?? Number.NaN, 3);
+  });
+};
+
+describe('a moved mark', () => {
+  const POINT: AnnotationInit = {
+    target: 'naive',
+    kind: 'point',
+    frac: { x: 0.25, y: 0.5, w: 0, h: 0 },
+    points: [{ x: 0.25, y: 0.5 }],
+  };
+  const LINE: AnnotationInit = {
+    target: 'naive',
+    kind: 'line',
+    frac: { x: 0.1, y: 0.2, w: 0.5, h: 0.4 },
+    points: [
+      { x: 0.1, y: 0.6 },
+      { x: 0.6, y: 0.2 },
+    ],
+  };
+
+  it('draws a point where the store hit-tests it after update moves it', () => {
+    const store = makeStore();
+    const id = store.add(POINT);
+    store.update(id, { frac: { x: 0.75, y: 0.25, w: 0, h: 0 } });
+
+    expectNear([centerOf(drawn(store))], [{ x: 0.75, y: 0.25 }]);
+    expect(store.hitTest('naive', { x: 0.75, y: 0.25 }, 0.001).map((a) => a.id)).toEqual([id]);
+    expect(store.get(id)?.points).toEqual([{ x: 0.75, y: 0.25 }]);
+  });
+
+  it('carries a line and a stroke along with their bounds', () => {
+    for (const kind of ['line', 'arrow', 'stroke'] as const) {
+      const store = makeStore();
+      const id = store.add({ ...LINE, kind });
+      store.update(id, { frac: { x: 0.3, y: 0.3, w: 0.5, h: 0.4 } });
+      const moved = [
+        { x: 0.3, y: 0.7 },
+        { x: 0.8, y: 0.3 },
+      ];
+      expectNear(drawn(store), moved);
+      expect(store.get(id)?.points).toEqual(moved);
+    }
+  });
+
+  it('stretches stored vertices with a resized box', () => {
+    const store = makeStore();
+    const id = store.add(LINE);
+    store.update(id, { frac: { x: 0.1, y: 0.2, w: 0.25, h: 0.8 } });
+    expectNear(drawn(store), [
+      { x: 0.1, y: 1 },
+      { x: 0.35, y: 0.2 },
+    ]);
+  });
+
+  it('follows a pose written straight to the scene, the way the pane moves a mark', () => {
+    const store = makeStore();
+    const id = store.add(POINT);
+    const node = asNodeId(id.slice(id.lastIndexOf('/') + 1));
+    store.sceneFor('naive').setPose(node, { x: 0.5 * 256, y: 0.1 * 170, width: 0, height: 0 });
+
+    expectNear([centerOf(drawn(store))], [{ x: 0.5, y: 0.1 }]);
+    expect(store.get(id)?.points).toEqual([{ x: 0.5, y: 0.1 }]);
+  });
+
+  it('moves the bounds when only the points are patched', () => {
+    const store = makeStore();
+    const id = store.add(POINT);
+    store.update(id, { points: [{ x: 0.9, y: 0.9 }] });
+
+    expect(store.get(id)?.frac).toEqual({ x: 0.9, y: 0.9, w: 0, h: 0 });
+    expectNear([centerOf(drawn(store))], [{ x: 0.9, y: 0.9 }]);
+  });
+
+  it('reads points a store saved in content fractions, before they followed the bounds', () => {
+    const legacy = {
+      version: 1,
+      scenes: {
+        naive: {
+          version: 1,
+          systemLayers: [{ id: 'marks' }],
+          nodes: [
+            {
+              id: 'n1',
+              kind: 'leaf',
+              layer: 'marks',
+              pose: { x: 0.1 * 256, y: 0.2 * 170, width: 0.5 * 256, height: 0.4 * 170 },
+              data: { target: 'naive', kind: 'line', points: LINE.points },
+            },
+          ],
+        },
+      },
+    };
+    const store = annotationsFromJSON(legacy, () => TARGETS);
+    expectNear(drawn(store), LINE.points ?? []);
+    expect(store.get('naive/n1')?.points).toEqual(LINE.points);
+  });
+});
+
 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' };

package/src/annotations/store.ts

@@ -8,7 +8,17 @@ import {
 import { captureTarget } from './capture';
 import { type MarkDrawOptions, resolveMarkStyle } from './drawOne';
 import type { WorldRect } from './frac';
-import { fracContains, fracEncloses, fracToWorld, roundFrac, worldToFrac } from './frac';
+import {
+  boundsOf,
+  fracContains,
+  fracEncloses,
+  fracToWorld,
+  fromShape,
+  roundFrac,
+  roundPoints,
+  toShape,
+  worldToFrac,
+} from './frac';
 import { MarkHistory } from './history';
 import { isStale as isStaleAgainst, seenFrom } from './staleness';
 import type {
@@ -18,6 +28,7 @@ import type {
   AnnotationMeaning,
   AnnotationPatch,
   AnnotationQuery,
+  AnnotationSelectionMode,
   AnnotationsApi,
   AnnotationTargetInfo,
   CaptureOptions,
@@ -38,6 +49,7 @@ export function createAnnotationScene(): MarkScene {
   return createScene<AnnotationData, 'marks', MarkPose>({ systemLayers: [{ id: 'marks' }] });
 }
 
+/** Inputs to `createAnnotationStore`. */
 export interface AnnotationStoreOptions {
   /** Re-read on every call, so a target resizing or gaining a dependency takes
    *  effect without rebuilding the store. */
@@ -53,6 +65,10 @@ export interface AnnotationStoreOptions {
   config?: () => unknown;
   /** Notified after every finished export. */
   onCapture?: (result: CaptureResult) => void;
+  /** Whether a selection can stand in several targets at once. `'exclusive'`
+   *  (the default) clears every other target when a mark is selected in one.
+   *  A thunk is read at each selection change. */
+  selection?: AnnotationSelectionMode | (() => AnnotationSelectionMode | undefined);
 }
 
 /** Everything a capture needs that is not the store's own state. Split out so
@@ -66,6 +82,34 @@ export interface CaptureDeps {
 
 const NO_CONTENT = { w: 0, h: 0 };
 
+/** Where a mark's vertices sit in its own bounds, from points in the content
+ *  box. A point has none to store: its bounds are its position. */
+function shapeFor(
+  kind: AnnotationData['kind'],
+  points: readonly FracPoint[] | undefined,
+  frac: FracRect,
+): readonly FracPoint[] | undefined {
+  if (!points || kind === 'point') return undefined;
+  return roundPoints(toShape(points, frac));
+}
+
+type SerializedMarks = SerializedScene<AnnotationData, 'marks', MarkPose>;
+
+/** Scenes saved before vertices followed the bounds hold them as `points` in
+ *  the content box. Restated against each mark's bounds as saved. */
+function migrateLegacyPoints(
+  raw: SerializedMarks,
+  content: { w: number; h: number },
+): SerializedMarks {
+  const nodes = raw.nodes.map((n) => {
+    const { points, ...data } = n.data as AnnotationData & { points?: readonly FracPoint[] };
+    if (!points || data.shape) return n;
+    const shape = shapeFor(data.kind, points, worldToFrac(n.pose, content));
+    return { ...n, data: { ...data, ...(shape ? { shape } : {}) } };
+  });
+  return { ...raw, nodes };
+}
+
 /** 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 {
@@ -92,21 +136,73 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
     for (const fn of subs) fn();
   };
 
+  // Scene changes made while held are told to subscribers as one, once the
+  // outermost hold ends — so a click that also clears another target, or a
+  // `setSelection` spanning several, is one event with the final answer.
+  let holding = 0;
+  let heldDirty = false;
+  const hold = (fn: () => void): void => {
+    holding += 1;
+    try {
+      fn();
+    } finally {
+      holding -= 1;
+    }
+    if (holding === 0 && heldDirty) {
+      heldDirty = false;
+      notify();
+    }
+  };
+
+  const exclusive = (): boolean =>
+    (typeof opts.selection === 'function' ? opts.selection() : opts.selection) !== 'per-target';
+
+  /** Each scene's selection as last seen, to tell a selection change from any
+   *  other change arriving on the same channel. */
+  const lastSelection = new Map<string, string>();
+  const selectionKey = (scene: MarkScene): string => scene.getSelection().map(String).join(' ');
+
+  const clearOthers = (keep: string): void => {
+    for (const [target, scene] of scenes) {
+      if (target !== keep && scene.getSelection().length > 0) scene.setSelection([]);
+    }
+  };
+
+  const targetOf = (id: string): AnnotationTargetInfo | undefined =>
+    targets().find((t) => t.id === id);
+
+  const contentOf = (id: string) => targetOf(id)?.content ?? NO_CONTENT;
+
   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>,
+          migrateLegacyPoints(raw as SerializedMarks, contentOf(target)),
           {},
         )
       : createAnnotationScene();
     scenes.set(target, scene);
     history.track(target, scene);
+    lastSelection.set(target, selectionKey(scene));
     scene.subscribe(() => {
       history.observe(target, scene);
-      notify();
+      const selected = selectionKey(scene);
+      const newlySelected = selected !== '' && selected !== lastSelection.get(target);
+      lastSelection.set(target, selected);
+      if (holding > 0) {
+        heldDirty = true;
+        return;
+      }
+      if (newlySelected && exclusive()) {
+        hold(() => {
+          heldDirty = true;
+          clearOthers(target);
+        });
+      } else {
+        notify();
+      }
     });
     return scene;
   };
@@ -120,10 +216,6 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
   // 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;
   /** 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 => ({
@@ -136,12 +228,13 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
   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))),
-    };
+    const { shape, ...data } = found.data;
+    const frac = roundFrac(worldToFrac(found.pose as MarkPose, contentOf(target)));
+    const points =
+      data.kind === 'point'
+        ? [{ x: frac.x, y: frac.y }]
+        : shape && roundPoints(fromShape(shape, frac));
+    return { ...data, target, id: `${target}/${node}`, frac, ...(points ? { points } : {}) };
   };
 
   /** Every target with a scene, in declaration order — then any whose target
@@ -245,20 +338,24 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
 
     setSelection(ids) {
       const wanted = new Map<string, string[]>();
+      const only = exclusive();
       for (const id of ids) {
         const found = nodeOf(id);
         if (!found) continue;
+        if (only && wanted.size > 0 && !wanted.has(found.target)) continue;
         const node = String(found.node.id);
         const on = wanted.get(found.target);
         if (!on) wanted.set(found.target, [node]);
         else if (!on.includes(node)) on.push(node);
       }
-      for (const [target, scene] of scenes) {
-        const next = wanted.get(target) ?? [];
-        const now = scene.getSelection();
-        if (now.length === next.length && next.every((n, i) => String(now[i]) === n)) continue;
-        scene.setSelection(next.map(asNodeId));
-      }
+      hold(() => {
+        for (const [target, scene] of scenes) {
+          const next = wanted.get(target) ?? [];
+          const now = scene.getSelection();
+          if (now.length === next.length && next.every((n, i) => String(now[i]) === n)) continue;
+          scene.setSelection(next.map(asNodeId));
+        }
+      });
     },
 
     subscribe(fn) {
@@ -270,10 +367,12 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
 
     add(init: AnnotationInit, config?: unknown) {
       const target = targetOf(init.target);
+      const frac = roundFrac(init.frac);
+      const shape = shapeFor(init.kind, init.points, frac);
       const data: AnnotationData = {
         target: init.target,
         kind: init.kind,
-        ...(init.points ? { points: init.points } : {}),
+        ...(shape ? { shape } : {}),
         ...(init.title !== undefined ? { title: init.title } : {}),
         ...(init.status !== undefined ? { status: init.status } : {}),
         ...(init.tags !== undefined ? { tags: init.tags } : {}),
@@ -283,7 +382,7 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
       const node = sceneFor(init.target).add({
         kind: 'leaf',
         layer: 'marks',
-        pose: fracToWorld(roundFrac(init.frac), target?.content ?? NO_CONTENT),
+        pose: fracToWorld(frac, target?.content ?? NO_CONTENT),
         data,
       });
       return `${init.target}/${String(node)}`;
@@ -292,14 +391,18 @@ export function createAnnotationStore(opts: AnnotationStoreOptions): Annotations
     update(id, patch: AnnotationPatch) {
       const found = nodeOf(id);
       if (!found) return;
-      const { frac, ...meaning } = patch;
+      const { frac: fracPatch, points, ...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)));
+      const content = contentOf(found.target);
+      const frac = fracPatch ?? (points ? boundsOf(points) : null);
+      const bounds = roundFrac(frac ?? worldToFrac(found.node.pose as MarkPose, content));
+      const shape = points ? shapeFor(found.node.data.kind, points, bounds) : undefined;
+      if (Object.keys(meaning).length > 0 || shape) {
+        found.scene.update(nid, {
+          data: { ...found.node.data, ...meaning, ...(shape ? { shape } : {}) },
+        });
       }
+      if (frac) found.scene.setPose(nid, fracToWorld(bounds, content));
     },
 
     setMeta(id, meta) {

package/src/annotations/svgNodes.test.ts

@@ -1,17 +1,15 @@
-import { serializeSvg } from '@weasel-js/svg';
+import { serializeSvg, svgNeeds } 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: [
+    shape: [
       { x: 0.1, y: 0.2 },
       { x: 0.5, y: 0.6 },
     ],
@@ -24,8 +22,8 @@ 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);
+    const cmds = markCommands(m);
+    const nodes = markSvgNodes(m);
     expect(nodes).toHaveLength(cmds.length);
     for (const [i, cmd] of cmds.entries()) {
       if (cmd.kind !== 'path') throw new Error('expected path commands');
@@ -46,32 +44,43 @@ describe('a mark as vector', () => {
   });
 
   it('carries a stale mark′s dash through', () => {
-    const [node] = markSvgNodes(mark('rect'), CONTENT, { stale: true });
+    const [node] = markSvgNodes(mark('rect'), { 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(
+  it("keeps the arrow's marker, so the export draws its head", () => {
+    const nodes = markSvgNodes(mark('arrow'));
+    expect(nodes).toHaveLength(1);
+    const [node] = nodes;
+    if (node?.kind !== 'path') throw new Error('expected a path node');
+    expect(node.stroke?.markerEnd).toBe('arrow');
+    expect(serializeSvg(nodes, { viewBox: { x: 0, y: 0, width: 100, height: 60 } })).toContain(
       '<marker',
     );
   });
 
   it('emits text as text, at the pose, in the mark color', () => {
     const m = mark('text', { title: 'missing edge' });
-    const [node] = markSvgNodes(m, CONTENT);
+    const [node] = markSvgNodes(m);
     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([]);
+    expect(markSvgNodes(mark('text'))).toEqual([]);
+  });
+
+  // Why `composeCaptureSvg` and `<OverviewMarks>` serialize without awaiting
+  // `warmSvg`: a mark exports nothing that loads on demand. A mark gaining a
+  // gradient paint or a script run fails this, and those two then need it.
+  it('needs nothing loaded to serialize, stale or not', () => {
+    const all: AnnotationKind[] = [...KINDS, 'point', 'text'];
+    for (const stale of [false, true]) {
+      const nodes = all.flatMap((k) =>
+        markSvgNodes(mark(k, { title: 'words' }), { stale, color: '#123456' }),
+      );
+      expect(nodes.length).toBeGreaterThan(all.length - 1);
+      expect(svgNeeds(nodes)).toEqual({ fonts: [], paintKinds: [] });
+    }
   });
 });

package/src/annotations/svgNodes.ts

@@ -1,4 +1,4 @@
-import type { DrawCommand, FillStyle, Stroke } from '@weasel-js/core';
+import type { DrawCommand, FillStyle, Stroke, View } from '@weasel-js/core';
 import type { SvgNode, SvgPaint, SvgStroke } from '@weasel-js/svg';
 import { type MarkStyle, markCommands, type PaintableMark } from './paint';
 
@@ -16,9 +16,6 @@ function toSvgPaint(paint: FillStyle | undefined): SvgPaint {
   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),
@@ -28,6 +25,9 @@ function toSvgStroke(stroke: Stroke): SvgStroke {
     ...(stroke.dash ? { dash: [...stroke.dash] } : {}),
     ...(stroke.miterLimit != null ? { miterLimit: stroke.miterLimit } : {}),
     ...(stroke.align ? { align: stroke.align } : {}),
+    ...(stroke.markerStart ? { markerStart: stroke.markerStart } : {}),
+    ...(stroke.markerMid ? { markerMid: stroke.markerMid } : {}),
+    ...(stroke.markerEnd ? { markerEnd: stroke.markerEnd } : {}),
   };
 }
 
@@ -67,8 +67,8 @@ function toSvgNode(cmd: DrawCommand, m: PaintableMark): SvgNode {
  */
 export function markSvgNodes(
   m: PaintableMark,
-  content: { w: number; h: number },
   style: MarkStyle = {},
+  scale?: View['scale'],
 ): SvgNode[] {
-  return markCommands(m, content, style).map((cmd) => toSvgNode(cmd, m));
+  return markCommands(m, style, scale).map((cmd) => toSvgNode(cmd, m));
 }