@jbrowse/capture 5.0.0-beta.8 → 5.0.0-beta.9

package/README.md

@@ -10,7 +10,10 @@ npx @jbrowse/capture --hub hg38 --loc BRCA1 \
 
 `--hub` names an assembly on [genomes.jbrowse.org](https://genomes.jbrowse.org),
 which hosts a ready-made JBrowse config per UCSC and GenArk genome, and `--loc`
-takes a gene name because those configs ship a text index.
+takes a gene name because those configs ship a text index. `--track` takes a
+trackId, the id without its assembly prefix (`clinvarMain`) or the track's
+display name; capture checks each one and the assembly against the config before
+launching a browser, and a miss fails at once with suggestions.
 
 ## Knowing when JBrowse has finished rendering
 
@@ -38,13 +41,18 @@ 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.
+   actually open. A trackId or assembly that capture could not check against the
+   config before launching (a session spec's, or a config it could not fetch)
+   fails here if it never opens. A config, session or plugin the app cannot load
+   fails here at once, with the app's own message, which it publishes as
+   `data-app-error`.
 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.
+   fetch finishing and the debounced next one starting. The hold also waits out
+   a view body still loading its code and a display drawing a morph between two
+   layouts (`data-display-animating="true"`), neither of which the marker can
+   see.
 
 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
@@ -52,10 +60,10 @@ 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.
+**The instance has to be JBrowse v5 or later**, the first release to publish the
+marker. Capture reads the instance's `version.txt` before launching a browser
+and refuses an older build there, rather than waiting out a timeout on a page
+that will never say it has finished.
 
 ## Library
 
@@ -70,20 +78,28 @@ const { pending, unsettled } = await captureJBrowse({
   out: 'brca1.png',
 })
 
-// or keep the page, to click things and read state back
+// or keep the page, to click things, read state back, or shoot one element
 const { browser, page } = await openJBrowse({ hub: 'mm39', loc: 'Sox2' })
 const tracks = await page.evaluate(
   () => window.JBrowseSession.views[0].tracks.length,
 )
+const view = await page.$('[data-testid^="view-container-"]')
+await view.screenshot({ path: 'view-only.png' })
 await browser.close()
 ```
 
+The CLI covers the common capture and has no flag for the rest. A crop, a click
+before the shot or a hidden element is a line of Puppeteer on the page
+`openJBrowse` returns, and a view or display setting goes in a `--spec`.
+
 Two waits, depending on what you did:
 
 - **`waitForJBrowseReady(page)`** is the wait on its own, for a page you
-  navigated yourself. The individual stages (`waitForSession`,
-  `waitForLoadingComplete`, `waitForDisplaysDone`, `waitForQuiescent`, ...) are
-  exported too, and each one documents what it can and cannot tell you.
+  navigated yourself. `waitForFrame(page)` is its second half alone, for a page
+  whose session you already gated, after a resize or a click. The individual
+  stages (`waitForSession`, `waitForLoadingComplete`, `waitForDisplaysDone`,
+  `waitForQuiescent`, ...) are exported too, and each one documents what it can
+  and cannot tell you.
 - **`waitForAppSettled(page)`** is the wait after you CLICK something. A page
   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
@@ -101,11 +117,11 @@ way, which is the vacuous-gate problem again, one step later.
 Here every stage reports its outcome, and an unsettled one throws by default,
 naming the gate:
 
-```
-gave up waiting after 2000ms: the loading overlay never cleared (a track fetch
-never finished). 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.
+```text
+gave up waiting after 60000ms: the app never held itself ready; display(s)
+never painted: LinearAlignmentsDisplay (volvox_cram-LinearAlignmentsDisplay) is
+loading. Raise the timeout, or pass allowUnsettled (--allowUnsettled) to capture
+the frame as it stands.
 ```
 
 `allowUnsettled` (`--allowUnsettled`) takes the frame as it stands instead, and
@@ -113,16 +129,21 @@ still tells you what did not settle.
 
 ## Reading the result
 
-Two fields on a successful capture:
+Three fields on a successful capture:
 
 - **`unsettled`** — stages that hit their timeout. Empty unless you asked to
   proceed anyway.
-- **`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.
+- **`pending`** — displays still reporting unpainted when the shutter fired,
+  each with its own phase: `loading` is a slow fetch, `error` a banner, `ready`
+  a display claiming it finished without drawing. 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, as does a display whose
+  renderer failed (`renderError`).
+- **`tooLarge`** — displays showing "Requested too much data" instead of their
+  features, because the region is wider than the track fetches without being
+  asked. The capture still succeeds, since that is the app working as designed,
+  and the CLI prints a warning naming them. Narrow the location to draw them.
 
 ## CLI
 

package/esm/args.d.ts

@@ -4,8 +4,8 @@ export interface ParsedArgs {
     assembly?: string;
     loc?: string;
     tracks: string[];
+    spec?: string;
     session?: string;
-    sessionName?: string;
     instance?: string;
     out?: string;
     width?: number;
@@ -17,6 +17,7 @@ export interface ParsedArgs {
     headed: boolean;
     verbose: boolean;
     help: boolean;
+    version: boolean;
     allowUnsettled: boolean;
     /** What `list` reads its hub and filter from. Empty for every other form. */
     positionals: string[];

package/esm/args.js

@@ -7,8 +7,8 @@ const OPTIONS = {
     config: { type: 'string' },
     assembly: { type: 'string' },
     loc: { type: 'string' },
+    spec: { type: 'string' },
     session: { type: 'string' },
-    sessionName: { type: 'string' },
     instance: { type: 'string' },
     out: { type: 'string', short: 'o' },
     track: { type: 'string', multiple: true, default: [] },
@@ -21,6 +21,7 @@ const OPTIONS = {
     headed: { type: 'boolean', default: false },
     verbose: { type: 'boolean', default: false },
     help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false },
     allowUnsettled: { type: 'boolean', default: false },
 };
 function finite(name, raw) {

package/esm/bin.js

@@ -2,52 +2,50 @@
 import { readFileSync } from 'node:fs';
 import { parseArgs } from './args.js';
 import { captureJBrowse } from './capture.js';
-import { listHubTracks } from './hub.js';
+import { resolveAgainstConfig } from './catalog.js';
+import { listHubAssemblies, listHubTracks } from './hub.js';
+import { describePendingDisplays } from './sessionGate.js';
 import { jbrowseUrl } from './url.js';
 const HELP = `jb2capture — screenshot a live JBrowse 2 view, once it has finished drawing
 
 USAGE
   jb2capture [flags] --out <file.png>    open a view, wait for it, screenshot it
   jb2capture url [flags]                 print the URL instead of launching a browser
-  jb2capture list <hub> [filter]         list a hosted assembly's trackIds
+  jb2capture list [hub] [filter]         list hosted assemblies, or one's trackIds
 
 WHAT TO SHOW
   --hub <name>          a genomes.jbrowse.org assembly: a UCSC db name (hg38, mm39)
                         or a GenArk accession (GCA_.../GCF_...)
   --config <url>        a config.json URL, for data that is not hosted there
   --assembly <name>     assembly to open (defaults to --hub)
-  --loc <locstring>     where to go: chr1:1,000-2,000, or several space-separated
-                        for a discontinuous view. On a config with a text index —
-                        every UCSC assembly on genomes.jbrowse.org has one — a
-                        gene name such as BRCA1 also works.
-  --track <trackId>     a track to open; repeat for several
-  --session <json|path> a full session spec, for several views or per-display
-                        settings. Replaces --assembly/--loc/--track.
+  --loc <locstring>     chr1:1,000-2,000, several space-separated, or a gene name
+                        where the config has a text index (hosted ones do)
+  --track <trackId>     a track to open, by trackId or name; repeat for several
+  --spec <json|path|->  a session spec, for several views or per-display settings
+  --session <path|->    a session saved with File → Export session
   --instance <url>      JBrowse Web deployment to drive
                         (default https://jbrowse.org/code/jb2/latest/)
-  --sessionName <name>  name the opened session carries
 
 THE IMAGE
-  --out, -o <file>      PNG to write (required unless using a subcommand)
+  --out, -o <file>      .png, .jpg or .webp to write (required unless using a
+                        subcommand)
   --width <px>          viewport width (default 1400)
   --height <px>         viewport height (default 900)
   --scale <n>           device pixel ratio (default 2)
-  --fullPage            capture the whole scrollable page, not just the viewport
+  --fullPage            grow the image until every view fits, not just the
+                        --height of the viewport
 
 WAITING
   --timeout <ms>        budget per wait stage (default 60000)
   --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
-  you asked for, the view resolving, tracks fetching, displays painting, and any
-  leftover "Loading…" text. A stage that times out FAILS the run rather than
-  quietly handing back a half-drawn frame — raise --timeout, or pass
-  --allowUnsettled if you want the frame as it stands.
+  A stage that times out fails the run rather than writing a half-drawn frame.
 
 OTHER
   --headed              run with a visible browser window
   --verbose             print browser console output (GPU noise filtered)
+  --version, -v         the package version
   --help, -h            this text
 
 EXAMPLES
@@ -62,16 +60,24 @@ EXAMPLES
   jb2capture --config https://example.org/config.json --assembly mydata \\
     --loc "chr3:25,325,000-25,361,000 chr10:58,716,500-58,718,500" -o two.png
 `;
-function readSession(value) {
-    const text = value.trimStart().startsWith('{')
-        ? value
-        : readFileSync(value, 'utf8');
+// inline JSON, `-` for stdin, or a path: the forms `jb2export --spec` reads
+function readJson(flag, value) {
+    const text = value === '-'
+        ? readFileSync(0, 'utf8')
+        : value.trimStart().startsWith('{')
+            ? value
+            : readFileSync(value, 'utf8');
     const parsed = JSON.parse(text);
     if (typeof parsed !== 'object' || parsed === null) {
-        throw new Error('--session must be a JSON object');
+        throw new Error(`--${flag} must be a JSON object`);
     }
     return parsed;
 }
+// a bare view object is the one-view spec it would be wrapped in
+function readSpec(value) {
+    const spec = readJson('spec', value);
+    return 'type' in spec && !('views' in spec) ? { views: [spec] } : spec;
+}
 function urlOptions(args) {
     return {
         hub: args.hub,
@@ -79,16 +85,24 @@ function urlOptions(args) {
         assembly: args.assembly,
         loc: args.loc,
         tracks: args.tracks.length ? args.tracks : undefined,
-        session: args.session ? readSession(args.session) : undefined,
-        sessionName: args.sessionName,
+        spec: args.spec ? readSpec(args.spec) : undefined,
+        session: args.session ? readJson('session', args.session) : undefined,
         instance: args.instance,
     };
 }
 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.');
+        const assemblies = await listHubAssemblies();
+        const pad = Math.max(...assemblies.map(a => a.name.length));
+        for (const a of assemblies) {
+            const about = [a.organism, a.description].filter(Boolean).join(' — ');
+            console.log(`  ${a.name.padEnd(pad)}  ${about}`);
+        }
+        console.log('\nGenArk accessions (GCA_…/GCF_…) work as --hub too; browse them at ' +
+            "https://genomes.jbrowse.org. List one assembly's tracks with " +
+            '`jb2capture list <name> [filter]`.');
+        return;
     }
     const tracks = await listHubTracks(hub, filter);
     if (!tracks.length) {
@@ -116,18 +130,23 @@ async function main() {
         console.log(HELP);
         return;
     }
+    if (args.version) {
+        const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(version);
+        return;
+    }
     if (first === 'list') {
         await runList(args.positionals);
         return;
     }
     if (first === 'url') {
-        console.log(jbrowseUrl(urlOptions(args)));
+        console.log(jbrowseUrl(await resolveAgainstConfig(urlOptions(args))));
         return;
     }
     if (!args.out) {
         throw new Error('--out <file.png> is required (or use `jb2capture url`)');
     }
-    const { url, pending, unsettled } = await captureJBrowse({
+    const { url, pending, tooLarge, unsettled } = await captureJBrowse({
         ...urlOptions(args),
         out: args.out,
         width: args.width,
@@ -155,7 +174,11 @@ async function main() {
     }
     if (pending.length) {
         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.`);
+            `(${describePendingDisplays(pending)}). Raise --timeout, or --settle for a slow remote file.`);
+    }
+    if (tooLarge.length) {
+        console.error(`warning: ${tooLarge.length} display(s) show "too much data" instead of their features ` +
+            `(${tooLarge.map(d => d.name).join(', ')}). Narrow --loc to draw them.`);
     }
 }
 try {

package/esm/browser.d.ts

@@ -1,4 +1,3 @@
-export declare const SANDBOX_CHROME_ARGS: string[];
 export declare const BASE_CHROME_ARGS: string[];
 export declare function findChromeExecutable(): string | undefined;
 export declare function isBrowserConsoleNoise(text: string): boolean;

package/esm/browser.js

@@ -1,15 +1,10 @@
 import fs from 'node:fs';
-// Just the sandbox flags, for the scripts that MEASURE cross-origin behaviour
-// (COOP/COEP isolation, cancelled cross-origin fetches) and would be measuring
-// nothing with web security off. They used to spell this
-// `BASE_CHROME_ARGS.filter(a => a !== '--disable-web-security')`, which silently
-// stops subtracting the day another security flag is added below.
-export const SANDBOX_CHROME_ARGS = ['--no-sandbox', '--disable-setuid-sandbox'];
 // Chrome flags both harnesses launch with. Backend-specific flags
 // (--disable-gpu, --enable-unsafe-swiftshader, --disable-popup-blocking) are
 // appended by each caller.
 export const BASE_CHROME_ARGS = [
-    ...SANDBOX_CHROME_ARGS,
+    '--no-sandbox',
+    '--disable-setuid-sandbox',
     '--disable-web-security',
 ];
 const CHROME_PATHS = [
@@ -30,10 +25,11 @@ const CHROME_PATHS = [
 export function findChromeExecutable() {
     return process.env.CHROME_PATH ?? CHROME_PATHS.find(p => fs.existsSync(p));
 }
-// GPU/WebGL lifecycle chatter that isn't a real error. Real GPU failures
-// (`context LOST`, `GL error`) are deliberately NOT suppressed.
+// Console chatter that isn't a real error. Real GPU failures (`context LOST`,
+// `GL error`) are deliberately NOT suppressed.
 const NOISE_NEEDLES = [
     'favicon',
+    'window.jb drives this app programmatically',
     'GPU stall',
     '[GPU] WebGPU not supported',
     '[GPU] No compatible GPU adapter',

package/esm/capture.d.ts

@@ -27,21 +27,22 @@ export interface OpenResult extends ReadyReport {
  * reading state back out of `window.JBrowseSession`, capturing a dialog. For a
  * plain image, `captureJBrowse` wraps the whole thing.
  *
- * The assembly and track count asked for in the URL become the session gate's
+ * The assembly and trackIds asked for in the URL become the session gate's
  * expectations unless you override them, so a mistyped trackId fails here rather
  * than producing an image of an empty browser.
  */
 export declare function openJBrowse(options?: OpenOptions): Promise<OpenResult>;
 export interface CaptureOptions extends OpenOptions {
-    /** PNG path to write. Omit to get the buffer back and write it yourself. */
+    /**
+     * Image path to write, `.png`, `.jpg`/`.jpeg` or `.webp`. Omit to get the PNG
+     * buffer back and write it yourself.
+     */
     out?: string;
     /**
-     * Capture the whole scrollable page rather than the viewport. Implemented by
-     * growing the viewport to the page height and re-settling, never by
-     * `page.screenshot({ fullPage: true })` — puppeteer implements that flag with
-     * the same viewport resize but shoots immediately, and the capture can return
-     * before the content re-rasters (measured in the browser-test suites as a
-     * 10–25% image diff that moves run to run).
+     * Capture every view rather than the viewport: the viewport grows by however
+     * far the session runs past it, and the frame is waited for again. Never
+     * puppeteer's `fullPage`, which measures the document (always the window's
+     * height here) and shoots before the resized content re-rasters.
      */
     fullPage?: boolean;
 }

package/esm/capture.js

@@ -2,10 +2,13 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import puppeteer from 'puppeteer';
 import { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';
-import { waitForJBrowseReady } from './ready.js';
-import { assemblyFromSession, trackIdsFromSession } from './session.js';
-import { jbrowseUrl } from './url.js';
-import { waitForAppSettled } from './waits.js';
+import { resolveAgainstConfig } from './catalog.js';
+import { assertImagePath } from './imagePath.js';
+import { assertSupportedInstance } from './instanceVersion.js';
+import { waitForFrame, waitForJBrowseReady } from './ready.js';
+import { assemblyFromSession, savedSnapshot, trackIdsFromSession, } from './session.js';
+import { sessionOverflowInPage } from './sessionOverflow.js';
+import { PUBLIC_INSTANCE, assertSessionStandsAlone, jbrowseUrl } from './url.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.
@@ -18,18 +21,21 @@ const DEFAULT_TIMEOUT = 60000;
  * reading state back out of `window.JBrowseSession`, capturing a dialog. For a
  * plain image, `captureJBrowse` wraps the whole thing.
  *
- * The assembly and track count asked for in the URL become the session gate's
+ * The assembly and trackIds asked for in the URL become the session gate's
  * expectations unless you override them, so a mistyped trackId fails here rather
  * than producing an image of an empty browser.
  */
 export async function openJBrowse(options = {}) {
-    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, timeout = 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
-    // have dropped it from the first, silently.
-    ...urlOptions } = options;
-    const url = jbrowseUrl(urlOptions);
+    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, timeout = DEFAULT_TIMEOUT, trackIds, ...given } = options;
+    assertSessionStandsAlone(given);
+    await assertSupportedInstance(given.instance ?? PUBLIC_INSTANCE);
+    const urlOptions = await resolveAgainstConfig(given);
+    // a named session keeps the header free of the timestamp an unnamed one gets,
+    // which otherwise differs on every capture of the same view
+    const url = jbrowseUrl({
+        ...urlOptions,
+        sessionName: urlOptions.sessionName ?? 'Screenshot',
+    });
     const browser = await puppeteer.launch({
         headless,
         executablePath,
@@ -50,28 +56,16 @@ export async function openJBrowse(options = {}) {
         // never go idle, and the session gate below is a far better "it is up"
         // signal than the absence of requests.
         await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
+        const { spec, session, assembly, hub, tracks } = urlOptions;
+        const opens = spec ?? (session && savedSnapshot(session));
+        // Spread rather than listed, so every ready option arrives by construction:
+        // a hand-copied list is what once dropped `allowUnsettled`.
         const report = await waitForJBrowseReady(page, {
-            // Spread, not a hand-copied field list. `OpenOptions extends
-            // ReadyOptions`, so every present and future ready option arrives here by
-            // construction. Listing them by hand is what dropped `allowUnsettled`:
-            // it was declared, documented, recommended by this function's own timeout
-            // message, and silently never forwarded, so `--allowUnsettled` did
-            // nothing and a timing-out stage always threw. Overridden below: the
-            // defaulted timeout, and the two options derived from the URL.
             ...options,
             timeout,
-            // A session spec's own assembly wins over the hub name. `--hub hg38
-            // --session spec.json` where the spec opens something else is legitimate
-            // (the hub is just supplying the config), and expecting the hub name there
-            // would fail a capture that is entirely correct.
-            assembly: urlOptions.session
-                ? (urlOptions.assembly ?? assemblyFromSession(urlOptions.session))
-                : (urlOptions.assembly ?? urlOptions.hub),
-            trackIds: trackIds ??
-                urlOptions.tracks ??
-                (urlOptions.session
-                    ? trackIdsFromSession(urlOptions.session)
-                    : undefined),
+            // a session may open another assembly than the hub that supplies its config
+            assembly: opens ? assemblyFromSession(opens) : (assembly ?? hub),
+            trackIds: trackIds ?? (opens ? trackIdsFromSession(opens) : tracks),
         });
         return { browser, page, url, ...report };
     }
@@ -90,35 +84,25 @@ export async function openJBrowse(options = {}) {
 export async function captureJBrowse(options = {}) {
     const { out, fullPage = false, ...openOptions } = options;
     if (out) {
-        // Before the browser launches: a missing parent directory otherwise fails
-        // at the screenshot, after the whole launch-navigate-wait cycle.
+        assertImagePath(out);
         mkdirSync(dirname(out), { recursive: true });
     }
-    const { browser, page, url, ...report } = await openJBrowse(openOptions);
+    const { browser, page, url, ...opened } = await openJBrowse(openOptions);
     try {
-        if (fullPage) {
-            const viewport = page.viewport();
-            const pageHeight = await page.evaluate(() => Math.ceil(Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)));
-            if (viewport && pageHeight > viewport.height) {
-                await page.setViewport({ ...viewport, height: pageHeight });
-                // The resize invalidates the raster and can start work (a display that
-                // grew gained rows to draw), so the frame has to settle again — 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.');
-                    }
-                }
-            }
+        let report = opened;
+        const overflow = fullPage ? await page.evaluate(sessionOverflowInPage) : 0;
+        const viewport = page.viewport();
+        if (viewport && overflow > 0) {
+            await page.setViewport({
+                ...viewport,
+                height: viewport.height + overflow,
+            });
+            // the resize repaints, and can start work, so the report describes the
+            // frame after it
+            report = await waitForFrame(page, {
+                ...openOptions,
+                timeout: openOptions.timeout ?? DEFAULT_TIMEOUT,
+            });
         }
         const image = await page.screenshot({ path: out });
         return { url, image, ...report };

package/esm/catalog.d.ts

@@ -0,0 +1,40 @@
+import type { JBrowseUrlOptions } from './url.ts';
+interface CatalogTrack {
+    trackId: string;
+    name?: unknown;
+}
+interface CatalogAssembly {
+    name: string;
+    aliases?: string[];
+}
+/** The parts of a JBrowse config.json that name what can be opened. */
+export interface Catalog {
+    assemblies?: CatalogAssembly[];
+    assembly?: CatalogAssembly;
+    tracks?: CatalogTrack[];
+}
+/**
+ * The canonical name of the assembly `input` names by name or alias, ignoring
+ * case. The canonical name is the one the app's census publishes, so the
+ * session gate compares against it rather than against an alias.
+ */
+export declare function resolveAssemblyName(catalog: Catalog, input: string): string;
+/**
+ * The trackId `input` names, resolved the way `jb2export --track` resolves one:
+ * an exact trackId, then the id with the assembly prefix a hosted config puts
+ * on every track (`clinvarMain` for `hg38-clinvarMain`), then a single
+ * case-insensitive match on the id, the unprefixed id or the display name. A
+ * miss names the tracks whose id or name contains what was typed.
+ */
+export declare function resolveTrackId(tracks: CatalogTrack[], input: string, assemblyName: string): string;
+/**
+ * The same options with the assembly and tracks checked against the config
+ * and spelled the way the config spells them, before any browser launches: a
+ * typo fails here with suggestions rather than as a session-gate timeout.
+ *
+ * A config this cannot fetch or parse passes through unchanged, and the app
+ * reports it. A spec or saved session passes through too, since it may declare
+ * tracks of its own that no config lists.
+ */
+export declare function resolveAgainstConfig(options: JBrowseUrlOptions): Promise<JBrowseUrlOptions>;
+export {};