@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/ui/useMouseTracking.js

@@ -0,0 +1,179 @@
+import { createContext, use, useCallback, useEffect, useRef, useSyncExternalStore, } from 'react';
+// A box rather than a bare `let`, because oxlint narrows a closure-assigned
+// `let` to its initializer and then reads every use of it as always-undefined.
+function createMouseStore() {
+    const box = { state: undefined };
+    const subscribers = new Set();
+    return {
+        subscribe(onStoreChange) {
+            subscribers.add(onStoreChange);
+            return () => {
+                subscribers.delete(onStoreChange);
+            };
+        },
+        // Stable identity while nothing moves, which useSyncExternalStore requires:
+        // the state object is replaced only in `set`, never rebuilt per read.
+        getSnapshot() {
+            return box.state;
+        },
+        set(next) {
+            box.state = next;
+            for (const onStoreChange of subscribers) {
+                onStoreChange();
+            }
+        },
+    };
+}
+/**
+ * Drop the tracked pointer, published by whoever bound the handlers.
+ *
+ * `mouseleave` reports the pointer leaving an element, and the browser decides
+ * that by comparing the hover chain before a move to the chain after it. A menu
+ * portalled to the body opens under the cursor with no move at all, and closing
+ * it detaches the chain's nodes — so hover restarts at `body` and the display
+ * the menu covered is never told anything again. Its overlays then keep drawing
+ * at the coordinate the pointer had when the menu opened, wherever the pointer
+ * has since gone.
+ *
+ * `ContextMenu` calls this on close, which is why the default is a no-op: a menu
+ * raised outside a display's chrome has no tracked pointer to drop.
+ */
+const ClearTrackedPointerContext = createContext(() => { });
+export const ClearTrackedPointerProvider = ClearTrackedPointerContext.Provider;
+export function useClearTrackedPointer() {
+    return use(ClearTrackedPointerContext);
+}
+/**
+ * Container-relative mouse position for the overlays that follow the pointer
+ * (`Crosshairs`, tooltips), coalesced to one update per frame.
+ *
+ * The position is measured against the box of whatever element the handlers are
+ * bound to, which is what the overlays are positioned in — off `currentTarget`,
+ * so there is no ref to pass and no way to bind the two to different elements.
+ * A display that also hit-tests takes `onMove`, so its hit and its guides come
+ * off one measurement in one frame instead of two pointer paths that have to
+ * agree.
+ *
+ * **It returns a `mouseTracker` rather than the position, and that is the
+ * load-bearing part.** Its one caller is `DisplayChromeBase`, which owns the
+ * container the handlers bind to — so if the position were state here, every
+ * mouse move would re-render the chrome itself (re-running
+ * `useRenderingBackend`), the status container with a fresh inline `style`
+ * object, all three overlays, and only then the body that actually wanted the
+ * coordinate. That is a whole display's chrome repainting because the cursor
+ * moved a pixel over it; it cost a full document `Layout` plus three `Paint`s
+ * per mousemove on the wiggle displays, back when each display called this hook
+ * itself and every one of them had it.
+ *
+ * So the position is published instead, and whoever wants it calls
+ * `useMouseState(mouseTracker)` — from inside the chrome's body, where the
+ * overlays live. Re-rendering then starts at the component that reads it.
+ * Passing the tracker down a prop is free; passing `mouseState` down is the bug.
+ */
+export function useMouseTracking(onMove) {
+    const rafRef = useRef(undefined);
+    const storeRef = useRef(undefined);
+    storeRef.current ??= createMouseStore();
+    const store = storeRef.current;
+    // Reached through a ref rather than captured, so `handleMouseLeave` below can
+    // be identity-stable — one of its callers is an effect, and a handler that
+    // changed identity every render would make that effect re-run every render.
+    // Reading the latest is also the better answer for the frame callback, which
+    // runs after the render whose closure scheduled it.
+    //
+    // Written in an effect rather than during render: a render React discards must
+    // not leave this pointing at a callback from it. Nothing can read it before
+    // the first commit — both users are event/effect callbacks — and `useRef`'s
+    // initial value covers the first commit itself.
+    const onMoveRef = useRef(onMove);
+    useEffect(() => {
+        onMoveRef.current = onMove;
+    });
+    /**
+     * Drop the published position and tell `onMove` the pointer is gone.
+     *
+     * Bound as the container's `onMouseLeave` — and called directly for the two
+     * cases `mouseleave` cannot report: the container being *removed* rather than
+     * left, and a portalled menu closing over it. `DisplayChromeBase` makes both
+     * calls, the second by publishing this on `ClearTrackedPointerProvider`.
+     * Identity-stable for both.
+     */
+    const handleMouseLeave = useCallback(() => {
+        if (rafRef.current) {
+            cancelAnimationFrame(rafRef.current);
+            rafRef.current = undefined;
+        }
+        store.set(undefined);
+        onMoveRef.current?.(undefined);
+    }, [store]);
+    const handleMouseMove = (event) => {
+        // An overlay portaled out of the container still *bubbles* its React events
+        // here, even though its DOM node is not a descendant — so the coordinate
+        // would be measured against a box the pointer isn't in. HiC guarded this by
+        // hand (its resolution dropdown and legend portal); it is a hazard for any
+        // display with a portaled overlay, and several have one, so the guard lives
+        // here and applies to all of them. Treated as a leave: the pointer is over
+        // something else, and the guides should drop rather than freeze.
+        const { target } = event;
+        if (target instanceof Node && !event.currentTarget.contains(target)) {
+            handleMouseLeave();
+            return;
+        }
+        if (rafRef.current) {
+            cancelAnimationFrame(rafRef.current);
+        }
+        const clientX = event.clientX;
+        const clientY = event.clientY;
+        // Captured here rather than read in the frame: React clears `currentTarget`
+        // once the handler returns. `isConnected` then stands in for the ref check
+        // this used to do — a display unmounted between the move and the frame
+        // measures as a zero rect, and would publish the client point as if the
+        // pointer were at the origin of a box that is gone.
+        const container = event.currentTarget;
+        rafRef.current = requestAnimationFrame(() => {
+            if (container.isConnected) {
+                const rect = container.getBoundingClientRect();
+                const state = {
+                    x: clientX - rect.left,
+                    y: clientY - rect.top,
+                    clientX,
+                    clientY,
+                };
+                store.set(state);
+                onMoveRef.current?.(state);
+            }
+        });
+    };
+    return {
+        mouseTracker: store,
+        handleMouseMove,
+        handleMouseLeave,
+    };
+}
+const identity = (state) => state;
+const noopSubscribe = () => () => { };
+/**
+ * Read something derived from the tracked pointer, re-rendering only when the
+ * derived value changes.
+ *
+ * `useMouseState` renders once per frame the pointer moves, which is what a
+ * thing drawn *at* the cursor wants. A consumer that only asks a question of the
+ * position — "is the pointer inside this band?" — renders once per answer
+ * instead, because `useSyncExternalStore` compares snapshots and a boolean
+ * compares equal to the last one.
+ *
+ * The tracker is optional so a component can sit outside whatever bound the
+ * handlers (a highlight band rendered in a test, say) and read a pointer that is
+ * simply never there.
+ */
+export function useMouseSelector(tracker, selector) {
+    return useSyncExternalStore(tracker?.subscribe ?? noopSubscribe, () => selector(tracker?.getSnapshot()), () => selector(undefined));
+}
+/**
+ * Read the tracked pointer position. Call this in the component that draws the
+ * cursor-following thing, not in the one that bound the handlers — see
+ * `useMouseTracking`.
+ */
+export function useMouseState(tracker) {
+    return useMouseSelector(tracker, identity);
+}

