@jbrowse/capture 5.0.0-beta.2 → 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,5 +1,6 @@
 const NUMERIC = new Set(['width', 'height', 'scale', 'timeout', 'settle']);
-const POSITIVE = new Set(['width', 'height', 'scale']);
+const POSITIVE = new Set(['width', 'height', 'scale', 'timeout']);
+const NON_NEGATIVE = new Set(['settle']);
 const FLAGS = new Set([
     'fullPage',
     'headed',
@@ -74,11 +75,15 @@ 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.
+            // 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.js

@@ -24,10 +24,6 @@ export async function openJBrowse(options = {}) {
     // 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.
-    waitForDownloads: _waitForDownloads, settleMs: _settleMs, expectSession: _expectSession, allowUnsettled: _allowUnsettled, 
     // `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

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/ready.js

@@ -1,5 +1,5 @@
 import { describePendingDisplays, hasPaintContract, pendingDisplayStates, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
-import { delay, hasAppReadyMarker, waitForAppReady, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForViewPhases, } from './waits.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.
@@ -38,6 +38,18 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
             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
@@ -59,16 +71,20 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
     // 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.
+    //    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 waitForAppReady(page, { timeout });
+        const ready = await waitForAppSettled(page, { timeout });
         if (!ready) {
-            unsettled.push('the app never reported itself 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
@@ -76,15 +92,16 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
         // 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.
+        // 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);
         }
@@ -98,7 +115,7 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
             appMarker: true,
         };
         if (!allowUnsettled && unsettled.length > 0) {
-            throw new Error(unsettledMessage(timeout, unsettled, pendingStates));
+            throw new Error(unsettledMessage(timeout, unsettled));
         }
         return report;
     }
@@ -125,6 +142,7 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
     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
@@ -170,21 +188,20 @@ export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownlo
         // 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));
+        throw new Error(unsettledMessage(timeout, unsettled));
     }
     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.
+ * 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, 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.`);
+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/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;
     }
@@ -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.2",
+  "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.2"
+    "@jbrowse/core": "^5.0.0-beta.3"
   },
   "publishConfig": {
     "access": "public"