@jbrowse/capture 5.0.0-beta.4 → 5.0.0-beta.7

package/esm/ready.js

@@ -1,207 +1,73 @@
-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;
+import { describePendingDisplays, pendingDisplayStates, waitForSession, } from './sessionGate.js';
+import { delay, hasAppReadyMarker, waitForAppSettled, waitForDisplaysDone, } from './waits.js';
 /**
  * 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.
+ * Two gates, both positive, which is the property that matters — every other
+ * readiness signal the app publishes is an ABSENCE, and an absence is equally
+ * true of an app that has not started.
+ *
+ * 1. The census says the assembly and trackIds you asked for are open.
+ * 2. `[data-app-phase="ready"]` HOLDS: no view is resolving an assembly and no
+ *    display is fetching, and still not a beat later. A display drops to
+ *    `ready` in the gap between one fetch finishing and the debounced next one
+ *    starting, so a single read takes that gap for the end.
+ *
+ * Then one negative gate that is only meaningful after them, and answers the
+ * question the marker does not: the marker is about WORK, and a display whose
+ * fetch failed is not working — it reads `ready` over an error banner.
+ * `data-display-drawn` is the stricter gate.
  */
-export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownloads = true, settleMs = 0, expectSession = true, assembly, trackIds, allowUnsettled = false, } = {}) {
+export async function waitForJBrowseReady(page, { timeout = 60000, settleMs = 0, 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 });
+    await waitForSession(page, { assembly, trackIds, timeout });
+    // 1. and the build publishes the marker at all. Said out loud rather than
+    //    worked around: a chain built from the remaining signals is satisfied by
+    //    a page that has not started, so the fallback that used to run here
+    //    reported success on an empty browser unless it was also given a
+    //    seen-busy-then-quiet gate to compensate. One positive selector replaces
+    //    all of it, and a build too old to have it needs a newer --instance, not
+    //    a wait chain that cannot fail.
+    if (!(await hasAppReadyMarker(page))) {
+        throw new Error('this page publishes no [data-app-phase], so there is no positive signal ' +
+            'that it has finished — every other readiness attribute is an absence ' +
+            'an app that has not started also satisfies. Point --instance at a ' +
+            'JBrowse build that publishes it.');
     }
-    // 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 }));
+    const ready = await waitForAppSettled(page, { timeout });
+    if (!ready) {
+        unsettled.push('the app never held itself ready');
     }
-    // 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);
+    // 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. Free on a page with no canvas.
+    if (ready) {
+        const drawn = await waitForDisplaysDone(page, timeout);
+        if (!drawn) {
+            unsettled.push('a display never reported its first paint');
+        }
     }
     if (settleMs > 0) {
         await delay(settleMs);
     }
+    // The shutter-time census, taken ONCE and after the settle, so the throw and
+    // the report it ships with agree. Taken before it they did not: a display
+    // that painted during `settleMs` was absent from `pending` and still failed
+    // the run, while the CLI's own warning recommended raising `--settle` to fix
+    // exactly that.
     const pendingStates = await pendingDisplayStates(page);
-    const report = {
-        pending: pendingStates.map(d => d.name),
-        pendingStates,
-        paintContract,
-        unsettled,
-        instrumentation,
-        appMarker: false,
-    };
+    if (pendingStates.length > 0) {
+        unsettled.push(`display(s) never painted: ${describePendingDisplays(pendingStates)}`);
+    }
     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));
+        // Throwing is the point. Each stage 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(`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ` +
+            'Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ' +
+            'capture the frame as it stands.');
     }
-    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.');
+    return { pending: pendingStates.map(d => d.name), pendingStates, unsettled };
 }

package/esm/session.js

@@ -58,8 +58,18 @@ export function trackIdsFromSession(session) {
     ]);
     return collect(session.views);
 }
-// Full `?config=…&session=…&sessionName=…` query string. `config` is inserted
-// as-is (callers that point at a remote absolute URL pre-encode it themselves).
+// Full `?config=…&session=…&sessionName=…` query string, for a caller that has
+// an origin but no JBrowse instance URL to hand `jbrowseUrl`.
+//
+// Built with URLSearchParams, the same encoder and the same rule as
+// `jbrowseUrl`: hand it the DECODED spec, because it encodes once itself. It
+// used to interpolate `config` raw and ask callers to pre-encode it, which none
+// of them did — harmless only for as long as no config URL contained a `?` or
+// an `&`, at which point the link loads a truncated config and reports nothing.
 export function sessionSpecQuery({ config, session, sessionName = 'Screenshot', }) {
-    return `?config=${config}&session=${encodeSessionSpec(session)}&sessionName=${encodeURIComponent(sessionName)}`;
+    return `?${new URLSearchParams({
+        config,
+        session: sessionSpecParam(session),
+        sessionName,
+    })}`;
 }

package/esm/sessionGate.d.ts

