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

package/esm/util/useVirtualScrollWheel.js

@@ -58,7 +58,17 @@ onWheel) {
     // not-yet-committed model read.
     const runningRef = useRef(0);
     const applyScroll = useCallback((e, { scrollTop, viewportHeight, scrollableHeight }, commit) => {
-        if (scrollableHeight <= 0) {
+        // Each handler takes the gesture whose dominant axis is its own: a
+        // sideways swipe belongs to the view's pan, and consuming its small
+        // vertical component would both drift the panel and — since consuming
+        // means preventDefault, which is how the view knows to stay out — kill
+        // the pan the user actually asked for. A tie is vertical, matching the
+        // view's own zoom-vs-pan tie-break. Raw deltas, because both axes of one
+        // event share a deltaMode. `holds` is what keeps this from cutting a
+        // gesture in half: once the panel has latched, the sideways momentum
+        // trailing a vertical scroll stays with the panel.
+        const sideways = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+        if (scrollableHeight <= 0 || (sideways && !latch.holds(e))) {
             return;
         }
         // A fresh frame (nothing pending) re-syncs to the model's live scrollTop;

package/esm/util/viewStatus.d.ts

@@ -56,3 +56,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

@@ -18,3 +18,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

package/esm/util/wheelZoom.js

@@ -89,9 +89,10 @@ export function applyZoomAccum(bpPerPx, zoomAccum, elapsedMs) {
 /**
  * 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
@@ -141,26 +142,41 @@ export function createWheelZoomController({ element, resolveTarget, swallowUnhan
                 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);
+            const apply = () => {
+                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 (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();
+            }
         }
         s.zoomAccum = 0;
         s.scrollDelta = 0;
     }
     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
@@ -216,7 +232,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,6 @@
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * 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 +10,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 +26,15 @@
  * 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.
  *
- * @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;
+    pendingLaunch?: unknown;
 }): Promise<boolean>;

package/esm/util/whenViewSettled.js

@@ -1,6 +1,7 @@
 import { when } from 'mobx';
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * 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 +11,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 +27,15 @@ 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.
  *
- * @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 async function whenViewSettled(view) {
-    await when(() => view.initialized || !!view.error);
-    return view.initialized;
+    const ready = () => view.initialized && view.pendingLaunch === undefined;
+    await when(() => ready() || !!view.error);
+    return ready();
 }

package/esm/util/withLaunchInput.d.ts

@@ -0,0 +1,168 @@
+export { legacyInitMessage, unknownKeysMessage } from './unknownSnapshotKeys.ts';
+import type { IAnyModelType, IModelType, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+/**
+ * The slice of a PluginManager the partition reads: which view type a
+ * snapshot's `type` names, and that type's state model as REGISTERED — the
+ * one `extendViewType` may have composed more properties onto after the
+ * factory wrapped its own.
+ */
+export interface ViewTypeLookup {
+    viewTypes: {
+        has: (name: string) => boolean;
+    };
+    getViewType: (name: string) => {
+        isStateModelLoaded: boolean;
+        stateModel: IAnyModelType;
+    };
+}
+export interface LaunchInputOptions<M extends IAnyModelType> {
+    /** the PluginManager; without it the partition sees only the wrapped model */
+    registry?: ViewTypeLookup;
+    /**
+     * Whether a snapshot shows the launch applied — rows built, regions set. The
+     * blob persists only until then: a snapshot taken mid-load (an autosave
+     * firing before the launch autorun navigates) has to rebuild the view rather
+     * than drop it to the import form, and a materialized view has nothing left
+     * to rebuild. `installInitAutorun` keys its failure policy off the same line,
+     * read from the live node. `Partial` because a `stripDefault` property is
+     * absent from the snapshot when empty, whatever its declared type says.
+     */
+    materialized: (snap: Partial<SnapshotOut<M>>) => boolean;
+}
+/**
+ * How a launch key's value is told apart from the state property of the same
+ * name. A key whose name collides with nothing is `launch`; the rest name the
+ * discriminator that splits one authored array into the recipe entries the
+ * launcher resolves and the built snapshots MST restores.
+ *
+ * `replay` is the one that is not remapped at all: the value lands on its
+ * property, and a copy rides in the blob so the launcher can run the ordered
+ * imperative step the property write alone does not produce.
+ */
+export type LaunchKeyKind = 'launch' | 'trackEntries' | 'rows' | 'highlightEntries' | 'replay';
+export interface LaunchKeySpec {
+    kind: LaunchKeyKind;
+}
+export interface LaunchKeyRegistration<Commands, PassThrough extends string = never> {
+    keys: Record<string, LaunchKeySpec>;
+    passThrough: readonly PassThrough[];
+    /** never assigned; it carries `Commands` to `withLaunchInput`'s return type */
+    commands?: Commands;
+}
+/**
+ * The launch keys a view captured, plus what it has to report.
+ *
+ * `Commands` is not made partial: hand-authored JSON is what fills this, so a
+ * key the interface marks required is not a guarantee here either way, and the
+ * launcher already guards the ones it cannot proceed without.
+ */
+export type LaunchInput<Commands> = Commands & {
+    unknown?: Record<string, unknown>;
+    malformed?: Record<string, unknown>;
+    legacyInit?: boolean;
+};
+/**
+ * The blob when it still holds something to apply, else undefined. A view's
+ * gates ask this rather than the raw property: a snapshot whose only launch
+ * content was a typo has nothing to launch, and a view that thinks otherwise
+ * waits on an assembly nobody named and never leaves the spinner.
+ *
+ * Returns the blob itself, never a copy — the launch autorun clears by
+ * identity, and a fresh object per read strands the init it just applied.
+ */
+export declare function pendingLaunch<C>(launch: LaunchInput<C> | undefined): LaunchInput<C> | undefined;
+/**
+ * A view's snapshot type, widened to the authored shape: every launch key is
+ * accepted beside the declared properties, and a key that is both takes either
+ * meaning. Excess-property checking then makes a misspelled key an error at
+ * every literal site — a `defaultSession` view, an `addView` call, a
+ * `createViewState` spec.
+ */
+export type LaunchSnapshotIn<M extends IAnyModelType, Commands, PassThrough extends string = never> = Omit<SnapshotIn<M>, keyof Commands> & {
+    [K in keyof Commands]?: K extends keyof SnapshotIn<M> ? Commands[K] | SnapshotIn<M>[K] : Commands[K];
+} & {
+    [K in PassThrough]?: unknown;
+} & {
+    /**
+     * @deprecated v4's nesting. Write every setting directly on the view object;
+     * this is unwrapped on the way in and warns.
+     */
+    init?: Commands;
+};
+type ReservedKey = 'id' | 'type' | 'launch';
+/**
+ * What a view can be launched with, derived: the keys its launcher interprets
+ * (`Commands`) plus every declared property of its state model, optional, in
+ * the property's own snapshot type. Nothing is restated, so a property is
+ * authorable — and TYPED — from the line that declares it.
+ *
+ * ```ts
+ * export type LinearSyntenyViewInit = ViewInit<
+ *   LinearSyntenyViewStateModel,
+ *   LinearSyntenyViewCommands
+ * >
+ * ```
+ *
+ * The twin of `LaunchSnapshotIn` above, from the other end: that one widens a
+ * snapshot type for a literal MST site, this one is what a caller BUILDING a
+ * spec annotates, so its commands stay required and its properties optional.
+ */
+export type ViewInit<M extends IAnyModelType, Commands> = Commands & Partial<Omit<SnapshotIn<M>, keyof Commands | ReservedKey>>;
+export type LaunchInputModel<M extends IAnyModelType, Commands, PassThrough extends string = never> = M extends IModelType<infer P, infer O, any, infer S> ? IModelType<P, O, LaunchSnapshotIn<M, Commands, PassThrough>, S> : never;
+/**
+ * Declare one view's launch keys. The argument is
+ * `Record<keyof Commands, LaunchKeySpec>`, so a command the view interprets and
+ * nobody registered is a compile error rather than a key that partitions as a
+ * typo and warns.
+ *
+ * `passThrough` names keys that are neither a launch key nor a declared
+ * property and still belong on the snapshot — a legacy spelling the view's own
+ * `preProcessSnapshot` converts.
+ */
+export declare function defineLaunchKeys<Commands>(): <const P extends readonly string[] = readonly never[]>(keys: Record<keyof Commands, LaunchKeySpec>, { passThrough }?: {
+    passThrough?: P;
+}) => LaunchKeyRegistration<Commands, P[number]>;
+/**
+ * The part of a launch spec that belongs on the snapshot: everything but the
+ * launch keys, and the identity and `launch` keys no spec may set. For a caller
+ * that applies the launch itself and builds the view from a snapshot — a
+ * synteny row, whose parent navigates it and opens its tracks — so what it
+ * hands MST is settings only, and the view's own partition sorts those into
+ * properties and reported typos.
+ */
+export declare function snapshotSettings(spec: Record<string, unknown>, registration: LaunchKeyRegistration<unknown, string> | undefined): {
+    [k: string]: unknown;
+};
+/**
+ * Accept a view's settings written directly on the view object, and move the
+ * ones a launcher has to resolve into the internal `launch` property.
+ *
+ * The partition is a `preProcessSnapshot` and is PURE. A session's view type is
+ * a `types.union`, so MST runs every member's preprocessor against every
+ * candidate snapshot while deciding which one matches, and runs it about twice
+ * more per instantiation; a warning from in here fires against snapshots that
+ * are about to be rejected. `afterAttach` — reached only by a snapshot that won
+ * — reports what the partition captured.
+ *
+ * `registry` is the PluginManager. With it the partition classifies against
+ * the view type as registered, `extendViewType`'s added properties included;
+ * without it, against the model as wrapped here. `materialized` draws the line
+ * past which the blob is no longer persisted; see `LaunchInputOptions`.
+ *
+ * ORDER: MST runs preprocessors in the reverse of the order they were added, so
+ * this belongs on the chain BEFORE a view's own legacy-key preprocessor, where
+ * it partitions the snapshot MST finally consumes rather than a key that remap
+ * is about to convert.
+ *
+ * The widening cast is the LAST link that may change the creation type: it
+ * replaces `CustomC`, so a `.props()` added after it is invisible to
+ * `SnapshotIn`. Further `preProcessSnapshot`/`postProcessSnapshot` links are
+ * fine — both carry `CustomC` through.
+ *
+ * Not `types.snapshotProcessor`, which carries the same widened input and stops
+ * being a `ModelType`. `PluginManager.pluggableMstType` filters union members on
+ * `isModelType`, so a wrapped view is dropped from the session's view union
+ * without a word, and `ViewType.stateModel` and every `.properties`
+ * introspection site break with it.
+ */
+export declare function withLaunchInput<M extends IAnyModelType, Commands, PassThrough extends string>(model: M, registration: LaunchKeyRegistration<Commands, PassThrough>, { registry, materialized }: LaunchInputOptions<M>): LaunchInputModel<M, Commands, PassThrough>;