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

package/esm/Session/Tracks.js

@@ -1,49 +1,212 @@
+import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
 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 { assertNotReaddedDifferently } from './readdedTrackConf.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.
+        //
+        // `keepAlive` is what makes that last sentence true, and it is load
+        // bearing: an unobserved computed re-derives on EVERY read, and this one
+        // walks every track, assembly and connection the session can resolve. A
+        // reader inside a reaction or an MST action was already fine — MobX
+        // caches within a batch, which is why the resolvers and `showTrackGeneric`
+        // never showed it. Ranking search hits is the caller that is neither, and
+        // it cost 33ms per search on a 2000-track config against 0.07ms held.
+        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,
+                ]),
             ]);
-        },
-    }))
+        }, { keepAlive: true });
+        // 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');
+            // the config's own adder appends without looking, so a re-add under a
+            // known id used to leave two entries with the first one winning
+            const expanded = expandLooseTrackConfig(trackConf, pluginManager);
+            const { trackId, type } = expanded;
+            const existing = self.getTrackById(trackId);
+            if (existing) {
+                assertNotReaddedDifferently(pluginManager, existing, {
+                    ...expanded,
+                    trackId,
+                    type,
+                });
+                return existing;
+            }
+            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/developerMode.d.ts

@@ -0,0 +1,7 @@
+import type { NotificationSink } from '@jbrowse/core/util/types';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+interface DeveloperModeHost extends IStateTreeNode, Pick<NotificationSink, 'notify'> {
+    getPreference: (key: string) => unknown;
+}
+export declare function applyDeveloperMode(self: DeveloperModeHost): void;
+export {};

package/esm/Session/developerMode.js

@@ -0,0 +1,43 @@
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
+import { enableContractReports, setContractReportSink, } from '@jbrowse/render-core/contractReports';
+/**
+ * What a plugin author sees when their display breaks an ordering contract in
+ * somebody else's production build.
+ *
+ * The checks themselves have always run and always reported; what they had no
+ * way to reach was this population, which is the one least able to diagnose the
+ * symptom and the one nobody can write a test for. A `console.error` surviving
+ * the build would not have fixed that — nobody has a console open on a page
+ * they did not write — so the report has to land in the app, in the session the
+ * broken display is in, and it has to explain itself: the reader did not turn
+ * this on deliberately in the common case (a plugin served from their own
+ * machine did), and a message they cannot place reads as the app being broken.
+ *
+ * `warning` rather than `error`: an error snackbar in this app means the user's
+ * data or their request failed, and every word here is about code they are
+ * writing. Warnings persist until dismissed, which is what a message with a fix
+ * in it wants, and identical ones collapse in the snackbar — so a violation
+ * repeating across ten tracks of one broken type is still one notice.
+ */
+function notification({ family, message, armedBy }) {
+    return (`JBrowse ${family} contract broken — a bug in code, not in your data or ` +
+        `configuration.\n\n${message}\n\n` +
+        `Shown because ${armedBy}. These notices can be turned on anywhere with ` +
+        `localStorage.jbrowseDeveloperMode = 1, or site-wide with ` +
+        `configuration.preferences.developerMode.`);
+}
+export function applyDeveloperMode(self) {
+    if (self.getPreference('developerMode') === true) {
+        enableContractReports('this site sets configuration.preferences.developerMode');
+    }
+    addDisposer(self, setContractReportSink(report => {
+        // out of whatever reaction, fetch handler or upload found the violation:
+        // `notify` writes observables, and a diagnostic that throws where it is
+        // read is worse than the bug it describes
+        queueMicrotask(() => {
+            if (isAlive(self)) {
+                self.notify(notification(report), 'warning');
+            }
+        });
+    }));
+}

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/readdedTrackConf.d.ts

@@ -0,0 +1,8 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+type TrackConfInput = {
+    trackId: string;
+    type: string;
+} & Record<string, unknown>;
+export declare function assertNotReaddedDifferently(pluginManager: PluginManager, existing: AnyConfigurationModel | TrackConfInput, trackConf: TrackConfInput): void;
+export {};

package/esm/Session/readdedTrackConf.js

@@ -0,0 +1,25 @@
+import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { compareStructural } from 'mobx';
+// What a config means once its defaults are resolved: a live config node
+// answers with its snapshot, and a plain object (desktop's `jbrowse.tracks` is
+// frozen, so its entries are the input as written) is hydrated through the
+// same schema first. Two inputs that would build the same node compare equal.
+function resolvedTrackConf(pluginManager, conf) {
+    return isStateTreeNode(conf)
+        ? getSnapshot(conf)
+        : getSnapshot(pluginManager
+            .pluggableConfigSchemaType('track')
+            .create(conf, { pluginManager }));
+}
+// Re-adding a trackId the session already holds returns the existing config,
+// which is what keeps a content-hashed trackId idempotent. It is also the trap
+// a recomputed track walks into: the new features arrive under the old id, the
+// old config is handed back, nothing is said, and the track keeps showing the
+// first values it saw. Same id with different content is therefore refused,
+// naming the two-step that works.
+export function assertNotReaddedDifferently(pluginManager, existing, trackConf) {
+    const same = compareStructural(resolvedTrackConf(pluginManager, existing), resolvedTrackConf(pluginManager, trackConf));
+    if (!same) {
+        throw new Error(`Track "${trackConf.trackId}" is already in this session with a different configuration, and adding it again would keep the old one. Delete it first (session.deleteTrackConf(session.getTrackById("${trackConf.trackId}"))), then add — and give a recomputed FromConfigAdapter a new adapterId, since the adapter cache is keyed on it.`);
+    }
+}

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>;