@jbrowse/capture 4.3.0 → 5.0.0-beta.10

package/esm/browser.js

@@ -1,44 +1,36 @@
 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,
-    '--disable-web-security',
-];
+import puppeteer from 'puppeteer';
+export const BASE_CHROME_ARGS = ['--no-sandbox', '--disable-setuid-sandbox'];
 const CHROME_PATHS = [
     '/usr/bin/google-chrome',
     '/usr/bin/chromium-browser',
     '/usr/bin/chromium',
 ];
-// First installed system Chrome/Chromium, or undefined to let Puppeteer use its
-// bundled browser. `CHROME_PATH` wins, so a run can be pinned to one binary --
-// which is how you answer "did the browser move under us?" when a figure regen
-// reports the whole corpus as changed.
-//
-// Measured 2026-08-02, because that question came up and the answer was no: the
-// same spec rendered under Chrome 147.0.7727.57 and 151.0.7922.47 produces
-// byte-identical PNGs, and the system package's 151.0.7922.47 -> .71 roll
-// likewise changed nothing. So a corpus-wide diff is accumulated app change
-// since the last `Bump snaps` sweep, not the browser -- don't chase it here.
+// `CHROME_PATH`, then a system Chrome, then undefined for Puppeteer's own
 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.
+/**
+ * The browser `openJBrowse` drives, for a page it cannot open itself: an
+ * embedded view on your own host page, navigated and then waited on with
+ * `waitForJBrowseReady`.
+ */
+export function launchBrowser({ headless = true, executablePath = findChromeExecutable(), args = [], } = {}) {
+    return puppeteer.launch({
+        headless,
+        executablePath,
+        args: [...BASE_CHROME_ARGS, ...args],
+    });
+}
 const NOISE_NEEDLES = [
     'favicon',
+    'window.jb drives this app programmatically',
     'GPU stall',
     '[GPU] WebGPU not supported',
     '[GPU] No compatible GPU adapter',
     '[GPU] WebGPU initialization failed',
     '[GPU] WebGL2 unavailable',
+    '[GPU] WebGL2 here is software-rendered',
     '[GPU] WebGPU device creation failed',
     'GroupMarkerNotSet',
     'Automatic fallback to software WebGL',

package/esm/capture.d.ts

@@ -1,81 +1,13 @@
-import type { Instrumentation, PendingDisplay, SessionExpectations } from './sessionGate.ts';
+import type { LaunchOptions } from './browser.ts';
+import type { ReadyOptions, ReadyReport } from './ready.ts';
 import type { JBrowseUrlOptions } from './url.ts';
 import type { Browser, Page } from 'puppeteer';
-export interface ReadyOptions extends SessionExpectations {
-    /** Budget for each individual wait stage. */
-    timeout?: number;
-    /**
-     * Also wait out adapter "Downloading…" status text, which can outlive the
-     * loading overlay when a track streams a large remote file.
-     */
-    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.
-     */
-    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
-     * one. The unsettled stages are still listed in the report either way.
-     */
-    allowUnsettled?: boolean;
-}
-export interface ReadyReport {
-    /** Displays still reporting unpainted at the end of the wait. */
-    pending: string[];
-    /**
-     * The same displays with the phase each one publishes, which is what
-     * separates a slow fetch from a display that says it finished without
-     * 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.
- */
-export declare function waitForJBrowseReady(page: Page, { timeout, waitForDownloads, settleMs, expectSession, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;
-export interface OpenOptions extends JBrowseUrlOptions, ReadyOptions {
+export interface OpenOptions extends JBrowseUrlOptions, ReadyOptions, LaunchOptions {
     width?: number;
     height?: number;
-    /** 2 renders a retina-density image, which is what a figure usually wants. */
+    /** Device pixel ratio. Default 2, the density a figure usually wants. */
     deviceScaleFactor?: number;
-    headless?: boolean;
-    /** Chrome binary. Defaults to $CHROME_PATH, a system Chrome, then Puppeteer's own. */
-    executablePath?: string;
-    /** Extra Chrome flags, appended to the defaults. */
-    args?: string[];
-    /** Called with each page console message that is not known GPU noise. */
+    /** Called with each page console message that is not known GPU noise, and each uncaught page error. */
     onConsole?: (text: string) => void;
 }
 export interface OpenResult extends ReadyReport {
@@ -84,22 +16,22 @@ export interface OpenResult extends ReadyReport {
     url: string;
 }
 /**
- * Launch a browser, navigate to a JBrowse session, and wait until it has
- * rendered. The caller owns the returned browser and must close it.
- *
- * Use this when the screenshot is not the end of the job: clicking a feature,
- * 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
- * expectations unless you override them, so a mistyped trackId fails here rather
- * than producing an image of an empty browser.
+ * Launch a browser, open a JBrowse session, and wait until it has rendered.
+ * The caller owns the returned browser and must close it. The assembly and
+ * tracks asked for become the session gate's expectations unless `trackIds`
+ * names others.
  */
 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. */
+    /**
+     * 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.
+     */
     fullPage?: boolean;
 }
 export interface CaptureResult extends ReadyReport {
@@ -107,7 +39,7 @@ export interface CaptureResult extends ReadyReport {
     image: Uint8Array;
 }
 /**
- * Open a JBrowse session, wait for it to render, screenshot it, close the
- * browser. The one-call form.
+ * Open a JBrowse session, wait for it to render, screenshot it, and close the
+ * browser.
  */
 export declare function captureJBrowse(options?: CaptureOptions): Promise<CaptureResult>;

package/esm/capture.js

@@ -1,213 +1,33 @@
-import puppeteer from 'puppeteer';
-import { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';
-import { assemblyFromSession, trackIdsFromSession } from './session.js';
-import { describePendingDisplays, hasPaintContract, pendingDisplayStates, readInstrumentation, readSessionSummary, waitForSession, } from './sessionGate.js';
-import { jbrowseUrl } from './url.js';
-import { delay, hasAppReadyMarker, waitForAppReady, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForViewPhases, } from './waits.js';
-// 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 { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isBrowserConsoleNoise, launchBrowser } from './browser.js';
+import { resolveAgainstConfig } from './catalog.js';
+import { assertImagePath } from './imagePath.js';
+import { assertSupportedInstance } from './instanceVersion.js';
+import { DEFAULT_TIMEOUT } from './poll.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';
 /**
- * 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.
- */
-export async function waitForJBrowseReady(page, { timeout = 60000, waitForDownloads = true, settleMs = 0, expectSession = true, assembly, trackIds, allowUnsettled = false, } = {}) {
-    const unsettled = [];
-    const stage = async (name, work) => {
-        if (!(await work)) {
-            unsettled.push(name);
-        }
-    };
-    // 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 });
-    }
-    // 1. THE WHOLE ANSWER, on any build that has it: the session renders
-    //    `[data-app-phase="ready"]` when no view is resolving an assembly and no
-    //    display is fetching. It is positive, so unlike everything below it
-    //    cannot be satisfied by an app that has not started, and there is nothing
-    //    to assemble — wait for the selector and stop.
-    //
-    //    Everything after this point is the fallback for a deployment older than
-    //    the marker, and can be deleted the day the oldest supported build has
-    //    it.
-    if (await hasAppReadyMarker(page)) {
-        const ready = await waitForAppReady(page, { timeout });
-        if (!ready) {
-            unsettled.push('the app never reported 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 here instead of absorbing the banner as expected output.
-        // Ordered after the marker rather than instead of it, which is what makes an
-        // absence meaningful (see waitForDisplaysDone), and free on a page that has
-        // no such canvas.
-        await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
-        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, pendingStates));
-        }
-        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.
-    const summary = await readSessionSummary(page);
-    const needsQuietGate = !instrumented && (summary?.trackIds.length ?? 0) > 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));
-    // 2. no track is still fetching. One call, two outcomes: the overlay half is
-    //    required (an overlay that never clears is a fetch that never finished,
-    //    with nothing behind it) and throws; the "Downloading…" half is
-    //    best-effort and comes back as the boolean.
-    const downloadsSettled = await required('the loading overlay never cleared (a track fetch never finished)', waitForLoadingComplete(page, { timeout, waitForDownloads }));
-    if (!downloadsSettled) {
-        unsettled.push('a track was still downloading');
-    }
-    await stage('a display was still in its loading phase', waitForDisplayPhases(page, timeout));
-    // 3. no display is still pending its first paint
-    await stage('a display never reported its first paint', waitForDisplaysDone(page, timeout));
-    // 4. no visible "Loading…/Rendering…/Computing…" text remains, which is how
-    //    the views that publish no phase attribute report themselves
-    await stage('a "Loading…/Rendering…" label was still on screen', waitForQuiescent(page, { timeout }));
-    // 5. 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);
-    }
-    if (settleMs > 0) {
-        await delay(settleMs);
-    }
-    const pendingStates = await pendingDisplayStates(page);
-    const report = {
-        pending: pendingStates.map(d => d.name),
-        pendingStates,
-        paintContract,
-        unsettled,
-        instrumentation,
-        appMarker: false,
-    };
-    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, pendingStates));
-    }
-    return report;
-}
-/**
- * What a timed-out wait says. The stage names alone were the whole message, and
- * they name the QUESTION rather than the answer — "a display never reported its
- * first paint" reads identically for a slow fetch, a failed one and a display
- * that never had a canvas to paint. Appending the census answers it, and the
- * `ready` case is the one that most changes what a reader does next: a longer
- * timeout is the fix for `loading` and never the fix for that.
- */
-function unsettledMessage(timeout, unsettled, pending) {
-    return (`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ${pending.length > 0
-        ? `Still unpainted: ${describePendingDisplays(pending)}. `
-        : ''}Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ` +
-        `capture the frame as it stands.`);
-}
-/**
- * Launch a browser, navigate to a JBrowse session, and wait until it has
- * rendered. The caller owns the returned browser and must close it.
- *
- * Use this when the screenshot is not the end of the job: clicking a feature,
- * 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
- * expectations unless you override them, so a mistyped trackId fails here rather
- * than producing an image of an empty browser.
+ * Launch a browser, open a JBrowse session, and wait until it has rendered.
+ * The caller owns the returned browser and must close it. The assembly and
+ * tracks asked for become the session gate's expectations unless `trackIds`
+ * names others.
  */
 export async function openJBrowse(options = {}) {
-    const { width = 1400, height = 900, deviceScaleFactor = 2, headless = true, executablePath = findChromeExecutable(), args = [], onConsole, timeout, trackIds, 
-    // Pulled out only to keep them out of `urlOptions`, which becomes the
-    // query string. They reach the ready wait through the `...options` spread
-    // below rather than from here.
-    waitForDownloads: _waitForDownloads, settleMs: _settleMs, expectSession: _expectSession, allowUnsettled: _allowUnsettled, 
-    // `assembly` is deliberately NOT pulled out here: it is both a URL option
-    // (which assembly to open) and the session gate's expectation (which
-    // assembly must end up open), and destructuring it for the second use would
-    // have dropped it from the first, silently.
-    ...urlOptions } = options;
-    const url = jbrowseUrl(urlOptions);
-    const browser = await puppeteer.launch({
-        headless,
-        executablePath,
-        args: [...BASE_CHROME_ARGS, ...args],
+    const { width = 1400, height = 900, deviceScaleFactor = 2, headless, executablePath, args, onConsole, timeout = DEFAULT_TIMEOUT, trackIds, ...given } = options;
+    assertSessionStandsAlone(given);
+    const [urlOptions] = await Promise.all([
+        resolveAgainstConfig(given),
+        assertSupportedInstance(given.instance ?? PUBLIC_INSTANCE),
+    ]);
+    // named, so the header carries no timestamp that differs on every capture
+    const url = jbrowseUrl({
+        ...urlOptions,
+        sessionName: urlOptions.sessionName ?? 'Screenshot',
     });
+    const browser = await launchBrowser({ headless, executablePath, args });
     try {
         const page = await browser.newPage();
         await page.setViewport({ width, height, deviceScaleFactor });
@@ -218,53 +38,50 @@ export async function openJBrowse(options = {}) {
                     onConsole(text);
                 }
             });
+            page.on('pageerror', error => {
+                onConsole(`uncaught ${error instanceof Error ? error.stack : error}`);
+            });
         }
-        // domcontentloaded, not networkidle2: an app that streams track data may
-        // never go idle, and the session gate below is a far better "it is up"
-        // signal than the absence of requests.
+        // an app streaming track data may never reach networkidle; the session
+        // gate is the signal that it is up
         await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
+        const { spec, session, assembly, hub, tracks } = urlOptions;
+        const opens = spec ?? (session && savedSnapshot(session));
         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. Only the two options
-            // derived from the URL are overridden below.
             ...options,
-            // 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.assembly ??
-                (urlOptions.session
-                    ? assemblyFromSession(urlOptions.session)
-                    : undefined) ??
-                (urlOptions.session ? undefined : urlOptions.hub),
-            trackIds: trackIds ??
-                urlOptions.tracks ??
-                (urlOptions.session
-                    ? trackIdsFromSession(urlOptions.session)
-                    : undefined),
+            assembly: opens ? assemblyFromSession(opens) : (assembly ?? hub),
+            trackIds: trackIds ?? (opens ? trackIdsFromSession(opens) : tracks),
         });
         return { browser, page, url, ...report };
     }
     catch (error) {
-        // A launch that got as far as a page and then failed still holds a Chrome
-        // process; without this the caller has no handle to close it.
-        await browser.close();
+        await browser.close().catch(() => { });
         throw error;
     }
 }
 /**
- * Open a JBrowse session, wait for it to render, screenshot it, close the
- * browser. The one-call form.
+ * Open a JBrowse session, wait for it to render, screenshot it, and close the
+ * browser.
  */
 export async function captureJBrowse(options = {}) {
     const { out, fullPage = false, ...openOptions } = options;
-    const { browser, page, url, ...report } = await openJBrowse(openOptions);
+    if (out) {
+        assertImagePath(out);
+        mkdirSync(dirname(out), { recursive: true });
+    }
+    const { browser, page, url, ...opened } = await openJBrowse(openOptions);
     try {
-        const image = await page.screenshot({ path: out, fullPage });
+        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,
+            });
+            report = await waitForFrame(page, openOptions);
+        }
+        const image = await page.screenshot({ path: out });
         return { url, image, ...report };
     }
     finally {

package/esm/catalog.d.ts

@@ -0,0 +1,32 @@
+import type { Track } from './hub.ts';
+import type { JBrowseUrlOptions } from './url.ts';
+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?: Track[];
+}
+/**
+ * The canonical name of the assembly `input` names by name or alias, ignoring
+ * case: the name the app's census publishes.
+ */
+export declare function resolveAssemblyName(catalog: Catalog, input: string): string;
+/**
+ * The trackId `input` names: an exact trackId, then the id with the assembly
+ * prefix a hosted config puts on every track, then a single case-insensitive
+ * match on the id, the unprefixed id or the display name. A miss suggests the
+ * tracks whose id or name contains the input.
+ */
+export declare function resolveTrackId(tracks: Track[], input: string, assemblyName: string): string;
+/**
+ * The options with the assembly and tracks checked against the config and
+ * spelled the way it spells them, so a typo fails before a browser launches.
+ * A config this cannot fetch passes through for the app to judge, and so does
+ * a spec or saved session, which may declare tracks no config lists.
+ */
+export declare function resolveAgainstConfig(options: JBrowseUrlOptions): Promise<JBrowseUrlOptions>;
+export {};

