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

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/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

@@ -5,7 +5,7 @@
  * 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>`
+ * (`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.

package/esm/svg/svgId.js

@@ -34,7 +34,7 @@ const UNSAFE_ID_CHAR = /[^\w.:-]/g;
  * 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>`
+ * (`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.

package/esm/svg/svgReady.d.ts

@@ -37,9 +37,9 @@ export interface SvgReadyTerminals {
  * 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
+ * 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).
@@ -55,10 +55,11 @@ export declare function computeSvgReady({ error, regionTooLarge, extraTerminal,
  * 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.
+ * 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
@@ -94,6 +95,7 @@ export declare function awaitSvgReady(model: Pick<SvgExportable, 'svgReady' | 'e
 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

package/esm/svg/svgReady.js

@@ -17,9 +17,9 @@ const SVG_READY_TIMEOUT_MS = 1_800_000;
  * 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
+ * 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).
@@ -37,10 +37,11 @@ export function computeSvgReady({ error, regionTooLarge, extraTerminal, fetchCan
  * 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.
+ * 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

package/esm/svg/trackNames.d.ts

@@ -12,10 +12,12 @@ export declare function svgTrackName(track: {
     configuration: AnyConfigurationModel;
 }, session: TrackCatalog): string;
 /**
- * Tell the user which visible tracks the export left out because their display
- * type implements no `renderSvg`. Called once per export, after the renders —
- * the stacked views flatten every row's `skippedTracks` into one call rather
- * than notifying per row.
+ * Tell the user which visible tracks the export left out, by default because
+ * their display type implements no `renderSvg`. Called once per reason per
+ * export, after the renders — the stacked views flatten every row's
+ * `skippedTracks` into one call rather than notifying per row.
+ *
+ * A track shown in several rows is named once.
  *
  * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
  * informational rather than an error. But it is not silent: a figure that is
@@ -24,4 +26,4 @@ export declare function svgTrackName(track: {
  */
 export declare function notifySkippedSvgTracks(session: NotificationSink & TrackCatalog, skipped: {
     configuration: AnyConfigurationModel;
-}[]): void;
+}[], reason?: string): void;

package/esm/svg/trackNames.js

@@ -12,20 +12,23 @@ export function svgTrackName(track, session) {
     return coarseStripHTML(getTrackName(track.configuration, session));
 }
 /**
- * Tell the user which visible tracks the export left out because their display
- * type implements no `renderSvg`. Called once per export, after the renders —
- * the stacked views flatten every row's `skippedTracks` into one call rather
- * than notifying per row.
+ * Tell the user which visible tracks the export left out, by default because
+ * their display type implements no `renderSvg`. Called once per reason per
+ * export, after the renders — the stacked views flatten every row's
+ * `skippedTracks` into one call rather than notifying per row.
+ *
+ * A track shown in several rows is named once.
  *
  * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
  * informational rather than an error. But it is not silent: a figure that is
  * quietly short a track is worse than one whose author was told why, and the
  * reader of the file has no way to tell the difference afterwards.
  */
-export function notifySkippedSvgTracks(session, skipped) {
-    if (skipped.length === 0) {
-        return;
+export function notifySkippedSvgTracks(session, skipped, reason) {
+    const names = [...new Set(skipped.map(t => svgTrackName(t, session)))];
+    if (names.length > 0) {
+        const why = reason ??
+            `${names.length === 1 ? 'Its display type does' : 'Their display types do'} not support SVG export.`;
+        session.notify(`Not included in the SVG: ${names.join(', ')}. ${why}`, 'info');
     }
-    const names = skipped.map(t => svgTrackName(t, session)).join(', ');
-    session.notify(`Not included in the SVG: ${names}. ${skipped.length === 1 ? 'Its display type does' : 'Their display types do'} not support SVG export.`, 'info');
 }

package/esm/svg/wrapSvgExport.js

@@ -1,78 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ThemeProvider } from '@mui/material';
-import { StyleThemeProvider } from '../ui/PaletteContext.js';
-import { resolveStyleTheme } from '../ui/styleTheme.js';
-import { createJBrowseTheme } from '../ui/theme.js';
-import { resetSvgClipIds } from '../util/SvgCanvas.js';
-import { renderToStaticMarkup } from '../util/renderToStaticMarkup.js';
 import { SVGExportRoot } from './SvgExport.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);
-function roundSvgNumbers(svg) {
-    return roundOpacity(roundCoords(svg));
-}
-// The identical tail every view's `renderToSvg` ends in: resolve the export
-// theme into a provider, apply the caller-supplied Wrapper, wrap the content in
-// the root <svg>, and serialize to a markup string. Callers keep their own
-// layout math and children — only this boilerplate lives here.
+import { SvgThemeProviders } from './SvgThemeProviders.js';
+import { serializeSvg } from './serializeSvg.js';
+// The identical tail every view's `renderToSvg` ends in: the export theme's
+// providers, the caller-supplied Wrapper, the root <svg>, and serialization to
+// a file's markup. Callers keep their own layout math and children.
 export function wrapSvgExport({ theme, width, height, margin, fontFamily, Wrapper = ({ children }) => children, children, }) {
-    // One document, one clip-id numbering run. The counter SvgCanvas draws from is
-    // document-global because SVG ids are, so left alone it also spans documents
-    // and numbers each export from wherever the last one stopped — see
-    // resetSvgClipIds. This is the only place that can reset it: the render below
-    // is synchronous, so it is the one moment a whole document's ids are minted
-    // with no other export able to interleave.
-    resetSvgClipIds();
-    // Both providers, from the same options — the export renders outside every
-    // React tree the app mounted, so a `makeStyles` component here would
-    // otherwise style itself from the *default* style theme and quietly ignore
-    // the theme the user picked in the export dialog.
-    return roundSvgNumbers(renderToStaticMarkup(_jsx(ThemeProvider, { theme: createJBrowseTheme(theme), children: _jsx(StyleThemeProvider, { theme: resolveStyleTheme({ configTheme: theme }), children: _jsx(Wrapper, { children: _jsx(SVGExportRoot, { width: width, height: height, margin: margin, fontFamily: fontFamily, children: children }) }) }) })));
+    return serializeSvg(_jsx(SvgThemeProviders, { theme: theme, children: _jsx(Wrapper, { children: _jsx(SVGExportRoot, { width: width, height: height, margin: margin, fontFamily: fontFamily, children: children }) }) }));
 }

package/esm/ui/AddCustomPluginDialog.js

@@ -33,15 +33,12 @@ export default function AddCustomPluginDialog({ onClose, onAdd, }) {
     const [umdPluginName, setUMDPluginName] = useState('');
     const [umdPluginUrl, setUMDPluginUrl] = useState('');
     const [esmPluginUrl, setESMPluginUrl] = useState('');
-    const [cjsPluginUrl, setCJSPluginUrl] = useState('');
     const [advancedOptionsOpen, setAdvancedOptionsOpen] = useState(false);
-    const ready = Boolean((umdPluginName && umdPluginUrl) || esmPluginUrl || cjsPluginUrl);
+    const ready = Boolean((umdPluginName && umdPluginUrl) || esmPluginUrl);
     return (_jsx(SubmitDialog, { open: true, maxWidth: "sm", fullWidth: true, title: "Add custom plugin", submitDisabled: !ready, onCancel: onClose, onSubmit: () => {
             const definition = umdPluginName && umdPluginUrl
                 ? { name: umdPluginName, umdUrl: umdPluginUrl }
-                : esmPluginUrl
-                    ? { esmUrl: esmPluginUrl }
-                    : { cjsUrl: cjsPluginUrl };
+                : { esmUrl: esmPluginUrl };
             if (onAdd(definition)) {
                 onClose();
             }
@@ -53,9 +50,7 @@ export default function AddCustomPluginDialog({ onClose, onAdd, }) {
                         setAdvancedOptionsOpen(!advancedOptionsOpen);
                     }, children: [_jsx(IconButton, { className: cx(classes.expand, {
                                 [classes.expandOpen]: advancedOptionsOpen,
-                            }), "aria-expanded": advancedOptionsOpen, "aria-label": "show more", children: _jsx(ExpandMoreIcon, {}) }), "Advanced options"] }), _jsx(Collapse, { in: advancedOptionsOpen, children: _jsxs("div", { className: classes.dialogContent, children: [_jsx(DialogContentText, { children: "The above fields assume that the plugin is built in UMD format. If your plugin is in another format, or you have additional builds you want to add (such as a CJS build for using NodeJS APIs in desktop), you can enter the URLs for those builds below." }), _jsx(TextField, { label: "ESM build URL", variant: "outlined", fullWidth: true, margin: "dense", value: esmPluginUrl, onChange: event => {
+                            }), "aria-expanded": advancedOptionsOpen, "aria-label": "show more", children: _jsx(ExpandMoreIcon, {}) }), "Advanced options"] }), _jsx(Collapse, { in: advancedOptionsOpen, children: _jsxs("div", { className: classes.dialogContent, children: [_jsx(DialogContentText, { children: "The above fields assume that the plugin is built in UMD format. For an ESM build, enter its URL here instead; it carries its own name, so the fields above stay empty." }), _jsx(TextField, { label: "ESM build URL", variant: "outlined", fullWidth: true, margin: "dense", value: esmPluginUrl, onChange: event => {
                                     setESMPluginUrl(event.target.value);
-                                } }), _jsx(TextField, { label: "CJS build URL", variant: "outlined", fullWidth: true, margin: "dense", value: cjsPluginUrl, onChange: event => {
-                                    setCJSPluginUrl(event.target.value);
                                 } })] }) })] }) }));
 }

