@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/rpc/methods/CoreGetSequence.d.ts

@@ -1,13 +1,6 @@
 import RpcMethodType from '../../pluggableElementTypes/RpcMethodType.ts';
-import type { RenderArgs } from './util.ts';
-import type { Region } from '../../util/index.ts';
-export default class CoreGetSequence extends RpcMethodType {
-    name: string;
-    serializeArguments(args: RenderArgs, rpcDriver: string): Promise<RenderArgs>;
-    execute(args: {
-        sessionId: string;
-        region: Region;
-        adapterConfig: Record<string, unknown>;
-        stopToken?: string;
-    }, rpcDriver: string): Promise<string | undefined>;
+import type { RpcExecuteArgs } from '../RpcRegistry.ts';
+export default class CoreGetSequence extends RpcMethodType<'CoreGetSequence'> {
+    name: 'CoreGetSequence';
+    execute(args: RpcExecuteArgs<'CoreGetSequence'>): Promise<string | undefined>;
 }

package/esm/rpc/methods/CoreGetSequence.js

@@ -1,17 +1,16 @@
-import { getAdapter } from "../../data_adapters/dataAdapterCache.js";
-import RpcMethodType from "../../pluggableElementTypes/RpcMethodType.js";
-import { renameRegionsIfNeeded } from "../../util/index.js";
+import { isSequenceAdapter } from '../../data_adapters/BaseAdapter/index.js';
+import { getAdapter } from '../../data_adapters/dataAdapterCache.js';
+import RpcMethodType from '../../pluggableElementTypes/RpcMethodType.js';
+// CoreGetSequence takes a single region whose refName fetchSeq() has already
+// resolved to the sequence adapter's name, so no region renaming is needed here
 export default class CoreGetSequence extends RpcMethodType {
     name = 'CoreGetSequence';
-    async serializeArguments(args, rpcDriver) {
-        const { rootModel } = this.pluginManager;
-        const assemblyManager = rootModel.session.assemblyManager;
-        const renamedArgs = await renameRegionsIfNeeded(assemblyManager, args);
-        return super.serializeArguments(renamedArgs, rpcDriver);
-    }
-    async execute(args, rpcDriver) {
-        const { stopToken, sessionId, adapterConfig, region } = await this.deserializeArguments(args, rpcDriver);
-        const dataAdapter = (await getAdapter(this.pluginManager, sessionId, adapterConfig)).dataAdapter;
-        return dataAdapter.getSequence(region, { stopToken });
+    async execute(args) {
+        const { stopToken, statusCallback, sessionId, adapterConfig, region } = args;
+        const { dataAdapter } = await getAdapter(this.pluginManager, sessionId, adapterConfig);
+        if (!isSequenceAdapter(dataAdapter)) {
+            throw new Error('Adapter does not support retrieving sequences');
+        }
+        return dataAdapter.getSequence(region, { stopToken, statusCallback });
     }
 }

package/esm/rpc/serializeError/index.d.ts

@@ -0,0 +1,9 @@
+export interface ErrorObject {
+    name?: string;
+    message: string;
+    stack?: string;
+    cause?: unknown;
+    [key: string]: unknown;
+}
+export declare function serializeError(value: unknown): ErrorObject;
+export declare function deserializeError(value: unknown): Error;

package/esm/rpc/serializeError/index.js

@@ -0,0 +1,86 @@
+// Error's core fields (name/message/stack) are non-enumerable, so they're
+// copied explicitly; `cause` is non-enumerable too and recursed separately. Any
+// other own-enumerable props (AuthNeededError.url, a Node-style .code, etc.) are
+// copied generically so custom error data survives the worker boundary.
+const coreProperties = new Set(['name', 'message', 'stack', 'cause']);
+function stringify(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    // JSON.stringify returns undefined (not a string) for undefined, functions,
+    // and symbols, despite its type signature claiming otherwise
+    if (value === undefined ||
+        typeof value === 'function' ||
+        typeof value === 'symbol') {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isSerializedError(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.message === 'string');
+}
+function errorToObject(error, seen) {
+    const obj = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+    };
+    // copy custom own-enumerable data (url, code, ...); skip functions since they
+    // aren't structured-cloneable and postMessage would throw on them
+    for (const [key, value] of Object.entries(error)) {
+        if (!coreProperties.has(key) && typeof value !== 'function') {
+            obj[key] = value;
+        }
+    }
+    const { cause } = error;
+    if (cause !== undefined && !seen.has(cause)) {
+        seen.add(cause);
+        obj.cause = cause instanceof Error ? errorToObject(cause, seen) : cause;
+    }
+    return obj;
+}
+export function serializeError(value) {
+    if (value instanceof Error) {
+        return errorToObject(value, new Set([value]));
+    }
+    // a thrown non-Error value (string, object, ...) still travels as an Error so
+    // the other side can reject with something error-shaped
+    return { name: 'NonError', message: stringify(value) };
+}
+export function deserializeError(value) {
+    if (value instanceof Error) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return new Error(value);
+    }
+    if (isSerializedError(value)) {
+        // reconstructed as a plain Error carrying the original name (nothing in the
+        // app branches on `instanceof TypeError` etc. across the worker boundary)
+        const error = new Error(value.message);
+        error.name = value.name ?? 'Error';
+        if (value.stack) {
+            error.stack = value.stack;
+        }
+        for (const [key, val] of Object.entries(value)) {
+            if (!coreProperties.has(key)) {
+                error[key] = val;
+            }
+        }
+        if (value.cause !== undefined) {
+            error.cause = isSerializedError(value.cause)
+                ? deserializeError(value.cause)
+                : value.cause;
+        }
+        return error;
+    }
+    return new Error(stringify(value));
+}

package/esm/svg/SvgExport.d.ts

@@ -0,0 +1,30 @@
+export declare function SVGBackground({ width, height, }: {
+    width: number;
+    height: number;
+}): import("react").JSX.Element;
+export declare function SVGExportRoot({ width, height, margin, fontFamily, children, }: {
+    width: number;
+    height: number;
+    margin?: number;
+    fontFamily?: string;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+export declare function SVGMessageBox({ message, width, height, }: {
+    message: string;
+    width: number;
+    height: number;
+}): import("react").JSX.Element;
+export declare function SvgChrome({ regionTooLarge, width, height, children, }: {
+    regionTooLarge?: boolean;
+    width: number;
+    height: number;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+export declare function SvgClipRect({ id, x, y, width, height, children, }: {
+    id: string;
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+    children: React.ReactNode;
+}): import("react").JSX.Element;

package/esm/svg/SvgExport.js

@@ -0,0 +1,53 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Reusable SVG-export building blocks, usable by any plugin without pulling in
+// the linear-genome-view plugin. Non-component members live in sibling files
+// (`constants.ts`, `svgReady.ts`) so this stays component-only for
+// react-refresh.
+import { useTheme } from '@mui/material';
+import { stripAlpha } from '../util/index.js';
+import { exportMargin } from './constants.js';
+import { svgSafeId } from './svgId.js';
+// Full-bleed background rect. `width`/`height` are the *total* SVG dimensions.
+export function SVGBackground({ width, height, }) {
+    const theme = useTheme();
+    return (_jsx("rect", { width: width, height: height, fill: stripAlpha(theme.palette.background.default) }));
+}
+// Root <svg> for an image export. Owns the xmlns/viewBox boilerplate, widens
+// the canvas by `margin` on each side, and paints the themed background.
+// `width`/`height` are the content dimensions (the rendered canvas is
+// `width + margin * 2` wide); views translate their content by `margin` to sit
+// inside the gutter.
+export function SVGExportRoot({ width, height, margin = exportMargin, fontFamily, children, }) {
+    const totalWidth = width + margin * 2;
+    return (_jsxs("svg", { width: totalWidth, height: height, xmlns: "http://www.w3.org/2000/svg", xmlnsXlink: "http://www.w3.org/1999/xlink", viewBox: `0 0 ${totalWidth} ${height}`, fontFamily: fontFamily ? fontFamily : undefined, children: [_jsx(SVGBackground, { width: totalWidth, height: height }), children] }));
+}
+// Informational box for a soft terminal state (region too large). Keeps the
+// track's reserved height and labels a state that would otherwise export as a
+// silent blank.
+//
+// There is deliberately no error counterpart. A failed track fails the export
+// (`throwOnExportErrors`) rather than painting its error into the figure, so the
+// only terminal an export draws is one the user asked for by zooming out.
+export function SVGMessageBox({ message, width, height, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("rect", { x: 0, y: 0, width: width, height: height, fill: "#f2f2f2" }), _jsx("text", { x: 10, y: height / 2, fill: "#555555", fontSize: 14, children: message })] }));
+}
+// SVG-export counterpart of DisplayChrome (BaseLinearDisplay/components): the
+// terminal-state gate every display's `renderSvg` ends in. It renders the
+// terminal state itself — a "region too large" message — and only paints the
+// children when the display has renderable data. The body is an ordinary child
+// component, so it never runs in a terminal state and no `renderSvg` re-detects
+// one from empty/absent data. The readiness wait stays an explicit
+// `await awaitSvgReady(model)` in each `renderSvg` (the one genuinely async
+// step), so this component is sync.
+//
+// One terminal, not two, and the asymmetry is the point: over-budget is a state
+// the user navigated to on purpose, and a figure saying so is the honest export
+// of it. A fetch that failed is not — it is the export being unable to answer,
+// which `throwOnExportErrors` reports by failing rather than by drawing.
+export function SvgChrome({ regionTooLarge, width, height, children, }) {
+    return regionTooLarge ? (_jsx(SVGMessageBox, { message: "Region too large to render", width: width, height: height })) : (_jsx(_Fragment, { children: children }));
+}
+export function SvgClipRect({ id, x = 0, y = 0, width, height, children, }) {
+    const safeId = svgSafeId(id);
+    return (_jsxs(_Fragment, { children: [_jsx("defs", { children: _jsx("clipPath", { id: safeId, children: _jsx("rect", { x: x, y: y, width: width, height: height }) }) }), _jsx("g", { clipPath: `url(#${safeId})`, children: children })] }));
+}

package/esm/svg/constants.d.ts

@@ -0,0 +1 @@
+export declare const exportMargin = 50;

package/esm/svg/constants.js

@@ -0,0 +1,5 @@
+// Fixed horizontal gutter (CSS px) added to the left and right of every image
+// export, giving ruler ticks and track-label backgrounds room to bleed past
+// the genome content area. Lives apart from `SvgExport.tsx` so that file stays
+// component-only for react-refresh.
+export const exportMargin = 50;

package/esm/svg/saveSvgAsImage.d.ts

@@ -0,0 +1,6 @@
+export interface SaveSvgAsImageOptions {
+    format?: string;
+    filename?: string;
+}
+export declare function svgHtmlToPngBlob(html: string, scale?: number): Promise<Blob>;
+export declare function saveSvgAsImage(html: string, opts?: SaveSvgAsImageOptions): Promise<void>;

package/esm/svg/saveSvgAsImage.js

@@ -0,0 +1,90 @@
+import { saveAs } from '../util/FileSaver/index.js';
+// Supersample factor for PNG rasterization. The vector text/gridlines/rulers
+// rasterize crisply at this scale, and the heavy track layers are already
+// embedded as 2× rasters (see createSvgRasterCanvas), so a 1× output canvas
+// would otherwise *downsample* them back to screen resolution. Kept at 2× to
+// match that embedded DPR: a higher factor sharpens vector text further but
+// upscales the 2× rasters (blur), and inflates the canvas toward browser size
+// limits.
+const PNG_SCALE = 2;
+// Bump the root <svg> width/height by `scale` while leaving viewBox alone, so
+// the browser re-rasterizes the *vector* content natively at the higher
+// resolution. Drawing the unscaled <img> with drawImage(...,w*scale,h*scale)
+// instead would only stretch the 1×-rasterized bitmap (blurry text, resample
+// artifacts on the embedded rasters).
+function scaleSvgMarkup(html, scale) {
+    return html.replace(/<svg\b[^>]*>/, tag => tag
+        .replace(/(\bwidth=")([\d.]+)(")/, (_m, p, n, s) => `${p}${+n * scale}${s}`)
+        .replace(/(\bheight=")([\d.]+)(")/, (_m, p, n, s) => `${p}${+n * scale}${s}`));
+}
+// Rasterizes an SVG string to a PNG Blob by routing through a hidden <img>
+// + Canvas2D. Rejects with the actual underlying cause so bug reports
+// distinguish "SVG failed to load" (usually malformed markup) from
+// "canvas.toBlob returned null" (rasterized image exceeded browser limits).
+export function svgHtmlToPngBlob(html, scale = PNG_SCALE) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        const svgBlob = new Blob([scaleSvgMarkup(html, scale)], {
+            type: 'image/svg+xml',
+        });
+        const url = URL.createObjectURL(svgBlob);
+        img.onload = () => {
+            // Everything here runs in an event handler, so a throw would escape the
+            // promise instead of rejecting it and leave the export dialog spinning
+            // forever with nothing said — the hang `awaitViewInitialized` cures on
+            // the other end of this pipeline. Reject explicitly instead.
+            try {
+                const canvas = document.createElement('canvas');
+                const w = img.width;
+                const h = img.height;
+                // stated once: both the context and the blob give out at this size,
+                // and both failures are silent (a null, not a throw)
+                const tooLarge = `The image may be too large (${w}x${h}). Try reducing the view size or use SVG format.`;
+                canvas.width = w;
+                canvas.height = h;
+                const ctx = canvas.getContext('2d');
+                if (!ctx) {
+                    // browsers hand back a null 2d context rather than throwing once the
+                    // canvas exceeds their area limit, which PNG_SCALE makes 4x easier to
+                    // hit than the on-screen canvases
+                    throw new Error(`Failed to create PNG rendering context. ${tooLarge}`);
+                }
+                ctx.imageSmoothingEnabled = true;
+                ctx.imageSmoothingQuality = 'high';
+                ctx.drawImage(img, 0, 0);
+                canvas.toBlob(blob => {
+                    if (blob) {
+                        resolve(blob);
+                    }
+                    else {
+                        reject(new Error(`Failed to create PNG. ${tooLarge}`));
+                    }
+                }, 'image/png');
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(`${e}`));
+            }
+            finally {
+                URL.revokeObjectURL(url);
+            }
+        };
+        img.onerror = event => {
+            URL.revokeObjectURL(url);
+            const detail = typeof event === 'string' ? event : 'image load failed';
+            reject(new Error(`Failed to load SVG for PNG conversion: ${detail}`));
+        };
+        img.src = url;
+    });
+}
+// Shared "save the rendered SVG" sink used by every view's `exportSvg`
+// action. `format: 'png'` rasterizes through svgHtmlToPngBlob; anything else
+// (default) saves the raw SVG markup.
+export async function saveSvgAsImage(html, opts = {}) {
+    if (opts.format === 'png') {
+        const blob = await svgHtmlToPngBlob(html);
+        saveAs(blob, opts.filename ?? 'image.png');
+    }
+    else {
+        saveAs(new Blob([html], { type: 'image/svg+xml' }), opts.filename ?? 'image.svg');
+    }
+}