package/esm/catalog.js

@@ -0,0 +1,84 @@
+import { fetchJson, hubUrl, trackName, tracksMatching } from './hub.js';
+import { instanceUrl } from './url.js';
+const assembliesOf = (catalog) => catalog.assemblies ?? (catalog.assembly ? [catalog.assembly] : []);
+/**
+ * The canonical name of the assembly `input` names by name or alias, ignoring
+ * case: the name the app's census publishes.
+ */
+export function resolveAssemblyName(catalog, input) {
+    const assemblies = assembliesOf(catalog);
+    const target = input.toLowerCase();
+    const found = assemblies.find(a => [a.name, ...(a.aliases ?? [])].some(n => n.toLowerCase() === target));
+    if (!found) {
+        const names = assemblies.map(a => a.name).join(', ');
+        throw new Error(`assembly "${input}" is not in the config, which has ${names || 'none'}`);
+    }
+    return found.name;
+}
+/**
+ * The trackId `input` names: an exact trackId, then the id with the assembly
+ * prefix a hosted config puts on every track, then a single case-insensitive
+ * match on the id, the unprefixed id or the display name. A miss suggests the
+ * tracks whose id or name contains the input.
+ */
+export function resolveTrackId(tracks, input, assemblyName) {
+    const ids = new Set(tracks.map(t => t.trackId));
+    const prefixed = `${assemblyName}-${input}`;
+    if (ids.has(input)) {
+        return input;
+    }
+    if (ids.has(prefixed)) {
+        return prefixed;
+    }
+    const target = input.toLowerCase();
+    const prefix = `${assemblyName}-`.toLowerCase();
+    const loose = tracks.filter(t => {
+        const id = t.trackId.toLowerCase();
+        return (id === target ||
+            (id.startsWith(prefix) && id.slice(prefix.length) === target) ||
+            trackName(t).toLowerCase() === target);
+    });
+    if (loose.length === 1) {
+        return loose[0].trackId;
+    }
+    if (loose.length > 1) {
+        throw new Error(`--track "${input}" is ambiguous; matches: ${loose.map(t => t.trackId).join(', ')}`);
+    }
+    const suggestions = tracksMatching(tracks, input)
+        .slice(0, 8)
+        .map(t => t.trackId);
+    const hint = suggestions.length
+        ? `. Did you mean: ${suggestions.join(', ')}?`
+        : '';
+    throw new Error(`--track "${input}" is not in the config${hint}`);
+}
+/**
+ * The options with the assembly and tracks checked against the config and
+ * spelled the way it spells them, so a typo fails before a browser launches.
+ * A config this cannot fetch passes through for the app to judge, and so does
+ * a spec or saved session, which may declare tracks no config lists.
+ */
+export async function resolveAgainstConfig(options) {
+    const { hub, config, assembly, tracks, spec, session, instance } = options;
+    const wanted = assembly ?? hub;
+    const url = config
+        ? new URL(config, instanceUrl(instance)).href
+        : hub
+            ? hubUrl(hub)
+            : undefined;
+    if (spec || session || !url || (!wanted && !tracks?.length)) {
+        return options;
+    }
+    const catalog = (await fetchJson(url, 'config').catch(() => undefined));
+    if (!catalog) {
+        return options;
+    }
+    const assemblyName = wanted
+        ? resolveAssemblyName(catalog, wanted)
+        : assembliesOf(catalog)[0]?.name;
+    return {
+        ...options,
+        assembly: wanted ? assemblyName : undefined,
+        tracks: tracks?.map(t => resolveTrackId(catalog.tracks ?? [], t, assemblyName ?? '')),
+    };
+}