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

package/esm/util/addRelativeUris.js

@@ -1,9 +1,14 @@
 /**
- * Stamp `baseUri` next to every `uri` in a config so relative URIs resolve
- * against the location the config itself was loaded from. jbrowse-web runs this
- * when it fetches a config.json from a URL; anything that injects a fetched
- * config as an object (a hub, a track hub connection, a headless render) has to
- * run it too, or the config's relative data URIs resolve against the page.
+ * Stamp `baseUri` next to every `uri` in a config, and beside a MultiWiggle
+ * `bigWigs` array of bare URI strings, so relative URIs resolve against the
+ * location the config itself was loaded from. A file written as a bare string
+ * where a location object can go (a search index, `refNameAliases`,
+ * `cytobands`, a `bedLocations` entry) has no object to stamp, so it becomes
+ * `{ uri, baseUri }`.
+ * jbrowse-web runs this when it fetches a config.json from a URL; anything that
+ * injects a fetched config as an object (a hub, a track hub connection, a
+ * headless render) has to run it too, or the config's relative data URIs
+ * resolve against the page.
  *
  * Lives in core because core is what consumes the result — the assembly config
  * schema and expandAssemblyConfigShorthand read `baseUri` back out.
@@ -11,16 +16,47 @@
 export function addRelativeUris(config, base) {
     if (typeof config === 'object' && config !== null) {
         for (const key of Object.keys(config)) {
-            if (typeof config[key] === 'object' && config[key] !== null) {
-                addRelativeUris(config[key], base);
+            const value = liftBareFiles(key, config[key]);
+            if (value !== config[key]) {
+                config[key] = value;
             }
-            else if (key === 'uri') {
-                // fill only when absent, so a node carrying its own baseUri wins
-                config.baseUri = config.baseUri ?? base.href;
+            if (typeof value === 'object' && value !== null) {
+                addRelativeUris(value, base);
+            }
+            if (key === 'uri' || (key === 'bigWigs' && Array.isArray(value))) {
+                config.baseUri ??= base.href;
             }
         }
     }
 }
+// the keys whose value may be a file written as a bare string, which has no
+// object to carry a baseUri until it becomes `{ uri }`
+const FILE_KEYS = new Set(['textSearchAdapter', 'refNameAliases', 'cytobands']);
+const FILE_LIST_KEYS = new Set(['aggregateTextSearchAdapters', 'bedLocations']);
+function liftBareFiles(key, value) {
+    const lift = (file) => typeof file === 'string' ? { uri: file } : file;
+    return FILE_KEYS.has(key)
+        ? lift(value)
+        : FILE_LIST_KEYS.has(key) &&
+            Array.isArray(value) &&
+            value.some(file => typeof file === 'string')
+            ? value.map(lift)
+            : value;
+}
+/**
+ * A copy of `config` with every relative URI stamped against the page, which
+ * is what the page itself would resolve it against. An RPC worker started from
+ * a `blob:` URL has no such base, so a location it receives without one fails
+ * to parse there.
+ */
+export function withPageBaseUri(config) {
+    if (typeof document === 'undefined' || config === undefined) {
+        return config;
+    }
+    const copy = structuredClone(config);
+    addRelativeUris(copy, new URL(document.baseURI));
+    return copy;
+}
 /**
  * Inverse of {@link addRelativeUris}: recursively delete every synthetic
  * `baseUri` key (mutates in place), e.g. before serializing a config snapshot

package/esm/util/addTrackFromWidget.d.ts

@@ -82,13 +82,10 @@ export declare function addTrackFromWidget({ model, session, conf, }: {
         name?: string;
         assemblyNames?: (string | undefined)[];
     };
-}): (import("@jbrowse/mobx-state-tree").$EmptyObjectBrand & Partial<{
+}): import("../configuration/types.ts").AnyConfigurationModel | (import("@jbrowse/mobx-state-tree").$EmptyObjectBrand & Partial<{
     [x: string]: any;
 }> & {
     trackId: string;
     name?: string;
     assemblyNames?: (string | undefined)[];
-}) | (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
-    setSubschema(slotName: string, data: Record<string, unknown>): any;
-    setSlot(slotName: string, value: unknown): void;
-} & IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>) | undefined;
+}) | undefined;

package/esm/util/addTrackFromWidget.js

@@ -1,3 +1,4 @@
+import { coarseStripHTML } from './coarseStripHTML.js';
 import { namesTemporaryAssembly } from './temporaryAssembly.js';
 import { isSameAssemblyName } from './tracks.js';
 import { isSessionModelWithWidgets, isSessionWithPublishTrackConf, } from './types/index.js';
@@ -65,10 +66,10 @@ export function addTrackFromWidget({ model, session, conf, }) {
     const { trackContainer } = model;
     if (namesTemporaryAssembly(session, conf)) {
         if (!trackContainer) {
-            session.notify(`Could not add "${conf.name ?? conf.trackId}": the view it was being added to has closed, and it uses an assembly that only that view had.`, 'warning');
+            session.notify(`Could not add "${coarseStripHTML(conf.name ?? conf.trackId)}": the view it was being added to has closed, and it uses an assembly that only that view had.`, 'warning');
             return undefined;
         }
-        trackContainer.showTrack(conf.trackId, {}, {}, conf);
+        void trackContainer.launchTrack(conf.trackId, {}, {}, conf);
         finishAddTrack(model, session);
         return conf;
     }
@@ -77,11 +78,11 @@ export function addTrackFromWidget({ model, session, conf, }) {
         return undefined;
     }
     if (containerDisplaysAssembly(trackContainer, conf.assemblyNames, session.assemblyManager)) {
-        trackContainer?.showTrack(conf.trackId);
+        void trackContainer?.launchTrack(conf.trackId);
     }
     else {
         const assemblies = conf.assemblyNames?.filter(a => !!a) ?? [];
-        session.notify(`Added track "${conf.name ?? conf.trackId}" to the session, but it was not displayed because it uses ${assemblies.length
+        session.notify(`Added track "${coarseStripHTML(conf.name ?? conf.trackId)}" to the session, but it was not displayed because it uses ${assemblies.length
             ? `assembly "${assemblies.join('", "')}"`
             : 'an assembly'}, which is not open in this view. Open a view for that assembly and use its track selector to display it.`, 'warning');
     }

package/esm/util/aggregateFieldName.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The field an aggregate op writes: `as` where named, else `count` for a
+ * count, else `<op>_<field>`. Imports nothing, so the validator's copy of the
+ * mark rule list carries it unchanged.
+ */
+export declare function aggregateFieldName({ op, field, as, }: {
+    op: string;
+    field?: string;
+    as?: string;
+}): string;

