@jbrowse/app-core 4.3.0 → 5.0.0-beta.1

package/esm/JBrowseModel/index.d.ts

@@ -1,115 +1,141 @@
-import type { PluginDefinition } from '@jbrowse/core/PluginLoader';
 import type PluginManager from '@jbrowse/core/PluginManager';
 import type { BaseAssemblyConfigSchema } from '@jbrowse/core/assemblyManager';
-import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { AnyConfiguration, AnyConfigurationModel, ConfigurationSchemaDefinition } from '@jbrowse/core/configuration';
+import type { PluginDefinition } from '@jbrowse/core/pluginDefinitions';
 import type RpcManager from '@jbrowse/core/rpc/RpcManager';
-export declare function JBrowseModelF({ pluginManager, assemblyConfigSchema, }: {
-    adminMode?: boolean;
+export declare function JBrowseModelF({ pluginManager, assemblyConfigSchema, extraConfigSlots, }: {
     pluginManager: PluginManager;
     assemblyConfigSchema: BaseAssemblyConfigSchema;
-}): import("@jbrowse/mobx-state-tree").IModelType<{
+    extraConfigSlots?: ConfigurationSchemaDefinition;
+}): import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").IModelType<{
     configuration: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-        rpc: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-            defaultDriver: {
-                type: string;
-                description: string;
-                defaultValue: string;
+        readonly rpc: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly defaultDriver: {
+                readonly type: "string";
+                readonly description: "the RPC driver to run data fetching on: MainThreadRpcDriver or WebWorkerRpcDriver. Leave empty to use the default for this application";
+                readonly defaultValue: "";
+                readonly advanced: true;
+            };
+            readonly workerCount: {
+                readonly type: "number";
+                readonly description: "The number of workers to use. If 0 (the default) JBrowse will decide how many workers to use.";
+                readonly defaultValue: 0;
+                readonly advanced: true;
             };
-            drivers: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<Record<string, any>>> | undefined, import("@jbrowse/mobx-state-tree").ModelSnapshotType<Record<string, any>>, ({} & Partial<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<Record<string, any>>> & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject) | undefined>>, [undefined]>;
         }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-        highResolutionScaling: {
-            type: string;
-            defaultValue: number;
-        };
-        formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-            feature: {
-                type: string;
-                description: string;
-                defaultValue: {};
-                contextVariable: string[];
+        readonly formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly feature: {
+                readonly type: "frozen";
+                readonly description: "adds extra fields to the feature details";
+                readonly defaultValue: {};
+                readonly contextVariable: ["feature"];
             };
-            subfeatures: {
-                type: string;
-                description: string;
-                defaultValue: {};
-                contextVariable: string[];
+            readonly subfeatures: {
+                readonly type: "frozen";
+                readonly description: "adds extra fields to the subfeatures of a feature";
+                readonly defaultValue: {};
+                readonly contextVariable: ["feature"];
             };
-            depth: {
-                type: string;
-                defaultValue: number;
-                description: string;
+            readonly depth: {
+                readonly type: "maybeNumber";
+                readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
             };
-            maxDepth: {
-                type: string;
-                defaultValue: number;
-                description: string;
+            readonly maxDepth: {
+                readonly type: "maybeNumber";
+                readonly description: "hide subfeatures nested deeper than this, default no limit";
             };
         }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-        formatAbout: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-            config: {
-                type: string;
-                description: string;
-                defaultValue: {};
-                contextVariable: string[];
+        readonly formatAbout: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly config: {
+                readonly type: "frozen";
+                readonly description: "formats configuration object in about dialog";
+                readonly defaultValue: {};
+                readonly contextVariable: ["config"];
             };
-            hideUris: {
-                type: string;
-                defaultValue: boolean;
+            readonly hideUris: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
             };
         }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-        shareURL: {
-            type: string;
-            defaultValue: string;
+        readonly shareURL: {
+            readonly type: "string";
+            readonly defaultValue: "https://share.jbrowse.org/api/v1/";
+            readonly advanced: true;
         };
-        disableAnalytics: {
-            type: string;
-            defaultValue: boolean;
+        readonly disableAnalytics: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
+            readonly advanced: true;
         };
-        hierarchical: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-            sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-                trackNames: {
-                    type: string;
-                    defaultValue: boolean;
+        readonly hierarchical: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+                readonly trackNames: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
                 };
-                categories: {
-                    type: string;
-                    defaultValue: boolean;
+                readonly categories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
                 };
             }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-            defaultFolderCategories: {
-                type: string;
-                description: string;
-                defaultValue: never[];
+            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<{
+                readonly categoryNames: {
+                    readonly type: "stringArray";
+                    readonly defaultValue: readonly [];
                 };
-                topLevelCategories: {
-                    type: string;
-                    defaultValue: boolean;
+                readonly topLevelCategories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
                 };
-                subCategories: {
-                    type: string;
-                    defaultValue: boolean;
+                readonly subCategories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
                 };
             }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
         }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-        theme: {
-            type: string;
-            defaultValue: {};
+        readonly preferences: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly animationMode: {
+                readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"disabled" | "enabled" | "system">;
+                readonly type: "stringEnum";
+                readonly defaultValue: "enabled";
+            };
+            readonly scrollZoom: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+            readonly numberGrouping: {
+                readonly type: "boolean";
+                readonly defaultValue: true;
+            };
+            readonly useWorkspaces: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly theme: {
+            readonly type: "frozen";
+            readonly description: "Material UI theme overrides applied to the JBrowse UI";
+            readonly defaultValue: {};
         };
-        extraThemes: {
-            type: string;
-            defaultValue: {};
+        readonly extraThemes: {
+            readonly type: "frozen";
+            readonly description: "additional named themes the user can switch between";
+            readonly defaultValue: {};
+            readonly advanced: true;
         };
-        logoPath: {
-            type: string;
-            defaultValue: {
-                uri: string;
-                locationType: string;
+        readonly logoPath: {
+            readonly type: "fileLocation";
+            readonly description: "path to a custom logo image displayed in the app header";
+            readonly defaultValue: {
+                readonly uri: "";
+                readonly locationType: "UriLocation";
             };
+            readonly advanced: true;
         };
     }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
     plugins: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<PluginDefinition, PluginDefinition, PluginDefinition>>;
@@ -124,42 +150,97 @@ export declare function JBrowseModelF({ pluginManager, assemblyConfigSchema, }:
         [key: string]: unknown;
         trackId: string;
     }[]>;
-    internetAccounts: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyModelType>;
-    aggregateTextSearchAdapters: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyModelType>;
-    connections: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyModelType>;
+    internetAccounts: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    aggregateTextSearchAdapters: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    connections: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
     defaultSession: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IType<any, any, any>, [undefined]>;
     preConfiguredSessions: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<any, any, any>>;
 }, {
+    /**
+     * #getter
+     */
     readonly assemblyNames: string[];
+    /**
+     * #getter
+     */
     readonly rpcManager: RpcManager;
 } & {
-    addAssemblyConf(conf: AnyConfigurationModel): ({
-        [x: string]: any;
-    } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & {
-        setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-            [x: string]: any;
-        } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & any & import("@jbrowse/mobx-state-tree").IStateTreeNode<import("@jbrowse/core/configuration").AnyConfigurationSchemaType>);
+    /**
+     * #action
+     */
+    addAssemblyConf(conf: AnyConfigurationModel): (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
+        setSubschema(slotName: string, data: Record<string, unknown>): any;
+        setSlot(slotName: string, value: unknown): void;
     } & import("@jbrowse/mobx-state-tree").IStateTreeNode<import("@jbrowse/core/configuration").AnyConfigurationSchemaType>) | undefined;
+    /**
+     * #action
+     */
     removeAssemblyConf(assemblyName: string): void;
-    addTrackConf(trackConf: {
+    /**
+     * #action
+     */
+    addTrackConf(loose: {
         trackId: string;
-        type: string;
+        type?: string;
     }): {
         [key: string]: unknown;
         trackId: string;
     } | undefined;
-    addConnectionConf(connectionConf: AnyConfigurationModel): any;
+    /**
+     * #action
+     * Adds to the config's own `connections`, which every visitor to this
+     * instance loads. Takes a snapshot as readily as a built config model —
+     * the array coerces — since callers hand it plain JSON (a session spec's
+     * `sessionConnections`, the CLI's add-connection output).
+     */
+    addConnectionConf(connectionConf: AnyConfiguration): any;
+    /**
+     * #action
+     */
     deleteConnectionConf(configuration: AnyConfigurationModel): boolean;
+    /**
+     * #action
+     */
     deleteTrackConf(trackConf: AnyConfigurationModel | {
         trackId: string;
     }): void;
+    /**
+     * #action
+     * Updates an existing track configuration. Used to sync editable configs
+     * back to the frozen tracks array.
+     */
     updateTrackConf(trackConf: {
         trackId: string;
         [key: string]: unknown;
     }): void;
+    /**
+     * #action
+     */
     addPlugin(pluginDefinition: PluginDefinition): void;
+    /**
+     * #action
+     * Removes the entry that loads from the same url — the version-pinned
+     * definition, not every entry sharing a name, so the update flow's
+     * remove-then-add swaps one version for another.
+     *
+     * A definition naming no loader matches nothing (`isPluginUrl`) rather than
+     * every other url-less entry: `pluginUrl`'s miss value is the display string
+     * 'unknown url', so removing one hand-written broken entry used to filter out
+     * all of them. Such an entry has no InstalledPlugin row to remove it from
+     * either — it never loads, so it is never in `runtimePluginDefinitions` — so
+     * matching nothing costs nothing the UI could reach.
+     */
     removePlugin(pluginDefinition: PluginDefinition): void;
+    /**
+     * #action
+     */
     setDefaultSessionConf(sessionConf: AnyConfigurationModel): void;
+    /**
+     * #action
+     */
     addInternetAccountConf(internetAccountConf: AnyConfigurationModel): any;
+    /**
+     * #action
+     */
     deleteInternetAccountConf(configuration: AnyConfigurationModel): boolean;
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, Record<string, unknown>, import("@jbrowse/mobx-state-tree")._NotCustomized>;

package/esm/JBrowseModel/index.js

@@ -1,18 +1,57 @@
 import { readConfObject } from '@jbrowse/core/configuration';
-import { cast, getParent, getSnapshot } from '@jbrowse/mobx-state-tree';
+import { isPluginUrl, maybePluginUrl } from '@jbrowse/core/pluginDefinitions';
+import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
+import { cast, getParent, getSnapshot, types } from '@jbrowse/mobx-state-tree';
+import { migrateConfigSnapshot } from '@jbrowse/product-core';
 import { toJS } from 'mobx';
-import { JBrowseConfigF } from "../JBrowseConfig/index.js";
-export function JBrowseModelF({ pluginManager, assemblyConfigSchema, }) {
-    return JBrowseConfigF({ pluginManager, assemblyConfigSchema })
+import { JBrowseConfigF } from '../JBrowseConfig/index.js';
+/**
+ * #stateModel AppCoreJBrowseModel
+ * #category root
+ * built on the [JBrowseRootConfig](/docs/config/jbrowserootconfig) config model —
+ * config models are MST trees themselves, which is why this state model is
+ * allowed to build on one. Generally found on a property named rootModel.jbrowse
+ */
+// A config with exactly one assembly is what every loose track is on, so
+// `assemblyNames` may be left off; with several, the track has to say.
+function expandLooseTracks(snapshot, pluginManager) {
+    const tracks = snapshot.tracks;
+    if (!Array.isArray(tracks)) {
+        return snapshot;
+    }
+    const assemblies = snapshot.assemblies;
+    const only = Array.isArray(assemblies) && assemblies.length === 1
+        ? assemblies[0].name
+        : undefined;
+    const expanded = tracks.map(t => expandLooseTrackConfig(t, pluginManager, only));
+    return expanded.every((t, i) => t === tracks[i])
+        ? snapshot
+        : { ...snapshot, tracks: expanded };
+}
+export function JBrowseModelF({ pluginManager, assemblyConfigSchema, extraConfigSlots, }) {
+    const model = JBrowseConfigF({
+        pluginManager,
+        assemblyConfigSchema,
+        extraConfigSlots,
+    })
         .views(self => ({
+        /**
+         * #getter
+         */
         get assemblyNames() {
             return self.assemblies.map(assembly => readConfObject(assembly, 'name'));
         },
+        /**
+         * #getter
+         */
         get rpcManager() {
             return getParent(self).rpcManager;
         },
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
         addAssemblyConf(conf) {
             const { name } = conf;
             if (!name) {
@@ -31,36 +70,64 @@ export function JBrowseModelF({ pluginManager, assemblyConfigSchema, }) {
             });
             return self.assemblies[length - 1];
         },
+        /**
+         * #action
+         */
         removeAssemblyConf(assemblyName) {
             const toRemove = self.assemblies.find(a => a.name === assemblyName);
             if (toRemove) {
                 self.assemblies.remove(toRemove);
             }
         },
-        addTrackConf(trackConf) {
+        /**
+         * #action
+         */
+        addTrackConf(loose) {
+            const trackConf = expandLooseTrackConfig(loose, pluginManager);
             const { type } = trackConf;
             if (!type) {
-                throw new Error(`unknown track type ${type}`);
+                throw new Error(`track type not specified for "${trackConf.trackId}"`);
             }
             self.tracks = [...self.tracks, trackConf];
             return self.tracks.at(-1);
         },
+        /**
+         * #action
+         * Adds to the config's own `connections`, which every visitor to this
+         * instance loads. Takes a snapshot as readily as a built config model —
+         * the array coerces — since callers hand it plain JSON (a session spec's
+         * `sessionConnections`, the CLI's add-connection output).
+         */
         addConnectionConf(connectionConf) {
             const { type } = connectionConf;
             if (!type) {
-                throw new Error(`unknown connection type ${type}`);
+                throw new Error('connection type not specified');
             }
             const length = self.connections.push(connectionConf);
             return self.connections[length - 1];
         },
+        /**
+         * #action
+         */
         deleteConnectionConf(configuration) {
-            const elt = self.connections.find(conn => conn.id === configuration.id);
-            return self.connections.remove(elt);
+            // key on connectionId: the connection schema's explicitIdentifier means
+            // `.id` is undefined on every entry, so an id-based find always matched
+            // the first connection and deleted the wrong one
+            const elt = self.connections.find(conn => conn.connectionId === configuration.connectionId);
+            return elt ? self.connections.remove(elt) : false;
         },
+        /**
+         * #action
+         */
         deleteTrackConf(trackConf) {
             const trackId = trackConf.trackId;
             self.tracks = self.tracks.filter(t => t.trackId !== trackId);
         },
+        /**
+         * #action
+         * Updates an existing track configuration. Used to sync editable configs
+         * back to the frozen tracks array.
+         */
         updateTrackConf(trackConf) {
             const { trackId } = trackConf;
             const idx = self.tracks.findIndex(t => t.trackId === trackId);
@@ -70,38 +137,72 @@ export function JBrowseModelF({ pluginManager, assemblyConfigSchema, }) {
                 self.tracks = newTracks;
             }
         },
+        /**
+         * #action
+         */
         addPlugin(pluginDefinition) {
             self.plugins.push(pluginDefinition);
-            const rootModel = getParent(self);
-            rootModel.setPluginsUpdated(true);
+            getParent(self).setPluginsUpdated();
         },
+        /**
+         * #action
+         * Removes the entry that loads from the same url — the version-pinned
+         * definition, not every entry sharing a name, so the update flow's
+         * remove-then-add swaps one version for another.
+         *
+         * A definition naming no loader matches nothing (`isPluginUrl`) rather than
+         * every other url-less entry: `pluginUrl`'s miss value is the display string
+         * 'unknown url', so removing one hand-written broken entry used to filter out
+         * all of them. Such an entry has no InstalledPlugin row to remove it from
+         * either — it never loads, so it is never in `runtimePluginDefinitions` — so
+         * matching nothing costs nothing the UI could reach.
+         */
         removePlugin(pluginDefinition) {
-            self.plugins = cast(self.plugins.filter(plugin => plugin.url !== pluginDefinition.url ||
-                plugin.umdUrl !== pluginDefinition.umdUrl ||
-                plugin.cjsUrl !== pluginDefinition.cjsUrl ||
-                plugin.esmUrl !== pluginDefinition.esmUrl));
-            getParent(self).setPluginsUpdated(true);
+            const targetUrl = maybePluginUrl(pluginDefinition);
+            self.plugins = cast(self.plugins.filter(plugin => !isPluginUrl(plugin, targetUrl)));
+            getParent(self).setPluginsUpdated();
         },
+        /**
+         * #action
+         */
         setDefaultSessionConf(sessionConf) {
-            const newDefault = getParent(self).session.name === sessionConf.name
+            const newDefault = getParent(self).session?.name === sessionConf.name
                 ? getSnapshot(sessionConf)
                 : toJS(sessionConf);
             if (!newDefault.name) {
-                throw new Error(`unable to set default session to ${newDefault.name}`);
+                throw new Error('default session must have a name');
             }
             self.defaultSession = cast(newDefault);
         },
+        /**
+         * #action
+         */
         addInternetAccountConf(internetAccountConf) {
             const { type } = internetAccountConf;
             if (!type) {
-                throw new Error(`unknown internetAccount type ${type}`);
+                throw new Error('internet account type not specified');
             }
             const length = self.internetAccounts.push(internetAccountConf);
             return self.internetAccounts[length - 1];
         },
+        /**
+         * #action
+         */
         deleteInternetAccountConf(configuration) {
-            const elt = self.internetAccounts.find(a => a.id === configuration.id);
-            return self.internetAccounts.remove(elt);
+            // key on internetAccountId, not the undefined `.id` (see
+            // deleteConnectionConf) so the correct account is removed
+            const elt = self.internetAccounts.find(a => a.internetAccountId === configuration.internetAccountId);
+            return elt ? self.internetAccounts.remove(elt) : false;
         },
     }));
+    // Migrate legacy display types (e.g. LinearPileupDisplay →
+    // LinearAlignmentsDisplay) when ingesting config snapshots so saved
+    // configs from older JBrowse versions still load. `tracks` stays frozen
+    // (ADR-032), so the loose `{ trackId, uri }` form is expanded here, where
+    // the track selector and the trackId index read it, and never by a schema.
+    return types.snapshotProcessor(model, {
+        preProcessor(snapshot) {
+            return migrateConfigSnapshot(expandLooseTracks(snapshot, pluginManager));
+        },
+    });
 }

package/esm/RootMenu/index.d.ts

@@ -1,13 +1,88 @@
-import type { Menu, MenuAction } from '../menus.ts';
+import type { MenuAction, MenuDefinition } from '../menus.ts';
 import type { MenuItem } from '@jbrowse/core/ui/Menu';
+/**
+ * #stateModel RootAppMenuMixin
+ */
 export declare function RootAppMenuMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     mutableMenuActions: MenuAction[];
 } & {
-    setMenus(newMenus: Menu[]): void;
+    /**
+     * #action
+     * Replace the menu bar wholesale. Item contributions recorded before
+     * this one are dropped along with the menus they targeted, so a plugin
+     * adding to the existing bar wants `appendToMenu` instead.
+     *
+     * @param newMenus - The complete new set of top-level menus.
+     */
+    setMenus(newMenus: MenuDefinition[]): void;
+    /**
+     * #action
+     * Add a top-level menu, if the app bar does not already have one with
+     * this name.
+     *
+     * @param menuName - Name of the menu to add.
+     */
     appendMenu(menuName: string): void;
+    /**
+     * #action
+     * Insert a top-level menu, if the app bar does not already have one
+     * with this name.
+     *
+     * @param menuName - Name of the menu to insert.
+     *
+     * @param position - Position to insert menu. If negative, counts from the
+     * end, e.g. `insertMenu('My Menu', -1)` will insert the menu as the
+     * second-to-last one.
+     */
     insertMenu(menuName: string, position: number): void;
+    /**
+     * #action
+     * Add a menu item to a top-level menu, creating the menu if it does not
+     * exist.
+     *
+     * @param menuName - Name of the top-level menu to append to.
+     *
+     * @param menuItem - Menu item to append.
+     */
     appendToMenu(menuName: string, menuItem: MenuItem): void;
+    /**
+     * #action
+     * Insert a menu item into a top-level menu, creating the menu if it
+     * does not exist.
+     *
+     * @param menuName - Name of the top-level menu to insert into
+     *
+     * @param menuItem - Menu item to insert
+     *
+     * @param position - Position to insert menu item. If negative, counts
+     * from the end, e.g. `insertInMenu('My Menu', item, -1)` will insert the
+     * item as the second-to-last one.
+     */
     insertInMenu(menuName: string, menuItem: MenuItem, position: number): void;
+    /**
+     * #action
+     * Add a menu item to a sub-menu, creating any part of the path that
+     * does not exist.
+     *
+     * @param menuPath - Path to the sub-menu to add to, starting with the
+     * top-level menu (e.g. `['File', 'Insert']`).
+     *
+     * @param menuItem - Menu item to append.
+     */
     appendToSubMenu(menuPath: string[], menuItem: MenuItem): void;
+    /**
+     * #action
+     * Insert a menu item into a sub-menu, creating any part of the path
+     * that does not exist.
+     *
+     * @param menuPath - Path to the sub-menu to add to, starting with the
+     * top-level menu (e.g. `['File', 'Insert']`).
+     *
+     * @param menuItem - Menu item to insert.
+     *
+     * @param position - Position to insert menu item. If negative, counts
+     * from the end, e.g. `insertInSubMenu(path, item, -1)` will insert the
+     * item as the second-to-last one.
+     */
     insertInSubMenu(menuPath: string[], menuItem: MenuItem, position: number): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;