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

package/esm/LinearGenomeView/components/useSearchBoxPrefs.js

@@ -0,0 +1,58 @@
+import { useLocalStorage } from '@jbrowse/core/util/hooks';
+/**
+ * Visibility and orientation of the search-box strip a stacked-LGV header
+ * draws, persisted per regime (few vs many rows) rather than under one global
+ * key, so the "compact default" heuristic isn't permanently overridden by a
+ * choice made in a differently-sized view.
+ *
+ * `prefix` keys the storage per container — the comparative view and the
+ * breakpoint split view remember their own. Everything else is shared, because
+ * the two headers held a copy each and the copies carried a comment telling the
+ * next editor to change the labels in both. They already import
+ * `HeaderSearchBoxRow` from this plugin, so the shared home costs no new
+ * dependency edge.
+ */
+export function useSearchBoxPrefs(prefix, numViews) {
+    const compact = numViews <= 3;
+    const regime = compact ? 'compact' : 'large';
+    const [showSearchBoxes, setShowSearchBoxes] = useLocalStorage(`${prefix}-showSearchBoxes-${regime}`, compact);
+    const [sideBySide, setSideBySide] = useLocalStorage(`${prefix}-sideBySide-${regime}`, compact);
+    return { showSearchBoxes, setShowSearchBoxes, sideBySide, setSideBySide };
+}
+/**
+ * The menu rows that drive those prefs. "Stacked" rather than "Vertical": the
+ * two headers name the same state and had drifted apart on it once already.
+ */
+export function searchBoxMenuItems({ showSearchBoxes, setShowSearchBoxes, sideBySide, setSideBySide, }) {
+    return [
+        {
+            label: 'Show search boxes',
+            type: 'checkbox',
+            checked: showSearchBoxes,
+            onClick: () => {
+                setShowSearchBoxes(!showSearchBoxes);
+            },
+        },
+        {
+            label: 'Search box orientation',
+            subMenu: [
+                {
+                    label: 'Side-by-side',
+                    type: 'radio',
+                    checked: sideBySide,
+                    onClick: () => {
+                        setSideBySide(true);
+                    },
+                },
+                {
+                    label: 'Stacked',
+                    type: 'radio',
+                    checked: !sideBySide,
+                    onClick: () => {
+                        setSideBySide(false);
+                    },
+                },
+            ],
+        },
+    ];
+}

package/esm/LinearGenomeView/components/useSideScroll.d.ts

@@ -1,6 +1,20 @@
-import type React from 'react';
 import type { LinearGenomeViewModel } from '../index.ts';
+import type React from 'react';
+/**
+ * Drag to pan and pinch to zoom, on pointer events so a finger works the same
+ * as a mouse. A second finger turns a pan into a pinch: the spread between the
+ * two zooms about their midpoint, and moving the midpoint pans. Lifting either
+ * finger goes back to panning with the other.
+ *
+ * The host sets `touch-action` to leave the browser only the gestures this
+ * does not want (TracksContainer keeps vertical scroll); without it a touch
+ * drag is a page scroll and a pinch zooms the page, and no pointer stream
+ * arrives.
+ *
+ * The window listeners go on in the press handler itself rather than in an
+ * effect, so a release that lands before React commits still finds them.
+ */
 export declare function useSideScroll(model: LinearGenomeViewModel): {
-    mouseDown: (event: React.MouseEvent) => void;
-    mouseUp: (event: React.MouseEvent) => void;
+    pointerDown: (event: React.PointerEvent) => void;
+    clickCapture: (event: React.MouseEvent) => void;
 };

package/esm/LinearGenomeView/components/useSideScroll.js

