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

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

@@ -1,5 +1,5 @@
 export interface ParsedArgs {
-    command: 'capture' | 'url' | 'list';
+    command: 'capture' | 'batch' | 'url' | 'list';
     hub?: string;
     config?: string;
     assembly?: string;
@@ -11,15 +11,17 @@ export interface ParsedArgs {
     out?: string;
     width?: number;
     height?: number;
-    scale?: number;
+    dpr?: number;
     timeout?: number;
+    concurrency?: number;
     fullPage: boolean;
+    annotations?: string;
     headed: boolean;
     verbose: boolean;
     help: boolean;
     version: boolean;
     allowUnsettled: boolean;
-    /** `list`'s hub and filter. Empty for the other commands. */
+    /** `list`'s hub and filter, or `batch`'s manifest. Empty for the other commands. */
     positionals: string[];
 }
 /**

package/esm/args.js

@@ -13,9 +13,11 @@ const OPTIONS = {
     track: { type: 'string', multiple: true, default: [] },
     width: { type: 'string' },
     height: { type: 'string' },
-    scale: { type: 'string' },
+    dpr: { type: 'string' },
     timeout: { type: 'string' },
+    concurrency: { 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 },
@@ -24,6 +26,8 @@ const OPTIONS = {
 };
 const EVERY_COMMAND = ['help', 'version'];
 const SUBCOMMAND_FLAGS = {
+    capture: new Set(Object.keys(OPTIONS).filter(f => f !== 'concurrency')),
+    batch: new Set(Object.keys(OPTIONS).filter(f => f !== 'out')),
     url: new Set([
         'hub',
         'config',
@@ -47,6 +51,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) {
@@ -61,31 +72,35 @@ function positive(name, raw) {
  */
 export function parseArgs(argv) {
     const [first, ...afterCommand] = argv;
-    const command = first === 'list' || first === 'url' ? first : 'capture';
+    const command = first === 'list' || first === 'url' || first === 'batch' ? first : 'capture';
     const { values, positionals, tokens } = parseNodeArgs({
         args: command === 'capture' ? argv : afterCommand,
         options: OPTIONS,
-        allowPositionals: command === 'list',
+        allowPositionals: command === 'list' || command === 'batch',
         tokens: true,
     });
-    if (command !== 'capture') {
-        for (const token of tokens) {
-            if (token.kind === 'option' &&
-                !SUBCOMMAND_FLAGS[command].has(token.name)) {
-                throw new Error(`${token.rawName} does not apply to \`jb2capture ${command}\``);
-            }
+    for (const token of tokens) {
+        if (token.kind === 'option' && !SUBCOMMAND_FLAGS[command].has(token.name)) {
+            throw new Error(command === 'capture'
+                ? `${token.rawName} applies only to \`jb2capture batch\``
+                : `${token.rawName} does not apply to \`jb2capture ${command}\``);
         }
     }
-    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, concurrency, ...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),
+        concurrency: positiveInt('concurrency', concurrency),
         positionals,
     };
 }

package/esm/bin.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
 import { parseArgs } from './args.js';
-import { captureJBrowse } from './capture.js';
+import { captureBatch, captureJBrowse } from './capture.js';
 import { resolveAgainstConfig } from './catalog.js';
 import { listHubAssemblies, listHubTracks, trackName } from './hub.js';
+import { readAnnotations, readBatch, 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
 
 USAGE
   jb2capture [flags] --out <file.png>    open a view, wait for it, screenshot it
+  jb2capture batch <json|path|-> [flags] screenshot many views from one browser
   jb2capture url [flags]                 print the URL instead of launching a browser
   jb2capture list [hub] [filter]         list hosted assemblies, or one's trackIds
 
@@ -31,9 +32,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)
@@ -42,6 +47,16 @@ WAITING
 
   Either fails the run rather than writing a frame that is not the picture.
 
+BATCH
+  The manifest is a JSON array with one object per image. Each names its "out"
+  and may set hub, config, assembly, loc, tracks, spec, session, width, height,
+  dpr, fullPage and annotations; the flags above are the defaults for what an
+  object leaves out. Every image gets a page of its own in one shared browser.
+  A failed image is reported and the rest carry on; the exit code is 1 if any
+  failed.
+
+  --concurrency <n>     pages open at once (default 4)
+
 OTHER
   --headed              run with a visible browser window
   --verbose             print browser console output and uncaught errors
@@ -57,28 +72,14 @@ EXAMPLES
   ## find the trackIds first
   jb2capture list hg38 conservation
 
+  ## one image per locus, from one browser
+  jb2capture batch '[{"loc":"BRCA1","out":"brca1.png"},{"loc":"TP53","out":"tp53.png"}]' \\
+    --hub hg38 --track hg38-ncbiRefSeqCurated
+
   ## your own config, two loci side by side
   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,
@@ -91,6 +92,71 @@ function urlOptions(args) {
         instance: args.instance,
     };
 }
