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

package/esm/hub.d.ts

@@ -1,23 +1,24 @@
 export declare function hubUrl(hub: string): string;
-interface HubTrack {
+export interface Track {
     trackId: string;
     type?: string;
-    name?: string;
+    name?: unknown;
 }
-interface HubConfig {
-    tracks?: HubTrack[];
-    [key: string]: unknown;
+export declare const trackName: (track: Track) => string;
+/** Tracks whose id or display name contains `filter`, ignoring case. */
+export declare function tracksMatching(tracks: Track[], filter: string): Track[];
+/** Fetch JSON with a timeout, throwing a message that names `what` and the URL. */
+export declare function fetchJson(url: string, what: string): Promise<unknown>;
+interface HostedAssembly {
+    name: string;
+    organism?: string;
+    description?: string;
 }
 /**
- * Fetch a hosted assembly config from genomes.jbrowse.org by UCSC database name
- * or GenArk accession. Use it to discover which trackIds an assembly publishes
- * before naming them in a session.
+ * The UCSC assemblies genomes.jbrowse.org hosts. Its thousands of GenArk
+ * accessions are not listed.
  */
-export declare function fetchHubConfig(hub: string): Promise<HubConfig>;
-/**
- * The trackIds a hosted assembly publishes, optionally narrowed to those whose
- * id or display name contains `filter`. Case-insensitive, because a hub carries
- * hundreds of tracks and an agent picking one from a name is the common case.
- */
-export declare function listHubTracks(hub: string, filter?: string): Promise<HubTrack[]>;
+export declare function listHubAssemblies(): Promise<HostedAssembly[]>;
+/** The tracks a hosted assembly publishes, optionally narrowed by `filter`. */
+export declare function listHubTracks(hub: string, filter?: string): Promise<Track[]>;
 export {};

package/esm/hub.js

@@ -1,43 +1,50 @@
 const HUB_HOST = 'https://jbrowse.org';
-// The genomes.jbrowse.org URL scheme: a UCSC database name (hg38, mm10, ...)
-// maps to /ucsc/<db>/config.json; a GenArk accession (GCA_/GCF_...) fans its 9
-// digits out into a 3-level directory tree.
-//
-// Deliberately a copy of `hubUrl` in packages/core/src/util/fetchHub.ts rather
-// than an import of it. This package is what an agent reaches for with a bare
-// `npx`, and its only runtime dependency is puppeteer; pulling in @jbrowse/core
-// (react, mobx, the whole state tree) to evaluate one regex would be the largest
-// thing in the install by far. `hub.test.ts` imports both and asserts they agree
-// on every shape, so the copy cannot drift silently.
+const FETCH_TIMEOUT_MS = 30000;
+const BROWSE_HINT = 'See https://genomes.jbrowse.org for the available assemblies.';
+// A copy of hubUrl in packages/core/src/util/fetchHub.ts, so an npx install
+// stays puppeteer-only; hub.test.ts holds the two together.
 export function hubUrl(hub) {
     const genark = /^(GC[AF])_(\d{3})(\d{3})(\d{3})/.exec(hub);
     return genark
         ? `${HUB_HOST}/hubs/genark/${genark[1]}/${genark[2]}/${genark[3]}/${genark[4]}/${hub}/config.json`
         : `${HUB_HOST}/ucsc/${hub}/config.json`;
 }
-/**
- * Fetch a hosted assembly config from genomes.jbrowse.org by UCSC database name
- * or GenArk accession. Use it to discover which trackIds an assembly publishes
- * before naming them in a session.
- */
-export async function fetchHubConfig(hub) {
-    const url = hubUrl(hub);
-    const res = await fetch(url);
+export const trackName = (track) => typeof track.name === 'string' ? track.name : '';
+/** Tracks whose id or display name contains `filter`, ignoring case. */
+export function tracksMatching(tracks, filter) {
+    const needle = filter.toLowerCase();
+    return tracks.filter(t => `${t.trackId} ${trackName(t)}`.toLowerCase().includes(needle));
+}
+/** Fetch JSON with a timeout, throwing a message that names `what` and the URL. */
+export async function fetchJson(url, what) {
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    }).catch((error) => {
+        const timedOut = error instanceof Error && error.name === 'TimeoutError';
+        throw new Error(`${what} could not be fetched from ${url} ` +
+            `(${error instanceof Error ? error.message : error}${timedOut ? `, after ${FETCH_TIMEOUT_MS}ms` : ''}). ${BROWSE_HINT}`);
+    });
     if (!res.ok) {
-        throw new Error(`hub "${hub}" not found (HTTP ${res.status} from ${url}). ` +
-            'See https://genomes.jbrowse.org for the available assemblies.');
+        throw new Error(`${what} not found (HTTP ${res.status} from ${url}). ${BROWSE_HINT}`);
     }
-    return (await res.json());
+    return res.json();
 }
 /**
- * The trackIds a hosted assembly publishes, optionally narrowed to those whose
- * id or display name contains `filter`. Case-insensitive, because a hub carries
- * hundreds of tracks and an agent picking one from a name is the common case.
+ * The UCSC assemblies genomes.jbrowse.org hosts. Its thousands of GenArk
+ * accessions are not listed.
  */
+export async function listHubAssemblies() {
+    const { ucscGenomes = {} } = (await fetchJson(`${HUB_HOST}/ucsc/list.json`, 'the hosted assembly list'));
+    return Object.entries(ucscGenomes)
+        .map(([name, { organism, description }]) => ({
+        name,
+        organism,
+        description,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The tracks a hosted assembly publishes, optionally narrowed by `filter`. */
 export async function listHubTracks(hub, filter) {
-    const { tracks = [] } = await fetchHubConfig(hub);
-    const needle = filter?.toLowerCase();
-    return needle
-        ? tracks.filter(t => `${t.trackId} ${t.name ?? ''}`.toLowerCase().includes(needle))
-        : tracks;
+    const { tracks = [] } = (await fetchJson(hubUrl(hub), `hub "${hub}"`));
+    return filter ? tracksMatching(tracks, filter) : tracks;
 }

package/esm/imagePath.d.ts

@@ -0,0 +1 @@
+export declare function assertImagePath(out: string): void;

package/esm/imagePath.js

@@ -0,0 +1,8 @@
+// The types puppeteer infers from a path; it writes a PNG under any other name.
+const IMAGE_EXTENSION = /\.(png|jpe?g|webp)$/i;
+export function assertImagePath(out) {
+    if (!IMAGE_EXTENSION.test(out)) {
+        throw new Error(`--out needs a .png, .jpg, .jpeg or .webp path, got "${out}" ` +
+            '(for SVG, @jbrowse/img renders one without a browser)');
+    }
+}

package/esm/index.d.ts

@@ -1,10 +1,13 @@
-export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.ts';
-export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.ts';
-export { PUBLIC_INSTANCE, jbrowseUrl } from './url.ts';
-export { fetchHubConfig, hubUrl, listHubTracks } from './hub.ts';
-export { assemblyFromSession, encodeSessionSpec, sessionSpecParam, sessionSpecQuery, trackIdsFromSession, } from './session.ts';
-export { APP_READY, BUSY_SELECTOR, LOADING_OVERLAY, PENDING_DISPLAYS, delay, describePendingDisplaysNow, displayById, displayPainted, displaySettled, hasAppReadyMarker, isPageBusyInPage, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForSelectorAttributed, waitForViewPhases, } from './waits.ts';
-export { BASE_CHROME_ARGS, SANDBOX_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.ts';
-export type { CaptureOptions, CaptureResult, OpenOptions, OpenResult, ReadyOptions, ReadyReport, } from './capture.ts';
-export type { Instrumentation, PendingDisplay, SessionExpectations, SessionSummary, } from './sessionGate.ts';
+export { captureJBrowse, openJBrowse } from './capture.ts';
+export { delay } from './poll.ts';
+export { waitForFrame, waitForJBrowseReady } from './ready.ts';
+export { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.ts';
+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 { LaunchOptions } from './browser.ts';
+export type { CaptureOptions, CaptureResult, OpenOptions, OpenResult, } from './capture.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,7 +1,8 @@
-export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.js';
-export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
-export { PUBLIC_INSTANCE, jbrowseUrl } from './url.js';
-export { fetchHubConfig, hubUrl, listHubTracks } from './hub.js';
-export { assemblyFromSession, encodeSessionSpec, sessionSpecParam, sessionSpecQuery, trackIdsFromSession, } from './session.js';
-export { APP_READY, BUSY_SELECTOR, LOADING_OVERLAY, PENDING_DISPLAYS, delay, describePendingDisplaysNow, displayById, displayPainted, displaySettled, hasAppReadyMarker, isPageBusyInPage, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForSelectorAttributed, waitForViewPhases, } from './waits.js';
-export { BASE_CHROME_ARGS, SANDBOX_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';
+export { captureJBrowse, openJBrowse } from './capture.js';
+export { delay } from './poll.js';
+export { waitForFrame, waitForJBrowseReady } from './ready.js';
+export { describeDisplays, displayCensusInPage, waitForSession, } from './sessionGate.js';
+export { jbrowseUrl } from './url.js';
+export { assemblyFromSession, encodeSessionSpec, sessionSpecQuery, trackIdsFromSession, } from './session.js';
+export { PENDING_DISPLAYS, displayPainted, displaySettled, waitForAppSettled, waitForSelectorAttributed, } from './waits.js';
+export { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, launchBrowser, } from './browser.js';

package/esm/instanceVersion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Refuse a JBrowse Web instance older than v5, read off its `version.txt`. An
+ * instance that serves no version passes, and the session gate judges it.
+ */
+export declare function assertSupportedInstance(instance: string): Promise<void>;

package/esm/instanceVersion.js

@@ -0,0 +1,21 @@
+import { instanceUrl } from './url.js';
+// the first release to publish `[data-app-phase]` and its census
+const MIN_MAJOR = 5;
+/**
+ * Refuse a JBrowse Web instance older than v5, read off its `version.txt`. An
+ * instance that serves no version passes, and the session gate judges it.
+ */
+export async function assertSupportedInstance(instance) {
+    const text = await fetch(new URL('version.txt', instanceUrl(instance)), {
+        signal: AbortSignal.timeout(10000),
+    })
+        .then(res => (res.ok ? res.text() : ''))
+        .catch(() => '');
+    const version = text.trim();
+    const major = /^(\d+)\.\d+\.\d+/.exec(version)?.[1];
+    if (major !== undefined && Number(major) < MIN_MAJOR) {
+        throw new Error(`${instance} serves JBrowse ${version}, and @jbrowse/capture needs v${MIN_MAJOR} or later: ` +
+            'older builds publish no readiness marker to wait on. Point --instance at a ' +
+            `v${MIN_MAJOR} build.`);
+    }
+}

package/esm/poll.d.ts

@@ -0,0 +1,14 @@
+/** 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>;
+/**
+ * Poll `read` until it has answered true for `holdMs` without a break, or
+ * `timeout` runs out. A `read` that throws ends the wait with its error.
+ * Polled from Node because Chrome throttles in-page timers in a background
+ * tab, which is what a headless page is.
+ */
+export declare function holdTrue(read: () => Promise<boolean>, { holdMs, timeout, pollMs, }: {
+    holdMs: number;
+    timeout: number;
+    pollMs: number;
+}): Promise<boolean>;

package/esm/poll.js

@@ -0,0 +1,30 @@
+/** The budget each stage of the ready chain gets unless told otherwise. */
+export const DEFAULT_TIMEOUT = 60000;
+export const delay = (ms) => new Promise(resolve => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Poll `read` until it has answered true for `holdMs` without a break, or
+ * `timeout` runs out. A `read` that throws ends the wait with its error.
+ * Polled from Node because Chrome throttles in-page timers in a background
+ * tab, which is what a headless page is.
+ */
+export async function holdTrue(read, { holdMs, timeout, pollMs, }) {
+    const deadline = Date.now() + timeout;
+    let since;
+    while (Date.now() < deadline) {
+        const ok = await read();
+        const now = Date.now();
+        if (ok) {
+            since ??= now;
+            if (now - since >= holdMs) {
+                return true;
+            }
+        }
+        else {
+            since = undefined;
+        }
+        await delay(pollMs);
+    }
+    return false;
+}

package/esm/ready.d.ts

@@ -0,0 +1,29 @@
+import type { DisplayState, SessionExpectations } from './sessionGate.ts';
+import type { Page } from 'puppeteer';
+export interface ReadyOptions extends SessionExpectations {
+    /** Budget for each wait stage. */
+    timeout?: number;
+    /**
+     * Return the report instead of throwing when a stage times out or a display
+     * is not showing its data.
+     */
+    allowUnsettled?: boolean;
+}
+export interface ReadyReport {
+    /** Displays unpainted, canceled or showing an error, each with its phase. */
+    pending: DisplayState[];
+    /** Displays showing "too much data" in place of their features. Not a failure. */
+    tooLarge: DisplayState[];
+    /** What did not settle. Empty unless `allowUnsettled`. */
+    unsettled: string[];
+}
+/**
+ * Wait until the session holds the assembly and tracks asked for, the app has
+ * held itself ready, and every display has painted.
+ */
+export declare function waitForJBrowseReady(page: Page, 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>;

package/esm/ready.js

@@ -0,0 +1,44 @@
+import { DEFAULT_TIMEOUT } from './poll.js';
+import { describeDisplays, displayCensusInPage, 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.
+ */
+export async function waitForJBrowseReady(page, options = {}) {
+    await waitForSession(page, options);
+    return waitForFrame(page, options);
+}
+/**
+ * `waitForJBrowseReady` without the session gate, for a frame that changed
+ * while the session did not, such as after a viewport resize.
+ */
+export async function waitForFrame(page, { timeout = DEFAULT_TIMEOUT, allowUnsettled = false, } = {}) {
+    const unsettled = [];
+    const blocker = await appSettledBlocker(page, { timeout });
+    if (blocker) {
+        unsettled.push(`the app never held itself ready (last blocked by ${blocker})`);
+    }
+    const timedOut = unsettled.length > 0;
+    const { pending, tooLarge } = await page.evaluate(displayCensusInPage);
+    const failed = pending.filter(d => d.phase === 'error' || d.phase === 'renderError');
+    const canceled = pending.filter(d => d.phase === 'canceled');
+    const unpainted = pending.filter(d => !failed.includes(d) && !canceled.includes(d));
+    if (failed.length > 0) {
+        unsettled.push(`display(s) showing an error: ${describeDisplays(failed)}`);
+    }
+    if (unpainted.length > 0) {
+        unsettled.push(`display(s) never painted: ${describeDisplays(unpainted)}`);
+    }
+    if (canceled.length > 0) {
+        unsettled.push(`display(s) canceled, which lasts until Retry: ${describeDisplays(canceled)}`);
+    }
+    if (!allowUnsettled && unsettled.length > 0) {
+        const stillLoading = pending.some(d => d.phase === undefined || d.phase === 'loading');
+        const advice = timedOut || stillLoading
+            ? 'Raise the timeout, or pass'
+            : 'No timeout changes that; pass';
+        throw new Error(`${timedOut ? `gave up waiting after ${timeout}ms: ` : ''}${unsettled.join('; ')}. ${advice} allowUnsettled (--allowUnsettled) to capture the frame as it stands.`);
+    }
+    return { pending, tooLarge, unsettled };
+}

package/esm/session.d.ts

@@ -1,23 +1,35 @@
+/**
+ * The decoded `session=` value that opens a session spec. Hand it to
+ * `URLSearchParams`, which encodes it once itself.
+ */
 export declare function sessionSpecParam(session: object): string;
+/**
+ * The `session=` value pre-encoded, for a query string built by hand. Passed
+ * through `URLSearchParams` as well, it is encoded twice and the app fails to
+ * parse it.
+ */
 export declare function encodeSessionSpec(session: object): string;
 /**
- * The assembly a session spec's first view opens, if it names one.
- *
- * The session gate needs this because a spec can be loaded against any config —
- * `--hub hg38 --session spec.json` where the spec opens a different assembly is
- * legitimate, and defaulting the expectation to the hub name would fail a
- * perfectly good capture.
+ * The `session=` value that opens a session saved with "Export session...".
+ * Takes the exported `{ session: {...} }` document or the snapshot inside it.
+ */
+export declare function savedSessionParam(session: object): string;
+/** The snapshot inside an exported session document, or the snapshot itself. */
+export declare function savedSnapshot(session: object): object;
+/**
+ * The assembly the first view of a session spec or saved snapshot opens, if
+ * it names one.
  */
 export declare function assemblyFromSession(session: object): string | undefined;
 /**
- * Every trackId a session spec asks a view to open, including nested views (a
- * synteny or breakpoint-split spec puts its LGVs one level down).
- *
- * Used as the session gate's expectation: it is what turns "the browser loaded"
- * into "the tracks I named are open", and a spec is the one input where the
- * caller has not spelled those ids out separately.
+ * Every trackId a session spec or saved snapshot opens, nested views
+ * included.
  */
 export declare function trackIdsFromSession(session: object): string[];
+/**
+ * `?config=…&session=…&sessionName=…`, for a caller that has an origin but no
+ * JBrowse instance URL to hand `jbrowseUrl`.
+ */
 export declare function sessionSpecQuery({ config, session, sessionName, }: {
     config: string;
     session: object;

package/esm/session.js

@@ -1,31 +1,41 @@
-// The DECODED value of the `session=` query param that jbrowse-web reads to open
-// a declarative session without a saved-session backend: a `spec-` prefix plus
-// the session JSON. This is what the app sees after the query string is parsed,
-// so it is the right thing to hand to `URLSearchParams.set`, which does its own
-// encoding.
+/**
+ * The decoded `session=` value that opens a session spec. Hand it to
+ * `URLSearchParams`, which encodes it once itself.
+ */
 export function sessionSpecParam(session) {
     return `spec-${JSON.stringify(session)}`;
 }
-// The same value pre-encoded, for callers that concatenate a query string by
-// hand rather than going through URL. Passing THIS to `URLSearchParams.set`
-// encodes it a second time, and the app then decodes once and parses `%7B…` as
-// JSON — so pick one path and stay on it. Shared so the runner and screenshot
-// generator can't drift on the encoding.
+/**
+ * The `session=` value pre-encoded, for a query string built by hand. Passed
+ * through `URLSearchParams` as well, it is encoded twice and the app fails to
+ * parse it.
+ */
 export function encodeSessionSpec(session) {
     return encodeURIComponent(sessionSpecParam(session));
 }
 /**
- * The assembly a session spec's first view opens, if it names one.
- *
- * The session gate needs this because a spec can be loaded against any config —
- * `--hub hg38 --session spec.json` where the spec opens a different assembly is
- * legitimate, and defaulting the expectation to the hub name would fail a
- * perfectly good capture.
+ * The `session=` value that opens a session saved with "Export session...".
+ * Takes the exported `{ session: {...} }` document or the snapshot inside it.
+ */
+export function savedSessionParam(session) {
+    return `json-${JSON.stringify({ session: savedSnapshot(session) })}`;
+}
+/** The snapshot inside an exported session document, or the snapshot itself. */
+export function savedSnapshot(session) {
+    const inner = session.session;
+    return typeof inner === 'object' && inner !== null ? inner : session;
+}
+/**
+ * The assembly the first view of a session spec or saved snapshot opens, if
+ * it names one.
  */
 export function assemblyFromSession(session) {
     const find = (views) => {
         for (const view of views ?? []) {
-            const found = view.assembly ?? find(view.views);
+            const found = [view.assembly ?? []].flat()[0] ??
+                view.displayedRegions?.[0]?.assemblyName ??
+                view.assemblyNames?.[0] ??
+                find(view.views);
             if (found) {
                 return found;
             }
@@ -35,27 +45,32 @@ export function assemblyFromSession(session) {
     return find(session.views);
 }
 /**
- * Every trackId a session spec asks a view to open, including nested views (a
- * synteny or breakpoint-split spec puts its LGVs one level down).
- *
- * Used as the session gate's expectation: it is what turns "the browser loaded"
- * into "the tracks I named are open", and a spec is the one input where the
- * caller has not spelled those ids out separately.
+ * Every trackId a session spec or saved snapshot opens, nested views
+ * included.
  */
 export function trackIdsFromSession(session) {
+    const idOf = (t) => typeof t === 'string'
+        ? t
+        : (t.trackId ??
+            (typeof t.configuration === 'string'
+                ? t.configuration
+                : t.configuration?.trackId));
+    const idsOf = (tracks = []) => tracks.map(idOf).filter(id => id !== undefined);
     const collect = (views) => (views ?? []).flatMap(view => [
-        // an entry may be a bare id or `{trackId, displaySnapshot}`; an object
-        // without a trackId is malformed rather than a track to expect, so it
-        // drops out here instead of gating on undefined
-        ...(view.tracks ?? [])
-            .map(t => (typeof t === 'string' ? t : t.trackId))
-            .filter(id => id !== undefined),
+        ...idsOf(view.tracks?.flat()),
+        ...(view.levels ?? []).flatMap(l => idsOf(l.tracks)),
         ...collect(view.views),
     ]);
     return collect(session.views);
 }
-// Full `?config=…&session=…&sessionName=…` query string. `config` is inserted
-// as-is (callers that point at a remote absolute URL pre-encode it themselves).
+/**
+ * `?config=…&session=…&sessionName=…`, for a caller that has an origin but no
+ * JBrowse instance URL to hand `jbrowseUrl`.
+ */
 export function sessionSpecQuery({ config, session, sessionName = 'Screenshot', }) {
-    return `?config=${config}&session=${encodeSessionSpec(session)}&sessionName=${encodeURIComponent(sessionName)}`;
+    return `?${new URLSearchParams({
+        config,
+        session: sessionSpecParam(session),
+        sessionName,
+    })}`;
 }