@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/translateTranscript.d.ts

@@ -0,0 +1,44 @@
+import type { TranslExcept } from './geneticCodes.ts';
+import type { Feature } from './simpleFeature.ts';
+export interface CdsSegment {
+    start: number;
+    end: number;
+    phase: number;
+}
+/**
+ * A transcript's CDS segments in genome coordinates, sorted and deduplicated. A
+ * GFF3 file can repeat a CDS row, and the duplicated bases would stitch into
+ * the translation and frameshift the protein. A standalone polyprotein CDS
+ * carries cleavage products rather than CDS children, so its own span is the
+ * one segment.
+ */
+export declare function transcriptCDS(transcript: Feature): CdsSegment[];
+/**
+ * The genetic code a transcript translates with: a `transl_table` on it or on
+ * its CDS, else the assembly's code for its contig, else undefined for the
+ * standard code.
+ */
+export declare function transcriptGeneticCodeId(transcript: Feature, assemblyGeneticCodeId?: number): number | undefined;
+/**
+ * A transcript's `transl_except` overrides (RefSeq's selenocysteines), read off
+ * the CDS by NCBI convention or the transcript itself, in the transcript-
+ * relative, strand-corrected frame `translateTranscript` translates in.
+ */
+export declare function transcriptTranslExcept(transcript: Feature): TranslExcept[] | undefined;
+/**
+ * A transcript's protein as JBrowse shows it: its CDS stitched in order, read
+ * with its genetic code and that code's alternative initiators, with any
+ * `transl_except` applied. `seq` is the genome under the transcript, its start
+ * to its end. Undefined for a transcript with no CDS. `cds` and `translExcept`
+ * are the transcript-relative, strand-corrected frame the protein was read in,
+ * for a caller placing residues back on it.
+ */
+export declare function translateTranscript({ transcript, seq, assemblyGeneticCodeId, }: {
+    transcript: Feature;
+    seq: string;
+    assemblyGeneticCodeId?: number;
+}): {
+    protein: string;
+    cds: CdsSegment[];
+    translExcept?: TranslExcept[];
+} | undefined;

package/esm/util/translateTranscript.js