package/esm/util/aggregateFieldName.js

@@ -0,0 +1,8 @@
+/**
+ * The field an aggregate op writes: `as` where named, else `count` for a
+ * count, else `<op>_<field>`. Imports nothing, so the validator's copy of the
+ * mark rule list carries it unchanged.
+ */
+export function aggregateFieldName({ op, field, as, }) {
+    return as || (op === 'count' || !field ? op : `${op}_${field}`);
+}

package/esm/util/analytics.js

@@ -9,11 +9,10 @@ export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuer
     try {
         const url = 'https://analytics.jbrowse.org/api/v1';
         const multiAssemblyTracks = rootModel.jbrowse.tracks.filter(track => readConfObject(track, 'assemblyNames').length > 1).length;
-        // which rendering backend is actually drawing (WebGPU/WebGL2/Canvas2D) —
-        // capabilities *and* any page-wide pin, so a session that fell back to
-        // Canvas2D is counted as Canvas2D rather than as what the hardware could
-        // have done. Reporting the capability answer here is what made "how many
-        // users end up on Canvas2D" unanswerable.
+        // The rung createGpuHal built where a display has built one by idle time,
+        // else the ladder's prediction with any page-wide pin applied — so a
+        // session that fell back to Canvas2D is counted as Canvas2D rather than as
+        // what the hardware could have done.
         const capabilities = await getGraphicsCapabilities();
         const renderer = effectiveRenderer(capabilities);
         // The coarse bit only. `glRenderer` names the exact driver and stays local
@@ -120,14 +119,48 @@ export function doAnalytics(rootModel, initialTimestamp, initialSessionQuery) {
         !analyticsSent &&
         !readConfObject(rootModel.jbrowse.configuration, 'disableAnalytics')) {
         analyticsSent = true;
-        // Defer off the critical load path: writeGAAnalytics injects a third-party
-        // Google Analytics script and writeAWSAnalytics probes graphics
-        // capabilities, together ~hundreds of ms of main-thread work at startup.
-        // loadTime is still measured from initialTimestamp, so the reported metric
-        // is unaffected by running these when the browser is idle.
-        rIC(() => {
-            void writeAWSAnalytics(rootModel, initialTimestamp, initialSessionQuery);
-            void writeGAAnalytics(rootModel, initialTimestamp);
+        // writeGAAnalytics injects Google's scripts and writeAWSAnalytics probes
+        // graphics capabilities, hundreds of ms of main-thread work together. Idle
+        // time alone is not late enough: a load spends most of its time idle,
+        // waiting on the network, so rIC ran them mid-boot. The writers measure
+        // loadTime up to when they run, so the start they get is moved forward by
+        // the wait, and loadTime still ends here.
+        const calledAt = Date.now();
+        afterAppReady(() => {
+            rIC(() => {
+                const start = initialTimestamp + (Date.now() - calledAt);
+                void writeAWSAnalytics(rootModel, start, initialSessionQuery);
+                void writeGAAnalytics(rootModel, start);
+            });
         });
     }
 }
+// `[data-app-phase="ready"]`, or a timeout for a page that never shows one
+// (Desktop's start screen)
+function afterAppReady(callback, maxWaitMs = 10_000) {
+    const isReady = () => document.querySelector('[data-app-phase="ready"]') !== null;
+    if (isReady()) {
+        callback();
+        return;
+    }
+    let done = false;
+    const finish = () => {
+        if (!done) {
+            done = true;
+            observer.disconnect();
+            clearTimeout(timer);
+            callback();
+        }
+    };
+    const observer = new MutationObserver(() => {
+        if (isReady()) {
+            finish();
+        }
+    });
+    const timer = setTimeout(finish, maxWaitMs);
+    observer.observe(document.body, {
+        subtree: true,
+        childList: true,
+        attributeFilter: ['data-app-phase'],
+    });
+}

package/esm/util/animationAllowed.d.ts

@@ -15,3 +15,12 @@ import type { AnimationMode } from './types/index.ts';
  * honors it.
  */
 export declare function animationAllowed(mode: AnimationMode): boolean;
+/** how long a layout morph takes from where it drew to where it now draws */
+export declare const MORPH_DURATION_MS = 300;
+export declare function easeInOutCubic(t: number): number;
+/**
+ * The wall clock a morph is timed on. Falls back to the epoch clock rather than
+ * a constant where `performance` is missing: a clock that never advances
+ * leaves a frame loop at progress 0 forever.
+ */
+export declare function morphClockMs(): number;

package/esm/util/animationAllowed.js

@@ -20,3 +20,16 @@ export function animationAllowed(mode) {
     return (hasFrameClock &&
         (mode === 'enabled' || (mode === 'system' && !prefersReduced)));
 }
+/** how long a layout morph takes from where it drew to where it now draws */
+export const MORPH_DURATION_MS = 300;
+export function easeInOutCubic(t) {
+    return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+}
+/**
+ * The wall clock a morph is timed on. Falls back to the epoch clock rather than
+ * a constant where `performance` is missing: a clock that never advances
+ * leaves a frame loop at progress 0 forever.
+ */
+export function morphClockMs() {
+    return typeof performance === 'undefined' ? Date.now() : performance.now();
+}

package/esm/util/applyRowResizeWheel.d.ts

@@ -1,10 +1,15 @@
-interface RowResizeTarget {
+import type { VirtualScrollModel } from './useVirtualScrollWheel.ts';
+export interface RowResizeTarget extends VirtualScrollModel {
+    /** resolved, never the 0/fit sentinel — this is divided by */
     effectiveRowHeight: number;
-    scrollTop: number;
     nrow: number;
-    viewportHeight: number;
     setRowHeight: (n: number) => void;
-    setScrollTop: (n: number) => void;
 }
+/**
+ * shift+wheel over a row stack: resize the rows, pinning the row under the
+ * cursor. The floor is the fit height, so rows never shrink past filling the
+ * viewport. The cap stops a gesture but never moves rows on its own, so it
+ * rises to a current height already above it (a pinned `rowHeight` is
+ * unbounded).
+ */
 export declare function applyRowResizeWheel(e: WheelEvent, el: HTMLElement, model: RowResizeTarget): void;
-export {};

package/esm/util/applyRowResizeWheel.js

@@ -1,30 +1,19 @@
-// shift+wheel resizes the sample rows (a vertical-zoom gesture) rather than
-// scrolling, keeping the row under the cursor pinned in place as the height
-// changes. Shared by every row-stack display — both variant displays and MAF —
-// so the gesture stays identical wherever rows have a resolved height and a
-// scroll offset. setScrollTop clamps to the new scrollableHeight, so the raw
-// target is passed through unclamped.
 import { normalizeWheelDelta } from './wheelZoom.js';
 const MAX_ROW_HEIGHT = 20;
-// px of row-height change per pixel of normalized wheel scroll. A mouse notch
-// (~100px) nudges the height ~0.4px; a trackpad's small continuous deltas
-// accumulate smoothly instead of the old sign-based ±1-per-event, which flew
-// through the whole range on a trackpad's event flood.
+// A mouse notch (~100px) nudges the height ~0.4px, and a trackpad's small
+// deltas accumulate smoothly rather than flying through the range.
 const RESIZE_PX_PER_WHEEL_PX = 1 / 240;
+/**
+ * shift+wheel over a row stack: resize the rows, pinning the row under the
+ * cursor. The floor is the fit height, so rows never shrink past filling the
+ * viewport. The cap stops a gesture but never moves rows on its own, so it
+ * rises to a current height already above it (a pinned `rowHeight` is
+ * unbounded).
+ */
 export function applyRowResizeWheel(e, el, model) {
     e.preventDefault();
-    // scroll up (deltaY < 0) grows rows; proportional to the normalized delta so
-    // the speed is consistent across mice/trackpads and finer than ±1/event.
     const delta = -normalizeWheelDelta(e.deltaY, e.deltaMode) * RESIZE_PX_PER_WHEEL_PX;
-    // guard nrow=0 (no samples) so the auto-fit floor stays finite
-    const minRowHeight = model.viewportHeight / Math.max(1, model.nrow);
-    // The cap may stop the gesture going further; it may never move the rows on
-    // its own. So both heights that can already sit above MAX_ROW_HEIGHT raise
-    // it: the auto-fit floor (few samples), and the current height (a pinned
-    // `rowHeight` — the config slot and the "Custom..." dialog are both
-    // unbounded, and MAF's own docs example is 12 while a bases-mode row wants
-    // more). Without the second, a 40px pinned row met `min(20, 40.4)` on the
-    // first notch of a *grow* gesture and halved.
+    const minRowHeight = model.scrollViewportHeight / Math.max(1, model.nrow);
     const maxRowHeight = Math.max(MAX_ROW_HEIGHT, minRowHeight, model.effectiveRowHeight);
     const newRowHeight = Math.max(minRowHeight, Math.min(maxRowHeight, model.effectiveRowHeight + delta));
     const mouseY = e.clientY - el.getBoundingClientRect().top;

package/esm/util/bandHeight.d.ts

@@ -51,3 +51,13 @@ export declare function boundBandHeight(n: number, { min, max }?: BandBounds): n
  *   display height so the plot below cannot be squashed to nothing
  */
 export declare function clampBandHeight(current: number, target: number, bounds?: BandBounds): number;
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export declare function scaleBandHeights(heights: number[], distance: number, floor?: number): number[];

package/esm/util/bandHeight.js

@@ -54,3 +54,32 @@ export function clampBandHeight(current, target, bounds = {}) {
     const { min = MIN_BAND_HEIGHT } = bounds;
     return boundBandHeight(target, { ...bounds, min: Math.min(min, current) });
 }
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export function scaleBandHeights(heights, distance, floor = MIN_BAND_HEIGHT) {
+    const floors = heights.map(h => Math.min(h, floor));
+    const room = heights.map((h, i) => h - floors[i]);
+    const roomTotal = room.reduce((a, b) => a + b, 0);
+    const target = Math.max(0, Math.round(roomTotal + distance));
+    const exact = room.map(r => roomTotal > 0 ? (r * target) / roomTotal : target / heights.length);
+    const whole = exact.map(e => Math.floor(e));
+    let left = target - whole.reduce((a, b) => a + b, 0);
+    const byRemainder = exact
+        .map((e, i) => ({ i, frac: e - whole[i] }))
+        .sort((a, b) => b.frac - a.frac);
+    for (const { i } of byRemainder) {
+        if (left <= 0) {
+            break;
+        }
+        whole[i] = whole[i] + 1;
+        left -= 1;
+    }
+    return whole.map((w, i) => w + floors[i]);
+}

package/esm/util/bandLayout.d.ts

@@ -39,11 +39,11 @@ export interface BandStack<K extends string> {
 /**
  * #api core/util
  * Fold an ordered set of bands into tops and a bottom. The order is the
- * argument, so a display states its band order exactly once; reserve, paint
- * and pick all read the same fold, which is what keeps "the reserver and the
- * painter read one function" true by construction rather than by prose.
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
  *
- * Only the fold is shared. What varies per display stays there: per-lane
+ * Only the fold is shared; the rest stays in each display. Per-lane
  * iteration runs this once per lane, sticky-vs-scrolling is a property of how
  * the result is projected to the screen, and a band drawn outside its
  * reservation (an overlay) carries its own draw rect beside the stack.

package/esm/util/bandLayout.js

@@ -14,11 +14,11 @@ export function reservedPx(band) {
 /**
  * #api core/util
  * Fold an ordered set of bands into tops and a bottom. The order is the
- * argument, so a display states its band order exactly once; reserve, paint
- * and pick all read the same fold, which is what keeps "the reserver and the
- * painter read one function" true by construction rather than by prose.
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
  *
- * Only the fold is shared. What varies per display stays there: per-lane
+ * Only the fold is shared; the rest stays in each display. Per-lane
  * iteration runs this once per lane, sticky-vs-scrolling is a property of how
  * the result is projected to the screen, and a band drawn outside its
  * reservation (an overlay) carries its own draw rect beside the stack.

package/esm/util/baseDisplayConfig.d.ts

@@ -0,0 +1,8 @@
+/**
+ * #api core/util
+ * The base's entry for this display, hydrated, which a reset returns to and
+ * "is this the reader's" compares against: the config.json's, or the one a
+ * track the session owns was added with; empty in a session that keeps no
+ * base.
+ */
+export declare function baseDisplayConfig(self: object): Record<string, unknown>;

package/esm/util/baseDisplayConfig.js

@@ -0,0 +1,27 @@
+import { hasParent } from '@jbrowse/mobx-state-tree';
+import { getConf } from '../configuration/getConf.js';
+import { getContainingTrack, getSession } from './mstUtils.js';
+import { isSessionWithBaseTrackConfig } from './types/index.js';
+/**
+ * #api core/util
+ * The base's entry for this display, hydrated, which a reset returns to and
+ * "is this the reader's" compares against: the config.json's, or the one a
+ * track the session owns was added with; empty in a session that keeps no
+ * base.
+ */
+export function baseDisplayConfig(self) {
+    if (!hasParent(self)) {
+        return {};
+    }
+    const session = getSession(self);
+    if (!isSessionWithBaseTrackConfig(session)) {
+        return {};
+    }
+    const base = session.baseTrackConfig(getConf(getContainingTrack(self), 'trackId'));
+    const { displayId } = self
+        .configuration;
+    const displays = base?.displays;
+    return ((Array.isArray(displays)
+        ? displays.find(d => d.displayId === displayId)
+        : undefined) ?? {});
+}

package/esm/util/bezierConnector.d.ts

@@ -1,5 +1,6 @@
-export declare const BEZIER_CONNECTOR_MAX_REACH_PX: number;
-export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dip, }: {
+export declare const CUBIC_APEX_RATIO = 0.75;
+export declare const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
+export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dipPx, }: {
     x1: number;
     y1: number;
     x2: number;
@@ -10,5 +11,5 @@ export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd
     reversed1?: boolean;
     reversed2?: boolean;
     maxHandlePx?: number;
-    dip?: boolean;
+    dipPx?: number;
 }): string;

package/esm/util/bezierConnector.js

@@ -19,43 +19,38 @@ const SPAN_FACTOR = 0.3;
 // its leading end: unbounded, that hook grows with the arc, and a full-width
 // inversion flings a ~500px curl back across unrelated reads.
 const MAX_HANDLE_PX = 200;
+// A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
+// control points, so an arc asked to reach a given apex puts its controls 4/3
+// past it. Exported because the sashimi overlay solves the same equation in the
+// other direction, and the two spellings drifting apart would put the insert-
+// size ruler's labels at heights nothing plots at.
+export const CUBIC_APEX_RATIO = 0.75;
 // Vertical bow applied to a connection whose two endpoints share (or nearly
 // share) a row — e.g. a chain whose split segments are all laid out on one
 // pileup row. Without it the horizontal-only handles collapse the cubic to a
 // flat, invisible line lying on the row; the bow lifts the control points so
 // the curve arcs into a visible hump. This is the control-point lift, not the
-// height the curve reaches: a cubic with both control points lifted by `bow`
-// apexes at 0.75 * bow.
+// height the curve reaches.
 const MAX_BOW_PX = 30;
 // A discordant connection bows *down* instead of up, so the two classes read
 // apart at a glance. Both renderers follow this: BreakpointSplitView dips its
-// same-level discordant links, and the pileup overlay dips every curve it draws
-// (its normal-orientation pairs are plain lines, so a curve there is always
-// discordant). Keep it that way — a renderer that opts out makes "below the
-// reads" mean two different things in two views of the same data.
+// same-level discordant links, and the pileup overlay dips every discordant
+// curve it draws (a normal-orientation pair is a plain line, or bows up over its
+// row where a hidden-segment one would lie on a chain's connecting line). Keep
+// it that way — a renderer that opts out makes "below the reads" mean two
+// different things in two views of the same data.
 //
-// Depth comes from the connection's own horizontal span
-// rather than reaching for some fixed row: with "view as pairs" / "link
-// supplementary alignments" every qname lands on one row, so dipping to a
-// shared row bottoms every curve out at the same depth and they collapse into
-// spaghetti. Keying on span makes the depth mean something — wide events dive
-// deeper than narrow ones — and lets the curves nest.
-//
-// Depth saturates toward MAX_DIP_PX rather than clamping at it. A hard cap
-// reintroduces exactly the problem being fixed: every connection wider than the
-// cap point bottoms out at an identical depth, and at any plausible cap a
-// typical view is mostly wider. This form stays strictly increasing in span at
-// every width while staying bounded. DIP_HALF_SPAN_PX is the span at which the
-// dip reaches half its maximum.
-const MAX_DIP_PX = 110;
-const DIP_HALF_SPAN_PX = 500;
-// How far a curve can stray outside the band between its two endpoints. A cubic
-// with both control points offset by `d` apexes at 0.75 * d, and the dip — the
-// deeper of the two shaping terms — saturates toward MAX_DIP_PX, so this bounds
-// both. A caller that culls off-screen curves has to pad its viewport test by
-// this: the shaping is applied to the *control points*, so a curve whose two
+// HOW DEEP is the renderer's call, not this file's. Depth is the mark's one free
+// channel, and only the renderer knows the band the ink has to survive in — the
+// pileup clips each section at its band bottom, and the split view bleeds a
+// too-deep dip into the panel below. So callers pass the depth they want and
+// `discordantDipPx` (@jbrowse/sv-core) is the law the two of them share.
+// How far a curve can stray outside the band between its two endpoints. The dip
+// is the deeper of the two shaping terms, so this is a ceiling on it, applied
+// here rather than trusted to a caller: a culler pads its viewport test by this,
+// and the shaping is applied to the *control points*, so a curve whose two
 // endpoints both sit just outside the viewport can still have a visible body.
-export const BEZIER_CONNECTOR_MAX_REACH_PX = 0.75 * MAX_DIP_PX;
+export const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
 // Sign (+1/-1) of an endpoint's horizontal control handle. The handle leaves a
 // trailing (3') endpoint along the read's reading direction (`strand`); at a
 // split junction's leading (5') endpoint it flips, so the curve arrives flowing
@@ -75,19 +70,6 @@ function shapingBudget(p1, p2) {
 function bowHeight(p1, p2, budget) {
     return Math.min(budget, Math.max(0, MAX_BOW_PX - Math.abs(p2.y - p1.y)));
 }
-// Negative = the control points drop below the reads (see MAX_DIP_PX). Keyed on
-// horizontal span alone: two reads a few px apart describe a small event and get
-// a small dip, however tall their track happens to be.
-//
-// Budget-clamped like the bow. At the current tuning the saturating curve
-// already resolves under the budget at every span (worst ratio ~0.73, as span
-// → 0), so this is inert — it's here so retuning MAX_DIP_PX / DIP_HALF_SPAN_PX
-// can't silently reintroduce the fold-back squiggle SPAN_FACTOR exists to
-// prevent. Pinned by 'the dip never outgrows its shaping budget'.
-function dipHeight(p1, p2, budget) {
-    const span = Math.abs(p2.x - p1.x);
-    return -Math.min(budget, MAX_DIP_PX * (span / (span + DIP_HALF_SPAN_PX)));
-}
 function cubicPath(from, ctrl1, ctrl2, to) {
     return `M ${from.x} ${from.y} C ${ctrl1.x} ${ctrl1.y} ${ctrl2.x} ${ctrl2.y} ${to.x} ${to.y}`;
 }
@@ -95,14 +77,25 @@ export function bezierConnectorPath({ x1, y1, x2, y2, s1, s2,
 // The second endpoint is a split junction's 5' leading edge (its handle flips
 // to fold the curve into the next segment); false for a paired mate's 3' edge.
 leadingEnd2 = false, reversed1 = false, reversed2 = false, maxHandlePx = MAX_HANDLE_PX, 
-// This connection is discordant (aberrant pair orientation, or a split
-// junction's strand flip): it dips below the reads instead of arcing over
-// them, so the two classes are tellable apart by shape alone.
-dip = false, }) {
+// Depth, in px, of the dip a discordant connection draws instead of the bow a
+// concordant one gets — aberrant pair orientation, or a split junction's
+// strand flip, so the two classes are tellable apart by shape alone. It is
+// the depth of the curve's APEX — what a caller can bound by the room it has —
+// and CUBIC_APEX_RATIO converts it to the control-point drop that puts the ink
+// there. Leave it out to bow up.
+dipPx, }) {
     const from = { x: x1, y: y1 };
     const to = { x: x2, y: y2 };
     const budget = shapingBudget(from, to);
     const handle = Math.min(maxHandlePx, budget);
-    const bow = dip ? dipHeight(from, to, budget) : bowHeight(from, to, budget);
+    // The dip is deliberately not clamped to the budget, unlike the bow. The
+    // budget stops the cubic folding back over itself, and only the horizontal
+    // handles can do that — a vertical offset leaves x(t) monotonic however deep
+    // it goes, so a big event squeezed into a few px draws a narrow trough rather
+    // than a squiggle. Pinned by 'a dipped connection never overshoots its
+    // endpoints in x'.
+    const bow = dipPx === undefined
+        ? bowHeight(from, to, budget)
+        : -Math.min(dipPx, BEZIER_CONNECTOR_MAX_REACH_PX) / CUBIC_APEX_RATIO;
     return cubicPath(from, { x: x1 + handle * tangentSign(s1, false, reversed1), y: y1 - bow }, { x: x2 + handle * tangentSign(s2, leadingEnd2, reversed2), y: y2 - bow }, to);
 }