@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/pluggableElementTypes/addMenuItems.d.ts

@@ -0,0 +1,87 @@
+import type PluginManager from '../PluginManager.ts';
+import type { DisplayTypeName, DisplayTypeRegistry, ViewTypeName, ViewTypeRegistry } from '../PluginManager.ts';
+import type { MenuItem } from '../ui/MenuTypes.ts';
+import type { IAnyType, Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * The instance a registry entry's state model produces. The registries are
+ * declared empty here and filled by module augmentation, so inside this package
+ * every one of these resolves to `never` — see {@link extendViewType} for why
+ * that is fine and what the caller gets instead.
+ */
+type ModelOf<T> = T extends IAnyType ? Instance<T> : never;
+/**
+ * The methods on a model that return a menu. Derived from the model rather than
+ * listed, which is what makes a renamed or retired method a compile error at
+ * the call site: there are six of them across views and displays (`menuItems`,
+ * `trackMenuItems`, `contextMenuItems`, `rubberBandMenuItems`,
+ * `rubberBandLaunchMenuItems`, `highlightMenuItems`), they are a convention
+ * rather than one declared interface, and a contribution to a name the model no
+ * longer has is otherwise silent.
+ *
+ * Given several names, `M` arrives as the union of their models and `keyof M`
+ * is what they share, so a menu only one of them has is a compile error rather
+ * than a `self[menu]` that is undefined on the others.
+ */
+type MenuMethodName<M> = {
+    [K in keyof M]: M[K] extends (...args: never[]) => MenuItem[] ? K : never;
+}[keyof M];
+/**
+ * What a contributor is handed: the model, plus whatever the menu method itself
+ * takes (`highlightMenuItems` gets the highlight). Returning `undefined` adds
+ * nothing, which is how a contribution scoped to some state opts out.
+ */
+type MenuItemsCallback<M, K extends keyof M> = (model: M, ...args: M[K] extends (...args: infer A) => unknown ? A : never) => MenuItem | MenuItem[] | undefined;
+interface MenuItemsOptions<M, K extends keyof M> {
+    /** which menu to add to */
+    menu: K;
+    /**
+     * a submenu label to collect the items under, e.g. `LAUNCH_LABEL`. The
+     * submenu is created once and shared, so several plugins naming the same
+     * group land in one place rather than each adding a top-level row
+     */
+    group?: string;
+    items: MenuItemsCallback<M, K>;
+}
+/**
+ * Add items to a menu on a view type belonging to another plugin, e.g. an "open
+ * a synteny view on this locus" entry on the linear genome view. Pass an array
+ * to contribute the same items to several types at once.
+ *
+ * Prefer this to extending the state model by hand. The model is the right seam
+ * — `menuItems()` is called from seven pieces of view chrome, and only the model
+ * reaches all of them — but writing the extension out means `stateModel.views`,
+ * capturing the previous method, spreading it, and remembering to return the
+ * whole array. Each of those is silent when it goes wrong, and the middle one
+ * costs every plugin registered earlier its items.
+ *
+ * ```ts
+ * addViewMenuItems(pluginManager, 'LinearGenomeView', {
+ *   menu: 'rubberBandLaunchMenuItems',
+ *   items: self => ({ label: 'Consensus sequence', onClick: () => {} }),
+ * })
+ * ```
+ *
+ * A contribution needing state or actions of its own is still a model
+ * extension: use {@link extendViewType} and add the menu items in the same
+ * `.views` block, so the items and the actions they call stay together.
+ */
+export declare function addViewMenuItems<N extends ViewTypeName, K extends MenuMethodName<ModelOf<ViewTypeRegistry[N]>>>(pluginManager: PluginManager, name: N | readonly N[], options: MenuItemsOptions<ModelOf<ViewTypeRegistry[N]>, K>): void;
+/**
+ * Add items to a menu on a display type belonging to another plugin, e.g. an
+ * "open this read in a dotplot" entry on the alignments display's context menu.
+ * See {@link addViewMenuItems}; the name is checked against
+ * `DisplayTypeRegistry`.
+ *
+ * ```ts
+ * addDisplayMenuItems(pluginManager, 'LinearAlignmentsDisplay', {
+ *   menu: 'contextMenuItems',
+ *   group: LAUNCH_LABEL,
+ *   items: self =>
+ *     self.contextMenuFeatureId === undefined
+ *       ? undefined
+ *       : { label: 'Dotplot of read vs ref', onClick: () => {} },
+ * })
+ * ```
+ */
+export declare function addDisplayMenuItems<N extends DisplayTypeName, K extends MenuMethodName<ModelOf<DisplayTypeRegistry[N]>>>(pluginManager: PluginManager, name: N | readonly N[], options: MenuItemsOptions<ModelOf<DisplayTypeRegistry[N]>, K>): void;
+export {};

package/esm/pluggableElementTypes/addMenuItems.js

@@ -0,0 +1,82 @@
+import { pushIntoSubMenu } from '../ui/launchViewMenu.js';
+import { extendDisplayType, extendViewType } from './extendElementType.js';
+// The shared fold. Both entry points are thin wrappers rather than overloads of
+// one function: with overloads, a `menu` the model does not have stops matching
+// the view signature, falls through to the display one, and reports as "'view'
+// does not exist in type …" — an error about the wrong parameter, for a mistake
+// this helper exists to name precisely.
+function menuExtension(menu, group, items) {
+    return (stateModel) => stateModel.views((self) => {
+        const superMenu = self[menu];
+        return {
+            // Copied rather than pushed into: `group` reaches inside an item the
+            // method before us built, and the array it came from is this call's
+            // to change, not one an earlier caller is still holding.
+            [menu](...args) {
+                const built = [...superMenu(...args)];
+                const contributed = items(self, ...args);
+                if (contributed !== undefined) {
+                    for (const item of Array.isArray(contributed)
+                        ? contributed
+                        : [contributed]) {
+                        if (group === undefined) {
+                            built.push(item);
+                        }
+                        else {
+                            pushIntoSubMenu(built, group, item);
+                        }
+                    }
+                }
+                return built;
+            },
+        };
+    });
+}
+/**
+ * Add items to a menu on a view type belonging to another plugin, e.g. an "open
+ * a synteny view on this locus" entry on the linear genome view. Pass an array
+ * to contribute the same items to several types at once.
+ *
+ * Prefer this to extending the state model by hand. The model is the right seam
+ * — `menuItems()` is called from seven pieces of view chrome, and only the model
+ * reaches all of them — but writing the extension out means `stateModel.views`,
+ * capturing the previous method, spreading it, and remembering to return the
+ * whole array. Each of those is silent when it goes wrong, and the middle one
+ * costs every plugin registered earlier its items.
+ *
+ * ```ts
+ * addViewMenuItems(pluginManager, 'LinearGenomeView', {
+ *   menu: 'rubberBandLaunchMenuItems',
+ *   items: self => ({ label: 'Consensus sequence', onClick: () => {} }),
+ * })
+ * ```
+ *
+ * A contribution needing state or actions of its own is still a model
+ * extension: use {@link extendViewType} and add the menu items in the same
+ * `.views` block, so the items and the actions they call stay together.
+ */
+export function addViewMenuItems(pluginManager, name, options) {
+    const { menu, group, items } = options;
+    extendViewType(pluginManager, name, menuExtension(menu, group, items));
+}
+/**
+ * Add items to a menu on a display type belonging to another plugin, e.g. an
+ * "open this read in a dotplot" entry on the alignments display's context menu.
+ * See {@link addViewMenuItems}; the name is checked against
+ * `DisplayTypeRegistry`.
+ *
+ * ```ts
+ * addDisplayMenuItems(pluginManager, 'LinearAlignmentsDisplay', {
+ *   menu: 'contextMenuItems',
+ *   group: LAUNCH_LABEL,
+ *   items: self =>
+ *     self.contextMenuFeatureId === undefined
+ *       ? undefined
+ *       : { label: 'Dotplot of read vs ref', onClick: () => {} },
+ * })
+ * ```
+ */
+export function addDisplayMenuItems(pluginManager, name, options) {
+    const { menu, group, items } = options;
+    extendDisplayType(pluginManager, name, menuExtension(menu, group, items));
+}

package/esm/pluggableElementTypes/extendElementType.d.ts

@@ -0,0 +1,30 @@
+import type PluginManager from '../PluginManager.ts';
+import type { DisplayTypeName, DisplayTypeRegistry, ViewTypeName, ViewTypeRegistry } from '../PluginManager.ts';
+import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
+/**
+ * Replace a view type's state model with an extended one, e.g. to add a menu
+ * item to `LinearGenomeView`. Pass an array to extend several at once, which is
+ * how a contribution reaches a family: the tree spells a display family as a
+ * shared mixin set rather than a chain, so there is no parent to name — see
+ * `reference/REJECTED_IDEAS.md`, "Give a pluggable element an `extendsType`".
+ *
+ * `Core-extendPluggableElement` fires for every pluggable element there is —
+ * adapters, widgets, RPC methods, all of them — so a callback written against
+ * it directly has to match the name, convince TypeScript the element is the
+ * kind that name implies, and remember to return the element. The middle one
+ * has no honest answer at the call site, which is why the two plugins that
+ * tried both landed on a type guard asserting `elt is DisplayType` from a
+ * string compare, which would go on asserting it if the name ever belonged to
+ * something else.
+ *
+ * Here the group is checked rather than asserted — it comes from
+ * `addElementType`, which knew it all along — and the name is checked against
+ * `ViewTypeRegistry`, so the state model arrives typed and a rename is a
+ * compile error rather than an extension that quietly stops applying.
+ */
+export declare function extendViewType<N extends ViewTypeName>(pluginManager: PluginManager, name: N | readonly N[], extend: (stateModel: ViewTypeRegistry[N]) => IAnyModelType): void;
+/**
+ * Replace a display type's state model with an extended one. See
+ * {@link extendViewType}; the name is checked against `DisplayTypeRegistry`.
+ */
+export declare function extendDisplayType<N extends DisplayTypeName>(pluginManager: PluginManager, name: N | readonly N[], extend: (stateModel: DisplayTypeRegistry[N]) => IAnyModelType): void;

package/esm/pluggableElementTypes/extendElementType.js

@@ -0,0 +1,68 @@
+// The one cast, in one place, named. `extend` is written by a caller against a
+// registry entry; this package cannot name that entry (see extendViewType), so
+// the callback is re-read as taking the base model type to call it.
+function widen(extend) {
+    return extend;
+}
+// Built once per registration rather than per element: the point fires for
+// every pluggable element there is, and every callback registered on it runs
+// for each one.
+function namesOf(name) {
+    return new Set(typeof name === 'string' ? [name] : name);
+}
+/**
+ * Replace a view type's state model with an extended one, e.g. to add a menu
+ * item to `LinearGenomeView`. Pass an array to extend several at once, which is
+ * how a contribution reaches a family: the tree spells a display family as a
+ * shared mixin set rather than a chain, so there is no parent to name — see
+ * `reference/REJECTED_IDEAS.md`, "Give a pluggable element an `extendsType`".
+ *
+ * `Core-extendPluggableElement` fires for every pluggable element there is —
+ * adapters, widgets, RPC methods, all of them — so a callback written against
+ * it directly has to match the name, convince TypeScript the element is the
+ * kind that name implies, and remember to return the element. The middle one
+ * has no honest answer at the call site, which is why the two plugins that
+ * tried both landed on a type guard asserting `elt is DisplayType` from a
+ * string compare, which would go on asserting it if the name ever belonged to
+ * something else.
+ *
+ * Here the group is checked rather than asserted — it comes from
+ * `addElementType`, which knew it all along — and the name is checked against
+ * `ViewTypeRegistry`, so the state model arrives typed and a rename is a
+ * compile error rather than an extension that quietly stops applying.
+ */
+export function extendViewType(pluginManager, name, extend) {
+    const names = namesOf(name);
+    pluginManager.addToExtensionPoint('Core-extendPluggableElement', (element, props) => {
+        if (props.group === 'view' && names.has(element.name)) {
+            // The group check established this element is a ViewType, and the
+            // registry says which one, so the read is proven. The body still works
+            // in `IAnyModelType`: `ViewTypeRegistry` is declared empty here and
+            // filled by module augmentation, so inside this package `ViewTypeName`
+            // is `never` and `ViewTypeRegistry[N]` with it — a value of that type
+            // cannot be produced or consumed, and compiling core alone fails on
+            // both. The precise type is what the *caller* gets, which is the whole
+            // point of the signature; widening it once here costs nothing, since
+            // the only operation is handing the model to `extend` and storing what
+            // comes back.
+            const view = element;
+            view.stateModel = widen(extend)(view.stateModel);
+        }
+        return element;
+    });
+}
+/**
+ * Replace a display type's state model with an extended one. See
+ * {@link extendViewType}; the name is checked against `DisplayTypeRegistry`.
+ */
+export function extendDisplayType(pluginManager, name, extend) {
+    const names = namesOf(name);
+    pluginManager.addToExtensionPoint('Core-extendPluggableElement', (element, props) => {
+        if (props.group === 'display' && names.has(element.name)) {
+            // widened for the reason in extendViewType
+            const display = element;
+            display.stateModel = widen(extend)(display.stateModel);
+        }
+        return element;
+    });
+}

package/esm/pluggableElementTypes/index.d.ts

@@ -2,26 +2,26 @@ import type AdapterType from './AdapterType.ts';
 import type AddTrackWorkflowType from './AddTrackWorkflowType.ts';
 import type ConnectionType from './ConnectionType.ts';
 import type DisplayType from './DisplayType.ts';
-import type GlyphType from './GlyphType.ts';
 import type InternetAccountType from './InternetAccountType.ts';
 import type RpcMethodType from './RpcMethodType.ts';
 import type TextSearchAdapterType from './TextSearchAdapterType.ts';
 import type TrackType from './TrackType.ts';
 import type ViewType from './ViewType.ts';
 import type WidgetType from './WidgetType.ts';
-import type RendererType from './renderers/RendererType.tsx';
-export * from './renderers/index.ts';
-export * from './models/index.ts';
-export type PluggableElementType = AdapterType | ConnectionType | RendererType | WidgetType | TrackType | DisplayType | ViewType | RpcMethodType | InternetAccountType | TextSearchAdapterType | AddTrackWorkflowType | GlyphType;
+export { BaseConnectionModelFactory, BaseDisplay, type BaseDisplayModel, type BaseDisplayStateModel, BaseInternetAccountConfig, type BaseInternetAccountModel, type BaseInternetAccountStateModel, type BaseTrackConfig, type BaseTrackModel, type BaseTrackStateModel, BaseViewModel, type DisplayModel, type FileTypeExporter, HighlightsMixin, type IBaseViewModel, InternetAccount, addDisplayConfigMigration, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, type TrackConfigSnapshot, trackConfigActions, } from './models/index.ts';
+export type PluggableElementType = AdapterType | ConnectionType | WidgetType | TrackType | DisplayType | ViewType | RpcMethodType | InternetAccountType | TextSearchAdapterType | AddTrackWorkflowType;
+export { extendDisplayType, extendViewType } from './extendElementType.ts';
+export { addDisplayMenuItems, addViewMenuItems } from './addMenuItems.ts';
 export { default as AdapterType } from './AdapterType.ts';
-export { default as RendererType } from './renderers/RendererType.tsx';
 export { default as ConnectionType } from './ConnectionType.ts';
 export { default as TrackType } from './TrackType.ts';
 export { default as WidgetType } from './WidgetType.ts';
 export { default as ViewType } from './ViewType.ts';
 export { default as DisplayType } from './DisplayType.ts';
 export { default as InternetAccountType } from './InternetAccountType.ts';
-export { default as GlyphType } from './GlyphType.ts';
 export { default as RpcMethodType } from './RpcMethodType.ts';
+export { default as RpcMethodTypeWithRenameRegion } from './RpcMethodTypeWithRenameRegion.ts';
+export { default as RpcMethodTypeWithRenameRegions } from './RpcMethodTypeWithRenameRegions.ts';
 export { default as AddTrackWorkflowType } from './AddTrackWorkflowType.ts';
+export type { AddTrackWorkflowCategory } from './AddTrackWorkflowType.ts';
 export { default as TextSearchAdapterType } from './TextSearchAdapterType.ts';

package/esm/pluggableElementTypes/index.js

@@ -1,14 +1,24 @@
-export * from "./renderers/index.js";
-export * from "./models/index.js";
-export { default as AdapterType } from "./AdapterType.js";
-export { default as RendererType } from "./renderers/RendererType.js";
-export { default as ConnectionType } from "./ConnectionType.js";
-export { default as TrackType } from "./TrackType.js";
-export { default as WidgetType } from "./WidgetType.js";
-export { default as ViewType } from "./ViewType.js";
-export { default as DisplayType } from "./DisplayType.js";
-export { default as InternetAccountType } from "./InternetAccountType.js";
-export { default as GlyphType } from "./GlyphType.js";
-export { default as RpcMethodType } from "./RpcMethodType.js";
-export { default as AddTrackWorkflowType } from "./AddTrackWorkflowType.js";
-export { default as TextSearchAdapterType } from "./TextSearchAdapterType.js";
+export { BaseConnectionModelFactory, BaseDisplay, BaseInternetAccountConfig, BaseViewModel, HighlightsMixin, InternetAccount, addDisplayConfigMigration, baseConnectionConfig, createBaseTrackConfig, createBaseTrackModel, preprocessTrackConfigSnapshot, trackConfigActions, } from './models/index.js';
+export { extendDisplayType, extendViewType } from './extendElementType.js';
+export { addDisplayMenuItems, addViewMenuItems } from './addMenuItems.js';
+export { default as AdapterType } from './AdapterType.js';
+export { default as ConnectionType } from './ConnectionType.js';
+export { default as TrackType } from './TrackType.js';
+export { default as WidgetType } from './WidgetType.js';
+export { default as ViewType } from './ViewType.js';
+export { default as DisplayType } from './DisplayType.js';
+export { default as InternetAccountType } from './InternetAccountType.js';
+export { default as RpcMethodType } from './RpcMethodType.js';
+// The two region-renaming bases, which nearly every RPC method that takes a
+// viewport wants — without them an external plugin deep-imports the file and
+// bundles its own copy, which is only harmless because RPC methods are keyed by
+// name (PluginManager.rpcMethods) and nothing does an instanceof.
+// `RpcMethodTypeWithFiltersAndRenameRegions` is deliberately not here: it pulls
+// in `renderers/util/serializableFilterChain`, and RFC-001 §9 deletes
+// `pluggableElementTypes/renderers/*` after the legacy renderer migration. This
+// barrel is served as ABI, so exporting it would pin a directory we intend to
+// remove.
+export { default as RpcMethodTypeWithRenameRegion } from './RpcMethodTypeWithRenameRegion.js';
+export { default as RpcMethodTypeWithRenameRegions } from './RpcMethodTypeWithRenameRegions.js';
+export { default as AddTrackWorkflowType } from './AddTrackWorkflowType.js';
+export { default as TextSearchAdapterType } from './TextSearchAdapterType.js';

package/esm/pluggableElementTypes/models/BaseConnectionModelFactory.d.ts

@@ -1,29 +1,84 @@
 import type PluginManager from '../../PluginManager.ts';
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
 type TrackConf = AnyConfigurationModel | Record<string, unknown>;
+/**
+ * #stateModel BaseConnectionModel
+ */
 declare function stateModelFactory(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    tracks: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyModelType>;
-    configuration: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        name: {
-            type: string;
-            defaultValue: string;
-            description: string;
+    /**
+     * #property
+     */
+    tracks: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    /**
+     * #property
+     */
+    configuration: import("../../configuration/configurationSchema.ts").IConfigurationReference<import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly name: {
+            readonly type: "string";
+            readonly defaultValue: "nameOfConnection";
+            readonly description: "a unique name for this connection";
         };
-        assemblyNames: {
-            type: string;
-            defaultValue: never[];
-            description: string;
+        readonly assemblyNames: {
+            readonly type: "stringArray";
+            readonly defaultValue: readonly [];
+            readonly description: "optional list of names of assemblies in this connection";
         };
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "connectionId">>;
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "connectionId">>>;
+    /**
+     * #property
+     * set when the connection is being re-established on session load (its
+     * open tracks are already restored from `connectionTrackConfigs`), so
+     * `doConnect` suppresses first-connect side effects like launching a view
+     * or a success snackbar. Runtime-only: connection instances aren't
+     * serialized.
+     */
+    silent: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
 }, {
-    connect(_arg: AnyConfigurationModel): void;
+    /**
+     * #volatile
+     * true while `connect()` is fetching this connection's tracks; drives a
+     * loading affordance in the track selector. Distinct from an empty
+     * `tracks` array, which is also the state of a connection that loaded
+     * successfully but has no tracks.
+     */
+    loading: boolean;
+} & {
+    /**
+     * #getter
+     * the connection's unique id, resolved from its configuration (the config
+     * is the source of truth; connection names are not guaranteed unique)
+     */
+    readonly connectionId: string;
+    /**
+     * #getter
+     */
+    readonly name: string;
+} & {
+    /**
+     * #action
+     * no-op hook; concrete connections (UCSC/JB2 track hubs, etc.) override
+     * this to fetch and populate their `tracks`. Returns a promise so
+     * `afterAttach` can clear the loading flag once the fetch settles.
+     */
+    connect(): Promise<void>;
+    /**
+     * #action
+     */
+    setLoading(loading: boolean): void;
 } & {
     afterAttach(): void;
+    /**
+     * #action
+     */
     addTrackConf(trackConf: TrackConf): any;
+    /**
+     * #action
+     */
     addTrackConfs(trackConfs: TrackConf[]): void;
-    setTrackConfs(trackConfs: AnyConfigurationModel[]): void;
-    clear(): void;
+    /**
+     * #action
+     */
+    setTrackConfs(trackConfs: TrackConf[]): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type BaseConnectionModel = ReturnType<typeof stateModelFactory>;
 export default stateModelFactory;

package/esm/pluggableElementTypes/models/BaseConnectionModelFactory.js

@@ -1,35 +1,115 @@
-import { cast, types } from '@jbrowse/mobx-state-tree';
-import configSchema from "./baseConnectionConfig.js";
-import { ConfigurationReference } from "../../configuration/index.js";
+import { cast, isAlive, types } from '@jbrowse/mobx-state-tree';
+import { ConfigurationReference, readConfObject, } from '../../configuration/index.js';
+import configSchema from './baseConnectionConfig.js';
+/**
+ * #stateModel BaseConnectionModel
+ */
 function stateModelFactory(pluginManager) {
     return types
         .model('Connection', {
-        name: types.identifier,
+        /**
+         * #property
+         */
         tracks: types.array(pluginManager.pluggableConfigSchemaType('track')),
+        /**
+         * #property
+         */
         configuration: ConfigurationReference(configSchema),
+        /**
+         * #property
+         * set when the connection is being re-established on session load (its
+         * open tracks are already restored from `connectionTrackConfigs`), so
+         * `doConnect` suppresses first-connect side effects like launching a view
+         * or a success snackbar. Runtime-only: connection instances aren't
+         * serialized.
+         */
+        silent: types.optional(types.boolean, false),
     })
-        .actions(() => ({
-        connect(_arg) { },
+        .volatile(() => ({
+        /**
+         * #volatile
+         * true while `connect()` is fetching this connection's tracks; drives a
+         * loading affordance in the track selector. Distinct from an empty
+         * `tracks` array, which is also the state of a connection that loaded
+         * successfully but has no tracks.
+         */
+        loading: false,
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * the connection's unique id, resolved from its configuration (the config
+         * is the source of truth; connection names are not guaranteed unique)
+         */
+        get connectionId() {
+            return self.configuration.connectionId;
+        },
+        /**
+         * #getter
+         */
+        get name() {
+            return readConfObject(self.configuration, 'name');
+        },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * no-op hook; concrete connections (UCSC/JB2 track hubs, etc.) override
+         * this to fetch and populate their `tracks`. Returns a promise so
+         * `afterAttach` can clear the loading flag once the fetch settles.
+         */
+        connect() {
+            return Promise.resolve();
+        },
+        /**
+         * #action
+         */
+        setLoading(loading) {
+            self.loading = loading;
+        },
     }))
         .actions(self => ({
         afterAttach() {
             if (self.tracks.length === 0) {
-                self.connect(self.configuration);
+                self.setLoading(true);
+                // connect() is overridden to return the (lazy) fetch promise; clear
+                // the loading flag once it settles. On failure doConnect breaks the
+                // connection (destroying this node), so guard with isAlive.
+                void self.connect().finally(() => {
+                    if (isAlive(self)) {
+                        self.setLoading(false);
+                    }
+                });
             }
         },
+        /**
+         * #action
+         */
         addTrackConf(trackConf) {
             const length = self.tracks.push(trackConf);
             return self.tracks[length - 1];
         },
+        /**
+         * #action
+         */
         addTrackConfs(trackConfs) {
-            for (const trackConf of trackConfs) {
-                self.tracks.push(trackConf);
+            // Append in chunks rather than one push per track: MST reconciles the
+            // array on every mutation, and on an 8k-track hub a push per track
+            // measured ~14.7s against ~10.8s for a single assignment, with chunks of
+            // 500 matching the single-assignment number. Chunked rather than one
+            // spread of the whole array so the argument count stays bounded no
+            // matter how large the hub is. What remains is per-config MST node
+            // creation, roughly 1ms per track.
+            for (let i = 0; i < trackConfs.length; i += 500) {
+                self.tracks.push(...trackConfs.slice(i, i + 500));
             }
         },
+        /**
+         * #action
+         */
         setTrackConfs(trackConfs) {
             self.tracks = cast(trackConfs);
         },
-        clear() { },
     }));
 }
 export default stateModelFactory;