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

package/esm/util/unknownSnapshotKeys.js

@@ -0,0 +1,82 @@
+import { getType } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/** what a diagnostic calls the view: its snapshot `type`, or the model name */
+export function viewLabel(self) {
+    return self.type ?? getType(self).name;
+}
+/**
+ * What every surface calls this mistake. A session spec launches a view without
+ * ever building a snapshot, so it classifies its own keys and reports them
+ * through its own session rather than through the sink below — one wording, so
+ * a typo reads the same whether it was written in a config or in a URL.
+ */
+export function unknownKeysMessage(label, keys) {
+    return `${label} ignored unknown key(s): ${keys.join(', ')}`;
+}
+/** The action `setter-only` names: `height` -> `setHeight`. */
+export function displaySetterName(key) {
+    return `set${key[0].toUpperCase()}${key.slice(1)}`;
+}
+/**
+ * What a surface calls a key the display has an action for but no slot. Its own
+ * sentence rather than `unknownKeysMessage`'s: the display does take the
+ * setting, just not written this way, and saying "unknown key" over a key whose
+ * setter we name in the same breath contradicts itself.
+ */
+export function setterOnlyMessage(label, keys) {
+    return `${label} did not apply ${keys.join(', ')}: no config slot takes ${keys.length > 1 ? 'them' : 'it'}. Call ${keys.map(displaySetterName).join(', ')} on the display instead.`;
+}
+/**
+ * Name the keys a view was handed and could not place, from the partition
+ * `withLaunchInput` runs on the snapshot.
+ */
+export function reportUnknownKeys(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = unknownKeysMessage(viewLabel(self), keys);
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * Name the row lists a view refused whole. `withLaunchInput` splits an authored
+ * array into the recipes a launcher resolves and the built snapshots MST
+ * restores, per entry — but a row list is indexed against the view's `levels`
+ * and per-level tracks, so a list holding both kinds has no correct split and
+ * is refused rather than renumbered.
+ */
+export function reportMalformedRows(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = `${viewLabel(self)} refused ${keys.join(', ')}: the list mixes built view snapshots with recipes to open one, and the rows index against the levels between them. Write all of them one way.`;
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * What every surface calls v4's nested `init`. v5 takes every setting directly
+ * on the view object and unwraps the nesting on the way in, so the settings
+ * still arrive — this names the spelling to fix while they do.
+ */
+export function legacyInitMessage(label) {
+    return `${label} nests its settings under "init", which is deprecated: write every setting directly on the view object.`;
+}
+/**
+ * Name a snapshot that still writes v4's nested `init`. The console alone,
+ * unlike the two reporters above: the settings were applied, so there is
+ * nothing for a visitor to act on and a warning toast over a working view is
+ * noise. `jbrowse validate` is where the author of the config hears about it.
+ */
+export function reportLegacyInit(self) {
+    console.warn(legacyInitMessage(viewLabel(self)));
+}

package/esm/util/useFeatureSequence.js

@@ -12,10 +12,10 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
             start,
             end,
             upDownBp,
-            +forceLoad,
+            forceLoad,
         ]
         : null, guard
-        ? async (_name, _asm, _ref, _start, _end, _upDown, _force, stopToken, statusCallback) => {
+        ? async (_name, _asm, _ref, _start, _end, _upDown, _force, signal, statusCallback) => {
             const { session: s, assemblyName: asmName } = guard;
             if (!forceLoad && end - start > BPLIMIT) {
                 return {
@@ -32,7 +32,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                     refName,
                     assemblyName: asmName,
                     session: s,
-                    stopToken,
+                    signal,
                     statusCallback: slot(),
                 }),
                 upDownBp > 0
@@ -42,7 +42,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                         refName,
                         assemblyName: asmName,
                         session: s,
-                        stopToken,
+                        signal,
                         statusCallback: slot(),
                     })
                     : Promise.resolve(''),
@@ -53,7 +53,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                         refName,
                         assemblyName: asmName,
                         session: s,
-                        stopToken,
+                        signal,
                         statusCallback: slot(),
                     })
                     : Promise.resolve(''),

package/esm/util/useFetch.d.ts

