@jbrowse/capture 4.3.0

package/esm/sessionGate.d.ts

@@ -0,0 +1,126 @@
+import type { Page } from 'puppeteer';
+export interface SessionExpectations {
+    /** Assembly that must be open on some view. Usually the one you navigated to. */
+    assembly?: string;
+    /**
+     * trackIds that must all be open. The exact ids, not a count: a hosted config
+     * usually ships a defaultSession, so `&tracks=` ADDS to tracks that are
+     * already there and a count is satisfied before your track arrives — or by
+     * the default set alone when the id you passed does not exist at all.
+     */
+    trackIds?: string[];
+}
+export interface SessionSummary {
+    views: number;
+    assemblies: string[];
+    trackIds: string[];
+}
+/** What the page currently has open, or undefined if there is no session 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.
+ *
+ * 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
+ * the one the config declares all fail here, which is the only place they fail
+ * at all — each of them otherwise produces a browser that loads, paints its
+ * chrome, and photographs beautifully with nothing in it.
+ */
+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.
+ */
+export declare function pendingDisplays(page: Page): Promise<string[]>;
+/** One unpainted display and what it says about itself. */
+export interface PendingDisplay {
+    /** the display TYPE, shared by every instance of it */
+    name: string;
+    /** 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.
+     */
+    phase?: string;
+}
+/**
+ * The same census, with each display's own account of itself.
+ *
+ * `pendingDisplays` above answers WHICH, and that was the whole report: every
+ * timeout read the same however it was caused. The phase separates the cases a
+ * bare name runs together —
+ *
+ *   `loading`   still fetching. A slow page or a fetch that never returns.
+ *   `error`     finished, badly. Nothing is coming; the picture is a banner.
+ *   `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).
+ */
+export declare function pendingDisplayStatesInPage(): PendingDisplay[];
+export declare function pendingDisplayStates(page: Page): Promise<PendingDisplay[]>;
+/** `pendingDisplayStates` as one line for an error message. */
+export declare function describePendingDisplays(pending: PendingDisplay[]): string;

package/esm/sessionGate.js

