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

package/esm/catalog.js

@@ -0,0 +1,103 @@
+import { hubUrl } from './hub.js';
+import { PUBLIC_INSTANCE } from './url.js';
+const CATALOG_FETCH_TIMEOUT_MS = 30000;
+const trackName = (track) => typeof track.name === 'string' ? track.name : '';
+const assembliesOf = (catalog) => catalog.assemblies ?? (catalog.assembly ? [catalog.assembly] : []);
+/**
+ * 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 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, 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 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 = tracks
+        .filter(t => `${t.trackId} ${trackName(t)}`.toLowerCase().includes(target))
+        .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}`);
+}
+async function fetchCatalog(url) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(CATALOG_FETCH_TIMEOUT_MS),
+        });
+        return res.ok ? (await res.json()) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 async function resolveAgainstConfig(options) {
+    const { hub, config, assembly, tracks, spec, session, instance = PUBLIC_INSTANCE, } = options;
+    const wanted = assembly ?? hub;
+    const url = config
+        ? new URL(config, instance).href
+        : hub
+            ? hubUrl(hub)
+            : undefined;
+    if (spec || session || !url || (!wanted && !tracks?.length)) {
+        return options;
+    }
+    const catalog = await fetchCatalog(url);
+    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 ?? '')),
+    };
+}

package/esm/hub.d.ts

@@ -14,6 +14,16 @@ interface HubConfig {
  * before naming them in a session.
  */
 export declare function fetchHubConfig(hub: string): Promise<HubConfig>;