package/esm/ui/useRecentLocations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A recorded row: what the menu shows, and what reopening it actually opens.
+ *
+ * The two are not the same string. A text-search hit's display string is built
+ * for reading — a snippet ellipsized to fit, or `name (matched attribute)` when
+ * the query hit something other than the name — and feeding it back to the
+ * search finds nothing, because those characters were never in the index. So a
+ * row that had a location carries it, and reopening parses that instead.
+ *
+ * `loc` is absent for a query the user typed and submitted freehand, which has
+ * no resolved location to record. That label _is_ searchable (it is what the
+ * user typed), so those rows are replayed through search as before.
+ */
+export interface RecentLocation {
+    label: string;
+    loc?: string;
+}
+/**
+ * Remembers the locations recently opened from the header search box or an
+ * import form, most-recent first and deduplicated, scoped per assembly (and per
+ * host/path/config like the remembered assembly). Without an assembly there is
+ * nothing to scope the key to, so the list stays in memory only.
+ */
+export declare function useRecentLocations(assemblyName?: string): {
+    recentLocations: RecentLocation[];
+    addRecentLocation: (entry: RecentLocation) => void;
+    clearRecentLocations: () => void;
+};

package/esm/ui/useRecentLocations.js

@@ -0,0 +1,31 @@
+import { useLocalStorage } from '../util/hooks.js';
+import { instanceScopedKey } from './useAssemblySelection.js';
+// keep the list short so it reads as "jump back to somewhere recent" rather
+// than a full history
+const MAX_RECENT_LOCATIONS = 6;
+function normalize(entry) {
+    return typeof entry === 'string' ? { label: entry } : entry;
+}
+// the same place reached two ways (by name, then by ID) is one row, so rows
+// that resolved to a location are identified by it rather than by their label
+function identity({ label, loc }) {
+    return loc ?? label;
+}
+/**
+ * Remembers the locations recently opened from the header search box or an
+ * import form, most-recent first and deduplicated, scoped per assembly (and per
+ * host/path/config like the remembered assembly). Without an assembly there is
+ * nothing to scope the key to, so the list stays in memory only.
+ */
+export function useRecentLocations(assemblyName) {
+    const [stored, setRecentLocations] = useLocalStorage(instanceScopedKey('recentLocations', assemblyName ?? ''), [], Boolean(assemblyName));
+    const recentLocations = stored.map(normalize);
+    function addRecentLocation(entry) {
+        const id = identity(entry);
+        setRecentLocations(prev => [entry, ...prev.map(normalize).filter(e => identity(e) !== id)].slice(0, MAX_RECENT_LOCATIONS));
+    }
+    function clearRecentLocations() {
+        setRecentLocations([]);
+    }
+    return { recentLocations, addRecentLocation, clearRecentLocations };
+}

