@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/SvgCanvas.js

@@ -0,0 +1,520 @@
+import { measureText as measureTextWidth } from './measureText.js';
+import { splitPaintAlpha } from './svgColorProps.js';
+const XML_ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+};
+function escapeXml(s) {
+    return s.replaceAll(/[&<>"]/g, c => XML_ESCAPES[c]);
+}
+// CSS font shorthand is [style] [variant] [weight] [stretch] <size>[/line-height]
+// <family>, so the tokens before the size have to be captured too: dropping them
+// rendered every `bold Npx ...` label (MAF codons, alignment read labels) at
+// regular weight in an SVG export while the canvas drew it bold.
+const fontShorthandRe = /^(.*?)(\d+(?:\.\d+)?)px(?:\/\S+)?\s+(.+)$/;
+const fontWeightTokens = new Set(['bold', 'bolder', 'lighter']);
+const fontStyleTokens = new Set(['italic', 'oblique']);
+// CSS font shorthand broken into the parts both consumers below need. One parse,
+// because they are the emitted size/family and the *measured* size/family, and a
+// string measured in one face and painted in another is the drift the whole
+// class exists to avoid. A bare "12px" (no family) still yields its size.
+function parseFont(font) {
+    const m = fontShorthandRe.exec(font);
+    return m
+        ? { prefix: m[1] ?? '', size: m[2], family: m[3] ?? '' }
+        : { prefix: '', size: `${Number.parseFloat(font) || 10}`, family: '' };
+}
+// Parse CSS font shorthand like "10px sans-serif" or "bold 12px monospace" into
+// SVG-compatible attributes. The default sans-serif family is left off so
+// feature labels match the raw-JSX <text> elements (ruler, scalebar, etc.),
+// which set no family either; an explicitly-set family is still emitted.
+function fontAttrs(font, scale) {
+    const { prefix, size, family } = parseFont(font);
+    const tokens = prefix.split(/\s+/).filter(Boolean);
+    const weight = tokens.find(t => fontWeightTokens.has(t) || /^\d{1,4}$/.test(t));
+    const style = tokens.find(t => fontStyleTokens.has(t));
+    return [
+        ` font-size="${Number(size) * scale}"`,
+        family === '' || family === 'sans-serif'
+            ? ''
+            : ` font-family="${escapeXml(family)}"`,
+        weight ? ` font-weight="${weight}"` : '',
+        style ? ` font-style="${style}"` : '',
+    ].join('');
+}
+// SVG ids are document-global (see svg/svgId.ts), so this counter has to be
+// too: one export mounts many SvgCanvas instances — a PaintLayer per display,
+// per band, per legend — and a per-instance counter would have every one of them
+// mint `svgcanvas-clip-0`, whereupon `url(#svgcanvas-clip-0)` resolves to the
+// first and every later layer is clipped to some other layer's rect.
+//
+// Document-global, not process-global: `withFreshSvgClipIds` below.
+let clipIdCounter = 0;
+/**
+ * Run `render` as one document's clip-id numbering run, starting at 0, then put
+ * the counter back.
+ *
+ * Starting at 0 is what makes the same view export to the same bytes: a counter
+ * left running numbers each export from wherever the previous one stopped, so
+ * diffing two saved SVGs shows changes that aren't real and `jest -t` on any
+ * export test but the first fails its snapshot on renumbering alone.
+ *
+ * Putting it back is what keeps a file export from renumbering the page: live
+ * figures (`useViewSvgFigure`) mint from the same counter into one DOM, where
+ * ids must not repeat, so a reset that stuck would let the next figure reuse an
+ * id another figure still points at.
+ *
+ * `render` must be synchronous — an `await` inside it would let two documents
+ * share a numbering run.
+ */
+export function withFreshSvgClipIds(render) {
+    const saved = clipIdCounter;
+    clipIdCounter = 0;
+    try {
+        return render();
+    }
+    finally {
+        clipIdCounter = saved;
+    }
+}
+export class SvgCanvas {
+    parts = [];
+    pathData = '';
+    stack = [];
+    // Clip groups `clip()` has opened but not yet written. Only a drawn element
+    // flushes them (`emit`), so a clip nothing was drawn inside is dropped
+    // entirely rather than serialized as a dead `<clipPath>` + empty `<g>`. See
+    // `clip()`.
+    pendingGroups = [];
+    // Flushed groups still awaiting their `</g>`.
+    openGroups = 0;
+    fillStyle = '#000';
+    strokeStyle = '#000';
+    lineWidth = 1;
+    font = '10px sans-serif';
+    textAlign = 'start';
+    textBaseline = 'alphabetic';
+    lineCap = 'butt';
+    lineJoin = 'miter';
+    // No `globalAlpha` and no `globalCompositeOperation`, deliberately: neither
+    // has an SVG equivalent this class could emit, so accepting one would let a
+    // painter set it, see it work on screen, and get a silently different export.
+    // Absent, the same line is a compile error against `Ctx2D`. That is already
+    // the rule for `globalAlpha` — the canvas feature renderer, the dotplot
+    // painter and MAF's inversion hatch each fold their opacity into an `rgba()`
+    // fill and say why. `globalCompositeOperation` was declared and save/restored
+    // but never emitted, so it was the half-kept version of the same idea.
+    lineDash = [];
+    // The CTM, as the SVG `matrix(a b c d e f)` affine:
+    //   x' = a*x + c*y + e      y' = b*x + d*y + f
+    // A full matrix rather than the separate translate/scale/rotate scalars this
+    // used to keep, because those composed in the wrong order: canvas
+    // `translate; scale; rotate` means rotate-then-scale (the last call applies
+    // first), while the scalars applied scale first. Identical for a uniform
+    // scale, but hic's fit-to-height triangle scales y and x differently, so its
+    // export came out tilted off the diagonal (proven in
+    // plugins/hic/.../svgExportGeometry.test.ts).
+    a = 1;
+    b = 0;
+    c = 0;
+    d = 1;
+    e = 0;
+    f = 0;
+    // No rotation/skew term, so a rect stays a rect and `x/y/width/height` can
+    // express it. Every caller but hic stays here.
+    get axisAligned() {
+        return this.b === 0 && this.c === 0;
+    }
+    // How much the CTM scales a length, for what SVG draws at a size of its own
+    // rather than through transformed coordinates: stroke widths, dashes and
+    // font sizes. Exact for a uniform scale; the geometric mean otherwise, where
+    // a Canvas2D pen would draw an ellipse no stroke-width can state.
+    get lengthScale() {
+        return Math.sqrt(Math.abs(this.a * this.d - this.b * this.c));
+    }
+    transformPoint(x, y) {
+        return [this.a * x + this.c * y + this.e, this.b * x + this.d * y + this.f];
+    }
+    // Axis-aligned only — a rotated CTM shares its width between both axes, and
+    // the callers that combine the two emit the matrix instead of pre-sizing.
+    transformSize(w, h) {
+        return [w * Math.abs(this.a), h * Math.abs(this.d)];
+    }
+    // Places a shape's local origin at `x,y` under the current CTM, keeping only
+    // the linear part in the matrix. The caller then emits the shape at local
+    // 0,0.
+    //
+    // Folding the origin into the translation this way is what keeps the export's
+    // 2-decimal `transform` rounding (wrapSvgExport) harmless: a/b/c/d are
+    // unitless multipliers, so rounding them displaces a point in proportion to
+    // its coordinate — 0.005 of error across a 1000px layer is 5px. Rounded
+    // translations are plain pixels, and the leftover rounding of a/b/c/d then
+    // only perturbs the shape's own width and height (sub-0.05px for a bin).
+    originMatrixAttr(x, y) {
+        const { a, b, c, d } = this;
+        const [tx, ty] = this.transformPoint(x, y);
+        return ` transform="matrix(${a} ${b} ${c} ${d} ${tx} ${ty})"`;
+    }
+    // Rects arrive as origin + size, but a negative scale flips which corner the
+    // origin lands on: under scale(-1, 1) the local left edge `x` becomes the
+    // right edge, so anchoring at transformPoint(x, y) and extending right by
+    // `w` covers the neighboring `w` of the canvas — the rect is drawn a full
+    // width off. Anchor on whichever corner ends up top-left instead.
+    // `transformSize` stays magnitude-only because an SVG width/height can't be
+    // negative. A no-op for positive scales (every caller today), which is why
+    // this was never noticed.
+    //
+    // Axis-aligned CTMs only — callers reach this through the `axisAligned`
+    // branches, and a rotated/skewed CTM goes through `originMatrixAttr` instead
+    // (which handles mirroring for free, since the matrix transforms the rect's
+    // own geometry).
+    //
+    // A negative *size* argument (`fillRect(x, y, -w, h)`, which a real canvas
+    // treats as the same rect anchored at `x-w`) is NOT normalized here — SVG
+    // would emit `width="-w"` and silently not render. Callers must pass a
+    // non-negative size; spans resolve both edges and take
+    // `left = min(x1,x2)` / `w = abs(x2-x1)` (see render-core/CLAUDE.md), the
+    // same convention that keeps reversed blocks correct.
+    transformRect(x, y, w, h) {
+        const [tx, ty] = this.transformPoint(this.a < 0 ? x + w : x, this.d < 0 ? y + h : y);
+        const [tw, th] = this.transformSize(w, h);
+        return [tx, ty, tw, th];
+    }
+    textAnchor() {
+        return this.textAlign === 'center'
+            ? 'middle'
+            : this.textAlign === 'right' || this.textAlign === 'end'
+                ? 'end'
+                : 'start';
+    }
+    paintAttr(name, style) {
+        const s = `${style}`;
+        const split = splitPaintAlpha(s);
+        if (!split) {
+            return `${name}="${s}"`;
+        }
+        const base = `${name}="${split.color}"`;
+        return split.opacity < 1
+            ? `${base} ${name}-opacity="${split.opacity}"`
+            : base;
+    }
+    strokeAttrs() {
+        const scale = this.lengthScale;
+        let attrs = ` ${this.paintAttr('stroke', this.strokeStyle)} stroke-width="${this.lineWidth * scale}"`;
+        if (this.lineCap !== 'butt') {
+            attrs += ` stroke-linecap="${this.lineCap}"`;
+        }
+        if (this.lineJoin !== 'miter') {
+            attrs += ` stroke-linejoin="${this.lineJoin}"`;
+        }
+        if (this.lineDash.length > 0) {
+            attrs += ` stroke-dasharray="${this.lineDash.map(d => d * scale).join(',')}"`;
+        }
+        return attrs;
+    }
+    // Every element that actually paints goes through here, and nothing else
+    // does. Writing a drawn element is what commits the clip groups enclosing it,
+    // which is what makes "nothing was drawn" observable at the end (`parts` stays
+    // empty) instead of being masked by the clip markup of the blocks that were
+    // walked and found empty.
+    emit(markup) {
+        if (this.pendingGroups.length > 0) {
+            this.parts.push(...this.pendingGroups);
+            this.openGroups += this.pendingGroups.length;
+            this.pendingGroups.length = 0;
+        }
+        this.parts.push(markup);
+    }
+    save() {
+        this.stack.push({
+            fillStyle: `${this.fillStyle}`,
+            strokeStyle: `${this.strokeStyle}`,
+            lineWidth: this.lineWidth,
+            font: this.font,
+            textAlign: this.textAlign,
+            textBaseline: this.textBaseline,
+            lineCap: this.lineCap,
+            lineJoin: this.lineJoin,
+            lineDash: [...this.lineDash],
+            a: this.a,
+            b: this.b,
+            c: this.c,
+            d: this.d,
+            e: this.e,
+            f: this.f,
+            groupsToClose: 0,
+        });
+    }
+    restore() {
+        const s = this.stack.pop();
+        if (s) {
+            for (let i = 0; i < s.groupsToClose; i++) {
+                if (this.pendingGroups.length > 0) {
+                    // Still pending means nothing was drawn between this clip() and its
+                    // restore(), so neither the group nor its <clipPath> is written at
+                    // all. The pending list is a stack, and a flush empties it whole, so
+                    // its tail is always this frame's own clips.
+                    this.pendingGroups.pop();
+                }
+                else {
+                    this.parts.push('</g>');
+                    this.openGroups--;
+                }
+            }
+            this.fillStyle = s.fillStyle;
+            this.strokeStyle = s.strokeStyle;
+            this.lineWidth = s.lineWidth;
+            this.font = s.font;
+            this.textAlign = s.textAlign;
+            this.textBaseline = s.textBaseline;
+            this.lineCap = s.lineCap;
+            this.lineJoin = s.lineJoin;
+            this.lineDash = s.lineDash;
+            this.a = s.a;
+            this.b = s.b;
+            this.c = s.c;
+            this.d = s.d;
+            this.e = s.e;
+            this.f = s.f;
+        }
+    }
+    // translate/scale/rotate/transform all right-multiply the CTM, matching
+    // CanvasRenderingContext2D: the most recently applied transform is the
+    // innermost one, so a later call affects the coordinate space of the calls
+    // before it and NOT vice versa.
+    translate(x, y) {
+        this.e += this.a * x + this.c * y;
+        this.f += this.b * x + this.d * y;
+    }
+    scale(x, y) {
+        this.a *= x;
+        this.b *= x;
+        this.c *= y;
+        this.d *= y;
+    }
+    rotate(angle) {
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        const { a, b, c, d } = this;
+        this.a = a * cos + c * sin;
+        this.b = b * cos + d * sin;
+        this.c = c * cos - a * sin;
+        this.d = d * cos - b * sin;
+    }
+    resetTransform() {
+        this.a = 1;
+        this.b = 0;
+        this.c = 0;
+        this.d = 1;
+        this.e = 0;
+        this.f = 0;
+    }
+    setTransform(a, b, c, d, e, f) {
+        this.a = a;
+        this.b = b;
+        this.c = c;
+        this.d = d;
+        this.e = e;
+        this.f = f;
+    }
+    transform(a, b, c, d, e, f) {
+        const { a: a0, b: b0, c: c0, d: d0 } = this;
+        this.a = a0 * a + c0 * b;
+        this.b = b0 * a + d0 * b;
+        this.c = a0 * c + c0 * d;
+        this.d = b0 * c + d0 * d;
+        this.e += a0 * e + c0 * f;
+        this.f += b0 * e + d0 * f;
+    }
+    setLineDash(segments) {
+        this.lineDash = [...segments];
+    }
+    getLineDash() {
+        return [...this.lineDash];
+    }
+    fillRect(x, y, w, h) {
+        if (this.axisAligned) {
+            const [tx, ty, tw, th] = this.transformRect(x, y, w, h);
+            this.emit(`<rect x="${tx}" y="${ty}" width="${tw}" height="${th}" ${this.paintAttr('fill', this.fillStyle)}/>`);
+        }
+        else {
+            // Under rotation with a non-uniform scale the rect is a parallelogram, so
+            // pre-transformed x/y/width/height can't describe it. Emit the local size
+            // and let the matrix place and shear it — exact for any affine, and
+            // adjacent rects still share edges (no AA seams between hic bins).
+            this.emit(`<rect width="${w}" height="${h}" ${this.paintAttr('fill', this.fillStyle)}${this.originMatrixAttr(x, y)}/>`);
+        }
+    }
+    clearRect(_x, _y, _w, _h) {
+        // no-op for SVG
+    }
+    strokeRect(x, y, w, h) {
+        if (this.axisAligned) {
+            const [tx, ty, tw, th] = this.transformRect(x, y, w, h);
+            this.emit(`<rect x="${tx}" y="${ty}" width="${tw}" height="${th}" fill="none"${this.strokeAttrs()}/>`);
+        }
+        else {
+            this.emit(`<rect width="${w}" height="${h}" fill="none"${this.strokeAttrs()}${this.originMatrixAttr(x, y)}/>`);
+        }
+    }
+    beginPath() {
+        this.pathData = '';
+    }
+    moveTo(x, y) {
+        const [tx, ty] = this.transformPoint(x, y);
+        this.pathData += `M${tx},${ty}`;
+    }
+    lineTo(x, y) {
+        const [tx, ty] = this.transformPoint(x, y);
+        this.pathData += `L${tx},${ty}`;
+    }
+    arc(x, y, radius, startAngle, endAngle, counterclockwise = false) {
+        this.ellipse(x, y, radius, radius, 0, startAngle, endAngle, counterclockwise);
+    }
+    ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise = false) {
+        const [rx, ry] = this.transformSize(radiusX, radiusY);
+        // A mirrored CTM turns a clockwise sweep counterclockwise on the page, and
+        // its rotation the other way.
+        const mirrored = this.a * this.d < 0;
+        const sweep = counterclockwise === mirrored ? 1 : 0;
+        const deg = ((mirrored ? -rotation : rotation) * 180) / Math.PI;
+        // Canvas measures the angle on the UNROTATED ellipse and then spins the
+        // whole thing, so the endpoint is the parametric point rotated — not the
+        // point at (angle + rotation) — and then placed by the CTM.
+        const at = (angle) => {
+            const px = radiusX * Math.cos(angle);
+            const py = radiusY * Math.sin(angle);
+            return this.transformPoint(x + px * Math.cos(rotation) - py * Math.sin(rotation), y + px * Math.sin(rotation) + py * Math.cos(rotation));
+        };
+        // The angle actually swept, as Canvas2D resolves it: in the stated
+        // direction, a whole turn once it reaches 2π, and otherwise wrapped into
+        // [0, 2π) — so a clockwise sweep from 0.5π back to 0 goes the long way.
+        const TAU = 2 * Math.PI;
+        const signed = counterclockwise
+            ? startAngle - endAngle
+            : endAngle - startAngle;
+        const swept = signed >= TAU ? TAU : ((signed % TAU) + TAU) % TAU;
+        const [sx, sy] = at(startAngle);
+        if (swept === TAU) {
+            // A closed ellipse has coincident endpoints, which an SVG arc command
+            // degenerates on — so go round in two halves, as a subpath of its own.
+            const half = counterclockwise ? -Math.PI : Math.PI;
+            const [hx, hy] = at(startAngle + half);
+            this.pathData += `M${sx},${sy}A${rx},${ry} ${deg} 1 ${sweep} ${hx},${hy}A${rx},${ry} ${deg} 1 ${sweep} ${sx},${sy}`;
+            return;
+        }
+        const [ex, ey] = at(endAngle);
+        const largeArc = swept > Math.PI ? 1 : 0;
+        this.pathData += !this.pathData ? `M${sx},${sy}` : `L${sx},${sy}`;
+        this.pathData += `A${rx},${ry} ${deg} ${largeArc} ${sweep} ${ex},${ey}`;
+    }
+    bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) {
+        const [tcp1x, tcp1y] = this.transformPoint(cp1x, cp1y);
+        const [tcp2x, tcp2y] = this.transformPoint(cp2x, cp2y);
+        const [tx, ty] = this.transformPoint(x, y);
+        this.pathData += `C${tcp1x},${tcp1y} ${tcp2x},${tcp2y} ${tx},${ty}`;
+    }
+    quadraticCurveTo(cpx, cpy, x, y) {
+        const [tcpx, tcpy] = this.transformPoint(cpx, cpy);
+        const [tx, ty] = this.transformPoint(x, y);
+        this.pathData += `Q${tcpx},${tcpy} ${tx},${ty}`;
+    }
+    rect(x, y, w, h) {
+        if (this.axisAligned) {
+            const [tx, ty, tw, th] = this.transformRect(x, y, w, h);
+            this.pathData += `M${tx},${ty}h${tw}v${th}h${-tw}Z`;
+        }
+        else {
+            // Path data carries no transform of its own, so a rotated CTM has to be
+            // baked into the four corners.
+            const [x0, y0] = this.transformPoint(x, y);
+            const [x1, y1] = this.transformPoint(x + w, y);
+            const [x2, y2] = this.transformPoint(x + w, y + h);
+            const [x3, y3] = this.transformPoint(x, y + h);
+            this.pathData += `M${x0},${y0}L${x1},${y1}L${x2},${y2}L${x3},${y3}Z`;
+        }
+    }
+    closePath() {
+        this.pathData += 'Z';
+    }
+    stroke() {
+        if (this.pathData) {
+            this.emit(`<path d="${this.pathData}" fill="none"${this.strokeAttrs()}/>`);
+        }
+    }
+    fill() {
+        if (this.pathData) {
+            this.emit(`<path d="${this.pathData}" ${this.paintAttr('fill', this.fillStyle)} stroke="none"/>`);
+        }
+    }
+    // Shared by fillText and strokeText: the halo pattern draws the same string
+    // twice through both, so they must resolve the baseline identically — with
+    // strokeText pinned to "auto" a non-alphabetic textBaseline slid the halo off
+    // the letters it is meant to back.
+    dominantBaseline() {
+        return this.textBaseline === 'middle'
+            ? 'middle'
+            : this.textBaseline === 'top' || this.textBaseline === 'hanging'
+                ? 'hanging'
+                : 'auto';
+    }
+    fillText(text, x, y) {
+        const [tx, ty] = this.transformPoint(x, y);
+        const escaped = escapeXml(text);
+        this.emit(`<text x="${tx}" y="${ty}" ${this.paintAttr('fill', this.fillStyle)}${fontAttrs(this.font, this.lengthScale)} text-anchor="${this.textAnchor()}" dominant-baseline="${this.dominantBaseline()}">${escaped}</text>`);
+    }
+    strokeText(text, x, y) {
+        const [tx, ty] = this.transformPoint(x, y);
+        const escaped = escapeXml(text);
+        this.emit(`<text x="${tx}" y="${ty}" fill="none"${this.strokeAttrs()}${fontAttrs(this.font, this.lengthScale)} text-anchor="${this.textAnchor()}" dominant-baseline="${this.dominantBaseline()}">${escaped}</text>`);
+    }
+    drawImage(..._args) {
+        // no-op: raster images can't be meaningfully serialized to SVG paths
+    }
+    clip(..._args) {
+        // Use the current path as a clipPath, then open a `<g clip-path>`
+        // group that subsequent draws will land inside. The group is closed by
+        // restore() — see groupsToClose on the save stack. Without a preceding
+        // save() the clip becomes permanent (matches Canvas2D semantics), and the
+        // group is closed by getSerializedSvg instead.
+        //
+        // Queued rather than written, because a clip is opened per candidate block
+        // and most of them paint nothing: `forEachClippedBlock` brackets every block
+        // that has data, and a block whose features are all off-screen (or whose
+        // layer is switched off) then leaves a dead `<clipPath>` + empty `<g>` pair
+        // behind. Those pairs are what made a layer that painted nothing still
+        // serialize as non-empty, defeating PaintLayer's elision of it.
+        if (!this.pathData) {
+            return;
+        }
+        const id = `svgcanvas-clip-${clipIdCounter++}`;
+        this.pendingGroups.push(`<clipPath id="${id}"><path d="${this.pathData}"/></clipPath><g clip-path="url(#${id})">`);
+        if (this.stack.length > 0) {
+            this.stack[this.stack.length - 1].groupsToClose++;
+        }
+    }
+    // The family goes through, not just the size: `measureText` switches to the
+    // fixed monospace advance on seeing one, so dropping it measured a monospace
+    // string against the proportional table — the same string, laid out one way on
+    // a real canvas and another in the export, with nothing to show which. An
+    // estimate all the same: a draw whose layout turns on a width (synteny's
+    // off-screen mate labels) measures through a real canvas and passes the
+    // result in, so the figure names what the screen named.
+    measureText(text) {
+        const { size, family } = parseFont(this.font);
+        return { width: measureTextWidth(text, Number(size), family) };
+    }
+    // The fragment drawn so far, or '' if nothing was drawn — PaintLayer reads
+    // the empty string as "emit no element at all".
+    //
+    // Groups still open are closed here: a permanent clip (one with no save() to
+    // scope it) has no restore() to close it, and neither does a painter that
+    // throws between the two. Leaving them open emitted an unbalanced `<g>`, which
+    // is not merely untidy — an SVG file is XML, so it doesn't parse at all.
+    // Non-mutating, so calling this twice returns the same string.
+    getSerializedSvg() {
+        return this.parts.join('') + '</g>'.repeat(this.openGroups);
+    }
+}

package/esm/util/TimeTraveller.d.ts

@@ -1,3 +1,8 @@
+/**
+ * #stateModel TimeTraveller
+ * Undo/redo history for a target state-tree node: records snapshots as it
+ * changes and exposes canUndo/canRedo with undo/redo actions.
+ */
 declare const TimeTraveller: import("@jbrowse/mobx-state-tree").IModelType<{
     undoIdx: import("@jbrowse/mobx-state-tree").IType<number | undefined, number, number>;
     targetPath: import("@jbrowse/mobx-state-tree").IType<string | undefined, string, string>;
@@ -12,6 +17,13 @@ declare const TimeTraveller: import("@jbrowse/mobx-state-tree").IModelType<{
     resumeTrackingUndo(): void;
     addUndoState(snapshot: unknown): void;
     beforeDestroy(): void;
+    /**
+     * Start recording history for the target store. Re-runs whenever the root
+     * swaps in a new session node, so it must be idempotent: the previous
+     * registration is disposed and the history reset, because `history` is
+     * volatile while `undoIdx` is a persisted prop — carrying the old
+     * session's snapshots forward would make undo apply them to the new one.
+     */
     initialize(): void;
     undo(): void;
     redo(): void;