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

package/README.md

@@ -19,10 +19,14 @@ config, builds a session, resolves an assembly, fetches each track, and then
 draws to a canvas — and a screenshot taken at any point before the last step is
 a picture of an empty browser that looks like a successful run.
 
-Every readiness signal JBrowse publishes is **negative**: no loading overlay, no
-display in its loading phase, no unpainted canvas. All of them therefore pass on
-a page whose JavaScript has not started yet. Measured against
-`jbrowse.org/code/jb2/latest`:
+Which signals exist at all depends on the build. Checked on 2026-09-05, the
+default `--instance` — `jbrowse.org/code/jb2/latest`, the released build every
+genomes.jbrowse.org link opens — publishes the loading overlay
+(`[data-testid="loading-overlay"]`) and none of `data-app-phase`,
+`data-view-phase`, `data-display-phase`, `data-display-drawn` or `data-busy`.
+Every one of those is a **negative** signal — no overlay, no display in its
+loading phase, no unpainted canvas — so all of them pass on a page whose
+JavaScript has not started yet. Measured against that instance:
 
 - `networkidle2` resolves at ~350ms
 - the session appears at ~880ms
@@ -38,6 +42,18 @@ exists, its views are initialized, and the assembly and trackIds you asked for
 are the ones actually open. A config URL that 404s, a trackId the config does
 not define, and an assembly name that does not match all fail there, loudly.
 
+What runs after that gate depends on which build answered it:
+
+- **One that publishes `data-app-phase`** — `jbrowse.org/code/jb2/main`, or a
+  local build of this repo, reached with `--instance` — needs one selector and
+  no chain: `[data-app-phase="ready"]` appears when no view is resolving an
+  assembly and no display is fetching, and `data-display-drawn` then says paint
+  happened.
+- **Every other build, the default included**, has the overlay and the status
+  text the session model carries per display. There the app has to be _seen
+  busy, then quiet for 2s_ — an absence alone is satisfied before the first
+  fetch is even set up — then given a fixed 1.5s for the paint nothing reports.
+
 ## Library
 
 ```js
@@ -69,7 +85,9 @@ Two waits, depending on what you did:
   that is loading starts out `loading` and the transition into `ready` is it
   finishing; a page you just clicked is already `ready` and stays that way until
   the click's work registers, so waiting for `ready` there returns on the
-  pre-click frame. `waitForAppSettled` requires it to hold.
+  pre-click frame. `waitForAppSettled` requires it to hold, and on a build
+  without the marker falls back to the quiet period rather than passing
+  instantly.
 
 ## Timeouts and unsettled waits
 
@@ -93,18 +111,20 @@ still tells you what did not settle.
 
 ## Reading the result
 
-Three fields on a successful capture:
+Four fields on a successful capture:
 
 - **`unsettled`** — stages that hit their timeout. Empty unless you asked to
   proceed anyway.
+- **`appMarker`** — which of the two paths above ran. False on the default
+  instance, and on anything else that predates `data-app-phase`.
 - **`pending`** — displays still reporting unpainted when the shutter fired. A
   display can return to pending after its stage passed, so this is a separate
   question from `unsettled`.
 - **`paintContract`** — whether this JBrowse build publishes the per-display
-  paint attributes at all. It does not on the current released build, which is
-  what every genomes.jbrowse.org link opens; there, `pending: []` means "cannot
-  tell", not "all done", and the CLI says so. A page with no tracks open reports
-  true — there is nothing to measure, which is not the same as being unable to.
+  paint attributes at all. It is false on the default instance, so `pending: []`
+  there means "cannot tell", not "all done", and the CLI says so. A page with no
+  tracks open reports true — there is nothing to measure, which is not the same
+  as being unable to.
 
 ## CLI
 

package/esm/args.js

@@ -1,4 +1,6 @@
 const NUMERIC = new Set(['width', 'height', 'scale', 'timeout', 'settle']);
+const POSITIVE = new Set(['width', 'height', 'scale', 'timeout']);
+const NON_NEGATIVE = new Set(['settle']);
 const FLAGS = new Set([
     'fullPage',
     'headed',
@@ -53,6 +55,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 +75,15 @@ export function parseArgs(argv) {
             if (!Number.isFinite(n)) {
                 throw new Error(`--${name} needs a number, got "${value}"`);
             }
+            // Otherwise these fail much later and elsewhere: a zero size inside
+            // puppeteer, naming neither the flag nor the value, and `--timeout 0` as
+            // no timeout at all there while the node-polled waits read it as expired.
+            if (POSITIVE.has(name) && n <= 0) {
+                throw new Error(`--${name} needs a positive number, got "${value}"`);
+            }
+            if (NON_NEGATIVE.has(name) && n < 0) {
+                throw new Error(`--${name} needs a number of milliseconds that is zero or more, 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,11 +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, 
-    // 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.
-    waitForDownloads: _waitForDownloads, settleMs: _settleMs, expectSession: _expectSession, allowUnsettled: _allowUnsettled, 
+    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, 
     // `assembly` is deliberately NOT pulled out here: it is both a URL option
     // (which assembly to open) and the session gate's expectation (which
     // assembly must end up open), and destructuring it for the second use would