package/esm/ui/wrapComponent.d.ts

@@ -0,0 +1,47 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ExtensionPointRegistry, PointsOfKind } from '../PluginManager.ts';
+import type { ComponentType } from 'react';
+/**
+ * The extension points that resolve to a single component — every point
+ * declared `ComponentSlot`. {@link PluggableComponent} is the producer side.
+ */
+export type SlotExtensionPointName = PointsOfKind<'componentSlot'>;
+/** The props the component in slot `N` is rendered with. */
+export type SlotProps<N extends SlotExtensionPointName> = ExtensionPointRegistry[N]['props'];
+export type WrapperProps<N extends SlotExtensionPointName> = SlotProps<N> & {
+    /**
+     * whatever fills the slot so far: the built-in default, or another plugin's
+     * wrapper. Render it where you want it to appear, or leave it out to take the
+     * slot over entirely
+     */
+    DefaultComponent: ComponentType<SlotProps<N>>;
+};
+/**
+ * Put `wrapper` around whatever currently fills a single-component slot. It
+ * receives the slot's props plus the component it wraps, so wrappers from
+ * several plugins nest rather than clobbering one another, and scoping is a
+ * plain conditional:
+ *
+ * ```tsx
+ * wrapComponent(pm, 'Core-replaceWidget', ({ DefaultComponent, ...props }) =>
+ *   matchesTrackSelector({ trackId: 'volvox.inv.vcf' }, props) ? (
+ *     <MyWidget {...props} />
+ *   ) : (
+ *     <DefaultComponent {...props} />
+ *   ),
+ * )
+ * ```
+ *
+ * Wrapping is the only operation these points have, because replacing is
+ * wrapping and not rendering what you were handed. Registering on the point
+ * directly does the same thing, minus the two halves this gets right:
+ *
+ * - the fold reruns on **every render** of the producer, so a wrapper declared
+ *   inside the callback is a new component type each time and React unmounts the
+ *   subtree, losing scroll position, form state and any open sub-panel. Here the
+ *   wrapped component is built once and cached per component wrapped.
+ * - a hand-written callback that forgets to hand back the accumulated component
+ *   on the tracks it does not want takes over the drawer, the modal and every
+ *   feature details panel.
+ */
+export declare function wrapComponent<N extends SlotExtensionPointName>(pluginManager: PluginManager, name: N, wrapper: ComponentType<WrapperProps<N>>): void;

