@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/wheelZoom.js

@@ -0,0 +1,297 @@
+// Shared wheel-zoom math and event handling for linear genome views. The LGV
+// wheel handler, the breakpoint-split overlay and the synteny canvas all zoom on
+// ctrl/scroll-zoom wheel gestures and must behave identically, so the normalizer,
+// the rate limit and the whole gesture decision matrix live here —
+// createWheelZoomController below is what each of those three actually runs.
+import { transaction } from 'mobx';
+import { createFrameCoalescer } from './frameCoalescer.js';
+import { trackPointerPresence } from './pointerPresence.js';
+// max zoom delta per millisecond — equivalent to 0.2 per frame at 60fps
+export const MAX_ZOOM_RATE_PER_MS = 0.2 / 16.67;
+// Scroll-zoom (plain wheel with the scrollZoom preference on) divides by a fixed
+// amount for a smooth proportional feel, rather than the adaptive
+// getZoomNormalizer used for ctrl/pinch zoom where device deltas vary wildly.
+export const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+// The per-event contribution to the zoom accumulator, given a wheel delta
+// already normalized to pixels via normalizeWheelDelta. ctrl/pinch zoom uses the
+// adaptive normalizer; scroll-zoom uses the fixed divisor. Single source of the
+// zoom-step feel so every wheel handler (LGV, breakpoint overlay, synteny)
+// zooms identically for the same gesture.
+export function wheelZoomAccum(normalizedDeltaY, isCtrlZoom) {
+    return (normalizedDeltaY /
+        (isCtrlZoom
+            ? getZoomNormalizer(normalizedDeltaY)
+            : SCROLL_ZOOM_FACTOR_DIVISOR));
+}
+// larger wheel deltas (e.g. mouse wheel notches) divide by more so a single
+// notch produces a consistent zoom step regardless of device delta magnitude
+export function getZoomNormalizer(deltaY) {
+    const abs = Math.abs(deltaY);
+    if (abs < 6) {
+        return 25;
+    }
+    if (abs > 150) {
+        return 500;
+    }
+    if (abs > 30) {
+        return 150;
+    }
+    return 75;
+}
+// One wheel notch in line mode (deltaMode 1) is roughly this many pixels, and a
+// page (deltaMode 2) roughly WHEEL_PAGE_HEIGHT — the values Facebook's
+// normalize-wheel uses, the de-facto cross-browser convention. Pixel mode (0),
+// which trackpads and modern mice report, passes through untouched.
+const WHEEL_LINE_HEIGHT = 40;
+const WHEEL_PAGE_HEIGHT = 800;
+// Convert a WheelEvent delta from its deltaMode units to pixels. Panel-scroll
+// callers pass the viewport height as `pageHeight` so a page maps to exactly one
+// screen; the zoom path omits it and takes the default. Single normalizer for
+// both the zoom math here and the vertical-scroll handlers so a notch means the
+// same thing everywhere.
+export function normalizeWheelDelta(delta, deltaMode, pageHeight = WHEEL_PAGE_HEIGHT) {
+    return deltaMode === 1
+        ? delta * WHEEL_LINE_HEIGHT
+        : deltaMode === 2
+            ? delta * pageHeight
+            : delta;
+}
+// elapsed since the previous animation frame, clamped to 100ms and defaulting
+// to one 60fps frame when there is no prior frame (first event or post-resume)
+export function wheelFrameElapsedMs(now, lastRafTime) {
+    return Math.min(100, lastRafTime !== null ? now - lastRafTime : 16.67);
+}
+// Accumulate horizontal scroll across a frame, restarting from zero when the
+// gesture reverses direction so a flick the opposite way isn't cancelled out by
+// leftover momentum.
+export function accumulateScroll(prev, deltaX) {
+    const reversed = prev !== 0 && Math.sign(deltaX) !== Math.sign(prev);
+    return (reversed ? 0 : prev) + deltaX;
+}
+// A pinch/scroll-zoom gesture fires a continuous stream of wheel events, so we
+// treat the view as "actively zooming" until this many ms pass with no zoom
+// event. While actively zooming, callers ignore horizontal deltas: trackpads
+// emit an unintentional side-scroll mid-gesture that would otherwise pan the
+// view out from under the user.
+export const ZOOM_ACTIVE_WINDOW_MS = 100;
+// `now` and `lastZoomTime` are both wheel-event timeStamps (same clock).
+// lastZoomTime is null before any zoom has occurred.
+export function isActivelyZooming(now, lastZoomTime) {
+    return lastZoomTime !== null && now - lastZoomTime < ZOOM_ACTIVE_WINDOW_MS;
+}
+// apply an accumulated zoom amount to bpPerPx, rate-limited so a burst of wheel
+// events can't zoom faster than MAX_ZOOM_RATE_PER_MS over the frame's elapsed
+export function applyZoomAccum(bpPerPx, zoomAccum, elapsedMs) {
+    const max = MAX_ZOOM_RATE_PER_MS * elapsedMs;
+    const d = Math.max(-max, Math.min(max, zoomAccum));
+    return d > 0 ? bpPerPx * (1 + d) : bpPerPx / (1 - d);
+}
+// A mouse notch lands as ~80ms of eased motion instead of one frame's jump, and
+// a trackpad whose events fall two or three to a frame zooms at an even pace
+const ZOOM_EASE_MS = 24;
+// in log(bpPerPx): a free-spinning wheel can't bank a zoom that runs on after
+// the hand stops
+const MAX_ZOOM_BACKLOG = Math.log(16);
+const ZOOM_SETTLE = 1e-3;
+function zoomAccumToLog(zoomAccum) {
+    return zoomAccum > 0 ? Math.log1p(zoomAccum) : -Math.log1p(-zoomAccum);
+}
+function addToZoomBacklog(backlog, zoomAccum) {
+    return Math.max(-MAX_ZOOM_BACKLOG, Math.min(MAX_ZOOM_BACKLOG, backlog + zoomAccumToLog(zoomAccum)));
+}
+// the rate limit bounds how fast the owed zoom lands, never how much of it
+function easeZoomBacklog(backlog, elapsedMs) {
+    const rest = backlog * Math.exp(-elapsedMs / ZOOM_EASE_MS);
+    const step = Math.abs(rest) < ZOOM_SETTLE ? backlog : backlog - rest;
+    const max = Math.log1p(MAX_ZOOM_RATE_PER_MS * elapsedMs);
+    return Math.max(-max, Math.min(max, step));
+}
+/**
+ * The one wheel gesture handler for linear views. Its decision matrix:
+ *
+ *   - a wheel a nested scroller already consumed  → declined, it owns the gesture
+ *   - ctrl/meta+wheel, or (scrollZoom && |dy| >= |dx|)  → zoom about the cursor
+ *   - shift+wheel while scrollZoom is on                → declined, we pass
+ *   - a sideways delta, unless one arrives mid-zoom     → pan by dx
+ *
+ * Declining shift is what leaves a nested panel its own scroll
+ * (`usePanelVirtualScroll`) — it is not a way back to the page. Browsers turn
+ * shift+wheel into *horizontal* scrolling, so what a view declines here scrolls
+ * the page sideways or not at all. The vertical way out is spatial rather than
+ * modal: JBrowse binds this below the view's sticky header, leaving that header
+ * as a gutter the wheel still scrolls (LinearGenomeViewContainer's tracksRef).
+ *
+ * The listener is non-passive so it can preventDefault to suppress native scroll
+ * during a zoom. To pay for that it only accumulates deltas: every model write
+ * happens in one requestAnimationFrame, so a burst of events (fast trackpad,
+ * inertial scroll) collapses to a single update per frame instead of thrashing
+ * the views once per event.
+ *
+ * A zoom lands eased over the frames after its event (`easeZoomBacklog`), and
+ * all of it lands: how far a gesture zooms depends on the wheel alone, never on
+ * the frame rate or how the events happened to fall into frames.
+ *
+ * Returns its disposer.
+ */
+export function createWheelZoomController({ element, resolveTarget, swallowUnhandled = false, releaseOnPointerLeave = false, onEvent, }) {
+    const frame = createFrameCoalescer();
+    const s = {
+        scrollDelta: 0,
+        zoomBacklog: 0,
+        target: undefined,
+        lastClientX: 0,
+        originLeft: undefined,
+        lastRafTime: null,
+        lastZoomTime: null,
+        lastEventTime: null,
+        warnedNonCancelable: false,
+    };
+    // see releaseOnPointerLeave: drop any in-flight accumulation and stop consuming
+    // latched wheel events, so a continued gesture pans/zooms nothing and chains to
+    // the page instead of staying stuck to this element
+    const presence = releaseOnPointerLeave
+        ? trackPointerPresence(element, () => {
+            s.scrollDelta = 0;
+            s.zoomBacklog = 0;
+            s.originLeft = undefined;
+        })
+        : undefined;
+    function flush(now) {
+        const elapsed = wheelFrameElapsedMs(now, s.lastRafTime);
+        s.lastRafTime = now;
+        const { target } = s;
+        if (target) {
+            const origin = target.originElement();
+            if (s.zoomBacklog !== 0 && origin && s.originLeft === undefined) {
+                s.originLeft = origin.getBoundingClientRect().left;
+            }
+            const originLeft = s.originLeft;
+            if (originLeft === undefined) {
+                s.zoomBacklog = 0;
+            }
+            const step = easeZoomBacklog(s.zoomBacklog, elapsed);
+            const apply = () => {
+                transaction(() => {
+                    if (step !== 0 && originLeft !== undefined) {
+                        const offset = s.lastClientX - originLeft;
+                        let moved = false;
+                        for (const view of target.views) {
+                            const before = view.bpPerPx;
+                            view.zoomTo(before * Math.exp(step), offset);
+                            moved ||= view.bpPerPx !== before;
+                        }
+                        // pinned at a zoom limit, the rest can never land
+                        s.zoomBacklog = moved ? s.zoomBacklog - step : 0;
+                    }
+                    if (s.scrollDelta !== 0) {
+                        for (const view of target.views) {
+                            view.horizontalScroll(s.scrollDelta);
+                        }
+                    }
+                });
+            };
+            if (target.hold) {
+                target.hold(apply);
+            }
+            else {
+                apply();
+            }
+        }
+        else {
+            s.zoomBacklog = 0;
+        }
+        s.scrollDelta = 0;
+        if (s.zoomBacklog !== 0) {
+            frame.schedule(flush);
+        }
+        else {
+            s.lastRafTime = null;
+        }
+    }
+    function onWheel(event) {
+        onEvent?.(event);
+        // A nested vertical scroller preventDefaults exactly what it consumed, and
+        // that flag is still readable on the way up, so the view declines what a
+        // panel is already scrolling: a trackpad emits a small deltaX alongside
+        // every vertical swipe, which used to pan the genome sideways under someone
+        // who was only scrolling reads. No timer of our own — the scroll latch
+        // holds the whole continuous gesture, boundary included, and releasing it
+        // is the pause that ends the gesture.
+        const gated = event.defaultPrevented || (presence !== undefined && !presence.isOver);
+        const target = gated ? undefined : resolveTarget(event);
+        if (target && !(event.shiftKey && target.scrollZoom)) {
+            // a gap longer than the frame-elapsed clamp means this event starts a new
+            // gesture, so the previous frame time is meaningless — including when it
+            // predates a spell in a backgrounded tab, where a huge elapsed would
+            // otherwise lift the zoom rate limit on the first frame back
+            if (!isActivelyZooming(event.timeStamp, s.lastEventTime)) {
+                s.lastRafTime = null;
+                s.originLeft = undefined;
+            }
+            s.lastEventTime = event.timeStamp;
+            s.target = target;
+            const deltaY = normalizeWheelDelta(event.deltaY, event.deltaMode);
+            const deltaX = normalizeWheelDelta(event.deltaX, event.deltaMode);
+            const isCtrlZoom = event.ctrlKey || event.metaKey;
+            const isZoom = isCtrlZoom ||
+                (target.scrollZoom && Math.abs(deltaY) >= Math.abs(deltaX));
+            if (isZoom) {
+                // warn once per latched run, not once per event — a non-cancelable
+                // sequence fires ~100 events/sec and console.warn is not free
+                if (event.cancelable) {
+                    s.warnedNonCancelable = false;
+                }
+                else if (!s.warnedNonCancelable) {
+                    s.warnedNonCancelable = true;
+                    console.warn('[wheelZoom] wheel event not cancelable — scroll sequence already in progress');
+                }
+                event.preventDefault();
+                s.zoomBacklog = addToZoomBacklog(s.zoomBacklog, wheelZoomAccum(deltaY, isCtrlZoom));
+                s.lastClientX = event.clientX;
+                s.lastZoomTime = event.timeStamp;
+                // drop any side-scroll accumulated earlier this frame — we're zooming,
+                // and a deltaX that arrived just before the zoom is part of the same
+                // noisy gesture
+                s.scrollDelta = 0;
+            }
+            else if (isActivelyZooming(event.timeStamp, s.lastZoomTime)) {
+                // ignore stray horizontal deltas that arrive mid-zoom — trackpads emit
+                // an unintentional side-scroll during a pinch/scroll-zoom gesture that
+                // would otherwise pan the view away from where the user is zooming.
+                // preventDefault anyway so the page itself doesn't scroll instead.
+                event.preventDefault();
+            }
+            else {
+                // With scrollZoom on, swallow the gesture even though it fell outside
+                // the zoom threshold: without this, a diagonal trackpad gesture whose
+                // |deltaX| slightly exceeds |deltaY| slips through and scrolls the page
+                // (shift+wheel above is the deliberate exception). With scrollZoom
+                // off, only swallow what we are about to pan with, so a plain vertical
+                // wheel isn't silently eaten.
+                if (swallowUnhandled ||
+                    target.scrollZoom ||
+                    Math.abs(deltaX) > Math.abs(2 * deltaY)) {
+                    event.preventDefault();
+                }
+                // Pan on a gesture that is actually sideways. A trackpad puts a small
+                // deltaX on every vertical swipe, and panning on it drifted the genome
+                // under anyone scrolling a track — including where no panel handler
+                // reports the scroll for us to decline, as with the natively-scrolling
+                // pinned-tracks block. Ties go vertical, the same way the zoom test
+                // above resolves them. With scrollZoom on this changes nothing: a
+                // vertical-dominant wheel was already taken as a zoom.
+                if (Math.abs(deltaX) > Math.abs(deltaY)) {
+                    s.scrollDelta = accumulateScroll(s.scrollDelta, deltaX);
+                }
+            }
+            frame.schedule(flush);
+        }
+    }
+    element.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+        element.removeEventListener('wheel', onWheel);
+        presence?.dispose();
+        // so a flush can't fire against a detached view
+        frame.cancel();
+    };
+}

