@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/useResizeDrag.js

@@ -0,0 +1,105 @@
+import { useRef } from 'react';
+import { usePointerDrag } from './usePointerDrag.js';
+import { useRafCommit } from './useRafCommit.js';
+/**
+ * A pointer drag along one axis, reported as a distance per animation frame.
+ *
+ * This is the whole gesture behind a resize handle with no opinion about how the
+ * handle looks. `ui/ResizeHandle` is this hook plus JBrowse's own 4px bar, and an
+ * app drawing its own divider spreads the returned props onto it. That is the
+ * per-track resize story for an embedder who mounts displays themselves: the
+ * track row is the host's box, so the bar has to be theirs, but the gesture and
+ * the two model calls are not.
+ *
+ * ```tsx
+ * const handleProps = useResizeDrag({
+ *   onDrag: distance => {
+ *     display.resizeHeight(distance)
+ *   },
+ *   onDragStart: () => {
+ *     track.setResizing(true)
+ *   },
+ *   onDragEnd: () => {
+ *     track.setResizing(false)
+ *   },
+ * })
+ * return (
+ *   <div
+ *     {...handleProps}
+ *     style={{ height: 4, cursor: 'row-resize', touchAction: 'none' }}
+ *   />
+ * )
+ * ```
+ *
+ * `touchAction: 'none'` is the caller's half of the deal: without it the browser
+ * claims a touch drag as a page scroll and the pointer stream never arrives.
+ * `usePanZoom` writes the same property itself and this cannot — that one is
+ * handed the element as a ref, while this returns props and never sees a node.
+ * It stays out of those props because a caller's own `style` would silently
+ * replace it.
+ *
+ * Three things a hand-rolled version gets wrong, none of which fails loudly:
+ *
+ * - **One commit per frame.** A pointermove stream (plus the browser's own
+ *   coalesced batches) outruns the frame rate, and each commit reruns whatever
+ *   the resize drives. Committing per event relayouts a pileup several times a
+ *   frame and throws all but the last away.
+ * - **The distance is measured from the last commit**, not from where the press
+ *   started, so a dropped intermediate position costs nothing and a drag that
+ *   runs into a clamp (`resizeHeight` stops at the display's minimum) does not
+ *   bank a debt the pointer has to pay back on the way out.
+ * - **`data-gesture-owner` rides in the props.** It is the marker ancestor
+ *   gestures test for (`closest('[data-gesture-owner]')`, in the LGV's own pan
+ *   and in `usePanZoom`) before starting a drag of their own, so without it
+ *   dragging a resize bar pans the view sideways instead. A `stopPropagation` is
+ *   not a substitute: those ancestors listen on *mouse* events while this runs
+ *   on *pointer* events, so there is no shared event to stop, and stopping the
+ *   mousedown would also cost focus-on-click, whose document-level listener
+ *   (`useFocusOnInteraction`) React's stopPropagation does block.
+ */
+export function useResizeDrag({ onDrag, onDragStart, onDragEnd, vertical = false, gain = 1, }) {
+    const prevPosRef = useRef(0);
+    const getPos = (event) => vertical ? event.clientX : event.clientY;
+    // The scheduled value is the absolute pointer position, last-write-wins, and
+    // the delta against the previous commit is derived here.
+    //
+    // Whole px, and the remainder stays in the baseline rather than in a second
+    // ref: a divided delta has a sub-pixel tail, and every consumer rounds (a band
+    // height is whole px), so rounding it away each frame instead made a gain-2
+    // drag travel 4/3 of the pointer. Leaving the unspent fraction ahead of
+    // `prevPos` is the same mechanism that keeps a drag into a clamp from banking
+    // debt — the distance is always measured from what was last committed.
+    const { schedule, flush } = useRafCommit(pos => {
+        const distance = Math.trunc((pos - prevPosRef.current) / gain);
+        if (distance !== 0) {
+            prevPosRef.current += distance * gain;
+            onDrag(distance);
+        }
+    });
+    const handlers = usePointerDrag({
+        onDragStart: event => {
+            prevPosRef.current = getPos(event);
+            onDragStart?.();
+        },
+        onDrag: event => {
+            event.preventDefault();
+            // read the position synchronously: the deferred commit runs after React
+            // has nulled the event
+            schedule(getPos(event));
+        },
+        onDragEnd: () => {
+            // land the resting size exactly, rather than a frame late
+            flush();
+            onDragEnd?.();
+        },
+    });
+    return {
+        ...handlers,
+        onPointerDown: (event) => {
+            // stops the press from starting a text selection that follows the drag
+            event.preventDefault();
+            handlers.onPointerDown(event);
+        },
+        'data-gesture-owner': 'true',
+    };
+}