@@ -0,0 +1,196 @@
+/** What the page currently has open, or undefined if there is no session yet. */
+export function readSessionSummary(page) {
+    return page.evaluate(readSessionSummaryInPage);
+}
+// Serialized into the page, so it can only call what it declares — hence the
+// inlined copy of readViews rather than a shared import.
+//
+// Exported for its test: it reads `globalThis.JBrowseSession` and nothing else,
+// 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() {
+    const session = globalThis.JBrowseSession;
+    const views = session?.views;
+    if (!views) {
+        return undefined;
+    }
+    // Inlined rather than shared with the gate below for the same reason as the
+    // readViews copy: both are serialized into the page.
+    function collect(v) {
+        return [
+            ...(v.tracks ?? []),
+            ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
+            ...(v.views ?? []).flatMap(collect),
+        ];
+    }
+    return {
+        views: views.length,
+        assemblies: [
+            ...new Set(views.flatMap(function asm(v) {
+                return [...(v.assemblyNames ?? []), ...(v.views ?? []).flatMap(asm)];
+            })),
+        ],
+        trackIds: views.flatMap(v => collect(v).map(t => t.configuration?.trackId ?? '(unnamed)')),
+    };
+}
+/**
+ * Wait until the session exists, every view reports itself initialized, 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
+ * the one the config declares all fail here, which is the only place they fail
+ * at all — each of them otherwise produces a browser that loads, paints its
+ * chrome, and photographs beautifully with nothing in it.
+ */
+export async function waitForSession(page, { assembly, trackIds = [], timeout = 60000, } = {}) {
+    try {
+        // #region session-gate
+        await page.waitForFunction((wantAssembly, wantTracks) => {
+            const session = globalThis.JBrowseSession;
+            const views = session?.views;
+            if (!views?.length) {
+                return false;
+            }
+            // `initialized` is an LGV getter; a view type without one is mounted
+            // content the moment it exists, so absent counts as initialized and
+            // only an explicit false is pending.
+            if (views.some(v => v.initialized === false)) {
+                return false;
+            }
+            // A container view (synteny, dotplot) keeps its assemblies on the rows
+            // and its tracks on the levels, so both walks descend into sub-views
+            // and levels rather than reading the top view only.
+            const asmOf = (v) => [
+                ...(v.assemblyNames ?? []),
+                ...(v.views ?? []).flatMap(asmOf),
+            ];
+            if (wantAssembly !== null &&
+                !views.some(v => asmOf(v).includes(wantAssembly))) {
+                return false;
+            }
+            const tracksOf = (v) => [
+                ...(v.tracks ?? []),
+                ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
+                ...(v.views ?? []).flatMap(tracksOf),
+            ];
+            const open = new Set(views.flatMap(v => tracksOf(v).map(t => t.configuration?.trackId)));
+            return wantTracks.every(id => open.has(id));
+        }, { timeout, polling: 250 }, assembly ?? null, trackIds);
+        // #endregion session-gate
+    }
+    catch {
+        const summary = await readSessionSummary(page);
+        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?)';
+        const missing = summary
+            ? trackIds.filter(id => !summary.trackIds.includes(id))
+            : trackIds;
+        const wanted = [
+            assembly ? `assembly "${assembly}"` : undefined,
+            missing.length ? `track(s) [${missing.join(', ')}]` : undefined,
+        ]
+            .filter(Boolean)
+            .join(' and ');
+        throw new Error(`the session never reached the requested state after ${timeout}ms. ` +
+            `Wanted ${wanted || 'an initialized view'}; found ${found}. ` +
+            'A config URL that 404s, a trackId the config does not define, or an ' +
+            'assembly name that does not match the config all look like this.');
+    }
+}
+export const PAINT_CONTRACT_NOTE = 'this JBrowse build publishes no data-display-drawn attributes, so "every ' +
+    'display has painted" cannot be checked — only that nothing is still ' +
+    'loading. Raise --settle if the image looks half-drawn.';
+/**
+ * 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 async function hasPaintContract(page) {
+    const summary = await readSessionSummary(page);
+    if (summary && summary.trackIds.length === 0) {
+        return true;
+    }
+    return page.evaluate(() => document.querySelector('[data-display-drawn]') !== null);
+}
+/** Serialized into the page; exported so a test can call the real function. */
+export function readInstrumentationInPage() {
+    return {
+        viewPhase: document.querySelector('[data-view-phase]') !== null,
+        displayPhase: document.querySelector('[data-display-phase]') !== null,
+        displayDrawn: document.querySelector('[data-display-drawn]') !== null,
+    };
+}
+export function readInstrumentation(page) {
+    return page.evaluate(readInstrumentationInPage);
+}
+/**
+ * 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.
+ */
+export function pendingDisplays(page) {
+    return page.evaluate(() => [
+        ...document.querySelectorAll('[data-display-drawn="false"]'),
+    ].map(el => el.dataset.testid ?? (el.id || 'unnamed display')));
+}
+/**
+ * The same census, with each display's own account of itself.
+ *
+ * `pendingDisplays` above answers WHICH, and that was the whole report: every
+ * timeout read the same however it was caused. The phase separates the cases a
+ * bare name runs together —
+ *
+ *   `loading`   still fetching. A slow page or a fetch that never returns.
+ *   `error`     finished, badly. Nothing is coming; the picture is a banner.
+ *   `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).
+ */
+export function pendingDisplayStatesInPage() {
+    return [
+        ...document.querySelectorAll('[data-display-drawn="false"]'),
+    ].map(el => ({
+        name: el.dataset.testid ?? (el.id || 'unnamed display'),
+        id: el.dataset.displayId,
+        phase: el.dataset.displayPhase,
+    }));
+}
+export function pendingDisplayStates(page) {
+    return page.evaluate(pendingDisplayStatesInPage);
+}
+/** `pendingDisplayStates` as one line for an error message. */
+export function describePendingDisplays(pending) {
+    return pending
+        .map(d => `${d.name}${d.id ? ` (${d.id})` : ''} is ${d.phase ?? 'in an unpublished phase'}`)
+        .join('; ');
+}

package/esm/url.d.ts