@@ -0,0 +1,102 @@
+import { convertCodingSequenceToPeptides } from './convertCodingSequenceToPeptides.js';
+import { getGeneticCode, parseTranslTable, relativizeTranslExcept, } from './geneticCodes.js';
+import { revlist } from './revlist.js';
+import { revcom } from './seqUtils.js';
+function isCDS(feature) {
+    return feature.get('type')?.toLowerCase() === 'cds';
+}
+function subfeatures(feature) {
+    return feature.get('subfeatures') ?? [];
+}
+/**
+ * A transcript's CDS segments in genome coordinates, sorted and deduplicated. A
+ * GFF3 file can repeat a CDS row, and the duplicated bases would stitch into
+ * the translation and frameshift the protein. A standalone polyprotein CDS
+ * carries cleavage products rather than CDS children, so its own span is the
+ * one segment.
+ */
+export function transcriptCDS(transcript) {
+    const seen = new Set();
+    const cds = [];
+    const sorted = subfeatures(transcript).toSorted((a, b) => a.get('start') - b.get('start'));
+    for (const sub of sorted) {
+        const start = sub.get('start');
+        const end = sub.get('end');
+        const key = `${start}-${end}`;
+        if (isCDS(sub) && start < end && !seen.has(key)) {
+            seen.add(key);
+            cds.push({ start, end, phase: sub.get('phase') ?? 0 });
+        }
+    }
+    if (cds.length === 0 && isCDS(transcript)) {
+        const start = transcript.get('start');
+        const end = transcript.get('end');
+        if (start < end) {
+            cds.push({ start, end, phase: transcript.get('phase') ?? 0 });
+        }
+    }
+    return cds;
+}
+/**
+ * The genetic code a transcript translates with: a `transl_table` on it or on
+ * its CDS, else the assembly's code for its contig, else undefined for the
+ * standard code.
+ */
+export function transcriptGeneticCodeId(transcript, assemblyGeneticCodeId) {
+    const cds = subfeatures(transcript).find(isCDS);
+    return (parseTranslTable(transcript.get('transl_table')) ??
+        parseTranslTable(cds?.get('transl_table')) ??
+        assemblyGeneticCodeId);
+}
+/**
+ * A transcript's `transl_except` overrides (RefSeq's selenocysteines), read off
+ * the CDS by NCBI convention or the transcript itself, in the transcript-
+ * relative, strand-corrected frame `translateTranscript` translates in.
+ */
+export function transcriptTranslExcept(transcript) {
+    const cds = subfeatures(transcript).find(isCDS);
+    const raw = transcript.get('transl_except') ?? cds?.get('transl_except');
+    const start = transcript.get('start');
+    return raw
+        ? relativizeTranslExcept({
+            raw,
+            featureStart: start,
+            featureLength: transcript.get('end') - start,
+            strand: transcript.get('strand'),
+        })
+        : undefined;
+}
+/**
+ * A transcript's protein as JBrowse shows it: its CDS stitched in order, read
+ * with its genetic code and that code's alternative initiators, with any
+ * `transl_except` applied. `seq` is the genome under the transcript, its start
+ * to its end. Undefined for a transcript with no CDS. `cds` and `translExcept`
+ * are the transcript-relative, strand-corrected frame the protein was read in,
+ * for a caller placing residues back on it.
+ */
+export function translateTranscript({ transcript, seq, assemblyGeneticCodeId, }) {
+    const start = transcript.get('start');
+    const relative = transcriptCDS(transcript).map(c => ({
+        ...c,
+        start: c.start - start,
+        end: c.end - start,
+    }));
+    if (relative.length === 0) {
+        return undefined;
+    }
+    const minus = transcript.get('strand') === -1;
+    const cds = minus ? revlist(relative, seq.length) : relative;
+    const translExcept = transcriptTranslExcept(transcript);
+    const { codonTable, starts } = getGeneticCode(transcriptGeneticCodeId(transcript, assemblyGeneticCodeId));
+    return {
+        protein: convertCodingSequenceToPeptides({
+            cds,
+            sequence: minus ? revcom(seq) : seq,
+            codonTable,
+            starts,
+            translExcept,
+        }),
+        cds,
+        translExcept,
+    };
+}

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

