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

package/README.md

@@ -19,14 +19,10 @@ 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.
 
-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:
+Nearly every signal a browser publishes is **negative** — no loading overlay, no
+display in its loading phase, no unpainted canvas — and an absence is equally
+true of a page whose JavaScript has not started. Measured against a released
+build with two remote tracks:
 
 - `networkidle2` resolves at ~350ms
 - the session appears at ~880ms
@@ -36,23 +32,30 @@ JavaScript has not started yet. Measured against that instance:
 A wait chain built from those signals alone finishes in under a second and
 reports success.
 
-So this package puts a **positive gate** in front of them, read off the live MST
-session model that jbrowse-web publishes as `window.JBrowseSession`: the session
-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.
+So this package waits on the two **positive** signals instead, and nothing else
+decides the answer:
+
+1. **The census.** `AppReadyMarker` publishes what is open as `data-app-views`,
+   `data-app-assemblies` and `data-app-tracks`, and the gate reads that one
+   element: at least one view, your assembly among them, every trackId you named
+   actually open. A config URL that 404s, a trackId the config does not define
+   and an assembly name that does not match the config all fail here, loudly,
+   and this is the only place they fail at all.
+2. **`[data-app-phase="ready"]`, held.** The session renders it when no view is
+   resolving an assembly and no display is fetching. It has to hold for a beat,
+   not merely be true once: a display drops to `ready` in the gap between one
+   fetch finishing and the debounced next one starting.
+
+Then one negative gate, which is meaningful only after those two and answers
+what they do not — the marker is about WORK, and a display whose fetch failed is
+not working, so it reads `ready` over an error banner. `data-display-drawn` is
+the stricter question, and the census of what is still unpainted goes in the
+error.
+
+**A build that publishes no `[data-app-phase]` is an error, not a slower path.**
+The fallback chain that used to run there was those negative signals plus a
+seen-busy-then-quiet heuristic to compensate for them, and it existed for builds
+older than the marker. Point `--instance` at a build that has it.
 
 ## Library
 
@@ -60,7 +63,7 @@ What runs after that gate depends on which build answered it:
 import { captureJBrowse, openJBrowse } from '@jbrowse/capture'
 
 // one call: launch, wait, shoot, close
