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

package/esm/util/tracks.js

@@ -8,9 +8,9 @@ export { getFileName } from './getFileName.js';
 // it. `fetchContext.ts` takes it from mstUtils instead, which is what keeps the
 // configuration schemas this file pulls in out of the fetch harness's graph.
 export { getRpcSessionId } from './parentWalk.js';
-import { getParent, getSnapshot, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getParent, getSnapshot, hasParent, isAlive, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import { observable, runInAction, untracked } from 'mobx';
-import { isConfigurationSlot, preProcessSlotValues, readConfObject, } from '../configuration/index.js';
+import { readConfObject } from '../configuration/index.js';
 import { getFileHandle, storeFileHandle, verifyPermission, } from './fileHandleStore.js';
 import { getFileName } from './getFileName.js';
 import { getContainingView, getEnv, getSession, objectHash, } from './mstUtils.js';
@@ -76,12 +76,22 @@ export function isSameAssemblyName(a, b, assemblyManager) {
  * `ReferenceSequenceTrack` does not — its schema omits the slot deliberately
  * (see `createReferenceSeqTrackConfig`), because the assembly config holding it
  * IS its assembly, so the name is read off the parent instead.
+ *
+ * That makes a sequence track's assembly **positional**, so a copy of one that
+ * is not inside its assembly cannot answer at all — and a detached config is
+ * what every hydration path produces (`hydrateTrackConfig`, and the working
+ * copy a non-admin's edits would go to, ADR-032). `hasParent` is the guard:
+ * without it the walk raises MST's "Failed to find the parent" from a helper
+ * whose other two failure modes are a plain `undefined`.
  */
 function confAssemblyNames(conf) {
     const trackAssemblyNames = readConfObject(conf, 'assemblyNames');
     if (trackAssemblyNames) {
         return trackAssemblyNames;
     }
+    if (!hasParent(conf)) {
+        return undefined;
+    }
     const parent = getParent(conf);
     return 'sequence' in parent
         ? [readConfObject(parent, 'name')]
@@ -368,8 +378,12 @@ export function guessAdapter(file, index, adapterHint, model) {
 }
 export function guessTrackType(adapterType, model, file) {
     if (model) {
-        const session = getSession(model);
-        const trackTypeGuesser = getEnv(session).pluginManager.evaluateExtensionPoint(
+        // getEnv(model), not getEnv(getSession(model)): the env is tree-wide, so
+        // the session hop only narrowed what may be passed here — a session itself
+        // has no session ancestor, so guessAdapter above accepted one and this
+        // threw on it
+        const { pluginManager } = getEnv(model);
+        const trackTypeGuesser = pluginManager.evaluateExtensionPoint(
         /** #extensionPoint Core-guessTrackTypeForLocation | sync | Guess a track type from a file location */
         'Core-guessTrackTypeForLocation', () => undefined);
         const trackType = trackTypeGuesser(adapterType, file);
@@ -392,24 +406,35 @@ export function guessTrackType(adapterType, model, file) {
  */
 export function guessTrackConf(input, pluginManager, assemblyName) {
     const { uri, index, ...extra } = typeof input === 'string' ? { uri: input } : input;
-    const file = { uri, locationType: 'UriLocation' };
-    const indexLocation = index
-        ? { uri: index, locationType: 'UriLocation' }
-        : undefined;
+    return {
+        ...guessTrackConfForLocation({ uri, locationType: 'UriLocation' }, index ? { uri: index, locationType: 'UriLocation' } : undefined, pluginManager, assemblyName),
+        ...extra,
+    };
+}
+/**
+ * {@link guessTrackConf} over an already-built {@link FileLocation}, for a
+ * caller holding a location the loose `{ uri }` vocabulary cannot spell — a
+ * desktop local path. Kept separate so `LooseTrackInput` stays URI-only: it
+ * sits on the track-config union and the root config's `tracks`, where a
+ * local path would be a config a web deployment could not open.
+ *
+ * The `trackId` is a content hash of the adapter, not a timestamp, so adding
+ * the same file twice is idempotent — `addToSession` dedupes on it.
+ */
+export function guessTrackConfForLocation(file, index, pluginManager, assemblyName) {
     const adapterGuesser = pluginManager.evaluateExtensionPoint('Core-guessAdapterForLocation', () => undefined);
-    const adapter = adapterGuesser(file, indexLocation, undefined);
+    const adapter = adapterGuesser(file, index, undefined);
+    const name = getFileName(file);
     if (!adapter || adapter.type === UNKNOWN) {
-        throw new Error(`could not infer a track type from "${uri}"; pass a full track config instead`);
+        throw new Error(`could not infer a track type from "${name}"; pass a full track config instead`);
     }
     const trackTypeGuesser = pluginManager.evaluateExtensionPoint('Core-guessTrackTypeForLocation', () => undefined);
-    const name = getFileName(file);
     return {
         trackId: `${name}-${objectHash(adapter).slice(0, 8)}`,
         type: trackTypeGuesser(adapter.type, file) ?? 'FeatureTrack',
         name,
         assemblyNames: assemblyName ? [assemblyName] : [],
         adapter,
-        ...extra,
     };
 }
 /**
@@ -572,6 +597,57 @@ export function normalizeTrackInit(t) {
         };
     }
 }
+function resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    // `trackId` seeds the expansion because `guessTrackConf` otherwise
+    // synthesizes one from the filename, and the dedupe in the callers and
+    // `hideTrackGeneric` both look the track up by the id the caller passed.
+    // Only for the loose form: spreading a live MST node (SvInspector's
+    // circular track) would flatten it out of the `isStateTreeNode` branch.
+    const inlineRawConf = isLooseTrackConfig(inlineConf)
+        ? expandLooseTrackConfig({ trackId, ...inlineConf }, pluginManager)
+        : inlineConf;
+    const rawConf = inlineRawConf ?? session.getTrackById(trackId);
+    if (!rawConf) {
+        throw new Error(`Could not resolve identifier "${trackId}"`);
+    }
+    const confSnapshot = structuredClone(isStateTreeNode(rawConf) ? getSnapshot(rawConf) : rawConf);
+    const conf = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', confSnapshot);
+    const trackType = pluginManager.getTrackType(conf.type);
+    // Validate only a conf that is not already in the tree. `configSchema.create`
+    // here builds an entire config node and throws it away purely to surface a
+    // nice error; its preProcessSnapshot also re-runs Core-preProcessTrackConfig
+    // on a snapshot this function just preprocessed. A conf that is a state tree
+    // node was validated when MST created it, so all of that is pure waste on
+    // the common showTrack path.
+    if (!isStateTreeNode(rawConf)) {
+        try {
+            trackType.configSchema.create(conf, getEnv(self));
+        }
+        catch (e) {
+            throw new Error(`Track "${trackId}" has an invalid configuration: ${e}`, {
+                cause: e,
+            });
+        }
+    }
+    // A track container that isn't itself a view — a synteny level, which owns
+    // a track list but has no width and no registered view type — takes the
+    // display choice from the view it sits in, which is the same node
+    // getContainingView already resolves to for everything else beneath it.
+    const view = isViewModel(self) ? self : getContainingView(self);
+    const viewType = pluginManager.getViewType(view.type);
+    const picked = pickDisplayForView({
+        declaredDisplays: conf.displays ?? [],
+        requestedType: displayInitialSnapshot.type,
+        trackDisplayTypes: trackType.displayTypes.map(d => d.name),
+        viewDisplayTypes: viewType.displayTypes.map(d => d.name),
+    });
+    if (!picked) {
+        throw new Error(`Could not find a compatible display for view type ${view.type}`);
+    }
+    return { rawConf, conf, trackType, picked };
+}
 export function showTrackGeneric(self, trackId, 
 // `object`, annotated, rather than inferred from the default. A bare `{}`
 // accepts every non-nullish value, numbers included, which is how a synteny
@@ -597,49 +673,28 @@ inlineConf) {
     // snackbars. Config is validated before the push so the open set never holds
     // a broken track.
     try {
-        const rawConf = (inlineConf && expandLooseTrackConfig(inlineConf, pluginManager)) ??
-            session.getTrackById(trackId);
-        if (!rawConf) {
-            throw new Error(`Could not resolve identifier "${trackId}"`);
-        }
-        const confSnapshot = structuredClone(isStateTreeNode(rawConf) ? getSnapshot(rawConf) : rawConf);
-        const conf = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', confSnapshot);
-        const trackType = pluginManager.getTrackType(conf.type);
-        // Validate only a conf that is not already in the tree. `configSchema.create`
-        // here builds an entire config node and throws it away purely to surface a
-        // nice error; its preProcessSnapshot also re-runs Core-preProcessTrackConfig
-        // on a snapshot this function just preprocessed. A conf that is a state tree
-        // node was validated when MST created it, so all of that is pure waste on
-        // the common showTrack path.
-        if (!isStateTreeNode(rawConf)) {
-            try {
-                trackType.configSchema.create(conf, getEnv(self));
-            }
-            catch (e) {
-                throw new Error(`Track "${trackId}" has an invalid configuration: ${e}`, { cause: e });
-            }
-        }
-        // A track container that isn't itself a view — a synteny level, which owns
-        // a track list but has no width and no registered view type — takes the
-        // display choice from the view it sits in, which is the same node
-        // getContainingView already resolves to for everything else beneath it.
-        const view = isViewModel(self) ? self : getContainingView(self);
-        const viewType = pluginManager.getViewType(view.type);
-        const picked = pickDisplayForView({
-            declaredDisplays: conf.displays ?? [],
-            requestedType: displayInitialSnapshot.type,
-            trackDisplayTypes: trackType.displayTypes.map(d => d.name),
-            viewDisplayTypes: viewType.displayTypes.map(d => d.name),
-        });
-        if (!picked) {
-            throw new Error(`Could not find a compatible display for view type ${view.type}`);
-        }
+        const { rawConf, conf, trackType, picked } = resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf);
         const { type: displayType, conf: displayConf } = picked;
         const displayId = displayConf?.displayId ?? `${trackId}-${displayType}`;
+        // a registered display whose model is not loaded yet: the load re-enters
+        // through the view's own showTrack action, so a synchronous caller gets the
+        // track a tick late; a caller that needs it back awaits launchTrack
+        const displayRecord = pluginManager.resolveDisplayTypeRecord(displayType);
+        if (displayRecord && !displayRecord.isStateModelLoaded) {
+            void launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+            return undefined;
+        }
         const track = trackType.stateModel.create({
             ...initialSnapshot,
             type: conf.type,
-            configuration: inlineConf ?? trackId,
+            // `rawConf`, not the caller's `inlineConf`: the loose `{ trackId, uri }`
+            // form has no `type` for the config schema to dispatch on, and the
+            // concrete schema this lands on carries no loose preprocessor — that one
+            // is on `pluggableConfigSchemaType('track')`, which a track model's
+            // `ConfigurationReference` is not. Not `conf` either: that has already
+            // run Core-preProcessTrackConfig, which the schema's own
+            // preProcessSnapshot runs again.
+            configuration: inlineConf ? rawConf : trackId,
             displays: [
                 {
                     ...displayConf,
@@ -652,23 +707,30 @@ inlineConf) {
         self.tracks.push(track);
         // Display settings (height, color, …) are config slots now, not display
         // instance props — passed in the display snapshot they'd be dropped as
-        // unknown MST keys. Route the ones that are real slots onto the persistent
-        // display config so they take effect and survive hide/retick (#5591). Runs
-        // after the push so the display's config reference can resolve.
+        // unknown MST keys. applyDisplaySettings routes the ones that are real
+        // slots onto the persistent display config so they take effect and
+        // survive hide/retick (#5591), running the schema's preProcessSnapshot
+        // first so shorthand expansions and legacy-key migrations reach this path
+        // too — a session spec, share link, or embed writes slots here rather
+        // than creating a config from a snapshot, and those surfaces are meant to
+        // speak the same vocabulary. Runs after the push so the display's config
+        // reference can resolve. Slots only, deliberately: this is the
+        // declarative surface, and `allowSetters` stays off so a spec key cannot
+        // reach internal display actions.
         //
-        // preProcessSlotValues first, so a display schema's shorthand expansions
-        // and legacy-key migrations reach this path too: a session spec, share
-        // link, or embed writes slots here rather than creating a config from a
-        // snapshot, and those two surfaces are meant to speak the same vocabulary.
-        const display = track.displays[0];
-        const displaySlots = preProcessSlotValues(display.configuration, displayInitialSnapshot);
-        for (const [key, value] of Object.entries(displaySlots)) {
-            if (key !== 'type' && isConfigurationSlot(display.configuration, key)) {
-                // the key comes from a snapshot at runtime, and setConf's slot name is
-                // a compile-time type
-                // eslint-disable-next-line no-restricted-syntax
-                display.configuration.setSlot(key, value);
-            }
+        // `type` is dropped first because this function already consumed it
+        // (pickDisplayForView above), and only `failed` — a key whose write threw —
+        // is notified: `unapplied` here also holds the MST display props the
+        // snapshot spread above already applied, so notifying on it would report a
+        // correct call as broken. A throwing slot value used to reach the outer
+        // catch and raise a snackbar; per-key catching kept the track intact but
+        // took the message away with it.
+        const displaySettings = Object.fromEntries(Object.entries(displayInitialSnapshot).filter(([key]) => key !== 'type'));
+        const report = track.applyDisplaySettings(displaySettings);
+        if (report.failed.length) {
+            session.notifyError(`Track "${trackId}" rejected ${report.failed
+                .map(f => `${f.key}: ${f.error}`)
+                .join('; ')}`);
         }
         // if this track came from a connection, persist its config so it survives
         // reload without re-establishing the connection (no-op otherwise)
@@ -708,6 +770,32 @@ export function toggleTrackGeneric(self, trackId) {
         ? false
         : !!showTrackGeneric(self, trackId);
 }
+export async function launchTrackGeneric(self, trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
+    const { pluginManager } = getEnv(self);
+    const session = getSession(self);
+    const found = self.tracks.find(t => t.configuration.trackId === trackId);
+    if (found) {
+        return found;
+    }
+    try {
+        const { picked } = resolveTrackDisplayChoice(self, trackId, displayInitialSnapshot, inlineConf);
+        await pluginManager.resolveDisplayTypeRecord(picked.type)?.loadStateModel();
+    }
+    catch (e) {
+        session.notifyError(`${e}`, e);
+        return undefined;
+    }
+    if (!isAlive(self)) {
+        return undefined;
+    }
+    return self.showTrack?.(trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+}
+// the hide runs in the synchronous prologue, so it keeps action context
+export async function launchToggleTrackGeneric(self, trackId) {
+    return hideTrackGeneric(self, trackId)
+        ? false
+        : !!(await launchTrackGeneric(self, trackId));
+}
 /**
  * Every track config the session can show, connection-supplied ones included.
  *
@@ -726,3 +814,41 @@ export function allSessionTracks(session) {
         ? [...session.tracks, ...connectionTracks]
         : session.tracks;
 }
+/**
+ * The session's annotation for `assemblyName`, as trackIds: what a view opened
+ * on another genome starts with. Only FeatureTracks, not everything configured
+ * for the assembly — an alignments track turned on behind the user's back
+ * fetches data nobody asked for, and a FeatureTrack over a few kb is one tabix
+ * range query.
+ */
+export function annotationTrackIds(session, assemblyName) {
+    return allSessionTracks(session).flatMap(track => readConfObject(track, 'type') === 'FeatureTrack' &&
+        readConfObject(track, 'assemblyNames').some(name => isSameAssemblyName(name, assemblyName, session.assemblyManager))
+        ? [readConfObject(track, 'trackId')]
+        : []);
+}
+function isNavigableView(view) {
+    return 'navToLocString' in view;
+}
+/**
+ * One assembly on its own in a linear genome view, at `loc`. Keyed on `id`:
+ * following several alignments to one genome re-navigates the view rather than
+ * stacking a new one each time.
+ */
+export async function openAssemblyInLinearView({ session, id, assemblyName, loc, tracks, }) {
+    const view = session.views.find(v => v.id === id);
+    if (view && isNavigableView(view)) {
+        await view.navToLocString(loc, assemblyName);
+    }
+    else {
+        session.addView('LinearGenomeView', {
+            id,
+            assembly: assemblyName,
+            loc,
+            tracks,
+        });
+    }
+}
+export function openMateLabel(assemblyName) {
+    return `Open ${assemblyName} at the matching region`;
+}

package/esm/util/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { ViewSnapshotInput } from '../../PluginManager.ts';
 import type TextSearchManager from '../../TextSearch/TextSearchManager.ts';
 import type { AnyConfigurationModel, ResolvableDisplay } from '../../configuration/index.ts';
 import type { BaseInternetAccountModel } from '../../pluggableElementTypes/models/index.ts';
@@ -22,7 +23,8 @@ export type { AugmentedRegion, BasePlugin, BlobLocation, FileHandleLocation, Fil
 export interface AbstractViewContainer extends IStateTreeNode {
     views: AbstractViewModel[];
     removeView(view: AbstractViewModel): void;
-    addView(typeName: string, initialState?: Record<string, unknown>): AbstractViewModel;
+    addView<N extends string>(typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): AbstractViewModel;
+    launchView(typeName: string, initialState?: Record<string, unknown>): Promise<AbstractViewModel>;
 }
 export declare function isViewContainer(thing: unknown): thing is AbstractViewContainer;
 /**
@@ -32,6 +34,7 @@ export declare function isViewContainer(thing: unknown): thing is AbstractViewCo
  */
 export interface TrackActionView {
     showTrack: (id: string) => void;
+    launchTrack: (id: string) => Promise<unknown>;
     getActiveDisplayId?: (trackId: string) => string | undefined;
 }
 /**
@@ -153,6 +156,21 @@ export interface SessionWithConfigEditing extends AbstractSessionModel {
     }): void;
 }
 export declare function isSessionModelWithConfigEditing(t: unknown): t is SessionWithConfigEditing;
+/**
+ * abstract interface for a session that keeps a list of views, so that `addView`
+ * appends and the view a launch came out of survives it.
+ *
+ * `AbstractViewContainer` alone does not say this. The single-view embedded
+ * products satisfy it with a `views` getter that wraps their one `view` in a
+ * fresh plain array and an `addView` that overwrites that view, so "Open in new
+ * view" there would destroy the view it was offered from. A view list that is
+ * itself part of the state tree is what tells the two apart: only a session
+ * that stores its views can hold one more.
+ */
+export interface SessionWithMultipleViews extends AbstractSessionModel {
+    views: AbstractViewModel[] & IStateTreeNode;
+}
+export declare function isSessionWithMultipleViews(t: unknown): t is SessionWithMultipleViews;
 /**
  * abstract interface for a session that can swap one of its views for a new one
  * of another type, in the slot the old view occupied.
@@ -164,7 +182,7 @@ export declare function isSessionModelWithConfigEditing(t: unknown): t is Sessio
  * and the guard is what a launcher asks before offering it.
  */
 export interface SessionWithViewReplacement extends AbstractSessionModel {
-    replaceView(view: AbstractViewModel, typeName: string, initialState?: Record<string, unknown>): AbstractViewModel;
+    replaceView<N extends string>(view: AbstractViewModel, typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): AbstractViewModel;
 }
 export declare function isSessionWithViewReplacement(t: unknown): t is SessionWithViewReplacement;
 /**
@@ -188,10 +206,10 @@ export declare function canReplaceView(session: AbstractViewContainer, view: Abs
  * that can't replace a view falls back to appending, so a caller passes the
  * source view unconditionally and never has to ask twice.
  */
-export declare function addOrReplaceView({ session, typeName, initialState, replacing, }: {
+export declare function addOrReplaceView<N extends string>({ session, typeName, initialState, replacing, }: {
     session: AbstractViewContainer;
-    typeName: string;
-    initialState?: Record<string, unknown>;
+    typeName: N;
+    initialState?: NoInfer<ViewSnapshotInput<N>>;
     replacing?: AbstractViewModel;
 }): AbstractViewModel;
 /**
@@ -358,21 +376,30 @@ export interface SessionWithSessionPlugins extends AbstractSessionModel {
     removeSessionPlugin: (plugin: PluginDefinition) => void;
 }
 export declare function isSessionWithSessionPlugins(thing: unknown): thing is SessionWithSessionPlugins;
+export interface PermanentPluginsSafeMode {
+    reason: 'requested' | 'previousLaunchFailed';
+    /** what was loading when the launch that failed did not finish */
+    suspects: string[];
+}
 /**
  * A session whose product keeps a plugin list of its own, outside both the
  * config and the session — jbrowse-web's permanent plugins, stored in the
  * browser against the config being viewed, so an install survives a new session
  * and the next visit.
  *
- * The list is not MST state, so `permanentPlugins` re-reads storage on each
- * call and nothing observes it. That is enough for its two readers, both of
- * which run in response to a click: adding or removing one asks for the whole-
- * app reload every plugin change needs anyway.
+ * The plugin store is the whole surface: the pin beside an installed plugin
+ * writes the list, and an entry the load skipped is a row there with a switch
+ * on it, which is what makes the safe mode below something a user can act on.
  */
 export interface SessionWithPermanentPlugins extends AbstractSessionModel {
-    permanentPlugins: PluginDefinition[];
+    permanentPlugins: (PluginDefinition & {
+        disabled?: boolean;
+    })[];
+    permanentPluginsSafeMode: PermanentPluginsSafeMode | undefined;
     addPermanentPlugin: (plugin: PluginDefinition) => void;
     removePermanentPlugin: (plugin: PluginDefinition) => void;
+    setPermanentPluginDisabled: (plugin: PluginDefinition, disabled: boolean) => void;
+    reloadWithPermanentPlugins: () => void;
 }
 export declare function isSessionWithPermanentPlugins(thing: unknown): thing is SessionWithPermanentPlugins;
 /** abstract interface for a session that manages a global selection */
@@ -410,6 +437,13 @@ export interface TrackContainer {
      * silence.
      */
     showTrack: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: Record<string, unknown>, inlineConf?: Record<string, unknown>) => unknown;
+    /**
+     * The sync pair still works on an unloaded display — it loads and shows a
+     * tick later, returning undefined — so these are for a caller that needs
+     * the track back.
+     */
+    launchTrack: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: Record<string, unknown>, inlineConf?: Record<string, unknown>) => Promise<unknown>;
+    launchToggleTrack: (trackId: string) => Promise<unknown>;
     hideTrack: (trackId: string) => unknown;
     toggleTrack: (trackId: string) => unknown;
 }
@@ -453,6 +487,20 @@ export interface AbstractViewModel {
      * `trackContainerFor` cannot answer that — a walker has no id to ask with.
      */
     trackContainers?: TrackContainer[];
+    /**
+     * what this view contributes to the census of what is open: the tracks it
+     * holds itself, and the views nested directly inside it. `BaseViewModel`
+     * answers both with nothing, so a view declares what it owns instead of the
+     * base reading properties whose meaning belongs to the view — see
+     * `util/openViews.ts`, where the recursion over them lives.
+     *
+     * Required, like `bodyMounted`, so a stand-in that means to be enumerated
+     * says so; the empty default means forgetting under-reports rather than
+     * putting something that is not a track in front of the readiness marker.
+     */
+    ownTracks: AbstractTrackModel[];
+    /** the views nested directly inside this one — see `ownTracks` */
+    ownViews: AbstractViewModel[];
 }
 export declare function isViewModel(thing: unknown): thing is AbstractViewModel;
 type Display = {

package/esm/util/types/index.js

@@ -18,6 +18,9 @@ export function isSessionModel(thing) {
 export function isSessionModelWithConfigEditing(t) {
     return isSessionModel(t) && 'editConfiguration' in t;
 }
+export function isSessionWithMultipleViews(t) {
+    return isSessionModel(t) && isStateTreeNode(t.views);
+}
 export function isSessionWithViewReplacement(t) {
     return isSessionModel(t) && 'replaceView' in t;
 }

package/esm/util/unknownSnapshotKeys.d.ts

@@ -0,0 +1,36 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/** what a diagnostic calls the view: its snapshot `type`, or the model name */
+export declare function viewLabel(self: IStateTreeNode): string;
+/**
+ * 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 declare function unknownKeysMessage(label: string, keys: string[]): string;
+/**
+ * Name the keys a view was handed and could not place, from the partition
+ * `withLaunchInput` runs on the snapshot.
+ */
+export declare function reportUnknownKeys(self: IStateTreeNode, keys: string[]): void;
+/**
+ * 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 declare function reportMalformedRows(self: IStateTreeNode, keys: string[]): void;
+/**
+ * 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 declare function legacyInitMessage(label: string): string;
+/**
+ * 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 declare function reportLegacyInit(self: IStateTreeNode): void;

package/esm/util/unknownSnapshotKeys.js

@@ -0,0 +1,69 @@
+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(', ')}`;
+}
+/**
+ * Name the keys a view was handed and could not place, from the partition
+ * `withLaunchInput` runs on the snapshot.
+ */
+export function reportUnknownKeys(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = unknownKeysMessage(viewLabel(self), keys);
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * Name the row lists a view refused whole. `withLaunchInput` splits an authored
+ * array into the recipes a launcher resolves and the built snapshots MST
+ * restores, per entry — but a row list is indexed against the view's `levels`
+ * and per-level tracks, so a list holding both kinds has no correct split and
+ * is refused rather than renumbered.
+ */
+export function reportMalformedRows(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = `${viewLabel(self)} refused ${keys.join(', ')}: the list mixes built view snapshots with recipes to open one, and the rows index against the levels between them. Write all of them one way.`;
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * What every surface calls v4's nested `init`. v5 takes every setting directly
+ * on the view object and unwraps the nesting on the way in, so the settings
+ * still arrive — this names the spelling to fix while they do.
+ */
+export function legacyInitMessage(label) {
+    return `${label} nests its settings under "init", which is deprecated: write every setting directly on the view object.`;
+}
+/**
+ * Name a snapshot that still writes v4's nested `init`. The console alone,
+ * unlike the two reporters above: the settings were applied, so there is
+ * nothing for a visitor to act on and a warning toast over a working view is
+ * noise. `jbrowse validate` is where the author of the config hears about it.
+ */
+export function reportLegacyInit(self) {
+    console.warn(legacyInitMessage(viewLabel(self)));
+}

package/esm/util/usePanelVirtualScroll.d.ts

@@ -8,11 +8,15 @@ interface PanelScrollTarget {
  * 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.
+ * A sideways-dominant wheel is the view's pan and is declined
+ * (`useVirtualScrollWheel`, which says what latching does with that).
  *
  * 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.
+ * `applyScroll`) owns `preventDefault` but never `stopPropagation`: the event
+ * still reaches the LGV, which reads that flag and declines a gesture this panel
+ * has claimed, so a diagonal wheel scrolls the reads without also panning the
+ * genome sideways.
  *
  * 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

package/esm/util/usePanelVirtualScroll.js

@@ -4,11 +4,15 @@ import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
  * 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.
+ * A sideways-dominant wheel is the view's pan and is declined
+ * (`useVirtualScrollWheel`, which says what latching does with that).
  *
  * 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.
+ * `applyScroll`) owns `preventDefault` but never `stopPropagation`: the event
+ * still reaches the LGV, which reads that flag and declines a gesture this panel
+ * has claimed, so a diagonal wheel scrolls the reads without also panning the
+ * genome sideways.
  *
  * 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

package/esm/util/useRowVirtualScroll.d.ts

@@ -10,7 +10,7 @@ interface RowScrollTarget {
  * 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.
+ * can't consume — a sideways swipe included — 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.

package/esm/util/useRowVirtualScroll.js

@@ -4,7 +4,7 @@ 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.
+ * can't consume — a sideways swipe included — 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.