+async function runBatch(args) {
+    const [manifest, ...extra] = args.positionals;
+    if (!manifest || extra.length) {
+        throw new Error('`jb2capture batch` takes one manifest: JSON, a path or -');
+    }
+    const defaults = {
+        ...urlOptions(args),
+        width: args.width,
+        height: args.height,
+        dpr: args.dpr,
+        fullPage: args.fullPage,
+        annotations: args.annotations
+            ? readAnnotations(args.annotations)
+            : undefined,
+        timeout: args.timeout,
+        allowUnsettled: args.allowUnsettled,
+        onConsole: args.verbose
+            ? (text) => {
+                console.error(`  [page] ${text}`);
+            }
+            : undefined,
+    };
+    const captures = readBatch(manifest).map(({ spec, session, annotations, ...entry }) => ({
+        ...defaults,
+        // an entry that says what to open replaces the default session whole
+        ...(spec || session ? { spec: undefined, session: undefined } : {}),
+        ...entry,
+        ...(spec
+            ? { spec: typeof spec === 'string' ? readSpec(spec) : spec }
+            : {}),
+        ...(session
+            ? {
+                session: typeof session === 'string'
+                    ? readJson('session', session)
+                    : session,
+            }
+            : {}),
+        ...(annotations
+            ? {
+                annotations: typeof annotations === 'string'
+                    ? readAnnotations(annotations)
+                    : annotations,
+            }
+            : {}),
+    }));
+    const start = performance.now();
+    const results = await captureBatch(captures, {
+        headless: !args.headed,
+        concurrency: args.concurrency,
+        onResult: (result, index) => {
+            const label = `[${index + 1}/${captures.length}] ${result.out} ${(result.ms / 1000).toFixed(1)}s`;
+            if (result.ok) {
+                console.log(`wrote ${label}`);
+            }
+            else {
+                console.error(`FAILED ${label}: ${result.error.message}`);
+            }
+        },
+    });
+    const failed = results.filter(r => !r.ok).length;
+    console.log(`wrote ${results.length - failed}/${results.length} images in ${((performance.now() - start) / 1000).toFixed(1)}s`);
+    if (failed) {
+        process.exitCode = 1;
+    }
+}
 async function runList(positionals) {
     const [hub, filter] = positionals;
     if (!hub) {
@@ -131,6 +197,10 @@ async function main() {
         await runList(args.positionals);
         return;
     }
+    if (args.command === 'batch') {
+        await runBatch(args);
+        return;
+    }
     if (args.command === 'url') {
         console.log(jbrowseUrl(await resolveAgainstConfig(urlOptions(args))));
         return;
@@ -143,8 +213,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;
@@ -43,3 +50,25 @@ export interface CaptureResult extends ReadyReport {
  * browser.
  */
 export declare function captureJBrowse(options?: CaptureOptions): Promise<CaptureResult>;
+export interface BatchOptions extends LaunchOptions {
+    /** Pages open at once. Default 4. */
+    concurrency?: number;
+    /** Called as each capture finishes, in completion order. */
+    onResult?: (result: BatchResult, index: number) => void;
+}
+export type BatchResult = {
+    out?: string;
+    ms: number;
+} & (({
+    ok: true;
+} & CaptureResult) | {
+    ok: false;
+    error: Error;
+});
+/**
+ * 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 declare function captureBatch(captures: CaptureOptions[], { concurrency, onResult, ...launch }?: BatchOptions): Promise<BatchResult[]>;