package/esm/svg/svgId.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Make an SVG id safe to both carry in an `id` attribute and point at with
+ * `url(#...)`.
+ *
+ * Injective but NOT idempotent — escaping the marker is what buys injectivity,
+ * so a second pass re-escapes the `~`s the first one wrote. Apply it exactly
+ * once, at the place that emits both the id and the reference to it
+ * (`SvgClipRect` and `SvgGradientLegend` already do; a hand-rolled `<clipPath>`
+ * must). Double-applying is harmless to correctness — the id and its `url()`
+ * still agree, since both are derived from one call — but it produces noisy ids
+ * for no reason.
+ */
+export declare function svgSafeId(id: string): string;
+/**
+ * The id to build a view's or display's SVG ids out of. It has to be two things
+ * at once, and each rules out the obvious answer to the other.
+ *
+ * **Unique within the document.** The configured `displayId` is not: a synteny
+ * or breakpoint split view exports several LGVs into one file, and a track
+ * shown in more than one of them instantiates a display from the *same* config
+ * in each, so both emitted the identical
+ * `alignments-clip-volvox_inv_indels-LGVSyntenyDisplay`. A duplicate id is
+ * silent — `url(#id)` resolves to the first match, so the second display simply
+ * renders unclipped and paints over its neighbours. `assertNoDuplicateSvgIds`
+ * in the web tests catches it.
+ *
+ * **Stable across session loads.** `model.id` is not: it is a `nanoid(10)`
+ * minted when the MST node is created, so two exports of the same unchanged
+ * view differ in every clip-path id. That is why the checked-in export
+ * snapshots churned on `wiggle-clip-5GfQp_z8Ji` → `-FePoZy7IhS` without a
+ * pixel moving, and why diffing two saved SVGs shows changes that aren't real.
+ *
+ * The state tree path is both. It is unique by construction — two nodes cannot
+ * occupy one path — and it is a function of where the node sits in the session
+ * rather than of when it was created, so the same session exports to the same
+ * bytes. Only the numeric indices are kept (`/views/0/tracks/2/displays/0` →
+ * `0-2-0`), since the property names in between are fixed by the schema and
+ * just make the id long.
+ */
+export declare function svgNodeId(model: {
+    id: string;
+}): string;

