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

package/esm/util/withLaunchInput.js

@@ -0,0 +1,273 @@
+import { reportLegacyInit, reportMalformedRows, reportUnknownKeys, } from './unknownSnapshotKeys.js';
+// re-exported here because the surfaces that classify their own keys — a
+// session spec, which launches without ever building a snapshot — reach the
+// partition's vocabulary through this module
+export { legacyInitMessage, unknownKeysMessage } from './unknownSnapshotKeys.js';
+// What afterAttach reports rather than applies. They live in the blob so the
+// partition has one place to put everything, and `pendingLaunch` is what keeps
+// them from reading as work to do.
+const REPORTED = new Set(['unknown', 'malformed', 'legacyInit']);
+/**
+ * The blob when it still holds something to apply, else undefined. A view's
+ * gates ask this rather than the raw property: a snapshot whose only launch
+ * content was a typo has nothing to launch, and a view that thinks otherwise
+ * waits on an assembly nobody named and never leaves the spinner.
+ *
+ * Returns the blob itself, never a copy — the launch autorun clears by
+ * identity, and a fresh object per read strands the init it just applied.
+ */
+export function pendingLaunch(launch) {
+    return launch && Object.keys(launch).some(k => !REPORTED.has(k))
+        ? launch
+        : undefined;
+}
+/**
+ * Declare one view's launch keys. The argument is
+ * `Record<keyof Commands, LaunchKeySpec>`, so a command the view interprets and
+ * nobody registered is a compile error rather than a key that partitions as a
+ * typo and warns.
+ *
+ * `passThrough` names keys that are neither a launch key nor a declared
+ * property and still belong on the snapshot — a legacy spelling the view's own
+ * `preProcessSnapshot` converts.
+ */
+export function defineLaunchKeys() {
+    return (keys, { passThrough } = {}) => ({
+        keys,
+        passThrough: passThrough ?? [],
+    });
+}
+// `id` picks up MST's optional identifier and `type` picks the view, so neither
+// is ever a setting and neither can be lifted off the snapshot.
+const IDENTITY = new Set(['id', 'type']);
+const LAUNCH = 'launch';
+/**
+ * The part of a launch spec that belongs on the snapshot: everything but the
+ * launch keys, and the identity and `launch` keys no spec may set. For a caller
+ * that applies the launch itself and builds the view from a snapshot — a
+ * synteny row, whose parent navigates it and opens its tracks — so what it
+ * hands MST is settings only, and the view's own partition sorts those into
+ * properties and reported typos.
+ */
+export function snapshotSettings(spec, registration) {
+    const keys = registration?.keys ?? {};
+    return Object.fromEntries(Object.entries(spec).filter(([key]) => !(key in keys) && !IDENTITY.has(key) && key !== LAUNCH));
+}
+function isObject(value) {
+    return !!value && typeof value === 'object';
+}
+// Each per-entry kind says only which entries are an authored recipe. A recipe
+// goes to the blob for the launcher to resolve; everything else is a built
+// snapshot and stays on the property, so a mixed array splits rather than
+// picking one meaning for the whole thing.
+function isRecipeEntry(kind, entry) {
+    switch (kind) {
+        case 'trackEntries':
+            // a built track snapshot cannot carry `trackId` — BaseTrackModel does not
+            // declare it. `type` does not discriminate: a spec writes display types
+            // inline
+            return (typeof entry === 'string' || (isObject(entry) && 'trackId' in entry));
+        case 'highlightEntries':
+            // a string needs coerceHighlight and the assembly manager, neither of
+            // which a pure preprocessor can reach; an object is the persisted shape
+            return typeof entry === 'string';
+        case 'rows':
+            // a built row is a view snapshot, and every view's `type` is a required
+            // literal
+            return !(isObject(entry) && 'type' in entry);
+        default:
+            return true;
+    }
+}
+function splitEntries(kind, value) {
+    const entries = Array.isArray(value) ? value : [value];
+    const recipes = entries.filter(e => isRecipeEntry(kind, e));
+    const built = entries.filter(e => !isRecipeEntry(kind, e));
+    return {
+        launch: recipes.length
+            ? Array.isArray(value)
+                ? recipes
+                : value
+            : undefined,
+        state: built.length ? (Array.isArray(value) ? built : value) : undefined,
+    };
+}
+// The properties a snapshot's keys are classified against are the REGISTERED
+// view type's, read at preprocess time: `extendViewType` composes onto the
+// model after `withLaunchInput` wrapped it, and a set frozen at wrap time sent
+// every added property to `unknown` — restored at its default, with a warning
+// naming it a typo. The wrapped model's own properties are the answer when no
+// registry is given, or the snapshot names a type it does not hold, which is
+// how a factory-built model in a test behaves.
+function knownPropsResolver(model, registry) {
+    let cachedProps;
+    let cachedKeys = new Set();
+    return (snap) => {
+        const name = snap.type;
+        const registered = registry && typeof name === 'string' && registry.viewTypes.has(name)
+            ? registry.getViewType(name)
+            : undefined;
+        const props = registered?.isStateModelLoaded
+            ? registered.stateModel.properties
+            : model.properties;
+        if (props !== cachedProps) {
+            cachedProps = props;
+            cachedKeys = new Set(Object.keys(props));
+        }
+        return cachedKeys;
+    };
+}
+function classify(snap, { keys, passThrough }, known, out) {
+    for (const [key, value] of Object.entries(snap)) {
+        const spec = keys[key];
+        if (IDENTITY.has(key)) {
+            out.state[key] = value;
+        }
+        else if (spec?.kind === 'launch') {
+            out.launch[key] = value;
+        }
+        else if (spec?.kind === 'replay') {
+            out.state[key] = value;
+            out.launch[key] = value;
+        }
+        else if (spec) {
+            const { launch, state } = splitEntries(spec.kind, value);
+            if (spec.kind === 'rows' && launch !== undefined && state !== undefined) {
+                // A row list indexes against `levels` and `tracks[i]`, so lifting half
+                // of it renumbers the other half. Nothing here can throw — a pure
+                // preprocessor runs against snapshots the union is about to reject — so
+                // the whole list goes to the bucket afterAttach reports and the view
+                // comes up on its import form rather than on a silently misaligned
+                // stack.
+                out.malformed[key] = value;
+            }
+            else {
+                if (launch !== undefined) {
+                    out.launch[key] = launch;
+                }
+                if (state !== undefined) {
+                    out.state[key] = state;
+                }
+            }
+        }
+        else if (known.has(key) || passThrough.includes(key)) {
+            out.state[key] = value;
+        }
+        else {
+            out.unknown[key] = value;
+        }
+    }
+}
+// BreakpointSplitView's v4 `init` was a bare array of panels rather than an
+// object of settings. A positional list can only be the view's row list, and a
+// view declares at most one, so it is read as that key rather than classified
+// per index — which would name "0" and "1" as unknown keys.
+function legacyInitSnapshot(init, { keys }) {
+    const rows = Object.entries(keys).find(([, spec]) => spec.kind === 'rows')?.[0];
+    return Array.isArray(init) && rows ? { [rows]: init } : init;
+}
+/**
+ * Accept a view's settings written directly on the view object, and move the
+ * ones a launcher has to resolve into the internal `launch` property.
+ *
+ * The partition is a `preProcessSnapshot` and is PURE. A session's view type is
+ * a `types.union`, so MST runs every member's preprocessor against every
+ * candidate snapshot while deciding which one matches, and runs it about twice
+ * more per instantiation; a warning from in here fires against snapshots that
+ * are about to be rejected. `afterAttach` — reached only by a snapshot that won
+ * — reports what the partition captured.
+ *
+ * `registry` is the PluginManager. With it the partition classifies against
+ * the view type as registered, `extendViewType`'s added properties included;
+ * without it, against the model as wrapped here. `materialized` draws the line
+ * past which the blob is no longer persisted; see `LaunchInputOptions`.
+ *
+ * ORDER: MST runs preprocessors in the reverse of the order they were added, so
+ * this belongs on the chain BEFORE a view's own legacy-key preprocessor, where
+ * it partitions the snapshot MST finally consumes rather than a key that remap
+ * is about to convert.
+ *
+ * The widening cast is the LAST link that may change the creation type: it
+ * replaces `CustomC`, so a `.props()` added after it is invisible to
+ * `SnapshotIn`. Further `preProcessSnapshot`/`postProcessSnapshot` links are
+ * fine — both carry `CustomC` through.
+ *
+ * Not `types.snapshotProcessor`, which carries the same widened input and stops
+ * being a `ModelType`. `PluginManager.pluggableMstType` filters union members on
+ * `isModelType`, so a wrapped view is dropped from the session's view union
+ * without a word, and `ViewType.stateModel` and every `.properties`
+ * introspection site break with it.
+ */
+export function withLaunchInput(model, registration, { registry, materialized }) {
+    const knownProps = knownPropsResolver(model, registry);
+    const partitioned = model
+        .preProcessSnapshot((snap) => {
+        if (!isObject(snap)) {
+            return snap;
+        }
+        const known = knownProps(snap);
+        const { init, ...rest } = snap;
+        const out = {
+            state: {},
+            launch: {},
+            unknown: {},
+            malformed: {},
+        };
+        if (isObject(init)) {
+            // v4's nesting, unwrapped rather than refused: a nested key sorts the
+            // same three ways a flat one does, so honoring it costs one more pass
+            // and a deprecation warning, where dropping it opens an admin's
+            // `defaultSession` on its defaults. First, so a snapshot spelling one
+            // key both ways resolves to the flat one the docs teach.
+            classify(legacyInitSnapshot(init, registration), registration, known, out);
+            out.launch.legacyInit = true;
+        }
+        classify(rest, registration, known, out);
+        if (Object.keys(out.unknown).length) {
+            out.launch.unknown = out.unknown;
+        }
+        if (Object.keys(out.malformed).length) {
+            out.launch.malformed = out.malformed;
+        }
+        const persisted = out.state[LAUNCH];
+        return Object.keys(out.launch).length
+            ? {
+                ...out.state,
+                [LAUNCH]: {
+                    ...(isObject(persisted) ? persisted : {}),
+                    ...out.launch,
+                },
+            }
+            : out.state;
+    })
+        .actions(self => ({
+        afterAttach() {
+            const { launch } = self;
+            if (launch?.legacyInit) {
+                reportLegacyInit(self);
+            }
+            reportUnknownKeys(self, Object.keys(launch?.unknown ?? {}));
+            reportMalformedRows(self, Object.keys(launch?.malformed ?? {}));
+        },
+    }))
+        // Whole while the view has yet to materialize, since the pending launch is
+        // then the only thing a reload can rebuild the view from, and gone once it
+        // has — the report keys with it, so a saved session never carries a
+        // typo report about content it no longer holds. `legacyInit` goes either
+        // way: it names the SPELLING of the snapshot this view was opened from,
+        // and the saved one does not use it, so persisting it would report nesting
+        // on every restore forever (`pendingLaunch` excludes the report keys, so
+        // no launch run ever clears it).
+        .postProcessSnapshot((snap) => {
+        const launch = snap[LAUNCH];
+        if (!isObject(launch)) {
+            return snap;
+        }
+        const { legacyInit, ...kept } = launch;
+        return Object.keys(kept).length &&
+            !materialized(snap)
+            ? { ...snap, [LAUNCH]: kept }
+            : Object.fromEntries(Object.entries(snap).filter(([key]) => key !== LAUNCH));
+    });
+    return partitioned;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/core",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.3",
   "type": "module",
   "description": "JBrowse 2 core libraries used by plugins",
   "keywords": [
@@ -32,6 +32,8 @@
     "./PluginLoader": "./esm/PluginLoader.js",
     "./PluginManager": "./esm/PluginManager.js",
     "./ReExports/list": "./esm/ReExports/list.js",
+    "./ReExports/modules": "./esm/ReExports/modules.js",
+    "./ReExports/registry": "./esm/ReExports/registry.js",
     "./TextSearch/BaseResults": "./esm/TextSearch/BaseResults.js",
     "./TextSearch/TextSearchManager": "./esm/TextSearch/TextSearchManager.js",
     "./assemblyManager": "./esm/assemblyManager/index.js",
@@ -44,6 +46,7 @@
     "./data_adapters/BaseAdapter/getAdapterId": "./esm/data_adapters/BaseAdapter/getAdapterId.js",
     "./data_adapters/BaseAdapter/stats": "./esm/data_adapters/BaseAdapter/stats.js",
     "./data_adapters/BaseAdapter/types": "./esm/data_adapters/BaseAdapter/types.js",
+    "./data_adapters/adapterSessionRefcount": "./esm/data_adapters/adapterSessionRefcount.js",
     "./data_adapters/dataAdapterCache": "./esm/data_adapters/dataAdapterCache.js",
     "./data_adapters/getFeatureAdapter": "./esm/data_adapters/getFeatureAdapter.js",
     "./data_adapters/getSequenceSubAdapter": "./esm/data_adapters/getSequenceSubAdapter.js",
@@ -140,14 +143,13 @@
     "./util/Base1DUtils": "./esm/util/Base1DUtils.js",
     "./util/Base1DViewModel": "./esm/util/Base1DViewModel.js",
     "./util/FileSaver": "./esm/util/FileSaver/index.js",
-    "./util/QuickLRU": "./esm/util/QuickLRU/index.js",
     "./util/SvgCanvas": "./esm/util/SvgCanvas.js",
     "./util/TimeTraveller": "./esm/util/TimeTraveller.js",
     "./util/aborting": "./esm/util/aborting.js",
+    "./util/adapterConfigKey": "./esm/util/adapterConfigKey.js",
     "./util/adapterMetadata": "./esm/util/adapterMetadata.js",
     "./util/addRelativeUris": "./esm/util/addRelativeUris.js",
     "./util/analytics": "./esm/util/analytics.js",
-    "./util/applyInitSettings": "./esm/util/applyInitSettings.js",
     "./util/assemblyConfigUtils": "./esm/util/assemblyConfigUtils.js",
     "./util/bandHeight": "./esm/util/bandHeight.js",
     "./util/bandLayout": "./esm/util/bandLayout.js",
@@ -185,6 +187,7 @@
     "./util/installClearHoverOnSurfaceMove": "./esm/util/installClearHoverOnSurfaceMove.js",
     "./util/installFetch": "./esm/util/installFetch.js",
     "./util/installInitAutorun": "./esm/util/installInitAutorun.js",
+    "./util/installPrerequisiteFetch": "./esm/util/installPrerequisiteFetch.js",
     "./util/io": "./esm/util/io/index.js",
     "./util/io/RemoteFileWithRangeCache": "./esm/util/io/RemoteFileWithRangeCache.js",
     "./util/isDataCurrent": "./esm/util/isDataCurrent.js",
@@ -194,14 +197,18 @@
     "./util/layouts": "./esm/util/layouts/index.js",
     "./util/layouts/GranularRectLayout": "./esm/util/layouts/GranularRectLayout.js",
     "./util/layouts/placeRect": "./esm/util/layouts/placeRect.js",
+    "./util/lazyAfterAttach": "./esm/util/lazyAfterAttach.js",
     "./util/leadingEdgeAutorun": "./esm/util/leadingEdgeAutorun.js",
+    "./util/legendCandidates": "./esm/util/legendCandidates.js",
     "./util/librpc": "./esm/util/librpc.js",
     "./util/localStorage": "./esm/util/localStorage.js",
     "./util/makeAssembly": "./esm/util/makeAssembly.js",
+    "./util/mst-reflection": "./esm/util/mst-reflection.js",
     "./util/mstUtils": "./esm/util/mstUtils.js",
     "./util/nanoid": "./esm/util/nanoid.js",
     "./util/numericUtils": "./esm/util/numericUtils.js",
     "./util/offscreenCanvasPonyfill": "./esm/util/offscreenCanvasPonyfill.js",
+    "./util/openViews": "./esm/util/openViews.js",
     "./util/paintLayer": "./esm/util/paintLayer.js",
     "./util/parseLineByLine": "./esm/util/parseLineByLine.js",
     "./util/progress": "./esm/util/progress.js",
@@ -235,7 +242,8 @@
     "./util/viewStatus": "./esm/util/viewStatus.js",
     "./util/virtualRange": "./esm/util/virtualRange.js",
     "./util/wheelZoom": "./esm/util/wheelZoom.js",
-    "./util/whenViewSettled": "./esm/util/whenViewSettled.js"
+    "./util/whenViewSettled": "./esm/util/whenViewSettled.js",
+    "./util/withLaunchInput": "./esm/util/withLaunchInput.js"
   },
   "files": [
     "esm"
@@ -253,13 +261,13 @@
     "@jbrowse/mobx-state-tree": "^6.5.1",
     "@jbrowse/quick-lru": "^7.3.5",
     "@leeoniya/ufuzzy": "^1.0.19",
-    "@mui/icons-material": "^9.3.1",
-    "@mui/material": "^9.3.1",
-    "@mui/system": "^9.3.0",
-    "@mui/x-data-grid": "^9.12.0",
+    "@mui/icons-material": "^9.4.0",
+    "@mui/material": "^9.4.0",
+    "@mui/system": "^9.4.0",
+    "@mui/x-data-grid": "^9.13.0",
     "canvas-sequencer-ts": "^3.1.3",
     "compare-versions": "^6.1.1",
-    "dompurify": "^3.4.14",
+    "dompurify": "^3.4.15",
     "generic-filehandle2": "^2.4.0",
     "idb": "^8.0.3",
     "mobx": "^7.0.3",
@@ -267,8 +275,8 @@
     "pako-esm2": "^2.0.2",
     "rxjs": "^7.8.2",
     "source-map-js": "^1.2.1",
-    "@jbrowse/add-track-core": "^5.0.0-beta.1",
-    "@jbrowse/render-core": "^5.0.0-beta.1"
+    "@jbrowse/add-track-core": "^5.0.0-beta.3",
+    "@jbrowse/render-core": "^5.0.0-beta.3"
   },
   "peerDependencies": {
     "react": ">=19.0.0",

package/esm/ui/promotableMenuItems.d.ts

@@ -1,19 +0,0 @@
-import type { Pin } from '../configuration/promotablePin.ts';
-import type { CheckboxMenuItem, RadioMenuItem } from './MenuTypes.ts';
-import type { RadioOption, SettingRowOptions } from './toggleMenuItems.ts';
-/** #menuBuilder promotableToggleItem | `checkboxItem` plus an apply-to-open-tracks pin */
-export declare function promotableToggleItem({ label, checked, onToggle, pin, ...opts }: {
-    label: string;
-    checked: boolean;
-    onToggle: () => void;
-    pin: Pin;
-} & SettingRowOptions): CheckboxMenuItem;
-/** #menuBuilder promotableRadioItem | `radioItem` plus an apply-to-open-tracks pin */
-export declare function promotableRadioItem({ label, checked, onClick, pin, ...opts }: {
-    label: string;
-    checked: boolean;
-    onClick: () => void;
-    pin?: Pin;
-} & SettingRowOptions): RadioMenuItem;
-/** #menuBuilder promotableRadioItems | `radioItems` plus a pin per option, from a factory over the value */
-export declare function promotableRadioItems<T extends string>(options: readonly RadioOption<T>[], current: T | undefined, setMode: (m: T) => void, pin: (value: T) => Pin): RadioMenuItem[];

package/esm/ui/promotableMenuItems.js

@@ -1,89 +0,0 @@
-import { checkboxItem, radioItem, radioItems } from './toggleMenuItems.js';
-// Every builder here describes the trailing pin (`pin`) rather than
-// rendering it. That is what keeps this module — and therefore every state
-// model and menu file that calls it — free of React and of MUI's
-// ToggleButton/Tooltip. `menuItemAdornment.tsx` turns the description into
-// `PinAdornment` at the point the menu is drawn. See
-// reference/EAGER_BUNDLE.md; `menuItems.purity.test.ts` holds it.
-//
-// Each is the plain builder in `toggleMenuItems.ts` plus a pin, and each is
-// written that way — `checkboxItem` / `radioItems` build the row — so the
-// promotable and plain forms of a row can differ only by the pin.
-// A promotable setting as one native checkbox menu row: the value toggles the
-// track (inheriting native hover/sizing/keyboard), and a trailing pin
-// (endAdornment) applies this value to every open track of the display type,
-// offering the display-type default as its snackbar's one action. Always shown
-// so the capability is discoverable.
-//
-// **The row itself is `checkboxItem`'s**, so the two builders can only ever
-// differ by the pin. They used to be two literals, and had already drifted: this
-// one accepted `helpText` and `keepMenuOpen` while silently dropping `disabled`
-// and `disabledHelpText`, so a promotable row could not be greyed out the way
-// its plain sibling could. Sharing the body is also what makes a future
-// change to what a checkbox row *is* reach both — the failure `checkboxItem`'s
-// own comment records is a menu regressing by omission.
-//
-// `keepMenuOpen` is left unset by default, so `CascadingMenu` keeps the row open
-// by its checkbox type: these rows only write a setting, users flip several in
-// one visit, and the menu is an observer so the ticks and pins move live. A row
-// whose click opens a dialog instead (colorBy's "Tag...") passes false.
-/** #menuBuilder promotableToggleItem | `checkboxItem` plus an apply-to-open-tracks pin */
-export function promotableToggleItem({ label, checked, onToggle, pin, ...opts }) {
-    return {
-        ...checkboxItem(label, checked, onToggle, opts),
-        pin: { control: pin, label },
-    };
-}
-// ONE radio row of a promotable-value group — the escape hatch, for a group the
-// plural builder below can't express. **Reach for `promotableRadioItems` first**:
-// every option in a group has to get a pin, and hand-naming the rows is what
-// leaves one without.
-//
-// The rows that genuinely need this: `pin` is optional here, for a row with no
-// single value to promote yet (the colorBy "Tag..." row before a tag is picked)
-// or a display whose slot isn't promotable at all (the shared colorBy menu on
-// gwas/variants); and the alignments size presets, whose group is gated row by
-// row (`needsContent`) and mixes in a non-promotable "Custom..." peer.
-//
-// **The row itself is `radioItem`'s**, for the reason `promotableToggleItem`'s
-// is `checkboxItem`'s: it was a second literal, and it had drifted the same way
-// its checkbox sibling had — naming `helpText`/`keepMenuOpen` by hand and so
-// silently dropping `disabled` and `disabledHelpText`, which the
-// alignments size presets have to bolt back on afterwards (`needsContent`).
-/** #menuBuilder promotableRadioItem | `radioItem` plus an apply-to-open-tracks pin */
-export function promotableRadioItem({ label, checked, onClick, pin, ...opts }) {
-    return {
-        ...radioItem(label, checked, onClick, opts),
-        ...(pin && {
-            pin: { control: pin, label },
-        }),
-    };
-}
-// A whole promotable radio group: `radioItems` plus one pin per option. The
-// plural form of the builder above, and the one to reach for on a group whose
-// options differ only in their value — which is all four of them today
-// (`heightMode`, `displayMode`, `subfeatureLabels`, `sashimiArcsMode`).
-//
-// **Every option in a group gets a pin, the `promotedBase` value included** —
-// once a non-base value is promoted, pinning the base back is the only per-value
-// way to undo it from its own row, and a radio group with one row silently
-// missing its trailing control reads as a bug. Building the group here is what
-// makes that structural instead of a rule to remember: `sashimiArcsMode`'s base
-// looked unpinnable precisely because each row had been named by hand. Prefer
-// this over `.map(promotableRadioItem)` whenever the pin is a function of the
-// option's value.
-//
-// `pin` is a factory rather than an array so it can't be a row short. Pass
-// `value => makePin(self, slot, value)`, or a model member of that shape where
-// the menu module is handed a duck-typed model (alignments).
-//
-// The rows are `radioItems`' own, so the promotable and plain groups can't drift
-// on anything but the pin. `radioItems` maps `options` in order, which is what
-// lets each row be paired back to the option that built it.
-/** #menuBuilder promotableRadioItems | `radioItems` plus a pin per option, from a factory over the value */
-export function promotableRadioItems(options, current, setMode, pin) {
-    return radioItems(options, current, setMode).map((item, i) => {
-        const { value, label } = options[i];
-        return { ...item, pin: { control: pin(value), label } };
-    });
-}

package/esm/util/applyInitSettings.d.ts

@@ -1,79 +0,0 @@
-import type { IAnyModelType, IStateTreeNode, SnapshotIn } from '@jbrowse/mobx-state-tree';
-/**
- * A view's init type, derived: the keys its launcher interprets (`Commands`)
- * plus every declared property of its state model, optional, in the property's
- * own snapshot type. Nothing is restated, so a property is authorable — and
- * TYPED — from the line that declares it.
- *
- * ```ts
- * export type LinearSyntenyViewInit = ViewInit<
- *   LinearSyntenyViewStateModel,
- *   LinearSyntenyViewCommands
- * >
- * ```
- *
- * THE ONE RULE THIS DEPENDS ON: the model's own `init` property must be typed
- * as the `Commands`, not as this. `init` is a property, so an `init` typed as
- * the whole thing makes the whole thing depend on itself — TS7023 on the
- * factory, then implicit-any across every file that touches the view (ADR-055,
- * same failure the view/display instance pair has). Commands never mention the
- * model, so typing `init` as those breaks the loop, and it costs nothing: the
- * view's own code reads the commands out of `self.init`, and the settings half
- * is read only by `applyInitSettings`, which asks the model rather than a type.
- */
-export type ViewInit<M extends IAnyModelType, Commands> = Commands & Partial<Omit<SnapshotIn<M>, keyof Commands | (typeof RESERVED_KEYS)[number]>>;
-export declare const RESERVED_KEYS: readonly ['id', 'type', 'init'];
-export interface InitSettingsReport {
-    /** keys applied, in the order they were found */
-    applied: string[];
-    /** keys naming no declared property — a typo, or a prop that never existed */
-    unknown: string[];
-    /** declared keys whose value the property's own type rejected */
-    invalid: string[];
-}
-/**
- * Apply the plain-settings half of an `init` blob: every key naming a declared
- * MST property of `self` is written straight to it, and the caller handles only
- * the keys it names in `commands`.
- *
- * THE POINT IS THAT THERE IS NO PER-SETTING CODE. A view used to need a
- * hand-written `if (init.x !== undefined) self.setX(init.x)` arm per property,
- * so a new toggle worked from its menu the moment it was declared and was
- * dropped in silence from every authored surface — a session spec, a share
- * link, a config `defaultSession` — until someone remembered the second edit.
- * Nobody did: `drawLocationMarkers` shipped unauthorable, and DotplotView's
- * `alpha`/`drawCigar`/`lineWidth`/`lockAspectRatio` never had an arm at all.
- * Reading the property list off the model at runtime means declaring the
- * property IS declaring it authorable, including properties a composed mixin
- * brings in (colorBy, showColorLegend), and there is nothing left to keep in
- * sync.
- *
- * `commands` is what a launcher genuinely has to interpret: keys with no
- * property behind them (`loc`, `autoDiagonalize`), keys whose name collides
- * with a property meaning something else (a spec's `views` is a list of
- * assemblies to open; the model's `views` is the built rows), and keys with an
- * ordering constraint (`levelHeights` must land after the auto-scale pass).
- * Listing one is a decision to write code for it; everything else needs none.
- *
- * WRITTEN AS A PATCH, not through `setX`. Applying init is state restoration,
- * and the authority on that is MST: `applyPatch` validates each value against
- * the property's own type and touches nothing else, where `applySnapshot`
- * would rebuild the view's children. That it skips the setters is correct
- * rather than a shortcut — a session reload restores the same state from a
- * snapshot and calls no setters either, so a property needing a setter's side
- * effect to be correct is already broken on reload, and the effect belongs in a
- * reaction on the property.
- *
- * A value the property's type rejects is dropped and reported rather than
- * thrown: init blobs come from URLs, and one bad number should not cost the
- * reader the whole view.
- */
-export declare function applyInitSettings(self: IStateTreeNode, init: object | undefined, { commands }?: {
-    commands?: readonly string[];
-}): InitSettingsReport;
-/**
- * Say what `applyInitSettings` refused, naming the surface. Split from the
- * apply so a caller under test can assert the report without a console, and so
- * the two messages read the same wherever they come from.
- */
-export declare function warnInitSettings(surface: string, report: InitSettingsReport): void;

package/esm/util/applyInitSettings.js

@@ -1,91 +0,0 @@
-import { applyPatch, getPropertyMembers } from '@jbrowse/mobx-state-tree';
-// Keys that are a view's identity or its plumbing rather than a setting. A
-// launch spec never gets to write these: `type` picks the view, `id` is passed
-// top-level so MST's optional identifier honors it, and `init` inside `init` is
-// the nesting mistake loadSessionSpec already reports.
-export const RESERVED_KEYS = ['id', 'type', 'init'];
-const RESERVED = new Set(RESERVED_KEYS);
-/**
- * Apply the plain-settings half of an `init` blob: every key naming a declared
- * MST property of `self` is written straight to it, and the caller handles only
- * the keys it names in `commands`.
- *
- * THE POINT IS THAT THERE IS NO PER-SETTING CODE. A view used to need a
- * hand-written `if (init.x !== undefined) self.setX(init.x)` arm per property,
- * so a new toggle worked from its menu the moment it was declared and was
- * dropped in silence from every authored surface — a session spec, a share
- * link, a config `defaultSession` — until someone remembered the second edit.
- * Nobody did: `drawLocationMarkers` shipped unauthorable, and DotplotView's
- * `alpha`/`drawCigar`/`lineWidth`/`lockAspectRatio` never had an arm at all.
- * Reading the property list off the model at runtime means declaring the
- * property IS declaring it authorable, including properties a composed mixin
- * brings in (colorBy, showColorLegend), and there is nothing left to keep in
- * sync.
- *
- * `commands` is what a launcher genuinely has to interpret: keys with no
- * property behind them (`loc`, `autoDiagonalize`), keys whose name collides
- * with a property meaning something else (a spec's `views` is a list of
- * assemblies to open; the model's `views` is the built rows), and keys with an
- * ordering constraint (`levelHeights` must land after the auto-scale pass).
- * Listing one is a decision to write code for it; everything else needs none.
- *
- * WRITTEN AS A PATCH, not through `setX`. Applying init is state restoration,
- * and the authority on that is MST: `applyPatch` validates each value against
- * the property's own type and touches nothing else, where `applySnapshot`
- * would rebuild the view's children. That it skips the setters is correct
- * rather than a shortcut — a session reload restores the same state from a
- * snapshot and calls no setters either, so a property needing a setter's side
- * effect to be correct is already broken on reload, and the effect belongs in a
- * reaction on the property.
- *
- * A value the property's type rejects is dropped and reported rather than
- * thrown: init blobs come from URLs, and one bad number should not cost the
- * reader the whole view.
- */
-export function applyInitSettings(self, 
-// `object` rather than a keyed record: an init blob's static type is the
-// view's own `ViewInit`, which has named members and no index signature — by
-// design, so a typo is a compile error there — and that is not assignable to
-// `Record<string, unknown>`. This reads it by enumeration anyway.
-init, { commands = [] } = {}) {
-    const report = { applied: [], unknown: [], invalid: [] };
-    if (!init) {
-        return report;
-    }
-    const skip = new Set(commands);
-    const { properties } = getPropertyMembers(self);
-    const patch = [];
-    for (const [key, value] of Object.entries(init)) {
-        if (skip.has(key) || RESERVED.has(key) || value === undefined) {
-            continue;
-        }
-        const propType = properties[key];
-        if (!propType) {
-            report.unknown.push(key);
-        }
-        else if (!propType.is(value)) {
-            report.invalid.push(key);
-        }
-        else {
-            patch.push({ op: 'replace', path: `/${key}`, value });
-            report.applied.push(key);
-        }
-    }
-    if (patch.length) {
-        applyPatch(self, patch);
-    }
-    return report;
-}
-/**
- * Say what `applyInitSettings` refused, naming the surface. Split from the
- * apply so a caller under test can assert the report without a console, and so
- * the two messages read the same wherever they come from.
- */
-export function warnInitSettings(surface, report) {
-    if (report.unknown.length) {
-        console.warn(`${surface} ignored unknown key(s): ${report.unknown.join(', ')}`);
-    }
-    if (report.invalid.length) {
-        console.warn(`${surface} ignored key(s) with an invalid value: ${report.invalid.join(', ')}`);
-    }
-}