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

package/esm/Session/Tracks.js

@@ -1,49 +1,189 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { BaseSessionModel, isBaseSession } from "./BaseSession.js";
-import { ReferenceManagementSessionMixin } from "./ReferenceManagement.js";
+import { computed } from 'mobx';
+import { BaseSessionModel, isBaseSession } from './BaseSession.js';
+import { isSessionWithConnections } from './Connections.js';
+import { ReferenceManagementSessionMixin } from './ReferenceManagement.js';
+import { assertTrackConfOutlivesItsAssemblies } from './temporaryAssemblyTracks.js';
+/**
+ * #stateModel TracksManagerSessionMixin
+ */
 export function TracksManagerSessionMixin(pluginManager) {
     return types
         .compose('TracksManagerSessionMixin', BaseSessionModel(pluginManager), ReferenceManagementSessionMixin(pluginManager))
         .views(self => ({
+        /**
+         * #getter
+         */
         get tracks() {
             return self.jbrowse.tracks;
         },
-        get assemblies() {
-            return self.jbrowse.assemblies;
-        },
-        getTracksById() {
+    }))
+        .views(self => {
+        // One index trackId → config for all tracks, assembly sequences, and
+        // connection tracks. Frozen jbrowse.tracks entries stay plain objects
+        // here; hydration to MST nodes happens lazily in TrackConfigurationReference
+        // on first access. Cached, so the N per-id lookups below share one rebuild
+        // per change rather than each re-scanning.
+        const tracksByIdRecord = computed(() => {
             const temporaryAssemblies = 'temporaryAssemblies' in self
                 ? self.temporaryAssemblies
                 : [];
-            const connectionInstances = 'connectionInstances' in self
-                ? self.connectionInstances
-                : [];
+            // both come from the connections mixin, which not every session
+            // composes. connectionInstances is annotated because its element type
+            // is a runtime-pluggable stateModel, so the guard can't infer it.
+            const connectionInstances = isSessionWithConnections(self) ? self.connectionInstances : [];
+            const connectionTrackConfigs = isSessionWithConnections(self)
+                ? self.connectionTrackConfigs
+                : {};
             return Object.fromEntries([
-                ...this.tracks.map(t => [t.trackId, t]),
-                ...this.assemblies.map(a => [a.sequence.trackId, a.sequence]),
+                ...self.tracks.map(t => [t.trackId, t]),
+                // assembly sequence tracks, so they resolve by trackId
+                ...self.assemblies.map(a => [a.sequence.trackId, a.sequence]),
                 ...temporaryAssemblies.map(a => [a.sequence.trackId, a.sequence]),
                 ...connectionInstances.flatMap(c => c.tracks.map(t => [t.trackId, t])),
+                // Persisted configs of opened connection tracks. Placed last so they
+                // win over the live connection instance: identity-stable across
+                // reload, and resolves even when the connection isn't re-established.
+                ...Object.entries(connectionTrackConfigs).map(([trackId, e]) => [
+                    trackId,
+                    e.config,
+                ]),
             ]);
-        },
-    }))
+        });
+        // Per-id computed cache backing getTrackById. Resolving one track's config
+        // subscribes only to that id's computed, so editing track A leaves track
+        // B's observers untouched: an unedited id's entry keeps its object identity
+        // across a sibling edit, so its computed re-evaluates equal and MobX
+        // short-circuits — B never wakes. Derived on read (no reconcile autorun),
+        // so it is never stale mid-action: session hydration and add-and-show
+        // resolve straight through it. Not evicted — bounded by the distinct ids
+        // resolved this session, and holds no authoritative state.
+        const trackByIdComputeds = new Map();
+        return {
+            /**
+             * #method
+             * Config for one trackId — a track, assembly sequence, or connection
+             * track — or undefined. Per-id reactive: every display resolves its
+             * config through this (via TrackConfigurationReference) and subscribes
+             * only to its own id, so one track's settings edit doesn't re-render the
+             * others.
+             */
+            getTrackById(id) {
+                let c = trackByIdComputeds.get(id);
+                if (!c) {
+                    c = computed(() => tracksByIdRecord.get()[id]);
+                    trackByIdComputeds.set(id, c);
+                }
+                return c.get();
+            },
+            /**
+             * #method
+             * Every track config the session can resolve, keyed by trackId. Prefer
+             * the per-id reactive `getTrackById(id)`: reading this whole map
+             * subscribes the caller to *every* track, so an edit to any one of them
+             * wakes it — the reason internal display config resolution moved off
+             * it. Kept for plugins that look up ids in a non-reactive context.
+             *
+             * @deprecated
+             */
+            getTracksById() {
+                return tracksByIdRecord.get();
+            },
+        };
+    })
         .actions(self => ({
+        /**
+         * #action
+         * Add a track config to *this session*.
+         *
+         * This mixin's session has no separate session-track store, so the
+         * destination is the jbrowse config — which in the products that compose
+         * it (desktop) is the single user's own file rather than something a
+         * server hands other visitors, so the two scopes are the same place.
+         * Defined here anyway so that every session has it: a feature standing a
+         * track up on the user's behalf can then call one action everywhere
+         * instead of asking which mixin it landed on.
+         * `SessionTracksManagerSessionMixin` overrides it with the real
+         * session-scoped store.
+         */
+        addSessionTrackConf(trackConf) {
+            assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
+            return self.jbrowse.addTrackConf(trackConf);
+        },
+        /**
+         * #action
+         * Add a track config wherever *this user's* catalog edits belong — the
+         * "Add track" workflows, where an admin adding a track means to add it
+         * for the whole site. `SessionTracksManagerSessionMixin` overrides it to
+         * send a non-admin's to the session instead; here there is only the one
+         * destination.
+         *
+         * Anything that is not an Add-track workflow wants
+         * `addSessionTrackConf`: a track a feature stands up on the user's behalf
+         * — a search result, a computed consensus, a reconstruction's labels — is
+         * not a catalog entry, and publishing one writes it into the config.json
+         * every visitor is served, once per click.
+         */
+        publishTrackConf(trackConf) {
+            assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
+            return self.jbrowse.addTrackConf(trackConf);
+        },
+        /**
+         * #action
+         * Deprecated alias of `addSessionTrackConf`. Call that, or
+         * `publishTrackConf`, which say which destination they mean.
+         *
+         * @deprecated
+         *
+         * Kept because a prebuilt plugin bundle reaches this by name at runtime
+         * and cannot be recompiled — `jbrowse-plugin-protein3d` calls it, and a
+         * member lookup that stops resolving throws nothing at all
+         * (`pluginFacingSessionApi.test.ts` is the guard). It now means the
+         * session, which is the destination every such caller wanted: a track a
+         * plugin stands up for one user is not a catalog entry. Nothing in tree
+         * may call it — `no-restricted-syntax` says so.
+         *
+         * Spelled out rather than delegating through `this`, for the reason
+         * `SessionTracks.addToSession` is a plain closure: an action whose return
+         * type is inferred from a sibling's makes the pair circular.
+         */
         addTrackConf(trackConf) {
+            assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
             return self.jbrowse.addTrackConf(trackConf);
         },
-        deleteTrackConf(trackConf) {
-            const callbacksToDereferenceTrack = [];
-            const dereferenceTypeCount = {};
-            const referring = self.getReferring(trackConf);
-            self.removeReferring(referring, trackConf, callbacksToDereferenceTrack, dereferenceTypeCount);
-            for (const cb of callbacksToDereferenceTrack) {
-                cb();
+        /**
+         * #action
+         * Persist edited track config back to the in-memory jbrowse config. The
+         * session-tracks mixin overrides this so a non-admin's edits become a
+         * shareable session-track override instead.
+         */
+        updateTrackConfiguration(trackConf) {
+            // an opened connection track lives in connectionTrackConfigs, not
+            // jbrowse.tracks; persist its edit there (jbrowse.updateTrackConf would
+            // no-op, since the track isn't in the config). Desktop uses this base
+            // mixin, so without this branch a connection-track edit is lost on
+            // reload.
+            if (isSessionWithConnections(self) &&
+                trackConf.trackId in self.connectionTrackConfigs) {
+                self.updateConnectionTrackConfig(trackConf);
             }
+            else {
+                self.jbrowse.updateTrackConf(trackConf);
+            }
+        },
+        /**
+         * #action
+         */
+        deleteTrackConf(trackConf) {
+            const { trackId } = trackConf;
+            self.dereferenceTrack(trackId, self.getReferring(trackId));
             if (self.adminMode) {
                 return self.jbrowse.deleteTrackConf(trackConf);
             }
         },
     }));
 }
+/** Type guard for SessionWithTracks */
 export function isSessionWithTracks(thing) {
     return isBaseSession(thing) && 'tracks' in thing;
 }

package/esm/Session/assertSessionModel.d.ts

@@ -0,0 +1,21 @@
+import type { AssertExtends } from '../assertExtends.ts';
+import type { AbstractSessionModel } from '@jbrowse/core/util/types';
+/**
+ * Compile-time assertion that a concrete session-model instance type satisfies
+ * `AbstractSessionModel`. Reference it with a product's session instance type
+ * to force the check; there is no runtime component, so a missing member
+ * surfaces as a type error at the reference site:
+ *
+ * ```ts
+ * type _Check = AssertSessionModel<Instance<WebSessionModelType>>
+ * ```
+ *
+ * Every product's session model pairs this with one `AssertExtends` per
+ * capability contract it relies on, because this assertion alone is not enough:
+ * `AbstractSessionModel` marks those capabilities **optional**, so it cannot
+ * catch a member drifting out of sync with the `SessionWith*` interface plugins
+ * actually narrow to. Keep them as one assertion per contract rather than
+ * collapsing them into a list — the whole value is the compile error naming the
+ * contract that broke.
+ */
+export type AssertSessionModel<T extends AbstractSessionModel> = AssertExtends<T, AbstractSessionModel>;

package/esm/Session/assertSessionModel.js

@@ -0,0 +1 @@
+export {};

package/esm/Session/finalizeSession.d.ts

@@ -0,0 +1,16 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { IAnyModelType, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+/**
+ * Apply the `Core-extendSession` extension point and drop the legacy
+ * object-shaped `connectionInstances` from incoming snapshots (the schema
+ * changed from an object to an array, so old snapshots must be filtered out,
+ * xref https://github.com/GMOD/jbrowse-components/issues/1903).
+ *
+ * Shared by the web session (`finalizeWebSession`) and the desktop session
+ * factory so the extension point + migration live in one place.
+ */
+export declare function finalizeSession<T extends IAnyModelType>(pluginManager: PluginManager, sessionModel: T): import("@jbrowse/mobx-state-tree").ISnapshotProcessor<T, Omit<SnapshotIn<T> & {
+    connectionInstances?: unknown;
+}, "connectionInstances">, Omit<SnapshotOut<T> & {
+    connectionInstances?: unknown;
+}, "connectionInstances">>;

package/esm/Session/finalizeSession.js

@@ -0,0 +1,29 @@
+import { types } from '@jbrowse/mobx-state-tree';
+/**
+ * Apply the `Core-extendSession` extension point and drop the legacy
+ * object-shaped `connectionInstances` from incoming snapshots (the schema
+ * changed from an object to an array, so old snapshots must be filtered out,
+ * xref https://github.com/GMOD/jbrowse-components/issues/1903).
+ *
+ * Shared by the web session (`finalizeWebSession`) and the desktop session
+ * factory so the extension point + migration live in one place.
+ */
+export function finalizeSession(pluginManager, sessionModel) {
+    const extendedSessionModel = pluginManager.evaluateExtensionPoint(
+    /** #extensionPoint Core-extendSession | sync | Extend the session model with extra state or actions */
+    'Core-extendSession', sessionModel);
+    return types.snapshotProcessor(extendedSessionModel, {
+        preProcessor(snapshot) {
+            const { connectionInstances, ...rest } = snapshot;
+            return !Array.isArray(connectionInstances) ? rest : snapshot;
+        },
+        postProcessor(snapshot) {
+            // connectionInstances are runtime-only: they hold the whole fetched hub
+            // (thousands of tracks), so persisting them bloats the session. Open
+            // connection tracks survive reload via `connectionTrackConfigs` instead,
+            // which resolves synchronously without re-establishing the connection.
+            const { connectionInstances: _connectionInstances, ...rest } = snapshot;
+            return rest;
+        },
+    });
+}

package/esm/Session/index.d.ts

@@ -1,10 +1,22 @@
-export * from './ReferenceManagement.ts';
-export * from './Connections.ts';
-export * from './DrawerWidgets.ts';
-export * from './DialogQueue.ts';
-export * from './Themes.ts';
-export * from './Tracks.ts';
-export * from './MultipleViews.ts';
-export * from './BaseSession.ts';
-export * from './SessionTracks.ts';
-export * from './BaseSession.ts';
+export { ReferenceManagementSessionMixin, isSessionWithReferenceManagement, } from './ReferenceManagement.ts';
+export type { ReferringNode, SessionWithReferenceManagement, SessionWithReferenceManagementType, } from './ReferenceManagement.ts';
+export { ConnectionManagementSessionMixin, isSessionWithConnections, } from './Connections.ts';
+export type { ConnectionTrackConfigEntry, SessionWithConnections, SessionWithConnectionsType, } from './Connections.ts';
+export { DrawerWidgetSessionMixin, isSessionWithDrawerWidgets, } from './DrawerWidgets.ts';
+export type { SessionWithDrawerWidgets, SessionWithDrawerWidgetsType, } from './DrawerWidgets.ts';
+export { ThemeManagerSessionMixin, isSessionWithThemes } from './Themes.ts';
+export type { SessionWithThemes, SessionWithThemesType } from './Themes.ts';
+export { TracksManagerSessionMixin, isSessionWithTracks } from './Tracks.ts';
+export type { SessionWithTracks, SessionWithTracksType } from './Tracks.ts';
+export { MultipleViewsSessionMixin, isSessionWithMultipleViews, } from './MultipleViews.ts';
+export type { SessionWithMultipleViews, SessionWithMultipleViewsType, } from './MultipleViews.ts';
+export { PreferencesSessionMixin } from './Preferences.ts';
+export { BaseSessionModel, isBaseSession, isSession } from './BaseSession.ts';
+export type { BaseSession, BaseSessionType } from './BaseSession.ts';
+export { SessionTracksManagerSessionMixin } from './SessionTracks.ts';
+export type { EditableTrackConfig, PlainTrackConfig, SessionWithSessionTracks, SessionWithSessionTracksType, } from './SessionTracks.ts';
+export { bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, } from './shareableSnapshot.ts';
+export { TrackMenuItemsSessionMixin, aboutTrackMenuItem, copyTrackSnapshot, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './TrackMenu.ts';
+export { TrackMenuSessionMixin } from './TrackMenuSessionMixin.ts';
+export { finalizeSession } from './finalizeSession.ts';
+export type { AssertSessionModel } from './assertSessionModel.ts';

package/esm/Session/index.js

@@ -1,10 +1,13 @@
-export * from "./ReferenceManagement.js";
-export * from "./Connections.js";
-export * from "./DrawerWidgets.js";
-export * from "./DialogQueue.js";
-export * from "./Themes.js";
-export * from "./Tracks.js";
-export * from "./MultipleViews.js";
-export * from "./BaseSession.js";
-export * from "./SessionTracks.js";
-export * from "./BaseSession.js";
+export { ReferenceManagementSessionMixin, isSessionWithReferenceManagement, } from './ReferenceManagement.js';
+export { ConnectionManagementSessionMixin, isSessionWithConnections, } from './Connections.js';
+export { DrawerWidgetSessionMixin, isSessionWithDrawerWidgets, } from './DrawerWidgets.js';
+export { ThemeManagerSessionMixin, isSessionWithThemes } from './Themes.js';
+export { TracksManagerSessionMixin, isSessionWithTracks } from './Tracks.js';
+export { MultipleViewsSessionMixin, isSessionWithMultipleViews, } from './MultipleViews.js';
+export { PreferencesSessionMixin } from './Preferences.js';
+export { BaseSessionModel, isBaseSession, isSession } from './BaseSession.js';
+export { SessionTracksManagerSessionMixin } from './SessionTracks.js';
+export { bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, } from './shareableSnapshot.js';
+export { TrackMenuItemsSessionMixin, aboutTrackMenuItem, copyTrackSnapshot, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './TrackMenu.js';
+export { TrackMenuSessionMixin } from './TrackMenuSessionMixin.js';
+export { finalizeSession } from './finalizeSession.js';

package/esm/Session/shareableSnapshot.d.ts

@@ -0,0 +1,77 @@
+import type { AbstractSessionModel } from '@jbrowse/core/util';
+/**
+ * The session snapshot to hand to anyone else — a share link, an exported
+ * `session.json`, a desktop→web export. Snapshotting and baking are one call so
+ * the pair can't be split: a bare `getSnapshot(session)` is never a correct
+ * outgoing snapshot (see `bakeSessionCascades`), and three of the four
+ * boundaries were spelling the two steps out identically.
+ *
+ * The fourth (desktop `ExportToWebDialog`) bakes a *transformed* snapshot from
+ * `planWebExport`, so it calls `bakeSessionCascades` directly.
+ */
+export declare function getShareableSessionSnapshot(session: AbstractSessionModel): Record<string, unknown>;
+/**
+ * Everything an outgoing snapshot has to resolve because the live session
+ * resolves it at read time against state that is staying behind.
+ *
+ * Two such cascades, and they have nothing to do with each other — promoted
+ * display-type defaults are per-track rendering, workspaces intent is the
+ * session's layout mode. What they share is only this: both live partly in the
+ * sender's own browser, so a raw `getSnapshot` records neither, and the
+ * recipient silently resolves their own.
+ *
+ * They get one entry point rather than a call each because the failure of a
+ * boundary that performs half of them is invisible at that boundary — the
+ * export succeeds, and what is missing only shows up on someone else's screen.
+ * Adding a third cascade should mean editing this function, not auditing four
+ * call sites.
+ */
+export declare function bakeSessionCascades(session: AbstractSessionModel, snapshot: Record<string, unknown>): Record<string, unknown>;
+/**
+ * `getComputedStyle` for the promotable-default cascade.
+ *
+ * A track that "follows" a session-wide promoted display-type default holds no
+ * value of its own — its rendered value is resolved at read time from the
+ * promoted display-type defaults in `preferencesOverrides`, which are personal,
+ * localStorage-backed, and deliberately never serialized into a shared session.
+ * So a raw `getSnapshot(session)` records a track as at-default even when the
+ * sender is looking at a promoted value, and the recipient (who lacks the sender's
+ * preferences) sees something different. This flattens the live cascade into a
+ * self-contained snapshot:
+ *
+ * Every slot an open display *inherits* from a promoted default (i.e.
+ * `getDisplayTypeDefaultChanges` — non-customized, differs from base) is baked
+ * into that track's config layer: its own config for a user-added or connection
+ * track, else a `trackConfigDeltas` entry against the admin base (see
+ * `ownTrackConfig`). So the concrete value travels with the document, and
+ * because it lands in the track's config the recipient reads it as *customized*
+ * — a customized value is the top of the cascade, so their own promoted defaults
+ * never get consulted for it.
+ *
+ * **What this deliberately does not cover**, and the reason there is no flag
+ * here: a slot the sender was viewing at its *base* value. Nothing is baked for
+ * it (the value equals base, and `stripDefault` drops it from the snapshot
+ * regardless), so a recipient who has promoted something else resolves it from
+ * their own cascade and sees their value. There is no value that can express "I
+ * deliberately saw the default" — at-base and unset are byte-identical once
+ * stripped. That case used to be covered by stamping a per-display
+ * `ignorePromotedDefaults` on every open display, which cost a second
+ * shape-aware walk that had to stay in step with `openPromotableDisplays` by
+ * hand, and permanently detached received tracks from the recipient's own pins
+ * until they clicked "use this default" on each one. A promoted default is
+ * personal and local — the same as the theme a session is viewed in, which this
+ * function has never baked either.
+ *
+ * The live session is untouched; a modified deep copy of `snapshot` is returned.
+ * Tracks the sender never opened carry no display state to resolve, so they're
+ * left to pick up the recipient's defaults when opened — matching "export the
+ * actual state of the (open) tracks".
+ *
+ * Reach is `openPromotableDisplays` — literally the same walk the cascade's own
+ * "apply to open tracks" uses, so the two can't drift. It recurses into a
+ * composite view's `views` array (breakpoint-split, the linear-comparative /
+ * synteny family), which holds child views rather than tracks of its own —
+ * `LGVSyntenyDisplay` is only reachable that way, and before the recursion a
+ * shared session containing one rendered differently for the recipient.
+ */
+export declare function bakePromotedDefaultsIntoSnapshot(session: AbstractSessionModel, snapshot: Record<string, unknown>): Record<string, unknown>;

package/esm/Session/shareableSnapshot.js

@@ -0,0 +1,196 @@
+import { getConf, getDisplayTypeDefaultChanges, } from '@jbrowse/core/configuration';
+import { getContainingTrack, mergeTrackConfig, openPromotableDisplays, } from '@jbrowse/core/util';
+import { getSnapshot } from '@jbrowse/mobx-state-tree';
+import { asArray, isRecord } from '../snapshotUtils.js';
+/**
+ * The session snapshot to hand to anyone else — a share link, an exported
+ * `session.json`, a desktop→web export. Snapshotting and baking are one call so
+ * the pair can't be split: a bare `getSnapshot(session)` is never a correct
+ * outgoing snapshot (see `bakeSessionCascades`), and three of the four
+ * boundaries were spelling the two steps out identically.
+ *
+ * The fourth (desktop `ExportToWebDialog`) bakes a *transformed* snapshot from
+ * `planWebExport`, so it calls `bakeSessionCascades` directly.
+ */
+export function getShareableSessionSnapshot(session) {
+    return bakeSessionCascades(session, getSnapshot(session));
+}
+/**
+ * Everything an outgoing snapshot has to resolve because the live session
+ * resolves it at read time against state that is staying behind.
+ *
+ * Two such cascades, and they have nothing to do with each other — promoted
+ * display-type defaults are per-track rendering, workspaces intent is the
+ * session's layout mode. What they share is only this: both live partly in the
+ * sender's own browser, so a raw `getSnapshot` records neither, and the
+ * recipient silently resolves their own.
+ *
+ * They get one entry point rather than a call each because the failure of a
+ * boundary that performs half of them is invisible at that boundary — the
+ * export succeeds, and what is missing only shows up on someone else's screen.
+ * Adding a third cascade should mean editing this function, not auditing four
+ * call sites.
+ */
+export function bakeSessionCascades(session, snapshot) {
+    const snap = bakePromotedDefaultsIntoSnapshot(session, snapshot);
+    bakeWorkspacesIntent(session, snap);
+    return snap;
+}
+/**
+ * The workspaces cascade: session property -> user preference -> admin
+ * `configuration.preferences.useWorkspaces`, of which only the first is in the
+ * snapshot.
+ *
+ * So a sender whose workspace is on because *their admin turned it on* exports
+ * a fully arranged `layout` with no statement that it is a workspace at all,
+ * and a recipient resolving their own cascade to false renders the classic
+ * stack: the arrangement arrives intact and invisible, with nothing to say it
+ * was dropped.
+ *
+ * Only the on case is baked. At `false` there is no arrangement to carry, so
+ * stamping it would be a sender with nothing to say overriding a recipient who
+ * prefers workspaces — the same line the promoted-default bake draws at a slot
+ * the sender was viewing at its base value.
+ *
+ * The paths that build a layout through an explicit user intent already set the
+ * property themselves (`setUseWorkspacesPreference`, ViewMenu's move-view-out,
+ * a spec `layout`), which is exactly what hides this: every arrangement made by
+ * a *drag* — split a cell, drag a tab into it, open a new tab — goes through
+ * `WorkspaceLayoutMixin` alone, which owns the tree and knows nothing about the
+ * preference.
+ *
+ * `effectiveUseWorkspaces` is read behind an `in` guard because
+ * `AbstractSessionModel` cannot name it (it lives on MultipleViewsSessionMixin,
+ * one layer up), so renaming that getter silently stops the bake rather than
+ * failing to compile — the hazard app-core/src/WorkspaceLayout/CLAUDE.md describes for
+ * `setPendingMove`. jbrowse-web's `sessionModel/exportLayout.test.ts` is the
+ * canary, since the bake needs a real session to have a cascade at all.
+ */
+function bakeWorkspacesIntent(session, snap) {
+    if (snap.useWorkspaces === undefined &&
+        'effectiveUseWorkspaces' in session &&
+        session.effectiveUseWorkspaces ===
+            true) {
+        snap.useWorkspaces = true;
+    }
+}
+/**
+ * `getComputedStyle` for the promotable-default cascade.
+ *
+ * A track that "follows" a session-wide promoted display-type default holds no
+ * value of its own — its rendered value is resolved at read time from the
+ * promoted display-type defaults in `preferencesOverrides`, which are personal,
+ * localStorage-backed, and deliberately never serialized into a shared session.
+ * So a raw `getSnapshot(session)` records a track as at-default even when the
+ * sender is looking at a promoted value, and the recipient (who lacks the sender's
+ * preferences) sees something different. This flattens the live cascade into a
+ * self-contained snapshot:
+ *
+ * Every slot an open display *inherits* from a promoted default (i.e.
+ * `getDisplayTypeDefaultChanges` — non-customized, differs from base) is baked
+ * into that track's config layer: its own config for a user-added or connection
+ * track, else a `trackConfigDeltas` entry against the admin base (see
+ * `ownTrackConfig`). So the concrete value travels with the document, and
+ * because it lands in the track's config the recipient reads it as *customized*
+ * — a customized value is the top of the cascade, so their own promoted defaults
+ * never get consulted for it.
+ *
+ * **What this deliberately does not cover**, and the reason there is no flag
+ * here: a slot the sender was viewing at its *base* value. Nothing is baked for
+ * it (the value equals base, and `stripDefault` drops it from the snapshot
+ * regardless), so a recipient who has promoted something else resolves it from
+ * their own cascade and sees their value. There is no value that can express "I
+ * deliberately saw the default" — at-base and unset are byte-identical once
+ * stripped. That case used to be covered by stamping a per-display
+ * `ignorePromotedDefaults` on every open display, which cost a second
+ * shape-aware walk that had to stay in step with `openPromotableDisplays` by
+ * hand, and permanently detached received tracks from the recipient's own pins
+ * until they clicked "use this default" on each one. A promoted default is
+ * personal and local — the same as the theme a session is viewed in, which this
+ * function has never baked either.
+ *
+ * The live session is untouched; a modified deep copy of `snapshot` is returned.
+ * Tracks the sender never opened carry no display state to resolve, so they're
+ * left to pick up the recipient's defaults when opened — matching "export the
+ * actual state of the (open) tracks".
+ *
+ * Reach is `openPromotableDisplays` — literally the same walk the cascade's own
+ * "apply to open tracks" uses, so the two can't drift. It recurses into a
+ * composite view's `views` array (breakpoint-split, the linear-comparative /
+ * synteny family), which holds child views rather than tracks of its own —
+ * `LGVSyntenyDisplay` is only reachable that way, and before the recursion a
+ * shared session containing one rendered differently for the recipient.
+ */
+export function bakePromotedDefaultsIntoSnapshot(session, snapshot) {
+    const snap = structuredClone(snapshot);
+    // `openPromotableDisplays` is the one walk that decides reach — shared with
+    // the cascade's own "apply to open tracks", so the set this bakes and the set
+    // that acts on a promoted default can't drift
+    for (const display of openPromotableDisplays(session)) {
+        const changes = getDisplayTypeDefaultChanges(display);
+        if (changes.length > 0) {
+            bakeValues(snap, {
+                trackId: getConf(getContainingTrack(display), 'trackId'),
+                displayId: getConf(display, 'displayId'),
+                displayType: display.type,
+                values: Object.fromEntries(changes.map(c => [c.path[0], c.to])),
+            });
+        }
+    }
+    return snap;
+}
+// The track's own full config in the snapshot, when it has one: a user-added
+// track's `sessionTracks` entry, or an opened connection track's persisted
+// `connectionTrackConfigs` config. Everything else is an admin-base track,
+// which carries only a delta.
+//
+// The connection case is not optional. `trackConfigDeltas` is merged over
+// `jbrowse.tracks` alone, so a delta written for a connection track resolves
+// nowhere — the recipient would render the base value, which is the exact
+// failure the bake exists to prevent. `updateTrackConfiguration` splits on the
+// same line.
+function ownTrackConfig(snap, trackId) {
+    const sessionTrack = asArray(snap.sessionTracks).find(t => isRecord(t) && t.trackId === trackId);
+    const connectionEntry = isRecord(snap.connectionTrackConfigs)
+        ? snap.connectionTrackConfigs[trackId]
+        : undefined;
+    return isRecord(sessionTrack)
+        ? sessionTrack
+        : isRecord(connectionEntry) && isRecord(connectionEntry.config)
+            ? connectionEntry.config
+            : undefined;
+}
+// Bake one display's inherited values into the config layer: into the matching
+// display of the track's own config when it has one, else merged as a
+// `trackConfigDeltas` entry against the admin base.
+function bakeValues(snap, bake) {
+    const partialDisplay = {
+        type: bake.displayType,
+        displayId: bake.displayId,
+        ...bake.values,
+    };
+    const ownConfig = ownTrackConfig(snap, bake.trackId);
+    if (ownConfig) {
+        const displays = asArray(ownConfig.displays);
+        const target = displays.find(d => isRecord(d) && d.displayId === bake.displayId);
+        if (isRecord(target)) {
+            Object.assign(target, bake.values);
+        }
+        else {
+            ownConfig.displays = [...displays, partialDisplay];
+        }
+    }
+    else {
+        const deltas = isRecord(snap.trackConfigDeltas)
+            ? { ...snap.trackConfigDeltas }
+            : {};
+        const existing = isRecord(deltas[bake.trackId])
+            ? deltas[bake.trackId]
+            : { trackId: bake.trackId };
+        deltas[bake.trackId] = mergeTrackConfig(existing, {
+            trackId: bake.trackId,
+            displays: [partialDisplay],
+        });
+        snap.trackConfigDeltas = deltas;
+    }
+}

package/esm/Session/temporaryAssemblyTracks.d.ts

@@ -0,0 +1,23 @@
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+/**
+ * Dev-only check that a track config being written into a session or config list
+ * is one something can still draw tomorrow. No-op in production.
+ *
+ * A config naming nothing but a temporary assembly is dead the moment its view
+ * closes, and no list outside that view has anyone to sweep it — which is the
+ * whole of ADR-084. A track only one view can draw carries its config on the
+ * track instead (`showTrackGeneric`'s `inlineConf`), so reaching a session list
+ * with one is the mistake, not the cleanup afterwards.
+ *
+ * **This reports a write, not a click.** The two flows a user can drive into it
+ * are answered before they get here — the track menu greys its copy actions, and
+ * `addTrackFromWidget` opens the track inline instead of adding it — so what
+ * survives to report is a caller that had `inlineConf` available and did not
+ * take it. That is the reading the message is written for.
+ *
+ * `console.error` and never `throw`, matching `assertDisplayContract`: these
+ * writes happen inside launchers and menu handlers where an exception is caught
+ * and reported as a failed track, which would hide the violation. The jest gate
+ * (`config/jest/contractGate.js`) is what listens.
+ */
+export declare function assertTrackConfOutlivesItsAssemblies(session: unknown, trackConf: AnyConfigurationModel | Record<string, unknown>, destination: string): void;