@@ -229,18 +56,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 +77,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 +89,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/hub.js

@@ -1,4 +1,5 @@
 const HUB_HOST = 'https://jbrowse.org';
+const HUB_FETCH_TIMEOUT_MS = 30000;
 // 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.
@@ -22,7 +23,19 @@ export function hubUrl(hub) {
  */
 export async function fetchHubConfig(hub) {
     const url = hubUrl(hub);
-    const res = await fetch(url);
+    // Without the signal a stalled connection hangs `jb2capture list` forever:
+    // fetch has no timeout of its own, and this is the one request the tool makes
+    // outside puppeteer's budget.
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(HUB_FETCH_TIMEOUT_MS),
+    }).catch((error) => {
+        // The budget is only part of the diagnosis when it is what fired; naming it
+        // on a DNS failure reads as though the request had been given 30s to resolve.
+        const timedOut = error instanceof Error && error.name === 'TimeoutError';
+        throw new Error(`hub "${hub}" could not be fetched from ${url} ` +
+            `(${error instanceof Error ? error.message : error}${timedOut ? `, after ${HUB_FETCH_TIMEOUT_MS}ms` : ''}). ` +
+            'See https://genomes.jbrowse.org for the available assemblies.');
+    });
     if (!res.ok) {
         throw new Error(`hub "${hub}" not found (HTTP ${res.status} from ${url}). ` +
             'See https://genomes.jbrowse.org for the available assemblies.');

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,207 @@
+import { describePendingDisplays, hasPaintContract, pendingDisplayStates, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
+import { delay, hasAppReadyMarker, waitForAppSettled, 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 post-condition of the paint stage, and on a terminal display the ONLY
+    // report of it: `waitForDisplaysDone` returns as soon as every pending display
+    // is past `loading`, so an errored canvas that will never paint no longer
+    // spends the whole timeout to arrive here. The phase is what a reader needs —
+    // `error` is a banner, `ready` is a display claiming it finished without
+    // drawing — so the entry carries the census rather than naming the question.
+    const reportUnpainted = async () => {
+        const pending = await pendingDisplayStates(page);
+        if (pending.length > 0) {
+            unsettled.push(`display(s) never painted: ${describePendingDisplays(pending)}`);
+        }
+    };
+    // 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.
+    //
+    //    Held, not read once — the same hold `jb.waitReady` requires, because a
+    //    display drops to `ready` in the gap between one fetch finishing and the
+    //    debounced next one starting. The marker is known to exist here, so
+    //    `waitForAppSettled`'s quiet-period fallback does not come into it.
+    //
+    //    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 waitForAppSettled(page, { timeout });
+        if (!ready) {
+            unsettled.push('the app never held 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 on the census below 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 reports the unpainted displays either way.
+        if (ready) {
+            await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
+        }
+        await reportUnpainted();
+        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));
+        }
+        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));
+    await reportUnpainted();
+    // 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));
+    }
+    return report;
+}
+/**
+ * What a timed-out wait says. A stage name is 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 — so
+ * `reportUnpainted` puts the census in the list beside 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) {
+    return (`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ` +
+        '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.d.ts

@@ -17,6 +17,14 @@ export declare const LOADING_OVERLAY = "[data-testid=\"loading-overlay\"]";
  * capture taken in it is a picture of an empty browser.
  */
 export declare const APP_READY = "[data-app-phase=\"ready\"]";
