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

package/src/annotations/Annotations.overlay.test.tsx

@@ -0,0 +1,142 @@
+/**
+ * What jsdom can honestly see of the overlay: which tiles get registered,
+ * where the input boxes land, and that both come back out on unmount.
+ *
+ * **GL is not exercised here.** jsdom's canvas has no WebGL2, so `<Canvas>`'s
+ * paint bails silently and nothing reaches the shared buffer — an assertion
+ * about pixels in this file would be an assertion about the emulation. The
+ * 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 { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import { useTiledSurface } from '../surface/useTiledSurface';
+import { AnnotationTargets } from './AnnotationTargets';
+import { createAnnotationStore } from './store';
+import type { AnnotationsCapability, AnnotationTarget } from './types';
+
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function Harness({ toolId = 'rect' }: { toolId?: string }) {
+  const a = useRef<HTMLDivElement | null>(null);
+  const b = useRef<HTMLDivElement | null>(null);
+  const surface = useTiledSurface({ onFrame: () => {} });
+  const annotations = useRef(createAnnotationStore({ targets: () => [] })).current;
+
+  const capability: AnnotationsCapability = {
+    targets: (): AnnotationTarget[] => [
+      { id: 'pane:a', ref: a, content: { w: 200, h: 100 } },
+      { id: 'pane:b', ref: b, content: { w: 200, h: 100 } },
+    ],
+  };
+
+  return (
+    <SurfaceContext.Provider value={surface}>
+      <SurfaceCanvasContext.Provider value={null}>
+        <div
+          data-testid="stage"
+          ref={(el) => {
+            if (!el) return;
+            // A non-zero container origin, so a rect composed against the
+            // wrong one is visible rather than accidentally right.
+            stubBox(el, 12, 7, 800, 600);
+            surface.containerRef(el);
+          }}
+        >
+          <div
+            data-testid="a"
+            ref={(el) => {
+              a.current = el;
+              if (el) stubBox(el, 40, 20, 200, 100);
+            }}
+          />
+          <div
+            data-testid="b"
+            ref={(el) => {
+              b.current = el;
+              if (el) stubBox(el, 400, 300, 200, 100);
+            }}
+          />
+          <AnnotationTargets
+            capability={capability}
+            state={{}}
+            config={{}}
+            annotations={annotations}
+            activeToolId={toolId}
+          />
+        </div>
+      </SurfaceCanvasContext.Provider>
+    </SurfaceContext.Provider>
+  );
+}
+
+describe('<AnnotationTargets>', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('puts an input box over each target, at the rect the surface measured', () => {
+    const { container } = render(<Harness />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+
+    const boxes = [...container.querySelectorAll<HTMLElement>('.lk-annotate__input')];
+    expect(boxes.map((el) => el.dataset.annotationTarget)).toEqual(['pane:a', 'pane:b']);
+    // The rect, not merely its existence: a box positioned against the wrong
+    // origin takes input for the wrong part of the picture.
+    expect(boxes[0]?.style.getPropertyValue('--lk-anno-x')).toBe('28px');
+    expect(boxes[0]?.style.getPropertyValue('--lk-anno-y')).toBe('13px');
+    expect(boxes[1]?.style.getPropertyValue('--lk-anno-x')).toBe('388px');
+    expect(boxes[1]?.style.getPropertyValue('--lk-anno-h')).toBe('100px');
+  });
+
+  it('lands the boxes in the surface container, not among the instrument DOM', () => {
+    const { container } = render(<Harness />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    const stage = container.querySelector('[data-testid="stage"]');
+    for (const el of container.querySelectorAll('.lk-annotate__input')) {
+      expect(el.parentElement).toBe(stage);
+    }
+  });
+
+  it('takes its tiles back out on unmount', () => {
+    const { container, unmount } = render(<Harness />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(container.querySelectorAll('.lk-annotate__input')).toHaveLength(2);
+    unmount();
+    expect(document.querySelectorAll('.lk-annotate__input')).toHaveLength(0);
+  });
+});

package/src/annotations/AnnotationsContext.ts

@@ -0,0 +1,49 @@
+import { createContext, useCallback, useContext, useRef, useSyncExternalStore } from 'react';
+import type { AnnotationsApi } from './types';
+
+/** Null in a trial whose instrument declares no `annotations`. */
+export const AnnotationsContext = createContext<AnnotationsApi | null>(null);
+
+/** Re-render the caller whenever any of the store's scenes changes.
+ *
+ *  The API is a stable facade over mutable scenes, so nothing about its
+ *  identity says a mark was added — a component reading `query()` without this
+ *  renders one answer and never revises it. */
+function useMarkVersion(api: AnnotationsApi | null): void {
+  const version = useRef(0);
+  useSyncExternalStore(
+    useCallback(
+      (fn: () => void) =>
+        api?.subscribe(() => {
+          version.current += 1;
+          fn();
+        }) ?? (() => {}),
+      [api],
+    ),
+    useCallback(() => version.current, []),
+    () => 0,
+  );
+}
+
+/** The marks on this trial's targets. Reached through a hook rather than the
+ *  chrome context, which carries no instrument state — a sidebar panel listing
+ *  marks pulls it the way `useTrialState()` does. Throws outside a trial whose
+ *  instrument declares the capability. */
+export function useAnnotations(): AnnotationsApi {
+  const api = useContext(AnnotationsContext);
+  useMarkVersion(api);
+  if (!api) {
+    throw new Error(
+      '[labkit] useAnnotations requires an instrument that declares the `annotations` capability',
+    );
+  }
+  return api;
+}
+
+/** The marks on this trial's targets, or null. For chrome that renders in
+ *  every trial and does something else where there are none. */
+export function useAnnotationsOptional(): AnnotationsApi | null {
+  const api = useContext(AnnotationsContext);
+  useMarkVersion(api);
+  return api;
+}

