@jbrowse/capture 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/sessionGate.d.ts

@@ -1,126 +1,59 @@
 import type { Page } from 'puppeteer';
 export interface SessionExpectations {
-    /** Assembly that must be open on some view. Usually the one you navigated to. */
+    /** Assembly that must be open on some view. */
     assembly?: string;
     /**
-     * trackIds that must all be open. The exact ids, not a count: a hosted config
-     * usually ships a defaultSession, so `&tracks=` ADDS to tracks that are
-     * already there and a count is satisfied before your track arrives — or by
-     * the default set alone when the id you passed does not exist at all.
+     * trackIds that must all be open. Exact ids rather than a count, since a
+     * config's default session may already hold others.
      */
     trackIds?: string[];
+    /** The fewest open views that count. Default 1; 0 accepts none. */
+    views?: number;
 }
-export interface SessionSummary {
+export interface SessionCensus {
     views: number;
     assemblies: string[];
     trackIds: string[];
 }
-/** What the page currently has open, or undefined if there is no session yet. */
-export declare function readSessionSummary(page: Page): Promise<SessionSummary | undefined>;
-export declare function readSessionSummaryInPage(): SessionSummary | undefined;
 /**
- * Wait until the session exists, every view reports itself initialized, and the
- * assembly and tracks that were asked for are actually open.
- *
- * Throws on timeout rather than proceeding. A config URL that 404s, a trackId
- * that does not exist in the config, and an assembly name that does not match
- * the one the config declares all fail here, which is the only place they fail
- * at all — each of them otherwise produces a browser that loads, paints its
- * chrome, and photographs beautifully with nothing in it.
+ * The load failure the app shows in place of itself, the census
+ * `AppReadyMarker` publishes beside its phase, and any snackbar up — which is
+ * where a location that did not resolve says so. Serialized into the page.
  */
-export declare function waitForSession(page: Page, { assembly, trackIds, timeout, }?: SessionExpectations & {
-    timeout?: number;
-}): Promise<void>;
-export declare const PAINT_CONTRACT_NOTE: string;
+export declare function readSessionInPage(): {
+    failure?: string;
+    census?: SessionCensus;
+    notices: string[];
+};
 /**
- * Whether every open display's paint state was actually measurable.
- *
- * The per-display paint attributes are not universal. Measured on 2026-08-07:
- * jbrowse.org/code/jb2/main publishes `data-view-phase`, `data-display-phase`
- * and `data-display-drawn`; jbrowse.org/code/jb2/latest — the released build,
- * which is what every genomes.jbrowse.org link and every docs figure link opens
- * — publishes none of them and exposes only the loading overlay. Against that
- * instance the display-level waits are unfalsifiable rather than satisfied, so a
- * caller has to be told which of the two it got instead of reading "0 displays
- * pending" as good news.
- *
- * The absence of the attribute is NOT on its own the answer, which is the trap
- * here: a page with no tracks open — an import form, a menu shot, a bare view —
- * publishes none of it either, and reporting that as "this build cannot measure
- * paint" is both wrong and alarming. So this asks the question only when there
- * is something to measure, and answers true when there is not.
- *
- * Call it AFTER the session gate, so "no tracks open" means the page genuinely
- * has none rather than not having got there yet.
+ * Wait until the census shows the assembly and tracks that were asked for.
+ * Throws at once with the app's message if it could not load, and on timeout
+ * with what the census held instead.
  */
-export declare function hasPaintContract(page: Page): Promise<boolean>;
-/**
- * Which readiness attributes this build publishes at all.
- *
- * `hasPaintContract` answers the same question for one attribute and folds in
- * "there was nothing to measure"; this is the raw read of all three, so the
- * chain can adapt to the build BEFORE it starts waiting rather than reporting
- * afterwards what it could not see.
- *
- * Every wait keyed on one of these is NEGATIVE — it passes when the selector is
- * absent — so on a build that publishes none of them all three are satisfied by
- * a page that has not begun to draw. Read this after the session gate and treat
- * `false` as "this signal is unavailable", never as "this signal says done".
- */
-export interface Instrumentation {
-    viewPhase: boolean;
-    displayPhase: boolean;
-    displayDrawn: boolean;
-}
-/** Serialized into the page; exported so a test can call the real function. */
-export declare function readInstrumentationInPage(): Instrumentation;
-export declare function readInstrumentation(page: Page): Promise<Instrumentation>;
-/**
- * Displays that were still reporting unpainted at the moment of the call.
- *
- * Distinct from `unsettled`, which says a wait ran out of time. This says what
- * the page looked like when the shutter fired, and the two do not imply each
- * other: a display can go back to pending after its stage passed. An empty
- * result means nothing at all on a build with no paint contract — check
- * `paintContract` before reading it as good news.
- */
-export declare function pendingDisplays(page: Page): Promise<string[]>;
-/** One unpainted display and what it says about itself. */
-export interface PendingDisplay {
-    /** the display TYPE, shared by every instance of it */
+export declare function waitForSession(page: Page, { assembly, trackIds, views, timeout, }?: SessionExpectations & {
+    timeout?: number;
+}): Promise<void>;
+/** One display and the phase it publishes. */
+export interface DisplayState {
+    /** The display type, or its id where a banner has replaced the display. */
     name: string;
-    /** which instance, where the display publishes `data-display-id` */
     id?: string;
-    /**
-     * Its own phase, or undefined on a build too old to publish one. `loading` is
-     * a display still fetching; `ready` is the one that earns this census, since
-     * a display that says it has finished while reporting no paint is a bug in
-     * the display rather than a slow page.
-     */
     phase?: string;
 }
 /**
- * The same census, with each display's own account of itself.
- *
- * `pendingDisplays` above answers WHICH, and that was the whole report: every
- * timeout read the same however it was caused. The phase separates the cases a
- * bare name runs together —
- *
- *   `loading`   still fetching. A slow page or a fetch that never returns.
- *   `error`     finished, badly. Nothing is coming; the picture is a banner.
- *   `ready`     it says it is done and reports no paint. That is the display's
- *               bug, not the wait's, and it is the one a longer timeout will
- *               never fix.
- *   absent      the element publishes no phase: a build older than the
- *               attribute, or a surface that never grew one.
- *
- * Serialized into the page, so a test can call the real function. Read fresh
- * from the DOM at report time rather than from handles the waits held. A handle to an element that has since re-rendered throws
- * `Node is detached from document`, which is how the previous attempt at this
- * turned four diagnosable timeouts into nine opaque puppeteer errors (reverted
- * in 28c6ee6d90).
+ * Displays that are not showing their data. `pending`: unpainted, canceled,
+ * or showing an error, each failing a capture — `loading` is still fetching,
+ * `error` and `renderError` show a banner, `canceled` lasts until Retry, and
+ * `ready` is a display that says it finished without painting. `tooLarge`:
+ * showing "too much data", which is the app working as designed. Serialized
+ * into the page.
+ *
+ * `error` is selected by phase as well as by paint: an LGV display that failed
+ * its fetch counts as painted, so its banner publishes `drawn="true"`.
  */
-export declare function pendingDisplayStatesInPage(): PendingDisplay[];
-export declare function pendingDisplayStates(page: Page): Promise<PendingDisplay[]>;
-/** `pendingDisplayStates` as one line for an error message. */
-export declare function describePendingDisplays(pending: PendingDisplay[]): string;
+export declare function displayCensusInPage(): {
+    pending: DisplayState[];
+    tooLarge: DisplayState[];
+};
+/** Displays as one clause for a message. */
+export declare function describeDisplays(displays: DisplayState[]): string;

package/esm/sessionGate.js

@@ -1,196 +1,102 @@
-/** What the page currently has open, or undefined if there is no session yet. */
-export function readSessionSummary(page) {
-    return page.evaluate(readSessionSummaryInPage);
-}
-// Serialized into the page, so it can only call what it declares — hence the
-// inlined copy of readViews rather than a shared import.
-//
-// Exported for its test: it reads `globalThis.JBrowseSession` and nothing else,
-// so calling it in node against a stubbed global exercises the very function
-// puppeteer serializes, rather than a copy of it that can drift.
-export function readSessionSummaryInPage() {
-    const session = globalThis.JBrowseSession;
-    const views = session?.views;
-    if (!views) {
-        return undefined;
-    }
-    // Inlined rather than shared with the gate below for the same reason as the
-    // readViews copy: both are serialized into the page.
-    function collect(v) {
-        return [
-            ...(v.tracks ?? []),
-            ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
-            ...(v.views ?? []).flatMap(collect),
-        ];
-    }
-    return {
-        views: views.length,
-        assemblies: [
-            ...new Set(views.flatMap(function asm(v) {
-                return [...(v.assemblyNames ?? []), ...(v.views ?? []).flatMap(asm)];
-            })),
-        ],
-        trackIds: views.flatMap(v => collect(v).map(t => t.configuration?.trackId ?? '(unnamed)')),
-    };
-}
+import { DEFAULT_TIMEOUT, holdTrue } from './poll.js';
 /**
- * Wait until the session exists, every view reports itself initialized, and the
- * assembly and tracks that were asked for are actually open.
- *
- * Throws on timeout rather than proceeding. A config URL that 404s, a trackId
- * that does not exist in the config, and an assembly name that does not match
- * the one the config declares all fail here, which is the only place they fail
- * at all — each of them otherwise produces a browser that loads, paints its
- * chrome, and photographs beautifully with nothing in it.
+ * The load failure the app shows in place of itself, the census
+ * `AppReadyMarker` publishes beside its phase, and any snackbar up — which is
+ * where a location that did not resolve says so. Serialized into the page.
  */
-export async function waitForSession(page, { assembly, trackIds = [], timeout = 60000, } = {}) {
+export function readSessionInPage() {
+    const failure = document.querySelector('[data-app-error]')?.dataset.appError;
+    const notices = [
+        ...document.querySelectorAll('[data-testid^="snackbar-"]'),
+    ].map(el => el.textContent.trim());
+    const marker = document.querySelector('[data-app-tracks]');
+    if (!marker) {
+        return { failure, notices };
+    }
     try {
-        // #region session-gate
-        await page.waitForFunction((wantAssembly, wantTracks) => {
-            const session = globalThis.JBrowseSession;
-            const views = session?.views;
-            if (!views?.length) {
-                return false;
-            }
-            // `initialized` is an LGV getter; a view type without one is mounted
-            // content the moment it exists, so absent counts as initialized and
-            // only an explicit false is pending.
-            if (views.some(v => v.initialized === false)) {
-                return false;
-            }
-            // A container view (synteny, dotplot) keeps its assemblies on the rows
-            // and its tracks on the levels, so both walks descend into sub-views
-            // and levels rather than reading the top view only.
-            const asmOf = (v) => [
-                ...(v.assemblyNames ?? []),
-                ...(v.views ?? []).flatMap(asmOf),
-            ];
-            if (wantAssembly !== null &&
-                !views.some(v => asmOf(v).includes(wantAssembly))) {
-                return false;
-            }
-            const tracksOf = (v) => [
-                ...(v.tracks ?? []),
-                ...(v.levels ?? []).flatMap(l => l.tracks ?? []),
-                ...(v.views ?? []).flatMap(tracksOf),
-            ];
-            const open = new Set(views.flatMap(v => tracksOf(v).map(t => t.configuration?.trackId)));
-            return wantTracks.every(id => open.has(id));
-        }, { timeout, polling: 250 }, assembly ?? null, trackIds);
-        // #endregion session-gate
+        return {
+            failure,
+            notices,
+            census: {
+                views: Number(marker.dataset.appViews) || 0,
+                assemblies: JSON.parse(marker.dataset.appAssemblies ?? '[]'),
+                trackIds: JSON.parse(marker.dataset.appTracks ?? '[]'),
+            },
+        };
     }
     catch {
-        const summary = await readSessionSummary(page);
-        const found = summary
-            ? `${summary.views} view(s), assemblies [${summary.assemblies.join(', ')}], tracks [${summary.trackIds.join(', ')}]`
-            : 'no session on the page at all (is this a jbrowse-web instance?)';
-        const missing = summary
-            ? trackIds.filter(id => !summary.trackIds.includes(id))
-            : trackIds;
+        return { failure, notices };
+    }
+}
+/**
+ * Wait until the census shows the assembly and tracks that were asked for.
+ * Throws at once with the app's message if it could not load, and on timeout
+ * with what the census held instead.
+ */
+export async function waitForSession(page, { assembly, trackIds = [], views = 1, timeout = DEFAULT_TIMEOUT, } = {}) {
+    let last;
+    const notices = new Set();
+    const reached = await holdTrue(async () => {
+        const read = await page.evaluate(readSessionInPage).catch(() => undefined);
+        if (read?.failure) {
+            throw new Error(`JBrowse could not load: ${read.failure}`);
+        }
+        for (const notice of read?.notices ?? []) {
+            notices.add(notice);
+        }
+        const census = read?.census;
+        last = census;
+        return (!!census &&
+            census.views >= views &&
+            (assembly === undefined || census.assemblies.includes(assembly)) &&
+            trackIds.every(id => census.trackIds.includes(id)));
+    }, { holdMs: 0, timeout, pollMs: 250 });
+    if (!reached) {
+        const census = last;
+        const found = census
+            ? `${census.views} view(s), assemblies [${census.assemblies.join(', ')}], tracks [${census.trackIds.join(', ')}]`
+            : 'no census on the page at all, so either this is not a JBrowse app or ' +
+                'it is older than v5, the first release to publish one';
+        const missing = trackIds.filter(id => !census?.trackIds.includes(id));
         const wanted = [
             assembly ? `assembly "${assembly}"` : undefined,
             missing.length ? `track(s) [${missing.join(', ')}]` : undefined,
         ]
             .filter(Boolean)
             .join(' and ');
-        throw new Error(`the session never reached the requested state after ${timeout}ms. ` +
-            `Wanted ${wanted || 'an initialized view'}; found ${found}. ` +
-            'A config URL that 404s, a trackId the config does not define, or an ' +
-            'assembly name that does not match the config all look like this.');
+        const said = notices.size
+            ? `The app said: ${[...notices].join(' | ')}.`
+            : 'A trackId the config does not define, or an assembly name that does not match the config, looks like this.';
+        throw new Error(`the session never reached the requested state after ${timeout}ms. Wanted ${wanted || (views > 0 ? 'an open view' : 'a session')}; found ${found}. ${said}`);
     }
 }
-export const PAINT_CONTRACT_NOTE = 'this JBrowse build publishes no data-display-drawn attributes, so "every ' +
-    'display has painted" cannot be checked — only that nothing is still ' +
-    'loading. Raise --settle if the image looks half-drawn.';
 /**
- * Whether every open display's paint state was actually measurable.
+ * Displays that are not showing their data. `pending`: unpainted, canceled,
+ * or showing an error, each failing a capture — `loading` is still fetching,
+ * `error` and `renderError` show a banner, `canceled` lasts until Retry, and
+ * `ready` is a display that says it finished without painting. `tooLarge`:
+ * showing "too much data", which is the app working as designed. Serialized
+ * into the page.
  *
- * The per-display paint attributes are not universal. Measured on 2026-08-07:
- * jbrowse.org/code/jb2/main publishes `data-view-phase`, `data-display-phase`
- * and `data-display-drawn`; jbrowse.org/code/jb2/latest — the released build,
- * which is what every genomes.jbrowse.org link and every docs figure link opens
- * — publishes none of them and exposes only the loading overlay. Against that
- * instance the display-level waits are unfalsifiable rather than satisfied, so a
- * caller has to be told which of the two it got instead of reading "0 displays
- * pending" as good news.
- *
- * The absence of the attribute is NOT on its own the answer, which is the trap
- * here: a page with no tracks open — an import form, a menu shot, a bare view —
- * publishes none of it either, and reporting that as "this build cannot measure
- * paint" is both wrong and alarming. So this asks the question only when there
- * is something to measure, and answers true when there is not.
- *
- * Call it AFTER the session gate, so "no tracks open" means the page genuinely
- * has none rather than not having got there yet.
+ * `error` is selected by phase as well as by paint: an LGV display that failed
+ * its fetch counts as painted, so its banner publishes `drawn="true"`.
  */
-export async function hasPaintContract(page) {
-    const summary = await readSessionSummary(page);
-    if (summary && summary.trackIds.length === 0) {
-        return true;
+export function displayCensusInPage() {
+    const pending = [];
+    const tooLarge = [];
+    for (const el of document.querySelectorAll('[data-display-drawn="false"], [data-display-phase="error"], [data-display-phase="canceled"], [data-display-phase="renderError"], [data-display-phase="tooLarge"]')) {
+        const phase = el.dataset.displayPhase;
+        (phase === 'tooLarge' ? tooLarge : pending).push({
+            name: el.dataset.testid ?? el.dataset.displayId ?? 'unnamed display',
+            id: el.dataset.displayId,
+            phase,
+        });
     }
-    return page.evaluate(() => document.querySelector('[data-display-drawn]') !== null);
-}
-/** Serialized into the page; exported so a test can call the real function. */
-export function readInstrumentationInPage() {
-    return {
-        viewPhase: document.querySelector('[data-view-phase]') !== null,
-        displayPhase: document.querySelector('[data-display-phase]') !== null,
-        displayDrawn: document.querySelector('[data-display-drawn]') !== null,
-    };
-}
-export function readInstrumentation(page) {
-    return page.evaluate(readInstrumentationInPage);
-}
-/**
- * Displays that were still reporting unpainted at the moment of the call.
- *
- * Distinct from `unsettled`, which says a wait ran out of time. This says what
- * the page looked like when the shutter fired, and the two do not imply each
- * other: a display can go back to pending after its stage passed. An empty
- * result means nothing at all on a build with no paint contract — check
- * `paintContract` before reading it as good news.
- */
-export function pendingDisplays(page) {
-    return page.evaluate(() => [
-        ...document.querySelectorAll('[data-display-drawn="false"]'),
-    ].map(el => el.dataset.testid ?? (el.id || 'unnamed display')));
-}
-/**
- * The same census, with each display's own account of itself.
- *
- * `pendingDisplays` above answers WHICH, and that was the whole report: every
- * timeout read the same however it was caused. The phase separates the cases a
- * bare name runs together —
- *
- *   `loading`   still fetching. A slow page or a fetch that never returns.
- *   `error`     finished, badly. Nothing is coming; the picture is a banner.
- *   `ready`     it says it is done and reports no paint. That is the display's
- *               bug, not the wait's, and it is the one a longer timeout will
- *               never fix.
- *   absent      the element publishes no phase: a build older than the
- *               attribute, or a surface that never grew one.
- *
- * Serialized into the page, so a test can call the real function. Read fresh
- * from the DOM at report time rather than from handles the waits held. A handle to an element that has since re-rendered throws
- * `Node is detached from document`, which is how the previous attempt at this
- * turned four diagnosable timeouts into nine opaque puppeteer errors (reverted
- * in 28c6ee6d90).
- */
-export function pendingDisplayStatesInPage() {
-    return [
-        ...document.querySelectorAll('[data-display-drawn="false"]'),
-    ].map(el => ({
-        name: el.dataset.testid ?? (el.id || 'unnamed display'),
-        id: el.dataset.displayId,
-        phase: el.dataset.displayPhase,
-    }));
-}
-export function pendingDisplayStates(page) {
-    return page.evaluate(pendingDisplayStatesInPage);
+    return { pending, tooLarge };
 }
-/** `pendingDisplayStates` as one line for an error message. */
-export function describePendingDisplays(pending) {
-    return pending
-        .map(d => `${d.name}${d.id ? ` (${d.id})` : ''} is ${d.phase ?? 'in an unpublished phase'}`)
+/** Displays as one clause for a message. */
+export function describeDisplays(displays) {
+    return displays
+        .map(d => `${d.name}${d.id && d.id !== d.name ? ` (${d.id})` : ''} is ${d.phase ?? 'in an unpublished phase'}`)
         .join('; ');
 }

package/esm/sessionOverflow.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How many CSS pixels of the session lie below the window: the most any
+ * scrolling column holding a view overflows, less the empty room `ViewStack`
+ * leaves below the last view. Serialized into the page.
+ */
+export declare function sessionOverflowInPage(): number;

package/esm/sessionOverflow.js

@@ -0,0 +1,22 @@
+/**
+ * How many CSS pixels of the session lie below the window: the most any
+ * scrolling column holding a view overflows, less the empty room `ViewStack`
+ * leaves below the last view. Serialized into the page.
+ */
+export function sessionOverflowInPage() {
+    let most = Math.max(0, document.documentElement.scrollHeight - window.innerHeight);
+    for (const container of document.querySelectorAll('[data-testid^="view-container-"]')) {
+        for (let el = container.parentElement; el; el = el.parentElement) {
+            const { overflowY } = getComputedStyle(el);
+            if ((overflowY === 'auto' || overflowY === 'scroll') &&
+                el.scrollHeight > el.clientHeight) {
+                const room = el
+                    .querySelector('[data-testid="view-stack-overscroll"]')
+                    ?.getBoundingClientRect().height ?? 0;
+                most = Math.max(most, Math.ceil(el.scrollHeight - room - el.clientHeight));
+                break;
+            }
+        }
+    }
+    return most;
+}

package/esm/url.d.ts

@@ -1,4 +1,9 @@
-export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/latest/";
+export declare const PUBLIC_INSTANCE = "https://jbrowse.org/code/jb2/v5.0.0-beta.11/";
+/**
+ * The instance as the page that loads it sees it: a directory given without
+ * its slash, which the host redirects, resolves relative URLs one level up.
+ */
+export declare function instanceUrl(instance?: string): URL;
 export interface JBrowseUrlOptions {
     /** A genomes.jbrowse.org assembly: a UCSC db name (`hg38`) or GenArk accession. */
     hub?: string;
@@ -7,14 +12,19 @@ export interface JBrowseUrlOptions {
     /** Assembly to open. Defaults to `hub`, whose config names its assembly after it. */
     assembly?: string;
     /**
-     * Where to open. A locstring (`chr1:1,000-2,000`, several space-separated for
-     * a discontinuous view), or — on a config that ships a text index, which every
-     * UCSC assembly on genomes.jbrowse.org does — a feature name such as `BRCA1`.
+     * Where to open: a locstring (`chr1:1,000-2,000`, several space-separated
+     * for a discontinuous view), or a feature name such as `BRCA1` on a config
+     * with a text index, which every UCSC assembly on genomes.jbrowse.org has.
      */
     loc?: string;
     /** trackIds from the config to open. */
     tracks?: string[];
-    /** The full session spec, for anything the three fields above cannot say. */
+    /** A session spec, for anything the three fields above cannot say. */
+    spec?: object;
+    /**
+     * A session saved with "Export session...": the `{ session: {...} }`
+     * document, or the snapshot inside it.
+     */
     session?: object;
     /** Name the session carries once opened. */
     sessionName?: string;
@@ -22,18 +32,19 @@ export interface JBrowseUrlOptions {
     instance?: string;
 }
 /**
- * The URL that opens a JBrowse Web instance onto a described view. Useful on its
- * own: an agent can hand this to a human, or paste it into a report, without
- * launching a browser at all.
+ * A spec or a saved session says which assembly, locations and tracks to
+ * open, so the URL carries one of the three ways of saying so, never two.
+ */
+export declare function assertSessionStandsAlone({ spec, session, assembly, loc, tracks, }: JBrowseUrlOptions): void;
+/**
+ * The URL that opens a JBrowse Web instance onto a described view, for a
+ * person to follow without launching a browser here.
  *
- * Two ways to say where to go, and they are not interchangeable. `assembly` /
- * `loc` / `tracks` become the [URL parameters](https://jbrowse.org/jb2/docs/urlparams/),
- * which route `loc` through the config's text-search index, so a **gene name**
- * works there. `session` becomes a
+ * `assembly`/`loc`/`tracks` become the
+ * [URL parameters](https://jbrowse.org/jb2/docs/urlparams/), whose `loc`
+ * takes a gene name. `spec` becomes a
  * [session spec](https://jbrowse.org/jb2/docs/urlparams/#session-spec), which
- * can describe several views and per-display settings but whose `init.loc` is
- * parsed as a locstring only and throws on a gene name. Pass one or the other;
- * `session` wins, and the URL params are dropped rather than silently starting
- * the fresh session that `&loc=` otherwise forces.
+ * can describe several views and per-display settings but whose `init.loc`
+ * takes a locstring only. `session` opens a saved session as exported.
  */
-export declare function jbrowseUrl({ hub, config, assembly, loc, tracks, session, sessionName, instance, }: JBrowseUrlOptions): string;
+export declare function jbrowseUrl({ hub, config, assembly, loc, tracks, spec, session, sessionName, instance, }: JBrowseUrlOptions): string;

package/esm/url.js

@@ -1,44 +1,68 @@
 import { hubUrl } from './hub.js';
-import { sessionSpecParam } from './session.js';
-// The public JBrowse Web build the docs' own figure links point at. Any other
-// deployment works the same way, including a local `npx serve` of a build.
-export const PUBLIC_INSTANCE = 'https://jbrowse.org/code/jb2/latest/';
+import { savedSessionParam, sessionSpecParam } from './session.js';
+import { version } from './version.js';
+// the release this package shipped with; `latest/` trails a major behind
+// during a beta
+export const PUBLIC_INSTANCE = `https://jbrowse.org/code/jb2/v${version}/`;
 /**
- * The URL that opens a JBrowse Web instance onto a described view. Useful on its
- * own: an agent can hand this to a human, or paste it into a report, without
- * launching a browser at all.
+ * The instance as the page that loads it sees it: a directory given without
+ * its slash, which the host redirects, resolves relative URLs one level up.
+ */
+export function instanceUrl(instance = PUBLIC_INSTANCE) {
+    const url = new URL(instance);
+    if (!url.pathname.endsWith('/') && !/\.html?$/.test(url.pathname)) {
+        url.pathname += '/';
+    }
+    return url;
+}
+/**
+ * A spec or a saved session says which assembly, locations and tracks to
+ * open, so the URL carries one of the three ways of saying so, never two.
+ */
+export function assertSessionStandsAlone({ spec, session, assembly, loc, tracks, }) {
+    if (spec && session) {
+        throw new Error('pass a session spec or a saved session, not both');
+    }
+    if ((spec || session) && (assembly || loc || tracks?.length)) {
+        throw new Error('a session spec or saved session says which assembly, locations and ' +
+            'tracks to open, so it cannot be combined with assembly, loc or tracks ' +
+            '(--assembly, --loc, --track): put them in the session');
+    }
+}
+/**
+ * The URL that opens a JBrowse Web instance onto a described view, for a
+ * person to follow without launching a browser here.
  *
- * Two ways to say where to go, and they are not interchangeable. `assembly` /
- * `loc` / `tracks` become the [URL parameters](https://jbrowse.org/jb2/docs/urlparams/),
- * which route `loc` through the config's text-search index, so a **gene name**
- * works there. `session` becomes a
+ * `assembly`/`loc`/`tracks` become the
+ * [URL parameters](https://jbrowse.org/jb2/docs/urlparams/), whose `loc`
+ * takes a gene name. `spec` becomes a
  * [session spec](https://jbrowse.org/jb2/docs/urlparams/#session-spec), which
- * can describe several views and per-display settings but whose `init.loc` is
- * parsed as a locstring only and throws on a gene name. Pass one or the other;
- * `session` wins, and the URL params are dropped rather than silently starting
- * the fresh session that `&loc=` otherwise forces.
+ * can describe several views and per-display settings but whose `init.loc`
+ * takes a locstring only. `session` opens a saved session as exported.
  */
-export function jbrowseUrl({ hub, config, assembly = hub, loc, tracks, session, sessionName, instance = PUBLIC_INSTANCE, }) {
-    const configUrl = config ?? (hub ? hubUrl(hub) : undefined);
-    const url = new URL(instance);
-    // URL's own encoder, not a hand-built query string: a config URL contains
-    // `://` and `?`, and a session spec is a whole JSON document, so appending
-    // either raw produces a link that loads a truncated config and reports
-    // nothing.
+export function jbrowseUrl({ hub, config, assembly, loc, tracks, spec, session, sessionName, instance, }) {
+    assertSessionStandsAlone({ spec, session, assembly, loc, tracks });
+    const params = new URLSearchParams();
     const set = (key, value) => {
         if (value) {
-            url.searchParams.set(key, value);
+            params.set(key, value);
         }
     };
-    set('config', configUrl);
-    if (session) {
-        set('session', sessionSpecParam(session));
+    set('config', config ?? (hub ? hubUrl(hub) : undefined));
+    if (spec) {
+        set('session', sessionSpecParam(spec));
+    }
+    else if (session) {
+        set('session', savedSessionParam(session));
     }
     else {
-        set('assembly', assembly);
+        set('assembly', assembly ?? hub);
         set('loc', loc);
         set('tracks', tracks?.join(','));
     }
     set('sessionName', sessionName);
+    const url = instanceUrl(instance);
+    // the fragment never reaches a server, so a large spec cannot hit HTTP 414
+    url.hash = params.toString();
     return url.href;
 }