@jbrowse/core 4.3.0 → 5.0.0-beta.10

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

@@ -1,61 +1,104 @@
-import type React from 'react';
-import type { BlobLocation as MUBlobLocation, FileHandleLocation as MUFileHandleLocation, LocalPathLocation as MULocalPathLocation, NoAssemblyRegion as MUNoAssemblyRegion, Region as MUIRegion, UriLocation as MUUriLocation } from './mst.ts';
+import type { ViewSnapshotInput } from '../../PluginManager.ts';
 import type TextSearchManager from '../../TextSearch/TextSearchManager.ts';
-import type assemblyManager from '../../assemblyManager/index.ts';
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
-import type { BaseInternetAccountModel } from '../../pluggableElementTypes/models/index.ts';
+import type { BaseInternetAccountModel, BaseTrackConfig } from '../../pluggableElementTypes/models/index.ts';
+import type { PluginDefinition } from '../../pluginDefinitions.ts';
 import type RpcManager from '../../rpc/RpcManager.ts';
 import type { MenuItem } from '../../ui/index.ts';
+import type { HighlightType } from '../highlights.ts';
 import type { Feature } from '../simpleFeature.ts';
-import type { IAnyStateTreeNode, IStateTreeNode, Instance, SnapshotIn } from '@jbrowse/mobx-state-tree';
-import type { ThemeOptions } from '@mui/material';
-export * from './util.ts';
+import type { TrackConfigChange } from '../trackConfigDelta.ts';
+import type { UriLocation } from './data.ts';
+import type { RenderingServices } from './renderingServices.ts';
+import type { DialogHost, NotificationSink } from './services.ts';
+import type { IAnyStateTreeNode, IAnyType, IStateTreeNode, SnapshotIn } from '@jbrowse/mobx-state-tree';
+import type { Theme, ThemeOptions } from '@mui/material';
+export type { AnyReactComponentType, ClassReturnedBy, InstanceTypeRestrictive, TypeTestedByPredicate, } from './util.ts';
+export type { IsAny } from './isAny.ts';
+export { isSessionServices } from './services.ts';
+export type { DialogComponentType, DialogHost, NotificationLevel, NotificationSink, PaletteHost, RpcCaller, RpcHost, SessionServices, SnackAction, } from './services.ts';
+export type { AssemblyHost, AssemblyManager, RenderingServices, } from './renderingServices.ts';
+export { AuthNeededError, isAuthNeededException, isBlobLocation, isFileHandleLocation, isLocalPathLocation, isUriLocation, } from './data.ts';
+export type { AugmentedRegion, BasePlugin, BlobLocation, FileHandleLocation, FileLocation, JBrowsePlugin, JBrowsePluginVersion, LocalPathLocation, NoAssemblyRegion, PreBlobLocation, PreFileHandleLocation, PreFileLocation, PreLocalPathLocation, PreUriLocation, Region, UriLocation, } from './data.ts';
+/** abstract type for a model that contains multiple views */
 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;
