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

package/esm/capture.js

@@ -1,23 +1,19 @@
 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';
-/**
- * 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
- * tracks asked for become the session gate's expectations unless `trackIds`
- * 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);
+import { PUBLIC_INSTANCE, assertCoherentOptions, jbrowseUrl } from './url.js';
+async function prepareOpen(options) {
+    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 +23,31 @@ export async function openJBrowse(options = {}) {
         ...urlOptions,
         sessionName: urlOptions.sessionName ?? 'Screenshot',
     });
-    const browser = await launchBrowser({ headless, executablePath, args });
+    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);
+    return {
+        url,
+        viewport: { width, height, deviceScaleFactor: dpr },
+        onConsole,
+        timeout,
+        ready: {
+            ...options,
+            assembly: expectedAssembly,
+            trackIds: trackIds ?? (opens ? trackIdsFromSession(opens) : tracks),
+        },
+    };
+}
+async function openPage(browser, { url, viewport, onConsole, timeout, ready, }) {
+    // a window each: a tab behind another stops painting, and a batch has
+    // several pages open
+    const page = await browser.newPage({ type: 'window' });
     try {
-        const page = await browser.newPage();
-        await page.setViewport({ width, height, deviceScaleFactor });
+        await page.setViewport(viewport);
         if (onConsole) {
             page.on('console', msg => {
                 const text = msg.text();
@@ -41,50 +58,155 @@ 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 report = await waitForJBrowseReady(page, {
-            ...options,
-            assembly: opens ? assemblyFromSession(opens) : (assembly ?? hub),
-            trackIds: trackIds ?? (opens ? trackIdsFromSession(opens) : tracks),
+        const response = await page.goto(url, {
+            waitUntil: 'domcontentloaded',
+            timeout,
         });
-        return { browser, page, url, ...report };
+        // 304: a page after the first in a batch comes from the shared cache
+        if (response && !response.ok() && response.status() !== 304) {
+            throw new Error(`${url} answered HTTP ${response.status()}. Check --instance.`);
+        }
+        const report = await waitForJBrowseReady(page, ready);
+        return { page, url, ...report };
     }
     catch (error) {
-        await browser.close().catch(() => { });
+        await page.close().catch(() => { });
         throw error;
     }
 }
 /**
- * Open a JBrowse session, wait for it to render, screenshot it, and close the
- * browser.
+ * 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
+ * tracks asked for become the session gate's expectations unless `trackIds`
+ * names others.
  */