package/esm/ui/AppReadyMarker.d.ts

@@ -0,0 +1,45 @@
+import type { AbstractSessionModel } from '../util/types/index.ts';
+/**
+ * One element that says whether the whole app has finished, and what is open.
+ *
+ * `[data-app-phase="ready"]` is the entire readiness contract for anything
+ * driving JBrowse from outside — a screenshot tool, a test, an agent. Wait for
+ * that selector and you are done; there is no chain to assemble and no
+ * per-display census to take.
+ *
+ * Why it exists when `data-view-phase` and `data-display-phase` already do:
+ * those are per-element and NEGATIVE. Asking them "is everything finished"
+ * means asserting that no element carries the loading value, which is equally
+ * true of an app that has not started — and the gap is real, measured at about
+ * a second on a two-track session. A positive attribute cannot be satisfied
+ * early, because something has to render it.
+ *
+ * The census attributes beside it — `data-app-views`, `data-app-assemblies`,
+ * `data-app-tracks` (the latter two JSON arrays) — publish WHAT is open the
+ * same way the phase publishes whether it is done, so an outside reader asking
+ * "is the track I requested actually open" reads one element instead of
+ * walking `window.JBrowseSession` with its own copy of the view nesting. The
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
+ *
+ * Its own component, and `hidden`, for two reasons: an observer here subscribes
+ * to every view's phase without re-rendering the app shell around it, and a
+ * marker that is never drawn cannot be mistaken for UI or shift a layout. It is
+ * still found by `querySelector`, which is what reads it.
+ *
+ * **What it is silent about**: a display in a TERMINAL state. `error` and
+ * `canceled` are finished states, so this reads `ready` over a display whose
+ * fetch failed or that the user stopped — correctly, since nothing is still
+ * working, and a user's cancel is durable until Retry. A capture wants more than
+ * that: it wants a picture, and neither banner is one. The capture census after
+ * this is what draws that line: it names every `data-display-drawn="false"`,
+ * which the two comparative canvases publish from their stricter `settled` gate
+ * (see `comparativeReadiness` in `@jbrowse/synteny-core`, which holds both
+ * answers and says why an error separates them), and every
+ * `data-display-phase="canceled"`.
+ */
+declare const AppReadyMarker: ({ session, }: {
+    session: AbstractSessionModel;
+}) => import("react").JSX.Element;
+export default AppReadyMarker;