package/esm/svg/svgId.js

@@ -0,0 +1,84 @@
+import { getPath, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * SVG ids in an export are routinely built out of config data — a `trackId`, a
+ * `displayId`, a block key carrying a refName. All three are arbitrary strings
+ * from a config file or a FASTA header, and an id is not just an attribute: it
+ * is pointed at by `clip-path="url(#id)"` / `fill="url(#id)"`, which is a CSS
+ * `url()` token. An unquoted `url()` cannot hold whitespace, parentheses or
+ * quotes, so a track named `Genes (curated)` or a refName like
+ * `gi|123|ref|NC_000001|` silently produced an unresolvable reference: the clip
+ * never applied and the track painted over its neighbours, or the gradient fill
+ * came out transparent.
+ *
+ * Percent-encoding is the wrong tool here even though the characters line up —
+ * a fragment reference is percent-*decoded* before it is matched against an id,
+ * so `url(#a%20b)` looks for the id `a b`, not `a%20b`, and encoding both ends
+ * just moves the mismatch.
+ *
+ * So: escape to a safe alphabet instead. `~` is the marker because it is legal
+ * in both an id and a `url()`, and essentially never appears in a real trackId
+ * — which means ordinary ids pass through byte-for-byte and no existing export
+ * changes.
+ */
+// Everything outside this set is escaped. `\w` is [A-Za-z0-9_]; `.`, `-` and
+// `:` are added because existing ids (block keys are `refName:start:end:idx`)
+// are full of them and all three are safe in an id and in a `url()`. `~` is
+// deliberately NOT in the set, so it escapes itself and the mapping stays
+// injective — two ids that differ only in an unsafe character must not collide
+// into one, or the second element silently steals the first's clip.
+const UNSAFE_ID_CHAR = /[^\w.:-]/g;
+/**
+ * Make an SVG id safe to both carry in an `id` attribute and point at with
+ * `url(#...)`.
+ *
+ * Injective but NOT idempotent — escaping the marker is what buys injectivity,
+ * so a second pass re-escapes the `~`s the first one wrote. Apply it exactly
+ * once, at the place that emits both the id and the reference to it
+ * (`SvgClipRect` and `SvgGradientLegend` already do; a hand-rolled `<clipPath>`
+ * must). Double-applying is harmless to correctness — the id and its `url()`
+ * still agree, since both are derived from one call — but it produces noisy ids
+ * for no reason.
+ */
+export function svgSafeId(id) {
+    return id.replaceAll(UNSAFE_ID_CHAR, c => `~${c.codePointAt(0).toString(16)}~`);
+}
+/**
+ * The id to build a view's or display's SVG ids out of. It has to be two things
+ * at once, and each rules out the obvious answer to the other.
+ *
+ * **Unique within the document.** The configured `displayId` is not: a synteny
+ * or breakpoint split view exports several LGVs into one file, and a track
+ * shown in more than one of them instantiates a display from the *same* config
+ * in each, so both emitted the identical
+ * `alignments-clip-volvox_inv_indels-LGVSyntenyDisplay`. A duplicate id is
+ * silent — `url(#id)` resolves to the first match, so the second display simply
+ * renders unclipped and paints over its neighbours. `assertNoDuplicateSvgIds`
+ * in the web tests catches it.
+ *
+ * **Stable across session loads.** `model.id` is not: it is a `nanoid(10)`
+ * minted when the MST node is created, so two exports of the same unchanged
+ * view differ in every clip-path id. That is why the checked-in export
+ * snapshots churned on `wiggle-clip-5GfQp_z8Ji` → `-FePoZy7IhS` without a
+ * pixel moving, and why diffing two saved SVGs shows changes that aren't real.
+ *
+ * The state tree path is both. It is unique by construction — two nodes cannot
+ * occupy one path — and it is a function of where the node sits in the session
+ * rather than of when it was created, so the same session exports to the same
+ * bytes. Only the numeric indices are kept (`/views/0/tracks/2/displays/0` →
+ * `0-2-0`), since the property names in between are fixed by the schema and
+ * just make the id long.
+ */
+export function svgNodeId(model) {
+    // getPath throws on anything that is not a live MST node, and unit tests
+    // render these components against plain object stand-ins. Their own id is
+    // unique, which is the half that matters when there is no tree to place them
+    // in — a detached node is not in a document with anything to collide with.
+    // Narrowed through a widened alias so that the guard doesn't also narrow
+    // `model` itself, whose `id` the fallback still needs.
+    const node = model;
+    if (!isStateTreeNode(node)) {
+        return model.id;
+    }
+    const indices = getPath(node).match(/\d+/g);
+    return indices ? indices.join('-') : model.id;
+}

package/esm/svg/svgReady.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The contract every GPU display's `renderSvg` relies on: a `svgReady` gate
+ * (the per-display terminal-state getter — see MultiRegionDisplayMixin /
+ * GlobalFetchMixin) and the `error` it fails the export on.
+ * Duck-typed `renderSvg` model interfaces extend this so the compiler catches a
+ * missing field instead of it surfacing as a runtime hang or a silent blank.
+ */
+export interface SvgExportable {
+    svgReady: boolean;
+    error: unknown;
+    regionTooLarge: boolean;
+    fetchCanceled?: boolean;
+}
+/**
+ * The terminal states that let an export proceed with no current data. Mirrors
+ * `DisplayPhaseInputs`: named fields, all required, so adding a state is a
+ * compile error at every call site rather than a silently missing branch.
+ *
+ * `extraTerminal` is the display-specific escape hatch — sequence sets it when
+ * zoomed past base resolution, where it renders a static "zoom in" message and
+ * fetches nothing, so a data-only gate would never resolve.
+ *
+ * `fetchCanceled` is the user's own resting state: a standing cancel holds the
+ * fetch gate shut until Retry or a viewport change, and an export causes
+ * neither, so without this terminal `awaitSvgReady` waits out its whole bound
+ * with the dialog up and nothing said, then fails. A display family with no
+ * cancel affordance answers it `false`.
+ */
+export interface SvgReadyTerminals {
+    error: unknown;
+    regionTooLarge: boolean;
+    extraTerminal: boolean;
+    fetchCanceled: boolean;
+}
+/**
+ * Whether an off-screen (SVG) export can read this display's data now: the held
+ * data is current for what is on screen, or the fetch reached a terminal state.
+ *
+ * Single-sourced for the same reason as `computeDisplayPhase`: every display
+ * family expresses freshness differently — spatial coverage (per-region),
+ * viewport-snapshot compare (global), signature compare (arc / dotplot /
+ * synteny) — but the *policy* wrapping it is identical, and each of the five
+ * hand-written copies this replaced was one place to forget a terminal and hang
+ * the export, or to forget freshness and capture a stale viewport (both have
+ * shipped; see agent-docs/reference/SVG_EXPORT.md).
+ *
+ * `dataCurrent` is a **thunk**, evaluated only after the terminals are ruled
+ * out, for the same MobX reason `computeDisplayPhase`'s `loading` is: freshness
+ * typically reads the containing view's `visibleRegions` / `loadedRegions`, and
+ * the `when()` in `awaitSvgReady` shouldn't subscribe to that churn while a
+ * banner is up.
+ */
+export declare function computeSvgReady({ error, regionTooLarge, extraTerminal, fetchCanceled }: SvgReadyTerminals, dataCurrent: () => boolean): boolean;
+/**
+ * Off-screen renderers (SVG export, headless jbrowse-img) must wait until the
+ * display reaches a terminal state before reading its data. That whole policy
+ * lives in `svgReady`; this is the one shared way to await it, so renderers
+ * never re-inline `data != null || error || …`. No time bound: `svgReady` is a
+ * terminal state (data loaded, or error / too-large), so it resolves once the
+ * fetch it observes settles. If a throwing `svgReady` getter rejects the wait,
+ * that error propagates faithfully rather than being masked.
+ *
+ * It then fails the export if the terminal it settled on was the error
+ * (`throwOnExportErrors`, below, for why that is fatal), making this the exact
+ * display-level twin of `awaitViewInitialized`: both wait for `settled || error`
+ * and both refuse to continue on the error, so the postcondition of each is
+ * "there is something to draw". Folded in rather than left to the caller because
+ * `svgReady` is *true* on error, so a caller that awaits and stops there gets a
+ * display with nothing to draw and no sign of why.
+ *
+ * Every display uses this one, including the ones with nowhere to draw an error
+ * (dotplot, synteny) — a display never has to know whether it owns the surface
+ * it paints, because the thing that made that distinction matter, reporting all
+ * the failures rather than one, is `awaitSvgRenders`'s job.
+ *
+ * A standing user cancel fails the export the same way an error does, and for
+ * the same reason the error is folded in rather than left to the caller: the
+ * cancel terminal makes `svgReady` *true* over a display with nothing to draw,
+ * so a caller that awaits and stops there exports that track blank in silence.
+ * On screen the same state shows "Loading canceled / Retry", so the loud
+ * failure matches what the user is looking at.
+ */
+export declare function awaitSvgReady(model: Pick<SvgExportable, 'svgReady' | 'error' | 'fetchCanceled'>, timeoutMs?: number): Promise<void>;
+/**
+ * The view-level counterpart, for the wait every `renderToSvg` opens with:
+ * `whenViewSettled` in the export's own vocabulary. Why the bare
+ * `when(() => view.initialized)` it replaced could not fail — only hang — is
+ * documented there.
+ *
+ * Only a view that never initialized is fatal *here*. A track error on an
+ * initialized view is fatal too, but it is the displays' readiness waits that
+ * report it (`throwOnExportErrors`), after this one has let the export start.
+ */
+export declare function awaitViewInitialized(view: {
+    initialized: boolean;
+    error: unknown;
+    pendingLaunch?: unknown;
+}): Promise<void>;
+/**
+ * How the export answers "a track failed": by failing. A track whose data won't
+ * load has its error caught by the fetch layer and stored on the display, so the
+ * render itself still returns — with that track blank.
+ *
+ * An export is a standalone artifact, so a failed track is fatal: the dialog
+ * shows its error banner and saves nothing, and a headless caller (jbrowse-img)
+ * exits nonzero instead of writing a broken image. Drawing the error into the
+ * figure instead costs more than the red rect it leaves in the picture: on a
+ * shared surface (dotplot plot rect, synteny band) the box covers the tracks
+ * that *did* render, and a snapshot regenerated while a display is broken
+ * absorbs the stack trace as expected output — which is how a real crash sat
+ * inside two committed goldens without turning anything red.
+ *
+ * `regionTooLarge` is deliberately not routed here — see `SvgChrome`.
+ *
+ * The failures are kept on the thrown error so that nesting one `awaitSvgRenders`
+ * inside another (synteny: rows of tracks *and* levels of ribbons) still reports
+ * every leaf rather than one per group.
+ */
+export declare function throwOnExportErrors(errors: unknown[]): void;
+/**
+ * `Promise.all` for the renders a view fans out, differing in the one way an
+ * export needs: it fails with **every** failure instead of whichever rejected
+ * first. Exporting a session with three broken tracks should not mean finding
+ * the second one by fixing the first and exporting again. Nest it freely — an
+ * inner fan-out's failures are flattened into the outer one's report.
+ *
+ * That is also what lets every display await through the plain `awaitSvgReady`.
+ * A display on a shared surface (the dotplot's plot rect, a synteny level's
+ * band) has nowhere to draw an error and nothing complete to say alone; the
+ * alternative is for it to stay silent and let its view read the combined error
+ * back *after* the waits, which nothing enforces and every new shared-surface
+ * view has to rediscover. Here the display just throws, and being complete is
+ * the fan-out's job rather than the display's.
+ */
+export declare function awaitSvgRenders<T extends readonly unknown[] | []>(renders: T): Promise<{
+    -readonly [K in keyof T]: Awaited<T[K]>;
+}>;