@jbrowse/capture 5.0.0-beta.11 → 5.0.0-beta.13

package/esm/annotationOverlay.js

@@ -0,0 +1,766 @@
+// The callout overlay behind `jb2capture --annotations`, the website's figure
+// generator and the desktop selenium harness
+// (`products/jbrowse-desktop/test/annotations.ts`). Puppeteer injects
+// `drawAnnotationOverlay` into page context through `annotations.ts`, selenium
+// through `executeScript`, so a callout drawn on a desktop figure, a web figure
+// and a reader's own capture is the same shape, color and geometry.
+//
+// Everything below the types is deliberately import-free: the function is
+// serialized to source and evaluated in the page, so anything it closes over
+// out here would be undefined in there.
+// A callout drawn over the captured page (SVG overlay) before the screenshot,
+// to reproduce the red arrows / boxes / text labels that hand-made teaching
+// figures use. Coordinates are viewport CSS px.
+//
+// Prefer `anchor` over raw x/y in every case: an anchored callout resolves its
+// geometry at capture time, a hand-tuned coordinate goes stale silently.
+// `dx`/`dy` nudge the anchored position.
+export const ANNOTATION_TYPES = [
+    'arrow',
+    'box',
+    'text',
+    'circle',
+    'legend',
+    'trapezoid',
+];
+export const ANNOTATION_OVERLAY_ID = '__screenshot_annotation_overlay';
+// A locus authored on an anchor, pre-parsed out here in node so the
+// page-context code stays a pure lookup. 1-based inclusive in, interbase out,
+// matching core's parseLocString (which needs an assembly-aware isValidRefName
+// callback we don't have out here — the refName is instead resolved through the
+// assembly's aliases inside the view's own getHighlightCoords).
+//
+// Splits on the LAST colon, so a refName may contain colons as long as
+// coordinates follow it.
+export function parseAnnotationLocus(locus, 
+// What a SINGLE coordinate means, which depends on the callout drawn from it.
+// An arrow head or a text pill points AT the position, and the zero-width
+// interval between two bases is the honest answer for that — it is what the
+// callout centres on. A box has to wrap it, and a box built on that same
+// zero-width region is centred on the boundary rather than around the base:
+// the column ends up in one half of the frame with the stroke drawn over it,
+// which is what "the boxes cover up the variant they are trying to show"
+// looked like at one base per ~6 css px. `wrap` asks for the base's own
+// column instead. (`locusAnchor.ts`'s click parser always wants the base, for
+// the neighbouring reason: a click cannot land on an edge.)
+wrap = false) {
+    const cleaned = locus.replaceAll(/[\s,]/g, '');
+    const idx = cleaned.lastIndexOf(':');
+    const refName = cleaned.slice(0, idx);
+    const coords = cleaned.slice(idx + 1);
+    const match = /^(\d+)(?:\.\.|-)?(\d+)?$/.exec(coords);
+    if (idx === -1 || !match) {
+        throw new Error(`annotation anchor loc "${locus}" is not <refName>:<start>[-<end>]`);
+    }
+    const start = Number(match[1]) - 1;
+    const end = match[2] ? Number(match[2]) : wrap ? start + 1 : start;
+    return { refName, start, end };
+}
+// Draw the annotations as a fixed SVG overlay covering the viewport so the
+// callouts composite into the screenshot, reproducing the red arrows / boxes /
+// text labels of hand-made teaching figures without an external image editor.
+//
+// Runs in PAGE CONTEXT (serialized to source by both harnesses), so it takes no
+// imports and returns plain data: the anchors that resolved to nothing, and the
+// items that resolved but drew outside the capture. The caller turns either into
+// a thrown error rather than leaving a callout parked at the origin or shipping
+// a figure the callout is missing from.
+export function drawAnnotationOverlay(items, overlayId) {
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    svg.id = overlayId;
+    svg.setAttribute('style', 'position:fixed;inset:0;width:100vw;height:100vh;z-index:2147483647;pointer-events:none');
+    // Model anchoring. The app already knows where a locus is painted, so ask
+    // it rather than re-deriving the layout from measured pixels: the track's
+    // rendering container is the element the blocks draw into, and
+    // getHighlightCoords maps a region into that same space (aliases
+    // resolved, scroll subtracted).
+    function viewAt(path) {
+        let view = window
+            .JBrowseSession;
+        for (const i of Array.isArray(path) ? path : [path ?? 0]) {
+            view = view?.views?.[i];
+        }
+        return view;
+    }
+    // The element a view's own DOM sits in: app-core's ViewContainer around a
+    // session view, or the LinearGenomeView's own box, which is all a row of a
+    // synteny stack has.
+    const viewContainerSelector = (view) => ['view-container', 'linear-genome-view']
+        .map(t => `[data-testid="${t}-${CSS.escape(view.id)}"]`)
+        .join(', ');
+    function modelRect(anchor) {
+        const view = viewAt(anchor.view);
+        if (!view) {
+            return undefined;
+        }
+        const el = anchor.trackId
+            ? document.querySelector(`[data-testid="trackRenderingContainer-${CSS.escape(view.id)}-${CSS.escape(anchor.trackId)}"]`)
+            : document
+                .querySelector(viewContainerSelector(view))
+                ?.querySelector('[data-testid="tracksContainer"]');
+        if (!el) {
+            return undefined;
+        }
+        const r = el.getBoundingClientRect();
+        // no fracY anchors the whole track band (what a box wants); a fracY
+        // collapses it to one horizontal line through the track (what an arrow
+        // head or a text baseline wants)
+        const band = anchor.fracY === undefined
+            ? { top: r.top, height: r.height }
+            : { top: r.top + anchor.fracY * r.height, height: 0 };
+        if (!anchor.region) {
+            return { left: r.left, width: r.width, ...band };
+        }
+        // the view's own assembly, so getHighlightCoords resolves the locus's
+        // refName through it: without a name it cannot, and a 'chr1' authored
+        // against an assembly whose canonical refName is '1' resolves to nothing
+        const coords = view.getHighlightCoords?.({
+            ...anchor.region,
+            assemblyName: view.assemblyNames?.[0],
+        });
+        if (!coords) {
+            return undefined;
+        }
+        return {
+            left: r.left + coords.left,
+            // getHighlightCoords floors width at 3px so a zoomed-out band stays
+            // visible; a point locus wants a true zero so the callout centers on it
+            width: anchor.region.end > anchor.region.start ? coords.width : 0,
+            ...band,
+        };
+    }
+    // Resolve an anchor to a live element: a CSS selector, or the
+    // smallest-area element whose visible text matches (so a callout can point
+    // at a menu item / button without a testid).
+    function domRect(anchor) {
+        let scope = document.body;
+        if (anchor.view !== undefined) {
+            const view = viewAt(anchor.view);
+            scope = view ? document.querySelector(viewContainerSelector(view)) : null;
+        }
+        if (!scope) {
+            return undefined;
+        }
+        if (anchor.selector) {
+            return scope.querySelector(anchor.selector)?.getBoundingClientRect();
+        }
+        if (anchor.text) {
+            const want = anchor.text.trim().toLowerCase();
+            let best;
+            let bestArea = Number.POSITIVE_INFINITY;
+            for (const el of scope.querySelectorAll('*')) {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                const txt = (el.textContent !== null ? el.textContent : '')
+                    .trim()
+                    .toLowerCase();
+                const matches = txt === want || (el.childElementCount === 0 && txt.includes(want));
+                // getBoundingClientRect forces layout, so only measure the elements
+                // that actually matched — this scan walks the whole document, and on
+                // a page like the 1104-row TCGA stack measuring every node instead
+                // costs thousands of synchronous layouts
+                if (matches) {
+                    const rect = el.getBoundingClientRect();
+                    const area = rect.width * rect.height;
+                    if (rect.width > 0 && rect.height > 0 && area < bestArea) {
+                        best = rect;
+                        bestArea = area;
+                    }
+                }
+            }
+            return best;
+        }
+        return undefined;
+    }
+    // a selector/text anchor is always a DOM lookup, so the two kinds can't
+    // be silently mixed into an anchor that resolves through neither
+    const isModel = (anchor) => anchor.selector === undefined &&
+        anchor.text === undefined &&
+        (anchor.trackId !== undefined ||
+            anchor.loc !== undefined ||
+            anchor.view !== undefined);
+    const misses = [];
+    function anchorRect(anchor) {
+        if (!anchor) {
+            return undefined;
+        }
+        // a graph-node or dotplot anchor arrives already resolved by the caller —
+        // both are one canvas with nothing per feature to measure in here — and an
+        // unresolved one carries no rect, so it falls through to the miss below
+        const preResolved = anchor.graphNode !== undefined ||
+            anchor.hLoc !== undefined ||
+            anchor.vLoc !== undefined;
+        const rect = preResolved
+            ? anchor.rect
+            : isModel(anchor)
+                ? modelRect(anchor)
+                : domRect(anchor);
+        if (!rect) {
+            misses.push(JSON.stringify(anchor));
+            return undefined;
+        }
+        // built field by field, not spread: domRect hands back a live DOMRect,
+        // whose left/top/width/height are prototype getters and so survive
+        // neither a spread nor Object.assign
+        return {
+            left: rect.left + (anchor.dx ?? 0),
+            top: rect.top + (anchor.dy ?? 0),
+            width: rect.width,
+            height: rect.height,
+        };
+    }
+    // Which point of a resolved rect an anchor names. Both ends of an arrow read
+    // it, so a tail can sit at an element's edge the same way a head can. It used
+    // to be inlined for the head only, and a tail carrying an `alignX` was
+    // silently the rect's centre instead: tcga/mutations_cdh1_histology asked for
+    // a short vertical arrow at a track's left edge + 400 and drew a diagonal
+    // across the whole panel, because a track's rect is the full view width and
+    // half of that is what the tail was off by.
+    function unionRect(a, b) {
+        const left = Math.min(a.left, b.left);
+        const top = Math.min(a.top, b.top);
+        return {
+            left,
+            top,
+            width: Math.max(a.left + a.width, b.left + b.width) - left,
+            height: Math.max(a.top + a.height, b.top + b.height) - top,
+        };
+    }
+    function anchorPoint(rect, anchor) {
+        const alignX = anchor?.alignX ?? 'center';
+        const alignY = anchor?.alignY ?? 'center';
+        return {
+            x: alignX === 'left'
+                ? rect.left
+                : alignX === 'right'
+                    ? rect.left + rect.width
+                    : rect.left + rect.width / 2,
+            y: alignY === 'top'
+                ? rect.top
+                : alignY === 'bottom'
+                    ? rect.top + rect.height
+                    : rect.top + rect.height / 2,
+        };
+    }
+    // Apply anchoring: fill in x/y (the anchor's point on the element) and, for
+    // box/ring shapes, width/height (element bounds + padding), then nudge by
+    // dx/dy.
+    const resolved = items.map(a => {
+        const dx = a.dx ?? 0;
+        const dy = a.dy ?? 0;
+        const from = a.fromAnchor ? anchorRect(a.fromAnchor) : undefined;
+        const tail = from ? anchorPoint(from, a.fromAnchor) : a.from;
+        const anchored = anchorRect(a.anchor);
+        const r = a.type === 'box' && from && anchored
+            ? unionRect(from, anchored)
+            : anchored;
+        if (!r) {
+            return {
+                ...a,
+                from: tail,
+                x: (a.x ?? 0) + dx,
+                y: (a.y ?? 0) + dy,
+                target: undefined,
+                fromRect: from,
+                toRect: undefined,
+            };
+        }
+        const pad = a.pad ?? 6;
+        // a numbered badge stays a fixed small disc; a hollow ring grows to wrap
+        // the anchored element
+        const ringRadius = Math.max(r.width, r.height) / 2 + pad;
+        const { x: px, y: py } = anchorPoint(r, a.anchor);
+        // A box's pad goes outward where there is room and inward where there is
+        // not. An element flush against the window edge — a docked drawer, a panel
+        // pinned to the right — has no outside on that side, so a stroke drawn
+        // there is off frame: the track-settings figure kept exactly one of its four
+        // edges, a red line hovering in the page margin with nothing to read it
+        // against. Clamped to the stroke's own half-width so the whole line lands.
+        const inset = (a.strokeWidth ?? 5) / 2;
+        const boxLeft = Math.max(inset, r.left - pad + dx);
+        const boxTop = Math.max(inset, r.top - pad + dy);
+        const boxRight = Math.min(window.innerWidth - inset, r.left + r.width + pad + dx);
+        const boxBottom = Math.min(window.innerHeight - inset, r.top + r.height + pad + dy);
+        return {
+            ...a,
+            from: tail,
+            x: a.type === 'box' ? boxLeft : px + dx,
+            y: a.type === 'box' ? boxTop : py + dy,
+            // the anchored point BEFORE the annotation's own dx/dy, which for a
+            // `leader` pill is the difference between where the label sits and what it
+            // names — the arrow needs both
+            target: { x: px, y: py },
+            width: a.width ?? boxRight - boxLeft,
+            height: a.height ?? boxBottom - boxTop,
+            radius: a.radius ?? (a.text ? 16 : ringRadius),
+            // A trapezoid is the one shape that needs both anchors as RECTS rather
+            // than as points: its two horizontal edges are the two elements' facing
+            // edges, so the widths are the geometry and not a decoration on it.
+            fromRect: from,
+            toRect: r,
+        };
+    });
+    // arrowhead length in marker units (path spans x:0..ARROW_LEN); the line
+    // is shortened by this much (scaled by strokeWidth, since markerUnits
+    // defaults to strokeWidth) so it ends at the arrowhead's base
+    const ARROW_LEN = 8;
+    const defs = document.createElementNS(NS, 'defs');
+    svg.append(defs);
+    // One marker per distinct arrow color. A single shared marker recolored
+    // per arrow would paint every head in whichever color was drawn last.
+    const markerIds = new Map();
+    function arrowMarker(color) {
+        const existing = markerIds.get(color);
+        if (existing) {
+            return existing;
+        }
+        const id = `arrowhead-${markerIds.size}`;
+        const marker = document.createElementNS(NS, 'marker');
+        marker.setAttribute('id', id);
+        marker.setAttribute('markerWidth', '10');
+        marker.setAttribute('markerHeight', '10');
+        // anchor the marker at its BASE (refX=0) so the line stops at the base
+        // and the triangle extends forward to the target, covering the line end
+        // — this avoids the butt-capped line poking past the sharp tip as a "nub"
+        marker.setAttribute('refX', '0');
+        marker.setAttribute('refY', '3');
+        marker.setAttribute('orient', 'auto');
+        const arrowPath = document.createElementNS(NS, 'path');
+        arrowPath.setAttribute('d', `M0,0 L${ARROW_LEN},3 L0,6 Z`);
+        arrowPath.setAttribute('fill', color);
+        marker.append(arrowPath);
+        defs.append(marker);
+        markerIds.set(color, id);
+        return id;
+    }
+    // One line with a head on it, shared by the `arrow` annotation and by the
+    // arrow a `leader` pill draws for itself, so the two cannot end up different
+    // marks in the same figure.
+    function drawArrowLine(from, to, color, strokeWidth) {
+        // pull the line endpoint back to the arrowhead's base so the triangle
+        // (placed base-first at the endpoint) extends forward to the true target;
+        // the line end is then hidden under the filled head
+        const ddx = to.x - from.x;
+        const ddy = to.y - from.y;
+        const dist = Math.hypot(ddx, ddy) || 1;
+        const headLen = ARROW_LEN * strokeWidth;
+        const line = document.createElementNS(NS, 'line');
+        line.setAttribute('x1', String(from.x));
+        line.setAttribute('y1', String(from.y));
+        line.setAttribute('x2', String(to.x - (ddx / dist) * headLen));
+        line.setAttribute('y2', String(to.y - (ddy / dist) * headLen));
+        line.setAttribute('stroke', color);
+        // the arrowhead marker uses markerUnits=strokeWidth, so a thinner line also
+        // shrinks the head proportionally
+        line.setAttribute('stroke-width', String(strokeWidth));
+        line.setAttribute('marker-end', `url(#${arrowMarker(color)})`);
+        return line;
+    }
+    // How much air a leader leaves at each end: clear of the pill's border so the
+    // tail is not drawn on it, and short of the target so the head names a point
+    // without covering it.
+    const LEADER_TAIL_GAP = 5;
+    const LEADER_HEAD_GAP = 14;
+    // The arrow a `leader` pill draws back to what it names. The tail is the point
+    // where the target's direction leaves the MEASURED pill, so it is the pill's
+    // own edge at any label length and at any angle; nothing here is a written
+    // offset. Undefined when the pill covers the target, which the caller reports
+    // rather than drawing a backwards arrow.
+    function leaderArrow(pill, target, color, strokeWidth) {
+        const midX = pill.left + pill.width / 2;
+        const midY = pill.top + pill.height / 2;
+        const dx = target.x - midX;
+        const dy = target.y - midY;
+        const dist = Math.hypot(dx, dy);
+        if (dist === 0) {
+            return undefined;
+        }
+        // the pill boundary along that direction: whichever of the two half-extents
+        // the ray reaches first
+        const edge = Math.min(Math.abs(dx) > 0 ? pill.width / 2 / Math.abs(dx) : Infinity, Math.abs(dy) > 0 ? pill.height / 2 / Math.abs(dy) : Infinity);
+        const start = edge * dist + LEADER_TAIL_GAP;
+        const end = dist - LEADER_HEAD_GAP;
+        if (!(end > start)) {
+            return undefined;
+        }
+        const at = (d) => ({
+            x: midX + (dx / dist) * d,
+            y: midY + (dy / dist) * d,
+        });
+        return drawArrowLine(at(start), at(end), color, strokeWidth);
+    }
+    // append the overlay now (before drawing) so text getBBox() resolves for
+    // the optional background pill below
+    document.body.append(svg);
+    // Text pills paint last, over every arrow and box, whatever order the spec
+    // listed them in. An arrow that names a pill has to start inside it: the
+    // pill's width is only known once the text is measured in the page, so a
+    // spec can place the tail near the pill but never exactly at its edge, and
+    // the leftover line drawn across the white callout reads as a mistake.
+    // Sorting here rather than asking every spec to list its pills last, which
+    // is a rule nothing would check.
+    const isPill = (t) => t === 'text' || t === 'legend';
+    const drawOrder = [
+        ...resolved.filter(a => !isPill(a.type)),
+        ...resolved.filter(a => isPill(a.type)),
+    ];
+    // An anchor that resolves and THEN draws outside the capture is the other
+    // half of the miss above, and the half nothing caught: the callout is correct,
+    // the spec is correct, and the figure ships without it. Measured from what was
+    // actually drawn rather than from the intended geometry, because a pill's own
+    // size is only known once its text is measured in the page.
+    //
+    // Reported only when the item lands ENTIRELY outside. A partial clip is left
+    // alone deliberately — a box already clamps its pad inward at the frame edge,
+    // so the shapes that reach the edge do so on purpose, and a threshold on
+    // "mostly visible" would fire on those without a measurement to set it from.
+    const offFrame = [];
+    // jsdom, where this file's unit tests run, measures every element as a zero
+    // rect; taken at face value that calls every callout off-frame. A zero-sized
+    // overlay root is how "no layout here" reads from inside page context.
+    const canMeasure = svg.getBoundingClientRect().width > 0;
+    function reportIfOffFrame(a, from) {
+        const drawn = [...svg.children].slice(from);
+        if (!canMeasure || drawn.length === 0) {
+            return;
+        }
+        let left = Infinity;
+        let top = Infinity;
+        let right = -Infinity;
+        let bottom = -Infinity;
+        for (const el of drawn) {
+            const r = el.getBoundingClientRect();
+            left = Math.min(left, r.left);
+            top = Math.min(top, r.top);
+            right = Math.max(right, r.right);
+            bottom = Math.max(bottom, r.bottom);
+        }
+        // Does the drawn box INTERSECT the viewport — not does the intersection
+        // have area. A perfectly vertical arrow (both ends on one x, which two
+        // anchors sharing a locus give you) has a zero-width box, and measured as
+        // an area it has none wherever it sits: an arrow in the middle of the frame
+        // reported as invisible and failed its whole figure.
+        //
+        // A pill is the exception to leaving partial clips alone: nothing clamps
+        // it, so any part past the edge is cut text.
+        const inside = isPill(a.type)
+            ? left >= -1 &&
+                right <= window.innerWidth + 1 &&
+                top >= -1 &&
+                bottom <= window.innerHeight + 1
+            : right >= 0 &&
+                left <= window.innerWidth &&
+                bottom >= 0 &&
+                top <= window.innerHeight;
+        if (inside) {
+            return;
+        }
+        offFrame.push(JSON.stringify({
+            type: a.type,
+            text: a.text,
+            anchor: a.anchor,
+            drawn: { left, top, right, bottom },
+            viewport: { width: window.innerWidth, height: window.innerHeight },
+        }));
+    }
+    for (const a of drawOrder) {
+        const drawnFrom = svg.childElementCount;
+        const color = a.color ?? '#e3242b';
+        const cx = a.x;
+        const cy = a.y;
+        if (a.type === 'arrow' && a.from) {
+            // anchored arrow: head points at the resolved element center
+            svg.append(drawArrowLine(a.from, {
+                x: a.anchor ? cx : (a.to?.x ?? 0),
+                y: a.anchor ? cy : (a.to?.y ?? 0),
+            }, color, a.strokeWidth ?? 4));
+        }
+        else if (a.type === 'trapezoid' && a.fromRect && a.toRect) {
+            // The lineage wedge: `fromAnchor` is the span the zoom came FROM,
+            // `anchor` the panel it opened into, and the two horizontal edges are
+            // those two elements' own facing edges. Which pair of edges face each
+            // other is read off the rects rather than declared, so the same
+            // annotation works whichever way round the composition stacks its parts.
+            const A = a.fromRect;
+            const B = a.toRect;
+            const span = (r, anchor) => {
+                const [f0, f1] = anchor?.fracX ?? [0, 1];
+                return [r.left + r.width * f0, r.left + r.width * f1];
+            };
+            const [aLeft, aRight] = span(A, a.fromAnchor);
+            const [bLeft, bRight] = span(B, a.anchor);
+            const aAbove = A.top + A.height / 2 < B.top + B.height / 2;
+            const aY = aAbove ? A.top + A.height : A.top;
+            const bY = aAbove ? B.top : B.top + B.height;
+            const poly = document.createElementNS(NS, 'polygon');
+            poly.setAttribute('points', `${aLeft},${aY} ${aRight},${aY} ${bRight},${bY} ${bLeft},${bY}`);
+            poly.setAttribute('fill', color);
+            poly.setAttribute('fill-opacity', String(a.fillOpacity ?? 0.14));
+            poly.setAttribute('stroke', 'none');
+            svg.append(poly);
+            // Only the SLANTED sides are stroked. The other two are the panels' own
+            // edges, and a line drawn along one of them reads as a border the figure
+            // grew rather than as part of the wedge.
+            for (const [x1, x2] of [
+                [aLeft, bLeft],
+                [aRight, bRight],
+            ]) {
+                const side = document.createElementNS(NS, 'line');
+                side.setAttribute('x1', String(x1));
+                side.setAttribute('y1', String(aY));
+                side.setAttribute('x2', String(x2));
+                side.setAttribute('y2', String(bY));
+                side.setAttribute('stroke', color);
+                side.setAttribute('stroke-width', String(a.strokeWidth ?? 3));
+                svg.append(side);
+            }
+        }
+        else if (a.type === 'trapezoid') {
+            // A trapezoid with only one end is not a shape. Reported rather than
+            // skipped, because the caller turns misses into a thrown error and a
+            // silently-undrawn lineage wedge is exactly the kind of thing that gets
+            // committed.
+            misses.push(JSON.stringify({
+                trapezoid: 'needs both anchor and fromAnchor to resolve',
+                anchor: a.anchor,
+                fromAnchor: a.fromAnchor,
+            }));
+        }
+        else if (a.type === 'box') {
+            const rect = document.createElementNS(NS, 'rect');
+            rect.setAttribute('x', String(cx));
+            rect.setAttribute('y', String(cy));
+            rect.setAttribute('width', String(a.width ?? 0));
+            rect.setAttribute('height', String(a.height ?? 0));
+            rect.setAttribute('rx', '4');
+            // a positive fillOpacity tints the box with a translucent wash of its
+            // own colour (a "light green/orange" highlight); otherwise hollow
+            rect.setAttribute('fill', a.fillOpacity ? color : 'none');
+            if (a.fillOpacity) {
+                rect.setAttribute('fill-opacity', String(a.fillOpacity));
+            }
+            rect.setAttribute('stroke', color);
+            rect.setAttribute('stroke-width', String(a.strokeWidth ?? 5));
+            svg.append(rect);
+        }
+        else if (a.type === 'circle') {
+            const radius = a.radius ?? 16;
+            const circle = document.createElementNS(NS, 'circle');
+            circle.setAttribute('cx', String(cx));
+            circle.setAttribute('cy', String(cy));
+            circle.setAttribute('r', String(radius));
+            circle.setAttribute('stroke', color);
+            circle.setAttribute('stroke-width', String(a.strokeWidth ?? 5));
+            // filled badge when it carries a label, hollow ring otherwise
+            circle.setAttribute('fill', a.text ? color : 'none');
+            svg.append(circle);
+            if (a.text) {
+                const text = document.createElementNS(NS, 'text');
+                text.setAttribute('x', String(cx));
+                text.setAttribute('y', String(cy));
+                text.setAttribute('fill', a.textColor ?? '#fff');
+                text.setAttribute('text-anchor', 'middle');
+                text.setAttribute('dominant-baseline', 'central');
+                text.setAttribute('font-family', 'system-ui, sans-serif');
+                text.setAttribute('font-size', String(a.fontSize ?? 18));
+                text.setAttribute('font-weight', '700');
+                text.textContent = a.text;
+                svg.append(text);
+            }
+        }
+        else if (a.type === 'legend' && a.entries?.length) {
+            // A color key: swatch + label per row, in one white pill styled like the
+            // text callout so the two read as the same annotation vocabulary. The
+            // pill's width comes from the measured labels, so nothing here is a
+            // hand-tuned box that goes stale when an entry is renamed.
+            const fontFamily = 'system-ui, sans-serif';
+            const fontSize = Math.max(a.fontSize ?? 20, 13);
+            const swatch = fontSize;
+            const gap = Math.round(fontSize * 0.5);
+            const rowHeight = Math.round(fontSize * 1.5);
+            const padX = 12;
+            const padY = 10;
+            const group = document.createElementNS(NS, 'g');
+            svg.append(group);
+            const labels = document.createElementNS(NS, 'text');
+            labels.setAttribute('fill', '#000');
+            labels.setAttribute('font-family', fontFamily);
+            labels.setAttribute('font-size', String(fontSize));
+            labels.setAttribute('font-weight', '600');
+            labels.setAttribute('dominant-baseline', 'central');
+            group.append(labels);
+            for (const [i, entry] of a.entries.entries()) {
+                const tspan = document.createElementNS(NS, 'tspan');
+                tspan.setAttribute('x', '0');
+                tspan.setAttribute('y', String(i * rowHeight + rowHeight / 2));
+                tspan.textContent = entry.label;
+                labels.append(tspan);
+            }
+            const labelWidth = labels.getBBox().width;
+            // right-align the whole pill on x when asked, which is what a key placed
+            // against the frame's right edge needs: its width is only known here
+            const width = padX * 2 + swatch + gap + labelWidth;
+            const height = padY * 2 + a.entries.length * rowHeight;
+            const left = a.textAlign === 'end' ? cx - width : cx;
+            const top = cy;
+            const rect = document.createElementNS(NS, 'rect');
+            rect.setAttribute('x', String(left));
+            rect.setAttribute('y', String(top));
+            rect.setAttribute('width', String(width));
+            rect.setAttribute('height', String(height));
+            rect.setAttribute('rx', '6');
+            rect.setAttribute('fill', '#fff');
+            rect.setAttribute('stroke', color);
+            rect.setAttribute('stroke-width', '3');
+            group.prepend(rect);
+            for (const [i, entry] of a.entries.entries()) {
+                const sw = document.createElementNS(NS, 'rect');
+                sw.setAttribute('x', String(left + padX));
+                sw.setAttribute('y', String(top + padY + i * rowHeight + (rowHeight - swatch) / 2));
+                sw.setAttribute('width', String(swatch));
+                sw.setAttribute('height', String(swatch));
+                sw.setAttribute('rx', '3');
+                sw.setAttribute('fill', entry.color);
+                sw.setAttribute('stroke', '#0006');
+                sw.setAttribute('stroke-width', '1');
+                group.append(sw);
+            }
+            labels.setAttribute('transform', `translate(${left + padX + swatch + gap},${top + padY})`);
+            // the labels were appended before the swatches so getBBox measured them
+            // in isolation; move them back on top so nothing overlaps a swatch
+            group.append(labels);
+        }
+        else if (a.type === 'text' && a.text) {
+            // Callout style: white pill, red border, black text, larger default
+            // font, with word-wrapping once a line exceeds maxWidth. `background`
+            // and `textColor` override the first and third; see their doc comments
+            // for when that is worth doing.
+            const fontFamily = 'system-ui, sans-serif';
+            const fontWeight = '600';
+            const fontSize = Math.max(a.fontSize ?? 22, 13);
+            const maxWidth = a.maxWidth ?? 420;
+            const measure = (s) => {
+                const t = document.createElementNS(NS, 'text');
+                t.setAttribute('font-family', fontFamily);
+                t.setAttribute('font-size', String(fontSize));
+                t.setAttribute('font-weight', fontWeight);
+                t.textContent = s;
+                svg.append(t);
+                const w = t.getBBox().width;
+                t.remove();
+                return w;
+            };
+            // A newline in the text is a hard break, so a callout can author a
+            // list; each resulting paragraph then word-wraps on its own within
+            // maxWidth. (Splitting the whole string on /\s+/ instead silently
+            // flattened an authored list into one run-on paragraph.) An empty
+            // paragraph — from a blank line — becomes a '' entry, drawn below as
+            // a gap rather than a tspan.
+            const lines = [];
+            for (const paragraph of a.text.split('\n')) {
+                const words = paragraph.trim();
+                if (words === '') {
+                    lines.push('');
+                }
+                else {
+                    let cur = '';
+                    for (const word of words.split(/\s+/)) {
+                        const test = cur ? `${cur} ${word}` : word;
+                        if (cur && measure(test) > maxWidth) {
+                            lines.push(cur);
+                            cur = word;
+                        }
+                        else {
+                            cur = test;
+                        }
+                    }
+                    lines.push(cur);
+                }
+            }
+            const lineHeight = fontSize * 1.25;
+            const text = document.createElementNS(NS, 'text');
+            text.setAttribute('x', String(cx));
+            text.setAttribute('y', String(cy));
+            text.setAttribute('fill', a.textColor ?? '#000');
+            text.setAttribute('font-family', fontFamily);
+            text.setAttribute('font-size', String(fontSize));
+            text.setAttribute('font-weight', fontWeight);
+            text.setAttribute('text-anchor', a.textAlign === 'end' ? 'end' : 'start');
+            // An empty tspan gets no layout, so a blank line can't be drawn as
+            // one: carry its half-line gap into the next real line's dy instead.
+            let gap = 0;
+            let isFirst = true;
+            for (const ln of lines) {
+                if (ln === '') {
+                    gap += lineHeight * 0.5;
+                }
+                else {
+                    const tspan = document.createElementNS(NS, 'tspan');
+                    tspan.setAttribute('x', String(cx));
+                    tspan.setAttribute('dy', isFirst ? '0' : String(lineHeight + gap));
+                    tspan.textContent = ln;
+                    text.append(tspan);
+                    gap = 0;
+                    isFirst = false;
+                }
+            }
+            svg.append(text);
+            const bbox = text.getBBox();
+            const padX = 10;
+            const padY = 7;
+            const width = bbox.width + padX * 2;
+            const height = bbox.height + padY * 2;
+            let left = bbox.x - padX;
+            let top = bbox.y - padY;
+            // A leader pill is placed by its PILL rather than by its text baseline:
+            // the facing edge lands on (cx, cy) and the other side of it follows from
+            // whatever the label measured. That is what lets `dx` mean the same gap
+            // for every callout in a figure, and it is the same measurement the arrow
+            // below leaves from — so the two cannot part company.
+            //
+            // Moved by a transform rather than by rewriting every tspan's x: getBBox
+            // reports the element's own user space, so the numbers above stay the ones
+            // that were measured.
+            if (a.leader && a.target) {
+                const wantLeft = a.target.x > cx ? cx - width : cx;
+                const wantTop = cy - height / 2;
+                text.setAttribute('transform', `translate(${wantLeft - left},${wantTop - top})`);
+                left = wantLeft;
+                top = wantTop;
+            }
+            const rect = document.createElementNS(NS, 'rect');
+            rect.setAttribute('x', String(left));
+            rect.setAttribute('y', String(top));
+            rect.setAttribute('width', String(width));
+            rect.setAttribute('height', String(height));
+            rect.setAttribute('rx', '6');
+            rect.setAttribute('fill', a.background ?? '#fff');
+            rect.setAttribute('stroke', a.color ?? '#e3242b');
+            rect.setAttribute('stroke-width', '3');
+            text.before(rect);
+            if (a.leader) {
+                // Both failures are silent otherwise — the pill draws, the arrow does
+                // not, and only a committed PNG says so.
+                const line = a.target
+                    ? leaderArrow({ left, top, width, height }, a.target, color, a.strokeWidth ?? 4)
+                    : undefined;
+                if (line) {
+                    // under its own pill, so a label that ends up closer than planned
+                    // reads as a short arrow rather than as a line drawn over white
+                    rect.before(line);
+                }
+                else {
+                    misses.push(JSON.stringify({
+                        leader: a.target
+                            ? 'the label sits on what it names — raise dx'
+                            : 'a leader needs an anchor to point back at',
+                        text: a.text,
+                        anchor: a.anchor,
+                    }));
+                }
+            }
+        }
+        reportIfOffFrame(a, drawnFrom);
+    }
+    return { unresolved: misses, offFrame };
+}