-export async function captureJBrowse(options = {}) {
-    const { out, fullPage = false, ...openOptions } = options;
+export async function openJBrowse(options = {}) {
+    const prepared = await prepareOpen(options);
+    const browser = await launchBrowser(options);
+    try {
+        return { browser, ...(await openPage(browser, prepared)) };
+    }
+    catch (error) {
+        await browser.close().catch(() => { });
+        throw error;
+    }
+}
+function assertCapturable({ out, annotations }) {
+    if (annotations) {
+        assertValidAnnotations(annotations);
+    }
     if (out) {
         assertImagePath(out);
         mkdirSync(dirname(out), { recursive: true });
     }
-    const { browser, page, url, ...opened } = await openJBrowse(openOptions);
+}
+async function shoot(page, opened, { out, fullPage = false, annotations, ...openOptions }) {
+    let report = opened;
+    const overflow = fullPage ? await page.evaluate(sessionOverflowInPage) : 0;
+    const viewport = page.viewport();
+    if (viewport && overflow > 0) {
+        await page.setViewport({
+            ...viewport,
+            height: viewport.height + overflow,
+        });
+        report = await waitForFrame(page, openOptions);
+    }
+    if (annotations?.length) {
+        await drawAnnotations(page, annotations);
+    }
+    const image = await page.screenshot({ path: out });
+    return { image, ...report };
+}
+/**
+ * Open a JBrowse session, wait for it to render, screenshot it, and close the
+ * browser.
+ */
+export async function captureJBrowse(options = {}) {
+    assertCapturable(options);
+    const { browser, page, url, ...opened } = await openJBrowse(options);
     try {
-        let report = opened;
-        const overflow = fullPage ? await page.evaluate(sessionOverflowInPage) : 0;
-        const viewport = page.viewport();
-        if (viewport && overflow > 0) {
-            await page.setViewport({
-                ...viewport,
-                height: viewport.height + overflow,
-            });
-            report = await waitForFrame(page, openOptions);
+        return { url, ...(await shoot(page, opened, options)) };
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
+/**
+ * Screenshot many sessions from one browser, each on a page of its own that is
+ * closed after its screenshot. A failed capture is reported in its result and
+ * the rest carry on; a browser that died is relaunched for the captures left.
+ * Results come back in the order of `captures`.
+ */
+export async function captureBatch(captures, { concurrency = 4, onResult, ...launch } = {}) {
+    for (const capture of captures) {
+        assertCapturable(capture);
+    }
+    const results = [];
+    let browser;
+    // chained, so workers that find no live browser share one launch
+    const liveBrowser = () => {
+        const launched = () => launchBrowser(launch);
+        browser = browser
+            ? browser.then(b => (b.connected ? b : launched()), launched)
+            : launched();
+        return browser;
+    };
+    let next = 0;
+    const worker = async () => {
+        while (next < captures.length) {
+            const index = next++;
+            const capture = captures[index];
+            const start = performance.now();
+            let result;
+            let page;
+            try {
+                const prepared = await prepareOpen(capture);
+                const opened = await openPage(await liveBrowser(), prepared);
+                page = opened.page;
+                const { url } = opened;
+                result = {
+                    ok: true,
+                    out: capture.out,
+                    url,
+                    ...(await shoot(page, opened, capture)),
+                    ms: performance.now() - start,
+                };
+            }
+            catch (error) {
+                result = {
+                    ok: false,
+                    out: capture.out,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    ms: performance.now() - start,
+                };
+            }
+            finally {
+                await page?.close().catch(() => { });
+            }
+            results[index] = result;
+            onResult?.(result, index);
         }
-        const image = await page.screenshot({ path: out });
-        return { url, image, ...report };
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(concurrency, captures.length) }, worker));
     }
     finally {
-        await browser.close();
+        const launched = await browser?.catch(() => undefined);
+        await launched?.close().catch(() => { });
     }
+    return results;
 }

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,
+    };
+}

package/esm/graphAnchor.d.ts

@@ -0,0 +1,47 @@
+import type { AnnotationAnchor } from './annotationOverlay.ts';
+import type { JSHandle, Page } from 'puppeteer';
+export interface ViewportRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface GraphNodeGeometry extends ViewportRect {
+    midX: number;
+    midY: number;
+}
+export interface GraphPane {
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    translateX?: number;
+    translateY?: number;
+    nodePositions?: Record<string, {
+        x: number;
+        y: number;
+    }[]>;
+    graph?: {
+        nodes: {
+            id: string;
+            length?: number;
+            stable?: {
+                rank?: number;
+                refName?: string;
+                start?: number;
+                end?: number;
+            };
+        }[];
+    };
+}
+export declare function locateGraphPaneInPage(viewPath: number[], trackId: string | undefined): {
+    pane: GraphPane;
+    canvas: Element;
+} | undefined;
+export type LocatedGraphPane = NonNullable<ReturnType<typeof locateGraphPaneInPage>>;
+export declare function nodeGeometryInPage(located: LocatedGraphPane | undefined, nodeId: string): GraphNodeGeometry | undefined;
+export declare function locateGraphPane(page: Page, anchor: Pick<AnnotationAnchor, 'view' | 'trackId'>): Promise<JSHandle<LocatedGraphPane | undefined>>;
+export declare function graphNodePoint(page: Page, anchor: AnnotationAnchor): Promise<{
+    x: number;
+    y: number;
+} | undefined>;
+export declare function graphNodeRect(page: Page, anchor: AnnotationAnchor, wantBounds: boolean): Promise<ViewportRect | undefined>;

