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

package/esm/util/unknownSnapshotKeys.js

@@ -0,0 +1,76 @@
+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. The console alone, like
+ * `reportLegacyInit`: the view opened without them, and the keys are usually a
+ * v4 session's retired state that a visitor holding the link cannot act on.
+ */
+export function reportUnknownKeys(self, keys) {
+    if (keys.length) {
+        console.warn(unknownKeysMessage(viewLabel(self), keys));
+    }
+}
+/**
+ * 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/usePanZoom.js

@@ -113,6 +113,9 @@ export function usePanZoom(ref, view, { touchAction = 'none', } = {}) {
         };
     }, [ref, touchAction]);
     function endDrag(event) {
+        if (dragRef.current?.pointerId !== event.pointerId) {
+            return;
+        }
         dragRef.current = undefined;
         // release only what the move handler took — a press that stayed under the
         // threshold never captured anything
@@ -131,7 +134,7 @@ export function usePanZoom(ref, view, { touchAction = 'none', } = {}) {
                 // lands on an icon inside the control. Shift is left alone too: it is
                 // what a range-select of the host's own would want, and it is what
                 // JBrowse's own view uses it for.
-                if (event.button !== 0 || event.shiftKey) {
+                if (!event.isPrimary || event.button !== 0 || event.shiftKey) {
                     return;
                 }
                 if (event.target instanceof Element &&
@@ -139,11 +142,15 @@ export function usePanZoom(ref, view, { touchAction = 'none', } = {}) {
                     return;
                 }
                 // Note what this does *not* do: capture the pointer. See onPointerMove.
-                dragRef.current = { x: event.clientX, panning: false };
+                dragRef.current = {
+                    x: event.clientX,
+                    panning: false,
+                    pointerId: event.pointerId,
+                };
             },
             onPointerMove(event) {
                 const drag = dragRef.current;
-                if (!drag) {
+                if (!drag || drag.pointerId !== event.pointerId) {
                     return;
                 }
                 if (!drag.panning) {

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/useRafCommit.js

@@ -18,6 +18,7 @@ export function useRafCommit(commit) {
         const pending = pendingRef.current;
         if (pending) {
             cancelAnimationFrame(pending.id);
+            pendingRef.current = undefined;
         }
     }, []);
     const schedule = useCallback((value) => {

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;