@jbrowse/capture 4.3.0 → 5.0.0-beta.2

package/esm/args.js

@@ -1,4 +1,5 @@
 const NUMERIC = new Set(['width', 'height', 'scale', 'timeout', 'settle']);
+const POSITIVE = new Set(['width', 'height', 'scale']);
 const FLAGS = new Set([
     'fullPage',
     'headed',
@@ -53,6 +54,10 @@ export function parseArgs(argv) {
             throw new Error(`unknown flag "${arg}"`);
         }
         if (FLAGS.has(name)) {
+            // `--fullPage=false` used to set the flag true, silently.
+            if (eq !== -1) {
+                throw new Error(`--${name} is a flag and takes no value; omit it to leave it off`);
+            }
             out[name] = true;
             continue;
         }
@@ -69,6 +74,11 @@ export function parseArgs(argv) {
             if (!Number.isFinite(n)) {
                 throw new Error(`--${name} needs a number, got "${value}"`);
             }
+            // A zero-size viewport or scale otherwise fails much later, inside
+            // puppeteer, with an error naming neither the flag nor the value.
+            if (POSITIVE.has(name) && n <= 0) {
+                throw new Error(`--${name} needs a positive number, got "${value}"`);
+            }
             out[name] = n;
         }
         else {

package/esm/capture.d.ts

@@ -1,70 +1,6 @@
-import type { Instrumentation, PendingDisplay, SessionExpectations } from './sessionGate.ts';
+import type { ReadyOptions, ReadyReport } from './ready.ts';
 import type { JBrowseUrlOptions } from './url.ts';
 import type { Browser, Page } from 'puppeteer';
-export interface ReadyOptions extends SessionExpectations {
-    /** Budget for each individual wait stage. */
-    timeout?: number;
-    /**
-     * Also wait out adapter "Downloading…" status text, which can outlive the
-     * loading overlay when a track streams a large remote file.
-     */
-    waitForDownloads?: boolean;
-    /** Extra settle after everything reports done, for animations and tooltips. */
-    settleMs?: number;
-    /**
-     * Skip the session gate. Only for a page that is not jbrowse-web and so
-     * publishes no `window.JBrowseSession` — an embedded component, say. You lose
-     * the only check that the data you asked for is the data on screen.
-     */
-    expectSession?: boolean;
-    /**
-     * Return the report instead of throwing when a wait stage times out. For
-     * capturing a page that is deliberately mid-load, or accepting a known-slow
-     * one. The unsettled stages are still listed in the report either way.
-     */
-    allowUnsettled?: boolean;
-}
-export interface ReadyReport {
-    /** Displays still reporting unpainted at the end of the wait. */
-    pending: string[];
-    /**
-     * The same displays with the phase each one publishes, which is what
-     * separates a slow fetch from a display that says it finished without
-     * painting. Empty whenever `pending` is.
-     */
-    pendingStates: PendingDisplay[];
-    /**
-     * Whether every display's paint state was actually measurable — false when
-     * tracks are open but the build publishes no `data-display-drawn`. With this
-     * false, an empty `pending` means "cannot tell", not "all done".
-     */
-    paintContract: boolean;
-    /** Wait stages that hit their timeout instead of being satisfied. */
-    unsettled: string[];
-    /**
-     * Which readiness attributes the build published, read once the session was
-     * up. Every `false` here is a wait that could not fail rather than one that
-     * passed, and the chain compensates for it — see LEGACY_QUIET_MS.
-     */
-    instrumentation: Instrumentation;
-    /**
-     * Whether the page published `[data-app-phase]`, the one positive readiness
-     * selector. True means the wait was that selector and nothing else; false
-     * means the build predates it and the fallback chain ran.
-     */
-    appMarker: boolean;
-}
-/**
- * Wait until a JBrowse page has finished loading AND finished drawing.
- *
- * One positive gate, then the negative ones. The order is the whole point: the
- * DOM waits all pass on a page that has not started yet, so without the session
- * gate in front the chain returns in under a second (see sessionGate.ts). After
- * it, each stage is only meaningful once the previous has passed — a view still
- * resolving its assembly has mounted no displays, and a display that has mounted
- * but not fetched has nothing to be drawn yet.
- */
-export declare function waitForJBrowseReady(page: Page, { timeout, waitForDownloads, settleMs, expectSession, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;
 export interface OpenOptions extends JBrowseUrlOptions, ReadyOptions {
     width?: number;
     height?: number;
@@ -99,7 +35,14 @@ export declare function openJBrowse(options?: OpenOptions): Promise<OpenResult>;
 export interface CaptureOptions extends OpenOptions {
     /** PNG path to write. Omit to get the buffer back and write it yourself. */
     out?: string;
-    /** Capture the whole scrollable page rather than the viewport. */
+    /**
+     * Capture the whole scrollable page rather than the viewport. Implemented by
+     * growing the viewport to the page height and re-settling, never by
+     * `page.screenshot({ fullPage: true })` — puppeteer implements that flag with
+     * the same viewport resize but shoots immediately, and the capture can return
+     * before the content re-rasters (measured in the browser-test suites as a
+     * 10–25% image diff that moves run to run).
+     */
     fullPage?: boolean;
 }
 export interface CaptureResult extends ReadyReport {

package/esm/capture.js

@@ -1,184 +1,11 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 import puppeteer from 'puppeteer';
 import { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';
+import { waitForJBrowseReady } from './ready.js';
 import { assemblyFromSession, trackIdsFromSession } from './session.js';
-import { describePendingDisplays, hasPaintContract, pendingDisplayStates, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
 import { jbrowseUrl } from './url.js';
-import { delay, hasAppReadyMarker, waitForAppReady, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForViewPhases, } from './waits.js';
-// A build with no per-display paint attributes gives no signal between "the
-// overlay cleared" and "the canvas has pixels on it", so the only thing left is
-// to wait. Sized from the measured gap on jbrowse.org/code/jb2/latest between
-// the overlay clearing and the tracks being fully drawn.
-const LEGACY_PAINT_SETTLE_MS = 1500;
-// ...and the gap at the OTHER end, which is the one that lands a capture on an
-// app that has drawn nothing at all. Measured on the same instance with two
-// remote tracks: the session gate is satisfied at ~2.5s, and the loading overlay
-// — the only remaining signal there — does not go up until ~3.5s. An
-// instrumented build has no such window: `data-display-phase` appears in the
-// same frame as the display it belongs to.
-//
-// So on an uninstrumented build the app has to be seen to START working, and
-// then hold still, before it counts as finished. The window is how long the
-// first indicator gets to appear before "nothing to wait for" is the better
-// reading; the quiet is how long the idle then has to hold.
-const LEGACY_BUSY_WINDOW_MS = 4000;
-const LEGACY_QUIET_MS = 2000;
-/**
- * Wait until a JBrowse page has finished loading AND finished drawing.
- *
- * One positive gate, then the negative ones. The order is the whole point: the
- * DOM waits all pass on a page that has not started yet, so without the session
- * gate in front the chain returns in under a second (see sessionGate.ts). After
- * it, each stage is only meaningful once the previous has passed — a view still
- * resolving its assembly has mounted no displays, and a display that has mounted
- * but not fetched has nothing to be drawn yet.
- */
-export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownloads = true, settleMs = 0, expectSession = true, assembly, trackIds, allowUnsettled = false, } = {}) {
-    const unsettled = [];
-    const stage = async (name, work) => {
-        if (!(await work)) {
-            unsettled.push(name);
-        }
-    };
-    // The two hard waits reject with puppeteer's own `Waiting failed: Nms
-    // exceeded`, which names neither the stage nor the selector — the whole
-    // failure mode this module exists to avoid, arriving as an error message
-    // instead of as a blank image. Say which gate it was and what to do.
-    const required = async (name, work) => {
-        try {
-            return await work;
-        }
-        catch {
-            throw new Error(`gave up waiting after ${timeout}ms: ${name}. Raise the timeout if the ` +
-                'page is merely slow; if it never finishes, open the same URL in a ' +
-                'browser — this gate has no content to fall through to.');
-        }
-    };
-    // 0. the session exists and holds what was asked for. Positive, and throws.
-    if (expectSession) {
-        await waitForSession(page, { assembly, trackIds, timeout });
-    }
-    // 1. THE WHOLE ANSWER, on any build that has it: the session renders
-    //    `[data-app-phase="ready"]` when no view is resolving an assembly and no
-    //    display is fetching. It is positive, so unlike everything below it
-    //    cannot be satisfied by an app that has not started, and there is nothing
-    //    to assemble — wait for the selector and stop.
-    //
-    //    Everything after this point is the fallback for a deployment older than
-    //    the marker, and can be deleted the day the oldest supported build has
-    //    it.
-    if (await hasAppReadyMarker(page)) {
-        const ready = await waitForAppReady(page, { timeout });
-        if (!ready) {
-            unsettled.push('the app never reported itself ready');
-        }
-        // One thing the marker does not answer, so this stage stays even here: the
-        // marker is about WORK, and a display whose fetch failed is not working. It
-        // reads `ready` over an error banner, which is a correct answer to a
-        // different question than a capture is asking. `data-display-drawn` is the
-        // stricter gate — the two comparative canvases publish it from `settled`,
-        // which holds an error open deliberately so a golden regenerated during an
-        // outage fails here instead of absorbing the banner as expected output.
-        // Ordered after the marker rather than instead of it, which is what makes an
-        // absence meaningful (see waitForDisplaysDone), and free on a page that has
-        // no such canvas.
-        await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
-        if (settleMs > 0) {
-            await delay(settleMs);
-        }
-        const pendingStates = await pendingDisplayStates(page);
-        const report = {
-            pending: pendingStates.map(d => d.name),
-            pendingStates,
-            paintContract: await hasPaintContract(page),
-            unsettled,
-            instrumentation: await readInstrumentation(page),
-            appMarker: true,
-        };
-        if (!allowUnsettled && unsettled.length > 0) {
-            throw new Error(unsettledMessage(timeout, unsettled, pendingStates));
-        }
-        return report;
-    }
-    // 1b. what an older build can be asked instead. On one that publishes none of
-    //     these, the stages below are not gates at all: they are assertions about
-    //     absent attributes that no page can fail.
-    const instrumentation = await readInstrumentation(page);
-    const instrumented = instrumentation.displayPhase || instrumentation.displayDrawn;
-    // A page with no tracks open has nothing to load, so the quiet gate below
-    // would be a fixed sleep for an import form or a menu shot.
-    const summary = await readSessionSummary(page);
-    const needsQuietGate = !instrumented && (summary?.trackIds.length ?? 0) > 0;
-    // 2. the view has an assembly and its React component has arrived. Also not
-    //    best-effort: a view stuck here has no content to fall through to.
-    await required('a view never left its loading phase (still resolving its assembly, or its ' +
-        'lazily-imported component never arrived)', waitForViewPhases(page, timeout));
-    // 2. no track is still fetching. One call, two outcomes: the overlay half is
-    //    required (an overlay that never clears is a fetch that never finished,
-    //    with nothing behind it) and throws; the "Downloading…" half is
-    //    best-effort and comes back as the boolean.
-    const downloadsSettled = await required('the loading overlay never cleared (a track fetch never finished)', waitForLoadingComplete(page, { timeout, waitForDownloads }));
-    if (!downloadsSettled) {
-        unsettled.push('a track was still downloading');
-    }
-    await stage('a display was still in its loading phase', waitForDisplayPhases(page, timeout));
-    // 3. no display is still pending its first paint
-    await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
-    // 4. no visible "Loading…/Rendering…/Computing…" text remains, which is how
-    //    the views that publish no phase attribute report themselves
-    await stage('a "Loading…/Rendering…" label was still on screen', waitForQuiescent(page, { timeout }));
-    // 5. and on a build that answered none of the above, the one gate that does
-    //    not depend on an attribute existing: the app has to hold still. Every
-    //    stage before this one passed the moment it was asked, so without it the
-    //    chain returns while the first fetch is still being set up.
-    if (needsQuietGate) {
-        await stage('the app never went quiet for ' +
-            `${LEGACY_QUIET_MS}ms (this build publishes no readiness attributes, ` +
-            'so being seen to work and then stop is the only finished signal there ' +
-            'is)', waitForQuietPeriod(page, {
-            quietMs: LEGACY_QUIET_MS,
-            busyWindowMs: LEGACY_BUSY_WINDOW_MS,
-            timeout,
-        }));
-    }
-    const paintContract = await hasPaintContract(page);
-    if (!paintContract) {
-        await delay(LEGACY_PAINT_SETTLE_MS);
-    }
-    if (settleMs > 0) {
-        await delay(settleMs);
-    }
-    const pendingStates = await pendingDisplayStates(page);
-    const report = {
-        pending: pendingStates.map(d => d.name),
-        pendingStates,
-        paintContract,
-        unsettled,
-        instrumentation,
-        appMarker: false,
-    };
-    if (!allowUnsettled && unsettled.length > 0) {
-        // Throwing is the point. Each of these stages swallows its own timeout so a
-        // slow page is not failed for being slow, which historically meant the run
-        // ended with an image and an exit code of 0 whether it had settled or not.
-        // A caller that genuinely wants the frame anyway asks for it by name.
-        throw new Error(unsettledMessage(timeout, unsettled, pendingStates));
-    }
-    return report;
-}
-/**
- * What a timed-out wait says. The stage names alone were the whole message, and
- * they name the QUESTION rather than the answer — "a display never reported its
- * first paint" reads identically for a slow fetch, a failed one and a display
- * that never had a canvas to paint. Appending the census answers it, and the
- * `ready` case is the one that most changes what a reader does next: a longer
- * timeout is the fix for `loading` and never the fix for that.
- */
-function unsettledMessage(timeout, unsettled, pending) {
-    return (`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ${pending.length > 0
-        ? `Still unpainted: ${describePendingDisplays(pending)}. `
-        : ''}Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ` +
-        `capture the frame as it stands.`);
-}
+import { waitForAppSettled } from './waits.js';
 /**
  * Launch a browser, navigate to a JBrowse session, and wait until it has
  * rendered. The caller owns the returned browser and must close it.
@@ -192,7 +19,11 @@ function unsettledMessage(timeout, unsettled, pending) {
  * than producing an image of an empty browser.
  */
 export async function openJBrowse(options = {}) {
-    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, timeout, trackIds, 
+    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, 
+    // Defaulted here as well as in waitForJBrowseReady, so the navigation gets
+    // the same budget as the wait stages — puppeteer's own goto default is 30s,
+    // half of what a caller passing nothing was told each stage would get.
+    timeout = 60000, trackIds, 
     // Pulled out only to keep them out of `urlOptions`, which becomes the
     // query string. They reach the ready wait through the `...options` spread
     // below rather than from here.
@@ -229,18 +60,17 @@ export async function openJBrowse(options = {}) {
             // construction. Listing them by hand is what dropped `allowUnsettled`:
             // it was declared, documented, recommended by this function's own timeout
             // message, and silently never forwarded, so `--allowUnsettled` did
-            // nothing and a timing-out stage always threw. Only the two options
-            // derived from the URL are overridden below.
+            // nothing and a timing-out stage always threw. Overridden below: the
+            // defaulted timeout, and the two options derived from the URL.
             ...options,
+            timeout,
             // A session spec's own assembly wins over the hub name. `--hub hg38
             // --session spec.json` where the spec opens something else is legitimate
             // (the hub is just supplying the config), and expecting the hub name there
             // would fail a capture that is entirely correct.
-            assembly: urlOptions.assembly ??
-                (urlOptions.session
-                    ? assemblyFromSession(urlOptions.session)
-                    : undefined) ??
-                (urlOptions.session ? undefined : urlOptions.hub),
+            assembly: urlOptions.session
+                ? (urlOptions.assembly ?? assemblyFromSession(urlOptions.session))
+                : (urlOptions.assembly ?? urlOptions.hub),
             trackIds: trackIds ??
                 urlOptions.tracks ??
                 (urlOptions.session
@@ -251,8 +81,9 @@ export async function openJBrowse(options = {}) {
     }
     catch (error) {
         // A launch that got as far as a page and then failed still holds a Chrome
-        // process; without this the caller has no handle to close it.
-        await browser.close();
+        // process; without this the caller has no handle to close it. The close is
+        // guarded so its own failure cannot replace the error worth reporting.
+        await browser.close().catch(() => { });
         throw error;
     }
 }
@@ -262,9 +93,24 @@ export async function openJBrowse(options = {}) {
  */
 export async function captureJBrowse(options = {}) {
     const { out, fullPage = false, ...openOptions } = options;
+    if (out) {
+        // Before the browser launches: a missing parent directory otherwise fails
+        // at the screenshot, after the whole launch-navigate-wait cycle.
+        mkdirSync(dirname(out), { recursive: true });
+    }
     const { browser, page, url, ...report } = await openJBrowse(openOptions);
     try {
-        const image = await page.screenshot({ path: out, fullPage });
+        if (fullPage) {
+            const viewport = page.viewport();
+            const pageHeight = await page.evaluate(() => Math.ceil(Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)));
+            if (viewport && pageHeight > viewport.height) {
+                await page.setViewport({ ...viewport, height: pageHeight });
+                // The resize invalidates the raster and can start work (a display that
+                // grew gained rows to draw), so the frame has to settle again.
+                await waitForAppSettled(page, { timeout: openOptions.timeout });
+            }
+        }
+        const image = await page.screenshot({ path: out });
         return { url, image, ...report };
     }
     finally {

package/esm/index.d.ts

@@ -1,10 +1,12 @@
-export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.ts';
-export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.ts';
+export { captureJBrowse, openJBrowse } from './capture.ts';
+export { waitForJBrowseReady } from './ready.ts';
+export { APP_CENSUS, 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 { CaptureOptions, CaptureResult, OpenOptions, OpenResult, } from './capture.ts';
+export type { ReadyOptions, ReadyReport } from './ready.ts';
 export type { Instrumentation, PendingDisplay, SessionExpectations, SessionSummary, } from './sessionGate.ts';
 export type { JBrowseUrlOptions } from './url.ts';

package/esm/index.js

@@ -1,5 +1,6 @@
-export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.js';
-export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
+export { captureJBrowse, openJBrowse } from './capture.js';
+export { waitForJBrowseReady } from './ready.js';
+export { APP_CENSUS, 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';

package/esm/ready.d.ts

@@ -0,0 +1,71 @@
+import type { Instrumentation, PendingDisplay, SessionExpectations } from './sessionGate.ts';
+import type { Page } from 'puppeteer';
+export interface ReadyOptions extends SessionExpectations {
+    /** Budget for each individual wait stage. */
+    timeout?: number;
+    /**
+     * Also wait out the app's own busy reports — adapter "Downloading…" status
+     * text, which can outlive the loading overlay when a track streams a large
+     * remote file, and any "Loading…/Rendering…" label still on screen. One
+     * predicate answers both. Only consulted on a build without the app-ready
+     * marker; the marker's `ready` already means no display is fetching.
+     */
+    waitForDownloads?: boolean;
+    /** Extra settle after everything reports done, for animations and tooltips. */
+    settleMs?: number;
+    /**
+     * Skip the session gate. Only for a page that is not jbrowse-web and so
+     * publishes no `window.JBrowseSession` — an embedded component, say. You lose
+     * the only check that the data you asked for is the data on screen, and the
+     * marker and instrumentation reads then race the boot, so the chain leans on
+     * the seen-busy-then-quiet gate instead of the attributes.
+     */
+    expectSession?: boolean;
+    /**
+     * Return the report instead of throwing when a wait stage times out. For
+     * capturing a page that is deliberately mid-load, or accepting a known-slow
+     * one. The unsettled stages are still listed in the report either way.
+     */
+    allowUnsettled?: boolean;
+}
+export interface ReadyReport {
+    /** Displays still reporting unpainted at the end of the wait. */
+    pending: string[];
+    /**
+     * The same displays with the phase each one publishes, which is what
+     * separates a slow fetch from a display that says it finished without
+     * painting. Empty whenever `pending` is.
+     */
+    pendingStates: PendingDisplay[];
+    /**
+     * Whether every display's paint state was actually measurable — false when
+     * tracks are open but the build publishes no `data-display-drawn`. With this
+     * false, an empty `pending` means "cannot tell", not "all done".
+     */
+    paintContract: boolean;
+    /** Wait stages that hit their timeout instead of being satisfied. */
+    unsettled: string[];
+    /**
+     * Which readiness attributes the build published, read once the session was
+     * up. Every `false` here is a wait that could not fail rather than one that
+     * passed, and the chain compensates for it — see LEGACY_QUIET_MS.
+     */
+    instrumentation: Instrumentation;
+    /**
+     * Whether the page published `[data-app-phase]`, the one positive readiness
+     * selector. True means the wait was that selector and nothing else; false
+     * means the build predates it and the fallback chain ran.
+     */
+    appMarker: boolean;
+}
+/**
+ * Wait until a JBrowse page has finished loading AND finished drawing.
+ *
+ * One positive gate, then the negative ones. The order is the whole point: the
+ * DOM waits all pass on a page that has not started yet, so without the session
+ * gate in front the chain returns in under a second (see sessionGate.ts). After
+ * it, each stage is only meaningful once the previous has passed — a view still
+ * resolving its assembly has mounted no displays, and a display that has mounted
+ * but not fetched has nothing to be drawn yet.
+ */
+export declare function waitForJBrowseReady(page: Page, { timeout, waitForDownloads, settleMs, expectSession, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;

package/esm/ready.js

@@ -0,0 +1,190 @@
+import { describePendingDisplays, hasPaintContract, pendingDisplayStates, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
+import { delay, hasAppReadyMarker, waitForAppReady, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForViewPhases, } from './waits.js';
+// The whole ready chain, in a module that touches puppeteer only through its
+// types — capture.ts holds the runtime import (launching a browser), which is
+// what keeps the chain callable under jest against a stubbed Page.
+// A build with no per-display paint attributes gives no signal between "the
+// overlay cleared" and "the canvas has pixels on it", so the only thing left is
+// to wait. Sized from the measured gap on jbrowse.org/code/jb2/latest between
+// the overlay clearing and the tracks being fully drawn.
+const LEGACY_PAINT_SETTLE_MS = 1500;
+// ...and the gap at the OTHER end, which is the one that lands a capture on an
+// app that has drawn nothing at all. Measured on the same instance with two
+// remote tracks: the session gate is satisfied at ~2.5s, and the loading overlay
+// — the only remaining signal there — does not go up until ~3.5s. An
+// instrumented build has no such window: `data-display-phase` appears in the
+// same frame as the display it belongs to.
+//
+// So on an uninstrumented build the app has to be seen to START working, and
+// then hold still, before it counts as finished. The window is how long the
+// first indicator gets to appear before "nothing to wait for" is the better
+// reading; the quiet is how long the idle then has to hold.
+const LEGACY_BUSY_WINDOW_MS = 4000;
+const LEGACY_QUIET_MS = 2000;
+/**
+ * Wait until a JBrowse page has finished loading AND finished drawing.
+ *
+ * One positive gate, then the negative ones. The order is the whole point: the
+ * DOM waits all pass on a page that has not started yet, so without the session
+ * gate in front the chain returns in under a second (see sessionGate.ts). After
+ * it, each stage is only meaningful once the previous has passed — a view still
+ * resolving its assembly has mounted no displays, and a display that has mounted
+ * but not fetched has nothing to be drawn yet.
+ */
+export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownloads = true, settleMs = 0, expectSession = true, assembly, trackIds, allowUnsettled = false, } = {}) {
+    const unsettled = [];
+    const stage = async (name, work) => {
+        if (!(await work)) {
+            unsettled.push(name);
+        }
+    };
+    // The two hard waits reject with puppeteer's own `Waiting failed: Nms
+    // exceeded`, which names neither the stage nor the selector — the whole
+    // failure mode this module exists to avoid, arriving as an error message
+    // instead of as a blank image. Say which gate it was and what to do.
+    const required = async (name, work) => {
+        try {
+            return await work;
+        }
+        catch {
+            throw new Error(`gave up waiting after ${timeout}ms: ${name}. Raise the timeout if the ` +
+                'page is merely slow; if it never finishes, open the same URL in a ' +
+                'browser — this gate has no content to fall through to.');
+        }
+    };
+    // 0. the session exists and holds what was asked for. Positive, and throws.
+    if (expectSession) {
+        await waitForSession(page, { assembly, trackIds, timeout });
+    }
+    // 1. THE WHOLE ANSWER, on any build that has it: the session renders
+    //    `[data-app-phase="ready"]` when no view is resolving an assembly and no
+    //    display is fetching. It is positive, so unlike everything below it
+    //    cannot be satisfied by an app that has not started, and there is nothing
+    //    to assemble — wait for the selector and stop.
+    //
+    //    Everything after this point is the fallback for a deployment older than
+    //    the marker, and can be deleted the day the oldest supported build has
+    //    it.
+    if (await hasAppReadyMarker(page)) {
+        const ready = await waitForAppReady(page, { timeout });
+        if (!ready) {
+            unsettled.push('the app never reported itself ready');
+        }
+        // One thing the marker does not answer, so this stage stays even here: the
+        // marker is about WORK, and a display whose fetch failed is not working. It
+        // reads `ready` over an error banner, which is a correct answer to a
+        // different question than a capture is asking. `data-display-drawn` is the
+        // stricter gate — the two comparative canvases publish it from `settled`,
+        // which holds an error open deliberately so a golden regenerated during an
+        // outage fails here instead of absorbing the banner as expected output.
+        // Ordered after the marker rather than instead of it, which is what makes an
+        // absence meaningful (see waitForDisplaysDone), and free on a page that has
+        // no such canvas. Skipped when the marker itself timed out: the paint wait
+        // would spend a second full timeout on a page already known unsettled, and
+        // the census below reports the unpainted displays either way.
+        if (ready) {
+            await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
+        }
+        if (settleMs > 0) {
+            await delay(settleMs);
+        }
+        const pendingStates = await pendingDisplayStates(page);
+        const report = {
+            pending: pendingStates.map(d => d.name),
+            pendingStates,
+            paintContract: await hasPaintContract(page),
+            unsettled,
+            instrumentation: await readInstrumentation(page),
+            appMarker: true,
+        };
+        if (!allowUnsettled && unsettled.length > 0) {
+            throw new Error(unsettledMessage(timeout, unsettled, pendingStates));
+        }
+        return report;
+    }
+    // 1b. what an older build can be asked instead. On one that publishes none of
+    //     these, the stages below are not gates at all: they are assertions about
+    //     absent attributes that no page can fail.
+    const instrumentation = await readInstrumentation(page);
+    const instrumented = instrumentation.displayPhase || instrumentation.displayDrawn;
+    // A page with no tracks open has nothing to load, so the quiet gate below
+    // would be a fixed sleep for an import form or a menu shot. No summary at all
+    // — expectSession: false, where these reads race the boot — is the opposite
+    // case: nothing has been ruled out, and reading "unknown" as "no tracks" here
+    // is what let the whole chain pass over an app that had not started, since
+    // every stage below the gate is an absence an empty page satisfies.
+    const summary = await readSessionSummary(page);
+    const needsQuietGate = !instrumented && (summary === undefined || summary.trackIds.length > 0);
+    // 2. the view has an assembly and its React component has arrived. Also not
+    //    best-effort: a view stuck here has no content to fall through to.
+    await required('a view never left its loading phase (still resolving its assembly, or its ' +
+        'lazily-imported component never arrived)', waitForViewPhases(page, timeout));
+    // 3. no track is still fetching: an overlay that never clears is a fetch
+    //    that never finished, with nothing behind it, so this one throws too.
+    await required('the loading overlay never cleared (a track fetch never finished)', waitForLoadingComplete(page, { timeout }));
+    await stage('a display was still in its loading phase', waitForDisplayPhases(page, timeout));
+    // 4. no display is still pending its first paint
+    await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
+    // 5. nothing still reports itself busy: adapter "Downloading…" status on the
+    //    session model, which can outlive the overlay, and the visible
+    //    "Loading…/Rendering…" labels of the views that publish no phase
+    //    attribute. One predicate answers both, so it is one stage — it used to
+    //    run twice, once as waitForLoadingComplete's download half and once
+    //    under its own name, and a slow page paid the same timeout for each.
+    if (waitForDownloads) {
+        await stage('a track was still downloading, or a "Loading…/Rendering…" label was ' +
+            'still on screen', waitForQuiescent(page, { timeout }));
+    }
+    // 6. and on a build that answered none of the above, the one gate that does
+    //    not depend on an attribute existing: the app has to hold still. Every
+    //    stage before this one passed the moment it was asked, so without it the
+    //    chain returns while the first fetch is still being set up.
+    if (needsQuietGate) {
+        await stage('the app never went quiet for ' +
+            `${LEGACY_QUIET_MS}ms (this build publishes no readiness attributes, ` +
+            'so being seen to work and then stop is the only finished signal there ' +
+            'is)', waitForQuietPeriod(page, {
+            quietMs: LEGACY_QUIET_MS,
+            busyWindowMs: LEGACY_BUSY_WINDOW_MS,
+            timeout,
+        }));
+    }
+    const paintContract = await hasPaintContract(page);
+    if (!paintContract) {
+        await delay(LEGACY_PAINT_SETTLE_MS);
+    }
+    if (settleMs > 0) {
+        await delay(settleMs);
+    }
+    const pendingStates = await pendingDisplayStates(page);
+    const report = {
+        pending: pendingStates.map(d => d.name),
+        pendingStates,
+        paintContract,
+        unsettled,
+        instrumentation,
+        appMarker: false,
+    };
+    if (!allowUnsettled && unsettled.length > 0) {
+        // Throwing is the point. Each of these stages swallows its own timeout so a
+        // slow page is not failed for being slow, which historically meant the run
+        // ended with an image and an exit code of 0 whether it had settled or not.
+        // A caller that genuinely wants the frame anyway asks for it by name.
+        throw new Error(unsettledMessage(timeout, unsettled, pendingStates));
+    }
+    return report;
+}
+/**
+ * What a timed-out wait says. The stage names alone were the whole message, and
+ * they name the QUESTION rather than the answer — "a display never reported its
+ * first paint" reads identically for a slow fetch, a failed one and a display
+ * that never had a canvas to paint. Appending the census answers it, and the
+ * `ready` case is the one that most changes what a reader does next: a longer
+ * timeout is the fix for `loading` and never the fix for that.
+ */
+function unsettledMessage(timeout, unsettled, pending) {
+    return (`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ${pending.length > 0
+        ? `Still unpainted: ${describePendingDisplays(pending)}. `
+        : ''}Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ` +
+        `capture the frame as it stands.`);
+}

package/esm/session.js

@@ -43,13 +43,17 @@ export function assemblyFromSession(session) {
  * caller has not spelled those ids out separately.
  */
 export function trackIdsFromSession(session) {
+    // 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
+    const idsOf = (tracks) => (tracks ?? [])
+        .map(t => (typeof t === 'string' ? t : t.trackId))
+        .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),
+        // a nested entry is a synteny spec's per-level list; these used to be
+        // filtered out as malformed, so a synteny --session gated on nothing
+        ...(view.tracks ?? []).flatMap(t => Array.isArray(t) ? idsOf(t) : idsOf([t])),
+        ...(view.levels ?? []).flatMap(l => idsOf(l.tracks)),
         ...collect(view.views),
     ]);
     return collect(session.views);

package/esm/sessionGate.d.ts

@@ -10,6 +10,18 @@ export interface SessionExpectations {
      */
     trackIds?: string[];
 }
+/**
+ * The census the app publishes beside its phase: `AppReadyMarker` renders
+ * `data-app-views` (a count), and `data-app-assemblies` / `data-app-tracks`
+ * (JSON string arrays of what is open). On a build that has it, the session
+ * gate and the summary are a read of ONE element — no walk of the session
+ * model, so nothing here has to know which property a container view keeps its
+ * children on. The session walk below each census read is the fallback for a
+ * deployed build older than the census, and goes when the legacy chain does.
+ * `scripts/readinessContract.test.ts` pins the attribute names against the
+ * marker, since neither package may import the other.
+ */
+export declare const APP_CENSUS = "[data-app-tracks]";
 export interface SessionSummary {
     views: number;
     assemblies: string[];

package/esm/sessionGate.js

@@ -1,3 +1,21 @@
+// `window.JBrowseSession` is jbrowse-web's own devtools/automation handle
+// (products/jbrowse-web/src/components/JBrowse.tsx). It is declared `unknown`
+// there and is a live MST node here, so a cast at the page boundary is
+// unavoidable. It is repeated in each function below rather than shared: every
+// one of them is serialized into the page by puppeteer, so it can only call what
+// it declares inside itself.
+/**
+ * The census the app publishes beside its phase: `AppReadyMarker` renders
+ * `data-app-views` (a count), and `data-app-assemblies` / `data-app-tracks`
+ * (JSON string arrays of what is open). On a build that has it, the session
+ * gate and the summary are a read of ONE element — no walk of the session
+ * model, so nothing here has to know which property a container view keeps its
+ * children on. The session walk below each census read is the fallback for a
+ * deployed build older than the census, and goes when the legacy chain does.
+ * `scripts/readinessContract.test.ts` pins the attribute names against the
+ * marker, since neither package may import the other.
+ */
+export const APP_CENSUS = '[data-app-tracks]';
 /** What the page currently has open, or undefined if there is no session yet. */
 export function readSessionSummary(page) {
     return page.evaluate(readSessionSummaryInPage);
@@ -9,6 +27,20 @@ export function readSessionSummary(page) {
 // so calling it in node against a stubbed global exercises the very function
 // puppeteer serializes, rather than a copy of it that can drift.
 export function readSessionSummaryInPage() {
+    // census first: one element, no walk (see APP_CENSUS)
+    const marker = document.querySelector('[data-app-tracks]');
+    if (marker) {
+        try {
+            return {
+                views: Number(marker.dataset.appViews) || 0,
+                assemblies: JSON.parse(marker.dataset.appAssemblies ?? '[]'),
+                trackIds: JSON.parse(marker.dataset.appTracks ?? '[]'),
+            };
+        }
+        catch {
+            // a malformed census falls through to the walk rather than failing the read
+        }
+    }
     const session = globalThis.JBrowseSession;
     const views = session?.views;
     if (!views) {
@@ -19,7 +51,7 @@ export function readSessionSummaryInPage() {
     function collect(v) {
         return [
             ...(v.tracks ?? []),
-            ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
+            ...(v.trackContainers ?? v.levels ?? []).flatMap(l => l.tracks ?? []),
             ...(v.views ?? []).flatMap(collect),
         ];
     }
@@ -47,6 +79,24 @@ export async function waitForSession(page, { assembly, trackIds = [], timeout =
     try {
         // #region session-gate
         await page.waitForFunction((wantAssembly, wantTracks) => {
+            // The census the app publishes on its ready marker (see APP_CENSUS):
+            // on a build that has it, the whole gate is a read of one element.
+            const marker = document.querySelector('[data-app-tracks]');
+            if (marker) {
+                try {
+                    const openViews = Number(marker.dataset.appViews);
+                    const assemblies = JSON.parse(marker.dataset.appAssemblies ?? '[]');
+                    const openTracks = JSON.parse(marker.dataset.appTracks ?? '[]');
+                    return (openViews > 0 &&
+                        (wantAssembly === null || assemblies.includes(wantAssembly)) &&
+                        wantTracks.every(id => openTracks.includes(id)));
+                }
+                catch {
+                    return false;
+                }
+            }
+            // No census: a deployed build older than the marker's attributes, so
+            // walk the session model it publishes instead.
             const session = globalThis.JBrowseSession;
             const views = session?.views;
             if (!views?.length) {
@@ -71,7 +121,7 @@ export async function waitForSession(page, { assembly, trackIds = [], timeout =
             }
             const tracksOf = (v) => [
                 ...(v.tracks ?? []),
-                ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
+                ...(v.trackContainers ?? v.levels ?? []).flatMap(l => l.tracks ?? []),
                 ...(v.views ?? []).flatMap(tracksOf),
             ];
             const open = new Set(views.flatMap(v => tracksOf(v).map(t => t.configuration?.trackId)));
@@ -80,7 +130,10 @@ export async function waitForSession(page, { assembly, trackIds = [], timeout =
         // #endregion session-gate
     }
     catch {
-        const summary = await readSessionSummary(page);
+        // Best-effort: the wait may have failed because the page crashed or
+        // navigated, and an unguarded evaluate here would replace the diagnostic
+        // below with its own opaque error.
+        const summary = await readSessionSummary(page).catch(() => undefined);
         const found = summary
             ? `${summary.views} view(s), assemblies [${summary.assemblies.join(', ')}], tracks [${summary.trackIds.join(', ')}]`
             : 'no session on the page at all (is this a jbrowse-web instance?)';
@@ -150,10 +203,8 @@ export function readInstrumentation(page) {
  * result means nothing at all on a build with no paint contract — check
  * `paintContract` before reading it as good news.
  */
-export function pendingDisplays(page) {
-    return page.evaluate(() => [
-        ...document.querySelectorAll('[data-display-drawn="false"]'),
-    ].map(el => el.dataset.testid ?? (el.id || 'unnamed display')));
+export async function pendingDisplays(page) {
+    return (await pendingDisplayStates(page)).map(d => d.name);
 }
 /**
  * The same census, with each display's own account of itself.

package/esm/waits.js

@@ -290,7 +290,7 @@ export function isPageBusyInPage() {
     const tracksOf = (c) => (c.tracks ?? []).flatMap(t => t.displays ?? []);
     const displaysOf = (v) => [
         ...tracksOf(v),
-        ...(v.trackContainers ?? []).flatMap(tracksOf),
+        ...(v.trackContainers ?? v.levels ?? []).flatMap(tracksOf),
         ...(v.views ?? []).flatMap(displaysOf),
     ];
     return (session?.views ?? [])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/capture",
-  "version": "4.3.0",
+  "version": "5.0.0-beta.2",
   "description": "Drive a JBrowse 2 instance with Puppeteer and screenshot it once it has actually finished rendering",
   "keywords": [
     "jbrowse",
@@ -34,7 +34,7 @@
     "puppeteer": "^25.9.0"
   },
   "devDependencies": {
-    "@jbrowse/core": "^4.3.0"
+    "@jbrowse/core": "^5.0.0-beta.2"
   },
   "publishConfig": {
     "access": "public"