@@ -1,5 +1,4 @@
 import type { RpcStatus, StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 export type FetchKey = string | readonly unknown[] | null | undefined | false;
 type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
 /**
@@ -10,8 +9,8 @@ type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
  * single argument (`useGenomesData`). Most fetchers close over what they need
  * and declare no parameters at all, which stays assignable either way.
  *
- * A stop token and a status callback follow the key arguments. The token is
- * created per fetch and stopped when the key changes or the component unmounts,
+ * A signal and a status callback follow the key arguments. The signal is
+ * created per fetch and aborted when the key changes or the component unmounts,
  * so a fetcher that forwards it to an RPC cancels the worker instead of leaving
  * it grinding on an answer nobody is waiting for. The callback is what the RPC's
  * own progress comes back through, and it surfaces on the hook's `status` — a
@@ -19,7 +18,7 @@ type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
  * works, instead of a bare spinner over an uninterruptible whole-chromosome
  * read. Fetchers that take neither are unaffected.
  */
-type FetcherArgs<Key> = FetchingKey<Key> extends readonly unknown[] ? [...FetchingKey<Key>, StopToken, StatusCallback] : [FetchingKey<Key>, StopToken, StatusCallback];
+type FetcherArgs<Key> = FetchingKey<Key> extends readonly unknown[] ? [...FetchingKey<Key>, AbortSignal, StatusCallback] : [FetchingKey<Key>, AbortSignal, StatusCallback];
 interface FetchState<Data> {
     data: Data | undefined;
     error: unknown;

package/esm/util/useFetch.js

@@ -1,11 +1,20 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { createStatusWindow } from './progress.js';
-import { createStopToken, stopStopToken } from './stopToken.js';
-const isNil = (k) => k === null || k === undefined || k === false;
-// A null result means "don't fetch": no key, or an array key with a missing
-// piece (e.g. an offset that isn't resolved yet).
+// The whole key as the "don't fetch" sentinel: `cond && [...]`, `cond ? [...] :
+// null`. `false` belongs here and NOT in the element check below, which is what
+// this used to share with it.
+const isNoKey = (k) => k === null || k === undefined || k === false;
+// An element that has not resolved yet — an offset still being computed, an
+// assembly still loading. **`false` is not one of them**: it is a resolved
+// boolean, and a caller with a `false`-valued setting in its key meant to fetch
+// under that setting. Sharing one predicate with the sentinel above made every
+// such key unfetchable, which the MAF sequence widget shipped — its
+// `includeInsertions` defaults to `false`, so the widget sat on its loading
+// animation forever and issued no RPC at all. `SaveTrackData` hit the same
+// thing and encoded its boolean as a string rather than fixing it here.
+const isUnresolved = (k) => k === null || k === undefined;
 function serializeKey(key) {
-    return isNil(key) || (Array.isArray(key) && key.some(isNil))
+    return isNoKey(key) || (Array.isArray(key) && key.some(isUnresolved))
         ? null
         : JSON.stringify(key);
 }
@@ -85,7 +94,7 @@ export function useFetch(key, fetcher, options = {}) {
             // fetch resolved is a different case, and the stream's own `clear` drops
             // that one.)
             let settled = false;
-            const stopToken = createStopToken();
+            const controller = new AbortController();
             // A refetch under the same key — mutate(), or the cross-component
             // mutate(key) — is the same question asked again, so what is on screen is
             // a stale answer to it rather than an answer to something else: leave it
@@ -107,7 +116,7 @@ export function useFetch(key, fetcher, options = {}) {
             setStatus(undefined);
             // The runtime counterpart of FetcherArgs: an array key becomes one
             // argument per element, anything else a single argument, then the stop
-            // token and the status callback. A conditional type over an unresolved
+            // signal and the status callback. A conditional type over an unresolved
             // `Key` can't be discharged
             // inside the function body, so the parameter list is erased for this one
             // call — callers still get the precise arity, and the looseness stops
@@ -127,7 +136,7 @@ export function useFetch(key, fetcher, options = {}) {
             const { statusCallback, clear: clearStatus } = statusWindow.open({
                 isCurrent: () => alive && !settled,
             });
-            const args = [...keyArgs, stopToken, statusCallback];
+            const args = [...keyArgs, controller.signal, statusCallback];
             const call = fetcher;
             Promise.resolve()
                 .then(() => call(...args))
@@ -151,9 +160,9 @@ export function useFetch(key, fetcher, options = {}) {
             });
             return () => {
                 alive = false;
-                // the token's lifetime is this fetch's. An abort rejection lands in the
+                // the signal's lifetime is this fetch's. An abort rejection lands in the
                 // catch above with alive already false, so it never surfaces as an error
-                stopStopToken(stopToken);
+                controller.abort();
                 // and the window's lifetime is too: `alive` already makes a queued
                 // trailing write a no-op, but the timer behind it would otherwise stand
                 // for up to a window past unmount

package/esm/util/useFetchPlugins.d.ts

@@ -1,12 +1,16 @@
-import type { JBrowsePlugin } from './types/data.ts';
 /**
  * The plugin store listing. Shared by every surface that installs plugins (the
  * in-session plugin store widget, Desktop's global plugins dialog) so they read
  * the same manifest version and get the same integrity hashes and compatibility
  * ranges — a second copy of this fetch is how one of them silently ends up on
  * the unhashed v1 list.
+ *
+ * Through `fetchPlugins`, which memoizes its request, rather than fetching the
+ * url directly: `useFetch` holds no data cache, so every open of the store
+ * widget was a fresh round trip beside whatever the boot path had already
+ * asked for.
  */
 export declare function useFetchPlugins(): {
-    plugins: JBrowsePlugin[] | undefined;
+    plugins: import("./index.ts").JBrowsePlugin[] | undefined;
     error: unknown;
 };

package/esm/util/useFetchPlugins.js

@@ -1,5 +1,4 @@
-import { PLUGIN_STORE_URL } from '../checkPlugins.js';
-import { fetchJson } from './fetchJson.js';
+import { fetchPlugins } from '../checkPlugins.js';
 import { useFetch } from './useFetch.js';
 /**
  * The plugin store listing. Shared by every surface that installs plugins (the
@@ -7,8 +6,13 @@ import { useFetch } from './useFetch.js';
  * the same manifest version and get the same integrity hashes and compatibility
  * ranges — a second copy of this fetch is how one of them silently ends up on
  * the unhashed v1 list.
+ *
+ * Through `fetchPlugins`, which memoizes its request, rather than fetching the
+ * url directly: `useFetch` holds no data cache, so every open of the store
+ * widget was a fresh round trip beside whatever the boot path had already
+ * asked for.
  */
 export function useFetchPlugins() {
-    const { data, error } = useFetch('jbrowse-plugin-store-v2', () => fetchJson(PLUGIN_STORE_URL));
+    const { data, error } = useFetch('jbrowse-plugin-store-v2', fetchPlugins);
     return { plugins: data?.plugins, error };
 }

package/esm/util/usePanelVirtualScroll.d.ts

@@ -1,37 +1,9 @@
-interface PanelScrollTarget {
-    scrollTop: number;
-    scrollableHeight: number;
-    setScrollTop: (n: number) => void;
-}
+import type { VirtualScrollModel } from './useVirtualScrollWheel.ts';
 /**
- * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
- * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
- * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
- * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this. The latch (inside
- * `applyScroll`) owns `preventDefault` but never `stopPropagation`, so a diagonal
- * wheel still bubbles its horizontal component to the LGV for panning.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
- * agree on what a gesture means. This is the second of the two rules that
- * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
- * resizes) is the other — and the two displays sharing it had byte-identical
- * copies differing only in which getter named the viewport. The canvas display
- * converged here when it moved off a native overflow container; the ADR's table
- * still described its pre-virtual-scroll rule and has been corrected.
- *
- * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
- * so core needs no view typing and each display keeps naming its own viewport
- * (the pileup's excludes the sticky coverage band; the canvas display's is the
- * whole track).
- *
- * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
- * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup, the
+ * canvas feature display, multi-way synteny: a plain wheel scrolls it, `shift`
+ * still scrolls it once `scrollZoom` has given the plain wheel to the view, and
+ * ctrl/meta is left to the browser and the view's pinch-zoom. The row-stack
+ * rule, where `shift` resizes, is `useRowVirtualScroll` (ADR-027).
  */
-export declare function usePanelVirtualScroll(panel: HTMLElement | null, model: PanelScrollTarget, { viewportHeight, scrollZoom, }: {
-    viewportHeight: number;
-    scrollZoom: boolean;
-}): void;
-export {};
+export declare function usePanelVirtualScroll(panel: HTMLElement | null, model: VirtualScrollModel, scrollZoom: boolean): void;

package/esm/util/usePanelVirtualScroll.js

@@ -1,42 +1,15 @@
 import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
 /**
- * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
- * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
- * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
- * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this. The latch (inside
- * `applyScroll`) owns `preventDefault` but never `stopPropagation`, so a diagonal
- * wheel still bubbles its horizontal component to the LGV for panning.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
- * agree on what a gesture means. This is the second of the two rules that
- * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
- * resizes) is the other — and the two displays sharing it had byte-identical
- * copies differing only in which getter named the viewport. The canvas display
- * converged here when it moved off a native overflow container; the ADR's table
- * still described its pre-virtual-scroll rule and has been corrected.
- *
- * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
- * so core needs no view typing and each display keeps naming its own viewport
- * (the pileup's excludes the sticky coverage band; the canvas display's is the
- * whole track).
- *
- * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
- * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup, the
+ * canvas feature display, multi-way synteny: a plain wheel scrolls it, `shift`
+ * still scrolls it once `scrollZoom` has given the plain wheel to the view, and
+ * ctrl/meta is left to the browser and the view's pinch-zoom. The row-stack
+ * rule, where `shift` resizes, is `useRowVirtualScroll` (ADR-027).
  */
-export function usePanelVirtualScroll(panel, model, { viewportHeight, scrollZoom, }) {
-    useVirtualScrollWheel(panel, (e, applyScroll) => {
-        if ((scrollZoom && !e.shiftKey) || e.ctrlKey || e.metaKey) {
-            return;
+export function usePanelVirtualScroll(panel, model, scrollZoom) {
+    useVirtualScrollWheel(panel, model, (e, scroll) => {
+        if ((!scrollZoom || e.shiftKey) && !e.ctrlKey && !e.metaKey) {
+            scroll();
         }
-        applyScroll(e, {
-            scrollTop: model.scrollTop,
-            viewportHeight,
-            scrollableHeight: model.scrollableHeight,
-        }, n => {
-            model.setScrollTop(n);
-        });
     });
 }

package/esm/util/useRowVirtualScroll.d.ts

@@ -1,32 +1,9 @@
-interface RowScrollTarget {
-    effectiveRowHeight: number;
-    scrollTop: number;
-    nrow: number;
-    scrollableHeight: number;
-    setRowHeight: (n: number) => void;
-    setScrollTop: (n: number) => void;
-}
+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 (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.
+ * 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: RowScrollTarget, { viewportHeight, scrollZoom, }: {
-    viewportHeight: number;
-    scrollZoom: boolean;
-}): void;
-export {};
+export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowResizeTarget, scrollZoom: boolean): void;

package/esm/util/useRowVirtualScroll.js

@@ -2,62 +2,21 @@ 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.
+ * 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, { 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.
+export function useRowVirtualScroll(el, model, scrollZoom) {
+    useVirtualScrollWheel(el, model, (e, scroll, rowsEl) => {
         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);
-                },
-            });
+            applyRowResizeWheel(e, rowsEl, model);
         }
         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);
-            });
+            scroll();
         }
     });
 }

package/esm/util/useVirtualScrollWheel.d.ts

@@ -1,7 +1,23 @@
-export interface VirtualScrollOpts {
+/**
+ * What a virtually scrolled panel reads and writes. `TrackHeightMixin`
+ * implements it, so a display passes itself.
+ */
+export interface VirtualScrollModel {
     scrollTop: number;
-    viewportHeight: number;
+    /** 0 when the content fits; never sub-pixel */
     scrollableHeight: number;
+    scrollViewportHeight: number;
+    setScrollTop: (scrollTop: number) => void;
 }
-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;
+/**
+ * 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

@@ -1,95 +1,61 @@
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+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';
-// 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.
+// 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 (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) {
+/**
+ * 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 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.
+    // 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 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);
+        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;
         }
-        // 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.
+        // 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();
         });

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[];