@@ -13,11 +13,15 @@ export interface SessionExpectations {
 /**
  * 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.
+ * (JSON string arrays of what is open).
+ *
+ * One element answers the whole gate. Each view declares what it holds and
+ * `openViews`/`openTracks` reduce over those declarations (ADR-103), so nothing
+ * here has to know that a synteny view keeps its tracks on levels and its rows
+ * on sub-views — the duck-typed walk of `window.JBrowseSession` that used to
+ * live here, and drifted against the copy in `isPageBusyInPage`, is gone with
+ * the builds that needed it.
+ *
  * `scripts/readinessContract.test.ts` pins the attribute names against the
  * marker, since neither package may import the other.
  */
@@ -27,12 +31,12 @@ export interface SessionSummary {
     assemblies: string[];
     trackIds: string[];
 }
-/** What the page currently has open, or undefined if there is no session yet. */
+/** What the page currently has open, or undefined if there is no census yet. */
 export declare function readSessionSummary(page: Page): Promise<SessionSummary | undefined>;
 export declare function readSessionSummaryInPage(): SessionSummary | undefined;
 /**
- * Wait until the session exists, every view reports itself initialized, and the
- * assembly and tracks that were asked for are actually open.
+ * Wait until the census exists and the assembly and tracks that were asked for
+ * are actually open.
  *
  * Throws on timeout rather than proceeding. A config URL that 404s, a trackId
  * that does not exist in the config, and an assembly name that does not match
@@ -43,58 +47,11 @@ export declare function readSessionSummaryInPage(): SessionSummary | undefined;
 export declare function waitForSession(page: Page, { assembly, trackIds, timeout, }?: SessionExpectations & {
     timeout?: number;
 }): Promise<void>;
-export declare const PAINT_CONTRACT_NOTE: string;
-/**
- * Whether every open display's paint state was actually measurable.
- *
- * The per-display paint attributes are not universal. Measured on 2026-08-07:
- * jbrowse.org/code/jb2/main publishes `data-view-phase`, `data-display-phase`
- * and `data-display-drawn`; jbrowse.org/code/jb2/latest — the released build,
- * which is what every genomes.jbrowse.org link and every docs figure link opens
- * — publishes none of them and exposes only the loading overlay. Against that
- * instance the display-level waits are unfalsifiable rather than satisfied, so a
- * caller has to be told which of the two it got instead of reading "0 displays
- * pending" as good news.
- *
- * The absence of the attribute is NOT on its own the answer, which is the trap
- * here: a page with no tracks open — an import form, a menu shot, a bare view —
- * publishes none of it either, and reporting that as "this build cannot measure
- * paint" is both wrong and alarming. So this asks the question only when there
- * is something to measure, and answers true when there is not.
- *
- * Call it AFTER the session gate, so "no tracks open" means the page genuinely
- * has none rather than not having got there yet.
- */
-export declare function hasPaintContract(page: Page): Promise<boolean>;
-/**
- * Which readiness attributes this build publishes at all.
- *
- * `hasPaintContract` answers the same question for one attribute and folds in
- * "there was nothing to measure"; this is the raw read of all three, so the
- * chain can adapt to the build BEFORE it starts waiting rather than reporting
- * afterwards what it could not see.
- *
- * Every wait keyed on one of these is NEGATIVE — it passes when the selector is
- * absent — so on a build that publishes none of them all three are satisfied by
- * a page that has not begun to draw. Read this after the session gate and treat
- * `false` as "this signal is unavailable", never as "this signal says done".
- */
-export interface Instrumentation {
-    viewPhase: boolean;
-    displayPhase: boolean;
-    displayDrawn: boolean;
-}
-/** Serialized into the page; exported so a test can call the real function. */
-export declare function readInstrumentationInPage(): Instrumentation;
-export declare function readInstrumentation(page: Page): Promise<Instrumentation>;
 /**
  * Displays that were still reporting unpainted at the moment of the call.
  *
  * Distinct from `unsettled`, which says a wait ran out of time. This says what
- * the page looked like when the shutter fired, and the two do not imply each
- * other: a display can go back to pending after its stage passed. An empty
- * result means nothing at all on a build with no paint contract — check
- * `paintContract` before reading it as good news.
+ * the page looked like when the shutter fired.
  */
 export declare function pendingDisplays(page: Page): Promise<string[]>;
 /** One unpainted display and what it says about itself. */
@@ -104,10 +61,9 @@ export interface PendingDisplay {
     /** which instance, where the display publishes `data-display-id` */
     id?: string;
     /**
-     * Its own phase, or undefined on a build too old to publish one. `loading` is
-     * a display still fetching; `ready` is the one that earns this census, since
-     * a display that says it has finished while reporting no paint is a bug in
-     * the display rather than a slow page.
+     * Its own phase. `loading` is a display still fetching; `ready` is the one
+     * that earns this census, since a display that says it has finished while
+     * reporting no paint is a bug in the display rather than a slow page.
      */
     phase?: string;
 }
@@ -123,14 +79,12 @@ export interface PendingDisplay {
  *   `ready`     it says it is done and reports no paint. That is the display's
  *               bug, not the wait's, and it is the one a longer timeout will
  *               never fix.
- *   absent      the element publishes no phase: a build older than the
- *               attribute, or a surface that never grew one.
  *
  * Serialized into the page, so a test can call the real function. Read fresh
- * from the DOM at report time rather than from handles the waits held. A handle to an element that has since re-rendered throws
- * `Node is detached from document`, which is how the previous attempt at this
- * turned four diagnosable timeouts into nine opaque puppeteer errors (reverted
- * in 28c6ee6d90).
+ * from the DOM at report time rather than from handles the waits held. A handle
+ * to an element that has since re-rendered throws `Node is detached from
+ * document`, which is how the previous attempt at this turned four diagnosable
+ * timeouts into nine opaque puppeteer errors (reverted in 28c6ee6d90).
  */
 export declare function pendingDisplayStatesInPage(): PendingDisplay[];
 export declare function pendingDisplayStates(page: Page): Promise<PendingDisplay[]>;