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

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 { clearAnnotations, drawAnnotations } from './annotations.ts';
 export { delay } from './poll.ts';
 export { waitForFrame, waitForJBrowseReady } from './ready.ts';
 export { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.ts';
@@ -6,6 +7,7 @@ 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 { ReadyOptions, ReadyReport } from './ready.ts';

package/esm/index.js

@@ -1,4 +1,5 @@
 export { 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';

package/esm/jsonArgs.d.ts

@@ -0,0 +1,4 @@
+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;

package/esm/jsonArgs.js

@@ -0,0 +1,34 @@
+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}: ${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;
+}

package/esm/poll.d.ts

@@ -1,3 +1,4 @@
+import type { Page } from 'puppeteer';
 /** 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 +13,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>(page: Page, query: Promise<T>, fallback: F): Promise<T | F>;

package/esm/poll.js

@@ -28,3 +28,23 @@ export async function holdTrue(read, { holdMs, timeout, pollMs, }) {
     }
     return false;
 }
+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(page, query, fallback) {
+    try {
+        return await query;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (PAGE_GONE.test(message) ||
+            page.isClosed() ||
+            !page.browser().connected) {
+            throw new Error(`the page closed or crashed before it finished rendering (${message})`, { cause: error });
+        }
+        return fallback;
+    }
+}

package/esm/ready.d.ts

@@ -19,7 +19,7 @@ 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>;
 /**

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

@@ -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: Page, { 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.10/";
+export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/v5.0.0-beta.13/";
 /**
  * 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.10";
+export declare const version = "5.0.0-beta.13";

package/esm/version.js

@@ -1 +1 @@
-export const version = '5.0.0-beta.10';
+export const version = '5.0.0-beta.13';

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.10",
+  "version": "5.0.0-beta.13",
   "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",
@@ -34,7 +36,7 @@
     "puppeteer": "^25.12.0"
   },
   "devDependencies": {
-    "@jbrowse/core": "^5.0.0-beta.10"
+    "@jbrowse/core": "^5.0.0-beta.13"
   },
   "publishConfig": {
     "access": "public"