+interface HostedAssembly {
+    name: string;
+    organism?: string;
+    description?: string;
+}
+/**
+ * The UCSC assemblies genomes.jbrowse.org hosts, by name. GenArk accessions
+ * are hosted too, thousands of them, and are not in this list.
+ */
+export declare function listHubAssemblies(): Promise<HostedAssembly[]>;
 /**
  * The trackIds a hosted assembly publishes, optionally narrowed to those whose
  * id or display name contains `filter`. Case-insensitive, because a hub carries

package/esm/hub.js

@@ -16,31 +16,46 @@ export function hubUrl(hub) {
         ? `${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);
-    // Without the signal a stalled connection hangs `jb2capture list` forever:
-    // fetch has no timeout of its own, and this is the one request the tool makes
-    // outside puppeteer's budget.
+const BROWSE_HINT = 'See https://genomes.jbrowse.org for the available assemblies.';
+// Bounded: fetch has no timeout of its own, and these are the requests the tool
+// makes outside puppeteer's budget, so without it a stalled connection hangs
+// `jb2capture list` forever.
+async function fetchHosted(url, what) {
     const res = await fetch(url, {
         signal: AbortSignal.timeout(HUB_FETCH_TIMEOUT_MS),
     }).catch((error) => {
         // The budget is only part of the diagnosis when it is what fired; naming it
         // on a DNS failure reads as though the request had been given 30s to resolve.
         const timedOut = error instanceof Error && error.name === 'TimeoutError';
-        throw new Error(`hub "${hub}" could not be fetched from ${url} ` +
-            `(${error instanceof Error ? error.message : error}${timedOut ? `, after ${HUB_FETCH_TIMEOUT_MS}ms` : ''}). ` +
-            'See https://genomes.jbrowse.org for the available assemblies.');
+        throw new Error(`${what} could not be fetched from ${url} ` +
+            `(${error instanceof Error ? error.message : error}${timedOut ? `, after ${HUB_FETCH_TIMEOUT_MS}ms` : ''}). ${BROWSE_HINT}`);
     });
     if (!res.ok) {
-        throw new Error(`hub "${hub}" not found (HTTP ${res.status} from ${url}). ` +
-            'See https://genomes.jbrowse.org for the available assemblies.');
+        throw new Error(`${what} not found (HTTP ${res.status} from ${url}). ${BROWSE_HINT}`);
     }
-    return (await res.json());
+    return res.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) {
+    return (await fetchHosted(hubUrl(hub), `hub "${hub}"`));
+}
+/**
+ * The UCSC assemblies genomes.jbrowse.org hosts, by name. GenArk accessions
+ * are hosted too, thousands of them, and are not in this list.
+ */
+export async function listHubAssemblies() {
+    const { ucscGenomes = {} } = (await fetchHosted(`${HUB_HOST}/ucsc/list.json`, 'the hosted assembly list'));
+    return Object.entries(ucscGenomes)
+        .map(([name, { organism, description }]) => ({
+        name,
+        organism,
+        description,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
  * The trackIds a hosted assembly publishes, optionally narrowed to those whose

package/esm/imagePath.d.ts

@@ -0,0 +1 @@
+export declare function assertImagePath(out: string): void;

package/esm/imagePath.js

@@ -0,0 +1,8 @@
+// The types puppeteer infers from a path; it writes a PNG under any other name.
+const IMAGE_EXTENSION = /\.(png|jpe?g|webp)$/i;
+export function assertImagePath(out) {
+    if (!IMAGE_EXTENSION.test(out)) {
+        throw new Error(`--out needs a .png, .jpg, .jpeg or .webp path, got "${out}" ` +
+            '(for SVG, @jbrowse/img renders one without a browser)');
+    }
+}

package/esm/index.d.ts

@@ -1,12 +1,12 @@
 export { captureJBrowse, openJBrowse } from './capture.ts';
-export { waitForJBrowseReady } from './ready.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';
-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 { delay } from './poll.ts';
+export { waitForFrame, waitForJBrowseReady } from './ready.ts';
+export { describePendingDisplays, pendingDisplayStatesInPage, waitForSession, } from './sessionGate.ts';
+export { jbrowseUrl } from './url.ts';
+export { assemblyFromSession, encodeSessionSpec, sessionSpecQuery, trackIdsFromSession, } from './session.ts';
+export { ANIMATING_DISPLAYS, PENDING_DISPLAYS, displayPainted, displaySettled, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForSelectorAttributed, waitForViewPhases, } from './waits.ts';
+export { BASE_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 { PendingDisplay, SessionExpectations, SessionSummary, } from './sessionGate.ts';
+export type { PendingDisplay, SessionExpectations } from './sessionGate.ts';
 export type { JBrowseUrlOptions } from './url.ts';

package/esm/index.js

@@ -1,8 +1,8 @@
 export { captureJBrowse, openJBrowse } from './capture.js';
-export { waitForJBrowseReady } from './ready.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';
-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';
+export { delay } from './poll.js';
+export { waitForFrame, waitForJBrowseReady } from './ready.js';
+export { describePendingDisplays, pendingDisplayStatesInPage, waitForSession, } from './sessionGate.js';
+export { jbrowseUrl } from './url.js';
+export { assemblyFromSession, encodeSessionSpec, sessionSpecQuery, trackIdsFromSession, } from './session.js';
+export { ANIMATING_DISPLAYS, PENDING_DISPLAYS, displayPainted, displaySettled, waitForAppReady, waitForAppSettled, waitForDisplayPhases, waitForDisplaysDone, waitForLoadingComplete, waitForQuiescent, waitForSelectorAttributed, waitForViewPhases, } from './waits.js';
+export { BASE_CHROME_ARGS, findChromeExecutable, isBrowserConsoleNoise, } from './browser.js';

package/esm/instanceVersion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Refuse a JBrowse Web instance older than v5 before launching a browser at it.
+ *
+ * Every jbrowse-web build writes its version to `version.txt`. An instance that
+ * serves none, or serves its index page there, cannot be judged and passes; the
+ * session gate still fails on it, a timeout later.
+ */
+export declare function assertSupportedInstance(instance: string): Promise<void>;

package/esm/instanceVersion.js

@@ -0,0 +1,24 @@
+// v5 is the first release to publish `[data-app-phase]` and the census beside
+// it, which are the only signals this package waits on.
+const MIN_MAJOR = 5;
+/**
+ * Refuse a JBrowse Web instance older than v5 before launching a browser at it.
+ *
+ * Every jbrowse-web build writes its version to `version.txt`. An instance that
+ * serves none, or serves its index page there, cannot be judged and passes; the
+ * session gate still fails on it, a timeout later.
+ */
+export async function assertSupportedInstance(instance) {
+    const text = await fetch(new URL('version.txt', instance), {
+        signal: AbortSignal.timeout(10000),
+    })
+        .then(res => (res.ok ? res.text() : ''))
+        .catch(() => '');
+    const version = text.trim();
+    const major = /^(\d+)\.\d+\.\d+/.exec(version)?.[1];
+    if (major !== undefined && Number(major) < MIN_MAJOR) {
+        throw new Error(`${instance} serves JBrowse ${version}, and @jbrowse/capture needs v${MIN_MAJOR} or later: ` +
+            'older builds publish no readiness marker to wait on. Point --instance at a ' +
+            `v${MIN_MAJOR} build.`);
+    }
+}

package/esm/poll.d.ts

@@ -0,0 +1,13 @@
+export declare const delay: (ms: number) => Promise<void>;
+/**
+ * Poll `read` until it has answered true for `holdMs` without a break, or
+ * `timeout` runs out. A `read` that throws ends the wait with its error.
+ *
+ * Polled from Node rather than in the page: chrome throttles in-page timers and
+ * rAF once a tab is not visible, which is the state a headless capture sits in.
+ */
+export declare function holdTrue(read: () => Promise<boolean>, { holdMs, timeout, pollMs, }: {
+    holdMs: number;
+    timeout: number;
+    pollMs: number;
+}): Promise<boolean>;

package/esm/poll.js

@@ -0,0 +1,29 @@
+export const delay = (ms) => new Promise(resolve => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Poll `read` until it has answered true for `holdMs` without a break, or
+ * `timeout` runs out. A `read` that throws ends the wait with its error.
+ *
+ * Polled from Node rather than in the page: chrome throttles in-page timers and
+ * rAF once a tab is not visible, which is the state a headless capture sits in.
+ */
+export async function holdTrue(read, { holdMs, timeout, pollMs, }) {
+    const deadline = Date.now() + timeout;
+    let since;
+    while (Date.now() < deadline) {
+        const ok = await read();
+        const now = Date.now();
+        if (ok) {
+            since ??= now;
+            if (now - since >= holdMs) {
+                return true;
+            }
+        }
+        else {
+            since = undefined;
+        }
+        await delay(pollMs);
+    }
+    return false;
+}

package/esm/ready.d.ts

@@ -17,14 +17,17 @@ export interface ReadyOptions extends SessionExpectations {
     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.
+     * Displays still reporting unpainted, or canceled, at the end of the wait,
+     * each with the phase it publishes: what separates a slow fetch from a
+     * display that says it finished without painting.
      */
-    pendingStates: PendingDisplay[];
+    pending: PendingDisplay[];
+    /**
+     * Displays showing "too much data" instead of their features. Not a failure,
+     * so never in `unsettled`, but worth saying: the image shows a banner there.
+     */
+    tooLarge: PendingDisplay[];
     /** Wait stages that hit their timeout instead of being satisfied. */
     unsettled: string[];
 }
@@ -43,7 +46,15 @@ export interface ReadyReport {
  *
  * 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.
+ * fetch failed is not working — it reads `ready` over an error banner, and over
+ * a user's cancel. `data-display-drawn` is the stricter gate, and the census
+ * after it names a canceled display whatever it drew.
+ */
+export declare function waitForJBrowseReady(page: Page, options?: ReadyOptions): Promise<ReadyReport>;
+/**
+ * The half of `waitForJBrowseReady` after the session gate: the marker held,
+ * every display painted, and the census of what did not. Run again after
+ * anything that changes the frame without changing the session, such as a
+ * viewport resize.
  */
-export declare function waitForJBrowseReady(page: Page, { timeout, settleMs, assembly, trackIds, allowUnsettled, }?: ReadyOptions): Promise<ReadyReport>;
+export declare function waitForFrame(page: Page, { timeout, settleMs, allowUnsettled, }?: Omit<ReadyOptions, keyof SessionExpectations>): Promise<ReadyReport>;

package/esm/ready.js

@@ -1,5 +1,6 @@
-import { describePendingDisplays, pendingDisplayStates, waitForSession, } from './sessionGate.js';
-import { delay, hasAppReadyMarker, waitForAppSettled, waitForDisplaysDone, } from './waits.js';
+import { delay } from './poll.js';
+import { describePendingDisplays, pendingDisplayStates, tooLargeDisplaysInPage, waitForSession, } from './sessionGate.js';
+import { waitForAppSettled, waitForDisplaysDone } from './waits.js';
 /**
  * Wait until a JBrowse page has finished loading AND finished drawing.
  *
@@ -15,26 +16,25 @@ import { delay, hasAppReadyMarker, waitForAppSettled, waitForDisplaysDone, } fro
  *
  * 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.
+ * fetch failed is not working — it reads `ready` over an error banner, and over
+ * a user's cancel. `data-display-drawn` is the stricter gate, and the census
+ * after it names a canceled display whatever it drew.
  */
-export async function waitForJBrowseReady(page, { timeout = 60000, settleMs = 0, assembly, trackIds, allowUnsettled = false, } = {}) {
+export async function waitForJBrowseReady(page, options = {}) {
+    // The census the gate reads shares its element with `[data-app-phase]`, so
+    // once it passes the marker is there too. Handed the options whole, so every
+    // session expectation reaches it, `views` included.
+    await waitForSession(page, options);
+    return waitForFrame(page, options);
+}
+/**
+ * The half of `waitForJBrowseReady` after the session gate: the marker held,
+ * every display painted, and the census of what did not. Run again after
+ * anything that changes the frame without changing the session, such as a
+ * viewport resize.
+ */
+export async function waitForFrame(page, { timeout = 60000, settleMs = 0, allowUnsettled = false, } = {}) {
     const unsettled = [];
-    // 0. the session exists and holds what was asked for. Positive, and throws.
-    await waitForSession(page, { assembly, trackIds, timeout });
-    // 1. and the build publishes the marker at all. Said out loud rather than
-    //    worked around: a chain built from the remaining signals is satisfied by
-    //    a page that has not started, so the fallback that used to run here
-    //    reported success on an empty browser unless it was also given a
-    //    seen-busy-then-quiet gate to compensate. One positive selector replaces
-    //    all of it, and a build too old to have it needs a newer --instance, not
-    //    a wait chain that cannot fail.
-    if (!(await hasAppReadyMarker(page))) {
-        throw new Error('this page publishes no [data-app-phase], so there is no positive signal ' +
-            'that it has finished — every other readiness attribute is an absence ' +
-            'an app that has not started also satisfies. Point --instance at a ' +
-            'JBrowse build that publishes it.');
-    }
     const ready = await waitForAppSettled(page, { timeout });
     if (!ready) {
         unsettled.push('the app never held itself ready');
@@ -56,18 +56,28 @@ export async function waitForJBrowseReady(page, { timeout = 60000, settleMs = 0,
     // that painted during `settleMs` was absent from `pending` and still failed
     // the run, while the CLI's own warning recommended raising `--settle` to fix
     // exactly that.
-    const pendingStates = await pendingDisplayStates(page);
-    if (pendingStates.length > 0) {
-        unsettled.push(`display(s) never painted: ${describePendingDisplays(pendingStates)}`);
+    const pending = await pendingDisplayStates(page);
+    const canceled = pending.filter(d => d.phase === 'canceled');
+    const unpainted = pending.filter(d => d.phase !== 'canceled');
+    if (unpainted.length > 0) {
+        unsettled.push(`display(s) never painted: ${describePendingDisplays(unpainted)}`);
+    }
+    if (canceled.length > 0) {
+        unsettled.push(`display(s) canceled, which lasts until Retry: ${describePendingDisplays(canceled)}`);
     }
     if (!allowUnsettled && unsettled.length > 0) {
         // Throwing is the point. Each stage 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(`gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ` +
-            'Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ' +
-            'capture the frame as it stands.');
+        throw new Error(unsettled.length === 1 && canceled.length > 0
+            ? `${unsettled[0]}. No timeout lifts a cancel; press Retry on the ` +
+                'track, or pass allowUnsettled (--allowUnsettled) to capture the ' +
+                'frame as it stands.'
+            : `gave up waiting after ${timeout}ms: ${unsettled.join('; ')}. ` +
+                'Raise the timeout, or pass allowUnsettled (--allowUnsettled) to ' +
+                'capture the frame as it stands.');
     }
-    return { pending: pendingStates.map(d => d.name), pendingStates, unsettled };
+    const tooLarge = await page.evaluate(tooLargeDisplaysInPage);
+    return { pending, tooLarge, unsettled };
 }

package/esm/session.d.ts

@@ -1,20 +1,28 @@
 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=` value that opens a session saved with "Export session...".
+ * Takes the exported `{ session: {...} }` document or the snapshot inside it.
+ */
+export declare function savedSessionParam(session: object): string;
+/** The snapshot inside an exported session document, or the snapshot itself. */
+export declare function savedSnapshot(session: object): object;
+/**
+ * The assembly the first view of a session spec or saved snapshot 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
+ * `--hub hg38 --spec 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).
+ * Every trackId a session spec or saved snapshot opens, including nested views
+ * (a synteny or breakpoint-split view 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
+ * into "the tracks I named are open", and a session is the one input where the
  * caller has not spelled those ids out separately.
  */
 export declare function trackIdsFromSession(session: object): string[];

package/esm/session.js

@@ -15,17 +15,33 @@ export function encodeSessionSpec(session) {
     return encodeURIComponent(sessionSpecParam(session));
 }
 /**
- * The assembly a session spec's first view opens, if it names one.
+ * The `session=` value that opens a session saved with "Export session...".
+ * Takes the exported `{ session: {...} }` document or the snapshot inside it.
+ */
+export function savedSessionParam(session) {
+    return `json-${JSON.stringify({ session: savedSnapshot(session) })}`;
+}
+/** The snapshot inside an exported session document, or the snapshot itself. */
+export function savedSnapshot(session) {
+    const inner = session.session;
+    return typeof inner === 'object' && inner !== null ? inner : session;
+}
+/**
+ * The assembly the first view of a session spec or saved snapshot 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
+ * `--hub hg38 --spec 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);
+            const found = [view.assembly ?? []].flat()[0] ??
+                view.displayedRegions?.[0]?.assemblyName ??
+                view.assemblyNames?.[0] ??
+                find(view.views);
             if (found) {
                 return found;
             }
@@ -35,20 +51,23 @@ export function assemblyFromSession(session) {
     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).
+ * Every trackId a session spec or saved snapshot opens, including nested views
+ * (a synteny or breakpoint-split view 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
+ * into "the tracks I named are open", and a session is the one input where the
  * caller has not spelled those ids out separately.
  */
 export function trackIdsFromSession(session) {
-    // 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
-    const idsOf = (tracks) => (tracks ?? [])
-        .map(t => (typeof t === 'string' ? t : t.trackId))
-        .filter(id => id !== undefined);
+    // an entry that names no trackId is malformed rather than a track to expect,
+    // so it drops out here instead of gating on undefined
+    const idOf = (t) => typeof t === 'string'
+        ? t
+        : (t.trackId ??
+            (typeof t.configuration === 'string'
+                ? t.configuration
+                : t.configuration?.trackId));
+    const idsOf = (tracks) => (tracks ?? []).map(idOf).filter(id => id !== undefined);
     const collect = (views) => (views ?? []).flatMap(view => [
         // a nested entry is a synteny spec's per-level list; these used to be
         // filtered out as malformed, so a synteny --session gated on nothing