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

package/esm/annotationSpec.d.ts

@@ -0,0 +1,7 @@
+import type { Annotation } from './annotationOverlay.ts';
+/**
+ * Throw for each callout the overlay would draw nothing for, or draw at the
+ * page origin, so a spec fails before a browser launches rather than shipping a
+ * figure with the callout missing.
+ */
+export declare function assertValidAnnotations(annotations: Annotation[]): void;

package/esm/annotationSpec.js

@@ -0,0 +1,70 @@
+import { ANNOTATION_TYPES } from './annotationOverlay.js';
+const ANCHOR_KEYS = new Set(Object.keys({
+    selector: 0,
+    text: 0,
+    graphNode: 0,
+    hLoc: 0,
+    vLoc: 0,
+    view: 0,
+    trackId: 0,
+    loc: 0,
+    fracY: 0,
+    alignX: 0,
+    alignY: 0,
+    dx: 0,
+    dy: 0,
+    fracX: 0,
+}));
+function unknownAnchorKeys(a) {
+    return [a.anchor, a.fromAnchor].flatMap(anchor => Object.keys(anchor ?? {}).filter(k => !ANCHOR_KEYS.has(k)));
+}
+const isNumber = (n) => typeof n === 'number' && Number.isFinite(n);
+function missing(a) {
+    const placed = !!a.anchor || (isNumber(a.x) && isNumber(a.y));
+    switch (a.type) {
+        case 'arrow': {
+            const head = !!a.anchor || isNumber(a.to?.x);
+            const tail = !!a.fromAnchor || isNumber(a.from?.x);
+            return head && tail ? undefined : 'an arrow needs a head and a tail';
+        }
+        case 'box':
+            return !!a.anchor || (placed && isNumber(a.width) && isNumber(a.height))
+                ? undefined
+                : 'a box needs an anchor or x, y, width and height';
+        case 'circle':
+            return placed ? undefined : 'a circle needs an anchor or x and y';
+        case 'text':
+            return a.text && placed
+                ? undefined
+                : 'a text needs text and an anchor or x and y';
+        case 'legend':
+            return a.entries?.length && placed
+                ? undefined
+                : 'a legend needs entries and an anchor or x and y';
+        case 'trapezoid':
+            return a.anchor && a.fromAnchor
+                ? undefined
+                : 'a trapezoid needs both anchor and fromAnchor';
+        default:
+            return `type "${a.type}" is not one of ${ANNOTATION_TYPES.join(', ')}`;
+    }
+}
+/**
+ * Throw for each callout the overlay would draw nothing for, or draw at the
+ * page origin, so a spec fails before a browser launches rather than shipping a
+ * figure with the callout missing.
+ */
+export function assertValidAnnotations(annotations) {
+    const problems = annotations.flatMap((a, i) => {
+        const unknown = a ? unknownAnchorKeys(a) : [];
+        const why = unknown.length > 0
+            ? `anchor key(s) ${unknown.join(', ')} not recognized; the keys are ${[...ANCHOR_KEYS].join(', ')}`
+            : a
+                ? missing(a)
+                : 'a callout must be an object';
+        return why ? [`annotation ${i}: ${why}`] : [];
+    });
+    if (problems.length > 0) {
+        throw new Error(`invalid annotations: ${problems.join('; ')}`);
+    }
+}

package/esm/annotations.d.ts

@@ -0,0 +1,14 @@
+import type { Annotation } from './annotationOverlay.ts';
+import type { Page } from 'puppeteer';
+/** Remove the callout overlay a previous `drawAnnotations` left on the page. */
+export declare function clearAnnotations(page: Page): Promise<void>;
+/**
+ * Draw callouts (arrows, boxes, labels, badges) over the page as one fixed SVG
+ * overlay, so the next screenshot includes them. Each anchor resolves against
+ * the live session — a locus through the view model, a graph node or dotplot
+ * cell through its view's layout, page chrome by selector or text — so nothing
+ * is a measured pixel. Throws when an anchor resolves to nothing or a callout
+ * lands outside the viewport, rather than writing a figure with a callout
+ * parked in the corner or missing.
+ */
+export declare function drawAnnotations(page: Page, annotations: Annotation[]): Promise<void>;

package/esm/annotations.js