package/esm/util/useRowVirtualScroll.d.ts

@@ -0,0 +1,9 @@
+import type { RowResizeTarget } from './applyRowResizeWheel.ts';
+/**
+ * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
+ * and MAF: `shift`+wheel resizes the rows, keeping the row under the cursor
+ * put, and a plain wheel scrolls them unless `scrollZoom` gave it to the view.
+ * ctrl/meta is the browser's zoom whatever else is held. The canvas-panel rule,
+ * where `shift` scrolls, is `usePanelVirtualScroll` (ADR-027).
+ */
+export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowResizeTarget, scrollZoom: boolean): void;

package/esm/util/useRowVirtualScroll.js

@@ -0,0 +1,22 @@
+import { applyRowResizeWheel } from './applyRowResizeWheel.js';
+import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
+/**
+ * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
+ * and MAF: `shift`+wheel resizes the rows, keeping the row under the cursor
+ * put, and a plain wheel scrolls them unless `scrollZoom` gave it to the view.
+ * ctrl/meta is the browser's zoom whatever else is held. The canvas-panel rule,
+ * where `shift` scrolls, is `usePanelVirtualScroll` (ADR-027).
+ */
+export function useRowVirtualScroll(el, model, scrollZoom) {
+    useVirtualScrollWheel(el, model, (e, scroll, rowsEl) => {
+        if (e.ctrlKey || e.metaKey) {
+            return;
+        }
+        if (e.shiftKey) {
+            applyRowResizeWheel(e, rowsEl, model);
+        }
+        else if (!scrollZoom) {
+            scroll();
+        }
+    });
+}

package/esm/util/useVirtualScrollWheel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a virtually scrolled panel reads and writes. `TrackHeightMixin`
+ * implements it, so a display passes itself.
+ */
+export interface VirtualScrollModel {
+    scrollTop: number;
+    /** 0 when the content fits; never sub-pixel */
+    scrollableHeight: number;
+    scrollViewportHeight: number;
+    setScrollTop: (scrollTop: number) => void;
+}
+/**
+ * Non-passive wheel wiring for a canvas-backed virtual scroll. Owns the scroll
+ * latch (and so `preventDefault`), per-frame coalescing of `setScrollTop`, and
+ * the listener lifecycle. `onWheel` decides what the gesture means and calls
+ * `scroll` when it means scrolling `model`.
+ *
+ * **Bind this to the panel, not to the `<canvas>`.** A canvas holds no DOM
+ * children, so the clickable overlays drawn over it are siblings, and a wheel
+ * over one never reaches a listener on the canvas. Overlays that run their own
+ * gestures opt out with `[data-gesture-owner]`.
+ */
+export declare function useVirtualScrollWheel(panel: HTMLElement | null, model: VirtualScrollModel, onWheel: (e: WheelEvent, scroll: () => void, panel: HTMLElement) => void): void;

package/esm/util/useVirtualScrollWheel.js