@@ -0,0 +1,39 @@
+export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/latest/";
+export interface JBrowseUrlOptions {
+    /** A genomes.jbrowse.org assembly: a UCSC db name (`hg38`) or GenArk accession. */
+    hub?: string;
+    /** A config.json URL, for data that is not on genomes.jbrowse.org. Wins over `hub`. */
+    config?: string;
+    /** Assembly to open. Defaults to `hub`, whose config names its assembly after it. */
+    assembly?: string;
+    /**
+     * Where to open. A locstring (`chr1:1,000-2,000`, several space-separated for
+     * a discontinuous view), or — on a config that ships a text index, which every
+     * UCSC assembly on genomes.jbrowse.org does — a feature name such as `BRCA1`.
+     */
+    loc?: string;
+    /** trackIds from the config to open. */
+    tracks?: string[];
+    /** The full session spec, for anything the three fields above cannot say. */
+    session?: object;
+    /** Name the session carries once opened. */
+    sessionName?: string;
+    /** JBrowse Web deployment to load. Defaults to the public one. */
+    instance?: string;
+}
+/**
+ * The URL that opens a JBrowse Web instance onto a described view. Useful on its
+ * own: an agent can hand this to a human, or paste it into a report, without
+ * launching a browser at all.
+ *
+ * Two ways to say where to go, and they are not interchangeable. `assembly` /
+ * `loc` / `tracks` become the [URL parameters](https://jbrowse.org/jb2/docs/urlparams/),
+ * which route `loc` through the config's text-search index, so a **gene name**
+ * works there. `session` becomes a
+ * [session spec](https://jbrowse.org/jb2/docs/urlparams/#session-spec), which
+ * can describe several views and per-display settings but whose `init.loc` is
+ * parsed as a locstring only and throws on a gene name. Pass one or the other;
+ * `session` wins, and the URL params are dropped rather than silently starting
+ * the fresh session that `&loc=` otherwise forces.
+ */
+export declare function jbrowseUrl({ hub, config, assembly, loc, tracks, session, sessionName, instance, }: JBrowseUrlOptions): string;

package/esm/url.js

@@ -0,0 +1,44 @@
+import { hubUrl } from './hub.js';
+import { sessionSpecParam } from './session.js';
+// The public JBrowse Web build the docs' own figure links point at. Any other
+// deployment works the same way, including a local `npx serve` of a build.
+export const PUBLIC_INSTANCE = 'https://jbrowse.org/code/jb2/latest/';
+/**
+ * The URL that opens a JBrowse Web instance onto a described view. Useful on its
+ * own: an agent can hand this to a human, or paste it into a report, without
+ * launching a browser at all.
+ *
+ * Two ways to say where to go, and they are not interchangeable. `assembly` /
+ * `loc` / `tracks` become the [URL parameters](https://jbrowse.org/jb2/docs/urlparams/),
+ * which route `loc` through the config's text-search index, so a **gene name**
+ * works there. `session` becomes a
+ * [session spec](https://jbrowse.org/jb2/docs/urlparams/#session-spec), which
+ * can describe several views and per-display settings but whose `init.loc` is
+ * parsed as a locstring only and throws on a gene name. Pass one or the other;
+ * `session` wins, and the URL params are dropped rather than silently starting
+ * the fresh session that `&loc=` otherwise forces.
+ */
+export function jbrowseUrl({ hub, config, assembly = hub, loc, tracks, session, sessionName, instance = PUBLIC_INSTANCE, }) {
+    const configUrl = config ?? (hub ? hubUrl(hub) : undefined);
+    const url = new URL(instance);
+    // URL's own encoder, not a hand-built query string: a config URL contains
+    // `://` and `?`, and a session spec is a whole JSON document, so appending
+    // either raw produces a link that loads a truncated config and reports
+    // nothing.
+    const set = (key, value) => {
+        if (value) {
+            url.searchParams.set(key, value);
+        }
+    };
+    set('config', configUrl);
+    if (session) {
+        set('session', sessionSpecParam(session));
+    }
+    else {
+        set('assembly', assembly);
+        set('loc', loc);
+        set('tracks', tracks?.join(','));
+    }
+    set('sessionName', sessionName);
+    return url.href;
+}

package/esm/waits.d.ts