@@ -0,0 +1,68 @@
+import { ANNOTATION_OVERLAY_ID, drawAnnotationOverlay, parseAnnotationLocus, } from './annotationOverlay.js';
+import { assertValidAnnotations } from './annotationSpec.js';
+import { dotplotAnchorRect } from './dotplotAnchor.js';
+import { graphNodeRect } from './graphAnchor.js';
+// Attach the parsed region so page context never parses strings, plus the
+// viewport rect of the two anchor kinds that resolve out here rather than in
+// the overlay: a graph node, and a dotplot's pair of axes. Both draw into a
+// single canvas, so there is no element in the page for the overlay to measure
+// and the view's own layout is the only thing that knows where they went.
+//
+// `wantBounds` is the same question for both kinds of anchor: does this callout
+// WRAP the thing it names, or point at it? A force-directed graph node bends, so
+// the centre of its bounding box can sit off the node and everything but a box
+// wants a point ON it (a dotplot block's cell is a rectangle either way). A
+// one-base locus is the same shape of question — the base's own column for a
+// box, the zero-width position between two bases for a pill or an arrow head —
+// which is what parseAnnotationLocus's `wrap` decides.
+async function withRegion(page, anchor, wantBounds) {
+    if (!anchor) {
+        return undefined;
+    }
+    const isDotplot = anchor.hLoc !== undefined || anchor.vLoc !== undefined;
+    return {
+        ...anchor,
+        region: anchor.loc
+            ? parseAnnotationLocus(anchor.loc, wantBounds)
+            : undefined,
+        rect: anchor.graphNode
+            ? await graphNodeRect(page, anchor, wantBounds)
+            : isDotplot
+                ? await dotplotAnchorRect(page, anchor)
+                : undefined,
+    };
+}
+/** Remove the callout overlay a previous `drawAnnotations` left on the page. */
+export async function clearAnnotations(page) {
+    await page.evaluate(id => {
+        document.getElementById(id)?.remove();
+    }, ANNOTATION_OVERLAY_ID);
+}
+/**
+ * Draw callouts (arrows, boxes, labels, badges) over the page as one fixed SVG
+ * overlay, so the next screenshot includes them. Each anchor resolves against
+ * the live session — a locus through the view model, a graph node or dotplot
+ * cell through its view's layout, page chrome by selector or text — so nothing
+ * is a measured pixel. Throws when an anchor resolves to nothing or a callout
+ * lands outside the viewport, rather than writing a figure with a callout
+ * parked in the corner or missing.
+ */
+export async function drawAnnotations(page, annotations) {
+    assertValidAnnotations(annotations);
+    await clearAnnotations(page);
+    const items = await Promise.all(annotations.map(async (a) => ({
+        ...a,
+        // only a box wants the drawn bounds — of a graph node, or of the base a
+        // one-coordinate locus names; a ring/arrow/label wants a point on it, and
+        // an arrow's tail always does
+        anchor: await withRegion(page, a.anchor, a.type === 'box'),
+        fromAnchor: await withRegion(page, a.fromAnchor, false),
+    })));
+    const { unresolved, offFrame } = await page.evaluate(drawAnnotationOverlay, items, ANNOTATION_OVERLAY_ID);
+    if (unresolved.length > 0) {
+        throw new Error(`annotation anchors resolved to nothing: ${unresolved.join(', ')}`);
+    }
+    if (offFrame.length > 0) {
+        throw new Error(`annotations drew outside the capture: ${offFrame.join(', ')}`);
+    }
+}

package/esm/args.d.ts