package/esm/ui/AppReadyMarker.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+import { openTracks, openViews } from '../util/openViews.js';
+function trackLoading(track) {
+    return track.displays.some(d => d.displayPhase === 'loading');
+}
+/**
+ * A view whose init failed (its assembly was never found) stays uninitialized
+ * for good and paints its error, so like a display's terminal phase it is
+ * finished, not pending: without this the whole app read `loading` for as long
+ * as that view was open, and every settle answered false with no reason.
+ *
+ * `pendingLaunch` is the third term and the one that was missing. `initialized`
+ * goes true mid-launch — LGV's flips the moment displayedRegions land, while
+ * the same apply pass still has the spec's tracks to attach — and `showLoading`
+ * goes false at the same moment, deliberately, so the reader sees the
+ * navigated view rather than a spinner while its tracks arrive. That left a
+ * window, exactly as wide as attaching the tracks, in which the marker said
+ * `ready` over a session missing everything it had been asked for.
+ * `whenViewSettled` states the same rule for the callers that await a single
+ * view, and says why in more detail. Not shared as one predicate: that one
+ * requires `initialized`, while absent here means not loading, and an adapter
+ * between the two null rules would read as agreement it does not have.
+ *
+ * `showImportForm` excuses the `initialized` term, and only that one. The
+ * comparative views spell `initialized` as "every row exists and is ready" —
+ * LinearSyntenyView's wants `views.length > 0`, dotplot's wants regions on both
+ * axes — so a view clicked into existence through `Add -> Linear synteny view`
+ * reads uninitialized for as long as its form is up, which is until a person
+ * fills it in. The app sat at `loading` behind every import-form figure. The
+ * other two terms keep their meaning: `showLoading` is the spinner the form
+ * yields to, and `showImportForm` is already false while a launch is pending.
+ */
+function viewLoading(view) {
+    const flags = view;
+    return (flags.error === undefined &&
+        (flags.showLoading === true ||
+            flags.pendingLaunch !== undefined ||
+            (flags.initialized === false && flags.showImportForm !== true)));
+}
+/**
+ * One element that says whether the whole app has finished, and what is open.
+ *
+ * `[data-app-phase="ready"]` is the entire readiness contract for anything
+ * driving JBrowse from outside — a screenshot tool, a test, an agent. Wait for
+ * that selector and you are done; there is no chain to assemble and no
+ * per-display census to take.
+ *
+ * Why it exists when `data-view-phase` and `data-display-phase` already do:
+ * those are per-element and NEGATIVE. Asking them "is everything finished"
+ * means asserting that no element carries the loading value, which is equally
+ * true of an app that has not started — and the gap is real, measured at about
+ * a second on a two-track session. A positive attribute cannot be satisfied
+ * early, because something has to render it.
+ *
+ * The census attributes beside it — `data-app-views`, `data-app-assemblies`,
+ * `data-app-tracks` (the latter two JSON arrays) — publish WHAT is open the
+ * same way the phase publishes whether it is done, so an outside reader asking
+ * "is the track I requested actually open" reads one element instead of
+ * walking `window.JBrowseSession` with its own copy of the view nesting. The
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
+ *
+ * Its own component, and `hidden`, for two reasons: an observer here subscribes
+ * to every view's phase without re-rendering the app shell around it, and a
+ * marker that is never drawn cannot be mistaken for UI or shift a layout. It is
+ * still found by `querySelector`, which is what reads it.
+ *
+ * **What it is silent about**: a display in a TERMINAL state. `error` and
+ * `canceled` are finished states, so this reads `ready` over a display whose
+ * fetch failed or that the user stopped — correctly, since nothing is still
+ * working, and a user's cancel is durable until Retry. A capture wants more than
+ * that: it wants a picture, and neither banner is one. The capture census after
+ * this is what draws that line: it names every `data-display-drawn="false"`,
+ * which the two comparative canvases publish from their stricter `settled` gate
+ * (see `comparativeReadiness` in `@jbrowse/synteny-core`, which holds both
+ * answers and says why an error separates them), and every
+ * `data-display-phase="canceled"`.
+ */
+const AppReadyMarker = observer(function AppReadyMarker({ session, }) {
+    const views = openViews(session);
+    const tracks = openTracks(session);
+    const loading = views.some(viewLoading) || tracks.some(trackLoading);
+    return (_jsx("span", { hidden: true, "data-testid": "app-ready-marker", "data-app-phase": loading ? 'loading' : 'ready', "data-app-views": session.views.length, "data-app-assemblies": JSON.stringify([
+            ...new Set(views.flatMap(v => v.assemblyNames ?? [])),
+        ]), "data-app-tracks": JSON.stringify(tracks.map(t => t.configuration.trackId ?? '(unnamed)')) }));
+});
+export default AppReadyMarker;

package/esm/ui/BaseExportSvgDialog.d.ts

@@ -9,7 +9,7 @@ export interface BaseExportSvgOptions {
 declare const _default: ({ model, handleClose, exportSvg, children, checkboxes, }: {
     model: IAnyStateTreeNode;
     handleClose: () => void;
-    exportSvg: (opts: BaseExportSvgOptions) => Promise<void>;
+    exportSvg: (opts: BaseExportSvgOptions) => Promise<unknown>;
     children?: React.ReactNode;
     checkboxes?: React.ReactNode;
 }) => import("react").JSX.Element;