@@ -0,0 +1,214 @@
+import type { ElementHandle, Page } from 'puppeteer';
+export declare const delay: (ms: number) => Promise<void>;
+export declare const LOADING_OVERLAY = "[data-testid=\"loading-overlay\"]";
+/**
+ * The whole readiness contract, in one selector.
+ *
+ * `AppReadyMarker` renders it from the session: it reads `ready` when no view
+ * is resolving an assembly and no display is fetching, and `loading` whenever
+ * one is. Waiting for it is the entire job — everything else in this module is
+ * either a narrower question (has THIS display painted) or a fallback for a
+ * deployment too old to publish it.
+ *
+ * It is POSITIVE, which is the property that matters. Every other signal here
+ * is an absence, and an absence is equally true of an app that has not started:
+ * measured on a two-track session, the gap between "the session holds the
+ * tracks" and "the first loading indicator appears" is about a second, and a
+ * capture taken in it is a picture of an empty browser.
+ */
+export declare const APP_READY = "[data-app-phase=\"ready\"]";
+export declare function waitForLoadingComplete(page: Page, { timeout, waitForDownloads, }?: {
+    timeout?: number;
+    waitForDownloads?: boolean;
+}): Promise<boolean>;
+/**
+ * Wait until nothing on the page is in flight.
+ *
+ * Every signal it reads is one the app publishes deliberately — the loading
+ * overlay, `data-busy`, the display and view phases, and each display's own
+ * status message on the session model. See `isPageBusyInPage`.
+ *
+ * It used to scan rendered text for /^(loading|rendering|computing)/ and resolve
+ * `getComputedStyle` on each match to decide whether it was on screen. That is a
+ * heuristic over a rendering: it broke on a reworded or translated message, it
+ * needed the visibility check only because the loading overlay keeps the word
+ * "Loading" in the DOM at `opacity: 0`, and an unset opacity parses to zero
+ * outside a full layout engine, which reads every ordinary element as hidden. A
+ * component that wants to be waited for now says so with an attribute.
+ *
+ * Best-effort: a view genuinely stuck loading would otherwise burn the whole
+ * timeout, so this reports false rather than throwing and the caller decides.
+ */
+export declare function waitForQuiescent(page: Page, { timeout }?: {
+    timeout?: number;
+}): Promise<boolean>;
+export declare const PENDING_DISPLAYS = "[data-display-drawn=\"false\"]";
+/**
+ * `page.waitForSelector`, with the display census in the timeout.
+ *
+ * The waits below are best-effort and hand their outcome back as a boolean, so
+ * a caller can say what was still unsettled. A *selector* wait is the opposite
+ * shape — it throws, and it runs FIRST, before any of them: a capture whose
+ * display never paints dies here on puppeteer's `TimeoutError`, which names the
+ * selector and nothing else, and the census that would have named the display
+ * runs later or not at all.
+ *
+ * So the census runs on the way out. It is re-read from the DOM here rather
+ * than taken off a handle the wait held: a handle to an element that has since
+ * re-rendered throws `Node is detached from document`, which is how the first
+ * attempt at this turned four diagnosable timeouts into nine opaque puppeteer
+ * errors (reverted in 28c6ee6d90).
+ *
+ * What it reports is the phase, and that is the part a longer timeout cannot
+ * substitute for: `loading` is a slow fetch, `error` is a display that has
+ * finished badly and is showing a banner, and `ready` is a display claiming it
+ * finished without drawing — a bug in the display rather than in the wait.
+ *
+ * An EMPTY census is the other answer, and `tooLarge` / `renderError` are why it
+ * is not good news. Those two replace the display's subtree outright, so they
+ * publish neither attribute and appear here as nothing at all: a wait on such a
+ * display can never resolve and can never be reported. Nothing pending means
+ * either that, or a selector that was never a display's.
+ */
+export declare function waitForSelectorAttributed(page: Page, selector: string, timeoutMs: number): Promise<ElementHandle>;
+/**
+ * The census as one clause, for a message. Best-effort in its own right: a page
+ * whose execution context is gone cannot be asked, and saying so is the answer.
+ */
+export declare function describePendingDisplaysNow(page: Page): Promise<string>;
+export declare const displayPainted: (testid: string) => string;
+/**
+ * The stronger one. `drawn` flips on FIRST paint — an empty canvas with the
+ * fetch still in flight satisfies it — so a figure that must show *data* waits
+ * on the phase instead.
+ */
+export declare const displaySettled: (testid: string) => string;
+/** One display, by its config's `displayId` rather than by type. */
+export declare const displayById: (displayId: string) => string;
+export declare function waitForDisplaysDone(page: Page, timeoutMs: number): Promise<boolean>;
+export declare function waitForDisplayPhases(page: Page, timeoutMs: number): Promise<boolean>;
+export declare function waitForViewPhases(page: Page, timeoutMs: number): Promise<import("puppeteer").JSHandle<false> | import("puppeteer").JSHandle<true>>;
+/**
+ * Everything the app publishes to say it is working, as one selector.
+ *
+ * All four are attributes a component sets deliberately, which is the whole
+ * point: the alternative — scanning rendered text for /^loading/ and resolving
+ * `getComputedStyle` to decide whether each match is on screen — makes a
+ * reworded message, a translation or an opacity animation change the answer.
+ *
+ *   `loading-overlay`      the view-level scrim, present in every build
+ *   `data-busy`            LoadingEllipses, which is what the app renders
+ *                          wherever it tells a user it is working
+ *   `data-display-phase`   one display's own fetch, newer builds
+ *   `data-view-phase`      a view still resolving its assembly, newer builds
+ */
+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
+ * 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;
+/**
+ * Wait until the app has been idle for an unbroken stretch.
+ *
+ * The gate for a build that publishes no readiness attributes, where every
+ * other wait in this module is an assertion about an absent selector and so
+ * cannot fail. Absence answers "is it working NOW"; a capture needs "has it
+ * finished", and the two differ in both directions:
+ *
+ *   BEFORE the work starts. Measured on jbrowse.org/code/jb2/latest with two
+ *   remote tracks: the session reports both tracks open at ~2.5s and the
+ *   loading overlay does not go up until ~3.5s. Every absence-based gate passes
+ *   during that second, over an app that has drawn nothing.
+ *
+ *   BETWEEN two pieces of work. A track that finishes one fetch and starts the
+ *   next is momentarily idle, and a single-sample gate takes it.
+ *
+ * Requiring the idle to HOLD closes both without needing to know which signals
+ * a given build has. Polled from node rather than in-page: chrome throttles
+ * in-page timers and rAF once the tab is not visible, which is the state a
+ * headless capture sits in.
+ *
+ * Returns false on timeout rather than throwing, like its neighbours — the
+ * caller decides whether a page that never went quiet is a failure or a slow
+ * page worth capturing anyway.
+ */
+export declare function waitForQuietPeriod(page: Page, { quietMs, timeout, pollMs, busyWindowMs, }?: {
+    quietMs?: number;
+    timeout?: number;
+    pollMs?: number;
+    /**
+     * Wait for the app to be seen BUSY before any idle counts, giving up on
+     * that after this long. Zero (the default) accepts idle immediately.
+     *
+     * This is what turns the wait positive. Idle is still an absence, so an app
+     * that has not begun looks exactly like one that has finished — measured on
+     * jbrowse.org/code/jb2/latest, where a chain starting at the session gate
+     * saw an idle page at 1.6s and the tracks did not draw until past 10s.
+     * Seeing the transition INTO work and back out of it is an observation of
+     * the work itself.
+     *
+     * The window is bounded because a page with nothing to fetch never goes
+     * busy at all, and hanging on that would be worse than the race it closes.
+     * Size it above the gap between the session gate passing and the first
+     * indicator appearing, measured at ~1s on that instance.
+     */
+    busyWindowMs?: number;
+}): Promise<boolean>;
+/**
+ * Wait for the app to say it has finished.
+ *
+ * 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.
+ */
+export declare function waitForAppReady(page: Page, { timeout }?: {
+    timeout?: number;
+}): Promise<boolean>;
+/** Whether this build publishes the app-level readiness marker at all. */
+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.
+ *
+ * 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
+ * produces looks finished, while too long is dead time on every run.
+ *
+ * **Not "seen busy, then ready"**, which is the obvious shape and was built and
+ * measured first. Waiting for `loading` to appear before accepting `ready` needs
+ * a cap, since an interaction that only opened a menu never makes the app busy at
+ * all — and on the figure spec it was measured against
+ * (`search_feature_highlight`) the app was never seen busy either, because that
+ * spec's own selector wait had already outlasted the redraw. The busy window then
+ * ran to its 2s cap having watched nothing, costing more than the 1.2s sleep it
+ * replaced. Requiring the idle to HOLD costs the hold and no more, and catches
+ * the same late-starting work.
+ *
+ * Polled from Node rather than by `page.waitForSelector`, for the reason
+ * `waitForQuietPeriod` is: chrome throttles in-page timers and rAF once the tab
+ * is not visible, which is exactly the state a headless capture sits in.
+ *
+ * Falls back to the quiet period on a build too old for the marker, rather than
+ * passing instantly. A no-op that reports success is how a spec that dropped its
+ * sleep for this ends up capturing the frame the sleep was there to avoid.
+ */
+export declare function waitForAppSettled(page: Page, { timeout, holdMs, pollMs, }?: {
+    timeout?: number;
+    holdMs?: number;
+    pollMs?: number;
+}): Promise<boolean>;