@jbrowse/product-core 4.2.1 → 5.0.0-beta.1

package/esm/RootModel/BaseRootModel.js

@@ -1,47 +1,171 @@
 import TextSearchManager from '@jbrowse/core/TextSearch/TextSearchManager';
 import assemblyManagerFactory from '@jbrowse/core/assemblyManager';
 import RpcManager from '@jbrowse/core/rpc/RpcManager';
-import { cast, getSnapshot, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
-export function BaseRootModelFactory({ pluginManager, jbrowseModelType, sessionModelType, assemblyConfigSchema, }) {
+import { cast, detach, getType, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
+import { describeUnbuildableNodes, pruneUnbuildableNodes, } from '../pruneUnbuildableNodes.js';
+import { scheduleDetachedDestroy } from '../scheduleDetachedDestroy.js';
+import { migrateSessionSnapshot } from '../sessionMigrations/index.js';
+import { filterSessionInPlace } from '../sessionUtils.js';
+// `session` is a `types.maybe(sessionModelType)` where `sessionModelType` is the
+// erased `IAnyType` (product-core can't name the concrete per-product session
+// type without a root↔session cycle), so `self.session` degrades to `any`. Every
+// concrete session composes BaseSessionModel + SnackbarModel, so asserting the
+// shared `BaseSession` contract restores real checking on the `setName`/`notify`
+// members the base root reaches for — without a hand-maintained shadow.
+/**
+ * #stateModel BaseRootModel
+ * #category root
+ * factory function for the Base-level root model shared by all products
+ */
+export function BaseRootModelFactory({ pluginManager, jbrowseModelType, sessionModelType, assemblyConfigSchema, rpcManagerOptions, }) {
     return types
         .model('BaseRootModel', {
+        /**
+         * #property
+         * `jbrowse` is a mapping of the config.json into the in-memory state
+         * tree
+         */
         jbrowse: jbrowseModelType,
+        /**
+         * #property
+         * `session` encompasses the currently active state of the app, including
+         * views open, tracks open in those views, etc.
+         */
         session: types.maybe(sessionModelType),
-        sessionPath: types.optional(types.string, ''),
+        /**
+         * #property
+         */
+        sessionPath: types.stripDefault(types.string, ''),
+        /**
+         * #property
+         */
         assemblyManager: types.optional(assemblyManagerFactory(assemblyConfigSchema, pluginManager), {}),
     })
         .volatile(self => ({
-        rpcManager: new RpcManager(pluginManager, self.jbrowse.configuration.rpc, {
-            MainThreadRpcDriver: {},
-        }),
+        /**
+         * #volatile
+         */
+        rpcManager: new RpcManager(pluginManager, self.jbrowse.configuration.rpc, rpcManagerOptions),
+        /**
+         * #volatile
+         */
         adminMode: false,
+        /**
+         * #volatile
+         */
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         error: undefined,
+        /**
+         * #volatile
+         */
         textSearchManager: new TextSearchManager(pluginManager),
+        /**
+         * #volatile
+         */
         pluginManager,
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
         setError(error) {
             self.error = error;
         },
+        /**
+         * #action
+         * Sets the active session. Remaps any legacy display type names
+         * (e.g. LinearPileupDisplay → LinearAlignmentsDisplay), drops nodes whose
+         * pluggable type this build has no plugin for (see
+         * `pruneUnbuildableNodes`), then walks the resulting MST tree to drop open
+         * tracks whose config can't hydrate so shared sessions still load when
+         * referencing tracks that no longer exist. Both kinds of drop are surfaced
+         * to the user via a snackbar. If filtering throws, the previous session is
+         * restored.
+         */
         setSession(sessionSnapshot) {
-            self.session = cast(sessionSnapshot);
+            const oldSession = self.session;
+            const unbuildable = [];
+            let migrated = sessionSnapshot;
+            if (sessionSnapshot && typeof sessionSnapshot === 'object') {
+                // before the cast, because a type this build has no plugin for is a
+                // union failure the try below never gets to see
+                const pruned = pruneUnbuildableNodes(migrateSessionSnapshot(sessionSnapshot), pluginManager, sessionModelType);
+                migrated = pruned.snapshot;
+                unbuildable.push(...pruned.dropped);
+            }
+            // Detach first: assigning over it would destroy it inside this action,
+            // and MobX runs the action's pending reactions afterwards, against the
+            // nodes it just killed. ADR-069.
+            if (oldSession) {
+                detach(oldSession);
+            }
+            // The assignment is inside the try because it typechecks: a registered
+            // type carrying a malformed prop is a throw `pruneUnbuildableNodes`
+            // does not and cannot pre-empt, and the detach above has already
+            // emptied `self.session`. MST does not roll an action back, so without
+            // this the root would be left with no session at all and the old tree
+            // detached-and-alive forever.
+            try {
+                self.session = cast(migrated);
+                if (self.session) {
+                    const unbuildableMessage = describeUnbuildableNodes(unbuildable);
+                    if (unbuildableMessage) {
+                        ;
+                        self.session.notify(unbuildableMessage, 'warning');
+                    }
+                    const dropped = filterSessionInPlace(self.session, getType(self.session));
+                    if (dropped.length > 0) {
+                        const names = dropped
+                            .map(d => d.configuration ?? d.type ?? 'unknown')
+                            .join(', ');
+                        const plural = dropped.length > 1;
+                        self.session.notify(`Removed ${dropped.length} track${plural ? 's' : ''} that could not be loaded: ${names}`, 'warning');
+                    }
+                }
+            }
+            catch (error) {
+                // put it back, and do not schedule the destroy below — this is the
+                // one path where the old session goes on being the live one
+                self.session = oldSession;
+                throw error;
+            }
+            // and it does still get destroyed, once the reaction flush has
+            // unwound. `beforeDestroy` is a plugin-facing contract and leaving a
+            // detached session alive forever would skip it. ADR-069.
+            if (oldSession) {
+                scheduleDetachedDestroy(oldSession);
+            }
         },
+        /**
+         * #action
+         */
         setDefaultSession() {
-            this.setSession(self.jbrowse.defaultSession);
+            const { defaultSession } = self.jbrowse;
+            this.setSession({
+                ...defaultSession,
+                // timestamp the name so repeated "new session" names don't collide
+                name: `${defaultSession.name || 'New session'} ${new Date().toLocaleString()}`,
+            });
         },
+        /**
+         * #action
+         */
         setSessionPath(path) {
             self.sessionPath = path;
         },
+        /**
+         * #action
+         */
         renameCurrentSession(newName) {
-            if (self.session) {
-                this.setSession({
-                    ...getSnapshot(self.session),
-                    name: newName,
-                });
-            }
+            // Every concrete session model is composed from BaseSessionModel, which
+            // provides setName — avoid a full setSession rebuild here since the
+            // only field changing is `name`.
+            ;
+            self.session?.setName(newName);
         },
     }));
 }
+/** Type guard for checking if something is a JB root model */
 export function isRootModel(thing) {
     return (isStateTreeNode(thing) &&
         'session' in thing &&

package/esm/RootModel/HierarchicalConfig.d.ts

@@ -1,31 +1,67 @@
+/**
+ * #config HierarchicalConfigSchema
+ * #category root
+ * generally exists on the config.json or root config as configuration.hierarchical
+ */
 export declare function HierarchicalConfigSchemaFactory(): import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-        trackNames: {
-            type: string;
-            defaultValue: boolean;
+    readonly sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        /**
+         * #slot configuration.hierarchical.sort.trackNames
+         * start the track selector with tracks sorted alphabetically inside each
+         * category rather than in config order. Only the initial state — the
+         * selector's own "Sort track names" toggle overrides it from then on
+         */
+        readonly trackNames: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
         };
-        categories: {
-            type: string;
-            defaultValue: boolean;
+        /**
+         * #slot configuration.hierarchical.sort.categories
+         * start the track selector with categories sorted alphabetically rather
+         * than in config order. Only the initial state — the selector's own
+         * "Sort categories" toggle overrides it from then on
+         */
+        readonly categories: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
         };
     }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-    defaultFolderCategories: {
-        type: string;
-        description: string;
-        defaultValue: never[];
+    /**
+     * #slot configuration.hierarchical.defaultFolderCategories
+     */
+    readonly defaultFolderCategories: {
+        readonly type: "stringArray";
+        readonly description: "list of category names to display as folders by default";
+        readonly defaultValue: readonly [];
     };
-    defaultCollapsed: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-        categoryNames: {
-            type: string;
-            defaultValue: never[];
+    readonly defaultCollapsed: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        /**
+         * #slot configuration.hierarchical.defaultCollapsed.categoryNames
+         * named top-level categories that start collapsed, e.g.
+         * `['ENCODE', 'RNA-seq']`. Once a user expands or collapses anything, the
+         * selector remembers their state instead
+         */
+        readonly categoryNames: {
+            readonly type: "stringArray";
+            readonly defaultValue: readonly [];
         };
-        topLevelCategories: {
-            type: string;
-            defaultValue: boolean;
+        /**
+         * #slot configuration.hierarchical.defaultCollapsed.topLevelCategories
+         * start every top-level category collapsed, so a config with many
+         * categories opens as a short list rather than a wall of tracks
+         */
+        readonly topLevelCategories: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
         };
-        subCategories: {
-            type: string;
-            defaultValue: boolean;
+        /**
+         * #slot configuration.hierarchical.defaultCollapsed.subCategories
+         * start every nested category collapsed while leaving the top level
+         * open, for deeply categorized track sets
+         */
+        readonly subCategories: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
         };
     }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;

package/esm/RootModel/HierarchicalConfig.js

@@ -1,30 +1,66 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
+/**
+ * #config HierarchicalConfigSchema
+ * #category root
+ * generally exists on the config.json or root config as configuration.hierarchical
+ */
 export function HierarchicalConfigSchemaFactory() {
     return ConfigurationSchema('hierarchical', {
         sort: ConfigurationSchema('hierarchicalSort', {
+            /**
+             * #slot configuration.hierarchical.sort.trackNames
+             * start the track selector with tracks sorted alphabetically inside each
+             * category rather than in config order. Only the initial state — the
+             * selector's own "Sort track names" toggle overrides it from then on
+             */
             trackNames: {
                 type: 'boolean',
                 defaultValue: false,
             },
+            /**
+             * #slot configuration.hierarchical.sort.categories
+             * start the track selector with categories sorted alphabetically rather
+             * than in config order. Only the initial state — the selector's own
+             * "Sort categories" toggle overrides it from then on
+             */
             categories: {
                 type: 'boolean',
                 defaultValue: false,
             },
         }),
+        /**
+         * #slot configuration.hierarchical.defaultFolderCategories
+         */
         defaultFolderCategories: {
             type: 'stringArray',
             description: 'list of category names to display as folders by default',
             defaultValue: [],
         },
         defaultCollapsed: ConfigurationSchema('defaultCollapsed', {
+            /**
+             * #slot configuration.hierarchical.defaultCollapsed.categoryNames
+             * named top-level categories that start collapsed, e.g.
+             * `['ENCODE', 'RNA-seq']`. Once a user expands or collapses anything, the
+             * selector remembers their state instead
+             */
             categoryNames: {
                 type: 'stringArray',
                 defaultValue: [],
             },
+            /**
+             * #slot configuration.hierarchical.defaultCollapsed.topLevelCategories
+             * start every top-level category collapsed, so a config with many
+             * categories opens as a short list rather than a wall of tracks
+             */
             topLevelCategories: {
                 type: 'boolean',
                 defaultValue: false,
             },
+            /**
+             * #slot configuration.hierarchical.defaultCollapsed.subCategories
+             * start every nested category collapsed while leaving the top level
+             * open, for deeply categorized track sets
+             */
             subCategories: {
                 type: 'boolean',
                 defaultValue: false,

package/esm/RootModel/InternetAccounts.d.ts

@@ -2,11 +2,28 @@ import type PluginManager from '@jbrowse/core/PluginManager';
 import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
 import type { UriLocation } from '@jbrowse/core/util';
 import type { Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel InternetAccountsMixin
+ * #category root
+ */
 export declare function InternetAccountsRootModelMixin(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
     internetAccounts: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
 }, {
-    initializeInternetAccount(internetAccountConfig: AnyConfigurationModel, initialSnapshot?: {}): any;
+    /**
+     * #action
+     */
+    initializeInternetAccount(internetAccountConfig: AnyConfigurationModel, initialSnapshot?: object): any;
+    /**
+     * #action
+     */
     createEphemeralInternetAccount(internetAccountId: string, initialSnapshot: Record<string, unknown>, url: string): any;
+} & {
+    /**
+     * #action
+     */
     findAppropriateInternetAccount(location: UriLocation): any;
 } & {
     afterCreate(): void;

package/esm/RootModel/InternetAccounts.js

@@ -1,74 +1,172 @@
 import { addDisposer, types } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
+import { asRoot } from '../siblingCast.js';
+/**
+ * The ephemeral account ids RpcManager mints are `<TypeName>-<rest>` — the
+ * leading segment names the account type and the remainder is its display name.
+ * Read in one place so the two callers cannot disagree about which is which.
+ */
+function parseEphemeralId(internetAccountId) {
+    const [type = '', ...rest] = internetAccountId.split('-');
+    return { type, name: rest.join('-') };
+}
+/**
+ * Whether the fetch this location describes would go to the origin serving
+ * JBrowse itself.
+ *
+ * `domains` cannot name that host. A config shipped with relative data paths
+ * (`volvox_microarray.bw`) resolves against wherever the app is deployed, which
+ * whoever wrote the config does not know — so an account for it has nothing to
+ * put in `domains`, and naming the account on the location is the only way to
+ * reach it. Safe whatever `domains` says: a link can move a same-origin
+ * location nowhere except the server already serving the page and holding the
+ * session.
+ *
+ * Resolved the way the request will be, against `baseUri` when there is one, so
+ * a spec cannot pass a relative uri under an off-origin base and read as local.
+ */
+function resolvesToAppOrigin(location) {
+    // typed as always present, and absent in node and in some embedded hosts
+    const here = globalThis.location;
+    // `null` is what an opaque origin (file:, data:) stringifies to, and two of
+    // them are not the same origin
+    if (!here?.origin || here.origin === 'null') {
+        return false;
+    }
+    try {
+        return (new URL(location.uri, location.baseUri ?? here.href).origin ===
+            here.origin);
+    }
+    catch {
+        return false;
+    }
+}
+// An account named by a location it is not scoped for reads as a dead track,
+// so say which half to fix. Once per pair: the check runs on every RPC
+// serialization, and a track issues one per block.
+const warnedScopeMismatches = new Set();
+function warnScopeMismatch(internetAccountId, uri) {
+    const key = `${internetAccountId}|${uri}`;
+    if (!warnedScopeMismatches.has(key)) {
+        warnedScopeMismatches.add(key);
+        console.warn(`Internet account "${internetAccountId}" is not used for ${uri}: the URL is outside its "domains". Add the host to that account's domains if this is your data.`);
+    }
+}
+/**
+ * #stateModel InternetAccountsMixin
+ * #category root
+ */
 export function InternetAccountsRootModelMixin(pluginManager) {
     return types
         .model({
+        /**
+         * #property
+         */
         internetAccounts: types.array(pluginManager.pluggableMstType('internet account', 'stateModel')),
     })
         .actions(self => ({
+        /**
+         * #action
+         */
         initializeInternetAccount(internetAccountConfig, initialSnapshot = {}) {
-            const internetAccountType = pluginManager.getInternetAccountType(internetAccountConfig.type);
-            if (!internetAccountType) {
-                throw new Error(`unknown internet account type ${internetAccountConfig.type}`);
-            }
-            const length = self.internetAccounts.push({
+            self.internetAccounts.push({
                 ...initialSnapshot,
                 type: internetAccountConfig.type,
                 configuration: internetAccountConfig,
             });
-            return self.internetAccounts[length - 1];
+            return self.internetAccounts.at(-1);
         },
+        /**
+         * #action
+         */
         createEphemeralInternetAccount(internetAccountId, initialSnapshot, url) {
             let hostUri;
             try {
-                hostUri = new URL(url).origin;
+                const urlObj = new URL(url);
+                const pathname = urlObj.pathname;
+                const lastSlash = pathname.lastIndexOf('/');
+                const dirPath = lastSlash !== -1 ? pathname.slice(0, lastSlash + 1) : '/';
+                hostUri = `${urlObj.origin}${dirPath}`;
             }
-            catch (e) {
+            catch {
+                // ignore
             }
-            const internetAccountSplit = internetAccountId.split('-');
+            const { type, name } = parseEphemeralId(internetAccountId);
             const configuration = {
-                type: internetAccountSplit[0],
-                internetAccountId: internetAccountId,
-                name: internetAccountSplit.slice(1).join('-'),
+                type,
+                internetAccountId,
+                name,
                 description: '',
                 domains: hostUri ? [hostUri] : [],
             };
-            const type = pluginManager.getInternetAccountType(configuration.type);
-            const internetAccount = type.stateModel.create({
+            self.internetAccounts.push({
                 ...initialSnapshot,
                 type: configuration.type,
                 configuration,
             });
-            self.internetAccounts.push(internetAccount);
-            return internetAccount;
+            return self.internetAccounts.at(-1);
         },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         */
         findAppropriateInternetAccount(location) {
+            // find the existing account selected from menu
             const selectedId = location.internetAccountId;
             if (selectedId) {
                 const selectedAccount = self.internetAccounts.find(account => {
                     return account.internetAccountId === selectedId;
                 });
+                // The account still has to be scoped for the URL. Naming one used to
+                // be enough on its own, which made the field a way to redirect
+                // someone else's credential: jbrowse-web builds tracks out of
+                // `sessionTracks` in the URL, and a location there carrying
+                // `internetAccountId` sent that account's token to whatever host the
+                // link chose — first as validateToken's probe from the main thread,
+                // then as the worker's read. An OAuth account with a refresh token in
+                // localStorage needs no interaction at all to mint a fresh one for it.
                 if (selectedAccount) {
-                    return selectedAccount;
+                    if (selectedAccount.handlesLocation(location) ||
+                        resolvesToAppOrigin(location)) {
+                        return selectedAccount;
+                    }
+                    warnScopeMismatch(selectedId, location.uri);
                 }
             }
+            // if no existing account or not found, try to find working account
             for (const account of self.internetAccounts) {
                 const handleResult = account.handlesLocation(location);
                 if (handleResult) {
                     return account;
                 }
             }
-            return selectedId
-                ? this.createEphemeralInternetAccount(selectedId, {}, location.uri)
-                : null;
+            // if still no existing account, create ephemeral config to use — but
+            // only for an id whose leading segment names an account type this
+            // session actually has. Anything else is a location pointing at an
+            // account that is simply gone (a track from a shared session whose
+            // config defined one, a config it was removed from, a host that never
+            // loaded the authentication plugin), and pushing an unknown type into
+            // the array threw a bare MST union error out of whatever was opening
+            // the file. No account instead lets the read go out unauthenticated and
+            // report the 401 it gets, which is the failure the user can act on.
+            if (selectedId &&
+                pluginManager
+                    .getElementTypesInGroup('internet account')
+                    .some(t => t.name === parseEphemeralId(selectedId).type)) {
+                return self.createEphemeralInternetAccount(selectedId, {}, location.uri);
+            }
+            return null;
         },
     }))
         .actions(self => ({
         afterCreate() {
             addDisposer(self, autorun(function internetAccountsAutorun() {
-                const { jbrowse } = self;
+                const { jbrowse } = asRoot(self);
                 for (const internetAccount of jbrowse.internetAccounts) {
-                    self.initializeInternetAccount(internetAccount);
+                    if (!self.internetAccounts.some(a => a.internetAccountId === internetAccount.internetAccountId)) {
+                        self.initializeInternetAccount(internetAccount);
+                    }
                 }
             }, { name: 'InternetAccounts' }));
         },

package/esm/RootModel/PreferencesConfig.d.ts

@@ -0,0 +1,53 @@
+/**
+ * #config PreferencesConfigSchema
+ * #category root
+ * admin/embedder defaults for user-facing preferences, found on the root config
+ * as `configuration.preferences`. Individual users override these at runtime
+ * (persisted to localStorage) via the session `getPreference` reader; a runtime
+ * override map layered over config defaults, at app scope.
+ */
+export declare function PreferencesConfigSchemaFactory(): import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+    /**
+     * #slot configuration.preferences.animationMode
+     * controls feature-layout animations: 'enabled' always animates (the
+     * default), 'system' respects the OS prefers-reduced-motion setting,
+     * 'disabled' never animates
+     */
+    readonly animationMode: {
+        readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"disabled" | "enabled" | "system">;
+        readonly type: "stringEnum";
+        readonly defaultValue: "enabled";
+    };
+    /**
+     * #slot configuration.preferences.scrollZoom
+     * when true, scrolling the mouse wheel over a track zooms in and out
+     * without holding Ctrl. Applies globally to all wheel-zoom views.
+     */
+    readonly scrollZoom: {
+        readonly type: "boolean";
+        readonly defaultValue: false;
+    };
+    /**
+     * #slot configuration.preferences.numberGrouping
+     * when true (the default), numbers are displayed with thousand separators
+     * — `chr1:1,234,567`. Turn it off to render them bare, which is what you
+     * want if you copy coordinates out of JBrowse into tools that won't accept
+     * the commas. Applies to every displayed number, and takes effect on
+     * reload.
+     */
+    readonly numberGrouping: {
+        readonly type: "boolean";
+        readonly defaultValue: true;
+    };
+    /**
+     * #slot configuration.preferences.useWorkspaces
+     * when true, views open in the tabbed/tiled workspace layout rather than
+     * stacked vertically. Only the default: a session that names
+     * `useWorkspaces` itself (a shared snapshot, or a session spec carrying a
+     * `layout`) still wins, and a user's own toggle overrides it.
+     */
+    readonly useWorkspaces: {
+        readonly type: "boolean";
+        readonly defaultValue: false;
+    };
+}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;