package/esm/graphAnchor.js

@@ -0,0 +1,120 @@
+// The graph pane an anchor addresses, and the canvas it draws on. The graph is
+// one canvas with no element per node, so the pane is asked where it put one
+// instead, the way a locus anchor asks the LGV. The pane is the addressed view
+// itself when that is a GraphGenomeView, and otherwise a LinearGraphDisplay
+// among the view's tracks, the one `trackId` names or the first: the display
+// itself from plugin 4.0.7, its nested `pane` before that.
+//
+// Puppeteer serializes this into the page, so it closes over nothing.
+export function locateGraphPaneInPage(viewPath, trackId) {
+    let view = window.JBrowseSession;
+    for (const i of viewPath) {
+        view = view?.views?.[i];
+    }
+    if (!view) {
+        return undefined;
+    }
+    const container = `[data-testid="view-container-${CSS.escape(view.id)}"]`;
+    let pane = view;
+    let scope = container;
+    if (view.tracks) {
+        const paneOf = (d) => d.pane ?? (d.type === 'LinearGraphDisplay' ? d : undefined);
+        const track = view.tracks.find(t => t.displays?.some(paneOf) &&
+            (trackId === undefined || t.configuration?.trackId === trackId));
+        const display = track?.displays?.find(paneOf);
+        pane = display ? paneOf(display) : undefined;
+        const id = track?.configuration?.trackId ?? '';
+        scope = `${container} [data-testid="trackRenderingContainer-${CSS.escape(view.id)}-${CSS.escape(id)}"] [data-testid="linear-graph-display"]`;
+    }
+    const canvas = document.querySelector(`${scope} [data-testid="graph-genome-canvas"]`);
+    return pane && canvas ? { pane, canvas } : undefined;
+}
+// Where the located pane drew one GFA segment, in viewport CSS px: its
+// `nodePositions` in graph world units through the transform the renderer
+// draws with. Undefined when the node isn't there, so the caller can fail the
+// spec by name rather than acting on (0,0). Serialized into the page too.
+export function nodeGeometryInPage(located, nodeId) {
+    if (!located) {
+        return undefined;
+    }
+    const { pane, canvas } = located;
+    // nodePositions is keyed by the node's drawn id, which carries the
+    // orientation the cut walked the segment in ('s2037+'), so a spec may name
+    // either that or the bare GFA segment id
+    const positions = pane.nodePositions;
+    const pts = positions?.[nodeId] ??
+        positions?.[`${nodeId}+`] ??
+        positions?.[`${nodeId}-`];
+    if (!pts?.length) {
+        return undefined;
+    }
+    const r = canvas.getBoundingClientRect();
+    const scaleX = pane.scaleX ?? pane.scale ?? 1;
+    const scaleY = pane.scaleY ?? pane.scale ?? 1;
+    const tx = pane.translateX ?? 0;
+    const ty = pane.translateY ?? 0;
+    const screen = pts.map(p => ({ x: p.x * scaleX + tx, y: p.y * scaleY + ty }));
+    const xs = screen.map(p => p.x);
+    const ys = screen.map(p => p.y);
+    const left = Math.min(...xs);
+    const top = Math.min(...ys);
+    // Halfway along the drawn line rather than its middle vertex: an anchored
+    // node is a two-point line, whose "middle" vertex is its left end, where it
+    // meets its neighbour, and the app's hit test there answers the neighbour.
+    const legs = screen
+        .slice(1)
+        .map((p, i) => Math.hypot(p.x - screen[i].x, p.y - screen[i].y));
+    let rest = legs.reduce((sum, leg) => sum + leg, 0) / 2;
+    let mid = screen[0];
+    for (const [i, leg] of legs.entries()) {
+        const from = screen[i];
+        const to = screen[i + 1];
+        if (rest <= leg) {
+            const t = leg > 0 ? rest / leg : 0;
+            mid = { x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t };
+            break;
+        }
+        rest -= leg;
+        mid = to;
+    }
+    return {
+        left: r.left + left,
+        top: r.top + top,
+        width: Math.max(...xs) - left,
+        height: Math.max(...ys) - top,
+        midX: r.left + mid.x,
+        midY: r.top + mid.y,
+    };
+}
+export function locateGraphPane(page, anchor) {
+    const path = Array.isArray(anchor.view) ? anchor.view : [anchor.view ?? 0];
+    return page.evaluateHandle(locateGraphPaneInPage, path, anchor.trackId);
+}
+async function graphNodeGeometry(page, anchor) {
+    const located = await locateGraphPane(page, anchor);
+    try {
+        return await located.evaluate(nodeGeometryInPage, anchor.graphNode ?? '');
+    }
+    finally {
+        await located.dispose();
+    }
+}
+// What a click/hover/ring acts on: a point on the node itself.
+export async function graphNodePoint(page, anchor) {
+    const geom = await graphNodeGeometry(page, anchor);
+    return geom
+        ? { x: geom.midX + (anchor.dx ?? 0), y: geom.midY + (anchor.dy ?? 0) }
+        : undefined;
+}
+// What an annotation resolves to: the drawn bounds for a box, a zero-size rect
+// on the node for anything else (so its centre lands on the node, not in the
+// space a bent node encloses).
+export async function graphNodeRect(page, anchor, wantBounds) {
+    const geom = await graphNodeGeometry(page, anchor);
+    if (!geom) {
+        return undefined;
+    }
+    return wantBounds
+        ? { left: geom.left, top: geom.top, width: geom.width, height: geom.height }
+        : { left: geom.midX, top: geom.midY, width: 0, height: 0 };
+}