@@ -0,0 +1,74 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { createFrameCoalescer } from './frameCoalescer.js';
+import { trackPointerPresence } from './pointerPresence.js';
+import { createScrollLatch } from './scrollLatch.js';
+import { useEventCallback } from './useEventCallback.js';
+import { normalizeWheelDelta } from './wheelZoom.js';
+// An owner that IS the panel (the scrollbar binds this hook to its own marked
+// track) or sits ABOVE it (`TrackContainer` marks its whole overlay layer) does
+// not count.
+function claimedInside(panel, target) {
+    const owner = target instanceof Element ? target.closest('[data-gesture-owner]') : null;
+    return owner !== null && owner !== panel && panel.contains(owner);
+}
+/**
+ * Non-passive wheel wiring for a canvas-backed virtual scroll. Owns the scroll
+ * latch (and so `preventDefault`), per-frame coalescing of `setScrollTop`, and
+ * the listener lifecycle. `onWheel` decides what the gesture means and calls
+ * `scroll` when it means scrolling `model`.
+ *
+ * **Bind this to the panel, not to the `<canvas>`.** A canvas holds no DOM
+ * children, so the clickable overlays drawn over it are siblings, and a wheel
+ * over one never reaches a listener on the canvas. Overlays that run their own
+ * gestures opt out with `[data-gesture-owner]`.
+ */
+export function useVirtualScrollWheel(panel, model, onWheel) {
+    const latch = useMemo(() => createScrollLatch(), []);
+    const frame = useMemo(() => createFrameCoalescer(), []);
+    // The offset as it advances across one frame's events, so the latch sees
+    // every delta before the model has committed any of them.
+    const runningRef = useRef(0);
+    const handleWheel = useEventCallback((e, el) => {
+        onWheel(e, () => {
+            // A sideways-dominant gesture is the view's pan unless this panel has
+            // already latched it; ties go vertical, as in the view.
+            const sideways = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+            const { scrollableHeight, scrollViewportHeight } = model;
+            if (scrollableHeight <= 0 || (sideways && !latch.holds(e))) {
+                return;
+            }
+            if (!frame.pending) {
+                runningRef.current = model.scrollTop;
+            }
+            const dy = normalizeWheelDelta(e.deltaY, e.deltaMode, scrollViewportHeight);
+            const next = latch.scroll(e, runningRef.current, dy, scrollableHeight);
+            if (next !== null) {
+                runningRef.current = next;
+                frame.schedule(() => {
+                    model.setScrollTop(runningRef.current);
+                });
+            }
+        }, el);
+    });
+    useEffect(() => {
+        if (!panel) {
+            return undefined;
+        }
+        // The browser keeps targeting a gesture at the element it began on after
+        // the pointer leaves; release those to the page.
+        const presence = trackPointerPresence(panel, () => {
+            latch.reset();
+        });
+        const onWheelNative = (e) => {
+            if (presence.isOver && !claimedInside(panel, e.target)) {
+                handleWheel(e, panel);
+            }
+        };
+        panel.addEventListener('wheel', onWheelNative, { passive: false });
+        return () => {
+            panel.removeEventListener('wheel', onWheelNative);
+            presence.dispose();
+            frame.cancel();
+        };
+    }, [panel, handleWheel, latch, frame]);
+}

package/esm/util/viewHighlights.d.ts

@@ -0,0 +1,3 @@
+import type { HighlightType } from './highlights.ts';
+import type { AssemblyNameResolver } from './tracks.ts';
+export declare function highlightsOnAssemblies(highlights: readonly HighlightType[], assemblyNames: Iterable<string>, assemblyManager: AssemblyNameResolver): HighlightType[];

package/esm/util/viewHighlights.js

@@ -0,0 +1,5 @@
+import { isSameAssemblyName } from './tracks.js';
+export function highlightsOnAssemblies(highlights, assemblyNames, assemblyManager) {
+    const names = [...assemblyNames];
+    return highlights.filter(h => names.some(a => isSameAssemblyName(a, h.assemblyName, assemblyManager)));
+}

package/esm/util/viewStatus.d.ts

