@jbrowse/plugin-linear-genome-view 4.3.0 → 5.0.0-beta.2

package/esm/LinearGenomeView/svgcomponents/SVGRuler.js

@@ -1,41 +1,69 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { getTickDisplayStr, measureText, stripAlpha } from '@jbrowse/core/util';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SvgClipRect } from '@jbrowse/core/svg/SvgExport';
+import { svgNodeId } from '@jbrowse/core/svg/svgId';
+import { stripAlpha } from '@jbrowse/core/util';
 import { useTheme } from '@mui/material';
-import { makeTicks } from "../util.js";
-import SVGRegionSeparators from "./SVGRegionSeparators.js";
-function Ruler({ start, end, bpPerPx, reversed = false, major = true, minor = true, hideText = false, widthPx, }) {
-    const ticks = makeTicks(start, end, bpPerPx, major, minor);
+import { REF_NAME_LABEL_FONT_SIZE, getScalebarRefNameLabels, labelFitsInBlock, refNameLabelFitsInView, tickLabelWidth, } from '../util.js';
+import SVGRegionSeparators from './SVGRegionSeparators.js';
+import { RULER_MAJOR_TICK, RULER_MINOR_TICK, RULER_TICK_FONT_SIZE, getRulerLayout, gridlineTickXs, refNameLabelBaselineY, refNameLabelBoxHeight, vlinePath, } from './util.js';
+// Tick marks and their coordinate labels, read from the same model getters the
+// on-screen Gridlines/ScalebarCoordinateLabels use (gridlineTicks /
+// scalebarLabels), so tick pitch, label text and label placement can't drift
+// from the screen. Both are computed in the staticBlocks frame, which overhangs
+// the viewport, so shift by the view's `staticBlocksTranslateX` and let the
+// caller's clip trim the overhang.
+function Ruler({ model, tickTopY, numbersBaselineY, }) {
     const theme = useTheme();
-    const c = stripAlpha(theme.palette.text.secondary);
-    return (_jsxs(_Fragment, { children: [ticks.map(tick => {
-                const x = (reversed ? end - tick.base : tick.base - start) / bpPerPx;
-                return (_jsx("line", { x1: x, x2: x, y1: 0, y2: tick.type === 'major' ? 6 : 4, strokeWidth: 1, stroke: c }, `tick-${tick.base}`));
-            }), !hideText
-                ? ticks
-                    .filter(tick => tick.type === 'major')
-                    .filter(tick => {
-                    const x = (reversed ? end - tick.base : tick.base - start) / bpPerPx;
-                    const labelText = getTickDisplayStr(tick.base + 1, bpPerPx);
-                    const labelWidth = measureText(labelText, 11) + 4;
-                    const leftEdge = x - 3;
-                    const rightEdge = leftEdge + labelWidth;
-                    return leftEdge >= 0 && rightEdge <= widthPx;
-                })
-                    .map(tick => {
-                    const x = (reversed ? end - tick.base : tick.base - start) / bpPerPx;
-                    return (_jsx("text", { x: x - 3, y: 7 + 11, fontSize: 11, fill: c, children: getTickDisplayStr(tick.base + 1, bpPerPx) }, `label-${tick.base}`));
-                })
-                : null] }));
+    const color = stripAlpha(theme.palette.text.secondary);
+    const { scalebarLabels, width } = model;
+    const { dx, major, minor } = gridlineTickXs(model);
+    // major and minor marks share a stroke and differ only in length, so both
+    // collapse into a single path
+    const ticks = vlinePath(major, tickTopY, tickTopY + RULER_MAJOR_TICK) +
+        vlinePath(minor, tickTopY, tickTopY + RULER_MINOR_TICK);
+    return (_jsxs(_Fragment, { children: [_jsx("path", { d: ticks, strokeWidth: 1, stroke: color, fill: "none" }), scalebarLabels
+                .filter(({ x, label }) => {
+                const w = tickLabelWidth(label);
+                return labelFitsInBlock(dx + x - w / 2, w, width);
+            })
+                .map(({ x, label, key }) => (_jsx("text", { x: dx + x, y: numbersBaselineY, textAnchor: "middle", fontSize: RULER_TICK_FONT_SIZE, fill: color, children: label }, key)))] }));
 }
-export default function SVGRuler({ model, fontSize, }) {
-    const { dynamicBlocks: { contentBlocks }, offsetPx: viewOffsetPx, bpPerPx, } = model;
-    const renderRuler = contentBlocks.length < 5;
+// Chromosome/refName labels along the ruler. Reuses the on-screen scalebar's
+// sticky-label logic (getScalebarRefNameLabels) so the exported name stays
+// pinned to the viewport's left edge when a region has scrolled off — otherwise
+// the name renders off-canvas whenever you export a view zoomed into a
+// chromosome interior. No assembly-name prefix here (unlike the on-screen
+// scalebar): the SVG export already draws a standalone assembly-name label
+// above the ruler, so folding it into this one too is redundant.
+//
+// `orientation` is not redundant, and this is the surface that needed it most.
+// A stacked export gives each row SVGRowHeader — assembly name, ruler, refName
+// labels — and no locstring, so a flipped row used to leave the numbers
+// counting down as the only evidence it was flipped. On screen the search box
+// says so; a figure has no search box.
+function SVGRefNameLabels({ model }) {
     const theme = useTheme();
-    const c = stripAlpha(theme.palette.text.primary);
-    return (_jsxs(_Fragment, { children: [_jsx(SVGRegionSeparators, { model: model, height: 30 }), contentBlocks.map(block => {
-                const { start, end, key, reversed, offsetPx, refName, widthPx } = block;
-                const offset = offsetPx - viewOffsetPx;
-                const clipid = `clip-${key}`;
-                return (_jsxs("g", { children: [_jsx("defs", { children: _jsx("clipPath", { id: clipid, children: _jsx("rect", { x: 0, y: 0, width: widthPx, height: 100 }) }) }), _jsx("g", { transform: `translate(${offset} 0)`, children: _jsxs("g", { clipPath: `url(#${clipid})`, children: [_jsx("text", { x: 4, y: fontSize, fontSize: fontSize, fill: c, children: refName }), _jsx("g", { transform: "translate(0 20)", children: _jsx(Ruler, { hideText: !renderRuler, start: start, end: end, bpPerPx: bpPerPx, reversed: reversed, widthPx: widthPx }) })] }) })] }, key));
-            })] }));
+    const fill = stripAlpha(theme.palette.text.primary);
+    const { labels, caption } = getScalebarRefNameLabels({
+        blocks: model.staticBlocks.blocks,
+        offsetPx: model.offsetPx,
+        prefix: undefined,
+        orientation: model.displayedRegionsOrientation,
+    });
+    return (_jsxs(_Fragment, { children: [caption === undefined ? null : (_jsx("text", { x: 0, y: refNameLabelBaselineY, fontSize: REF_NAME_LABEL_FONT_SIZE, fontWeight: "bold", fill: fill, children: caption })), labels
+                .filter(label => refNameLabelFitsInView(label, model.width))
+                .map(label => (_jsx(SVGRefNameLabel, { label: label, fill: fill, clipId: `reflabel-${svgNodeId(model)}-${label.key}` }, label.key)))] }));
+}
+// One refName label, clipped to the pixels left before its run of regions ends
+// so a long name can't run past what it names — the vector counterpart of the
+// on-screen label's maxWidth + overflow:clip. The clip rect spans the whole
+// label box from its left edge, paddingLeft included, which is the box-sizing
+// the on-screen span states for the same reason.
+function SVGRefNameLabel({ label, fill, clipId, }) {
+    const { transform, maxWidth, paddingLeft, text } = label;
+    return (_jsx("g", { transform: `translate(${transform} 0)`, children: _jsx(SvgClipRect, { id: clipId, width: maxWidth, height: refNameLabelBoxHeight, children: _jsx("text", { x: paddingLeft, y: refNameLabelBaselineY, fontSize: REF_NAME_LABEL_FONT_SIZE, fontWeight: "bold", fill: fill, children: text }) }) }));
+}
+export default function SVGRuler({ model, rulerHeight, }) {
+    const { tickTopY, numbersBaselineY } = getRulerLayout(rulerHeight);
+    return (_jsxs(SvgClipRect, { id: `ruler-clip-${svgNodeId(model)}`, width: model.width, height: rulerHeight, children: [_jsx(SVGRegionSeparators, { model: model, height: rulerHeight }), _jsx(Ruler, { model: model, tickTopY: tickTopY, numbersBaselineY: numbersBaselineY }), _jsx(SVGRefNameLabels, { model: model })] }));
 }

package/esm/LinearGenomeView/svgcomponents/SVGScalebar.d.ts

@@ -3,5 +3,5 @@ type LGV = LinearGenomeViewModel;
 export default function SVGScalebar({ model, fontSize, }: {
     model: LGV;
     fontSize: number;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 export {};

package/esm/LinearGenomeView/svgcomponents/SVGScalebar.js

@@ -1,14 +1,16 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { getBpDisplayStr, stripAlpha } from '@jbrowse/core/util';
 import { useTheme } from '@mui/material';
+import { SVG_SCALEBAR_CAP } from '../consts.js';
+import { labelBaselineFromTop } from './util.js';
 export default function SVGScalebar({ model, fontSize, }) {
     const { offsetPx, dynamicBlocks: { totalWidthPxWithoutBorders: totalWidthPx, totalBp }, } = model;
     const theme = useTheme();
     const displayBp = getBpDisplayStr(totalBp);
     const x0 = Math.max(-offsetPx, 0);
     const x1 = x0 + totalWidthPx;
-    const c = stripAlpha(theme.palette.text.secondary);
-    const x = x0 + (x1 - x0) / 2;
-    const y = fontSize;
-    return (_jsxs(_Fragment, { children: [_jsx("line", { x1: x0, x2: x1, y1: 10, y2: 10, stroke: c }), _jsx("line", { x1: x0, x2: x0, y1: 5, y2: 15, stroke: c }), _jsx("line", { x1: x1, x2: x1, y1: 5, y2: 15, stroke: c }), _jsx("text", { x: x, y: y, textAnchor: "middle", dominantBaseline: "hanging", fontSize: fontSize, fill: c, children: displayBp })] }));
+    const color = stripAlpha(theme.palette.text.secondary);
+    // the bar is drawn on this component's own origin (y=0), with capped ends and
+    // the bp label hanging just below; callers translate it to the desired line y
+    return (_jsxs(_Fragment, { children: [_jsx("line", { x1: x0, x2: x1, y1: 0, y2: 0, stroke: color }), _jsx("line", { x1: x0, x2: x0, y1: -SVG_SCALEBAR_CAP, y2: SVG_SCALEBAR_CAP, stroke: color }), _jsx("line", { x1: x1, x2: x1, y1: -SVG_SCALEBAR_CAP, y2: SVG_SCALEBAR_CAP, stroke: color }), _jsx("text", { x: (x0 + x1) / 2, y: labelBaselineFromTop(SVG_SCALEBAR_CAP, fontSize), textAnchor: "middle", fontSize: fontSize, fill: color, children: displayBp })] }));
 }

package/esm/LinearGenomeView/svgcomponents/SVGTrackLabel.d.ts

@@ -1,7 +1,9 @@
-export default function SVGTrackLabel({ trackLabels, trackName, fontSize, trackLabelOffset, x, }: {
+import type { TrackLabelMode } from '../types.ts';
+export default function SVGTrackLabel({ trackLabels, trackName, fontSize, textHeight, trackLabelOffset, x, }: {
     trackName: string;
-    trackLabels: string;
+    trackLabels: TrackLabelMode;
     fontSize: number;
+    textHeight: number;
     trackLabelOffset: number;
     x: number;
-}): import("react/jsx-runtime").JSX.Element | null;
+}): import("react").JSX.Element | null;

package/esm/LinearGenomeView/svgcomponents/SVGTrackLabel.js

@@ -1,11 +1,47 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { coarseStripHTML, stripAlpha } from '@jbrowse/core/util';
+import { stripAlpha } from '@jbrowse/core/util';
 import { useTheme } from '@mui/material';
-export default function SVGTrackLabel({ trackLabels, trackName, fontSize, trackLabelOffset, x, }) {
+import { TRACK_LABEL_GAP, insetLabelBaselineY, offsetLabelBaselineY, } from './util.js';
+// Where the label sits, per mode. 'left' right-aligns in the gutter
+// trackLabelLeftOffset reserved (hence the shared TRACK_LABEL_GAP); the other
+// modes hang off the leftmost visible content at `x`, either just above the
+// track body ('offset') or inset over it ('overlay').
+//
+// Every mode is placed on its alphabetic baseline (the SVG default, so no
+// dominantBaseline is emitted at all): 'offset' so its descenders land a known
+// distance above the track body — the band it sits in is `textHeight` tall, and
+// offsetLabelBaselineY owns that arithmetic — and 'left'/'overlay' so their
+// ascenders stay inside the track box they align with. 'left' used to be pinned
+// at a hardcoded y=20 on a hanging baseline, which neither scaled with fontSize
+// nor stayed inside a track shorter than ~35px.
+function labelPosition({ trackLabels, trackLabelOffset, textHeight, fontSize, x, }) {
+    if (trackLabels === 'left') {
+        return {
+            x: trackLabelOffset - TRACK_LABEL_GAP,
+            y: insetLabelBaselineY(fontSize),
+            textAnchor: 'end',
+        };
+    }
+    // the other two are left-aligned, which is the SVG default, so neither emits
+    // a textAnchor at all
+    if (trackLabels === 'offset') {
+        return { x, y: offsetLabelBaselineY(textHeight, fontSize) };
+    }
+    // inset over the track body, on a baseline far enough down that the ascenders
+    // stay inside it (at y=0 they rose into the track above)
+    return { x: x + 5, y: insetLabelBaselineY(fontSize) };
+}
+export default function SVGTrackLabel({ trackLabels, trackName, fontSize, textHeight, trackLabelOffset, x, }) {
     const theme = useTheme();
-    const fill = stripAlpha(theme.palette.text.primary);
-    const xoff = trackLabels === 'overlay' ? 5 : 0;
-    const yoff = trackLabels === 'offset' ? 5 : 0;
-    const name = coarseStripHTML(trackName);
-    return trackLabels !== 'none' ? (_jsx("g", { children: trackLabels === 'left' ? (_jsx("text", { x: trackLabelOffset - 40, y: 20, fill: fill, fontSize: fontSize, dominantBaseline: "hanging", textAnchor: "end", children: name })) : (_jsx("text", { x: x + xoff, y: yoff, fill: fill, fontSize: fontSize, dominantBaseline: "hanging", children: name })) })) : null;
+    if (trackLabels === 'none') {
+        return null;
+    }
+    const pos = labelPosition({
+        trackLabels,
+        trackLabelOffset,
+        textHeight,
+        fontSize,
+        x,
+    });
+    return (_jsx("text", { x: pos.x, y: pos.y, textAnchor: pos.textAnchor, fontSize: fontSize, fill: stripAlpha(theme.palette.text.primary), children: trackName }));
 }

package/esm/LinearGenomeView/svgcomponents/SVGTracks.d.ts

@@ -1,21 +1,15 @@
 import type { LinearGenomeViewModel } from '../index.ts';
-import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { TrackLabelMode } from '../types.ts';
+import type { SvgDisplayResult } from './util.ts';
 type LGV = LinearGenomeViewModel;
-interface DisplayResult {
-    track: {
-        configuration: AnyConfigurationModel;
-        displays: {
-            height: number;
-        }[];
-    };
-    result: string;
-}
-export default function SVGTracks({ displayResults, model, textHeight, fontSize, trackLabels, trackLabelOffset, }: {
-    displayResults: DisplayResult[];
+export default function SVGTracks({ displayResults, model, textHeight, fontSize, trackLabels, trackLabelOffset, leftBuffer, legendWidth, }: {
+    displayResults: SvgDisplayResult[];
     model: LGV;
     textHeight: number;
     fontSize: number;
-    trackLabels?: string;
+    trackLabels?: TrackLabelMode;
     trackLabelOffset?: number;
-}): import("react/jsx-runtime").JSX.Element;
+    leftBuffer?: number;
+    legendWidth?: number;
+}): import("react").JSX.Element;
 export {};

package/esm/LinearGenomeView/svgcomponents/SVGTracks.js

@@ -1,26 +1,21 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SvgClipRect } from '@jbrowse/core/svg/SvgExport';
+import { svgNodeId } from '@jbrowse/core/svg/svgId';
+import { svgTrackName } from '@jbrowse/core/svg/trackNames';
 import { getSession } from '@jbrowse/core/util';
-import { getTrackName } from '@jbrowse/core/util/tracks';
-import SVGRegionSeparators from "./SVGRegionSeparators.js";
-import SVGTrackLabel from "./SVGTrackLabel.js";
-export default function SVGTracks({ displayResults, model, textHeight, fontSize, trackLabels = 'offset', trackLabelOffset = 0, }) {
+import SVGRegionSeparators from './SVGRegionSeparators.js';
+import SVGTrackLabel from './SVGTrackLabel.js';
+import { labelOffset, trackBoxOffsets } from './util.js';
+export default function SVGTracks({ displayResults, model, textHeight, fontSize, trackLabels = 'offset', trackLabelOffset = 0, leftBuffer = 0, legendWidth = 0, }) {
     const session = getSession(model);
-    const textOffset = trackLabels === 'offset' ? textHeight : 0;
-    return (_jsx(_Fragment, { children: displayResults.reduce(({ prevOffset, reactElements }, { track, result }) => {
+    const textOffset = labelOffset(trackLabels, textHeight);
+    const x = Math.max(-model.offsetPx, 0);
+    const offsets = trackBoxOffsets(displayResults.map(r => r.track), textOffset);
+    return (_jsx(_Fragment, { children: displayResults.map(({ track, result }, i) => {
             const conf = track.configuration;
-            const trackName = getTrackName(conf, session);
+            const trackName = svgTrackName(track, session);
             const display = track.displays[0];
-            const x = Math.max(-model.offsetPx, 0);
-            const currOffset = prevOffset + display.height + textOffset;
-            return {
-                prevOffset: currOffset,
-                reactElements: [
-                    ...reactElements,
-                    _jsxs("g", { transform: `translate(0 ${prevOffset})`, children: [_jsxs("g", { transform: `translate(${trackLabelOffset} ${textOffset})`, children: [_jsx(SVGRegionSeparators, { model: model, height: display.height }), result] }), _jsx(SVGTrackLabel, { trackName: trackName, fontSize: fontSize, trackLabels: trackLabels, trackLabelOffset: trackLabelOffset, x: x })] }, conf.trackId),
-                ],
-            };
-        }, {
-            prevOffset: 0,
-            reactElements: [],
-        }).reactElements }));
+            const currentOffset = offsets[i];
+            return (_jsxs("g", { transform: `translate(0 ${currentOffset})`, children: [_jsx(SvgClipRect, { id: `track-clip-${svgNodeId(model)}-${conf.trackId}`, x: -leftBuffer, y: textOffset, width: model.width + trackLabelOffset + leftBuffer + legendWidth, height: display.height, children: _jsxs("g", { transform: `translate(${trackLabelOffset} ${textOffset})`, children: [result, _jsx(SVGRegionSeparators, { model: model, height: display.height })] }) }), _jsx(SVGTrackLabel, { trackName: trackName, fontSize: fontSize, textHeight: textHeight, trackLabels: trackLabels, trackLabelOffset: trackLabelOffset, x: x })] }, conf.trackId));
+        }) }));
 }

package/esm/LinearGenomeView/svgcomponents/SVGView.d.ts

@@ -0,0 +1,18 @@
+import type { LinearGenomeViewModel } from '../index.ts';
+import type { TrackLabelMode } from '../types.ts';
+import type { SvgDisplayResult } from './util.ts';
+import type { ReactNode } from 'react';
+export default function SVGView({ view, displayResults, header, fontSize, textHeight, trackLabels, trackLabelOffset, contentTop, tracksHeight, showGridlines, leftBuffer, legendWidth, }: {
+    view: LinearGenomeViewModel;
+    displayResults: SvgDisplayResult[];
+    header: ReactNode;
+    fontSize: number;
+    textHeight: number;
+    trackLabels: TrackLabelMode;
+    trackLabelOffset: number;
+    contentTop: number;
+    tracksHeight: number;
+    showGridlines: boolean;
+    leftBuffer?: number;
+    legendWidth?: number;
+}): import("react").JSX.Element;

package/esm/LinearGenomeView/svgcomponents/SVGView.js

@@ -0,0 +1,13 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import SVGGridlines from './SVGGridlines.js';
+import SVGHighlightsOverlay from './SVGHighlightsOverlay.js';
+import SVGTracks from './SVGTracks.js';
+// One LGV's worth of exported SVG: a caller-supplied header on top, then
+// optional gridlines, the track bodies, and the highlight layer over them.
+// Shared by all three exports that stack an LGV — the standalone one, and the
+// linear-synteny and breakpoint-split rows — so their per-view layout can't
+// drift. It did drift while the standalone export kept its own copy of these
+// four groups: only that copy widened the per-track clip by `legendWidth`.
+export default function SVGView({ view, displayResults, header, fontSize, textHeight, trackLabels, trackLabelOffset, contentTop, tracksHeight, showGridlines, leftBuffer = 0, legendWidth = 0, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("g", { transform: `translate(${trackLabelOffset})`, children: header }), showGridlines ? (_jsx("g", { transform: `translate(${trackLabelOffset} ${contentTop})`, children: _jsx(SVGGridlines, { model: view, height: tracksHeight }) })) : null, _jsx("g", { transform: `translate(0 ${contentTop})`, children: _jsx(SVGTracks, { textHeight: textHeight, trackLabels: trackLabels, fontSize: fontSize, model: view, displayResults: displayResults, trackLabelOffset: trackLabelOffset, leftBuffer: leftBuffer, legendWidth: legendWidth }) }), _jsx("g", { transform: `translate(${trackLabelOffset} ${contentTop})`, children: _jsx(SVGHighlightsOverlay, { model: view, tracksHeight: tracksHeight }) })] }));
+}

package/esm/LinearGenomeView/svgcomponents/figureContract.d.ts

@@ -0,0 +1,45 @@
+import type { RefObject } from 'react';
+/**
+ * One live figure per view.
+ *
+ * Every id a figure mints is `<what>-${svgNodeId(view)}`, deterministic so that
+ * exporting an unchanged view twice produces the same bytes (see `svgNodeId`).
+ * The same property makes two figures of ONE view collide on all of them, and
+ * SVG ids are document-global with `url(#…)` resolving to the first match — so
+ * the second figure's tracks are clipped by the first figure's rects. With
+ * different options on the two (the reason to draw two in the first place) those
+ * rects are the wrong size, and it reads as a track drawn unclipped or a
+ * highlight band cut short.
+ *
+ * Deliberately not fixed by scoping the ids per figure. The determinism is load
+ * bearing for the file export that shares these components, and a second figure
+ * of one view is a thing to do differently rather than a case to support.
+ */
+export declare function useOneFigurePerView(view: {
+    id: string;
+}): void;
+/**
+ * Nothing inside a figure re-renders itself.
+ *
+ * A figure's track bodies are built once and frozen; its ruler, scalebar and
+ * seams re-derive from the model on any render they get. The `memo` in
+ * `useViewSvgFigure` is what keeps those in step, and it sits between the figure
+ * and its PARENT — it is not between a component inside the figure and MobX. An
+ * `observer` in there re-renders on its own subscription and slides across
+ * bodies drawn at a moment in the past, which is a rendering bug the picture
+ * gives no sign of.
+ *
+ * Checked as the state rather than the shape, because the shape is not
+ * detectable: `observer(f)` on a function component is `memo(f)` with no marker
+ * on it, so it cannot be told from a plain `memo`, which is harmless. Watching
+ * for the symptom also covers what an enumeration would miss — a plugin's
+ * component reached through `LinearGenomeView-HighlightSVGComponent`, an
+ * observer a display's `renderSvg` returned, or a subscription that is not
+ * MobX's at all.
+ *
+ * A mutation is only a violation while the snapshot is unchanged. React's own
+ * commit for a NEW snapshot mutates this subtree too, so `rendered` moves to
+ * that snapshot during the render that precedes the commit and the records are
+ * ignored.
+ */
+export declare function useFrozenFigureContract(ref: RefObject<SVGSVGElement | null>, snapshot: object): void;

package/esm/LinearGenomeView/svgcomponents/figureContract.js

@@ -0,0 +1,130 @@
+import { useEffect, useRef } from 'react';
+import { svgNodeId } from '@jbrowse/core/svg/svgId';
+import { contractReportsOn, reportContractViolation, } from '@jbrowse/render-core/contractReports';
+/**
+ * Checks that a live SVG figure is being used the way it can work.
+ *
+ * `useViewSvgFigure` publishes a figure whose two halves are drawn at different
+ * moments and only agree by construction, and both ways of breaking that are
+ * invisible in the output: the drawing is still a plausible picture of
+ * somewhere, just not of one moment or not with its own clips. So the run
+ * reports instead, through the `[jbrowse <family> contract]` channel every
+ * check in the tree uses — `config/jest/contractGate.js` fails the test that
+ * collects one, and ARCHITECTURAL_LIMITS.md §"Ordering is the contract" is the
+ * register. `figure` rather than `svg-figure` because the gate's family pattern
+ * is `\w+`, which a hyphen is not.
+ *
+ * Reported and never thrown, as the rest of that family: a figure is chrome a
+ * host renders beside its own, and taking the host's tree down over a drawing
+ * is worse than the drawing being wrong.
+ */
+function report(message) {
+    reportContractViolation('figure', message);
+}
+// Live figures per view, keyed the way their SVG ids are. A count rather than a
+// flag: the report belongs on the second mount, and the first has to survive the
+// second unmounting.
+const figuresPerView = new Map();
+/**
+ * One live figure per view.
+ *
+ * Every id a figure mints is `<what>-${svgNodeId(view)}`, deterministic so that
+ * exporting an unchanged view twice produces the same bytes (see `svgNodeId`).
+ * The same property makes two figures of ONE view collide on all of them, and
+ * SVG ids are document-global with `url(#…)` resolving to the first match — so
+ * the second figure's tracks are clipped by the first figure's rects. With
+ * different options on the two (the reason to draw two in the first place) those
+ * rects are the wrong size, and it reads as a track drawn unclipped or a
+ * highlight band cut short.
+ *
+ * Deliberately not fixed by scoping the ids per figure. The determinism is load
+ * bearing for the file export that shares these components, and a second figure
+ * of one view is a thing to do differently rather than a case to support.
+ */
+export function useOneFigurePerView(view) {
+    useEffect(() => {
+        // captured, not re-derived on cleanup: by then the view may have left the
+        // tree, and `svgNodeId` walks it
+        const key = svgNodeId(view);
+        const live = (figuresPerView.get(key) ?? 0) + 1;
+        figuresPerView.set(key, live);
+        if (live > 1) {
+            report(`${live} live figures of one view are mounted at once. They mint the ` +
+                `same SVG ids (ruler-clip-${key}, track-clip-${key}-<trackId>, …), ` +
+                `ids are document-global, and url(#…) resolves to the first match — ` +
+                `so every figure after the first is clipped by the first one's rects ` +
+                `and draws its tracks and highlights at the wrong extent. Render one ` +
+                `figure per view.`);
+        }
+        return () => {
+            const left = (figuresPerView.get(key) ?? 1) - 1;
+            if (left > 0) {
+                figuresPerView.set(key, left);
+            }
+            else {
+                figuresPerView.delete(key);
+            }
+        };
+    }, [view]);
+}
+/**
+ * Nothing inside a figure re-renders itself.
+ *
+ * A figure's track bodies are built once and frozen; its ruler, scalebar and
+ * seams re-derive from the model on any render they get. The `memo` in
+ * `useViewSvgFigure` is what keeps those in step, and it sits between the figure
+ * and its PARENT — it is not between a component inside the figure and MobX. An
+ * `observer` in there re-renders on its own subscription and slides across
+ * bodies drawn at a moment in the past, which is a rendering bug the picture
+ * gives no sign of.
+ *
+ * Checked as the state rather than the shape, because the shape is not
+ * detectable: `observer(f)` on a function component is `memo(f)` with no marker
+ * on it, so it cannot be told from a plain `memo`, which is harmless. Watching
+ * for the symptom also covers what an enumeration would miss — a plugin's
+ * component reached through `LinearGenomeView-HighlightSVGComponent`, an
+ * observer a display's `renderSvg` returned, or a subscription that is not
+ * MobX's at all.
+ *
+ * A mutation is only a violation while the snapshot is unchanged. React's own
+ * commit for a NEW snapshot mutates this subtree too, so `rendered` moves to
+ * that snapshot during the render that precedes the commit and the records are
+ * ignored.
+ */
+export function useFrozenFigureContract(ref, snapshot) {
+    const rendered = useRef(snapshot);
+    rendered.current = snapshot;
+    useEffect(() => {
+        const el = ref.current;
+        // the one check here with a cost of its own — a `MutationObserver` over the
+        // whole figure subtree — so unlike its neighbour it asks whether the
+        // channel is armed rather than running and reporting into it
+        if (!contractReportsOn() || !el) {
+            return undefined;
+        }
+        const observer = new MutationObserver(() => {
+            if (rendered.current !== snapshot) {
+                return;
+            }
+            // once is the whole message; a drifting subtree mutates every frame
+            observer.disconnect();
+            report(`a figure redrew part of itself against a snapshot that did not ` +
+                `change, so its chrome and its track bodies now describe different ` +
+                `moments and a pan slides one across the other. Something inside it ` +
+                `is subscribed to the view — most often an observer component a ` +
+                `plugin contributed to LinearGenomeView-HighlightSVGComponent, or ` +
+                `one a display's renderSvg returned. Nothing inside a figure may be ` +
+                `an observer: the memo that freezes it is between the figure and its ` +
+                `parent, not between an observer and MobX.`);
+        });
+        observer.observe(el, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            characterData: true,
+        });
+        return () => {
+            observer.disconnect();
+        };
+    }, [ref, snapshot]);
+}

package/esm/LinearGenomeView/svgcomponents/renderViewTracks.d.ts

@@ -0,0 +1,76 @@
+import type { ExportSvgOptions, TrackLabelMode } from '../types.ts';
+import type { ExportSvgDisplayOptions } from '@jbrowse/display-kit/types';
+import type { ThemeOptions } from '@mui/material';
+import type { ReactNode } from 'react';
+export interface SvgExportTrack {
+    minimized: boolean;
+    displays: {
+        height: number;
+        svgLegendWidth?: () => number;
+        /**
+         * Optional, and the option is the point: SVG export is a substantial extra
+         * implementation for a display type, and a third-party plugin that has not
+         * written one should cost its own track a place in the figure, not cost
+         * everyone in the session the ability to export at all. A display without
+         * one is dropped from the export the same way a minimized track is, and
+         * `skippedTracks` carries it back out so the user is told which.
+         */
+        renderSvg?: (opts: ExportSvgDisplayOptions) => Promise<ReactNode>;
+    }[];
+}
+export interface ViewTracksSvg<T> {
+    /** the tracks that were rendered, in the order they were laid out */
+    tracks: T[];
+    displayResults: {
+        track: T;
+        result: ReactNode;
+    }[];
+    /** total height of the stack, valid only because the renders above resolved */
+    tracksHeight: number;
+    /** 0 unless `reserveLegendWidth` was asked for */
+    legendWidth: number;
+    /**
+     * Visible tracks left out because their display implements no `renderSvg`.
+     * Not an error, but not nothing either — a figure quietly missing a track is
+     * its own trap, so callers report these once per export.
+     */
+    skippedTracks: T[];
+}
+/**
+ * One view's worth of exported track bodies: which tracks are in, their
+ * rendered SVG, and how tall the stack ends up.
+ *
+ * It exists to own the two orderings that each of the three view exports got
+ * wrong at least once, because neither is visible at a call site that merely
+ * lists the same statements in some order:
+ *
+ * - `legendWidth` is measured **before** the awaits, because it is an input to
+ *   them: a display draws its legend beside its body or floating over it
+ *   depending on whether the container reserved room. That is why
+ *   `svgLegendWidth` is specified as a function of the *settings* and not of
+ *   the loaded data — see LinearHicDisplay's implementation.
+ * - `tracksHeight` is measured **after** them. A display whose height follows
+ *   its data (grow mode; `LinearMultiRowFeatureDisplay` is `nrow *
+ *   effectiveRowHeight`) only reaches its final height once `renderSvg`'s
+ *   readiness wait resolves, and `SVGTracks` re-reads `displays[0].height`
+ *   later still. Measuring up front sized the canvas for the pre-fetch height
+ *   and the taller bodies ran off the bottom of the export — and in the
+ *   breakpoint-split export it also desynced the overlay anchors, resolved
+ *   after, from the view tops, which weren't.
+ *
+ * The minimized filter and the track order are here for the same reason: the
+ * reserved height, the rendered bodies, the label gutter and (breakpoint-split)
+ * the ribbon anchors must all be derived from one list, and pinned tracks are
+ * drawn at the top of a view on screen.
+ */
+export declare function renderViewTracks<T extends SvgExportTrack>({ view, opts, theme, textHeight, trackLabels, reserveLegendWidth, }: {
+    view: {
+        pinnedTracks: T[];
+        unpinnedTracks: T[];
+    };
+    opts: ExportSvgOptions;
+    theme: ThemeOptions | undefined;
+    textHeight: number;
+    trackLabels: TrackLabelMode;
+    reserveLegendWidth?: boolean;
+}): Promise<ViewTracksSvg<T>>;