package/esm/ui/wrapComponent.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { wrappedComponent } from '../PluginManager.js';
+/**
+ * Put `wrapper` around whatever currently fills a single-component slot. It
+ * receives the slot's props plus the component it wraps, so wrappers from
+ * several plugins nest rather than clobbering one another, and scoping is a
+ * plain conditional:
+ *
+ * ```tsx
+ * wrapComponent(pm, 'Core-replaceWidget', ({ DefaultComponent, ...props }) =>
+ *   matchesTrackSelector({ trackId: 'volvox.inv.vcf' }, props) ? (
+ *     <MyWidget {...props} />
+ *   ) : (
+ *     <DefaultComponent {...props} />
+ *   ),
+ * )
+ * ```
+ *
+ * Wrapping is the only operation these points have, because replacing is
+ * wrapping and not rendering what you were handed. Registering on the point
+ * directly does the same thing, minus the two halves this gets right:
+ *
+ * - the fold reruns on **every render** of the producer, so a wrapper declared
+ *   inside the callback is a new component type each time and React unmounts the
+ *   subtree, losing scroll position, form state and any open sub-panel. Here the
+ *   wrapped component is built once and cached per component wrapped.
+ * - a hand-written callback that forgets to hand back the accumulated component
+ *   on the tracks it does not want takes over the drawer, the modal and every
+ *   feature details panel.
+ */
+export function wrapComponent(pluginManager, name, wrapper) {
+    const Wrapper = wrapper;
+    const cache = new WeakMap();
+    pluginManager.addToExtensionPoint(name, (accumulated) => {
+        const Default = accumulated;
+        let built = cache.get(Default);
+        if (!built) {
+            const made = (slotProps) => {
+                // the literal is what checks the wrapper's props. The assertion is for
+                // JSX alone: it checks attributes against a type made entirely of
+                // optionals, and through `N` tsc cannot see this one has any property in
+                // common with it, so a plain spread reads as the weak-type mistake
+                const wrapperProps = {
+                    ...slotProps,
+                    DefaultComponent: Default,
+                };
+                return _jsx(Wrapper, { ...wrapperProps });
+            };
+            made.displayName = `${Wrapper.displayName ?? Wrapper.name}(${Default.displayName ?? Default.name})`;
+            // records what it wraps, so evaluateComponentExtensionPoint counts this
+            // as composition rather than as taking the slot
+            Object.defineProperty(made, wrappedComponent, { value: Default });
+            cache.set(Default, made);
+            built = made;
+        }
+        return built;
+    });
+}

package/esm/ui/zIndexes.d.ts

@@ -0,0 +1,28 @@
+/** Material UI's `zIndex.drawer`: above the app bar (1100), below a modal (1300). */
+export declare const DRAWER_Z_INDEX = 1200;
+/**
+ * Material UI's `zIndex.tooltip`, for chrome that must clear every Material
+ * surface without leaving that scale — the coordinate guide label, which is
+ * fixed-position and follows the cursor across the whole app.
+ */
+export declare const MUI_TOOLTIP_Z_INDEX = 1500;
+/**
+ * The button that brings a minimized drawer back (see AppFab). It floats over
+ * the views, so it has to clear the layers they stack inside themselves — the
+ * LGV's rubberband, its vertical guide and its coordinate labels run to ~1002 —
+ * and it is app chrome rather than a hover, so it stays below the two layers
+ * beneath.
+ */
+export declare const FAB_Z_INDEX = 10000;
+/**
+ * Hover tooltips (see BaseTooltip). Above the app chrome so a tooltip near a
+ * track edge isn't clipped by the drawer or the view's own overlays.
+ */
+export declare const TOOLTIP_Z_INDEX = 100000;
+/**
+ * Right-click menus (see ContextMenu). One above the tooltip: the menu is
+ * something the user just asked for, so nothing may cover it. Handlers still
+ * drop the hover when opening a menu — this is what keeps a tooltip that
+ * outlives that clear (a neighbouring display's, say) from landing on top.
+ */
+export declare const CONTEXT_MENU_Z_INDEX: number;