@@ -0,0 +1,90 @@
+/**
+ * What a view's loading screen says: the label, the determinate fraction when
+ * the load reports one, and the URL being fetched when the phase named one.
+ */
+export interface ViewLoading {
+    message: string;
+    progress: number | undefined;
+    source?: string;
+}
+interface LoadingAssembly {
+    statusMessage?: string;
+    statusProgress?: number;
+    statusSource?: string;
+}
+/**
+ * A view's `loading` getter: undefined unless `showLoading`, and otherwise read
+ * off the assembly whose load is the wait. The assembly is a thunk because its
+ * status ticks while a file is in flight, and a view that is not loading should
+ * not subscribe to it.
+ */
+export declare function viewLoading(showLoading: boolean, assembly: () => LoadingAssembly | undefined): ViewLoading | undefined;
+/**
+ * The mutually-exclusive lifecycle state of a view, as one value.
+ *
+ * The payload travels with the branch, so a caller cannot read a loading
+ * message out of a failed view or an error out of a healthy one.
+ */
+export type ViewStatus = {
+    type: 'ready';
+} | {
+    type: 'error';
+    error: unknown;
+} | ({
+    type: 'loading';
+} & ViewLoading) | {
+    type: 'noRegions';
+};
+export interface ViewStatusInputs {
+    error: unknown;
+    /**
+     * Whether anything has told the view where to look — displayed regions, or an
+     * `init` blob still being applied.
+     */
+    hasSomethingToShow: boolean;
+    /**
+     * The view's own loading term, as a thunk: `undefined` when it is not
+     * loading, otherwise what the spinner should say.
+     *
+     * A thunk for the same reason `computeDisplayPhase` takes one. The message
+     * and the progress fraction come off the assembly's download status, which
+     * ticks continuously while a file is in flight — so evaluating it eagerly
+     * would make every reader of a *ready* view subscribe to a churning
+     * observable it never displays.
+     */
+    loading: () => ViewLoading | undefined;
+}
+/**
+ * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
+ * rather than re-encoded by subtraction in each view and again in each host.
+ *
+ * **`ready` here is strictly narrower than `view.ready`**, which is the point of
+ * having it. That getter is true when nothing has told the view where to look —
+ * `showLoading` is false in that state and so is `error` — so a host gating on
+ * it mounts track components over a view with no regions and gets an empty box
+ * with nothing anywhere saying why. `noRegions` is that state, named.
+ */
+export declare function computeViewStatus({ error, hasSomethingToShow, loading, }: ViewStatusInputs): ViewStatus;
+/**
+ * The slice of `AssemblyManager` this needs, spelled out rather than imported:
+ * the real type is an MST model a `PluginManager` built, so naming it here
+ * would cost this leaf the whole application's type graph (`util/CLAUDE.md`).
+ */
+interface AssemblyErrorSource {
+    get: (name: string) => {
+        error?: unknown;
+    } | undefined;
+}
+/**
+ * The assembly failures behind a view's `assemblyNames`, joined, or `undefined`
+ * when there are none.
+ *
+ * **Undefined and not `''`**, which is the whole reason this is shared. Three
+ * views spelled it as a bare `.join(', ')`, and a getter that answers the empty
+ * string for "nothing failed" reads as an error to every `!== undefined` test —
+ * `DotplotView.error` folded it in with `??`, so the view reported a terminal
+ * error permanently and jbrowse-img refused to render any dotplot. The in-app
+ * readers all happened to be truthiness tests, which is why it stayed invisible.
+ */
+export declare function assemblyErrorMessage(assemblyManager: AssemblyErrorSource, assemblyNames: string[]): string | undefined;
+export {};

package/esm/util/viewStatus.js

@@ -0,0 +1,54 @@
+/**
+ * A view's `loading` getter: undefined unless `showLoading`, and otherwise read
+ * off the assembly whose load is the wait. The assembly is a thunk because its
+ * status ticks while a file is in flight, and a view that is not loading should
+ * not subscribe to it.
+ */
+export function viewLoading(showLoading, assembly) {
+    if (!showLoading) {
+        return undefined;
+    }
+    const asm = assembly();
+    return {
+        message: asm?.statusMessage || 'Loading',
+        progress: asm?.statusProgress,
+        source: asm?.statusSource,
+    };
+}
+/**
+ * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
+ * rather than re-encoded by subtraction in each view and again in each host.
+ *
+ * **`ready` here is strictly narrower than `view.ready`**, which is the point of
+ * having it. That getter is true when nothing has told the view where to look —
+ * `showLoading` is false in that state and so is `error` — so a host gating on
+ * it mounts track components over a view with no regions and gets an empty box
+ * with nothing anywhere saying why. `noRegions` is that state, named.
+ */
+export function computeViewStatus({ error, hasSomethingToShow, loading, }) {
+    if (error) {
+        return { type: 'error', error };
+    }
+    if (!hasSomethingToShow) {
+        return { type: 'noRegions' };
+    }
+    const pending = loading();
+    return pending ? { type: 'loading', ...pending } : { type: 'ready' };
+}
+/**
+ * The assembly failures behind a view's `assemblyNames`, joined, or `undefined`
+ * when there are none.
+ *
+ * **Undefined and not `''`**, which is the whole reason this is shared. Three
+ * views spelled it as a bare `.join(', ')`, and a getter that answers the empty
+ * string for "nothing failed" reads as an error to every `!== undefined` test —
+ * `DotplotView.error` folded it in with `??`, so the view reported a terminal
+ * error permanently and jbrowse-img refused to render any dotplot. The in-app
+ * readers all happened to be truthiness tests, which is why it stayed invisible.
+ */
+export function assemblyErrorMessage(assemblyManager, assemblyNames) {
+    const errors = assemblyNames
+        .map(name => assemblyManager.get(name)?.error)
+        .filter(e => !!e);
+    return errors.length > 0 ? errors.join(', ') : undefined;
+}

