@jbrowse/core 4.3.0 → 5.0.0-beta.2

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,32 @@
+interface RowScrollTarget {
+    effectiveRowHeight: number;
+    scrollTop: number;
+    nrow: number;
+    scrollableHeight: number;
+    setRowHeight: (n: number) => void;
+    setScrollTop: (n: number) => void;
+}
+/**
+ * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
+ * and MAF: `shift`+wheel resizes the rows (a vertical-zoom that keeps the row
+ * under the cursor put), a plain wheel scrolls them, and anything the panel
+ * can't consume is left to bubble to the view.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
+ * not agree on what a gesture means — and that still holds. This is the one rule
+ * two of them genuinely share, which the ADR states outright ("same rule as the
+ * variant displays, and deliberately so: same sample-row shape, same coupled
+ * row-height axis"). It is unified for exactly that reason, and no further: the
+ * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
+ * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
+ * model, so core needs no view typing and each display keeps naming its own
+ * rows-area height.
+ */
+export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowScrollTarget, { viewportHeight, scrollZoom, }: {
+    viewportHeight: number;
+    scrollZoom: boolean;
+}): void;
+export {};

package/esm/util/useRowVirtualScroll.js

@@ -0,0 +1,63 @@
+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 (a vertical-zoom that keeps the row
+ * under the cursor put), a plain wheel scrolls them, and anything the panel
+ * can't consume is left to bubble to the view.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
+ * not agree on what a gesture means — and that still holds. This is the one rule
+ * two of them genuinely share, which the ADR states outright ("same rule as the
+ * variant displays, and deliberately so: same sample-row shape, same coupled
+ * row-height axis"). It is unified for exactly that reason, and no further: the
+ * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
+ * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
+ * model, so core needs no view typing and each display keeps naming its own
+ * rows-area height.
+ */
+export function useRowVirtualScroll(el, model, { viewportHeight, scrollZoom, }) {
+    useVirtualScrollWheel(el, (e, applyScroll, rowsEl) => {
+        // ctrl/meta is the browser's own zoom (and the view's pinch-zoom) and is
+        // never ours, whatever else is held. Tested first rather than only in the
+        // scroll branch: ctrl+shift+wheel used to reach the resize below, which
+        // `preventDefault`s — so a row-stack display swallowed page zoom where
+        // every other display passes it through.
+        if (e.ctrlKey || e.metaKey) {
+            return;
+        }
+        if (e.shiftKey) {
+            // Resizing exits fit-to-height into a pinned height, which is what makes
+            // the gesture meaningful: the fit height is exactly the floor it shrinks
+            // to, so there is nothing to zoom while the sentinel is set.
+            applyRowResizeWheel(e, rowsEl, {
+                effectiveRowHeight: model.effectiveRowHeight,
+                scrollTop: model.scrollTop,
+                nrow: model.nrow,
+                viewportHeight,
+                setRowHeight: n => {
+                    model.setRowHeight(n);
+                },
+                setScrollTop: n => {
+                    model.setScrollTop(n);
+                },
+            });
+        }
+        else if (!scrollZoom) {
+            // A gesture the panel can't consume is left alone: with the rows fitting
+            // the track (`scrollableHeight === 0`, always true in fit-to-height mode)
+            // the wheel reaches the view and zooms or scrolls the page exactly as it
+            // does over any other track. Same for the explicit zoom gestures.
+            applyScroll(e, {
+                scrollTop: model.scrollTop,
+                viewportHeight,
+                scrollableHeight: model.scrollableHeight,
+            }, n => {
+                model.setScrollTop(n);
+            });
+        }
+    });
+}

package/esm/util/useVirtualScrollWheel.d.ts

@@ -0,0 +1,7 @@
+export interface VirtualScrollOpts {
+    scrollTop: number;
+    viewportHeight: number;
+    scrollableHeight: number;
+}
+export type ApplyVirtualScroll = (e: WheelEvent, opts: VirtualScrollOpts, commit: (scrollTop: number) => void) => void;
+export declare function useVirtualScrollWheel(panel: HTMLElement | null, onWheel: (e: WheelEvent, applyScroll: ApplyVirtualScroll, el: HTMLElement) => void): void;

package/esm/util/useVirtualScrollWheel.js

@@ -0,0 +1,108 @@
+import { useCallback, 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';
+// Whether the wheel landed inside something within the panel that runs its own
+// gestures — JBrowse's `[data-gesture-owner]` marker, the same one the LGV's
+// click-drag pan and MAF's drag-selection test for. A panel spans its overlays
+// now, and a few of those are controls rather than content: the display's own
+// `VerticalScrollbar` (which scrolls the panel itself, from its own listener),
+// the pileup's band resize handles, a floating legend. Those keep the gesture
+// they already had instead of being absorbed the moment the panel grew to cover
+// them.
+//
+// The marker element ITSELF is a panel at the one call site that is one — the
+// scrollbar binds this hook to its own marked track — so an owner that IS the
+// panel does not count. Nor does one ABOVE it: `TrackContainer` stamps the
+// marker once for its whole overlay layer, and `closest` walking out of the
+// panel into that would otherwise disown every wheel a display gets.
+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 (no DOM overflow
+// container to self-correct). Owns the latch, the per-frame coalescing, and the
+// listener lifecycle, and hands the caller an `applyScroll` that runs the latch
+// + schedules the commit. The gesture guards (scrollZoom, ctrl/meta,
+// shift-to-resize) differ per display and so stay in the caller; this
+// centralizes the mechanical latch + listener + rAF boilerplate shared by the
+// alignments pileup, the variant matrix, and the canvas display.
+//
+// **Bind this to the panel, not to the `<canvas>`.** A canvas cannot hold DOM
+// children, so every overlay a display draws over it — floating feature labels,
+// group chips, sashimi arcs — is a positioned SIBLING, and the ones that answer
+// the pointer (`pointerEvents: 'auto'`, because they are clickable) are what a
+// wheel event over them targets. That event bubbles past the canvas entirely, so
+// a listener bound to the canvas never sees it and the gesture falls through to
+// the page mid-scroll. Bound to the element containing both, the wheel is the
+// panel's wherever inside it the cursor happens to be. `trackPointerPresence`
+// below keys off the same element, and `mouseenter`/`mouseleave` ignore
+// descendant transitions — so crossing onto an overlay no longer reads as
+// leaving the panel either.
+//
+// What keeps a panel safe to widen is `claimedInside` above: it covers its
+// overlays, and yields the ones that run gestures of their own.
+export function useVirtualScrollWheel(panel, 
+// `el` is the element the listener is bound to, handed back non-null: a
+// gesture measuring against its own box (the row-resize pin) would otherwise
+// re-assert the nullable it was passed, at the one call site that cannot be
+// reached with a null.
+onWheel) {
+    const latch = useMemo(() => createScrollLatch(), []);
+    const frame = useMemo(() => createFrameCoalescer(), []);
+    // The latched scroll position as it advances across one frame's events. The
+    // latch reads this, not the model, so its boundary/preventDefault decision
+    // sees monotonically advancing offsets and no delta is lost to a
+    // not-yet-committed model read.
+    const runningRef = useRef(0);
+    const applyScroll = useCallback((e, { scrollTop, viewportHeight, scrollableHeight }, commit) => {
+        if (scrollableHeight <= 0) {
+            return;
+        }
+        // A fresh frame (nothing pending) re-syncs to the model's live scrollTop;
+        // within a frame `running` keeps advancing from the last latched offset.
+        if (!frame.pending) {
+            runningRef.current = scrollTop;
+        }
+        const dy = normalizeWheelDelta(e.deltaY, e.deltaMode, viewportHeight);
+        const next = latch.scroll(e, runningRef.current, dy, scrollableHeight);
+        if (next !== null) {
+            runningRef.current = next;
+            // The first move of a frame schedules the commit; later moves only
+            // advance `running`, so the frame ends with a single setScrollTop (one
+            // repaint) carrying the accumulated offset.
+            frame.schedule(() => {
+                commit(runningRef.current);
+            });
+        }
+    }, [latch, frame]);
+    const handleWheel = useEventCallback((e, el) => {
+        onWheel(e, applyScroll, el);
+    });
+    useEffect(() => {
+        if (!panel) {
+            return undefined;
+        }
+        // Ignore wheel events the browser keeps latching to this panel once the
+        // pointer has left (see trackPointerPresence): let them chain to the page
+        // and reset the latch so the next in-panel gesture starts clean. Without
+        // this the panel stays stuck to per-track scroll after the mouse has left —
+        // worst in embedded, where the outer page is the thing that should scroll.
+        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/viewStatus.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The mutually-exclusive lifecycle state of a view, as one value.
+ *
+ * A view answers this question through nine getters today — `ready`, `error`,
+ * `initialized`, `showLoading`, `showImportForm`, `hasSomethingToShow`,
+ * `loadingMessage`, `loadingProgress`, `assemblyErrors` — and a host reading
+ * them has to re-derive the precedence by subtraction, which is the mistake
+ * `computeDisplayPhase` was written to stop one level down. `view.ready` **is**
+ * that subtraction: `!showLoading && !this.error`.
+ *
+ * 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';
+    message: string;
+    progress: number | undefined;
+} | {
+    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: () => {
+        message: string;
+        progress: number | undefined;
+    } | 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,37 @@
+/**
+ * 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');