package/esm/ui/zIndexes.js

@@ -0,0 +1,38 @@
+// Stacking order, kept in one place so it is stated rather than inferred from
+// magic numbers spread across displays. Two groups, and the split matters.
+//
+// The first is Material UI's own scale, reproduced here rather than read off
+// `theme.zIndex`. `makeStyles` is handed JBrowse's plain-data style theme
+// (`styleTheme.ts`), which carries no `zIndex` — a layer belongs where the
+// layering is decided, not in a token bag every styled component drags around.
+// See `agent-docs/reference/EAGER_BUNDLE.md`.
+/** Material UI's `zIndex.drawer`: above the app bar (1100), below a modal (1300). */
+export const DRAWER_Z_INDEX = 1200;
+/**
+ * Material UI's `zIndex.tooltip`, for chrome that must clear every Material
+ * surface without leaving that scale — the coordinate guide label, which is
+ * fixed-position and follows the cursor across the whole app.
+ */
+export const MUI_TOOLTIP_Z_INDEX = 1500;
+// The second group is the floating layers that live above everything else. All
+// of them sit far above Material UI's scale, so they are not expressible on it.
+/**
+ * The button that brings a minimized drawer back (see AppFab). It floats over
+ * the views, so it has to clear the layers they stack inside themselves — the
+ * LGV's rubberband, its vertical guide and its coordinate labels run to ~1002 —
+ * and it is app chrome rather than a hover, so it stays below the two layers
+ * beneath.
+ */
+export const FAB_Z_INDEX = 10000;
+/**
+ * Hover tooltips (see BaseTooltip). Above the app chrome so a tooltip near a
+ * track edge isn't clipped by the drawer or the view's own overlays.
+ */
+export const TOOLTIP_Z_INDEX = 100000;
+/**
+ * Right-click menus (see ContextMenu). One above the tooltip: the menu is
+ * something the user just asked for, so nothing may cover it. Handlers still
+ * drop the hover when opening a menu — this is what keeps a tooltip that
+ * outlives that clear (a neighbouring display's, say) from landing on top.
+ */
+export const CONTEXT_MENU_Z_INDEX = TOOLTIP_Z_INDEX + 1;

package/esm/util/Base1DUtils.d.ts