package/esm/util/virtualRange.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Index window for a virtualized 1-D axis of uniform cells: the `[start, end)`
+ * range covering the visible span plus `overscan` cells of buffer on each side,
+ * clamped to `[0, total]`.
+ *
+ * `end` is anchored to `start` (a fixed cell count) rather than recomputed from
+ * `scroll + viewport`. That makes the window **stable across sub-cell scrolling**
+ * — it only moves when `start` crosses a cell boundary — which is what lets
+ * consumers skip work on most scroll events: a canvas keeps its size and
+ * contents, a DOM list keeps its rows mounted. Recomputing `end` independently
+ * is tighter by up to `overscan` cells at the origin and costs that stability,
+ * which is the wrong trade for both.
+ *
+ * `start` is clamped to `total`, not just to 0. A list that shrinks while its
+ * container keeps its scroll position (a new region or track arriving under a
+ * scrolled grid) otherwise yields `start > end` — an inverted range whose
+ * consumers compute a negative canvas height and paint nothing until the next
+ * scroll event. The faceted selector had already hit that and clamped for it;
+ * the MAF sequence grid had the same math without the clamp, which is what
+ * brought the two together here.
+ */
+export declare function virtualRange({ scroll, cellSize, viewport, overscan, total, }: {
+    /** scroll offset of the container, in px */
+    scroll: number;
+    /** px size of one cell along this axis */
+    cellSize: number;
+    /** px size of the visible span */
+    viewport: number;
+    /** cells of buffer to render beyond each edge */
+    overscan: number;
+    /** total number of cells on this axis */
+    total: number;
+}): {
+    start: number;
+    end: number;
+};

package/esm/util/virtualRange.js

@@ -0,0 +1,26 @@
+/**
+ * Index window for a virtualized 1-D axis of uniform cells: the `[start, end)`
+ * range covering the visible span plus `overscan` cells of buffer on each side,
+ * clamped to `[0, total]`.
+ *
+ * `end` is anchored to `start` (a fixed cell count) rather than recomputed from
+ * `scroll + viewport`. That makes the window **stable across sub-cell scrolling**
+ * — it only moves when `start` crosses a cell boundary — which is what lets
+ * consumers skip work on most scroll events: a canvas keeps its size and
+ * contents, a DOM list keeps its rows mounted. Recomputing `end` independently
+ * is tighter by up to `overscan` cells at the origin and costs that stability,
+ * which is the wrong trade for both.
+ *
+ * `start` is clamped to `total`, not just to 0. A list that shrinks while its
+ * container keeps its scroll position (a new region or track arriving under a
+ * scrolled grid) otherwise yields `start > end` — an inverted range whose
+ * consumers compute a negative canvas height and paint nothing until the next
+ * scroll event. The faceted selector had already hit that and clamped for it;
+ * the MAF sequence grid had the same math without the clamp, which is what
+ * brought the two together here.
+ */
+export function virtualRange({ scroll, cellSize, viewport, overscan, total, }) {
+    const start = Math.min(total, Math.max(0, Math.floor(scroll / cellSize) - overscan));
+    const visible = Math.ceil(viewport / cellSize) + overscan * 2;
+    return { start, end: Math.min(total, start + visible) };
+}