-const { pending, paintContract } = await captureJBrowse({
+const { pending, unsettled } = await captureJBrowse({
   hub: 'hg38',
   loc: 'BRCA1',
   tracks: ['hg38-ncbiRefSeqCurated'],
@@ -85,9 +88,8 @@ 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, and on a build
-  without the marker falls back to the quiet period rather than passing
-  instantly.
+  pre-click frame. `waitForAppSettled` requires it to hold, and throws on a
+  build with no marker rather than falling back to a wait that cannot fail.
 
 ## Timeouts and unsettled waits
 
@@ -111,20 +113,16 @@ still tells you what did not settle.
 
 ## Reading the result
 
-Four fields on a successful capture:
+Two 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 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.
+- **`pending`** — displays still reporting unpainted when the shutter fired.
+  Read after `settle`, not before it, so the frame it describes is the frame
+  that was captured; a display that finished during the settle is not in it, and
+  no longer fails the run either. Whatever is left lands in `unsettled` too,
+  carrying each display's own phase — `loading` is a slow fetch, `error` a
+  banner, `ready` a display claiming it finished without drawing.
 
 ## CLI
 

package/esm/args.d.ts

@@ -18,13 +18,23 @@ export interface ParsedArgs {
     verbose: boolean;
     help: boolean;
     allowUnsettled: boolean;
+    /** What `list` reads its hub and filter from. Empty for every other form. */
+    positionals: string[];
 }
 /**
  * Parse `jb2capture` flags. Split from the binary so the accepted shapes are
  * unit-testable without launching a browser.
  *
- * Unknown flags throw rather than being ignored: a mistyped `--tracks` on a tool
- * whose whole job is to produce a plausible-looking image would otherwise be
- * reported by nothing at all.
+ * `node:util`'s parser in strict mode, which rejects an unknown flag rather
+ * than ignoring it: a mistyped `--tracks` on a tool whose whole job is to
+ * produce a plausible-looking image would otherwise be reported by nothing at
+ * all. It also rejects `--fullPage=false`, which used to set the flag true.
+ *
+ * `allowPositionals` is for `list`, the one form that takes bare words. Left
+ * off, a stray `foo.png` is an error rather than a silently ignored argument —
+ * and node's unknown-flag message stays free of the advice about `--` that only
+ * applies to a command with positionals.
  */
-export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function parseArgs(argv: string[], { allowPositionals }?: {
+    allowPositionals?: boolean;
+}): ParsedArgs;

package/esm/args.js

@@ -1,94 +1,88 @@
-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',
-    'verbose',
-    'help',
-    'allowUnsettled',
-]);
-const REPEATABLE = new Set(['track']);
-const STRINGS = new Set([
-    'hub',
-    'config',
-    'assembly',
-    'loc',
-    'session',
-    'sessionName',
-    'instance',
-    'out',
-]);
+import { parseArgs as parseNodeArgs } from 'node:util';
 // `--fullPage`, not `--full-page`: the flags match the option names in the
 // library API one for one, so a script and a command line say the same thing.
 // Aliases are the two abbreviations that are hard not to type.
-const ALIASES = { o: 'out', h: 'help' };
-function known(name) {
-    return (NUMERIC.has(name) ||
-        FLAGS.has(name) ||
-        REPEATABLE.has(name) ||
-        STRINGS.has(name));
+const OPTIONS = {
+    hub: { type: 'string' },
+    config: { type: 'string' },
+    assembly: { type: 'string' },
+    loc: { type: 'string' },
+    session: { type: 'string' },
+    sessionName: { type: 'string' },
+    instance: { type: 'string' },
+    out: { type: 'string', short: 'o' },
+    track: { type: 'string', multiple: true, default: [] },
+    width: { type: 'string' },
+    height: { type: 'string' },
+    scale: { type: 'string' },
+    timeout: { type: 'string' },
+    settle: { type: 'string' },
+    fullPage: { type: 'boolean', default: false },
+    headed: { type: 'boolean', default: false },
+    verbose: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+    allowUnsettled: { type: 'boolean', default: false },
+};
+function finite(name, raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+        throw new Error(`--${name} needs a number, got "${raw}"`);
+    }
+    return n;
+}
+// node:util parses every value as a string, and these two checks are the ones
+// it cannot make. Without them they 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.
+function positive(name, raw) {
+    const n = finite(name, raw);
+    if (n !== undefined && n <= 0) {
+        throw new Error(`--${name} needs a positive number, got "${raw}"`);
+    }
+    return n;
+}
+function milliseconds(name, raw) {
+    const n = finite(name, raw);
+    if (n !== undefined && n < 0) {
+        throw new Error(`--${name} needs a number of milliseconds that is zero or more, got "${raw}"`);
+    }
+    return n;
 }
 /**
  * Parse `jb2capture` flags. Split from the binary so the accepted shapes are
  * unit-testable without launching a browser.
  *
- * Unknown flags throw rather than being ignored: a mistyped `--tracks` on a tool
- * whose whole job is to produce a plausible-looking image would otherwise be
- * reported by nothing at all.
+ * `node:util`'s parser in strict mode, which rejects an unknown flag rather
+ * than ignoring it: a mistyped `--tracks` on a tool whose whole job is to
+ * produce a plausible-looking image would otherwise be reported by nothing at
+ * all. It also rejects `--fullPage=false`, which used to set the flag true.
+ *
+ * `allowPositionals` is for `list`, the one form that takes bare words. Left
+ * off, a stray `foo.png` is an error rather than a silently ignored argument —
+ * and node's unknown-flag message stays free of the advice about `--` that only
+ * applies to a command with positionals.
  */
-export function parseArgs(argv) {
-    const out = { tracks: [] };
-    for (const flag of FLAGS) {
-        out[flag] = false;
-    }
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (!arg.startsWith('-')) {
-            throw new Error(`unexpected argument "${arg}"`);
-        }
-        const bare = arg.replace(/^--?/, '');
-        const eq = bare.indexOf('=');
-        const rawName = eq === -1 ? bare : bare.slice(0, eq);
-        const name = ALIASES[rawName] ?? rawName;
-        if (!known(name)) {
-            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;
-        }
-        const value = eq === -1 ? argv[++i] : bare.slice(eq + 1);
-        if (value === undefined) {
-            throw new Error(`--${name} needs a value`);
-        }
-        if (REPEATABLE.has(name)) {
-            ;
-            out.tracks.push(value);
-        }
-        else if (NUMERIC.has(name)) {
-            const n = Number(value);
-            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 {
-            out[name] = value;
-        }
-    }
-    return out;
+export function parseArgs(argv, { allowPositionals = false } = {}) {
+    const { values, positionals } = parseNodeArgs({
+        args: argv,
+        options: OPTIONS,
+        allowPositionals,
+    });
+    const { track, width, height, scale, timeout, settle, ...rest } = values;
+    return {
+        ...rest,
+        // Copied: with no `--track`, node hands back the `default: []` array off
+        // OPTIONS itself, so every call shares one instance and a caller that
+        // pushes to it edits the module constant.
+        tracks: [...track],
+        width: positive('width', width),
+        height: positive('height', height),
+        scale: positive('scale', scale),
+        timeout: positive('timeout', timeout),
+        settle: milliseconds('settle', settle),
+        positionals,
+    };
 }

package/esm/bin.js

@@ -3,7 +3,6 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from './args.js';
 import { captureJBrowse } from './capture.js';
 import { listHubTracks } from './hub.js';
-import { PAINT_CONTRACT_NOTE } from './sessionGate.js';
 import { jbrowseUrl } from './url.js';
 const HELP = `jb2capture — screenshot a live JBrowse 2 view, once it has finished drawing
 
@@ -37,7 +36,7 @@ THE IMAGE
 
 WAITING
   --timeout <ms>        budget per wait stage (default 60000)
-  --settle <ms>         extra pause after everything reports drawn (default 0)
+  --settle <ms>         extra pause before the census and the shot (default 0)
   --allowUnsettled      write the image anyway when a stage times out
 
   Every stage is waited on for you: the session holding the assembly and tracks
@@ -85,8 +84,8 @@ function urlOptions(args) {
         instance: args.instance,
     };
 }
-async function runList(rest) {
-    const [hub, filter] = rest;
+async function runList(positionals) {
+    const [hub, filter] = positionals;
     if (!hub) {
         throw new Error('list needs an assembly, e.g. `jb2capture list hg38`. ' +
             'Browse them at https://genomes.jbrowse.org.');
@@ -105,24 +104,30 @@ async function runList(rest) {
 async function main() {
     const argv = process.argv.slice(2);
     const [first, ...rest] = argv;
-    if (first === 'list') {
-        await runList(rest);
-        return;
-    }
-    const isUrlOnly = first === 'url';
-    const args = parseArgs(isUrlOnly ? rest : argv);
+    // `list` is the one form that takes bare words, so it is the one that allows
+    // positionals. Routing it through the parser at all is what makes a flag
+    // after it an error: `list hg38 --foo` used to filter the track list on the
+    // string "--foo" and report that nothing matched.
+    const isSubcommand = first === 'list' || first === 'url';
+    const args = parseArgs(isSubcommand ? rest : argv, {
+        allowPositionals: first === 'list',
+    });
     if (args.help || argv.length === 0) {
         console.log(HELP);
         return;
     }
-    if (isUrlOnly) {
+    if (first === 'list') {
+        await runList(args.positionals);
+        return;
+    }
+    if (first === 'url') {
         console.log(jbrowseUrl(urlOptions(args)));
         return;
     }
     if (!args.out) {
         throw new Error('--out <file.png> is required (or use `jb2capture url`)');
     }
-    const { url, pending, paintContract, unsettled } = await captureJBrowse({
+    const { url, pending, unsettled } = await captureJBrowse({
         ...urlOptions(args),
         out: args.out,
         width: args.width,
@@ -152,9 +157,6 @@ async function main() {
         console.error(`warning: ${pending.length} display(s) had not finished drawing at capture time ` +
             `(${pending.join(', ')}). Raise --timeout, or --settle for a slow remote file.`);
     }
-    else if (!paintContract) {
-        console.error(`note: ${PAINT_CONTRACT_NOTE}`);
-    }
 }
 try {
     await main();

package/esm/capture.js

@@ -6,6 +6,10 @@ import { waitForJBrowseReady } from './ready.js';
 import { assemblyFromSession, trackIdsFromSession } from './session.js';
 import { jbrowseUrl } from './url.js';
 import { waitForAppSettled } from './waits.js';
+// Puppeteer's own `goto` default is 30s, half of what a caller passing nothing
+// is told each wait stage gets. Defaulted here so the navigation, the chain and
+// the fullPage re-settle all run on one budget.
+const DEFAULT_TIMEOUT = 60000;
 /**
  * Launch a browser, navigate to a JBrowse session, and wait until it has
  * rendered. The caller owns the returned browser and must close it.
@@ -19,11 +23,7 @@ import { waitForAppSettled } from './waits.js';
  * 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, 
-    // 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, 
+    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, timeout = DEFAULT_TIMEOUT, 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
@@ -102,8 +102,22 @@ export async function captureJBrowse(options = {}) {
             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 });
+                // grew gained rows to draw), so the frame has to settle again — on the
+                // same budget the chain used, and with its outcome reported. Dropping
+                // the outcome made this the one stage that could give up and still
+                // report `unsettled: []`, over the frame most likely to be half-drawn.
+                const settled = await waitForAppSettled(page, {
+                    timeout: openOptions.timeout ?? DEFAULT_TIMEOUT,
+                });
+                if (!settled) {
+                    report.unsettled.push('the app never re-settled after the resize');
+                    if (!openOptions.allowUnsettled) {
+                        throw new Error(`gave up waiting after ${openOptions.timeout ?? DEFAULT_TIMEOUT}ms: ` +
+                            'the app never re-settled after the fullPage resize. Raise the ' +
+                            'timeout, or pass allowUnsettled (--allowUnsettled) to capture ' +
+                            'the frame as it stands.');
+                    }
+                }
             }
         }
         const image = await page.screenshot({ path: out });

package/esm/index.d.ts

@@ -1,6 +1,6 @@
 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 { APP_CENSUS, describePendingDisplays, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, 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';
@@ -8,5 +8,5 @@ export { APP_READY, BUSY_SELECTOR, LOADING_OVERLAY, PENDING_DISPLAYS, delay, des
 export { BASE_CHROME_ARGS, SANDBOX_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.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 { PendingDisplay, SessionExpectations, SessionSummary, } from './sessionGate.ts';
 export type { JBrowseUrlOptions } from './url.ts';

package/esm/index.js

@@ -1,6 +1,6 @@
 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 { APP_CENSUS, describePendingDisplays, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, 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

@@ -1,26 +1,14 @@
-import type { Instrumentation, PendingDisplay, SessionExpectations } from './sessionGate.ts';
+import type { 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.
+     * Extra pause after every stage reports done, for animations and tooltips —
+     * and for a display finishing its first paint, since the census that decides
+     * whether the run failed is taken after this rather than before it.
      */
-    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
@@ -37,35 +25,25 @@ export interface ReadyReport {
      * 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.
+ * 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 declare function waitForJBrowseReady(page: Page, { timeout, waitForDownloads, settleMs, expectSession, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;
+export declare function waitForJBrowseReady(page: Page, { timeout, settleMs, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;