@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/paintLayer.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SvgCanvas } from './SvgCanvas.js';
+import { createSvgRasterCanvas } from './createSvgRasterCanvas.js';
+/**
+ * Paint into either a 2× rasterize canvas (PNG-embedded as <image>) or an
+ * SvgCanvas (serialized into a <g>). Renders one element — callers don't
+ * branch on which mode was picked.
+ *
+ * Used by every renderSvg.tsx that has a heavy draw path: the same `paint`
+ * callback runs on both surfaces, with `paint(ctx)` doing whatever drawing
+ * the plugin needs in logical coordinates (the raster canvas is pre-scaled, so
+ * callbacks never deal with devicePixelRatio). Width 0 or height 0 falls
+ * through to the vector branch (canvas creation rejects 0×0).
+ *
+ * A vector layer whose `paint` drew nothing renders nothing — not an empty
+ * `<g>`. Layers are routinely conditional on data (a highlight pass with no
+ * highlighted feature, a legend-less track, a band that is switched off), and
+ * every such layer was leaving a stray group in the file for a reader to open
+ * and find empty. The raster branch has no cheap equivalent — asking whether a
+ * canvas is blank means reading its pixels back — and it does not need one: a
+ * fully transparent PNG is a couple of hundred bytes.
+ */
+export function PaintLayer({ width, height, opts, paint, }) {
+    if (opts?.rasterizeLayers && width > 0 && height > 0) {
+        const { canvas, ctx } = createSvgRasterCanvas(width, height, opts);
+        paint(ctx);
+        return (_jsx("image", { width: width, height: height, xlinkHref: canvas.toDataURL('image/png') }));
+    }
+    const svg = new SvgCanvas();
+    paint(svg);
+    const markup = svg.getSerializedSvg();
+    return markup ? (_jsx("g", { dangerouslySetInnerHTML: { __html: markup } })) : null;
+}

package/esm/util/parentWalk.d.ts