@@ -11,9 +11,10 @@ export interface ParsedArgs {
     out?: string;
     width?: number;
     height?: number;
-    scale?: number;
+    dpr?: number;
     timeout?: number;
     fullPage: boolean;
+    annotations?: string;
     headed: boolean;
     verbose: boolean;
     help: boolean;

package/esm/args.js

@@ -13,9 +13,10 @@ const OPTIONS = {
     track: { type: 'string', multiple: true, default: [] },
     width: { type: 'string' },
     height: { type: 'string' },
-    scale: { type: 'string' },
+    dpr: { type: 'string' },
     timeout: { type: 'string' },
     fullPage: { type: 'boolean', default: false },
+    annotations: { type: 'string' },
     headed: { type: 'boolean', default: false },
     verbose: { type: 'boolean', default: false },
     help: { type: 'boolean', short: 'h', default: false },
@@ -47,6 +48,13 @@ function finite(name, raw) {
     }
     return n;
 }
+function positiveInt(name, raw) {
+    const n = positive(name, raw);
+    if (n !== undefined && !Number.isInteger(n)) {
+        throw new Error(`--${name} needs a whole number, got "${raw}"`);
+    }
+    return n;
+}
 function positive(name, raw) {
     const n = finite(name, raw);
     if (n !== undefined && n <= 0) {
@@ -76,15 +84,19 @@ export function parseArgs(argv) {
             }
         }
     }
-    const { track, width, height, scale, timeout, ...rest } = values;
+    const fromStdin = ['spec', 'session', 'annotations'].filter(flag => values[flag] === '-');
+    if (fromStdin.length > 1) {
+        throw new Error(`${fromStdin.map(f => `--${f}`).join(' and ')} cannot both read stdin (-)`);
+    }
+    const { track, width, height, dpr, timeout, ...rest } = values;
     return {
         ...rest,
         command,
         // copied, since node hands back the option table's own default array
         tracks: [...track],
-        width: positive('width', width),
-        height: positive('height', height),
-        scale: positive('scale', scale),
+        width: positiveInt('width', width),
+        height: positiveInt('height', height),
+        dpr: positive('dpr', dpr),
         timeout: positive('timeout', timeout),
         positionals,
     };

package/esm/bin.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
 import { parseArgs } from './args.js';
 import { captureJBrowse } from './capture.js';
 import { resolveAgainstConfig } from './catalog.js';
 import { listHubAssemblies, listHubTracks, trackName } from './hub.js';
+import { readAnnotations, readJson, readSpec } from './jsonArgs.js';
 import { PUBLIC_INSTANCE, jbrowseUrl } from './url.js';
 import { version } from './version.js';
 const HELP = `jb2capture — screenshot a live JBrowse 2 view, once it has finished drawing
@@ -31,9 +31,13 @@ THE IMAGE
                         subcommand)
   --width <px>          viewport width (default 1400)
   --height <px>         viewport height (default 900)
-  --scale <n>           device pixel ratio (default 2)
+  --dpr <n>             device pixel ratio (default 2)
   --fullPage            grow the image until every view fits, not just the
                         --height of the viewport
+  --annotations <json|path|->
+                        callouts to draw over the view: a JSON array of arrows,
+                        boxes and labels, each anchored to a locus, a graph
+                        node, a dotplot cell or an element
 
 WAITING
   --timeout <ms>        budget per wait stage (default 60000)
@@ -61,24 +65,6 @@ EXAMPLES
   jb2capture --config https://example.org/config.json --assembly mydata \\
     --loc "chr3:25,325,000-25,361,000 chr10:58,716,500-58,718,500" -o two.png
 `;
-// inline JSON, `-` for stdin, or a path: the forms `jb2export --spec` reads
-function readJson(flag, value) {
-    const text = value === '-'
-        ? readFileSync(0, 'utf8')
-        : value.trimStart().startsWith('{')
-            ? value
-            : readFileSync(value, 'utf8');
-    const parsed = JSON.parse(text);
-    if (typeof parsed !== 'object' || parsed === null) {
-        throw new Error(`--${flag} must be a JSON object`);
-    }
-    return parsed;
-}
-// a bare view object is the one-view spec it would be wrapped in
-function readSpec(value) {
-    const spec = readJson('spec', value);
-    return 'type' in spec && !('views' in spec) ? { views: [spec] } : spec;
-}
 function urlOptions(args) {
     return {
         hub: args.hub,
@@ -143,8 +129,11 @@ async function main() {
         out: args.out,
         width: args.width,
         height: args.height,
-        deviceScaleFactor: args.scale,
+        dpr: args.dpr,
         fullPage: args.fullPage,
+        annotations: args.annotations
+            ? readAnnotations(args.annotations)
+            : undefined,
         headless: !args.headed,
         timeout: args.timeout,
         allowUnsettled: args.allowUnsettled,

package/esm/capture.d.ts

@@ -1,3 +1,4 @@
+import type { Annotation } from './annotationOverlay.ts';
 import type { LaunchOptions } from './browser.ts';
 import type { ReadyOptions, ReadyReport } from './ready.ts';
 import type { JBrowseUrlOptions } from './url.ts';
@@ -6,8 +7,8 @@ export interface OpenOptions extends JBrowseUrlOptions, ReadyOptions, LaunchOpti
     width?: number;
     height?: number;
     /** Device pixel ratio. Default 2, the density a figure usually wants. */
-    deviceScaleFactor?: number;
-    /** Called with each page console message that is not known GPU noise, and each uncaught page error. */
+    dpr?: number;
+    /** Called with each page console message that is not known GPU noise, each uncaught page error, and each failed or HTTP 4xx/5xx request. */
     onConsole?: (text: string) => void;
 }
 export interface OpenResult extends ReadyReport {
@@ -33,6 +34,12 @@ export interface CaptureOptions extends OpenOptions {
      * far the session runs past it, and the frame is waited for again.
      */
     fullPage?: boolean;
+    /**
+     * Callouts drawn over the settled view before the screenshot, in the shape
+     * the JBrowse docs figures use: arrows, boxes, labels and badges, each
+     * anchored to a locus, a graph node, a dotplot cell or an element.
+     */
+    annotations?: Annotation[];
 }
 export interface CaptureResult extends ReadyReport {
     url: string;

package/esm/capture.js

@@ -1,14 +1,16 @@
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { assertValidAnnotations } from './annotationSpec.js';
+import { drawAnnotations } from './annotations.js';
 import { isBrowserConsoleNoise, launchBrowser } from './browser.js';
-import { resolveAgainstConfig } from './catalog.js';
+import { canonicalSessionAssembly, resolveAgainstConfig } from './catalog.js';
 import { assertImagePath } from './imagePath.js';
 import { assertSupportedInstance } from './instanceVersion.js';
 import { DEFAULT_TIMEOUT } from './poll.js';
 import { waitForFrame, waitForJBrowseReady } from './ready.js';
 import { assemblyFromSession, savedSnapshot, trackIdsFromSession, } from './session.js';
 import { sessionOverflowInPage } from './sessionOverflow.js';
-import { PUBLIC_INSTANCE, assertSessionStandsAlone, jbrowseUrl } from './url.js';
+import { PUBLIC_INSTANCE, assertCoherentOptions, jbrowseUrl } from './url.js';
 /**
  * Launch a browser, open a JBrowse session, and wait until it has rendered.
  * The caller owns the returned browser and must close it. The assembly and
@@ -16,8 +18,8 @@ import { PUBLIC_INSTANCE, assertSessionStandsAlone, jbrowseUrl } from './url.js'
  * names others.
  */
 export async function openJBrowse(options = {}) {
-    const { width = 1400, height = 900, deviceScaleFactor = 2, headless, executablePath, args, onConsole, timeout = DEFAULT_TIMEOUT, trackIds, ...given } = options;
-    assertSessionStandsAlone(given);
+    const { width = 1400, height = 900, dpr = 2, headless, executablePath, args, onConsole, timeout = DEFAULT_TIMEOUT, trackIds, ...given } = options;
+    assertCoherentOptions(given);
     const [urlOptions] = await Promise.all([
         resolveAgainstConfig(given),
         assertSupportedInstance(given.instance ?? PUBLIC_INSTANCE),
@@ -27,10 +29,17 @@ export async function openJBrowse(options = {}) {
         ...urlOptions,
         sessionName: urlOptions.sessionName ?? 'Screenshot',
     });
+    const { spec, session, assembly, hub, tracks } = urlOptions;
+    const opens = spec ?? (session && savedSnapshot(session));
+    const sessionAssembly = opens && assemblyFromSession(opens);
+    const expectedAssembly = opens
+        ? sessionAssembly &&
+            (await canonicalSessionAssembly(urlOptions, sessionAssembly))
+        : (assembly ?? hub);
     const browser = await launchBrowser({ headless, executablePath, args });
     try {
         const page = await browser.newPage();
-        await page.setViewport({ width, height, deviceScaleFactor });
+        await page.setViewport({ width, height, deviceScaleFactor: dpr });
         if (onConsole) {
             page.on('console', msg => {
                 const text = msg.text();
@@ -41,15 +50,30 @@ export async function openJBrowse(options = {}) {
             page.on('pageerror', error => {
                 onConsole(`uncaught ${error instanceof Error ? error.stack : error}`);
             });
+            page.on('requestfailed', request => {
+                const reason = request.failure()?.errorText;
+                if (reason !== 'net::ERR_ABORTED') {
+                    onConsole(`request failed: ${request.url()} (${reason})`);
+                }
+            });
+            page.on('response', response => {
+                if (response.status() >= 400) {
+                    onConsole(`HTTP ${response.status()}: ${response.url()}`);
+                }
+            });
         }
         // an app streaming track data may never reach networkidle; the session
         // gate is the signal that it is up
-        await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
-        const { spec, session, assembly, hub, tracks } = urlOptions;
-        const opens = spec ?? (session && savedSnapshot(session));
+        const response = await page.goto(url, {
+            waitUntil: 'domcontentloaded',
+            timeout,
+        });
+        if (response && !response.ok()) {
+            throw new Error(`${url} answered HTTP ${response.status()}. Check --instance.`);
+        }
         const report = await waitForJBrowseReady(page, {
             ...options,
-            assembly: opens ? assemblyFromSession(opens) : (assembly ?? hub),
+            assembly: expectedAssembly,
             trackIds: trackIds ?? (opens ? trackIdsFromSession(opens) : tracks),
         });
         return { browser, page, url, ...report };
@@ -64,7 +88,10 @@ export async function openJBrowse(options = {}) {
  * browser.
  */
 export async function captureJBrowse(options = {}) {
-    const { out, fullPage = false, ...openOptions } = options;
+    const { out, fullPage = false, annotations, ...openOptions } = options;
+    if (annotations) {
+        assertValidAnnotations(annotations);
+    }
     if (out) {
         assertImagePath(out);
         mkdirSync(dirname(out), { recursive: true });
@@ -81,10 +108,13 @@ export async function captureJBrowse(options = {}) {
             });
             report = await waitForFrame(page, openOptions);
         }
+        if (annotations?.length) {
+            await drawAnnotations(page, annotations);
+        }
         const image = await page.screenshot({ path: out });
         return { url, image, ...report };
     }
     finally {
-        await browser.close();
+        await browser.close().catch(() => { });
     }
 }

package/esm/catalog.d.ts

@@ -10,10 +10,6 @@ export interface Catalog {
     assembly?: CatalogAssembly;
     tracks?: Track[];
 }
-/**
- * The canonical name of the assembly `input` names by name or alias, ignoring
- * case: the name the app's census publishes.
- */
 export declare function resolveAssemblyName(catalog: Catalog, input: string): string;
 /**
  * The trackId `input` names: an exact trackId, then the id with the assembly
@@ -25,8 +21,17 @@ export declare function resolveTrackId(tracks: Track[], input: string, assemblyN
 /**
  * The options with the assembly and tracks checked against the config and
  * spelled the way it spells them, so a typo fails before a browser launches.
- * A config this cannot fetch passes through for the app to judge, and so does
- * a spec or saved session, which may declare tracks no config lists.
+ * A `--config` this cannot fetch passes through for the app to judge, and so
+ * does a spec or saved session, which may declare tracks no config lists. A
+ * hosted `hub` that fails to fetch throws, since genomes.jbrowse.org either has
+ * the assembly or the name is wrong.
  */
 export declare function resolveAgainstConfig(options: JBrowseUrlOptions): Promise<JBrowseUrlOptions>;
+/**
+ * The assembly a spec or saved session names, spelled the way the config does,
+ * since the app's census publishes the config's name and a spec may use an
+ * alias. A name the config does not list stays as given: a spec can declare
+ * its own assemblies.
+ */
+export declare function canonicalSessionAssembly(options: JBrowseUrlOptions, name: string): Promise<string>;
 export {};

package/esm/catalog.js

@@ -5,12 +5,16 @@ const assembliesOf = (catalog) => catalog.assemblies ?? (catalog.assembly ? [cat
  * The canonical name of the assembly `input` names by name or alias, ignoring
  * case: the name the app's census publishes.
  */
-export function resolveAssemblyName(catalog, input) {
-    const assemblies = assembliesOf(catalog);
+const findAssembly = (catalog, input) => {
     const target = input.toLowerCase();
-    const found = assemblies.find(a => [a.name, ...(a.aliases ?? [])].some(n => n.toLowerCase() === target));
+    return assembliesOf(catalog).find(a => [a.name, ...(a.aliases ?? [])].some(n => n.toLowerCase() === target));
+};
+export function resolveAssemblyName(catalog, input) {
+    const found = findAssembly(catalog, input);
     if (!found) {
-        const names = assemblies.map(a => a.name).join(', ');
+        const names = assembliesOf(catalog)
+            .map(a => a.name)
+            .join(', ');
         throw new Error(`assembly "${input}" is not in the config, which has ${names || 'none'}`);
     }
     return found.name;
@@ -52,24 +56,33 @@ export function resolveTrackId(tracks, input, assemblyName) {
         : '';
     throw new Error(`--track "${input}" is not in the config${hint}`);
 }
+async function fetchCatalog({ hub, config, instance, }) {
+    const url = config
+        ? new URL(config, instanceUrl(instance)).href
+        : hub
+            ? hubUrl(hub)
+            : undefined;
+    if (!url) {
+        return undefined;
+    }
+    const fetched = fetchJson(url, config ? 'config' : `hub "${hub}"`);
+    return (await (config ? fetched.catch(() => undefined) : fetched));
+}
 /**
  * The options with the assembly and tracks checked against the config and
  * spelled the way it spells them, so a typo fails before a browser launches.
- * A config this cannot fetch passes through for the app to judge, and so does
- * a spec or saved session, which may declare tracks no config lists.
+ * A `--config` this cannot fetch passes through for the app to judge, and so
+ * does a spec or saved session, which may declare tracks no config lists. A
+ * hosted `hub` that fails to fetch throws, since genomes.jbrowse.org either has
+ * the assembly or the name is wrong.
  */
 export async function resolveAgainstConfig(options) {
-    const { hub, config, assembly, tracks, spec, session, instance } = options;
+    const { hub, assembly, tracks, spec, session } = options;
     const wanted = assembly ?? hub;
-    const url = config
-        ? new URL(config, instanceUrl(instance)).href
-        : hub
-            ? hubUrl(hub)
-            : undefined;
-    if (spec || session || !url || (!wanted && !tracks?.length)) {
+    if (spec || session || (!wanted && !tracks?.length)) {
         return options;
     }
-    const catalog = (await fetchJson(url, 'config').catch(() => undefined));
+    const catalog = await fetchCatalog(options);
     if (!catalog) {
         return options;
     }
@@ -82,3 +95,13 @@ export async function resolveAgainstConfig(options) {
         tracks: tracks?.map(t => resolveTrackId(catalog.tracks ?? [], t, assemblyName ?? '')),
     };
 }
+/**
+ * The assembly a spec or saved session names, spelled the way the config does,
+ * since the app's census publishes the config's name and a spec may use an
+ * alias. A name the config does not list stays as given: a spec can declare
+ * its own assemblies.
+ */
+export async function canonicalSessionAssembly(options, name) {
+    const catalog = await fetchCatalog(options);
+    return (catalog && findAssembly(catalog, name)?.name) ?? name;
+}

package/esm/dotplotAnchor.d.ts

@@ -0,0 +1,4 @@
+import type { AnnotationAnchor } from './annotationOverlay.ts';
+import type { ViewportRect } from './graphAnchor.ts';
+import type { Page } from 'puppeteer';
+export declare function dotplotAnchorRect(page: Page, anchor: AnnotationAnchor): Promise<ViewportRect | undefined>;

package/esm/dotplotAnchor.js

@@ -0,0 +1,104 @@
+// Where a DotplotView drew a pair of loci, in viewport CSS px.
+//
+// The LGV sibling of this is `getHighlightCoords`, which the overlay calls from
+// page context (`annotationOverlay.ts`'s modelRect). A dotplot cannot be reached
+// that way for the same reason a graph cannot: the plot is one canvas with no
+// element per feature, so a callout on a block would be a raw viewport
+// coordinate — correct only for the width, the assembly order and the zoom it
+// was measured against, with nothing to say when one of those moved. This is the
+// `graphAnchor.ts` treatment: resolve it out here, against the live model.
+//
+// Two axes, so an anchor names up to two loci. `hLoc` is the horizontal
+// (`hview`) axis and `vLoc` the vertical one; either may be omitted, and the
+// omitted axis spans the whole plot — which is what a callout on "this
+// chromosome, whatever it pairs with" wants. Naming neither is not a dotplot
+// anchor at all, and `annotations.ts` never routes one here.
+//
+// The vertical axis is INVERTED against the layout: a dotplot's origin is the
+// bottom-left, so a base's screen y is `viewHeight - alongPx`, the same flip the
+// model's own `pxToBp` round trip makes (`DotplotView/model.ts`, the rubberband
+// region). Reading the layout offset straight through as y puts every callout on
+// the wrong half of the plot, mirrored about the middle — which looks like a
+// plausible position rather than like a bug.
+//
+// Returns undefined when the view, an axis, the canvas or a refName isn't there,
+// so the caller fails the spec by name rather than parking a callout at (0,0).
+export async function dotplotAnchorRect(page, anchor) {
+    const path = Array.isArray(anchor.view) ? anchor.view : [anchor.view ?? 0];
+    return page.evaluate((viewPath, h, v) => {
+        let view = window
+            .JBrowseSession;
+        for (const i of viewPath) {
+            view = view?.views?.[i];
+        }
+        const hview = view?.hview;
+        const vview = view?.vview;
+        if (!view || !hview || !vview) {
+            return undefined;
+        }
+        // The canvas IS the plot area — it is styled to viewWidth/viewHeight, i.e.
+        // the frame less the two axis borders — so its own rect is the box the
+        // layout offsets below are measured in, and the borders need no arithmetic
+        // here. The testid carries a `_done` suffix once the view settles, hence
+        // the prefix match. Scoped to the view container when there is one, so a
+        // page with two dotplots anchors against the one the spec named.
+        const canvas = document.querySelector(`[data-testid="view-container-${CSS.escape(view.id)}"] [data-testid^="dotplot_webgl_canvas"]`) ?? document.querySelector('[data-testid^="dotplot_webgl_canvas"]');
+        if (!canvas) {
+            return undefined;
+        }
+        const r = canvas.getBoundingClientRect();
+        // A locus as screen px along one axis, low first. A bare refName takes the
+        // whole displayed region of that name; a reversed axis puts `end` left of
+        // `start`, so neither this nor its caller can assume an order.
+        function span(axis, locus) {
+            const whole = axis.displayedRegions.find(reg => reg.refName === locus.refName);
+            const start = locus.start ?? whole?.start;
+            const end = locus.end ?? whole?.end;
+            if (start === undefined || end === undefined) {
+                return undefined;
+            }
+            const a = axis.bpToPx({ refName: locus.refName, coord: start });
+            const b = axis.bpToPx({ refName: locus.refName, coord: end });
+            return a === undefined || b === undefined
+                ? undefined
+                : {
+                    lo: Math.min(a, b) - axis.offsetPx,
+                    hi: Math.max(a, b) - axis.offsetPx,
+                };
+        }
+        const hs = h ? span(hview, h) : { lo: 0, hi: r.width };
+        const vs = v ? span(vview, v) : { lo: 0, hi: r.height };
+        if (!hs || !vs) {
+            return undefined;
+        }
+        return {
+            left: r.left + hs.lo,
+            width: hs.hi - hs.lo,
+            // the flip: an axis's HIGH coordinate is the plot's TOP edge
+            top: r.top + r.height - vs.hi,
+            height: vs.hi - vs.lo,
+        };
+    }, path, anchor.hLoc ? parseAxisLocus(anchor.hLoc) : null, anchor.vLoc ? parseAxisLocus(anchor.vLoc) : null);
+}
+// `4A`, `4A:1-5,000,000` or `4A:2,500,000`. Deliberately not
+// `parseAnnotationLocus`, which requires the coordinates: on a dotplot the
+// common case is a whole chromosome, and spelling that as `4A:1-830000000`
+// would put an assembly's chromosome lengths into a spec, where they would be
+// wrong the next time the assembly moved.
+function parseAxisLocus(locus) {
+    const cleaned = locus.replaceAll(/[\s,]/g, '');
+    const idx = cleaned.lastIndexOf(':');
+    if (idx === -1) {
+        return { refName: cleaned };
+    }
+    const match = /^(\d+)(?:\.\.|-)?(\d+)?$/.exec(cleaned.slice(idx + 1));
+    if (!match) {
+        throw new Error(`dotplot anchor loc "${locus}" is not <refName>[:<start>[-<end>]]`);
+    }
+    const start = Number(match[1]) - 1;
+    return {
+        refName: cleaned.slice(0, idx),
+        start,
+        end: match[2] ? Number(match[2]) : start,
+    };
+}