@@ -1,4 +1,4 @@
-import type { ViewSnap } from './index.ts';
+import type { BaseBlock } from './blockTypes.ts';
 export interface BpOffset {
     refName?: string;
     index: number;
@@ -6,33 +6,221 @@ export interface BpOffset {
     start?: number;
     end?: number;
 }
-export declare function moveTo(self: ViewSnap & {
+/**
+ * Offset in bp from a displayed region's **left screen edge**, which is its end
+ * when the region is reversed. This one reflection is what "reversed" means
+ * everywhere in a linear view: `bpToPx` below, the ruler's ticks
+ * (`LinearGenomeView/util.ts`), and any display placing a feature against a
+ * single block. Reach for it instead of writing `pos - region.start`, which
+ * silently lays out forward under a right-to-left ruler.
+ */
+export declare function bpOffsetInRegion(region: {
+    start: number;
+    end: number;
+    reversed?: boolean;
+}, bp: number): number;
+interface RegionSnap {
+    start: number;
+    end: number;
+    refName: string;
+    reversed?: boolean;
+    assemblyName: string;
+}
+interface MoveSnap {
+    displayedRegions: {
+        start: number;
+        end: number;
+    }[];
+    width: number;
+}
+export interface ViewLayout {
+    displayedRegions: RegionSnap[];
+    bpPerPx: number;
+    offsetPx: number;
+    width: number;
+    minimumBlockWidth: number;
+}
+export declare function moveTo(self: MoveSnap & {
     zoomTo: (arg: number) => number;
     scrollTo: (arg: number) => void;
 }, start?: BpOffset, end?: BpOffset): void;
-export declare function pxToBp(self: ViewSnap, px: number): {
+/**
+ * Pure version of moveTo: returns the {bpPerPx, offsetPx} that moveTo would
+ * apply, without mutating any model. Assumes no bpPerPx clamping (i.e.
+ * Base1DView with no min/maxBpPerPx).
+ */
+export declare function computeMoveToLayout(self: MoveSnap, start: BpOffset, end: BpOffset): {
+    bpPerPx: number;
+    offsetPx: number;
+};
+/**
+ * The base **painted** at a pixel. Pair it with `pxToBp`'s `offset` field, and
+ * only once you know the pixel is in bounds (`!oob`) — off the end of a region
+ * no base is painted and the question has no answer.
+ *
+ * Use this rather than `coord0` whenever the result indexes per-base data: a
+ * sequence string, a coverage bin, a per-base tooltip. Reversed, bp runs
+ * leftward, so base b covers offsets (b, b+1] — `coord0`'s floor names b+1 on
+ * b's leftmost pixel column, and names `r.end`, outside the region entirely, on
+ * the region's first column.
+ *
+ * This is the same one-base pivot as render-core's `makeCellLeftMapper` /
+ * `bpAtPx`, which is what the per-base painters draw with, so this is the
+ * readout that agrees with what is on screen. The parity block in
+ * `Base1DUtils.test.ts` holds the two together.
+ *
+ * They stay two spellings because there is no shared call to make, not because
+ * of the package graph — core declares `@jbrowse/render-core` and imports it
+ * from three modules already. `bpAtPx` takes a screen pixel plus a px/bp
+ * projection and is mostly about the float behaviour of that projection; this
+ * takes an offset already in bp and has no projection. Feeding `bpAtPx`
+ * synthetic bounds to fake one computes `(offsetBp * span) / span`, which is
+ * not exactly `offsetBp` at genome scale: over a 3000000-sample sweep of base
+ * boundaries the perturbation named the wrong base 6885 times, every one of
+ * them on a 248956422 bp region (1.9% of that span's samples) and none on any
+ * span at or below 133797422. What is left to share is the two lines below, and
+ * only render-core could hold them — it must not import core — which would put
+ * a pixel-free function downstream of the renderer and split it from its own
+ * forward twin, `bpOffsetInRegion` at the top of this file.
+ */
+export declare function basePaintedAt(r: {
+    start: number;
+    end: number;
+    reversed?: boolean;
+}, offsetBp: number): number;
+export interface PxToBpResult extends RegionSnap {
     coord: number;
+    coord0: number;
     index: number;
-    refName: string;
     oob: boolean;
-    assemblyName: string;
     offset: number;
-    start: number;
-    end: number;
-    reversed?: boolean;
-};
-export declare function bpToPx({ refName, coord, regionNumber, self, }: {
+}
+export declare function pxToBp(self: ViewLayout, px: number): PxToBpResult;
+export declare function offsetBpToPx(self: ViewLayout, regionIndex: number, regionOffsetBp: number): number;
+export declare function bpToPx({ refName, coord, displayedRegionIndex, self, }: {
     refName: string;
     coord: number;
-    regionNumber?: number;
-    self: ViewSnap;
+    displayedRegionIndex?: number;
+    self: ViewLayout;
 }): {
     index: number;
     offsetPx: number;
 } | undefined;
-export declare function bpToPxMap({ refName, coord, regionNumber, self, }: {
+/**
+ * The {@link BpOffset} a 0-based genomic coord sits at — a region index plus an
+ * offset in **bp** from that region's left screen edge, which is the shape
+ * `moveTo` and `computeMoveToLayout` take.
+ *
+ * `bpToPx` above answers the neighbouring question in pixels and returns an
+ * `index` too, so `{...bpToPx(...), offset: hit.offsetPx}` type-checks and is
+ * wrong: `moveTo` re-adds the bp of every region before `index`, which
+ * `offsetPx` has already counted, and divides by a bpPerPx that was never in
+ * the units to begin with. Reach for this when the destination is a coordinate
+ * rather than a pixel.
+ *
+ * Undefined when no displayed region holds the coord, same as `bpToPx`; a
+ * caller that means "as far as the region goes" clamps before asking.
+ */
+export declare function bpToOffset({ refName, coord, displayedRegions, }: {
+    refName: string;
+    coord: number;
+    displayedRegions: {
+        refName: string;
+        start: number;
+        end: number;
+        reversed?: boolean;
+    }[];
+}): BpOffset | undefined;
+/**
+ * Where a 0-based genomic coord sits in the LINEARIZED bp space — the
+ * concatenation of `displayedRegions`, which is the space `windowStartBp`
+ * indexes and the one a viewport is stored in.
+ *
+ * `bpToPx`'s answer in those units, and without its rounding, which is the
+ * reason to reach for this one: `bpToPx` quantizes to a whole pixel at the
+ * CURRENT `bpPerPx`, so a caller computing a destination while the view is
+ * mid-zoom — an animated flight planning its next leg — gets a destination
+ * that shifts with whatever zoom it happened to ask at.
+ *
+ * `undefined` when no displayed region holds the coord, exactly as `bpToPx`
+ * answers: a refName the view is not showing has no place on its screen.
+ */
+export declare function bpToLinearBp({ refName, coord, displayedRegions, }: {
+    refName: string;
+    coord: number;
+    displayedRegions: {
+        refName: string;
+        start: number;
+        end: number;
+        reversed?: boolean;
+    }[];
+}): number | undefined;
+/**
+ * Screen order of two {@link BpOffset}s: negative when `a` is to the left of
+ * `b`. `moveTo` takes its arguments left-to-right and computes a negative
+ * bpPerPx from a backwards pair, so a caller deriving the two from data that
+ * can name them in either order sorts with this first.
+ */
+export declare function compareBpOffsets(a: BpOffset, b: BpOffset): number;
+export declare function layoutBpToPx(layout: ViewLayout, args: {
     refName: string;
     coord: number;
-    regionNumber?: number;
-    self: ViewSnap;
-}): {};
+    displayedRegionIndex?: number;
+}): number | undefined;
+export declare function clipToDisplayedRegions(layout: ViewLayout, region: {
+    refName: string;
+    start: number;
+    end: number;
+}): {
+    start: number;
+    end: number;
+} | undefined;
+export declare function getLayoutHighlightCoords(layout: ViewLayout, region: {
+    refName: string;
+    start: number;
+    end: number;
+}, minWidth?: number): {
+    width: number;
+    left: number;
+} | undefined;
+export declare function createOverviewLayout({ displayedRegions, width, minimumBlockWidth, }: {
+    displayedRegions: RegionSnap[];
+    width: number;
+    minimumBlockWidth?: number;
+}): ViewLayout;
+export interface PxSpan {
+    leftPx: number;
+    rightPx: number;
+}
+/** Project a span into another pixel space: each end becomes px * scale + translatePx. */
+export declare function transformPxSpan(span: PxSpan, scale: number, translatePx?: number): PxSpan;
+/**
+ * Absolute pixel extent (measured from the layout origin) of the region blocks
+ * — content and elided — but not the blank inter-region padding at the ends.
+ * Since dynamic blocks only pad at the ends, the region blocks are contiguous,
+ * so the first block's left edge to the last block's right edge is the full
+ * extent.
+ *
+ * Uses block pixel geometry rather than projecting genomic coordinates because
+ * coalesced elided blocks have their coordinates zeroed out, so coordinate
+ * projection cannot reach them at all — and because pixel geometry is per-copy
+ * correct for free, where projecting a refName would land both copies of a
+ * twice-displayed region on the first.
+ */
+export declare function regionBlocksPxExtent(blocks: BaseBlock[]): PxSpan | undefined;
+/**
+ * The visible regions' pixel extent projected onto an overview layout: the span
+ * of the overview scalebar's "you are here" rectangle, and of the top edge of
+ * the polygon drawn under it. Both read this one extent so they always describe
+ * the same regions, elided ones included.
+ *
+ * The main view and the overview lay out the same regions from cumulative-bp 0,
+ * so a main-view pixel maps to the (more zoomed-out) overview by the bpPerPx
+ * ratio.
+ */
+export declare function getOverviewRegionPxSpan({ overview, bpPerPx, blocks, }: {
+    overview: ViewLayout;
+    bpPerPx: number;
+    blocks: BaseBlock[];
+}): PxSpan | undefined;
+export {};