@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/selectNamedRegions.js

@@ -0,0 +1,222 @@
+/**
+ * `*` is the only metacharacter; everything else in a name is matched literally,
+ * so a refName containing regex punctuation (`chr1.1`, `scaffold[2]`) can't turn
+ * into an accidental pattern. Anchored, so a pattern names whole refNames.
+ *
+ * Case-INSENSITIVE, and not optionally: the literal reading beside it resolves
+ * through getCanonicalRefName, which falls back to `lowerCaseRefNameAliases`, so
+ * `CHR1` has always found `chr1`. A case-sensitive glob meant `CHR1*` found
+ * nothing on the same assembly — literal working where pattern silently fails,
+ * which is the same split the alias fix removed and is no more tellable apart
+ * from "this assembly has no such contigs" here than it was there. No caller
+ * wants the other behaviour, so it is baked in rather than passed.
+ *
+ * Module-private, and worth keeping that way: both readings of `*` — the
+ * resolver's and the search box's — live in this file precisely so a pattern
+ * that selects a set in a session spec selects the same set typed into the box.
+ * A third caller reaching in from elsewhere is how that stops being true.
+ */
+function globToRegExp(pattern) {
+    const escaped = pattern.replaceAll(/[.*+?^${}()|[\]\\]/g, m => m === '*' ? '.*' : `\\${m}`);
+    return new RegExp(`^${escaped}$`, 'i');
+}
+/**
+ * Resolve caller-supplied region names against an assembly's own regions,
+ * preserving the requested order and dropping names that match nothing.
+ *
+ * An entry containing `*` is a glob matched against the refName, which is what
+ * makes a fragmented assembly tractable: a haplotype-resolved genome wants "all
+ * of hap1" (`*_hap1`), not a hand-maintained list of its 16 scaffolds that goes
+ * stale the moment the assembly is rebuilt. A glob contributes its matches in
+ * the ASSEMBLY's order (the only order it can mean); exact names contribute in
+ * the CALLER's order, so an explicit list still controls layout. Duplicates
+ * across entries are dropped, so `['chr1_hap1', '*_hap1']` is chr1 first then
+ * the rest.
+ *
+ * AN EXACT REFNAME BEATS THE GLOB READING, which is the only reason `*` is safe
+ * to hand a user as a syntax: `*` is a legal character in a real contig name and
+ * the names carrying it are the ones nobody would think to escape. GRCh38's ALT
+ * decoys are HLA allele names — `HLA-A*01:01:01:01` — so a pattern typed to name
+ * one allele was compiled to `^HLA-A.*01:01:01:01$`, which matches that contig
+ * (hence it looked fine) and every other HLA-A allele with the same last four
+ * fields. Trying the literal lookup first costs one Map hit and means a name
+ * that IS a contig always resolves to that contig; only a name matching nothing
+ * is reinterpreted as a pattern.
+ *
+ * Selecting from the assembly's own region objects (rather than synthesizing
+ * them) keeps coordinates and lengths correct.
+ *
+ * THERE IS DELIBERATELY NO CEILING on how many regions a glob may resolve to.
+ * `["*"]` on a scaffold-level assembly really does mean every contig, which is
+ * no more than `showAllRegionsInAssembly` already hands to `setDisplayedRegions`.
+ * A cap here could only truncate — silently returning some of what was asked
+ * for, which is the failure mode this file keeps being fixed for. The search
+ * box's picker does bound its bulk-select row, and that is a different thing: it
+ * withholds an OFFER, leaving every match still pickable one at a time, rather
+ * than quietly resolving a list to a prefix of itself.
+ *
+ * BOTH READINGS GO THROUGH THE ASSEMBLY'S ALIASES, and they have to, because
+ * only one of them used to. An exact name has always resolved via
+ * `getCanonicalRefName`, so `['chr1']` picks out a contig an Ensembl-named
+ * assembly calls `1` — but the glob was tested against `region.refName`, the
+ * canonical name alone, so `['chr*']` on that same assembly matched nothing at
+ * all. The literal working where the pattern silently fails is the worst
+ * possible split: the caller has no way to tell "this assembly has no such
+ * contigs" from "globs don't see the names you're using". Pass `allRefNames`
+ * (canonical names AND aliases — `buildRefNameMaps` identity-maps every region,
+ * so it is a strict superset) and a pattern sees what a literal sees.
+ *
+ * It is optional ONLY because this is published ABI and the three-argument form
+ * predates it; an external plugin still calling that gets the canonical-only
+ * matching it always got. It is not optional because there is a state where an
+ * assembly has regions but not yet names — `setLoaded` writes `volatileRegions`
+ * and `refNameAliases` in one action, so no such state exists, and every
+ * in-tree caller (all of them through `resolveNamedRegions`) passes both.
+ */
+export function selectNamedRegions(regions, names, getCanonicalRefName, allRefNames) {
+    const byRefName = new Map(regions.map(r => [r.refName, r]));
+    // every name a glob may match on — see above for why the absent case is a
+    // legacy call rather than an unloaded assembly
+    const candidates = allRefNames?.length
+        ? allRefNames
+        : regions.map(r => r.refName);
+    const out = [];
+    const seen = new Set();
+    const take = (r) => {
+        if (r && !seen.has(r.refName)) {
+            seen.add(r.refName);
+            out.push(r);
+        }
+    };
+    for (const name of names) {
+        const exact = byRefName.get(getCanonicalRefName(name) ?? name);
+        if (exact) {
+            take(exact);
+        }
+        else if (name.includes('*')) {
+            const re = globToRegExp(name);
+            // Resolve every matching NAME to the region it names, then walk `regions`
+            // to emit them — the two passes are what keeps a glob's contribution in
+            // ASSEMBLY order. Matching over `candidates` directly would order by the
+            // alias map instead, which is the order the alias file happened to list.
+            const hits = new Set();
+            for (const candidate of candidates) {
+                if (re.test(candidate)) {
+                    hits.add(getCanonicalRefName(candidate) ?? candidate);
+                }
+            }
+            for (const r of regions) {
+                if (hits.has(r.refName)) {
+                    take(r);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Split a user-typed or URL-supplied region list into the entries
+ * `selectNamedRegions` takes. Comma-separated, because the two things anyone
+ * writes here are one glob (`*_MATERNAL`) or a short explicit list
+ * (`chr1, chr2`), and neither wants punctuation ceremony. Only the comma
+ * splits, so an HLA allele name — which carries both `*` and `:` — survives
+ * intact.
+ *
+ * Whitespace-trimmed and empties dropped, so a trailing comma, a box holding
+ * only spaces, and a bare `&regions=` all mean the same thing as nothing at
+ * all: no restriction, whole assembly. That last one is why this lives in core
+ * beside the matcher rather than next to the text box that first needed it —
+ * `&regions=` was reading the same syntax through a bare `split(',')`, so
+ * `&regions=chr1,%20chr2` dropped chr2 on the floor without a word and
+ * `&regions=` warned that a list of one empty name had matched nothing.
+ */
+export function parseRegionNames(value) {
+    return value
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s !== '');
+}
+/**
+ * `selectNamedRegions` plus the report a miss owes the user, which each of the
+ * four views taking `displayedRegionNames` had written out for itself — and two
+ * of them had not written at all, so a typo there showed the whole assembly and
+ * read as the field being ignored. A typo is no longer only a hand-authored-JSON
+ * mistake either: the dotplot and synteny import forms put this syntax in a text
+ * box.
+ *
+ * `undefined` means "this list picks out nothing" — the caller's cue to apply
+ * its own fallback, which is the part that genuinely differs between them: the
+ * LGV keeps a defaultSession's existing navigation, the circular view and a
+ * synteny row draw the whole assembly, and a dotplot axis is left as the
+ * regions autorun populated it.
+ */
+export function resolveNamedRegions({ regions, names, assemblyName, getCanonicalRefName, allRefNames, notify, }) {
+    const picked = selectNamedRegions(regions, names, getCanonicalRefName, allRefNames);
+    if (picked.length) {
+        return picked;
+    }
+    notify(`displayedRegionNames matched no regions in ${assemblyName}: ${names.join(', ')}`);
+    return undefined;
+}
+/**
+ * How many regions an INTERACTIVE glob will open at once. Displaying a few
+ * hundred whole chromosomes is ordinary — GRCh38 with its alts and decoys is
+ * ~640 refNames, and showAllRegionsInAssembly lays out every one — so this sits
+ * well above any real chromosome set and well below a scaffold-level assembly's
+ * contig count. Past it the offer is WITHHELD, never truncated: a bulk action
+ * reading "all of them" that opens the first thousand is the one behaviour not
+ * worth having.
+ *
+ * `selectNamedRegions` itself is deliberately unbounded — see its docstring.
+ * The bound belongs to the surfaces a person types at, not to the resolver a
+ * session spec goes through, because only the former has a way to say "too
+ * many, narrow it" and only the latter is a written-down intention.
+ */
+export const MAX_GLOB_REGIONS = 1000;
+/**
+ * The canonical refNames a search-box query picks out, in ASSEMBLY order.
+ *
+ * Shared by the dropdown's option list and by what Enter does, which is the
+ * whole point of it being one function: those two answer for the same typed
+ * text, and a surface-by-surface reading of one syntax is the split this file
+ * keeps being fixed for. A substring match (what the box has always done) and,
+ * when the text contains `*`, an anchored glob — union, never one instead of
+ * the other, since `*` is a legal refName character and a literal hit must
+ * survive the pattern reading of the same text.
+ *
+ * Matching runs over every name the assembly answers to, aliases included, and
+ * resolves hits to the canonical name — the name the view will display, and the
+ * same choice `searchRefNames` makes. Emitting by walking `regions` is what
+ * keeps assembly order rather than alias-file order.
+ *
+ * Bounded: matching stops one hit past `ceiling`, so a caller can tell "at the
+ * limit" from "under it" without the scan being unbounded.
+ */
+export function matchRefNames(assembly, inputValue, ceiling) {
+    const regions = assembly?.regions ?? [];
+    const query = inputValue.toLowerCase();
+    const glob = query.includes('*') ? globToRegExp(query) : undefined;
+    // getCanonicalRefName THROWS before aliases load, and is only ever reached
+    // for a name that came out of this list, which is empty in that state
+    const candidates = assembly?.allRefNames ?? [];
+    const hits = new Set();
+    for (const name of candidates) {
+        if (name.toLowerCase().includes(query) || glob?.test(name)) {
+            hits.add(assembly?.getCanonicalRefName(name) ?? name);
+            if (hits.size > ceiling) {
+                break;
+            }
+        }
+    }
+    const out = [];
+    for (const { refName } of regions) {
+        if (hits.has(refName)) {
+            out.push(refName);
+            // every hit is placed, so nothing later in `regions` can match
+            if (out.length === hits.size) {
+                break;
+            }
+        }
+    }
+    return out;
+}

package/esm/util/seqUtils.d.ts

@@ -0,0 +1,17 @@
+export declare const complementTable: Record<string, string>;
+export declare function revcom(str: string): string;
+export declare function reverse(str: string): string;
+export declare function complement(str: string): string;
+export type Frame = 1 | 2 | 3 | -1 | -2 | -3;
+export declare function getFrame(start: number, end: number, strand: 1 | -1, phase: 0 | 1 | 2): Frame;
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export declare const defaultStarts: string[];
+export declare function stitch(subfeats: {
+    start: number;
+    end: number;
+}[], sequence: string): string;

package/esm/util/seqUtils.js

@@ -0,0 +1,80 @@
+// from bioperl: tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/
+// generated with:
+// perl -MJSON -E '@l = split "","acgtrymkswhbvdnxACGTRYMKSWHBVDNX"; print to_json({ map { my $in = $_; tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/; $in => $_ } @l})'
+export const complementTable = {
+    S: 'S',
+    w: 'w',
+    T: 'A',
+    r: 'y',
+    a: 't',
+    N: 'N',
+    K: 'M',
+    x: 'x',
+    d: 'h',
+    Y: 'R',
+    V: 'B',
+    y: 'r',
+    M: 'K',
+    h: 'd',
+    k: 'm',
+    C: 'G',
+    g: 'c',
+    t: 'a',
+    A: 'T',
+    n: 'n',
+    W: 'W',
+    X: 'X',
+    m: 'k',
+    v: 'b',
+    B: 'V',
+    s: 's',
+    H: 'D',
+    c: 'g',
+    D: 'H',
+    b: 'v',
+    R: 'Y',
+    G: 'C',
+};
+export function revcom(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[n - 1 - i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function reverse(str) {
+    // index loop rather than [...str] spread: sequences can be large and the
+    // spread's code-point iterator is markedly slower than raw UTF-16 access
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        arr[i] = str[n - 1 - i];
+    }
+    return arr.join('');
+}
+export function complement(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function getFrame(start, end, strand, phase) {
+    return strand === 1
+        ? (((start + phase) % 3) + 1)
+        : (-1 * ((end - phase) % 3) - 1);
+}
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export const defaultStarts = ['ATG'];
+export function stitch(subfeats, sequence) {
+    return subfeats.map(sub => sequence.slice(sub.start, sub.end)).join('');
+}

package/esm/util/sessionServices.d.ts

@@ -0,0 +1,29 @@
+import type { DialogHost, NotificationSink, PaletteHost, RpcHost, SessionServices } from './types/services.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * The services a session offers that cost nothing application-shaped to name.
+ * Prefer one of the narrower accessors below, which say which of them the
+ * calling module actually uses.
+ */
+export declare function getSessionServices(node: IAnyStateTreeNode): SessionServices;
+/**
+ * #api core/util
+ * The host's RPC entry point, for a module that issues RPCs and nothing else.
+ */
+export declare function getRpcHost(node: IAnyStateTreeNode): RpcHost;
+/**
+ * #api core/util
+ * Where a display puts a message it cannot draw itself.
+ */
+export declare function getNotificationSink(node: IAnyStateTreeNode): NotificationSink;
+/**
+ * #api core/util
+ * Where a display puts a dialog it cannot mount itself.
+ */
+export declare function getDialogHost(node: IAnyStateTreeNode): DialogHost;
+/**
+ * #api core/util
+ * The colors to draw with, and the args that rebuild them in a worker.
+ */
+export declare function getPaletteHost(node: IAnyStateTreeNode): PaletteHost;

package/esm/util/sessionServices.js

@@ -0,0 +1,46 @@
+import { cachedParent, findParentThatIs } from './parentWalk.js';
+import { isSessionServices } from './types/services.js';
+// `getSession(self).notify(...)` and `getNotificationSink(self).notify(...)`
+// find the same object; the difference is what the calling module then has in
+// its type graph, which is the whole session interface in the first case and
+// four function signatures in the second. The return annotations are therefore
+// deliberate rather than inferred — widening one back to `SessionServices`
+// would undo the point of the accessor.
+const sessionServicesCache = new WeakMap();
+/**
+ * #api core/util
+ * The services a session offers that cost nothing application-shaped to name.
+ * Prefer one of the narrower accessors below, which say which of them the
+ * calling module actually uses.
+ */
+export function getSessionServices(node) {
+    return cachedParent(sessionServicesCache, node, () => findParentThatIs(node, isSessionServices), 'no session model found!');
+}
+/**
+ * #api core/util
+ * The host's RPC entry point, for a module that issues RPCs and nothing else.
+ */
+export function getRpcHost(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * Where a display puts a message it cannot draw itself.
+ */
+export function getNotificationSink(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * Where a display puts a dialog it cannot mount itself.
+ */
+export function getDialogHost(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * The colors to draw with, and the args that rebuild them in a worker.
+ */
+export function getPaletteHost(node) {
+    return getSessionServices(node);
+}

package/esm/util/sessionSharing.d.ts

@@ -0,0 +1,38 @@
+export declare function b64PadSuffix(b64: string): string;
+/**
+ * Decode and inflate a url-safe base64 to a string
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export declare function fromUrlSafeB64(b64: string): Promise<string>;
+/**
+ * Compress and encode a string as url-safe base64
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export declare function toUrlSafeB64(str: string): Promise<string>;
+/**
+ * The `?session=` value prefixes, named here because this module is what
+ * produces them. The decoder half (jbrowse-web's SessionLoader) has its own
+ * list covering the two prefixes nothing here writes (`spec-`, `local-`).
+ */
+export declare const SHARE_PREFIX = "share-";
+export declare const ENCODED_PREFIX = "encoded-";
+export declare const JSON_PREFIX = "json-";
+/**
+ * Joins a configured `shareURL` with one of the share service's two endpoints.
+ * A plain `${shareURL}share` silently produced `https://host/api/v1share` for
+ * the (natural) configured value without a trailing slash, and the 404 that
+ * followed read as "the share service is down". An empty shareURL is left
+ * alone: web honors an explicit empty string as "resolve relative to the page".
+ */
+export declare function shareEndpoint(shareURL: string, path: 'share' | 'load'): string;
+export type SessionShareMode = 'short' | 'long' | 'json';
+export interface EncodedSessionParam {
+    sessionParam: string;
+    password?: string;
+    plaintext?: string;
+}
+export declare function encodeSessionParam(mode: SessionShareMode, session: unknown, options: {
+    shareURL: string;
+    referer: string;
+}): Promise<EncodedSessionParam>;
+export declare function readSessionFromDynamo(loadUrl: string, sessionQueryParam: string, password: string, signal?: AbortSignal): Promise<string>;

package/esm/util/sessionSharing.js

@@ -0,0 +1,154 @@
+import { aesDecrypt, aesEncrypt } from './crypto.js';
+function bytesToBinaryString(bytes) {
+    return Array.from(bytes, b => String.fromCharCode(b)).join('');
+}
+// from https://stackoverflow.com/questions/1349404/
+// crypto.getRandomValues is available in non-secure contexts per MDN,
+// unlike crypto.subtle which requires HTTPS.
+function generateUID(length) {
+    return window
+        .btoa(bytesToBinaryString(crypto.getRandomValues(new Uint8Array(length * 2))))
+        .replaceAll(/[+/]/g, '')
+        .slice(0, length);
+}
+function getErrorMsg(err) {
+    try {
+        const obj = JSON.parse(err);
+        return obj.message ?? err;
+    }
+    catch {
+        return err;
+    }
+}
+export function b64PadSuffix(b64) {
+    let num;
+    const mo = b64.length % 4;
+    switch (mo) {
+        case 3:
+            num = 1;
+            break;
+        case 2:
+            num = 2;
+            break;
+        case 0:
+            num = 0;
+            break;
+        default:
+            throw new Error('Illegal base64url string!');
+    }
+    return b64 + '='.repeat(num);
+}
+/**
+ * Decode and inflate a url-safe base64 to a string
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export async function fromUrlSafeB64(b64) {
+    const originalB64 = b64PadSuffix(b64.replaceAll('-', '+').replaceAll('_', '/'));
+    const { inflate } = await import('pako-esm2');
+    const bytes = Uint8Array.from(atob(originalB64), c => c.charCodeAt(0));
+    const inflated = inflate(bytes, undefined);
+    return new TextDecoder('utf8').decode(inflated);
+}
+/**
+ * Compress and encode a string as url-safe base64
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export async function toUrlSafeB64(str) {
+    const bytes = new TextEncoder().encode(str);
+    const { deflate } = await import('pako-esm2');
+    const deflated = deflate(bytes, undefined);
+    const encoded = btoa(bytesToBinaryString(deflated)).replace(/=+$/, '');
+    return encoded.replaceAll('+', '-').replaceAll('/', '_');
+}
+/**
+ * The `?session=` value prefixes, named here because this module is what
+ * produces them. The decoder half (jbrowse-web's SessionLoader) has its own
+ * list covering the two prefixes nothing here writes (`spec-`, `local-`).
+ */
+export const SHARE_PREFIX = 'share-';
+export const ENCODED_PREFIX = 'encoded-';
+export const JSON_PREFIX = 'json-';
+/**
+ * Joins a configured `shareURL` with one of the share service's two endpoints.
+ * A plain `${shareURL}share` silently produced `https://host/api/v1share` for
+ * the (natural) configured value without a trailing slash, and the 404 that
+ * followed read as "the share service is down". An empty shareURL is left
+ * alone: web honors an explicit empty string as "resolve relative to the page".
+ */
+export function shareEndpoint(shareURL, path) {
+    return shareURL && !shareURL.endsWith('/')
+        ? `${shareURL}/${path}`
+        : `${shareURL}${path}`;
+}
+/**
+ * writes the encrypted session, current datetime, and referer to DynamoDB
+ */
+async function shareSessionToDynamo(session, shareURL, referer) {
+    const sess = await toUrlSafeB64(JSON.stringify(session));
+    const password = generateUID(5);
+    const data = new FormData();
+    data.append('session', await aesEncrypt(sess, password));
+    data.append('dateShared', `${Date.now()}`);
+    data.append('referer', referer);
+    const response = await fetch(shareEndpoint(shareURL, 'share'), {
+        method: 'POST',
+        mode: 'cors',
+        body: data,
+    });
+    if (!response.ok) {
+        throw new Error(getErrorMsg(await response.text()));
+    }
+    const { sessionId } = (await response.json());
+    return { sessionId, password };
+}
+// Encodes a session snapshot into the `?session=` value jbrowse-web decodes:
+// `share-<id>` (uploaded + encrypted), `encoded-<b64>` (compressed inline), or
+// `json-<json>` (plaintext inline). Single source of these prefixes, shared by
+// jbrowse-web's ShareDialog and jbrowse-desktop's ExportToWebDialog so the two
+// producers can't drift from the decoder.
+export async function encodeSessionParam(mode, session, options) {
+    if (mode === 'short') {
+        const { sessionId, password } = await shareSessionToDynamo(session, options.shareURL, options.referer);
+        return { sessionParam: `${SHARE_PREFIX}${sessionId}`, password };
+    }
+    else if (mode === 'json') {
+        // compact in the link (this mode's URL is the longest of the three
+        // already), indented in the dialog's readable-JSON panel
+        return {
+            sessionParam: `${JSON_PREFIX}${JSON.stringify({ session })}`,
+            plaintext: JSON.stringify({ session }, null, 2),
+        };
+    }
+    else {
+        const encoded = await toUrlSafeB64(JSON.stringify(session));
+        return { sessionParam: `${ENCODED_PREFIX}${encoded}` };
+    }
+}
+export async function readSessionFromDynamo(loadUrl, sessionQueryParam, password, signal) {
+    const sessionId = sessionQueryParam.startsWith(SHARE_PREFIX)
+        ? sessionQueryParam.slice(SHARE_PREFIX.length)
+        : sessionQueryParam;
+    // The password never reaches the server — it lives only in the link — so a
+    // link that lost its `&password=` (a chat client that clipped the URL, a
+    // hand-edited link) fetches fine and then fails in the cipher, where the
+    // browser's message is "The operation failed for an operation-specific
+    // reason". Say what actually went wrong instead.
+    if (!password) {
+        throw new Error('This shared session link is missing its "password" URL parameter, which is the only thing that can decrypt it');
+    }
+    const url = `${loadUrl}?sessionId=${encodeURIComponent(sessionId)}`;
+    const response = await fetch(url, { signal });
+    if (!response.ok) {
+        throw new Error(getErrorMsg(await response.text()));
+    }
+    const json = (await response.json());
+    if (typeof json.session !== 'string') {
+        throw new Error('Shared session not found — the link may have expired or the id is wrong');
+    }
+    try {
+        return await aesDecrypt(json.session, password);
+    }
+    catch (e) {
+        throw new Error('Could not decrypt the shared session — the "password" in the link is wrong or the link was truncated', { cause: e });
+    }
+}

package/esm/util/sessionStorage.d.ts

@@ -0,0 +1 @@
+export declare const sessionStorageAvailable: () => boolean, sessionStorageGetItem: (key: string) => string | undefined, sessionStorageSetItem: (key: string, value: string) => boolean, sessionStorageRemoveItem: (key: string) => boolean;

package/esm/util/sessionStorage.js

@@ -0,0 +1,15 @@
+// sessionStorage, guarded exactly as localStorage is — see webStorage.ts for
+// the three ways a Web Storage store fails.
+//
+// This store holds the internet-account access tokens, which is a per-tab cache
+// of something the user can always be asked for again. So a store that refuses
+// to be read or written costs an extra auth prompt, and a throw out of
+// `storeToken` takes the whole auth flow down instead — in the embedded
+// products, on someone else's page, which is where third-party storage is
+// blocked in the first place.
+//
+// Deliberately no `sessionStorageSetJSON` / `…GetJSON` twins: jbrowse-web's
+// session mirror is the other caller, and it *wants* the quota throw so it can
+// tell the user its autosave has stopped working.
+import { guardedSessionStorage } from './webStorage.js';
+export const { available: sessionStorageAvailable, getItem: sessionStorageGetItem, setItem: sessionStorageSetItem, removeItem: sessionStorageRemoveItem, } = guardedSessionStorage;

package/esm/util/setStackTraceLimit.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface ErrorConstructor {
+        stackTraceLimit: number;
+    }
+}
+export declare function setStackTraceLimit(): void;

package/esm/util/setStackTraceLimit.js

@@ -0,0 +1,20 @@
+// V8 records only the top 10 frames of any Error by default, and the RPC,
+// React and MST plumbing can consume all 10 before reaching JBrowse code —
+// truncating bug reports right above the actual fault. 50 gets through the
+// wrappers. Costs ~34µs extra per Error constructed, which is irrelevant here:
+// JBrowse throws exceptionally, not as control flow (MST's typecheck failures
+// are plain objects, not Errors).
+//
+// Only *applications* should call this. It mutates a global, so the embeddable
+// products (@jbrowse/react-app, react-linear-genome-view, ...) must not impose
+// it on their host page. Worker entry points are fair game: that scope is ours,
+// and a worker error's stack is captured in the worker, so the limit has to be
+// raised there to have any effect on it.
+//
+// No-op outside V8 — firefox and safari have no equivalent knob and ignore the
+// assignment.
+export function setStackTraceLimit() {
+    // setting this V8-only property is the entire point; engines without it ignore it
+    // eslint-disable-next-line unicorn/no-nonstandard-builtin-properties
+    Error.stackTraceLimit = 50;
+}