-export type NotificationLevel = 'error' | 'info' | 'warning' | 'success';
-export interface SnackAction {
-    name: React.ReactElement | string;
-    onClick: () => void;
-}
-export type AssemblyManager = Instance<ReturnType<typeof assemblyManager>>;
-export interface BasePlugin {
-    version?: string;
-    name: string;
-    url?: string;
+/**
+ * the slice of a view that track-action menu items need: opening a track, and
+ * (for views that show tracks) reporting which display is active for a given
+ * track so the config editor can expand it and collapse the rest
+ */
+export interface TrackActionView {
+    showTrack: (id: string) => void;
+    launchTrack: (id: string) => Promise<unknown>;
+    getActiveDisplayId?: (trackId: string) => string | undefined;
+}
+/**
+ * controls feature-layout animations. 'system' respects the OS
+ * prefers-reduced-motion setting, 'enabled' always animates, 'disabled' never
+ * animates
+ */
+export type AnimationMode = 'system' | 'enabled' | 'disabled';
+/**
+ * The tracks and assemblies a host offers, which is what a track picker, a
+ * track-name lookup and a search result read.
+ *
+ * App-shaped by construction — `AnyConfigurationModel` is the configuration
+ * schema machinery — so this lives here beside the session family rather than
+ * in `./services.ts`, which is the file that stays cheap to name.
+ */
+export interface TrackCatalog {
+    tracks: AnyConfigurationModel[];
+    assemblies: AnyConfigurationModel[];
+    connectionInstances?: {
+        tracks: AnyConfigurationModel[];
+    }[];
+    getTrackById: (id: string) => AnyConfigurationModel | undefined;
 }
-export interface JBrowsePlugin {
-    name: string;
-    authors: string[];
-    description: string;
-    location: string;
-    url?: string;
-    umdUrl?: string;
-    esmUrl?: string;
-    cjsUrl?: string;
-    license: string;
-    image?: string;
-}
-export type DialogComponentType = React.LazyExoticComponent<React.FC<any>> | React.FC<any>;
-export interface AbstractSessionModel extends AbstractViewContainer {
+/** minimum interface that all session state models must implement */
+export interface AbstractSessionModel extends AbstractViewContainer, RenderingServices, NotificationSink, DialogHost, TrackCatalog {
+    /** @deprecated prefer the per-id reactive `getTrackById(id)` */
     getTracksById: () => Record<string, AnyConfigurationModel>;
     jbrowse: IAnyStateTreeNode;
-    drawerPosition?: string;
+    drawerPosition?: DrawerPosition;
+    stickyViewHeaders?: boolean;
+    viewTitleBars?: boolean;
     configuration: AnyConfigurationModel;
     rpcManager: RpcManager;
     assemblyNames: string[];
-    assemblies: AnyConfigurationModel[];
     selection?: unknown;
     focusedViewId?: string;
     themeName?: string;
-    theme?: ThemeOptions;
+    theme: Theme;
+    animationMode: AnimationMode;
+    scrollZoom: boolean;
+    highlights: readonly HighlightType[];
+    addHighlight: (highlight: HighlightType) => void;
+    removeHighlight: (highlight: HighlightType) => void;
+    updateHighlight: (old: HighlightType, updates: Partial<HighlightType>) => void;
+    setHighlights: (highlights: HighlightType[]) => void;
+    highlightsVisible: boolean;
+    setHighlightsVisible: (arg: boolean) => void;
+    highlightLabelsVisible: boolean;
+    setHighlightLabelsVisible: (arg: boolean) => void;
+    getPreference: (key: string) => unknown;
+    setPreferenceOverride: (key: string, value: unknown) => void;
+    clearPreferenceOverrides: () => void;
+    setScrollZoom: (flag: boolean) => void;
     hovered: unknown;
     setHovered: (arg: unknown) => void;
     setFocusedViewId?: (id: string) => void;
-    allThemes?: () => Record<string, ThemeOptions>;
+    allThemes?: () => Record<string, ThemeOptions & {
+        name?: string;
+    }>;
+    getActiveThemeOptions?: (name?: string) => (ThemeOptions & {
+        name?: string;
+    }) | undefined;
     setSelection: (feature: Feature) => void;
     setSession?: (arg: {
         name: string;
@@ -63,14 +106,17 @@ export interface AbstractSessionModel extends AbstractViewContainer {
     }) => void;
     clearSelection: () => void;
     duplicateCurrentSession?: () => void;
-    notify: (message: string, level?: NotificationLevel, action?: SnackAction) => void;
-    notifyError: (message: string, error?: unknown, extra?: unknown, action?: SnackAction) => void;
-    assemblyManager: AssemblyManager;
     version: string;
-    getTrackActionMenuItems?: (config: AnyConfigurationModel, extraTrackActions?: MenuItem[]) => MenuItem[];
-    getTrackActions?: (arg: AnyConfigurationModel) => MenuItem[];
-    getTrackListMenuItems?: (arg: AnyConfigurationModel) => MenuItem[];
+    gitCommit?: string;
+    getTrackActionMenuItems?: (arg: {
+        config: BaseTrackConfig;
+        view?: TrackActionView;
+    }) => MenuItem[];
+    getTrackActions?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
+    getTrackListMenuItems?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
     addAssembly?: (conf: Record<string, unknown>) => void;
+    addSessionAssembly?: (conf: Record<string, unknown>) => void;
+    sessionAssemblies?: AnyConfigurationModel[];
     removeAssembly?: (name: string) => void;
     textSearchManager?: TextSearchManager;
     connections: AnyConfigurationModel[];
@@ -80,35 +126,188 @@ export interface AbstractSessionModel extends AbstractViewContainer {
     removeTemporaryAssembly?: (arg: string) => void;
     sessionConnections?: AnyConfigurationModel[];
     sessionTracks?: AnyConfigurationModel[];
-    connectionInstances?: {
-        name: string;
-        tracks: AnyConfigurationModel[];
-        configuration: AnyConfigurationModel;
-    }[];
+    trackConfigDeltas?: Record<string, {
+        trackId: string;
+        [key: string]: unknown;
+    }>;
+    getTrackConfigChanges?: (trackId: string) => TrackConfigChange[];
+    resetTrackConfiguration?: (trackId: string) => void;
+    connectionInstances?: ConnectionInstance[];
+    connectionTrackConfigs?: Record<string, {
+        connectionId: string;
+        config: Record<string, unknown>;
+    }>;
     makeConnection?: (arg: AnyConfigurationModel) => void;
     breakConnection?: (arg: AnyConfigurationModel) => void;
-    prepareToBreakConnection?: (arg: AnyConfigurationModel) => [() => void, Record<string, number>] | undefined;
-    adminMode?: boolean;
+    captureConnectionTrack?: (trackId: string) => void;
+    pruneConnectionTrackConfig?: (trackId: string) => void;
+    hydrateConnection?: (connectionId: string) => void;
+    adminMode: boolean;
     showWidget?: (widget: unknown) => void;
     addWidget?: (typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
         type: string;
     }) => Widget;
-    DialogComponent?: DialogComponentType;
-    DialogProps: Record<string, unknown> | undefined;
-    queueDialog<T extends DialogComponentType>(callback: (doneCallback: () => void) => [T, React.ComponentProps<T>]): void;
     name: string;
     id?: string;
-    tracks: AnyConfigurationModel[];
 }
 export declare function isSessionModel(thing: unknown): thing is AbstractSessionModel;
+/** abstract interface for a session allows editing configurations */
 export interface SessionWithConfigEditing extends AbstractSessionModel {
-    editConfiguration(configuration: AnyConfigurationModel): void;
+    editConfiguration(configuration: AnyConfigurationModel, opts?: {
+        expandedDisplayId?: string;
+    }): void;
+    updateTrackConfiguration(trackConf: {
+        trackId: string;
+        [key: string]: unknown;
+    }): void;
 }
 export declare function isSessionModelWithConfigEditing(t: unknown): t is SessionWithConfigEditing;
-export interface SessionWithAddTracks extends AbstractSessionModel {
-    addTrackConf(configuration: AnyConfigurationModel | SnapshotIn<AnyConfigurationModel>): void;
-}
-export declare function isSessionWithAddTracks(t: unknown): t is SessionWithAddTracks;
+/**
+ * A session that edits its tracks as deltas over a base it can hand back: what
+ * a display compares its live config against to say whether a setting is the
+ * reader's or the one the track was configured or added with.
+ */
+export interface SessionWithBaseTrackConfig extends AbstractSessionModel {
+    baseTrackConfig(trackId: string): {
+        trackId: string;
+        [key: string]: unknown;
+    } | undefined;
+}
+export declare function isSessionWithBaseTrackConfig(t: unknown): t is SessionWithBaseTrackConfig;
+/**
+ * A session that hands a shown track a private working copy of its config, so
+ * a non-admin's quick edits land as deltas and never on the shared base
+ * (ADR-032). `TrackConfigurationReference` resolves through it where it is
+ * one, and through `getTrackById` otherwise.
+ */
+export interface SessionWithEditableTrackConfig extends AbstractSessionModel {
+    getEditableTrackConfig(trackId: string, schemaType: IAnyType): AnyConfigurationModel | undefined;
+}
+export declare function isSessionWithEditableTrackConfig(t: unknown): t is SessionWithEditableTrackConfig;
+/**
+ * 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.
+ *
+ * Separate from AbstractViewContainer rather than an optional member on it: the
+ * single-view embedded products implement addView by destructively replacing
+ * their one view, which is the same words for a different contract — there is
+ * no slot and nothing to name. Only a real multi-view container can offer this,
+ * and the guard is what a launcher asks before offering it.
+ */
+export interface SessionWithViewReplacement extends AbstractSessionModel {
+    replaceView<N extends string>(view: AbstractViewModel, typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): AbstractViewModel;
+}
+export declare function isSessionWithViewReplacement(t: unknown): t is SessionWithViewReplacement;
+/**
+ * Whether `view` is a view a launcher can actually offer to swap out — i.e.
+ * whether "Replace current view" would replace anything.
+ *
+ * Both halves are needed. The session must be able to replace a view at all,
+ * and the view must be one of the session's OWN: a launcher resolves its source
+ * with `getContainingView`, which inside a LinearSyntenyView (or a dotplot)
+ * returns the row's inner LGV, and that view occupies no session slot. Replacing
+ * it falls through to `addView`, so the button did what Submit does while saying
+ * otherwise — the launched view appended below the untouched source. Asking this
+ * instead leaves those cases with the one button that tells the truth.
+ */
+export declare function canReplaceView(session: AbstractViewContainer, view: AbstractViewModel | undefined): view is AbstractViewModel;
+/**
+ * Open a launched view, either in the slot `replacing` occupies or appended.
+ *
+ * The branch every launcher that offers "Replace current view" would otherwise
+ * write for itself, kept in one place with the guard it depends on. A session
+ * 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<N extends string>({ session, typeName, initialState, replacing, }: {
+    session: AbstractViewContainer;
+    typeName: N;
+    initialState?: NoInfer<ViewSnapshotInput<N>>;
+    replacing?: AbstractViewModel;
+}): AbstractViewModel;
+/**
+ * abstract interface for a session that can publish a track config to the
+ * shared catalog on behalf of whoever is looking.
+ *
+ * The capability the "Add track" workflows need, and nothing else: an admin's
+ * track goes into the config.json every visitor is served. A feature standing a
+ * track up on the user's behalf wants `SessionWithAddSessionTrack` below —
+ * every session has that one, so reaching for this is a statement about the
+ * workflow rather than a fallback when the other is missing.
+ */
+export interface SessionWithPublishTrackConf extends AbstractSessionModel {
+    publishTrackConf(configuration: AnyConfigurationModel | SnapshotIn<AnyConfigurationModel>): AnyConfigurationModel | undefined;
+}
+export declare function isSessionWithPublishTrackConf(t: unknown): t is SessionWithPublishTrackConf;
+/**
+ * abstract interface for a session that keeps a user's own added/copied tracks
+ * separate from the ones the config ships. `AbstractSessionModel` already
+ * declares `sessionTracks` optionally; this is the narrowing a caller needs to
+ * read it, and it lives here rather than in product-core so a plugin — in-tree
+ * or external — can ask the question through the ABI it already depends on.
+ */
+export interface SessionWithSessionTracks extends AbstractSessionModel {
+    sessionTracks: AnyConfigurationModel[];
+}
+export declare function isSessionWithSessionTracks(t: unknown): t is SessionWithSessionTracks;
+/**
+ * abstract interface for a session that can be given a track belonging to the
+ * session itself.
+ *
+ * The default, and what a feature standing a track up on the user's behalf
+ * wants: an admin opening a VCF in the SV inspector does not thereby mean to
+ * publish it to every visitor. Every session mixin defines
+ * `addSessionTrackConf`, so a false here means the host turned tracks off
+ * (`disableAddTracks`) rather than that this product lacks a session scope —
+ * the guard is about permission, not about capability.
+ */
+export interface SessionWithAddSessionTrack extends AbstractSessionModel {
+    addSessionTrackConf(configuration: AnyConfigurationModel | SnapshotIn<AnyConfigurationModel>): AnyConfigurationModel | undefined;
+}
+export declare function isSessionWithAddSessionTrack(t: unknown): t is SessionWithAddSessionTrack;
+/**
+ * @deprecated ask `isSessionWithAddSessionTrack` for a track a feature stands
+ * up on the user's behalf, or `isSessionWithPublishTrackConf` in an Add-track
+ * workflow.
+ *
+ * Kept because a prebuilt plugin bundle links it by name off
+ * `JBrowseExports['@jbrowse/core/util']` and cannot be recompiled:
+ * jbrowse-plugin-protein3d 0.8.0 gates its structure-track launch on it
+ * (`(0,ll.isSessionWithAddTracks)(e)?e:void 0`), so dropping the export makes
+ * the call `undefined is not a function` inside the menu builder rather than
+ * failing a build. It answers the session-scoped question now, which is the one
+ * that caller wanted — its launch goes on to `session.addTrackConf`, the
+ * session-scoped alias. `graphgenomeviewer` does not reference either name.
+ *
+ * Nothing in tree may call it; `no-restricted-syntax` says so.
+ */
+export declare const isSessionWithAddTracks: typeof isSessionWithAddSessionTrack;
+/** abstract interface for a session that allows adding session assemblies */
+export interface SessionWithAddAssembly extends AbstractSessionModel {
+    addSessionAssembly(conf: Record<string, unknown>): void;
+}
+export declare function isSessionWithAddAssembly(t: unknown): t is SessionWithAddAssembly;
+/** abstract interface for a session that allows deleting track configs */
+export interface SessionWithDeleteTrackConf extends AbstractSessionModel {
+    deleteTrackConf(configuration: AnyConfigurationModel): void;
+}
+export declare function isSessionWithDeleteTrackConf(t: unknown): t is SessionWithDeleteTrackConf;
+/** abstract interface for a session allows adding tracks */
 export interface SessionWithShareURL extends AbstractSessionModel {
     shareURL: string;
 }
@@ -116,7 +315,11 @@ export declare function isSessionWithShareURL(thing: unknown): thing is SessionW
 export interface Widget {
     type: string;
     id: string;
+    view?: {
+        id: string;
+    };
 }
+/** Minimal map interface compatible with both native Map and MST IMSTMap */
 export interface WidgetMap<K, V> {
     size: number;
     has(key: K): boolean;
@@ -127,6 +330,7 @@ export interface WidgetMap<K, V> {
     forEach(callbackfn: (value: V, key: K) => void): void;
     [Symbol.iterator](): IterableIterator<[K, V]>;
 }
+/** abstract interface for a session that manages widgets */
 export interface SessionWithWidgets extends AbstractSessionModel {
     minimized: boolean;
     visibleWidget?: Widget;
@@ -136,51 +340,217 @@ export interface SessionWithWidgets extends AbstractSessionModel {
     addWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
         type: string;
     }): Widget;
+    openWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
+        type: string;
+    }): Widget;
     showWidget(widget: unknown): void;
     hideWidget(widget: unknown): void;
 }
+/**
+ * Which side of the main content the drawer sits on. A closed set rather than a
+ * string: the drawer's three readers disagree about what an unrecognized value
+ * means -- the grid template treats anything but `right` as a left column, the
+ * resize handle treats anything but `left` as a right-hand one, and the app
+ * shell renders the drawer only for an exact match, so a junk value left a
+ * reserved column with nothing in it.
+ */
+export type DrawerPosition = 'left' | 'right';
 export interface SessionWithDrawerWidgets extends SessionWithWidgets {
     drawerWidth: number;
-    resizeDrawer(arg: number): number;
+    /**
+     * @param distance - px the handle travelled
+     * @param availableWidth - width the drawer and the main area share, which
+     * bounds the drawer. Defaults to the window, which is only the same thing in a
+     * full-window app
+     */
+    resizeDrawer(distance: number, availableWidth?: number): number;
     minimizeWidgetDrawer(): void;
     showWidgetDrawer: () => void;
-    drawerPosition: string;
-    setDrawerPosition(arg: string): void;
+    /** whether the drawer column is on screen at all */
+    drawerVisible: boolean;
+    drawerPosition: DrawerPosition;
+    setDrawerPosition(arg: DrawerPosition): void;
+    /** true while the visible widget is shown in a modal instead of the drawer */
+    poppedOut: boolean;
+    popoutWidget(): void;
+    returnWidgetToDrawer(): void;
+    /** true on a host with no room for a drawer, where every widget is a modal */
+    modalWidgets: boolean;
+    setModalWidgets(flag: boolean): void;
+    /** whether the visible widget is on screen in a modal */
+    modalWidgetVisible: boolean;
+    closeModalWidget(): void;
 }
 export declare function isSessionModelWithWidgets(thing: unknown): thing is SessionWithWidgets;
-export interface SessionWithConnections {
+/** a live connection instance held in a session's `connectionInstances` */
+export interface ConnectionInstance {
+    name: string;
+    connectionId: string;
+    tracks: AnyConfigurationModel[];
+    configuration: AnyConfigurationModel;
+    loading: boolean;
+}
+/** a session that can turn connections on and off */
+export interface SessionWithConnections extends AbstractSessionModel {
+    connectionInstances: ConnectionInstance[];
     makeConnection: (arg: AnyConfigurationModel) => void;
+    breakConnection: (arg: AnyConfigurationModel) => void;
+    deleteConnection: (arg: AnyConfigurationModel) => void;
 }
 export declare function isSessionModelWithConnections(thing: unknown): thing is SessionWithConnections;
-export interface SessionWithConnectionEditing {
-    addConnectionConf: (arg: AnyConfigurationModel) => void;
+/** a session that can also add new connection configs */
+export interface SessionWithConnectionEditing extends SessionWithConnections {
+    addConnectionConf: (arg: AnyConfigurationModel) => AnyConfigurationModel;
 }
 export declare function isSessionModelWithConnectionEditing(thing: unknown): thing is SessionWithConnectionEditing;
 export interface SessionWithSessionPlugins extends AbstractSessionModel {
-    sessionPlugins: JBrowsePlugin[];
-    addSessionPlugin: (plugin: BasePlugin) => void;
-    removeSessionPlugin: (plugin: Record<string, unknown> | undefined) => void;
+    sessionPlugins: (PluginDefinition & {
+        name: string;
+    })[];
+    addSessionPlugin: (plugin: PluginDefinition & {
+        name: string;
+    }) => void;
+    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 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 & {
+        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 */
 export interface SelectionContainer extends AbstractSessionModel {
     selection?: unknown;
     setSelection(thing: unknown): void;
 }
 export declare function isSelectionContainer(thing: unknown): thing is SelectionContainer;
+/** abstract interface for a session allows applying focus to views and widgets */
 export interface SessionWithFocusedViewAndDrawerWidgets extends SessionWithDrawerWidgets {
     focusedViewId: string | undefined;
     setFocusedViewId(id: string): void;
 }
+/**
+ * the slice of a view that the track-selector and add-track widgets write into:
+ * a track list, the assemblies it may show tracks for, and the open/close
+ * actions. A plain view is its own track container; a view that owns several
+ * (the synteny view's per-level track lists) hands them out via
+ * `trackContainerFor`.
+ */
+export interface TrackContainer {
+    tracks: {
+        configuration: {
+            trackId: string;
+        };
+        displays: {
+            type: string;
+            configuration: AnyConfigurationModel;
+        }[];
+    }[];
+    assemblyNames?: string[];
+    /**
+     * The trailing three are `showTrackGeneric`'s, and only the last has a caller
+     * here: `addTrackFromWidget` passes a config the session must not keep. A
+     * container that implements the one-argument form still satisfies this, and
+     * drops the config — `showTrackGeneric` then finds no track by that id and
+     * throws "Could not resolve identifier", which is a snackbar rather than a
+     * 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;
+}
+/** minimum interface that all view state models must implement */
 export interface AbstractViewModel {
     id: string;
     type: string;
     width: number;
     minimized: boolean;
+    /**
+     * Whether the view's container has its body in the DOM — see
+     * `BaseViewModel.bodyMounted`. A display's phase excuses the first paint it
+     * will never make while this is false.
+     */
+    bodyMounted: boolean;
+    /**
+     * The same, counting the views this one is nested inside — a synteny row has
+     * no container of its own to write `bodyMounted`, so that flag alone reads
+     * `true` for a row whose whole stack is off screen — and false while the body
+     * renders none of its displays (`rendersDisplays`). This is what a display's
+     * phase asks.
+     */
+    effectiveBodyMounted: boolean;
+    /** See `BaseViewModel.rendersDisplays`. */
+    rendersDisplays: boolean;
     setWidth(width: number): void;
+    setBodyMounted(flag: boolean): void;
     setMinimized(flag: boolean): void;
     displayName: string | undefined;
     setDisplayName: (arg: string) => void;
     menuItems: () => MenuItem[];
+    assemblyNames?: string[];
+    /**
+     * a track container owned by this view, by its id. Only views holding more
+     * than one track list implement it; for every other view the widget targets
+     * the view itself.
+     */
+    trackContainerFor?: (id: string) => TrackContainer | undefined;
+    /**
+     * the node a display in this view lays its regions out against, where that
+     * is not the view's own box — the circular view's strip. A display's
+     * foundation reads its host through `containingHost`, which answers this
+     * before the view itself.
+     */
+    regionHost?: unknown;
+    /**
+     * every track container this view owns INSTEAD of a `tracks` array of its
+     * own. The synteny view is the only one: its tracks hang off the levels, one
+     * per band, so anything walking `view.tracks` to reach a display finds
+     * nothing there and reads a still-fetching synteny view as idle.
+     * `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 = {
@@ -189,17 +559,19 @@ type Display = {
 export interface AbstractTrackModel {
     id: string;
     displays: AbstractDisplayModel[];
-    configuration: AnyConfigurationModel & {
+    configuration: BaseTrackConfig & {
         displays: Display[];
     };
     minimized: boolean;
+    resizing: boolean;
+    setResizing: (flag: boolean) => void;
+    persistConfigurationNow?: () => void;
 }
 export declare function isTrackModel(thing: unknown): thing is AbstractTrackModel;
 export interface AbstractDisplayModel {
     id: string;
     parentTrack: AbstractTrackModel;
     renderDelay: number;
-    rendererType: any;
     cannotBeRenderedReason?: string;
 }
 export declare function isDisplayModel(thing: unknown): thing is AbstractDisplayModel;
@@ -208,16 +580,23 @@ export interface TrackViewModel extends AbstractViewModel {
     hideTrack(trackId: string): void;
 }
 export declare function isTrackViewModel(thing: unknown): thing is TrackViewModel;
+/** minimum interface for the root MST model of a JBrowse app */
 export interface AbstractRootModel {
     jbrowse: IAnyStateTreeNode;
     session?: AbstractSessionModel;
+    setSession?(arg: {
+        name: string;
+        [key: string]: unknown;
+    }): void;
     setDefaultSession?(): void;
-    adminMode?: boolean;
+    adminMode: boolean;
     error?: unknown;
 }
+/** root model with more included for the heavier JBrowse web and desktop app */
 export interface AppRootModel extends AbstractRootModel {
     internetAccounts: BaseInternetAccountModel[];
     findAppropriateInternetAccount(location: UriLocation): BaseInternetAccountModel | undefined;
+    createEphemeralInternetAccount(internetAccountId: string, initialSnapshot: Record<string, unknown>, url: string): BaseInternetAccountModel;
 }
 export declare function isAppRootModel(thing: unknown): thing is AppRootModel;
 export interface RootModelWithInternetAccounts extends AbstractRootModel {
@@ -225,58 +604,17 @@ export interface RootModelWithInternetAccounts extends AbstractRootModel {
     findAppropriateInternetAccount(location: UriLocation): BaseInternetAccountModel | undefined;
 }
 export declare function isRootModelWithInternetAccounts(thing: unknown): thing is RootModelWithInternetAccounts;
+/**
+ * a root model that manages global menus. Every method records a contribution
+ * that is applied when the menu opens, so none of them can report where the
+ * item landed
+ */
 export interface AbstractMenuManager {
     appendMenu(menuName: string): void;
-    insertMenu(menuName: string, position: number): number;
-    insertInMenu(menuName: string, menuItem: MenuItem, position: number): number;
-    appendToMenu(menuName: string, menuItem: MenuItem): number;
-    appendToSubMenu(menuPath: string[], menuItem: MenuItem): number;
-    insertInSubMenu(menuPath: string[], menuItem: MenuItem, position: number): number;
+    insertMenu(menuName: string, position: number): void;
+    insertInMenu(menuName: string, menuItem: MenuItem, position: number): void;
+    appendToMenu(menuName: string, menuItem: MenuItem): void;
+    appendToSubMenu(menuPath: string[], menuItem: MenuItem): void;
+    insertInSubMenu(menuPath: string[], menuItem: MenuItem, position: number): void;
 }
 export declare function isAbstractMenuManager(thing: unknown): thing is AbstractMenuManager;
-export interface NoAssemblyRegion extends SnapshotIn<typeof MUNoAssemblyRegion> {
-}
-export interface Region extends SnapshotIn<typeof MUIRegion> {
-}
-export interface AugmentedRegion extends Region {
-    originalRefName?: string;
-}
-export interface LocalPathLocation extends SnapshotIn<typeof MULocalPathLocation> {
-}
-export interface UriLocation extends SnapshotIn<typeof MUUriLocation> {
-}
-export declare function isUriLocation(location: unknown): location is UriLocation;
-export declare function isLocalPathLocation(location: unknown): location is LocalPathLocation;
-export declare function isBlobLocation(location: unknown): location is BlobLocation;
-export interface FileHandleLocation extends SnapshotIn<typeof MUFileHandleLocation> {
-}
-export declare function isFileHandleLocation(location: unknown): location is FileHandleLocation;
-export declare class AuthNeededError extends Error {
-    message: string;
-    url: string;
-    constructor(message: string, url: string);
-}
-export declare class RetryError extends Error {
-    message: string;
-    internetAccountId: string;
-    constructor(message: string, internetAccountId: string);
-}
-export declare function isAuthNeededException(exception: unknown): exception is AuthNeededError;
-export declare function isRetryException(exception: Error): boolean;
-export interface BlobLocation extends SnapshotIn<typeof MUBlobLocation> {
-}
-export type FileLocation = LocalPathLocation | UriLocation | BlobLocation | FileHandleLocation;
-export interface PreUriLocation {
-    uri: string;
-}
-export interface PreLocalPathLocation {
-    localPath: string;
-}
-export interface PreBlobLocation {
-    blob: File;
-}
-export interface PreFileHandleLocation {
-    handle: FileSystemFileHandle;
-}
-export type PreFileLocation = PreUriLocation | PreLocalPathLocation | PreBlobLocation | PreFileHandleLocation;
-export { default as TextSearchManager } from '../../TextSearch/TextSearchManager.ts';