@@ -53,7 +53,6 @@ export interface JBrowsePluginVersion {
     url?: string;
     umdUrl?: string;
     esmUrl?: string;
-    cjsUrl?: string;
     integrity?: string;
 }
 export interface JBrowsePlugin {
@@ -65,7 +64,6 @@ export interface JBrowsePlugin {
     url?: string;
     umdUrl?: string;
     esmUrl?: string;
-    cjsUrl?: string;
     integrity?: string;
     versions?: JBrowsePluginVersion[];
     latestUrl?: string;

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

@@ -1,15 +1,17 @@
+import type { ViewSnapshotInput } from '../../PluginManager.ts';
 import type TextSearchManager from '../../TextSearch/TextSearchManager.ts';
-import type { AnyConfigurationModel, ResolvableDisplay } from '../../configuration/index.ts';
-import type { BaseInternetAccountModel } from '../../pluggableElementTypes/models/index.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { BaseInternetAccountModel, BaseTrackConfig } from '../../pluggableElementTypes/models/index.ts';
 import type { PluginDefinition } from '../../pluginDefinitions.ts';
 import type RpcManager from '../../rpc/RpcManager.ts';
 import type { MenuItem } from '../../ui/index.ts';
+import type { HighlightType } from '../highlights.ts';
 import type { Feature } from '../simpleFeature.ts';
 import type { TrackConfigChange } from '../trackConfigDelta.ts';
 import type { UriLocation } from './data.ts';
 import type { RenderingServices } from './renderingServices.ts';
 import type { DialogHost, NotificationSink } from './services.ts';
-import type { IAnyStateTreeNode, IStateTreeNode, SnapshotIn } from '@jbrowse/mobx-state-tree';
+import type { IAnyStateTreeNode, IAnyType, IStateTreeNode, SnapshotIn } from '@jbrowse/mobx-state-tree';
 import type { Theme, ThemeOptions } from '@mui/material';
 export type { AnyReactComponentType, ClassReturnedBy, InstanceTypeRestrictive, TypeTestedByPredicate, } from './util.ts';
 export type { IsAny } from './isAny.ts';
@@ -22,7 +24,8 @@ export type { AugmentedRegion, BasePlugin, BlobLocation, FileHandleLocation, Fil
 export interface AbstractViewContainer extends IStateTreeNode {
     views: AbstractViewModel[];
     removeView(view: AbstractViewModel): void;
-    addView(typeName: string, initialState?: Record<string, unknown>): AbstractViewModel;
+    addView<N extends string>(typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): AbstractViewModel;
+    launchView(typeName: string, initialState?: Record<string, unknown>): Promise<AbstractViewModel>;
 }
 export declare function isViewContainer(thing: unknown): thing is AbstractViewContainer;
 /**
@@ -32,6 +35,7 @@ export declare function isViewContainer(thing: unknown): thing is AbstractViewCo
  */
 export interface TrackActionView {
     showTrack: (id: string) => void;
+    launchTrack: (id: string) => Promise<unknown>;
     getActiveDisplayId?: (trackId: string) => string | undefined;
 }
 /**
@@ -63,6 +67,7 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     jbrowse: IAnyStateTreeNode;
     drawerPosition?: DrawerPosition;
     stickyViewHeaders?: boolean;
+    viewTitleBars?: boolean;
     configuration: AnyConfigurationModel;
     rpcManager: RpcManager;
     assemblyNames: string[];
@@ -72,15 +77,19 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     theme: Theme;
     animationMode: AnimationMode;
     scrollZoom: boolean;
+    highlights: readonly HighlightType[];
+    addHighlight: (highlight: HighlightType) => void;
+    removeHighlight: (highlight: HighlightType) => void;
+    updateHighlight: (old: HighlightType, updates: Partial<HighlightType>) => void;
+    setHighlights: (highlights: HighlightType[]) => void;
     highlightsVisible: boolean;
     setHighlightsVisible: (arg: boolean) => void;
-    revealHighlights: () => void;
+    highlightLabelsVisible: boolean;
+    setHighlightLabelsVisible: (arg: boolean) => void;
     getPreference: (key: string) => unknown;
     setPreferenceOverride: (key: string, value: unknown) => void;
     clearPreferenceOverrides: () => void;
     setScrollZoom: (flag: boolean) => void;
-    getDisplayTypeDefault: (displayType: string, slot: string) => unknown;
-    setDisplayTypeDefault: (displayType: string, slot: string, value: unknown) => void;
     hovered: unknown;
     setHovered: (arg: unknown) => void;
     setFocusedViewId?: (id: string) => void;
@@ -100,11 +109,11 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     version: string;
     gitCommit?: string;
     getTrackActionMenuItems?: (arg: {
-        config: AnyConfigurationModel;
+        config: BaseTrackConfig;
         view?: TrackActionView;
     }) => MenuItem[];
-    getTrackActions?: (arg: AnyConfigurationModel, view?: TrackActionView) => MenuItem[];
-    getTrackListMenuItems?: (arg: AnyConfigurationModel, view?: TrackActionView) => MenuItem[];
+    getTrackActions?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
+    getTrackListMenuItems?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
     addAssembly?: (conf: Record<string, unknown>) => void;
     addSessionAssembly?: (conf: Record<string, unknown>) => void;
     sessionAssemblies?: AnyConfigurationModel[];
@@ -153,6 +162,43 @@ export interface SessionWithConfigEditing extends AbstractSessionModel {
     }): void;
 }
 export declare function isSessionModelWithConfigEditing(t: unknown): t is SessionWithConfigEditing;
+/**
+ * A session that edits its tracks as deltas over a base it can hand back: what
+ * a display compares its live config against to say whether a setting is the
+ * reader's or the one the track was configured or added with.
+ */
+export interface SessionWithBaseTrackConfig extends AbstractSessionModel {
+    baseTrackConfig(trackId: string): {
+        trackId: string;
+        [key: string]: unknown;
+    } | undefined;
+}
+export declare function isSessionWithBaseTrackConfig(t: unknown): t is SessionWithBaseTrackConfig;
+/**
+ * A session that hands a shown track a private working copy of its config, so
+ * a non-admin's quick edits land as deltas and never on the shared base
+ * (ADR-032). `TrackConfigurationReference` resolves through it where it is
+ * one, and through `getTrackById` otherwise.
+ */
+export interface SessionWithEditableTrackConfig extends AbstractSessionModel {
+    getEditableTrackConfig(trackId: string, schemaType: IAnyType): AnyConfigurationModel | undefined;
+}
+export declare function isSessionWithEditableTrackConfig(t: unknown): t is SessionWithEditableTrackConfig;
+/**
+ * abstract interface for a session that keeps a list of views, so that `addView`
+ * appends and the view a launch came out of survives it.
+ *
+ * `AbstractViewContainer` alone does not say this. The single-view embedded
+ * products satisfy it with a `views` getter that wraps their one `view` in a
+ * fresh plain array and an `addView` that overwrites that view, so "Open in new
+ * view" there would destroy the view it was offered from. A view list that is
+ * itself part of the state tree is what tells the two apart: only a session
+ * that stores its views can hold one more.
+ */
+export interface SessionWithMultipleViews extends AbstractSessionModel {
+    views: AbstractViewModel[] & IStateTreeNode;
+}
+export declare function isSessionWithMultipleViews(t: unknown): t is SessionWithMultipleViews;
 /**
  * abstract interface for a session that can swap one of its views for a new one
  * of another type, in the slot the old view occupied.
@@ -164,7 +210,7 @@ export declare function isSessionModelWithConfigEditing(t: unknown): t is Sessio
  * and the guard is what a launcher asks before offering it.
  */
 export interface SessionWithViewReplacement extends AbstractSessionModel {
-    replaceView(view: AbstractViewModel, typeName: string, initialState?: Record<string, unknown>): AbstractViewModel;
+    replaceView<N extends string>(view: AbstractViewModel, typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): AbstractViewModel;
 }
 export declare function isSessionWithViewReplacement(t: unknown): t is SessionWithViewReplacement;
 /**
@@ -188,10 +234,10 @@ export declare function canReplaceView(session: AbstractViewContainer, view: Abs
  * that can't replace a view falls back to appending, so a caller passes the
  * source view unconditionally and never has to ask twice.
  */
-export declare function addOrReplaceView({ session, typeName, initialState, replacing, }: {
+export declare function addOrReplaceView<N extends string>({ session, typeName, initialState, replacing, }: {
     session: AbstractViewContainer;
-    typeName: string;
-    initialState?: Record<string, unknown>;
+    typeName: N;
+    initialState?: NoInfer<ViewSnapshotInput<N>>;
     replacing?: AbstractViewModel;
 }): AbstractViewModel;
 /**
@@ -294,6 +340,9 @@ export interface SessionWithWidgets extends AbstractSessionModel {
     addWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
         type: string;
     }): Widget;
+    openWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
+        type: string;
+    }): Widget;
     showWidget(widget: unknown): void;
     hideWidget(widget: unknown): void;
 }
@@ -325,6 +374,12 @@ export interface SessionWithDrawerWidgets extends SessionWithWidgets {
     poppedOut: boolean;
     popoutWidget(): void;
     returnWidgetToDrawer(): void;
+    /** true on a host with no room for a drawer, where every widget is a modal */
+    modalWidgets: boolean;
+    setModalWidgets(flag: boolean): void;
+    /** whether the visible widget is on screen in a modal */
+    modalWidgetVisible: boolean;
+    closeModalWidget(): void;
 }
 export declare function isSessionModelWithWidgets(thing: unknown): thing is SessionWithWidgets;
 /** a live connection instance held in a session's `connectionInstances` */
@@ -358,21 +413,30 @@ export interface SessionWithSessionPlugins extends AbstractSessionModel {
     removeSessionPlugin: (plugin: PluginDefinition) => void;
 }
 export declare function isSessionWithSessionPlugins(thing: unknown): thing is SessionWithSessionPlugins;
+export interface PermanentPluginsSafeMode {
+    reason: 'requested' | 'previousLaunchFailed';
+    /** what was loading when the launch that failed did not finish */
+    suspects: string[];
+}
 /**
  * A session whose product keeps a plugin list of its own, outside both the
  * config and the session — jbrowse-web's permanent plugins, stored in the
  * browser against the config being viewed, so an install survives a new session
  * and the next visit.
  *
- * The list is not MST state, so `permanentPlugins` re-reads storage on each
- * call and nothing observes it. That is enough for its two readers, both of
- * which run in response to a click: adding or removing one asks for the whole-
- * app reload every plugin change needs anyway.
+ * The plugin store is the whole surface: the pin beside an installed plugin
+ * writes the list, and an entry the load skipped is a row there with a switch
+ * on it, which is what makes the safe mode below something a user can act on.
  */
 export interface SessionWithPermanentPlugins extends AbstractSessionModel {
-    permanentPlugins: PluginDefinition[];
+    permanentPlugins: (PluginDefinition & {
+        disabled?: boolean;
+    })[];
+    permanentPluginsSafeMode: PermanentPluginsSafeMode | undefined;
     addPermanentPlugin: (plugin: PluginDefinition) => void;
     removePermanentPlugin: (plugin: PluginDefinition) => void;
+    setPermanentPluginDisabled: (plugin: PluginDefinition, disabled: boolean) => void;
+    reloadWithPermanentPlugins: () => void;
 }
 export declare function isSessionWithPermanentPlugins(thing: unknown): thing is SessionWithPermanentPlugins;
 /** abstract interface for a session that manages a global selection */
@@ -398,7 +462,10 @@ export interface TrackContainer {
         configuration: {
             trackId: string;
         };
-        displays: ResolvableDisplay[];
+        displays: {
+            type: string;
+            configuration: AnyConfigurationModel;
+        }[];
     }[];
     assemblyNames?: string[];
     /**
@@ -410,6 +477,13 @@ export interface TrackContainer {
      * silence.
      */
     showTrack: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: Record<string, unknown>, inlineConf?: Record<string, unknown>) => unknown;
+    /**
+     * The sync pair still works on an unloaded display — it loads and shows a
+     * tick later, returning undefined — so these are for a caller that needs
+     * the track back.
+     */
+    launchTrack: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: Record<string, unknown>, inlineConf?: Record<string, unknown>) => Promise<unknown>;
+    launchToggleTrack: (trackId: string) => Promise<unknown>;
     hideTrack: (trackId: string) => unknown;
     toggleTrack: (trackId: string) => unknown;
 }
@@ -428,10 +502,13 @@ export interface AbstractViewModel {
     /**
      * The same, counting the views this one is nested inside — a synteny row has
      * no container of its own to write `bodyMounted`, so that flag alone reads
-     * `true` for a row whose whole stack is off screen. This is what a display's
+     * `true` for a row whose whole stack is off screen — and false while the body
+     * renders none of its displays (`rendersDisplays`). This is what a display's
      * phase asks.
      */
     effectiveBodyMounted: boolean;
+    /** See `BaseViewModel.rendersDisplays`. */
+    rendersDisplays: boolean;
     setWidth(width: number): void;
     setBodyMounted(flag: boolean): void;
     setMinimized(flag: boolean): void;
@@ -445,6 +522,13 @@ export interface AbstractViewModel {
      * the view itself.
      */
     trackContainerFor?: (id: string) => TrackContainer | undefined;
+    /**
+     * the node a display in this view lays its regions out against, where that
+     * is not the view's own box — the circular view's strip. A display's
+     * foundation reads its host through `containingHost`, which answers this
+     * before the view itself.
+     */
+    regionHost?: unknown;
     /**
      * every track container this view owns INSTEAD of a `tracks` array of its
      * own. The synteny view is the only one: its tracks hang off the levels, one
@@ -453,6 +537,20 @@ export interface AbstractViewModel {
      * `trackContainerFor` cannot answer that — a walker has no id to ask with.
      */
     trackContainers?: TrackContainer[];
+    /**
+     * what this view contributes to the census of what is open: the tracks it
+     * holds itself, and the views nested directly inside it. `BaseViewModel`
+     * answers both with nothing, so a view declares what it owns instead of the
+     * base reading properties whose meaning belongs to the view — see
+     * `util/openViews.ts`, where the recursion over them lives.
+     *
+     * Required, like `bodyMounted`, so a stand-in that means to be enumerated
+     * says so; the empty default means forgetting under-reports rather than
+     * putting something that is not a track in front of the readiness marker.
+     */
+    ownTracks: AbstractTrackModel[];
+    /** the views nested directly inside this one — see `ownTracks` */
+    ownViews: AbstractViewModel[];
 }
 export declare function isViewModel(thing: unknown): thing is AbstractViewModel;
 type Display = {
@@ -461,12 +559,13 @@ type Display = {
 export interface AbstractTrackModel {
     id: string;
     displays: AbstractDisplayModel[];
-    configuration: AnyConfigurationModel & {
+    configuration: BaseTrackConfig & {
         displays: Display[];
     };
     minimized: boolean;
     resizing: boolean;
     setResizing: (flag: boolean) => void;
+    persistConfigurationNow?: () => void;
 }
 export declare function isTrackModel(thing: unknown): thing is AbstractTrackModel;
 export interface AbstractDisplayModel {

package/esm/util/types/index.js

@@ -18,6 +18,15 @@ export function isSessionModel(thing) {
 export function isSessionModelWithConfigEditing(t) {
     return isSessionModel(t) && 'editConfiguration' in t;
 }
+export function isSessionWithBaseTrackConfig(t) {
+    return isSessionModel(t) && 'baseTrackConfig' in t;
+}
+export function isSessionWithEditableTrackConfig(t) {
+    return isSessionModel(t) && 'getEditableTrackConfig' in t;
+}
+export function isSessionWithMultipleViews(t) {
+    return isSessionModel(t) && isStateTreeNode(t.views);
+}
 export function isSessionWithViewReplacement(t) {
     return isSessionModel(t) && 'replaceView' in t;
 }

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

@@ -145,4 +145,7 @@ export declare const FileLocation: import("@jbrowse/mobx-state-tree").ISnapshotP
         authInfo: any;
     }> | undefined;
 }>, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+/** A `jexl:` expression; a bare string is refused rather than read as one. */
+export declare const JexlExpressionString: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
 export { ElementId, createElementId } from './ElementId.ts';
+export { renameIds } from './renameIds.ts';

package/esm/util/types/mst.js

@@ -1,4 +1,5 @@
 import { types } from '@jbrowse/mobx-state-tree';
+import { isJexl } from '../jexlStrings.js';
 // #region regionModel
 export const NoAssemblyRegion = types
     .model('NoAssemblyRegion', {
@@ -78,4 +79,7 @@ export const FileLocation = types.snapshotProcessor(FileLocationUnion, {
         }
     },
 });
+/** A `jexl:` expression; a bare string is refused rather than read as one. */
+export const JexlExpressionString = types.refinement('JexlExpression', types.string, isJexl, value => `${JSON.stringify(value)} is not an expression: one is written with its prefix, as "jexl:get(feature,'score') > 10"`);
 export { ElementId, createElementId } from './ElementId.js';
+export { renameIds } from './renameIds.js';

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

@@ -0,0 +1 @@
+export declare function renameIds(obj: Record<string, unknown>): Record<string, unknown>;

package/esm/util/types/renameIds.js

@@ -0,0 +1,29 @@
+import { createElementId } from './ElementId.js';
+export function renameIds(obj) {
+    const idMap = new Map();
+    function transformIds(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return value.map(transformIds);
+        }
+        if (typeof value === 'object') {
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                if (key === 'id' && typeof val === 'string') {
+                    if (!idMap.has(val)) {
+                        idMap.set(val, createElementId());
+                    }
+                    result[key] = idMap.get(val);
+                }
+                else {
+                    result[key] = transformIds(val);
+                }
+            }
+            return result;
+        }
+        return value;
+    }
+    return transformIds(obj);
+}

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

@@ -38,7 +38,7 @@ export type DialogComponentType = React.LazyExoticComponent<React.FC<any>> | Rea
  * dialog. It is the most-called session member from plugin code (49 sites), and
  * nearly all of them are a display saying "the user wants to configure
  * something" — so a host drawing its own UI needs exactly this one name, not a
- * session. `agent-docs/ideas/lightweight-toolkit.md` §3.
+ * session. `agent-docs/ideas/waiting-on-a-call/lightweight-toolkit.md` §3.
  */
 export interface DialogHost {
     DialogComponent?: DialogComponentType;

package/esm/util/unknownSnapshotKeys.d.ts

@@ -0,0 +1,51 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/** what a diagnostic calls the view: its snapshot `type`, or the model name */
+export declare function viewLabel(self: IStateTreeNode): string;
+/**
+ * What every surface calls this mistake. A session spec launches a view without
+ * ever building a snapshot, so it classifies its own keys and reports them
+ * through its own session rather than through the sink below — one wording, so
+ * a typo reads the same whether it was written in a config or in a URL.
+ */
+export declare function unknownKeysMessage(label: string, keys: string[]): string;
+/** Why a settings key `applyDisplaySettings` was handed wrote nothing. */
+export type UnappliedReason = 'no-slot' | 'setter-only' | 'display-type';
+export interface UnappliedSetting {
+    key: string;
+    reason: UnappliedReason;
+}
+/** The action `setter-only` names: `height` -> `setHeight`. */
+export declare function displaySetterName(key: string): string;
+/**
+ * What a surface calls a key the display has an action for but no slot. Its own
+ * sentence rather than `unknownKeysMessage`'s: the display does take the
+ * setting, just not written this way, and saying "unknown key" over a key whose
+ * setter we name in the same breath contradicts itself.
+ */
+export declare function setterOnlyMessage(label: string, keys: string[]): string;
+/**
+ * Name the keys a view was handed and could not place, from the partition
+ * `withLaunchInput` runs on the snapshot.
+ */
+export declare function reportUnknownKeys(self: IStateTreeNode, keys: string[]): void;
+/**
+ * Name the row lists a view refused whole. `withLaunchInput` splits an authored
+ * array into the recipes a launcher resolves and the built snapshots MST
+ * restores, per entry — but a row list is indexed against the view's `levels`
+ * and per-level tracks, so a list holding both kinds has no correct split and
+ * is refused rather than renumbered.
+ */
+export declare function reportMalformedRows(self: IStateTreeNode, keys: string[]): void;
+/**
+ * What every surface calls v4's nested `init`. v5 takes every setting directly
+ * on the view object and unwraps the nesting on the way in, so the settings
+ * still arrive — this names the spelling to fix while they do.
+ */
+export declare function legacyInitMessage(label: string): string;
+/**
+ * Name a snapshot that still writes v4's nested `init`. The console alone,
+ * unlike the two reporters above: the settings were applied, so there is
+ * nothing for a visitor to act on and a warning toast over a working view is
+ * noise. `jbrowse validate` is where the author of the config hears about it.
+ */
+export declare function reportLegacyInit(self: IStateTreeNode): void;