@@ -1,57 +1,175 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useRef } from 'react';
+import { transaction } from 'mobx';
+// A press that travels further than this is a pan, and the click that ends it
+// is not a click. A hand that wobbles two pixels can still select something.
+const PAN_CLICK_THRESHOLD_PX = 4;
+// The pan publishes its state as attributes on the element the press landed in
+// (TracksContainer), so a track's own pointer handlers read it with `closest`
+// and nothing has to hand them a ref or a model field — the same marker shape
+// as `data-gesture-owner`. `data-pan-dragging` is present from press to
+// release; `data-pan-moved` is set once the press travels past the threshold
+// or becomes a pinch, and cleared by the next press, so it still answers for
+// the click that follows the release: `clickCapture` swallows that click
+// before any track sees it.
+const PAN_DRAGGING_ATTR = 'data-pan-dragging';
+const PAN_MOVED_ATTR = 'data-pan-moved';
+function preventDefault(event) {
+    event.preventDefault();
+}
+function pointOf(event) {
+    return { x: event.clientX, y: event.clientY };
+}
+/**
+ * Drag to pan and pinch to zoom, on pointer events so a finger works the same
+ * as a mouse. A second finger turns a pan into a pinch: the spread between the
+ * two zooms about their midpoint, and moving the midpoint pans. Lifting either
+ * finger goes back to panning with the other.
+ *
+ * The host sets `touch-action` to leave the browser only the gestures this
+ * does not want (TracksContainer keeps vertical scroll); without it a touch
+ * drag is a page scroll and a pinch zooms the page, and no pointer stream
+ * arrives.
+ *
+ * The window listeners go on in the press handler itself rather than in an
+ * effect, so a release that lands before React commits still finds them.
+ */
 export function useSideScroll(model) {
-    const [mouseDragging, setMouseDragging] = useState(false);
-    const scheduled = useRef(false);
-    const prevX = useRef(0);
-    useEffect(() => {
-        let cleanup = () => { };
-        function globalMouseMove(event) {
-            event.preventDefault();
-            const currX = event.clientX;
-            const distance = currX - prevX.current;
-            if (distance) {
-                if (!scheduled.current) {
-                    scheduled.current = true;
-                    window.requestAnimationFrame(() => {
-                        model.horizontalScroll(-distance);
-                        scheduled.current = false;
-                        prevX.current = event.clientX;
-                    });
+    const gestureRef = useRef(undefined);
+    useEffect(() => () => {
+        gestureRef.current?.cancel();
+    }, []);
+    function pointerDown(event) {
+        const host = event.currentTarget;
+        if (gestureRef.current) {
+            gestureRef.current.join(event);
+            return;
+        }
+        // Cleared for EVERY press, ahead of the returns below: the marker outlives
+        // the gesture that set it, and a stale true is what the next reader of
+        // this DOM contract would inherit.
+        host.removeAttribute(PAN_MOVED_ATTR);
+        if (event.shiftKey || event.button !== 0 || !event.isPrimary) {
+            return;
+        }
+        // a draggable element, a control that claimed the press (resize handles,
+        // the scalebar, a legend), or a button: `closest`, since the press usually
+        // lands on a child of the control
+        const target = event.target;
+        if (target.draggable ||
+            target.closest('[data-gesture-owner]') ||
+            target.closest('button')) {
+            return;
+        }
+        const left = host.getBoundingClientRect().left;
+        const startX = event.clientX;
+        // where each finger is now, and where it was when the view last moved
+        const pointers = new Map([[event.pointerId, pointOf(event)]]);
+        let applied = new Map(pointers);
+        let frame;
+        function flush() {
+            frame = undefined;
+            const [a, b] = [...pointers.keys()];
+            const curr1 = pointers.get(a);
+            const prev1 = applied.get(a);
+            if (b === undefined) {
+                if (curr1.x !== prev1.x) {
+                    model.horizontalScroll(prev1.x - curr1.x);
                 }
             }
-        }
-        function globalMouseUp() {
-            prevX.current = 0;
-            if (mouseDragging) {
-                setMouseDragging(false);
+            else {
+                const curr2 = pointers.get(b);
+                const prev2 = applied.get(b);
+                const prevSpread = Math.hypot(prev1.x - prev2.x, prev1.y - prev2.y);
+                const spread = Math.hypot(curr1.x - curr2.x, curr1.y - curr2.y);
+                const prevMid = (prev1.x + prev2.x) / 2;
+                const mid = (curr1.x + curr2.x) / 2;
+                transaction(() => {
+                    if (prevSpread > 0 && spread > 0) {
+                        model.zoomTo((model.bpPerPx * prevSpread) / spread, prevMid - left);
+                    }
+                    if (mid !== prevMid) {
+                        model.horizontalScroll(prevMid - mid);
+                    }
+                });
             }
+            applied = new Map(pointers);
         }
-        if (mouseDragging) {
-            window.addEventListener('mousemove', globalMouseMove, true);
-            window.addEventListener('mouseup', globalMouseUp, true);
-            cleanup = () => {
-                window.removeEventListener('mousemove', globalMouseMove, true);
-                window.removeEventListener('mouseup', globalMouseUp, true);
-            };
+        // Applies what is queued before the set of fingers changes, so the next
+        // frame measures from where every finger is now rather than jumping by the
+        // distance between them.
+        function settle() {
+            if (frame !== undefined) {
+                window.cancelAnimationFrame(frame);
+                flush();
+            }
         }
-        return cleanup;
-    }, [model, mouseDragging]);
-    function mouseDown(event) {
-        if (event.shiftKey) {
-            return;
+        function move(e) {
+            if (!pointers.has(e.pointerId)) {
+                return;
+            }
+            pointers.set(e.pointerId, pointOf(e));
+            if (Math.abs(e.clientX - startX) > PAN_CLICK_THRESHOLD_PX) {
+                host.setAttribute(PAN_MOVED_ATTR, '');
+            }
+            frame ??= window.requestAnimationFrame(flush);
         }
-        const target = event.target;
-        if (target.draggable || target.dataset.resizer) {
-            return;
+        function end(applyQueued) {
+            if (applyQueued) {
+                settle();
+            }
+            else if (frame !== undefined) {
+                window.cancelAnimationFrame(frame);
+            }
+            host.removeAttribute(PAN_DRAGGING_ATTR);
+            window.removeEventListener('pointermove', move, true);
+            window.removeEventListener('pointerup', release, true);
+            window.removeEventListener('pointercancel', release, true);
+            window.removeEventListener('selectstart', preventDefault, true);
+            gestureRef.current = undefined;
         }
-        if (event.button === 0) {
-            prevX.current = event.clientX;
-            setMouseDragging(true);
+        // pointercancel as well as pointerup: the browser cancels a touch it takes
+        // over as a vertical scroll, and the gesture would otherwise stay latched
+        function release(e) {
+            if (!pointers.has(e.pointerId)) {
+                return;
+            }
+            if (pointers.size > 1) {
+                settle();
+                pointers.delete(e.pointerId);
+                applied.delete(e.pointerId);
+            }
+            else {
+                end(true);
+            }
         }
+        host.setAttribute(PAN_DRAGGING_ATTR, '');
+        window.addEventListener('pointermove', move, true);
+        window.addEventListener('pointerup', release, true);
+        window.addEventListener('pointercancel', release, true);
+        window.addEventListener('selectstart', preventDefault, true);
+        gestureRef.current = {
+            join(e) {
+                if (e.pointerType !== 'touch' || pointers.size > 1) {
+                    return;
+                }
+                settle();
+                pointers.set(e.pointerId, pointOf(e));
+                applied = new Map(pointers);
+                host.setAttribute(PAN_MOVED_ATTR, '');
+                model.cancelZoomAnimation();
+            },
+            cancel() {
+                end(false);
+            },
+        };
     }
-    function mouseUp(event) {
-        event.preventDefault();
-        setMouseDragging(false);
+    // The browser fires `click` after a release on whatever the press and the
+    // release share, which over a track is its canvas, so a pan that ended on a
+    // gene would open that gene's details.
+    function clickCapture(event) {
+        if (event.currentTarget.hasAttribute(PAN_MOVED_ATTR)) {
+            event.stopPropagation();
+        }
     }
-    return { mouseDown, mouseUp };
+    return { pointerDown, clickCapture };
 }

package/esm/LinearGenomeView/components/util.d.ts

@@ -1,14 +1,32 @@
 import type { Assembly } from '@jbrowse/core/assemblyManager/assembly';
-export { fetchResults, splitLast } from '../../searchUtils.ts';
-export declare function getRelativeX(event: {
-    clientX: number;
-    target: EventTarget | null;
-}, element: HTMLElement | null): number;
+import type { ViewLayout } from '@jbrowse/core/util/Base1DUtils';
+export { getHighlightColor, highlightKey } from '@jbrowse/core/util/highlights';
+export declare const scalebarRefLabelProps: {
+    'data-scalebar-ref-label': string;
+};
+export declare function isOnScalebarRefLabel(target: EventTarget | null): boolean;
+export declare const elidedBlockStyles: {
+    readonly backgroundColor: '#999';
+    readonly backgroundImage: 'repeating-linear-gradient(90deg, transparent, transparent 1px, rgba(255,255,255,.5) 1px, rgba(255,255,255,.5) 3px)';
+};
+export type Cytoband = ReturnType<typeof getCytobands>[number];
 export declare function getCytobands(assembly: Assembly | undefined, refName: string): {
     refName: string;
     start: number;
     end: number;
     type: string;
-    name: any;
+    name: string | undefined;
 }[];
+/**
+ * The bp under a pixel of the overview strip. The strip spans the whole view,
+ * but the overview *layout* is laid out in the pixels after the chromosome-name
+ * gutter (cytobandOffset), so a press or hover on that gutter sits left of the
+ * layout's own origin. `pxToBp` extrapolates there rather than refusing, and
+ * every overview reader took it at face value: the hover and rubberband labels
+ * read out an impossible "ctgA:-12,345,678", and a click did nothing at all,
+ * silently, because `centerAt` cannot resolve a coordinate that is in no region.
+ * Clamping into the layout's own span makes all three name the genome's start,
+ * which is what the gutter is adjacent to.
+ */
+export declare function overviewPxToBp(overview: ViewLayout, px: number, cytobandOffset: number): import("@jbrowse/core/util/Base1DUtils").PxToBpResult;
 export declare function shouldSwapTracks(lastSwapY: number | undefined, currentY: number, movingDown: boolean): boolean;

package/esm/LinearGenomeView/components/util.js

@@ -1,17 +1,40 @@
-export { fetchResults, splitLast } from "../../searchUtils.js";
-export function getRelativeX(event, element) {
-    return event.clientX - (element?.getBoundingClientRect().left || 0);
+import { clamp } from '@jbrowse/core/util';
+import { pxToBp } from '@jbrowse/core/util/Base1DUtils';
+// getHighlightColor/highlightKey live in core so the dotplot highlight bands can
+// share the exact same color and React-key semantics
+export { getHighlightColor, highlightKey } from '@jbrowse/core/util/highlights';
+export const scalebarRefLabelProps = { 'data-scalebar-ref-label': '' };
+export function isOnScalebarRefLabel(target) {
+    return (target instanceof Element && !!target.closest('[data-scalebar-ref-label]'));
 }
+export const elidedBlockStyles = {
+    backgroundColor: '#999',
+    backgroundImage: 'repeating-linear-gradient(90deg, transparent, transparent 1px, rgba(255,255,255,.5) 1px, rgba(255,255,255,.5) 3px)',
+};
 export function getCytobands(assembly, refName) {
     return (assembly?.cytobands
         ?.map(f => ({
-        refName: assembly.getCanonicalRefName(f.get('refName')) || f.get('refName'),
+        refName: assembly.getCanonicalRefName2(f.get('refName')),
         start: f.get('start'),
         end: f.get('end'),
         type: f.get('gieStain'),
         name: f.get('name'),
     }))
-        .filter(f => f.refName === refName) || []);
+        .filter(f => f.refName === refName) ?? []);
+}
+/**
+ * The bp under a pixel of the overview strip. The strip spans the whole view,
+ * but the overview *layout* is laid out in the pixels after the chromosome-name
+ * gutter (cytobandOffset), so a press or hover on that gutter sits left of the
+ * layout's own origin. `pxToBp` extrapolates there rather than refusing, and
+ * every overview reader took it at face value: the hover and rubberband labels
+ * read out an impossible "ctgA:-12,345,678", and a click did nothing at all,
+ * silently, because `centerAt` cannot resolve a coordinate that is in no region.
+ * Clamping into the layout's own span makes all three name the genome's start,
+ * which is what the gutter is adjacent to.
+ */
+export function overviewPxToBp(overview, px, cytobandOffset) {
+    return pxToBp(overview, clamp(px - cytobandOffset, 0, overview.width - 1));
 }
 const MIN_DRAG_DISTANCE = 30;
 export function shouldSwapTracks(lastSwapY, currentY, movingDown) {

package/esm/LinearGenomeView/consts.d.ts

@@ -1,7 +1,14 @@
+export declare const MIN_BP_PER_PX: number;
+export declare const MINIMUM_BLOCK_WIDTH = 3;
+export declare const SHOW_ALL_REGIONS_FILL = 0.9;
 export declare const HEADER_BAR_HEIGHT = 48;
 export declare const HEADER_OVERVIEW_HEIGHT = 20;
 export declare const SCALE_BAR_HEIGHT = 17;
-export declare const RESIZE_HANDLE_HEIGHT = 3;
-export declare const INTER_REGION_PADDING_WIDTH = 2;
+export declare const SVG_SCALEBAR_CAP = 5;
+export declare const RESIZE_HANDLE_HEIGHT = 4;
+export declare const RESIZE_ALL_HANDLE_HEIGHT = 6;
+export declare const TRACK_TOP_GAP = 2;
+export declare const TRACK_OUTLINE_BORDER = 1;
+export declare const MINIMIZED_TRACK_HEIGHT = 20;
 export declare const SPACING = 7;
 export declare const WIDGET_HEIGHT = 32;

package/esm/LinearGenomeView/consts.js

@@ -1,7 +1,25 @@
+// most zoomed-in level: 50px per bp
+export const MIN_BP_PER_PX = 1 / 50;
+export const MINIMUM_BLOCK_WIDTH = 3;
+// fraction of the view width the whole genome fills at the most zoomed-out
+// level, leaving a 10% margin
+export const SHOW_ALL_REGIONS_FILL = 0.9;
 export const HEADER_BAR_HEIGHT = 48;
 export const HEADER_OVERVIEW_HEIGHT = 20;
 export const SCALE_BAR_HEIGHT = 17;
-export const RESIZE_HANDLE_HEIGHT = 3;
-export const INTER_REGION_PADDING_WIDTH = 2;
+// Half-height of the total-bp scalebar's end caps in the SVG export; also the
+// clearance the bar needs below the assembly label.
+export const SVG_SCALEBAR_CAP = 5;
+// The three pieces of chrome TrackContainer puts around a track's rendering
+// container. The model sums them to place a track without measuring the DOM, so
+// TrackContainer lays its Paper out from these same three and nothing else —
+// the previous spelling had the model on a 3 while the CSS rendered 2 + 1 + 4,
+// which put every model-derived track offset 5px per track above the pixels.
+// The track *label* is not among them: it is measured, see `trackLabelBand`.
+export const RESIZE_HANDLE_HEIGHT = 4;
+export const RESIZE_ALL_HANDLE_HEIGHT = 6;
+export const TRACK_TOP_GAP = 2;
+export const TRACK_OUTLINE_BORDER = 1;
+export const MINIMIZED_TRACK_HEIGHT = 20;
 export const SPACING = 7;
 export const WIDGET_HEIGHT = 32;

package/esm/LinearGenomeView/containingLgv.d.ts

@@ -0,0 +1,21 @@
+import type { LinearGenomeViewModel } from './model.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * The containing view as the linear genome view itself, for a display that
+ * needs `pxToBp`, `showTrack`, `navTo` or the view's own chrome settings.
+ *
+ * The twin of display-kit's `containingHost`, and deliberately not the same
+ * function: `RegionHost` is the region contract display-kit reads, and widening
+ * it to carry the LGV's own surface is how the display layer would come to
+ * depend on the view plugin. A display that wants the view names the view.
+ *
+ * A view that lays its displays along a strip of its own — the circular view's
+ * ring host — is answered here too, the way `containingHost` answers it: the
+ * strip carries the members a display reads to draw (`bpToPx`, `pxToBp`, the
+ * blocks), and a display drawn there that reaches for a member the strip has
+ * not is the display that stays off the circle.
+ *
+ * Components and structural helpers taking duck-typed model shapes keep calling
+ * `getContainingView` — the same carve-out `containingHost` documents.
+ */
+export declare function containingLgv(self: IStateTreeNode): LinearGenomeViewModel;

package/esm/LinearGenomeView/containingLgv.js

@@ -0,0 +1,23 @@
+import { getContainingView } from '@jbrowse/core/util';
+/**
+ * The containing view as the linear genome view itself, for a display that
+ * needs `pxToBp`, `showTrack`, `navTo` or the view's own chrome settings.
+ *
+ * The twin of display-kit's `containingHost`, and deliberately not the same
+ * function: `RegionHost` is the region contract display-kit reads, and widening
+ * it to carry the LGV's own surface is how the display layer would come to
+ * depend on the view plugin. A display that wants the view names the view.
+ *
+ * A view that lays its displays along a strip of its own — the circular view's
+ * ring host — is answered here too, the way `containingHost` answers it: the
+ * strip carries the members a display reads to draw (`bpToPx`, `pxToBp`, the
+ * blocks), and a display drawn there that reaches for a member the strip has
+ * not is the display that stays off the circle.
+ *
+ * Components and structural helpers taking duck-typed model shapes keep calling
+ * `getContainingView` — the same carve-out `containingHost` documents.
+ */
+export function containingLgv(self) {
+    const view = getContainingView(self);
+    return (view.regionHost ?? view);
+}

package/esm/LinearGenomeView/flyTo.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A window of the view's linearized bp space — the space `windowStartBp` is in,
+ * so a position here is invariant under zoom and a flight can be planned once
+ * for a path whose scale changes under it.
+ */
+export interface FlightViewport {
+    centerBp: number;
+    windowWidthBp: number;
+}
+export interface Flight {
+    durationMs: number;
+    /** the viewport at `t` in [0,1]; exactly the destination at t >= 1 */
+    at: (t: number) => FlightViewport;
+}
+/**
+ * The viewport path from `from` to `to`, and how long to spend on it.
+ *
+ * The path is equation (9) of the paper cited at the top of this file: it zooms
+ * out as it travels and back in as it arrives, along the geodesic that holds
+ * the *perceived* velocity constant, so the reader can follow the whole journey
+ * rather than watching one blurred smear.
+ *
+ * A STRAIGHT PAN IS NOT THE ALTERNATIVE, it is the thing this exists to avoid.
+ * The jump that wants animating here is a synteny row showing a whole assembly
+ * being sent to a mate on another chromosome: tens of megabases at a window of
+ * tens of kilobases, which is a thousand screens of travel. Panned at constant
+ * scale that is a thousand screens of unreadable streaking and no frame in
+ * which the reader is anywhere identifiable. Pulled back to where both ends fit
+ * and then dropped in, it is a picture of where they came from and where they
+ * landed.
+ *
+ * The zoomed-out apex is `w0 * cosh(r0)` — for a same-zoom hop, about the
+ * distance travelled — so the arc naturally tops out at "both endpoints on
+ * screen". A view whose `maxBpPerPx` is tighter than that simply clamps there
+ * and flies the middle of the path flat; nothing here has to know the limit,
+ * because the caller writes through `zoomTo` and reads back what it got.
+ */
+export declare function planFlight(from: FlightViewport, to: FlightViewport): Flight;

package/esm/LinearGenomeView/flyTo.js

@@ -0,0 +1,135 @@
+import { clamp } from '@jbrowse/core/util';
+// The paper's rho: how much the path is willing to zoom out to cover distance.
+// Their section 6 user experiment measured 1.42 (sd 0.47), and they note that
+// it "suggests that rho = sqrt(2) is possibly an optimal value" without being
+// able to say why; d3-interpolateZoom takes the same sqrt(2). Lower flattens
+// the arc into a pan, higher pulls further back and travels faster, and it is
+// the one knob to reach for if the zoomed-out apex ever proves too expensive to
+// fetch through.
+//
+// IT DOES NOT TODAY, and the arithmetic that says it should is worth
+// contradicting explicitly. A cross-chromosome flight over stacked whole
+// assemblies traces ~15 octaves of zoom out and ~15 back, and synteny's fetch
+// key buckets on `floor(log2(bpPerPx))` — so a flight crosses ~30 fetch buckets
+// where a pan at constant zoom crosses none. Measured against
+// `demos/grape_peach_cacao` it costs exactly ONE extra RPC over the instant
+// jump (2 against 1), because the 500ms leading-edge debounce absorbs the whole
+// excursion: one fetch leaving, one on landing.
+// `agent-docs/measurements/synteny-mate-flight.json`.
+const RHO = Math.sqrt(2);
+// WHERE WE PART COMPANY WITH THE PAPER, and the one number in here that is not
+// theirs. `S` is a path length in their dimensionless units of perceived
+// motion, growing with the LOG of the distance: half a screen scores 0.7, one
+// screen 1.2, a hundred screens 7.5, a whole genome 12. Their section 6
+// measured an animation speed V of 0.90 of those units per second, which would
+// put that whole-genome flight at THIRTEEN SECONDS — a wait, not a transition,
+// and their own scenario (a map of the US) never asks for a path that long.
+//
+// So the duration is clamped instead: a floor for the hops too short to need
+// time, a ceiling for the cross-genome one, and a rate between. At the ceiling
+// that is an effective V around 11, an order of magnitude above what they
+// measured, and it is the deliberate cost of not making the reader wait.
+// Perceived velocity is still constant WITHIN a flight — that is equation (9)'s
+// doing, not this — and this only picks the total.
+const MS_PER_UNIT = 90;
+const MIN_MS = 250;
+const MAX_MS = 1100;
+// Below this much motion, relative to the window it happens in, the pan is
+// treated as none at all. RELATIVE, not absolute: the general solution divides
+// by the distance, so a sub-bp move between two different zooms sends `b`
+// through infinity and `at` returns NaN — and an absolute epsilon that is small
+// against a 250Mb chromosome is not small against a 500bp window.
+const STATIONARY = 1e-6;
+/**
+ * The viewport path from `from` to `to`, and how long to spend on it.
+ *
+ * The path is equation (9) of the paper cited at the top of this file: it zooms
+ * out as it travels and back in as it arrives, along the geodesic that holds
+ * the *perceived* velocity constant, so the reader can follow the whole journey
+ * rather than watching one blurred smear.
+ *
+ * A STRAIGHT PAN IS NOT THE ALTERNATIVE, it is the thing this exists to avoid.
+ * The jump that wants animating here is a synteny row showing a whole assembly
+ * being sent to a mate on another chromosome: tens of megabases at a window of
+ * tens of kilobases, which is a thousand screens of travel. Panned at constant
+ * scale that is a thousand screens of unreadable streaking and no frame in
+ * which the reader is anywhere identifiable. Pulled back to where both ends fit
+ * and then dropped in, it is a picture of where they came from and where they
+ * landed.
+ *
+ * The zoomed-out apex is `w0 * cosh(r0)` — for a same-zoom hop, about the
+ * distance travelled — so the arc naturally tops out at "both endpoints on
+ * screen". A view whose `maxBpPerPx` is tighter than that simply clamps there
+ * and flies the middle of the path flat; nothing here has to know the limit,
+ * because the caller writes through `zoomTo` and reads back what it got.
+ */
+export function planFlight(from, to) {
+    const w0 = from.windowWidthBp;
+    const w1 = to.windowWidthBp;
+    const delta = to.centerBp - from.centerBp;
+    const dist = Math.abs(delta);
+    const at = dist > Math.max(w0, w1) * STATIONARY
+        ? zoomAndPan(from, to, dist, Math.sign(delta))
+        : zoomInPlace(from, to);
+    return {
+        durationMs: at ? clamp(at.S * MS_PER_UNIT, MIN_MS, MAX_MS) : 0,
+        // Snapped at the end rather than left to the closed form, whose `u(S)`
+        // reaches the destination only to within the rounding of two hyperbolics.
+        at: t => (at && t < 1 ? at.at(t) : to),
+    };
+}
+// Equation (9), term for term. `u` runs along the path in world units from the
+// start, and the two `r` are where the start and end sit on the ellipse the
+// path traces. The paper's `u1 - u0` is signed; here the caller's sign is
+// carried separately in `direction` and `dist` is its magnitude, so that u0 = 0
+// and the two forms agree.
+function zoomAndPan(from, to, dist, direction) {
+    const w0 = from.windowWidthBp;
+    const w1 = to.windowWidthBp;
+    const rho2 = RHO * RHO;
+    const rho4 = rho2 * rho2;
+    const b0 = (w1 * w1 - w0 * w0 + rho4 * dist * dist) / (2 * w0 * rho2 * dist);
+    const b1 = (w1 * w1 - w0 * w0 - rho4 * dist * dist) / (2 * w1 * rho2 * dist);
+    // asinh(-b), which is exactly the ln(-b + sqrt(b*b + 1)) equation (9) writes
+    // (and d3 implements literally) — but evaluated without the catastrophic
+    // cancellation those two terms suffer at the far end of a cross-genome jump,
+    // where b runs to a thousand and they agree to seven digits before
+    // subtracting. Same value, better conditioned.
+    const r0 = Math.asinh(-b0);
+    const r1 = Math.asinh(-b1);
+    const S = (r1 - r0) / RHO;
+    const coshR0 = Math.cosh(r0);
+    const sinhR0 = Math.sinh(r0);
+    return S > 0
+        ? {
+            S,
+            at: (t) => {
+                const s = t * S * RHO + r0;
+                return {
+                    centerBp: from.centerBp +
+                        direction *
+                            ((w0 / rho2) * coshR0 * Math.tanh(s) - (w0 / rho2) * sinhR0),
+                    windowWidthBp: (w0 * coshR0) / Math.cosh(s),
+                };
+            },
+        }
+        : undefined;
+}
+// The paper's u0 = u1 case, given unnumbered just after equation (9): the
+// endpoints are the same place at different scales, so there is no path to
+// trace and the zoom is exponential in `s` on its own. Their `w0 exp(k*rho*s)`
+// over `S = |ln(w1/w0)|/rho` is `w0 * ratio**t` here, which is the same curve
+// with `t = s/S` and their sign `k` folded into the ratio.
+function zoomInPlace(from, to) {
+    const ratio = to.windowWidthBp / from.windowWidthBp;
+    const S = Math.abs(Math.log(ratio)) / RHO;
+    return S > 0
+        ? {
+            S,
+            at: (t) => ({
+                centerBp: from.centerBp + (to.centerBp - from.centerBp) * t,
+                windowWidthBp: from.windowWidthBp * ratio ** t,
+            }),
+        }
+        : undefined;
+}