package/src/annotations/ExportMenu.test.tsx

@@ -0,0 +1,86 @@
+/**
+ * The toolbar's export popover. Marks belong to a target, so any export has to
+ * name one — which is why this is a panel and not a bare button.
+ */
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnnotationsContext } from './AnnotationsContext';
+import { ExportMenu } from './ExportMenu';
+import { createAnnotationStore } from './store';
+import type { AnnotationsApi, AnnotationTargetInfo, CaptureOptions } from './types';
+
+const TARGETS: AnnotationTargetInfo[] = [
+  { id: 'flat', content: { w: 200, h: 100 } },
+  { id: 'shaded', content: { w: 200, h: 100 } },
+];
+
+function mount(store: AnnotationsApi | null) {
+  return render(
+    <AnnotationsContext.Provider value={store}>
+      <ExportMenu />
+    </AnnotationsContext.Provider>,
+  );
+}
+
+/** A store whose capture is a spy — the real one needs a browser. */
+function spied(): { store: AnnotationsApi; capture: ReturnType<typeof vi.fn> } {
+  const store = createAnnotationStore({ targets: () => TARGETS });
+  const capture = vi.fn(async (target: string, opts?: CaptureOptions) => ({
+    target,
+    blob: new Blob(['x'], { type: 'image/png' }),
+    format: opts?.format ?? ('png' as const),
+    width: 1,
+    height: 1,
+  }));
+  return { store: { ...store, capture } as AnnotationsApi, capture };
+}
+
+const open = () => fireEvent.click(screen.getByRole('button', { name: /export/i }));
+
+// Downloading clicks an anchor at an object URL, which jsdom answers with
+// "Not implemented: navigation". The real save is asserted in the browser
+// spec; here the claim is only which capture the panel asked for.
+beforeAll(() => {
+  vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {});
+});
+
+describe('<ExportMenu>', () => {
+  it('renders nothing for a trial whose instrument declares no annotations', () => {
+    const { container } = mount(null);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('offers every target, both formats and the scales', () => {
+    mount(spied().store);
+    open();
+    const targets = screen.getByRole('combobox', { name: /target/i }) as HTMLSelectElement;
+    expect([...targets.options].map((o) => o.value)).toEqual(['flat', 'shaded']);
+    expect(screen.getByRole('radio', { name: 'PNG' })).toBeTruthy();
+    expect(screen.getByRole('radio', { name: 'SVG' })).toBeTruthy();
+    expect(screen.getByRole('radio', { name: '4×' })).toBeTruthy();
+  });
+
+  it('captures the target, format and scale the panel is holding', async () => {
+    const { store, capture } = spied();
+    mount(store);
+    open();
+    fireEvent.change(screen.getByRole('combobox', { name: /target/i }), {
+      target: { value: 'shaded' },
+    });
+    fireEvent.click(screen.getByRole('radio', { name: 'SVG' }));
+    fireEvent.click(screen.getByRole('radio', { name: '4×' }));
+    fireEvent.click(screen.getByRole('button', { name: /download/i }));
+    await waitFor(() =>
+      expect(capture).toHaveBeenCalledWith('shaded', { format: 'svg', scale: 4 }),
+    );
+  });
+
+  it('says so when a capture fails rather than doing nothing visible', async () => {
+    const { store, capture } = spied();
+    capture.mockRejectedValueOnce(new Error('the capture canvas is tainted'));
+    mount(store);
+    open();
+    fireEvent.click(screen.getByRole('button', { name: /download/i }));
+    expect(await screen.findByRole('alert')).toHaveTextContent(/tainted/);
+  });
+});

package/src/annotations/ExportMenu.tsx

@@ -0,0 +1,182 @@
+import { ExportIcon } from '@weasel-js/ui';
+import { useId, useState } from 'react';
+import { Callout } from '../passthrough/weasel-ui';
+import { Toolbar } from '../primitives/Toolbar';
+import { useAnnotationsOptional } from './AnnotationsContext';
+import type { CaptureResult } from './types';
+
+const SCALES = [1, 2, 4] as const;
+const FORMATS = [
+  { id: 'png', label: 'PNG' },
+  { id: 'svg', label: 'SVG' },
+] as const;
+
+type Format = (typeof FORMATS)[number]['id'];
+
+function fileName(result: CaptureResult): string {
+  return `${result.target.replace(/[^a-z0-9._-]+/gi, '-')}.${result.format}`;
+}
+
+/** A blob the person asked for, handed to the browser's own save flow. The
+ *  object URL is revoked on the next turn — revoking it synchronously races
+ *  the navigation the click starts. */
+function download(result: CaptureResult): void {
+  const url = URL.createObjectURL(result.blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = fileName(result);
+  a.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+/** PNG goes to the clipboard as an image. SVG goes as text: `image/svg+xml`
+ *  needs Chromium's `web ` prefix and nothing else reads it, while the markup
+ *  is what a person pasting a vector export actually wants. */
+async function copy(result: CaptureResult): Promise<void> {
+  if (result.format === 'svg') {
+    await navigator.clipboard.writeText(await result.blob.text());
+    return;
+  }
+  await navigator.clipboard.write([new ClipboardItem({ 'image/png': result.blob })]);
+}
+
+/**
+ * Export a target's picture with its marks on it.
+ *
+ * A panel rather than a button because a mark belongs to a target: with more
+ * than one pane, "export" on its own does not say what.
+ *
+ * Reads the store through the hook the way `<MarkList>` does — the chrome
+ * context carries no instrument state and is not the route to it.
+ */
+export function ExportMenu() {
+  const marks = useAnnotationsOptional();
+  // The anchor doubles as the portal target lookup: a React Aria popover
+  // portals to `document.body` by default, which is outside the element
+  // labkit paints its theme tokens onto — `--wzl-surface` does not exist
+  // there and the panel renders unthemed.
+  const [anchor, setAnchor] = useState<HTMLSpanElement | null>(null);
+  const [open, setOpen] = useState(false);
+  const [target, setTarget] = useState<string | null>(null);
+  const [format, setFormat] = useState<Format>('png');
+  const [scale, setScale] = useState<number>(2);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const titleId = useId();
+
+  if (!marks) return null;
+  const targets = marks.targets();
+  const chosen = target ?? targets[0]?.id ?? null;
+
+  const run = async (then: (r: CaptureResult) => void | Promise<void>): Promise<void> => {
+    if (!chosen) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await then(await marks.capture(chosen, { format, scale }));
+      setOpen(false);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <span className="lk-export" ref={setAnchor}>
+      <Toolbar.Button
+        iconOnly
+        pressed={open}
+        aria-label="Export"
+        title="Export"
+        onClick={() => setOpen((was) => !was)}
+      >
+        <ExportIcon size={16} />
+      </Toolbar.Button>
+      <Callout
+        triggerRef={{ current: anchor }}
+        isOpen={open}
+        onOpenChange={setOpen}
+        onDismiss={() => setOpen(false)}
+        placement="bottom end"
+        UNSTABLE_portalContainer={anchor?.closest('.lk-root') ?? undefined}
+        aria-labelledby={titleId}
+      >
+        <div className="lk-export__panel">
+          <span className="lk-export__title" id={titleId}>
+            Export
+          </span>
+
+          <label className="lk-export__row">
+            <span>Target</span>
+            {/* Native controls: role, name and keyboard operability for free,
+                and a five-control panel is not the place to rebuild them. */}
+            <select
+              aria-label="Target"
+              value={chosen ?? ''}
+              onChange={(e) => setTarget(e.target.value)}
+            >
+              {targets.map((t) => (
+                <option key={t.id} value={t.id}>
+                  {t.id}
+                </option>
+              ))}
+            </select>
+          </label>
+
+          {/* A <fieldset>/<legend> cannot do this: a legend is outside its
+              fieldset's grid formatting context, so it will not take a grid
+              column and every choice row drops below its own label. */}
+          <div className="lk-export__row">
+            <span>Format</span>
+            <span className="lk-export__choices" role="radiogroup" aria-label="Format">
+              {FORMATS.map((f) => (
+                <label key={f.id}>
+                  <input
+                    type="radio"
+                    name="lk-export-format"
+                    checked={format === f.id}
+                    onChange={() => setFormat(f.id)}
+                  />
+                  {f.label}
+                </label>
+              ))}
+            </span>
+          </div>
+
+          <div className="lk-export__row">
+            <span>Scale</span>
+            <span className="lk-export__choices" role="radiogroup" aria-label="Scale">
+              {SCALES.map((s) => (
+                <label key={s}>
+                  <input
+                    type="radio"
+                    name="lk-export-scale"
+                    checked={scale === s}
+                    onChange={() => setScale(s)}
+                  />
+                  {s}×
+                </label>
+              ))}
+            </span>
+          </div>
+
+          <div className="lk-export__actions">
+            <button type="button" disabled={busy || !chosen} onClick={() => run(download)}>
+              Download
+            </button>
+            <button type="button" disabled={busy || !chosen} onClick={() => run(copy)}>
+              Copy
+            </button>
+          </div>
+
+          {error ? (
+            <p className="lk-export__error" role="alert">
+              {error}
+            </p>
+          ) : null}
+        </div>
+      </Callout>
+    </span>
+  );
+}

package/src/annotations/MarkList.tsx

@@ -0,0 +1,75 @@
+import { useAnnotations } from './AnnotationsContext';
+import type { AnnotationMeaning } from './types';
+
+/** Props for `<MarkList>`. */
+export interface MarkListProps {
+  /** The instrument's vocabulary. Omitted, rows carry no status control —
+   *  a host that declared none owns what a mark means. */
+  meaning?: AnnotationMeaning;
+  /** The live config, for answering staleness. */
+  config: unknown;
+}
+
+/** Every mark on this trial's targets: what it says, and whether it still
+ *  describes the picture under it.
+ *
+ *  Reads the store through the hook, which re-renders on every mutation — so a
+ *  mark drawn on a pane appears here without anything wiring the two. */
+export function MarkList({ meaning, config }: MarkListProps) {
+  const marks = useAnnotations();
+  const all = marks.query();
+  const statuses = meaning?.statuses ?? [];
+
+  if (all.length === 0) {
+    return <div className="lk-mark-list__empty">No marks yet</div>;
+  }
+
+  return (
+    <ul className="lk-mark-list">
+      {all.map((a) => {
+        const stale = marks.isStale(a, config);
+        return (
+          <li className="lk-mark-list__row" key={a.id}>
+            <div className="lk-mark-list__head">
+              <span className="lk-mark-list__kind">{a.kind}</span>
+              <span className="lk-mark-list__target">{a.target}</span>
+              {stale ? <span className="lk-mark-list__stale">stale</span> : null}
+              <button
+                type="button"
+                className="lk-mark-list__drop"
+                aria-label={`Remove ${a.kind} on ${a.target}`}
+                onClick={() => marks.remove(a.id)}
+              >
+                ×
+              </button>
+            </div>
+            <input
+              className="lk-mark-list__title"
+              aria-label={`Title of ${a.kind} on ${a.target}`}
+              value={a.title ?? ''}
+              placeholder="Untitled"
+              onChange={(e) => marks.update(a.id, { title: e.target.value })}
+            />
+            {statuses.length > 0 ? (
+              // A native select: it carries role, name and keyboard operability
+              // for free, and a sidebar row is not the place to rebuild them.
+              <select
+                className="lk-mark-list__status"
+                aria-label={`Status of ${a.kind} on ${a.target}`}
+                value={a.status ?? ''}
+                onChange={(e) => marks.update(a.id, { status: e.target.value })}
+              >
+                <option value="">—</option>
+                {statuses.map((s) => (
+                  <option key={s.id} value={s.id}>
+                    {s.label}
+                  </option>
+                ))}
+              </select>
+            ) : null}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/annotations/capture.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from 'vitest';
+import { capturePlan, composeCaptureSvg } from './capture';
+import { createAnnotationStore } from './store';
+import type { AnnotationTargetInfo, CaptureSource } from './types';
+
+const SVG_BASE = '<svg viewBox="0 0 100 60"><rect width="100" height="60" fill="#f00"/></svg>';
+
+function targets(): AnnotationTargetInfo[] {
+  return [
+    {
+      id: 'flat',
+      content: { w: 100, h: 60 },
+      base: (): CaptureSource => ({ kind: 'svg', markup: SVG_BASE }),
+    },
+    { id: 'bare', content: { w: 100, h: 60 } },
+  ];
+}
+
+describe('a target that can be captured', () => {
+  it('reports every target, in declaration order, base or no base', () => {
+    const store = createAnnotationStore({ targets });
+    expect(store.targets().map((t) => t.id)).toEqual(['flat', 'bare']);
+    expect(store.targets()[1]?.base).toBeUndefined();
+  });
+
+  it('does not call a target base until a capture asks for it', () => {
+    const base = vi.fn((): CaptureSource => ({ kind: 'svg', markup: SVG_BASE }));
+    const store = createAnnotationStore({
+      targets: () => [{ id: 'flat', content: { w: 100, h: 60 }, base }],
+    });
+    store.add({ target: 'flat', kind: 'rect', frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 } });
+    store.query();
+    store.targets();
+    expect(base).not.toHaveBeenCalled();
+  });
+});
+
+describe('which route an export takes', () => {
+  const svg: CaptureSource = { kind: 'svg', markup: SVG_BASE };
+  const image: CaptureSource = { kind: 'image', src: 'data:image/png;base64,AA' };
+
+  // The two rasterizing halves are browser-only and are asserted in
+  // `tests/visual/annotations-capture.spec.ts`. jsdom's canvas has no 2D
+  // context, so a test of them here could not fail for the right reason.
+  it('stays vector for an SVG format, whatever the base is', () => {
+    expect(capturePlan(svg, 'svg')).toBe('svg-document');
+    expect(capturePlan(image, 'svg')).toBe('svg-document');
+    expect(capturePlan(undefined, 'svg')).toBe('svg-document');
+  });
+
+  it('nests an SVG base rather than rasterizing it twice', () => {
+    expect(capturePlan(svg, 'png')).toBe('svg-document');
+  });
+
+  it('stacks rasters for a raster base, or for no base at all', () => {
+    expect(capturePlan(image, 'png')).toBe('raster-stack');
+    expect(capturePlan({ kind: 'canvas', canvas: {} as HTMLCanvasElement }, 'png')).toBe(
+      'raster-stack',
+    );
+    expect(capturePlan(undefined, 'png')).toBe('raster-stack');
+  });
+});
+
+describe('the composed document', () => {
+  const draw = { content: { w: 100, h: 60 }, config: {} };
+
+  function sceneWithMark() {
+    const store = createAnnotationStore({ targets });
+    store.add({ target: 'flat', kind: 'rect', frac: { x: 0.1, y: 0.2, w: 0.3, h: 0.4 } });
+    return store.sceneFor('flat');
+  }
+
+  it('frames the content box, and carries the scale as width and height', () => {
+    const out = composeCaptureSvg({ scene: sceneWithMark(), draw, scale: 4 });
+    expect(out).toContain('viewBox="0 0 100 60"');
+    expect(out).toContain('width="400"');
+    expect(out).toContain('height="240"');
+  });
+
+  it('nests the base and re-frames it onto the content box', () => {
+    const out = composeCaptureSvg({
+      base: { kind: 'svg', markup: SVG_BASE },
+      scene: sceneWithMark(),
+      draw,
+      scale: 2,
+    });
+    // Scale 2, so the outer viewport is 200x120 and the base's own 100x60 is
+    // unambiguously the re-framing rather than a coincidence.
+    expect(out).toContain('fill="#f00"');
+    expect(out).toMatch(/<svg[^>]*x="0"[^>]*y="0"[^>]*width="100"[^>]*height="60"/);
+    expect(out).toContain('#e5484d');
+  });
+
+  it('re-frames a base whose declared size disagrees with its viewBox', () => {
+    const out = composeCaptureSvg({
+      base: { kind: 'svg', markup: '<svg viewBox="0 0 100 60" width="520"><rect/></svg>' },
+      scene: sceneWithMark(),
+      draw,
+      scale: 1,
+    });
+    expect(out).not.toContain('width="520"');
+  });
+
+  it('exports marks on transparency when a target hands over no base', () => {
+    const out = composeCaptureSvg({ scene: sceneWithMark(), draw, scale: 1 });
+    expect(out).toContain('#e5484d');
+    expect(out.match(/<svg/g)).toHaveLength(2);
+  });
+
+  it('embeds a raster base as an image, warning when it is only a reference', () => {
+    const warn = vi.fn();
+    const out = composeCaptureSvg({
+      base: { kind: 'image', src: 'https://example.test/brick.png' },
+      scene: sceneWithMark(),
+      draw,
+      scale: 1,
+      onWarn: warn,
+    });
+    expect(out).toContain('https://example.test/brick.png');
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('not self-contained'));
+  });
+
+  it('refuses markup that is not an SVG document', () => {
+    expect(() =>
+      composeCaptureSvg({
+        base: { kind: 'svg', markup: '<div>not svg</div>' },
+        scene: sceneWithMark(),
+        draw,
+        scale: 1,
+      }),
+    ).toThrow(/not an <svg> document/);
+  });
+});
+
+describe('capturing through the store', () => {
+  it('rejects a target the instrument does not declare', async () => {
+    const store = createAnnotationStore({ targets });
+    await expect(store.capture('nope')).rejects.toThrow(/no annotation target/);
+  });
+});