package/esm/util/webStorage.d.ts

@@ -0,0 +1,26 @@
+export interface GuardedStorage {
+    /**
+     * Whether there is a store to persist to at all — the first two failures
+     * above, both of which are decided once for the page.
+     *
+     * Every accessor is safe without asking; what this answers is the different
+     * question of whether persistence is *real*. With no store, a write is
+     * dropped and the matching read answers the default, so a caller that
+     * round-trips a value through a key (rather than merely saving one) has to
+     * know, or it reads back its own default and calls it the stored value.
+     */
+    available: () => boolean;
+    /** The raw string stored at `key`, or undefined if absent or unreadable. */
+    getItem: (key: string) => string | undefined;
+    /**
+     * Returns whether the store took the value. Nearly every caller ignores that
+     * — a setting that could not be persisted is not worth interrupting anyone
+     * over — but a caller that reads the key back to learn the current value
+     * needs to know that the read will not reflect this write.
+     */
+    setItem: (key: string, value: string) => boolean;
+    /** Returns whether the store took the removal; see {@link setItem}. */
+    removeItem: (key: string) => boolean;
+}
+export declare const guardedLocalStorage: GuardedStorage;
+export declare const guardedSessionStorage: GuardedStorage;

package/esm/util/webStorage.js

@@ -0,0 +1,92 @@
+// The guard both Web Storage stores need, written once.
+//
+// Every accessor built here is *total*: it falls back rather than throwing.
+// That is not defensiveness for its own sake — the callers are MobX autoruns
+// persisting a setting and state-model actions caching a token, and there a
+// throw is doubly bad. It skips the writes queued behind it in the same autorun
+// body (the LGV persists six keys in a row, the hierarchical track selector
+// seven), and MobX reports it as an uncaught reaction error on every subsequent
+// tick.
+//
+// Three separate ways this can fail, and only the first is the obvious one:
+//
+// - no store global at all — an RPC worker, SSR.
+// - reading the global THROWS rather than being undefined: a cross-origin
+//   iframe with third-party storage blocked, or Safari with cookies disabled.
+//   `typeof localStorage` invokes the same getter, so even the probe has to be
+//   guarded — which is also why a `typeof … === 'undefined'` probe is not a way
+//   to ask whether you are in a worker. This is the embedded-product case
+//   (`@jbrowse/react-*` on someone else's page), where it is also the least
+//   likely to be noticed by us.
+// - the store exists and reads fine, but `setItem` throws: quota exhausted, or
+//   Safari private browsing, which refuses every write.
+/**
+ * `read` names the global rather than being handed it, so resolving it can be
+ * deferred past module load and wrapped in the try that the read itself needs.
+ * `label` only ever reaches the one warning below.
+ */
+function guardedStorage(read, label) {
+    // Resolved once. `null` means "checked, unavailable" — distinct from the
+    // `undefined` that means "not checked yet".
+    let store;
+    function getStore() {
+        if (store === undefined) {
+            try {
+                store = read();
+            }
+            catch {
+                store = null;
+            }
+        }
+        return store ?? undefined;
+    }
+    // One warning per page per store, not one per failed write: the autoruns that
+    // persist settings re-run on every change, so a persistent failure (quota,
+    // private browsing) would otherwise fill the console with the same line. Same
+    // doctrine as the `savingFailed` latch in jbrowse-web's session autosave.
+    let warnedOnWrite = false;
+    return {
+        available: () => getStore() !== undefined,
+        getItem(key) {
+            try {
+                return getStore()?.getItem(key) ?? undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        setItem(key, value) {
+            const s = getStore();
+            if (!s) {
+                return false;
+            }
+            try {
+                s.setItem(key, value);
+                return true;
+            }
+            catch (e) {
+                if (!warnedOnWrite) {
+                    warnedOnWrite = true;
+                    console.warn(`Unable to persist to ${label} (key "${key}"); further failures are not reported`, e);
+                }
+                return false;
+            }
+        },
+        removeItem(key) {
+            const s = getStore();
+            if (!s) {
+                return false;
+            }
+            try {
+                s.removeItem(key);
+                return true;
+            }
+            catch {
+                // nothing useful to do: the value we wanted gone is unreachable anyway
+                return false;
+            }
+        },
+    };
+}
+export const guardedLocalStorage = guardedStorage(() => localStorage, 'localStorage');
+export const guardedSessionStorage = guardedStorage(() => sessionStorage, 'sessionStorage');

package/esm/util/wheelZoom.d.ts

@@ -0,0 +1,65 @@
+export declare const MAX_ZOOM_RATE_PER_MS: number;
+export declare const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+export declare function wheelZoomAccum(normalizedDeltaY: number, isCtrlZoom: boolean): number;
+export declare function getZoomNormalizer(deltaY: number): 25 | 75 | 150 | 500;
+export declare function normalizeWheelDelta(delta: number, deltaMode: number, pageHeight?: number): number;
+export declare function wheelFrameElapsedMs(now: number, lastRafTime: number | null): number;
+export declare function accumulateScroll(prev: number, deltaX: number): number;
+export declare const ZOOM_ACTIVE_WINDOW_MS = 100;
+export declare function isActivelyZooming(now: number, lastZoomTime: number | null): boolean;
+export declare function applyZoomAccum(bpPerPx: number, zoomAccum: number, elapsedMs: number): number;
+export interface WheelZoomView {
+    bpPerPx: number;
+    zoomTo: (bpPerPx: number, offset?: number) => void;
+    horizontalScroll: (delta: number) => void;
+}
+export interface WheelZoomTarget {
+    views: WheelZoomView[];
+    scrollZoom: boolean;
+    originElement: () => HTMLElement | undefined;
+    hold?: <T>(fn: () => T) => T;
+}
+export interface WheelZoomControllerOptions {
+    element: HTMLElement;
+    resolveTarget: (event: WheelEvent) => WheelZoomTarget | undefined;
+    swallowUnhandled?: boolean;
+    /**
+     * Abandon the gesture once the pointer leaves `element`, rather than following
+     * the wheel events the browser keeps latching here (see trackPointerPresence).
+     *
+     * Only for an element large and stationary enough that "the pointer left" is a
+     * real exit. On a small or moving target it isn't: a zoom slides a thin svg
+     * ribbon out from under a stationary cursor, the browser fires mouseleave, and
+     * the gesture would die halfway through. So this is opt-in, not the default.
+     */
+    releaseOnPointerLeave?: boolean;
+    onEvent?: (event: WheelEvent) => void;
+}
+/**
+ * The one wheel gesture handler for linear views. Its decision matrix:
+ *
+ *   - a wheel a nested scroller already consumed  → declined, it owns the gesture
+ *   - ctrl/meta+wheel, or (scrollZoom && |dy| >= |dx|)  → zoom about the cursor
+ *   - shift+wheel while scrollZoom is on                → declined, we pass
+ *   - a sideways delta, unless one arrives mid-zoom     → pan by dx
+ *
+ * Declining shift is what leaves a nested panel its own scroll
+ * (`usePanelVirtualScroll`) — it is not a way back to the page. Browsers turn
+ * shift+wheel into *horizontal* scrolling, so what a view declines here scrolls
+ * the page sideways or not at all. The vertical way out is spatial rather than
+ * modal: JBrowse binds this below the view's sticky header, leaving that header
+ * as a gutter the wheel still scrolls (LinearGenomeViewContainer's tracksRef).
+ *
+ * The listener is non-passive so it can preventDefault to suppress native scroll
+ * during a zoom. To pay for that it only accumulates deltas: every model write
+ * happens in one requestAnimationFrame, so a burst of events (fast trackpad,
+ * inertial scroll) collapses to a single update per frame instead of thrashing
+ * the views once per event.
+ *
+ * A zoom lands eased over the frames after its event (`easeZoomBacklog`), and
+ * all of it lands: how far a gesture zooms depends on the wheel alone, never on
+ * the frame rate or how the events happened to fall into frames.
+ *
+ * Returns its disposer.
+ */
+export declare function createWheelZoomController({ element, resolveTarget, swallowUnhandled, releaseOnPointerLeave, onEvent, }: WheelZoomControllerOptions): () => void;