@@ -0,0 +1,32 @@
+import type { TypeTestedByPredicate } from './types/predicate.ts';
+import type { IAnyStateTreeNode, IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export declare function findParentThat(node: IAnyStateTreeNode, predicate: (thing: IAnyStateTreeNode) => boolean): IStateTreeNode<IAnyStateTreeNode> | (object & IStateTreeNode<import("@jbrowse/mobx-state-tree").IAnyComplexType>);
+export declare function findParentThatIs<T extends (a: IAnyStateTreeNode) => boolean>(node: IAnyStateTreeNode, predicate: T): TypeTestedByPredicate<T>;
+/**
+ * Memoized ancestor lookups, and load-bearing ones: `getSession` alone has 465
+ * call sites and is reached from render paths, while the walk it replaces is
+ * six `getParent` hops — every MST array between a display and the session is a
+ * node of its own. Worth 13.6-17.6x, and 3.2-3.7x even inside a reaction
+ * (`packages/core/benches/parentWalkMemo.bench.ts`, which also rules out the
+ * obvious alternative: the predicate's `in` checks are ~1% of the walk, so
+ * making it cheaper buys nothing).
+ *
+ * Keying on the node is safe because nothing re-parents one — both `detach`
+ * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
+ * a cached ancestor can only go stale by dying, which the `isAlive` check
+ * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * removing: each keyed on something its caller had just allocated.
+ */
+export declare function cachedParent<T>(cache: WeakMap<IAnyStateTreeNode, T>, node: IAnyStateTreeNode, finder: () => T, errorMsg: string): T;
+/**
+ * The `rpcSessionId` of the highest node at or above `thisNode` that declares
+ * one — which webworker its work is routed to.
+ *
+ * The walk includes the root. It used to stop *before* it (`!isRoot(node)` as
+ * the loop condition), which silently made a tree whose only rpcSessionId-
+ * bearing node was the root throw "no parent node in the state tree has an
+ * `rpcSessionId`". Nothing in the app hit that — the id lives on a track, deep
+ * in the tree — but a test building a minimal session had to wrap it in a
+ * throwaway root purely to dodge this.
+ */
+export declare function getRpcSessionId(thisNode: IAnyStateTreeNode): string;

package/esm/util/parentWalk.js

@@ -0,0 +1,84 @@
+import { getParent, hasParent, isAlive, isRoot } from '@jbrowse/mobx-state-tree';
+// The ancestor walk itself, with no application in its type graph.
+// `mstUtils.ts` is where the walks that return an `AbstractSessionModel` live
+// and is therefore as expensive to import as the session interface;
+// `sessionServices.ts` gets the same primitives without paying for that.
+export function findParentThat(node, predicate) {
+    if (!hasParent(node)) {
+        const alive = isAlive(node);
+        const nodeType = node.type;
+        console.warn(`[findParentThat] node has no parent: alive=${alive} type=${nodeType}`);
+        throw new Error('node does not have parent');
+    }
+    let currentNode = getParent(node);
+    while (isAlive(currentNode)) {
+        if (predicate(currentNode)) {
+            return currentNode;
+        }
+        if (hasParent(currentNode)) {
+            currentNode = getParent(currentNode);
+        }
+        else {
+            break;
+        }
+    }
+    throw new Error('no matching node found');
+}
+export function findParentThatIs(node, predicate) {
+    return findParentThat(node, predicate);
+}
+/**
+ * Memoized ancestor lookups, and load-bearing ones: `getSession` alone has 465
+ * call sites and is reached from render paths, while the walk it replaces is
+ * six `getParent` hops — every MST array between a display and the session is a
+ * node of its own. Worth 13.6-17.6x, and 3.2-3.7x even inside a reaction
+ * (`packages/core/benches/parentWalkMemo.bench.ts`, which also rules out the
+ * obvious alternative: the predicate's `in` checks are ~1% of the walk, so
+ * making it cheaper buys nothing).
+ *
+ * Keying on the node is safe because nothing re-parents one — both `detach`
+ * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
+ * a cached ancestor can only go stale by dying, which the `isAlive` check
+ * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * removing: each keyed on something its caller had just allocated.
+ */
+export function cachedParent(cache, node, finder, errorMsg) {
+    const cached = cache.get(node);
+    if (cached && isAlive(cached)) {
+        return cached;
+    }
+    try {
+        const result = finder();
+        cache.set(node, result);
+        return result;
+    }
+    catch (e) {
+        throw new Error(errorMsg, { cause: e });
+    }
+}
+/**
+ * The `rpcSessionId` of the highest node at or above `thisNode` that declares
+ * one — which webworker its work is routed to.
+ *
+ * The walk includes the root. It used to stop *before* it (`!isRoot(node)` as
+ * the loop condition), which silently made a tree whose only rpcSessionId-
+ * bearing node was the root throw "no parent node in the state tree has an
+ * `rpcSessionId`". Nothing in the app hit that — the id lives on a track, deep
+ * in the tree — but a test building a minimal session had to wrap it in a
+ * throwaway root purely to dodge this.
+ */
+export function getRpcSessionId(thisNode) {
+    let highestRpcSessionId;
+    for (let node = thisNode;; node = getParent(node)) {
+        if ('rpcSessionId' in node) {
+            highestRpcSessionId = node.rpcSessionId;
+        }
+        if (isRoot(node)) {
+            break;
+        }
+    }
+    if (!highestRpcSessionId) {
+        throw new Error('getRpcSessionId failed, no parent node in the state tree has an `rpcSessionId` attribute');
+    }
+    return highestRpcSessionId;
+}

package/esm/util/parseLineByLine.d.ts

@@ -1,3 +1,46 @@
-export type StatusCallback = (arg: string) => void;
+import { IntervalTree } from './IntervalTree.ts';
+import type { StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+export type { StatusCallback };
 export type LineCallback = (line: string, lineIndex: number) => boolean | undefined;
-export declare function parseLineByLine(buffer: Uint8Array, lineCallback: LineCallback, statusCallback?: StatusCallback): void;
+/**
+ * Scan a tab-delimited genomic flat file (GFF3, GTF, BED, …), grouping
+ * feature lines by reference name (first tab-delimited column).
+ * Stops at an embedded FASTA section (`>`). Lines starting with `#` are
+ * collected as header lines.
+ */
+export declare function groupLinesByRef(buffer: Uint8Array, statusCallback?: StatusCallback): {
+    headerLines: string[];
+    linesByRef: Record<string, string[]>;
+};
+/**
+ * Build a `refName -> lazy IntervalTree` map from feature lines grouped by ref
+ * (the output of {@link groupLinesByRef}). Each ref's lines are parsed and
+ * indexed into an interval tree on first access, then the raw lines are
+ * released. Shared scaffolding for the plain-text GFF3 and GTF adapters, which
+ * differ only in how they parse a ref's lines into features.
+ */
+export declare function makeFeatureIntervalTreeMap<T extends {
+    start: number;
+    end: number;
+}>(linesByRef: Record<string, string[]>, parse: (lines: string[], refName: string) => T[], parsingStatusMessage: string): {
+    [k: string]: (statusCallback?: StatusCallback) => IntervalTree<T>;
+};
+/**
+ * Parse buffer line by line, calling a callback for each line
+ * @param buffer - The buffer to parse
+ * @param lineCallback - Callback function called for each line. Return false to stop parsing.
+ * @param statusCallback - Progress channel, or `undefined` for none. A required
+ *   parameter with a nullable value rather than an optional one, so a caller
+ *   states which it means; `undefined` is the value the rest of this module's
+ *   contract is built on ("no channel, skip the bookkeeping"), and it used to
+ *   default to `() => {}`, which says the opposite.
+ * @param opts - `label` names the phase on the progress bar (a multi-phase
+ *   adapter wants "Parsing PAF", not another "Loading" indistinguishable from
+ *   the download that preceded it); `stopToken` makes a multi-GB parse
+ *   interruptible instead of running to completion after a cancel.
+ */
+export declare function parseLineByLine(buffer: Uint8Array, lineCallback: LineCallback, statusCallback: StatusCallback | undefined, opts?: {
+    label?: string;
+    stopToken?: StopToken;
+}): void;

package/esm/util/parseLineByLine.js

@@ -1,22 +1,163 @@
-import { getProgressDisplayStr } from "./index.js";
-export function parseLineByLine(buffer, lineCallback, statusCallback = () => { }) {
+import { IntervalTree } from './IntervalTree.js';
+import { createProgressReporter } from './progress.js';
+/**
+ * Scan a tab-delimited genomic flat file (GFF3, GTF, BED, …), grouping
+ * feature lines by reference name (first tab-delimited column).
+ * Stops at an embedded FASTA section (`>`). Lines starting with `#` are
+ * collected as header lines.
+ */
+export function groupLinesByRef(buffer, statusCallback) {
+    const headerLines = [];
+    const linesByRef = {};
+    parseLineByLine(buffer, line => {
+        if (line.startsWith('#')) {
+            headerLines.push(line);
+        }
+        else if (line.startsWith('>')) {
+            return false;
+        }
+        else {
+            // a line with no tab has no coordinate columns either, so it cannot be
+            // a feature line; keying it by its own text would publish it through
+            // getRefNames as a phantom refName
+            const tab = line.indexOf('\t');
+            if (tab !== -1) {
+                ;
+                (linesByRef[line.slice(0, tab)] ??= []).push(line);
+            }
+        }
+        return true;
+    }, statusCallback);
+    return { headerLines, linesByRef };
+}
+/**
+ * Build a `refName -> lazy IntervalTree` map from feature lines grouped by ref
+ * (the output of {@link groupLinesByRef}). Each ref's lines are parsed and
+ * indexed into an interval tree on first access, then the raw lines are
+ * released. Shared scaffolding for the plain-text GFF3 and GTF adapters, which
+ * differ only in how they parse a ref's lines into features.
+ */
+export function makeFeatureIntervalTreeMap(linesByRef, parse, parsingStatusMessage) {
+    const cache = {};
+    return Object.fromEntries(Object.entries(linesByRef).map(([refName, refLines]) => {
+        let lines = refLines;
+        return [
+            refName,
+            (statusCallback) => {
+                if (!cache[refName]) {
+                    statusCallback?.(parsingStatusMessage);
+                    const intervalTree = new IntervalTree();
+                    for (const feature of parse(lines, refName)) {
+                        intervalTree.insert([feature.start, feature.end], feature);
+                    }
+                    lines = null;
+                    cache[refName] = intervalTree;
+                }
+                return cache[refName];
+            },
+        ];
+    }));
+}
+// Decode window. Deliberately small: the win over per-line decoding is in
+// amortizing the per-call cost, which is already gone by a few KB, and a small
+// window keeps the decoded string in cache and the extra memory bounded. A
+// whole-buffer decode measured no faster and has two failure modes this avoids
+// — it doubles peak memory, and V8 caps a string at ~512MB, which a large
+// uncompressed GFF3 can exceed.
+const DECODE_CHUNK_SIZE = 64 * 1024;
+const NEWLINE = 10;
+/**
+ * End of the decode chunk starting at `start`: the nominal window extended
+ * *forward* to just past the next newline, so a chunk never ends mid-line and
+ * therefore never ends mid-character either (a newline byte cannot occur inside
+ * a UTF-8 multi-byte sequence, whose continuation bytes are all >= 0x80). That
+ * is what lets each chunk be decoded independently, without `{stream: true}`.
+ *
+ * Extending forward rather than trimming back to the previous newline matters
+ * for a line longer than the window: trimming back has no newline to find and
+ * would either split the line or stall, while extending simply makes one
+ * oversized chunk and moves on.
+ */
+function chunkBoundary(buffer, start) {
+    const nominal = start + DECODE_CHUNK_SIZE;
+    if (nominal >= buffer.length) {
+        return buffer.length;
+    }
+    const nl = buffer.indexOf(NEWLINE, nominal);
+    return nl === -1 ? buffer.length : nl + 1;
+}
+/**
+ * Parse buffer line by line, calling a callback for each line
+ * @param buffer - The buffer to parse
+ * @param lineCallback - Callback function called for each line. Return false to stop parsing.
+ * @param statusCallback - Progress channel, or `undefined` for none. A required
+ *   parameter with a nullable value rather than an optional one, so a caller
+ *   states which it means; `undefined` is the value the rest of this module's
+ *   contract is built on ("no channel, skip the bookkeeping"), and it used to
+ *   default to `() => {}`, which says the opposite.
+ * @param opts - `label` names the phase on the progress bar (a multi-phase
+ *   adapter wants "Parsing PAF", not another "Loading" indistinguishable from
+ *   the download that preceded it); `stopToken` makes a multi-GB parse
+ *   interruptible instead of running to completion after a cancel.
+ */
+export function parseLineByLine(buffer, lineCallback, statusCallback, opts = {}) {
+    const { label = 'Loading', stopToken } = opts;
     const decoder = new TextDecoder('utf8');
-    let blockStart = 0;
+    // Time-gated, not gated on a line counter: a file of few but very expensive
+    // lines would never reach a count mask, freezing the bar at 0% for the whole
+    // parse (the failure createProgressReporter documents). The stop-token check
+    // rides the same tick, so cancellation lands within one window.
+    const report = createProgressReporter({
+        label,
+        total: buffer.length,
+        statusCallback,
+        stopToken,
+    });
+    let chunkStart = 0;
     let i = 0;
-    while (blockStart < buffer.length) {
-        const n = buffer.indexOf(10, blockStart);
-        const lineEnd = n === -1 ? buffer.length : n;
-        const b = buffer.subarray(blockStart, lineEnd);
-        const line = decoder.decode(b).trim();
-        if (line) {
-            const shouldContinue = lineCallback(line, i);
-            if (shouldContinue === false) {
+    let stopped = false;
+    try {
+        while (chunkStart < buffer.length) {
+            const chunkEnd = chunkBoundary(buffer, chunkStart);
+            // One decode per chunk rather than one per line. TextDecoder.decode costs
+            // roughly a microsecond per call regardless of length, which a per-line
+            // decode pays once per line: ~100ms of a 12MB/157k-line GFF3 was this
+            // call alone, and the cost scales with line *count*, so the files that
+            // suffer most are the dense ones. Slicing the decoded chunk instead is
+            // ~4x faster over the same bytes.
+            const text = decoder.decode(buffer.subarray(chunkStart, chunkEnd));
+            let p = 0;
+            while (p < text.length) {
+                const n = text.indexOf('\n', p);
+                // the final chunk of a file with no trailing newline ends without one
+                const lineEnd = n === -1 ? text.length : n;
+                const line = text.slice(p, lineEnd).trim();
+                if (line) {
+                    const shouldContinue = lineCallback(line, i);
+                    if (shouldContinue === false) {
+                        stopped = true;
+                        break;
+                    }
+                }
+                i++;
+                // Chunk-granular position, not line-granular: `report` is called every
+                // line so cancellation still lands within one throttle window, but the
+                // byte offset it publishes only advances per chunk. Interpolating
+                // within the chunk would mean converting a UTF-16 offset back to a byte
+                // offset, and at 64KB the bar already moves in sub-percent steps.
+                report(chunkStart);
+                p = lineEnd + 1;
+            }
+            if (stopped) {
                 break;
             }
+            chunkStart = chunkEnd;
         }
-        if (i++ % 10_000 === 0) {
-            statusCallback(`Loading ${getProgressDisplayStr(blockStart, buffer.length)}`);
-        }
-        blockStart = lineEnd + 1;
+    }
+    finally {
+        // Cleared in a finally: on the happy path so the finished parse's last
+        // percentage doesn't sit on screen through whatever unlabelled phase runs
+        // next, and on a throw (or a cancel) so it doesn't sit under the error.
+        statusCallback?.('');
     }
 }

package/esm/util/parseMotifList.d.ts

@@ -0,0 +1,17 @@
+export interface ParsedMotif {
+    name: string;
+    site: string;
+    line: string;
+    cutOffset?: number;
+    cutOffsetBottom?: number;
+}
+export interface MotifParseError {
+    line: number;
+    text: string;
+    message: string;
+}
+export interface MotifListParse {
+    motifs: ParsedMotif[];
+    errors: MotifParseError[];
+}
+export declare function parseMotifList(text: string): MotifListParse;

package/esm/util/parseMotifList.js

@@ -0,0 +1,69 @@
+import { IUPAC_MOTIF_REGEX } from './iupac.js';
+// REBASE writes an enzyme that cuts OUTSIDE its recognition site as
+// `GGTCTC(1/5)`: the two numbers are the top- and bottom-strand cuts counted
+// from the site's 3' end (negative counts back into the site). Every type IIS
+// enzyme — BsaI, BsmBI, BbsI, SapI, AarI, the whole Golden Gate set — is written
+// this way, so a pasted REBASE list is largely unusable without it.
+const CUT_OFFSET_NOTATION = /\((-?\d+)\/(-?\d+)\)$/;
+// Parses a pasted list of named motifs, one per line, in the notation REBASE
+// already uses for restriction enzymes:
+//
+//   EcoRI  G^AATTC     name + site, '^' marks the top-strand cut
+//   BsaI   GGTCTC(1/5) cuts downstream of the site, top/bottom
+//   GGTNACC            bare site, name defaults to the site
+//   # comment
+//
+// The cut notation is the whole reason this format is worth honoring: it carries
+// the cut positions, so no per-enzyme table needs to be baked in — a user can
+// paste any enzyme set (or any motif set at all) straight from their own source.
+export function parseMotifList(text) {
+    const motifs = [];
+    const errors = [];
+    for (const [idx, rawLine] of text.split('\n').entries()) {
+        const line = rawLine.trim();
+        if (line && !line.startsWith('#')) {
+            const tokens = line.split(/[\s,]+/);
+            const fail = (message) => {
+                errors.push({ line: idx + 1, text: line, message });
+            };
+            if (tokens.length > 2) {
+                fail('Expected "<name> <site>" or "<site>"');
+            }
+            else {
+                const rawSite = (tokens.length === 2 ? tokens[1] : tokens[0]).toUpperCase();
+                const offsets = CUT_OFFSET_NOTATION.exec(rawSite);
+                const marked = offsets ? rawSite.slice(0, offsets.index) : rawSite;
+                const caretIdx = marked.indexOf('^');
+                const site = marked.replaceAll('^', '');
+                const name = tokens.length === 2 ? tokens[0] : site;
+                if (offsets && caretIdx !== -1) {
+                    fail('Use either ^ or (n/m) to mark the cut, not both');
+                }
+                else if (caretIdx !== marked.lastIndexOf('^')) {
+                    fail('Use at most one ^ to mark the cut position');
+                }
+                else if (!site) {
+                    fail('Missing sequence');
+                }
+                else if (!IUPAC_MOTIF_REGEX.test(site)) {
+                    fail(`"${site}" contains non-IUPAC characters`);
+                }
+                else {
+                    motifs.push({
+                        name,
+                        site,
+                        line,
+                        ...(caretIdx === -1 ? {} : { cutOffset: caretIdx }),
+                        ...(offsets
+                            ? {
+                                cutOffset: site.length + Number(offsets[1]),
+                                cutOffsetBottom: site.length + Number(offsets[2]),
+                            }
+                            : {}),
+                    });
+                }
+            }
+        }
+    }
+    return { motifs, errors };
+}

package/esm/util/pluginStore.d.ts

@@ -0,0 +1,113 @@
+import type { PluginDefinition } from '../pluginDefinitions.ts';
+import type { JBrowsePlugin } from './types/data.ts';
+/**
+ * The store entries a product can install at all, before any user filter. Both
+ * surfaces that list the store go through this — the in-session plugin store
+ * widget and Desktop's global plugins dialog — because an entry one of them
+ * offers and the loader behind the other drops is a silent install: the button
+ * says Installed (or stays live, and every click appends another dead entry) and
+ * nothing about the running app changes.
+ *
+ * Two independent reasons to hide an entry:
+ *
+ * - **No build this product can load.** Web runs ESM/UMD; a CJS-only entry needs
+ *   Node's `require`, so only Desktop can install it. Asked of every build the
+ *   entry publishes rather than only the top-level urls — an entry that pins urls
+ *   per version, which `resolvePlugin`'s fallback exists to accommodate, used to
+ *   vanish from Web's list with no diagnostic. An entry whose *resolved* build is
+ *   the CJS-only one is still shown, since that is a fact about this JBrowse
+ *   version rather than about the product, and PluginStoreCard already has a
+ *   place to say so.
+ * - **Already vendored into this product's core bundle**, where installing does
+ *   nothing because `dropVendoredPlugins` drops the definition at load. Desktop's
+ *   half of that list counts too, and is the half both surfaces were missing.
+ */
+export declare function installablePlugins(plugins: JBrowsePlugin[], isElectron: boolean): JBrowsePlugin[];
+export interface ResolvedPlugin {
+    compatible: boolean;
+    pluginVersion?: string;
+    supportedRanges: string[];
+    definition: PluginDefinition | undefined;
+}
+export interface PluginUpdate {
+    pluginVersion: string;
+    name: string;
+    definition: PluginDefinition;
+}
+export declare function resolvePlugin(plugin: JBrowsePlugin, jbrowseVersion: string): ResolvedPlugin;
+export declare function installedVersionFromUrl(url: string | undefined, packageName: string | undefined): string | undefined;
+/**
+ * Whether a store entry is already among `installed`.
+ *
+ * Matched by packageName rather than by the resolved url wherever the store
+ * publishes one: once a newer compatible version appears the resolved url
+ * changes, and a url match would report "not installed" and let the user add a
+ * second copy of the same plugin (same UMD global name) alongside the one
+ * already there, which then fails to load with duplicate pluggable-element
+ * registrations. Moving to a newer version is a separate, explicit action.
+ */
+export declare function isPluginInstalled(plugin: JBrowsePlugin, resolved: ResolvedPlugin, installed: PluginDefinition[]): boolean;
+export declare function getPluginUpdate(plugin: JBrowsePlugin, jbrowseVersion: string, installedVersion: string | undefined): PluginUpdate | undefined;
+/**
+ * A definition whose store ref could not be turned into something loadable,
+ * with the reason.
+ *
+ * Structurally identical to `PluginLoader`'s `PluginLoadFailure`, and
+ * deliberately re-declared rather than imported: that module pulls in ReExports
+ * — effectively all of core — which is the whole reason inspecting a definition
+ * lives apart from running one. Matching the shape lets a product report a
+ * plugin that could not be resolved and one that could not be loaded through a
+ * single path, which is what its user sees anyway.
+ */
+export interface StorePluginFailure {
+    definition: PluginDefinition;
+    error: unknown;
+}
+export interface StorePluginResolution {
+    definitions: PluginDefinition[];
+    failures: StorePluginFailure[];
+}
+/**
+ * Replaces every store ref in `defs` with the concrete definition the store
+ * publishes for this JBrowse version, and passes everything else through
+ * untouched.
+ *
+ * A ref names the store's `name`, not the npm package — the store owns the
+ * former and can repoint it at a different package without breaking a config
+ * that named it years ago (jbrowse-plugin-list ADR 0008). `packageName` stays
+ * the key on the install side, where pinning is the point.
+ *
+ * `storePlugins` is `undefined` when the manifest could not be read at all.
+ * That is a different situation from a name the manifest does not list, but it
+ * gets the same answer, and the split that matters is elsewhere:
+ *
+ * - **No answer from the store** — unreachable, or the name is not listed
+ *   (retired, renamed, never published). A ref that also carries a url falls
+ *   back to it: that url is what a JBrowse without ref support loads from the
+ *   same config today, so falling back is exactly no worse than not having
+ *   tried. A ref with no url has nothing to fall back on and fails.
+ * - **An answer of "not for this JBrowse"** — the package is listed and no
+ *   published version's `jbrowseRange` covers the running version. This does
+ *   NOT fall back. The store has an opinion and the opinion is that the bundle
+ *   does not work here; loading the url anyway is the hole ADR 0007 describes,
+ *   where narrowing a range hid a broken plugin from careful clients and left
+ *   it armed for everyone else.
+ *
+ * The resolved definition keeps `storePlugin`. It is the only one of the three
+ * identity keys that survives resolution, so it is what lets `samePlugin` match
+ * a config's resolved entry against a session's still-unresolved ref for the
+ * same plugin. It ends up equal to the definition's `name`, because the store's
+ * `name` is what both are.
+ */
+export declare function resolveStoreRefs(defs: PluginDefinition[], storePlugins: JBrowsePlugin[] | undefined, jbrowseVersion: string): StorePluginResolution;
+/**
+ * `resolveStoreRefs` with the manifest fetched for it — the form a product
+ * calls, immediately before it drops vendored plugins and loads what is left.
+ *
+ * Fetches nothing when no definition is a ref, which is every config that
+ * predates them and every session a user assembled by hand. The store is on the
+ * boot path only for the configs that opted in.
+ */
+export declare function resolveStorePluginRefs(defs: PluginDefinition[], jbrowseVersion: string, fetchStore?: () => Promise<{
+    plugins: JBrowsePlugin[];
+}>): Promise<StorePluginResolution>;