@jbrowse/capture 4.3.0

package/esm/capture.d.ts

@@ -0,0 +1,113 @@
+import type { Instrumentation, PendingDisplay, SessionExpectations } from './sessionGate.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 {
+    width?: number;
+    height?: number;
+    /** 2 renders a retina-density image, which is what 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. */
+    onConsole?: (text: string) => void;
+}
+export interface OpenResult extends ReadyReport {
+    browser: Browser;
+    page: Page;
+    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.
+ */
+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. */
+    out?: string;
+    /** Capture the whole scrollable page rather than the viewport. */
+    fullPage?: boolean;
+}
+export interface CaptureResult extends ReadyReport {
+    url: string;
+    image: Uint8Array;
+}
+/**
+ * Open a JBrowse session, wait for it to render, screenshot it, close the
+ * browser. The one-call form.
+ */
+export declare function captureJBrowse(options?: CaptureOptions): Promise<CaptureResult>;

package/esm/capture.js

@@ -0,0 +1,273 @@
+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;
+/**
+ * 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.
+ */
+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],
+    });
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({ width, height, deviceScaleFactor });
+        if (onConsole) {
+            page.on('console', msg => {
+                const text = msg.text();
+                if (!isBrowserConsoleNoise(text)) {
+                    onConsole(text);
+                }
+            });
+        }
+        // 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.
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
+        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),
+        });
+        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();
+        throw error;
+    }
+}
+/**
+ * Open a JBrowse session, wait for it to render, screenshot it, close the
+ * browser. The one-call form.
+ */
+export async function captureJBrowse(options = {}) {
+    const { out, fullPage = false, ...openOptions } = options;
+    const { browser, page, url, ...report } = await openJBrowse(openOptions);
+    try {
+        const image = await page.screenshot({ path: out, fullPage });
+        return { url, image, ...report };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/esm/hub.d.ts

@@ -0,0 +1,23 @@
+export declare function hubUrl(hub: string): string;
+interface HubTrack {
+    trackId: string;
+    type?: string;
+    name?: string;
+}
+interface HubConfig {
+    tracks?: HubTrack[];
+    [key: string]: unknown;
+}
+/**
+ * Fetch a hosted assembly config from genomes.jbrowse.org by UCSC database name
+ * or GenArk accession. Use it to discover which trackIds an assembly publishes
+ * before naming them in a session.
+ */
+export declare function fetchHubConfig(hub: string): Promise<HubConfig>;
+/**
+ * The trackIds a hosted assembly publishes, optionally narrowed to those whose
+ * id or display name contains `filter`. Case-insensitive, because a hub carries
+ * hundreds of tracks and an agent picking one from a name is the common case.
+ */
+export declare function listHubTracks(hub: string, filter?: string): Promise<HubTrack[]>;
+export {};

package/esm/hub.js

@@ -0,0 +1,43 @@
+const HUB_HOST = 'https://jbrowse.org';
+// The genomes.jbrowse.org URL scheme: a UCSC database name (hg38, mm10, ...)
+// maps to /ucsc/<db>/config.json; a GenArk accession (GCA_/GCF_...) fans its 9
+// digits out into a 3-level directory tree.
+//
+// Deliberately a copy of `hubUrl` in packages/core/src/util/fetchHub.ts rather
+// than an import of it. This package is what an agent reaches for with a bare
+// `npx`, and its only runtime dependency is puppeteer; pulling in @jbrowse/core
+// (react, mobx, the whole state tree) to evaluate one regex would be the largest
+// thing in the install by far. `hub.test.ts` imports both and asserts they agree
+// on every shape, so the copy cannot drift silently.
+export function hubUrl(hub) {
+    const genark = /^(GC[AF])_(\d{3})(\d{3})(\d{3})/.exec(hub);
+    return genark
+        ? `${HUB_HOST}/hubs/genark/${genark[1]}/${genark[2]}/${genark[3]}/${genark[4]}/${hub}/config.json`
+        : `${HUB_HOST}/ucsc/${hub}/config.json`;
+}
+/**
+ * Fetch a hosted assembly config from genomes.jbrowse.org by UCSC database name
+ * or GenArk accession. Use it to discover which trackIds an assembly publishes
+ * before naming them in a session.
+ */
+export async function fetchHubConfig(hub) {
+    const url = hubUrl(hub);
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`hub "${hub}" not found (HTTP ${res.status} from ${url}). ` +
+            'See https://genomes.jbrowse.org for the available assemblies.');
+    }
+    return (await res.json());
+}
+/**
+ * The trackIds a hosted assembly publishes, optionally narrowed to those whose
+ * id or display name contains `filter`. Case-insensitive, because a hub carries
+ * hundreds of tracks and an agent picking one from a name is the common case.
+ */
+export async function listHubTracks(hub, filter) {
+    const { tracks = [] } = await fetchHubConfig(hub);
+    const needle = filter?.toLowerCase();
+    return needle
+        ? tracks.filter(t => `${t.trackId} ${t.name ?? ''}`.toLowerCase().includes(needle))
+        : tracks;
+}

package/esm/index.d.ts

