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

package/esm/jsonArgs.d.ts

@@ -0,0 +1,23 @@
+import type { Annotation } from './annotationOverlay.ts';
+export declare function readJson(flag: string, value: string): object;
+export declare function readAnnotations(value: string): Annotation[];
+export declare function readSpec(value: string): object;
+export interface BatchEntry {
+    out: string;
+    hub?: string;
+    config?: string;
+    assembly?: string;
+    loc?: string;
+    tracks?: string[];
+    /** A session spec inline, or a path to one. */
+    spec?: object | string;
+    /** A session saved with File → Export session inline, or a path to one. */
+    session?: object | string;
+    width?: number;
+    height?: number;
+    dpr?: number;
+    fullPage?: boolean;
+    /** Callouts inline, or a path to them. */
+    annotations?: Annotation[] | string;
+}
+export declare function readBatch(value: string): BatchEntry[];

package/esm/jsonArgs.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+// inline JSON, `-` for stdin, or a path
+function parseJson(flag, value) {
+    try {
+        const inline = /^\s*[[{]/.test(value);
+        return JSON.parse(value === '-'
+            ? readFileSync(0, 'utf8')
+            : inline
+                ? value
+                : readFileSync(value, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${flag.includes(' ') ? flag : `--${flag}`}: ${error instanceof Error ? error.message : error}`, { cause: error });
+    }
+}
+export function readJson(flag, value) {
+    const parsed = parseJson(flag, value);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`--${flag} must be a JSON object`);
+    }
+    return parsed;
+}
+export function readAnnotations(value) {
+    const parsed = parseJson('annotations', value);
+    if (!Array.isArray(parsed)) {
+        throw new Error('--annotations must be a JSON array of callouts');
+    }
+    return parsed;
+}
+// a bare view object is the one-view spec it would be wrapped in
+export function readSpec(value) {
+    const spec = readJson('spec', value);
+    return 'type' in spec && !('views' in spec) ? { views: [spec] } : spec;
+}
+export function readBatch(value) {
+    const parsed = parseJson('batch manifest', value);
+    if (!Array.isArray(parsed)) {
+        throw new Error('the batch manifest must be a JSON array of captures');
+    }
+    for (const [i, entry] of parsed.entries()) {
+        if (typeof entry?.out !== 'string') {
+            throw new Error(`batch capture ${i} has no "out" image path`);
+        }
+    }
+    return parsed;
+}

package/esm/poll.d.ts

@@ -1,3 +1,6 @@
+import type { Frame, Page } from 'puppeteer';
+/** A page, or a frame inside one such as an embedded JBrowse's iframe. */
+export type PageOrFrame = Page | Frame;
 /** The budget each stage of the ready chain gets unless told otherwise. */
 export declare const DEFAULT_TIMEOUT = 60000;
 export declare const delay: (ms: number) => Promise<void>;
@@ -12,3 +15,9 @@ export declare function holdTrue(read: () => Promise<boolean>, { holdMs, timeout
     timeout: number;
     pollMs: number;
 }): Promise<boolean>;
+/**
+ * Await a page query, answering `fallback` when it failed for a reason a later
+ * poll can outlive, such as a navigation destroying the execution context. A
+ * closed or crashed page throws, since no poll will recover it.
+ */
+export declare function queryWhileOpen<T, F>(target: PageOrFrame, query: Promise<T>, fallback: F): Promise<T | F>;

package/esm/poll.js

@@ -28,3 +28,26 @@ export async function holdTrue(read, { holdMs, timeout, pollMs, }) {
     }
     return false;
 }
+function isGone(target) {
+    return 'page' in target
+        ? target.detached || isGone(target.page())
+        : target.isClosed() || !target.browser().connected;
+}
+const PAGE_GONE = /crashed|Target closed|Session closed|Connection closed/i;
+/**
+ * Await a page query, answering `fallback` when it failed for a reason a later
+ * poll can outlive, such as a navigation destroying the execution context. A
+ * closed or crashed page throws, since no poll will recover it.
+ */
+export async function queryWhileOpen(target, query, fallback) {
+    try {
+        return await query;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (PAGE_GONE.test(message) || isGone(target)) {
+            throw new Error(`the page closed or crashed before it finished rendering (${message})`, { cause: error });
+        }
+        return fallback;
+    }
+}

package/esm/ready.d.ts

@@ -1,5 +1,5 @@
+import type { PageOrFrame } from './poll.ts';
 import type { DisplayState, SessionExpectations } from './sessionGate.ts';
-import type { Page } from 'puppeteer';
 export interface ReadyOptions extends SessionExpectations {
     /** Budget for each wait stage. */
     timeout?: number;
@@ -19,11 +19,11 @@ export interface ReadyReport {
 }
 /**
  * Wait until the session holds the assembly and tracks asked for, the app has
- * held itself ready, and every display has painted.
+ * held itself ready, every display has painted, and no error is on screen.
  */
-export declare function waitForJBrowseReady(page: Page, options?: ReadyOptions): Promise<ReadyReport>;
+export declare function waitForJBrowseReady(page: PageOrFrame, options?: ReadyOptions): Promise<ReadyReport>;
 /**
  * `waitForJBrowseReady` without the session gate, for a frame that changed
  * while the session did not, such as after a viewport resize.
  */
-export declare function waitForFrame(page: Page, { timeout, allowUnsettled, }?: Omit<ReadyOptions, keyof SessionExpectations>): Promise<ReadyReport>;
+export declare function waitForFrame(page: PageOrFrame, { timeout, allowUnsettled, }?: Omit<ReadyOptions, keyof SessionExpectations>): Promise<ReadyReport>;

package/esm/ready.js

@@ -1,9 +1,9 @@
 import { DEFAULT_TIMEOUT } from './poll.js';
-import { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.js';
+import { describeDisplays, displayCensusInPage, errorsShownInPage, waitForSession, } from './sessionGate.js';
 import { appSettledBlocker } from './waits.js';
 /**
  * Wait until the session holds the assembly and tracks asked for, the app has
- * held itself ready, and every display has painted.
+ * held itself ready, every display has painted, and no error is on screen.
  */
 export async function waitForJBrowseReady(page, options = {}) {
     await waitForSession(page, options);
@@ -33,6 +33,10 @@ export async function waitForFrame(page, { timeout = DEFAULT_TIMEOUT, allowUnset
     if (canceled.length > 0) {
         unsettled.push(`display(s) canceled, which lasts until Retry: ${describeDisplays(canceled)}`);
     }
+    const errors = await page.evaluate(errorsShownInPage);
+    if (errors.length > 0) {
+        unsettled.push(`error(s) on screen: ${errors.join('; ')}`);
+    }
     if (!allowUnsettled && unsettled.length > 0) {
         const stillLoading = pending.some(d => d.phase === undefined || d.phase === 'loading');
         const advice = timedOut || stillLoading

package/esm/sessionGate.d.ts

@@ -1,4 +1,4 @@
-import type { Page } from 'puppeteer';
+import type { PageOrFrame } from './poll.ts';
 export interface SessionExpectations {
     /** Assembly that must be open on some view. */
     assembly?: string;
@@ -8,7 +8,7 @@ export interface SessionExpectations {
      */
     trackIds?: string[];
     /** The fewest open views that count. Default 1; 0 accepts none. */
-    views?: number;
+    minViews?: number;
 }
 export interface SessionCensus {
     views: number;
@@ -30,7 +30,7 @@ export declare function readSessionInPage(): {
  * Throws at once with the app's message if it could not load, and on timeout
  * with what the census held instead.
  */
-export declare function waitForSession(page: Page, { assembly, trackIds, views, timeout, }?: SessionExpectations & {
+export declare function waitForSession(page: PageOrFrame, { assembly, trackIds, minViews, timeout, }?: SessionExpectations & {
     timeout?: number;
 }): Promise<void>;
 /** One display and the phase it publishes. */
@@ -55,5 +55,11 @@ export declare function displayCensusInPage(): {
     pending: DisplayState[];
     tooLarge: DisplayState[];
 };
+/**
+ * The error surfaces no display carries: the toast `notifyError` raises, as a
+ * track whose config fails to load does, and the box `ErrorMessage` renders.
+ * A track that never opened leaves nothing in {@link displayCensusInPage}.
+ */
+export declare function errorsShownInPage(): string[];
 /** Displays as one clause for a message. */
 export declare function describeDisplays(displays: DisplayState[]): string;

package/esm/sessionGate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_TIMEOUT, holdTrue } from './poll.js';
+import { DEFAULT_TIMEOUT, holdTrue, queryWhileOpen } from './poll.js';
 /**
  * The load failure the app shows in place of itself, the census
  * `AppReadyMarker` publishes beside its phase, and any snackbar up — which is
@@ -33,11 +33,11 @@ export function readSessionInPage() {
  * Throws at once with the app's message if it could not load, and on timeout
  * with what the census held instead.
  */
-export async function waitForSession(page, { assembly, trackIds = [], views = 1, timeout = DEFAULT_TIMEOUT, } = {}) {
+export async function waitForSession(page, { assembly, trackIds = [], minViews = 1, timeout = DEFAULT_TIMEOUT, } = {}) {
     let last;
     const notices = new Set();
     const reached = await holdTrue(async () => {
-        const read = await page.evaluate(readSessionInPage).catch(() => undefined);
+        const read = await queryWhileOpen(page, page.evaluate(readSessionInPage), undefined);
         if (read?.failure) {
             throw new Error(`JBrowse could not load: ${read.failure}`);
         }
@@ -47,7 +47,7 @@ export async function waitForSession(page, { assembly, trackIds = [], views = 1,
         const census = read?.census;
         last = census;
         return (!!census &&
-            census.views >= views &&
+            census.views >= minViews &&
             (assembly === undefined || census.assemblies.includes(assembly)) &&
             trackIds.every(id => census.trackIds.includes(id)));
     }, { holdMs: 0, timeout, pollMs: 250 });
@@ -67,7 +67,7 @@ export async function waitForSession(page, { assembly, trackIds = [], views = 1,
         const said = notices.size
             ? `The app said: ${[...notices].join(' | ')}.`
             : 'A trackId the config does not define, or an assembly name that does not match the config, looks like this.';
-        throw new Error(`the session never reached the requested state after ${timeout}ms. Wanted ${wanted || (views > 0 ? 'an open view' : 'a session')}; found ${found}. ${said}`);
+        throw new Error(`the session never reached the requested state after ${timeout}ms. Wanted ${wanted || (minViews > 0 ? 'an open view' : 'a session')}; found ${found}. ${said}`);
     }
 }
 /**
@@ -94,6 +94,16 @@ export function displayCensusInPage() {
     }
     return { pending, tooLarge };
 }
+/**
+ * The error surfaces no display carries: the toast `notifyError` raises, as a
+ * track whose config fails to load does, and the box `ErrorMessage` renders.
+ * A track that never opened leaves nothing in {@link displayCensusInPage}.
+ */
+export function errorsShownInPage() {
+    return [
+        ...document.querySelectorAll('[data-testid="snackbar-error"], [data-testid="error-message-box"]'),
+    ].map(el => (el.innerText || el.textContent || '').trim().slice(0, 300));
+}
 /** Displays as one clause for a message. */
 export function describeDisplays(displays) {
     return displays

package/esm/url.d.ts

@@ -1,4 +1,4 @@
-export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/v5.0.0-beta.11/";
+export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/v5.0.0-beta.14/";
 /**
  * The instance as the page that loads it sees it: a directory given without
  * its slash, which the host redirects, resolves relative URLs one level up.
@@ -7,7 +7,7 @@ export declare function instanceUrl(instance?: string): URL;
 export interface JBrowseUrlOptions {
     /** A genomes.jbrowse.org assembly: a UCSC db name (`hg38`) or GenArk accession. */
     hub?: string;
-    /** A config.json URL, for data that is not on genomes.jbrowse.org. Wins over `hub`. */
+    /** A config.json URL, for data that is not on genomes.jbrowse.org. Not combined with `hub`. */
     config?: string;
     /** Assembly to open. Defaults to `hub`, whose config names its assembly after it. */
     assembly?: string;
@@ -32,10 +32,11 @@ export interface JBrowseUrlOptions {
     instance?: string;
 }
 /**
- * A spec or a saved session says which assembly, locations and tracks to
- * open, so the URL carries one of the three ways of saying so, never two.
+ * One source for the config, never a hub and a config URL. A spec or a saved
+ * session says which assembly, locations and tracks to open, so the URL carries
+ * one of the three ways of saying so, never two.
  */
-export declare function assertSessionStandsAlone({ spec, session, assembly, loc, tracks, }: JBrowseUrlOptions): void;
+export declare function assertCoherentOptions({ hub, config, spec, session, assembly, loc, tracks, }: JBrowseUrlOptions): void;
 /**
  * The URL that opens a JBrowse Web instance onto a described view, for a
  * person to follow without launching a browser here.

package/esm/url.js

@@ -9,17 +9,24 @@ export const PUBLIC_INSTANCE = `https://jbrowse.org/code/jb2/v${version}/`;
  * its slash, which the host redirects, resolves relative URLs one level up.
  */
 export function instanceUrl(instance = PUBLIC_INSTANCE) {
-    const url = new URL(instance);
+    const url = URL.parse(instance);
+    if (!url || !['http:', 'https:', 'file:'].includes(url.protocol)) {
+        throw new Error(`instance "${instance}" is not an http(s) or file URL`);
+    }
     if (!url.pathname.endsWith('/') && !/\.html?$/.test(url.pathname)) {
         url.pathname += '/';
     }
     return url;
 }
 /**
- * A spec or a saved session says which assembly, locations and tracks to
- * open, so the URL carries one of the three ways of saying so, never two.
+ * One source for the config, never a hub and a config URL. A spec or a saved
+ * session says which assembly, locations and tracks to open, so the URL carries
+ * one of the three ways of saying so, never two.
  */
-export function assertSessionStandsAlone({ spec, session, assembly, loc, tracks, }) {
+export function assertCoherentOptions({ hub, config, spec, session, assembly, loc, tracks, }) {
+    if (hub && config) {
+        throw new Error('pass a hosted hub or a config URL, not both (--hub, --config); name the assembly with --assembly');
+    }
     if (spec && session) {
         throw new Error('pass a session spec or a saved session, not both');
     }
@@ -41,7 +48,15 @@ export function assertSessionStandsAlone({ spec, session, assembly, loc, tracks,
  * takes a locstring only. `session` opens a saved session as exported.
  */
 export function jbrowseUrl({ hub, config, assembly, loc, tracks, spec, session, sessionName, instance, }) {
-    assertSessionStandsAlone({ spec, session, assembly, loc, tracks });
+    assertCoherentOptions({
+        hub,
+        config,
+        spec,
+        session,
+        assembly,
+        loc,
+        tracks,
+    });
     const params = new URLSearchParams();
     const set = (key, value) => {
         if (value) {

package/esm/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.0.0-beta.11";
+export declare const version = "5.0.0-beta.14";

package/esm/version.js

@@ -1 +1 @@
-export const version = '5.0.0-beta.11';
+export const version = '5.0.0-beta.14';

package/esm/waits.d.ts

@@ -1,4 +1,5 @@
-import type { ElementHandle, Page } from 'puppeteer';
+import type { PageOrFrame } from './poll.ts';
+import type { ElementHandle } from 'puppeteer';
 interface WaitOptions {
     timeout?: number;
 }
@@ -14,7 +15,7 @@ export declare const displaySettled: (testid: string) => string;
  * `page.waitForSelector`, whose timeout names each display that had not
  * painted and the phase it was in.
  */
-export declare function waitForSelectorAttributed(page: Page, selector: string, { timeout }?: WaitOptions): Promise<ElementHandle>;
+export declare function waitForSelectorAttributed(page: PageOrFrame, selector: string, { timeout }?: WaitOptions): Promise<ElementHandle>;
 type SettleOptions = WaitOptions & {
     holdMs?: number;
     pollMs?: number;
@@ -23,7 +24,7 @@ type SettleOptions = WaitOptions & {
  * `waitForAppSettled`, answering with what was still blocking at the timeout,
  * or undefined once the hold passed.
  */
-export declare function appSettledBlocker(page: Page, { timeout, holdMs, pollMs, }?: SettleOptions): Promise<string | undefined>;
+export declare function appSettledBlocker(page: PageOrFrame, { timeout, holdMs, pollMs, }?: SettleOptions): Promise<string | undefined>;
 /**
  * Wait until every app on the page has read ready, with nothing loading or
  * animating, for an unbroken `holdMs`. False on timeout. Right after a
@@ -31,5 +32,5 @@ export declare function appSettledBlocker(page: Page, { timeout, holdMs, pollMs,
  * publishes `[data-app-phase]` throws, since nothing positive exists to wait
  * for.
  */
-export declare function waitForAppSettled(page: Page, options?: SettleOptions): Promise<boolean>;
+export declare function waitForAppSettled(page: PageOrFrame, options?: SettleOptions): Promise<boolean>;
 export {};

package/esm/waits.js

@@ -1,4 +1,4 @@
-import { DEFAULT_TIMEOUT, holdTrue } from './poll.js';
+import { DEFAULT_TIMEOUT, holdTrue, queryWhileOpen } from './poll.js';
 import { describeDisplays, displayCensusInPage } from './sessionGate.js';
 /** The app's own verdict: no view is resolving an assembly, no display is fetching. */
 export const APP_READY = '[data-app-phase="ready"]';
@@ -64,14 +64,12 @@ const NO_MARKER = 'no [data-app-phase] on the page';
  * or undefined once the hold passed.
  */
 export async function appSettledBlocker(page, { timeout = DEFAULT_TIMEOUT, holdMs = APP_SETTLED_HOLD_MS, pollMs = 250, } = {}) {
-    const blocker = () => page
-        .evaluate((ready, blockers, noMarker) => document.querySelector('[data-app-phase]') === null
+    const blocker = () => queryWhileOpen(page, page.evaluate((ready, blockers, noMarker) => document.querySelector('[data-app-phase]') === null
         ? noMarker
         : (blockers.find(([selector]) => document.querySelector(selector))?.[1] ??
             (document.querySelector(ready) === null
                 ? 'the marker not reading ready'
-                : undefined)), APP_READY, SETTLE_BLOCKERS, NO_MARKER)
-        .catch(() => 'the page could not be queried');
+                : undefined)), APP_READY, SETTLE_BLOCKERS, NO_MARKER), 'the page could not be queried');
     const held = await holdTrue(async () => (await blocker()) === undefined, {
         holdMs,
         timeout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/capture",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.14",
   "description": "Drive a JBrowse 2 instance with Puppeteer and screenshot it once it has actually finished rendering",
   "keywords": [
     "jbrowse",
@@ -16,7 +16,9 @@
   "type": "module",
   "main": "esm/index.js",
   "exports": {
-    ".": "./esm/index.js"
+    ".": "./esm/index.js",
+    "./annotationOverlay": "./esm/annotationOverlay.js",
+    "./graphAnchor": "./esm/graphAnchor.js"
   },
   "author": "JBrowse Team",
   "license": "Apache-2.0",
@@ -31,10 +33,10 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "puppeteer": "^25.12.0"
+    "puppeteer": "^25.14.0"
   },
   "devDependencies": {
-    "@jbrowse/core": "^5.0.0-beta.11"
+    "@jbrowse/core": "^5.0.0-beta.14"
   },
   "publishConfig": {
     "access": "public"