package/esm/util/whenViewSettled.d.ts

@@ -0,0 +1,74 @@
+export interface SettleableView {
+    initialized: boolean;
+    error: unknown;
+    pendingLaunch?: unknown;
+}
+/**
+ * A view that is up AND has finished applying whatever launched it.
+ *
+ * Both terms, for the reason spelled out on {@link whenViewSettled} below.
+ * Exported because AppReadyMarker decides the same thing from the same model
+ * for the whole app, the two drifted on exactly this second term, and
+ * `readinessTerms.test.tsx` in app-core now holds them together.
+ */
+export declare const viewSettled: (view: SettleableView) => boolean;
+/**
+ * Wait until a view has either initialized — launch blob consumed and all — or
+ * failed, and report which.
+ *
+ * `initialized` folds in a view's assemblies, so an assembly that fails to load
+ * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * export hung behind its dialog's spinner, and a launched breakpoint split view
+ * that opened but was never navigated or zoomed.
+ *
+ * `pendingLaunch` is the other half, and it matters because `initialized` can
+ * go true MID-launch: LGV's flips the moment displayedRegions land, while the
+ * same apply pass still has tracks to attach — so a caller acting there reads a
+ * positioned view with its tracks missing (an SVG export saves it that way).
+ * A launch failure cannot hang this: the state machine either clears the blob
+ * (materialized, reported as a snackbar) or sets the view's `error`
+ * (installInitAutorun's failure policy). A view with no launch machinery has no
+ * `pendingLaunch` and the term is vacuously satisfied.
+ *
+ * Every view exposes a resolved `error` beside `initialized`, so waiting on the
+ * pair turns the hang into something reportable. What to report is the caller's,
+ * because the vocabularies genuinely differ — an export says "cannot export"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * No time bound, deliberately: `(initialized && launch consumed) || error` is a
+ * terminal set, so a slow-but-healthy remote assembly is waited out rather than
+ * guessed at. `escape` is how a caller adds the one term that is not the view's
+ * own — a session-level render failure for an export, `superseded` for a view
+ * an `installInitAutorun` apply is waiting on — which is what keeps a caller
+ * from re-spelling the whole predicate around it.
+ *
+ * **Not for the view whose `apply` you are inside.** `applyInitOnce` clears the
+ * launch blob only after awaiting `apply`, so `pendingLaunch` is held for the
+ * whole of it and this can end only on `escape` or `error`, never on success.
+ * A wait on `self` stays hand-rolled; `reference/VIEW_INIT.md` has the shape.
+ *
+ * @returns true if the view initialized (and consumed any launch), false if it
+ * settled on an error
+ */
+export declare function whenViewSettled(view: SettleableView, escape?: () => boolean): Promise<boolean>;
+/**
+ * The same wait over several views at once — a synteny view's genome rows. An
+ * SVG export of a split view keeps its own per-panel loop instead: the split
+ * view's `initialized` folds in `views.every(v => v.initialized)` but not each
+ * panel's own `pendingLaunch`, so that loop is waiting on a different question
+ * by the time it runs.
+ *
+ * One predicate over `every`, never `Promise.all` of the single form: `when`
+ * returns a cancellable promise, so racing N of them against an escape leaves
+ * N-1 live reactions behind on the path that escapes. This is one reaction with
+ * nothing to cancel.
+ *
+ * @returns true if every view initialized, false if any settled on an error or
+ * the escape fired
+ */
+export declare function whenViewsSettled(views: SettleableView[], escape?: () => boolean): Promise<boolean>;