package/esm/index.d.ts

@@ -1,4 +1,5 @@
-export { captureJBrowse, openJBrowse } from './capture.ts';
+export { captureBatch, captureJBrowse, openJBrowse } from './capture.ts';
+export { clearAnnotations, drawAnnotations } from './annotations.ts';
 export { delay } from './poll.ts';
 export { waitForFrame, waitForJBrowseReady } from './ready.ts';
 export { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.ts';
@@ -6,8 +7,10 @@ export { jbrowseUrl } from './url.ts';
 export { assemblyFromSession, encodeSessionSpec, sessionSpecQuery, trackIdsFromSession, } from './session.ts';
 export { PENDING_DISPLAYS, displayPainted, displaySettled, waitForAppSettled, waitForSelectorAttributed, } from './waits.ts';
 export { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, launchBrowser, } from './browser.ts';
+export type { Annotation, AnnotationAnchor } from './annotationOverlay.ts';
 export type { LaunchOptions } from './browser.ts';
-export type { CaptureOptions, CaptureResult, OpenOptions, OpenResult, } from './capture.ts';
+export type { BatchOptions, BatchResult, CaptureOptions, CaptureResult, OpenOptions, OpenResult, } from './capture.ts';
+export type { PageOrFrame } from './poll.ts';
 export type { ReadyOptions, ReadyReport } from './ready.ts';
 export type { DisplayState, SessionExpectations } from './sessionGate.ts';
 export type { JBrowseUrlOptions } from './url.ts';

package/esm/index.js

@@ -1,4 +1,5 @@
-export { captureJBrowse, openJBrowse } from './capture.js';
+export { captureBatch, captureJBrowse, openJBrowse } from './capture.js';
+export { clearAnnotations, drawAnnotations } from './annotations.js';
 export { delay } from './poll.js';
 export { waitForFrame, waitForJBrowseReady } from './ready.js';
 export { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.js';