@@ -0,0 +1,10 @@
+export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.ts';
+export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, 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';
+export { APP_READY, BUSY_SELECTOR, LOADING_OVERLAY, PENDING_DISPLAYS, delay, describePendingDisplaysNow, displayById, displayPainted, displaySettled, hasAppReadyMarker, isPageBusyInPage, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForSelectorAttributed, waitForViewPhases, } from './waits.ts';
+export { BASE_CHROME_ARGS, SANDBOX_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.ts';
+export type { CaptureOptions, CaptureResult, OpenOptions, OpenResult, ReadyOptions, ReadyReport, } from './capture.ts';
+export type { Instrumentation, PendingDisplay, SessionExpectations, SessionSummary, } from './sessionGate.ts';
+export type { JBrowseUrlOptions } from './url.ts';

package/esm/index.js

@@ -0,0 +1,7 @@
+export { captureJBrowse, openJBrowse, waitForJBrowseReady } from './capture.js';
+export { PAINT_CONTRACT_NOTE, describePendingDisplays, hasPaintContract, pendingDisplayStates, pendingDisplayStatesInPage, pendingDisplays, readInstrumentation, 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';
+export { APP_READY, BUSY_SELECTOR, LOADING_OVERLAY, PENDING_DISPLAYS, delay, describePendingDisplaysNow, displayById, displayPainted, displaySettled, hasAppReadyMarker, isPageBusyInPage, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForQuietPeriod, waitForSelectorAttributed, waitForViewPhases, } from './waits.js';
+export { BASE_CHROME_ARGS, SANDBOX_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';

package/esm/session.d.ts

@@ -0,0 +1,25 @@
+export declare function sessionSpecParam(session: object): string;
+export declare function encodeSessionSpec(session: object): string;
+/**
+ * The assembly a session spec's first view opens, if it names one.
+ *
+ * The session gate needs this because a spec can be loaded against any config —
+ * `--hub hg38 --session spec.json` where the spec opens a different assembly is
+ * legitimate, and defaulting the expectation to the hub name would fail a
+ * perfectly good capture.
+ */
+export declare function assemblyFromSession(session: object): string | undefined;
+/**
+ * Every trackId a session spec asks a view to open, including nested views (a
+ * synteny or breakpoint-split spec puts its LGVs one level down).
+ *
+ * Used as the session gate's expectation: it is what turns "the browser loaded"
+ * into "the tracks I named are open", and a spec is the one input where the
+ * caller has not spelled those ids out separately.
+ */
+export declare function trackIdsFromSession(session: object): string[];
+export declare function sessionSpecQuery({ config, session, sessionName, }: {
+    config: string;
+    session: object;
+    sessionName?: string;
+}): string;

package/esm/session.js

@@ -0,0 +1,61 @@
+// The DECODED value of the `session=` query param that jbrowse-web reads to open
+// a declarative session without a saved-session backend: a `spec-` prefix plus
+// the session JSON. This is what the app sees after the query string is parsed,
+// so it is the right thing to hand to `URLSearchParams.set`, which does its own
+// encoding.
+export function sessionSpecParam(session) {
+    return `spec-${JSON.stringify(session)}`;
+}
+// The same value pre-encoded, for callers that concatenate a query string by
+// hand rather than going through URL. Passing THIS to `URLSearchParams.set`
+// encodes it a second time, and the app then decodes once and parses `%7B…` as
+// JSON — so pick one path and stay on it. Shared so the runner and screenshot
+// generator can't drift on the encoding.
+export function encodeSessionSpec(session) {
+    return encodeURIComponent(sessionSpecParam(session));
+}
+/**
+ * The assembly a session spec's first view opens, if it names one.
+ *
+ * The session gate needs this because a spec can be loaded against any config —
+ * `--hub hg38 --session spec.json` where the spec opens a different assembly is
+ * legitimate, and defaulting the expectation to the hub name would fail a
+ * perfectly good capture.
+ */
+export function assemblyFromSession(session) {
+    const find = (views) => {
+        for (const view of views ?? []) {
+            const found = view.assembly ?? find(view.views);
+            if (found) {
+                return found;
+            }
+        }
+        return undefined;
+    };
+    return find(session.views);
+}
+/**
+ * Every trackId a session spec asks a view to open, including nested views (a
+ * synteny or breakpoint-split spec puts its LGVs one level down).
+ *
+ * Used as the session gate's expectation: it is what turns "the browser loaded"
+ * into "the tracks I named are open", and a spec is the one input where the
+ * caller has not spelled those ids out separately.
+ */
+export function trackIdsFromSession(session) {
+    const collect = (views) => (views ?? []).flatMap(view => [
+        // an entry may be a bare id or `{trackId, displaySnapshot}`; an object
+        // without a trackId is malformed rather than a track to expect, so it
+        // drops out here instead of gating on undefined
+        ...(view.tracks ?? [])
+            .map(t => (typeof t === 'string' ? t : t.trackId))
+            .filter(id => id !== undefined),
+        ...collect(view.views),
+    ]);
+    return collect(session.views);
+}
+// Full `?config=…&session=…&sessionName=…` query string. `config` is inserted
+// as-is (callers that point at a remote absolute URL pre-encode it themselves).
+export function sessionSpecQuery({ config, session, sessionName = 'Screenshot', }) {
+    return `?config=${config}&session=${encodeSessionSpec(session)}&sessionName=${encodeURIComponent(sessionName)}`;
+}