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

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

package/esm/util/viewHighlights.js

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

package/esm/util/viewStatus.d.ts

@@ -1,13 +1,27 @@
+/**
+ * What a view's loading screen says: the label, the determinate fraction when
+ * the load reports one, and the URL being fetched when the phase named one.
+ */
+export interface ViewLoading {
+    message: string;
+    progress: number | undefined;
+    source?: string;
+}
+interface LoadingAssembly {
+    statusMessage?: string;
+    statusProgress?: number;
+    statusSource?: string;
+}
+/**
+ * A view's `loading` getter: undefined unless `showLoading`, and otherwise read
+ * off the assembly whose load is the wait. The assembly is a thunk because its
+ * status ticks while a file is in flight, and a view that is not loading should
+ * not subscribe to it.
+ */
+export declare function viewLoading(showLoading: boolean, assembly: () => LoadingAssembly | undefined): ViewLoading | undefined;
 /**
  * The mutually-exclusive lifecycle state of a view, as one value.
  *
- * 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.
  */
@@ -16,11 +30,9 @@ export type ViewStatus = {
 } | {
     type: 'error';
     error: unknown;
-} | {
+} | ({
     type: 'loading';
-    message: string;
-    progress: number | undefined;
-} | {
+} & ViewLoading) | {
     type: 'noRegions';
 };
 export interface ViewStatusInputs {
@@ -40,10 +52,7 @@ export interface ViewStatusInputs {
      * would make every reader of a *ready* view subscribe to a churning
      * observable it never displays.
      */
-    loading: () => {
-        message: string;
-        progress: number | undefined;
-    } | undefined;
+    loading: () => ViewLoading | undefined;
 }
 /**
  * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
@@ -56,3 +65,26 @@ export interface ViewStatusInputs {
  * 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

@@ -1,3 +1,20 @@
+/**
+ * A view's `loading` getter: undefined unless `showLoading`, and otherwise read
+ * off the assembly whose load is the wait. The assembly is a thunk because its
+ * status ticks while a file is in flight, and a view that is not loading should
+ * not subscribe to it.
+ */
+export function viewLoading(showLoading, assembly) {
+    if (!showLoading) {
+        return undefined;
+    }
+    const asm = assembly();
+    return {
+        message: asm?.statusMessage || 'Loading',
+        progress: asm?.statusProgress,
+        source: asm?.statusSource,
+    };
+}
 /**
  * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
  * rather than re-encoded by subtraction in each view and again in each host.
@@ -18,3 +35,20 @@ export function computeViewStatus({ error, hasSomethingToShow, loading, }) {
     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/wheelZoom.d.ts

@@ -17,6 +17,7 @@ export interface WheelZoomTarget {
     views: WheelZoomView[];
     scrollZoom: boolean;
     originElement: () => HTMLElement | undefined;
+    hold?: <T>(fn: () => T) => T;
 }
 export interface WheelZoomControllerOptions {
     element: HTMLElement;
@@ -37,9 +38,10 @@ export interface WheelZoomControllerOptions {
 /**
  * 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 horizontal delta, unless one arrives mid-zoom   → pan by dx
+ *   - 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
@@ -54,6 +56,10 @@ export interface WheelZoomControllerOptions {
  * inertial scroll) collapses to a single update per frame instead of thrashing
  * the views once per event.
  *
+ * A zoom lands eased over the frames after its event (`easeZoomBacklog`), and
+ * all of it lands: how far a gesture zooms depends on the wheel alone, never on
+ * the frame rate or how the events happened to fall into frames.
+ *
  * Returns its disposer.
  */
 export declare function createWheelZoomController({ element, resolveTarget, swallowUnhandled, releaseOnPointerLeave, onEvent, }: WheelZoomControllerOptions): () => void;

package/esm/util/wheelZoom.js

@@ -86,12 +86,33 @@ export function applyZoomAccum(bpPerPx, zoomAccum, 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 horizontal delta, unless one arrives mid-zoom   → pan by dx
+ *   - 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
@@ -106,13 +127,17 @@ export function applyZoomAccum(bpPerPx, zoomAccum, elapsedMs) {
  * 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,
-        zoomAccum: 0,
+        zoomBacklog: 0,
         target: undefined,
         lastClientX: 0,
         originLeft: undefined,
@@ -127,7 +152,7 @@ export function createWheelZoomController({ element, resolveTarget, swallowUnhan
     const presence = releaseOnPointerLeave
         ? trackPointerPresence(element, () => {
             s.scrollDelta = 0;
-            s.zoomAccum = 0;
+            s.zoomBacklog = 0;
             s.originLeft = undefined;
         })
         : undefined;
@@ -137,30 +162,62 @@ export function createWheelZoomController({ element, resolveTarget, swallowUnhan
         const { target } = s;
         if (target) {
             const origin = target.originElement();
-            if (s.zoomAccum !== 0 && origin && s.originLeft === undefined) {
+            if (s.zoomBacklog !== 0 && origin && s.originLeft === undefined) {
                 s.originLeft = origin.getBoundingClientRect().left;
             }
             const originLeft = s.originLeft;
-            transaction(() => {
-                if (s.zoomAccum !== 0 && originLeft !== undefined) {
-                    const offset = s.lastClientX - originLeft;
-                    for (const view of target.views) {
-                        view.zoomTo(applyZoomAccum(view.bpPerPx, s.zoomAccum, elapsed), offset);
+            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 (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.zoomAccum = 0;
         s.scrollDelta = 0;
+        if (s.zoomBacklog !== 0) {
+            frame.schedule(flush);
+        }
+        else {
+            s.lastRafTime = null;
+        }
     }
     function onWheel(event) {
         onEvent?.(event);
-        const gated = presence !== undefined && !presence.isOver;
+        // 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
@@ -189,7 +246,7 @@ export function createWheelZoomController({ element, resolveTarget, swallowUnhan
                     console.warn('[wheelZoom] wheel event not cancelable — scroll sequence already in progress');
                 }
                 event.preventDefault();
-                s.zoomAccum += wheelZoomAccum(deltaY, isCtrlZoom);
+                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,
@@ -216,7 +273,16 @@ export function createWheelZoomController({ element, resolveTarget, swallowUnhan
                     Math.abs(deltaX) > Math.abs(2 * deltaY)) {
                     event.preventDefault();
                 }
-                s.scrollDelta = accumulateScroll(s.scrollDelta, deltaX);
+                // 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);
         }

package/esm/util/whenViewSettled.d.ts

@@ -1,5 +1,20 @@
+export interface SettleableView {
+    initialized: boolean;
+    error: unknown;
+    pendingLaunch?: unknown;
+}
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * 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
@@ -9,6 +24,15 @@
  * 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"
@@ -16,12 +40,35 @@
  * says the launch failed — which is why this returns the answer instead of
  * throwing one wording at both.
  *
- * No time bound, deliberately: `initialized || error` is a terminal pair, so a
- * slow-but-healthy remote assembly is waited out rather than guessed at.
+ * 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, false if it settled on an error
+ * @returns true if the view initialized (and consumed any launch), false if it
+ * settled on an error
  */
-export declare function whenViewSettled(view: {
-    initialized: boolean;
-    error: unknown;
-}): Promise<boolean>;
+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

@@ -1,6 +1,17 @@
 import { when } from 'mobx';
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * 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
@@ -10,6 +21,15 @@ import { when } from 'mobx';
  * 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"
@@ -17,12 +37,41 @@ import { when } from 'mobx';
  * says the launch failed — which is why this returns the answer instead of
  * throwing one wording at both.
  *
- * No time bound, deliberately: `initialized || error` is a terminal pair, so a
- * slow-but-healthy remote assembly is waited out rather than guessed at.
+ * 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 the view initialized, false if it settled on an error
+ * @returns true if every view initialized, false if any settled on an error or
+ * the escape fired
  */
-export async function whenViewSettled(view) {
-    await when(() => view.initialized || !!view.error);
-    return view.initialized;
+export async function whenViewsSettled(views, escape = () => false) {
+    await when(() => escape() || views.every(done));
+    return views.every(viewSettled);
 }