package/esm/util/whenViewSettled.js

@@ -0,0 +1,77 @@
+import { when } from 'mobx';
+/**
+ * A view that is up AND has finished applying whatever launched it.
+ *
+ * Both terms, for the reason spelled out on {@link whenViewSettled} below.
+ * Exported because AppReadyMarker decides the same thing from the same model
+ * for the whole app, the two drifted on exactly this second term, and
+ * `readinessTerms.test.tsx` in app-core now holds them together.
+ */
+export const viewSettled = (view) => view.initialized && view.pendingLaunch === undefined;
+const done = (view) => viewSettled(view) || !!view.error;
+/**
+ * Wait until a view has either initialized — launch blob consumed and all — or
+ * failed, and report which.
+ *
+ * `initialized` folds in a view's assemblies, so an assembly that fails to load
+ * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * export hung behind its dialog's spinner, and a launched breakpoint split view
+ * that opened but was never navigated or zoomed.
+ *
+ * `pendingLaunch` is the other half, and it matters because `initialized` can
+ * go true MID-launch: LGV's flips the moment displayedRegions land, while the
+ * same apply pass still has tracks to attach — so a caller acting there reads a
+ * positioned view with its tracks missing (an SVG export saves it that way).
+ * A launch failure cannot hang this: the state machine either clears the blob
+ * (materialized, reported as a snackbar) or sets the view's `error`
+ * (installInitAutorun's failure policy). A view with no launch machinery has no
+ * `pendingLaunch` and the term is vacuously satisfied.
+ *
+ * Every view exposes a resolved `error` beside `initialized`, so waiting on the
+ * pair turns the hang into something reportable. What to report is the caller's,
+ * because the vocabularies genuinely differ — an export says "cannot export"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * No time bound, deliberately: `(initialized && launch consumed) || error` is a
+ * terminal set, so a slow-but-healthy remote assembly is waited out rather than
+ * guessed at. `escape` is how a caller adds the one term that is not the view's
+ * own — a session-level render failure for an export, `superseded` for a view
+ * an `installInitAutorun` apply is waiting on — which is what keeps a caller
+ * from re-spelling the whole predicate around it.
+ *
+ * **Not for the view whose `apply` you are inside.** `applyInitOnce` clears the
+ * launch blob only after awaiting `apply`, so `pendingLaunch` is held for the
+ * whole of it and this can end only on `escape` or `error`, never on success.
+ * A wait on `self` stays hand-rolled; `reference/VIEW_INIT.md` has the shape.
+ *
+ * @returns true if the view initialized (and consumed any launch), false if it
+ * settled on an error
+ */
+export async function whenViewSettled(view, escape = () => false) {
+    await when(() => escape() || done(view));
+    return viewSettled(view);
+}
+/**
+ * The same wait over several views at once — a synteny view's genome rows. An
+ * SVG export of a split view keeps its own per-panel loop instead: the split
+ * view's `initialized` folds in `views.every(v => v.initialized)` but not each
+ * panel's own `pendingLaunch`, so that loop is waiting on a different question
+ * by the time it runs.
+ *
+ * One predicate over `every`, never `Promise.all` of the single form: `when`
+ * returns a cancellable promise, so racing N of them against an escape leaves
+ * N-1 live reactions behind on the path that escapes. This is one reaction with
+ * nothing to cancel.
+ *
+ * @returns true if every view initialized, false if any settled on an error or
+ * the escape fired
+ */
+export async function whenViewsSettled(views, escape = () => false) {
+    await when(() => escape() || views.every(done));
+    return views.every(viewSettled);
+}

package/esm/util/withFeatureDetails.d.ts

@@ -0,0 +1,34 @@
+import type { Feature } from './simpleFeature.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export declare function withFeatureDetails(self: IStateTreeNode, fetch: () => Promise<Feature | undefined>, onFeat: (feat: Feature) => void, onMiss?: () => void): Promise<void>;

package/esm/util/withFeatureDetails.js

@@ -0,0 +1,59 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { notifyFeatureDetailsMiss } from './openFeatureWidget.js';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export async function withFeatureDetails(self, fetch, onFeat, onMiss = () => {
+    notifyFeatureDetailsMiss(self);
+}) {
+    try {
+        const feature = await fetch();
+        if (!isAlive(self)) {
+            return;
+        }
+        if (feature) {
+            onFeat(feature);
+        }
+        else {
+            onMiss();
+        }
+    }
+    catch (e) {
+        // Logged whatever happened, and only toasted while the display is still
+        // there: `getSession` throws on a detached node, and a message naming a
+        // track the user has already closed is noise they cannot act on.
+        console.error(e);
+        if (isAlive(self)) {
+            getNotificationSink(self).notifyError(`${e}`, e);
+        }
+    }
+}