+/**
+ * Wait until the loading overlay is gone, and with `waitForDownloads` until
+ * nothing else reports itself busy either — a remote fetch can outlive the
+ * overlay, so a capture taken on the overlay alone catches a half-loaded track.
+ *
+ * NOT best-effort: an overlay that never clears means a fetch that never
+ * finished, and there is no content behind it to fall through to.
+ */
 export declare function waitForLoadingComplete(page: Page, { timeout, waitForDownloads, }?: {
     timeout?: number;
     waitForDownloads?: boolean;
@@ -106,15 +114,16 @@ export declare const BUSY_SELECTOR: string;
 /**
  * Is the app doing anything right now?
  *
- * Serialized into the page, so it declares everything it uses. Two sources: the
- * selector above, and the live session model's own per-display status, which is
- * the only PER-DISPLAY signal a build with no readiness attributes has left.
- * Both are contracts rather than renderings — a model field and a set of data
+ * Serialized into the page, so it declares everything it uses and takes
+ * `BUSY_SELECTOR` as an argument rather than importing it. Two sources: that
+ * selector, and the live session model's own per-display status, which is the
+ * only PER-DISPLAY signal a build with no readiness attributes has left. Both
+ * are contracts rather than renderings — a model field and a set of data
  * attributes — so neither moves when the UI is restyled.
  *
  * Exported so a test can call the real function rather than a copy of it.
  */
-export declare function isPageBusyInPage(): boolean;
+export declare function isPageBusyInPage(busySelector: string): boolean;
 /**
  * Wait until the app has been idle for an unbroken stretch.
  *
@@ -163,12 +172,16 @@ export declare function waitForQuietPeriod(page: Page, { quietMs, timeout, pollM
     busyWindowMs?: number;
 }): Promise<boolean>;
 /**
- * Wait for the app to say it has finished.
+ * Wait for the FIRST frame the app says it has finished.
+ *
+ * `[data-app-phase="ready"]` is rendered by the session itself, so it cannot be
+ * satisfied before the app exists — but one frame of it is not the answer on its
+ * own: a display reads `ready` in the gap between one fetch finishing and the
+ * debounced next one starting. `waitForAppSettled` requires it to HOLD, and is
+ * what both the chain here and `jb.waitReady` use.
  *
- * One selector, no chain: `[data-app-phase="ready"]` is rendered by the session
- * itself, so it cannot be satisfied before the app exists. Returns false if the
- * page never publishes it, which is how a caller tells "not ready yet" from "a
- * build too old to have the marker" and falls back.
+ * Returns false if the page never publishes it, which is how a caller tells "not
+ * ready yet" from "a build too old to have the marker" and falls back.
  */
 export declare function waitForAppReady(page: Page, { timeout }?: {
     timeout?: number;
@@ -178,12 +191,12 @@ export declare function hasAppReadyMarker(page: Page): Promise<boolean>;
 /**
  * Wait out work an INTERACTION started: `ready`, and still ready a beat later.
  *
- * The gate for after a click, a keystroke or a resize, where `waitForAppReady`
- * alone is not one. A page that is still LOADING starts at `loading` and the
- * transition into `ready` is the app finishing, so one read of the selector
- * answers it. After an interaction the app is already `ready` — it was finished a
- * moment ago — and stays that way until the click's work registers, so the same
- * read returns instantly, on the pre-click frame.
+ * The gate wherever `waitForAppReady` alone is not one, which is everywhere the
+ * app is working. After an interaction the app is already `ready` — it was
+ * finished a moment ago — and stays that way until the click's work registers,
+ * so a single read returns instantly, on the pre-click frame; during a load it
+ * reads `ready` in the gap between one fetch finishing and the debounced next
+ * one starting, and a single read takes that gap for the end.
  *
  * What it replaces is a fixed sleep, which is wrong in both directions and only
  * ever caught in one: too short captures the work in progress, and the figure it

package/esm/waits.js

@@ -4,12 +4,6 @@ import { describePendingDisplays, pendingDisplayStatesInPage, } from './sessionG
 export const delay = (ms) => new Promise(resolve => {
     setTimeout(resolve, ms);
 });
-// Wait until the LoadingOverlay test-id is gone. NOTE: the overlay keeps the
-// literal text "Loading" in the DOM (hidden via opacity), so a text-based wait
-// burns its full timeout — only the `loading-overlay` test-id count is a
-// reliable signal. With `waitForDownloads`, also wait out adapter "Downloading…"
-// status text, which can linger after the overlay clears (e.g. a remote BAM
-// still fetching) so a capture doesn't catch a half-loaded track.
 // Every best-effort wait below runs through this. They swallow their own timeout
 // on purpose — a slow-but-finishing page should not be failed for being slow,
 // and a display in a terminal state publishes no attribute to wait on at all —
@@ -52,17 +46,16 @@ export const APP_READY = '[data-app-phase="ready"]';
  * in the gap reports the pre-click frame as finished.
  */
 const APP_SETTLED_HOLD_MS = 1000;
+/**
+ * Wait until the loading overlay is gone, and with `waitForDownloads` until
+ * nothing else reports itself busy either — a remote fetch can outlive the
+ * overlay, so a capture taken on the overlay alone catches a half-loaded track.
+ *
+ * NOT best-effort: an overlay that never clears means a fetch that never
+ * finished, and there is no content behind it to fall through to.
+ */
 export async function waitForLoadingComplete(page, { timeout = 30000, waitForDownloads = false, } = {}) {
-    // NOT best-effort: an overlay that never clears means a fetch that never
-    // finished, and there is no content behind it to fall through to.
-    await page.waitForFunction((selector) => document.querySelectorAll(selector).length === 0, { timeout }, LOADING_OVERLAY);
-    // The download half asks the app what it is doing, through the attributes it
-    // publishes and each display's own status on the session model. It used to be
-    // `document.body.innerText.includes('Downloading')`, a string search over the
-    // whole rendered page: it matched a track NAMED "Downloading…", it matched
-    // documentation text, and it stopped matching the moment a message was
-    // reworded or translated.
-    //
+    await page.waitForFunction((selector) => document.querySelectorAll(selector).length === 0, { timeout, polling: 'mutation' }, LOADING_OVERLAY);
     // `quietMs: 0` because this is the "nothing is in flight right now" question;
     // the one that needs the idle to hold is waitForQuietPeriod's own caller.
     return waitForDownloads
@@ -185,22 +178,27 @@ export const displayPainted = (testid) => `[data-testid="${testid}"][data-displa
 export const displaySettled = (testid) => `[data-testid="${testid}"][data-display-phase="ready"]`;
 /** One display, by its config's `displayId` rather than by type. */
 export const displayById = (displayId) => `[data-display-id="${displayId}"]`;
-// Wait until no display wrapper is still pending its first paint, or until the
-// timeout elapses (proceed anyway — a display stuck in its too-large/error state
-// renders no wrapper at all and never reports done).
+// Wait until no display is still pending its first paint AND could still reach
+// it: a pending display publishing `loading`, or publishing no phase at all (a
+// build older than the attribute), is still coming; a terminal phase is not. The
+// two comparative canvases hold `drawn=false` open through `error` deliberately,
+// so waiting on the attribute alone burns the whole timeout over an answer the
+// census already has — waitForJBrowseReady takes that census straight after and
+// reports whatever is left as unsettled.
 //
 // Keying on the *absence* of pending wrappers rather than counting done-vs-total
-// matters twice over. A page with no canvas displays — an import form, a menu or
-// widget figure — resolves immediately instead of burning the full timeout as a
-// hidden fixed sleep. And a page whose displays finish at different times waits
-// for the last one; the previous "any element ends in -done" fallback returned as
-// soon as the *first* of several tracks painted.
+// is what lets a page with no canvas displays — an import form, a menu or widget
+// figure — resolve immediately instead of paying the full timeout as a hidden
+// fixed sleep, and what makes a page whose displays finish at different times
+// wait for the last one; the previous "any element ends in -done" fallback
+// returned as soon as the *first* of several tracks painted.
 //
 // Absence is only meaningful once the views have mounted (a track's display
 // wrapper mounts with its TrackRenderingContainer), so call this after the
 // readySelector / loading-overlay gates, not straight off a navigation.
 export function waitForDisplaysDone(page, timeoutMs) {
-    return settled(page.waitForFunction((selector) => document.querySelector(selector) === null, { timeout: timeoutMs }, PENDING_DISPLAYS));
+    return settled(page.waitForFunction((selector) => [...document.querySelectorAll(selector)].every(el => el.dataset.displayPhase !== undefined &&
+        el.dataset.displayPhase !== 'loading'), { timeout: timeoutMs, polling: 'mutation' }, PENDING_DISPLAYS));
 }
 // Wait until no display is in its `loading` phase.
 //
@@ -221,7 +219,7 @@ export function waitForDisplaysDone(page, timeoutMs) {
 // fail loudly through that settled check, with the frame to look at, rather than
 // as an opaque timeout here.
 export function waitForDisplayPhases(page, timeoutMs) {
-    return settled(page.waitForFunction(() => document.querySelector('[data-display-phase="loading"]') === null, { timeout: timeoutMs }));
+    return settled(page.waitForFunction(() => document.querySelector('[data-display-phase="loading"]') === null, { timeout: timeoutMs, polling: 'mutation' }));
 }
 // The view-level counterpart: ViewContainer publishes `data-view-phase` from the
 // view model's own phase, and `loading` means the view is still waiting on its
@@ -242,7 +240,7 @@ export function waitForDisplayPhases(page, timeoutMs) {
 // should surface it.
 export function waitForViewPhases(page, timeoutMs) {
     return page.waitForFunction(() => document.querySelector('[data-view-phase="loading"]') === null &&
-        document.querySelector('[data-view-component-pending]') === null, { timeout: timeoutMs, polling: 500 });
+        document.querySelector('[data-view-component-pending]') === null, { timeout: timeoutMs, polling: 'mutation' });
 }
 /**
  * Everything the app publishes to say it is working, as one selector.
@@ -267,21 +265,16 @@ export const BUSY_SELECTOR = [
 /**
  * Is the app doing anything right now?
  *
- * Serialized into the page, so it declares everything it uses. Two sources: the
- * selector above, and the live session model's own per-display status, which is
- * the only PER-DISPLAY signal a build with no readiness attributes has left.
- * Both are contracts rather than renderings — a model field and a set of data
+ * Serialized into the page, so it declares everything it uses and takes
+ * `BUSY_SELECTOR` as an argument rather than importing it. Two sources: that
+ * selector, and the live session model's own per-display status, which is the
+ * only PER-DISPLAY signal a build with no readiness attributes has left. Both
+ * are contracts rather than renderings — a model field and a set of data
  * attributes — so neither moves when the UI is restyled.
  *
  * Exported so a test can call the real function rather than a copy of it.
  */
-export function isPageBusyInPage() {
-    const busySelector = [
-        '[data-testid="loading-overlay"]',
-        '[data-busy="true"]',
-        '[data-display-phase="loading"]',
-        '[data-view-phase="loading"]',
-    ].join(', ');
+export function isPageBusyInPage(busySelector) {
     if (document.querySelector(busySelector)) {
         return true;
     }
@@ -290,7 +283,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 ?? [])
@@ -330,7 +323,9 @@ export async function waitForQuietPeriod(page, { quietMs = 1500, timeout = 30000
     while (Date.now() < deadline) {
         // A page that navigates or closes under us fails the evaluate; treat that
         // as busy and let the deadline decide, rather than reporting quiet.
-        const busy = await page.evaluate(isPageBusyInPage).catch(() => true);
+        const busy = await page
+            .evaluate(isPageBusyInPage, BUSY_SELECTOR)
+            .catch(() => true);
         const now = Date.now();
         if (busy) {
             seenBusy = true;
@@ -338,9 +333,11 @@ export async function waitForQuietPeriod(page, { quietMs = 1500, timeout = 30000
         }
         else {
             if (!seenBusy && now - start >= busyWindowMs) {
-                // never went busy within the window: nothing to wait out
+                // Never went busy within the window: nothing to wait out, and the idle
+                // that already ran the length of the window counts towards the hold —
+                // every sample in it was idle, since a failed evaluate reads as busy.
                 seenBusy = true;
-                quietSince = now;
+                quietSince = start;
             }
             if (seenBusy) {
                 quietSince ??= now;
@@ -354,12 +351,16 @@ export async function waitForQuietPeriod(page, { quietMs = 1500, timeout = 30000
     return false;
 }
 /**
- * Wait for the app to say it has finished.
+ * Wait for the FIRST frame the app says it has finished.
+ *
+ * `[data-app-phase="ready"]` is rendered by the session itself, so it cannot be
+ * satisfied before the app exists — but one frame of it is not the answer on its
+ * own: a display reads `ready` in the gap between one fetch finishing and the
+ * debounced next one starting. `waitForAppSettled` requires it to HOLD, and is
+ * what both the chain here and `jb.waitReady` use.
  *
- * One selector, no chain: `[data-app-phase="ready"]` is rendered by the session
- * itself, so it cannot be satisfied before the app exists. Returns false if the
- * page never publishes it, which is how a caller tells "not ready yet" from "a
- * build too old to have the marker" and falls back.
+ * Returns false if the page never publishes it, which is how a caller tells "not
+ * ready yet" from "a build too old to have the marker" and falls back.
  */
 export function waitForAppReady(page, { timeout = 30000 } = {}) {
     return settled(page.waitForSelector(APP_READY, { timeout, visible: false }));
@@ -371,12 +372,12 @@ export function hasAppReadyMarker(page) {
 /**
  * Wait out work an INTERACTION started: `ready`, and still ready a beat later.
  *
- * The gate for after a click, a keystroke or a resize, where `waitForAppReady`
- * alone is not one. A page that is still LOADING starts at `loading` and the
- * transition into `ready` is the app finishing, so one read of the selector
- * answers it. After an interaction the app is already `ready` — it was finished a
- * moment ago — and stays that way until the click's work registers, so the same
- * read returns instantly, on the pre-click frame.
+ * The gate wherever `waitForAppReady` alone is not one, which is everywhere the
+ * app is working. After an interaction the app is already `ready` — it was
+ * finished a moment ago — and stays that way until the click's work registers,
+ * so a single read returns instantly, on the pre-click frame; during a load it
+ * reads `ready` in the gap between one fetch finishing and the debounced next
+ * one starting, and a single read takes that gap for the end.
  *
  * What it replaces is a fixed sleep, which is wrong in both directions and only
  * ever caught in one: too short captures the work in progress, and the figure it

package/package.json

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