@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/svg/exportViewSvg.js

@@ -0,0 +1,13 @@
+/**
+ * The body of every view's `exportSvg` action: load the view's lazy
+ * `renderToSvg`, render, save unless `save: false`, and return the markup.
+ */
+export async function exportViewSvg(view, opts, load) {
+    const { renderToSvg } = await load();
+    const html = await renderToSvg(view, opts);
+    if (opts.save !== false) {
+        const { saveSvgAsImage } = await import('./saveSvgAsImage.js');
+        await saveSvgAsImage(html, opts);
+    }
+    return html;
+}

package/esm/svg/normalizeSvgMarkup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The markup rules an SVG file has to meet that a React render into an HTML
+ * container does not: XML entities only (HTML serialization writes U+00A0 as
+ * ` `, which XML does not define, so one no-break space in a feature label
+ * made the whole file unparsable), SVG 1.1 colors, and rounded numbers.
+ */
+export declare function normalizeSvgMarkup(html: string): string;

package/esm/svg/normalizeSvgMarkup.js

@@ -0,0 +1,99 @@
+import { splitPaintAlpha } from '../util/svgColorProps.js';
+// Coordinates computed as bp/bpPerPx land in attributes as long floats
+// (`-32.4816`) or floating-point noise (`242.23839999999998`), bloating exports
+// with sub-pixel precision no renderer needs. Round numbers inside a fixed
+// whitelist of numeric attributes, so a track label or id that happens to look
+// numeric is never a candidate for rewriting. Geometry gets 2 decimals
+// (sub-pixel); opacity keeps 3 so a faint 0.01 mark can't collapse to 0.
+const COORD_ATTRS = [
+    'x',
+    'y',
+    'x1',
+    'y1',
+    'x2',
+    'y2',
+    'cx',
+    'cy',
+    'r',
+    'rx',
+    'ry',
+    'dx',
+    'dy',
+    'width',
+    'height',
+    'd',
+    'points',
+    'transform',
+    'gradientTransform',
+    'offset',
+    'viewBox',
+    'font-size',
+    'stroke-width',
+    'stroke-dashoffset',
+    'stroke-dasharray',
+];
+const OPACITY_ATTRS = [
+    'opacity',
+    'fill-opacity',
+    'stroke-opacity',
+    'stop-opacity',
+    'flood-opacity',
+];
+function makeRounder(attrs, digits) {
+    const re = new RegExp(`\\b(${attrs.join('|')})="([^"]*)"`, 'g');
+    return (svg) => svg.replaceAll(re, (_, name, value) => {
+        const rounded = value.replaceAll(/-?\d+\.\d{3,}(?:e-?\d+)?/gi, n => String(Number.parseFloat(Number(n).toFixed(digits))));
+        return `${name}="${rounded}"`;
+    });
+}
+const roundCoords = makeRounder(COORD_ATTRS, 2);
+const roundOpacity = makeRounder(OPACITY_ATTRS, 3);
+const OPACITY_OF = {
+    fill: 'fill-opacity',
+    stroke: 'stroke-opacity',
+    'stop-color': 'stop-opacity',
+    'flood-color': 'flood-opacity',
+};
+// a start tag, attribute by attribute, so a `>` inside a quoted value (which
+// HTML serialization leaves unescaped) cannot end it early
+const START_TAG = /<[a-zA-Z][^\s/>]*(?:\s+[^\s"'/=>]+="[^"]*")*\s*\/?>/g;
+const PAINT_ATTR = /\s(fill|stroke|stop-color|flood-color)="([^"]*)"/g;
+const MAY_NEED_SPLIT = /(?:fill|stroke|stop-color|flood-color)="(?:rgba|hsl|#[\da-f]{4}"|#[\da-f]{8}"|transparent)/i;
+// A JSX color reaches the file as React wrote it, and theme palette entries are
+// routinely `rgba()` (`divider`, `text.secondary`) — see `splitPaintAlpha` for
+// why that can't stay. Scoped to one start tag so an alpha folds into an
+// opacity attribute the element already carries instead of duplicating it,
+// which would not parse as XML.
+function splitTagPaintAlpha(tag) {
+    const alphas = [];
+    let out = tag.replaceAll(PAINT_ATTR, (whole, name, value) => {
+        const split = splitPaintAlpha(value);
+        if (!split) {
+            return whole;
+        }
+        if (split.opacity < 1) {
+            alphas.push([OPACITY_OF[name], split.opacity]);
+        }
+        return ` ${name}="${split.color}"`;
+    });
+    for (const [opacityName, alpha] of alphas) {
+        const existing = new RegExp(`\\s${opacityName}="([^"]*)"`);
+        out = existing.test(out)
+            ? out.replace(existing, (_, v) => ` ${opacityName}="${Number(v) * alpha}"`)
+            : out.replace(/\s*(\/?>)$/, ` ${opacityName}="${alpha}"$1`);
+    }
+    return out;
+}
+/**
+ * The markup rules an SVG file has to meet that a React render into an HTML
+ * container does not: XML entities only (HTML serialization writes U+00A0 as
+ * `&nbsp;`, which XML does not define, so one no-break space in a feature label
+ * made the whole file unparsable), SVG 1.1 colors, and rounded numbers.
+ */
+export function normalizeSvgMarkup(html) {
+    const xml = html.replaceAll('&nbsp;', '&#160;');
+    const split = MAY_NEED_SPLIT.test(xml)
+        ? xml.replaceAll(START_TAG, splitTagPaintAlpha)
+        : xml;
+    return roundOpacity(roundCoords(split));
+}

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/serializeSvg.d.ts

@@ -0,0 +1,7 @@
+import type React from 'react';
+export { normalizeSvgMarkup } from './normalizeSvgMarkup.ts';
+/**
+ * Serialize one standalone SVG document: its own clip-id numbering run (see
+ * `withFreshSvgClipIds`) and the file rules in `normalizeSvgMarkup`.
+ */
+export declare function serializeSvg(node: React.ReactElement): string;

package/esm/svg/serializeSvg.js

@@ -0,0 +1,11 @@
+import { withFreshSvgClipIds } from '../util/SvgCanvas.js';
+import { renderToStaticMarkup } from '../util/renderToStaticMarkup.js';
+import { normalizeSvgMarkup } from './normalizeSvgMarkup.js';
+export { normalizeSvgMarkup } from './normalizeSvgMarkup.js';
+/**
+ * Serialize one standalone SVG document: its own clip-id numbering run (see
+ * `withFreshSvgClipIds`) and the file rules in `normalizeSvgMarkup`.
+ */
+export function serializeSvg(node) {
+    return normalizeSvgMarkup(withFreshSvgClipIds(() => renderToStaticMarkup(node)));
+}

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 `SvgColorLegend` 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 `SvgColorLegend` 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,138 @@
+/**
+ * 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), a
+ * signature compare (global, 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 || …`. `svgReady` is a terminal state
+ * (data loaded, or error / too-large / canceled), so it resolves once the fetch
+ * it observes settles; the half-hour `timeoutMs` is only a backstop for a gate
+ * that cannot converge. 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]>;
+}>;