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

package/esm/util/whenViewSettled.d.ts

@@ -1,5 +1,6 @@
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * Wait until a view has either initialized — launch blob consumed and all — or
+ * failed, and report which.
  *
  * `initialized` folds in a view's assemblies, so an assembly that fails to load
  * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
@@ -9,6 +10,15 @@
  * export hung behind its dialog's spinner, and a launched breakpoint split view
  * that opened but was never navigated or zoomed.
  *
+ * `pendingLaunch` is the other half, and it matters because `initialized` can
+ * go true MID-launch: LGV's flips the moment displayedRegions land, while the
+ * same apply pass still has tracks to attach — so a caller acting there reads a
+ * positioned view with its tracks missing (an SVG export saves it that way).
+ * A launch failure cannot hang this: the state machine either clears the blob
+ * (materialized, reported as a snackbar) or sets the view's `error`
+ * (installInitAutorun's failure policy). A view with no launch machinery has no
+ * `pendingLaunch` and the term is vacuously satisfied.
+ *
  * Every view exposes a resolved `error` beside `initialized`, so waiting on the
  * pair turns the hang into something reportable. What to report is the caller's,
  * because the vocabularies genuinely differ — an export says "cannot export"
@@ -16,12 +26,15 @@
  * says the launch failed — which is why this returns the answer instead of
  * throwing one wording at both.
  *
- * No time bound, deliberately: `initialized || error` is a terminal pair, so a
- * slow-but-healthy remote assembly is waited out rather than guessed at.
+ * No time bound, deliberately: `(initialized && launch consumed) || error` is a
+ * terminal set, so a slow-but-healthy remote assembly is waited out rather than
+ * guessed at.
  *
- * @returns true if the view initialized, false if it settled on an error
+ * @returns true if the view initialized (and consumed any launch), false if it
+ * settled on an error
  */
 export declare function whenViewSettled(view: {
     initialized: boolean;
     error: unknown;
+    pendingLaunch?: unknown;
 }): Promise<boolean>;

package/esm/util/whenViewSettled.js

@@ -1,6 +1,7 @@
 import { when } from 'mobx';
 /**
- * Wait until a view has either initialized or failed, and report which.
+ * Wait until a view has either initialized — launch blob consumed and all — or
+ * failed, and report which.
  *
  * `initialized` folds in a view's assemblies, so an assembly that fails to load
  * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
@@ -10,6 +11,15 @@ import { when } from 'mobx';
  * export hung behind its dialog's spinner, and a launched breakpoint split view
  * that opened but was never navigated or zoomed.
  *
+ * `pendingLaunch` is the other half, and it matters because `initialized` can
+ * go true MID-launch: LGV's flips the moment displayedRegions land, while the
+ * same apply pass still has tracks to attach — so a caller acting there reads a
+ * positioned view with its tracks missing (an SVG export saves it that way).
+ * A launch failure cannot hang this: the state machine either clears the blob
+ * (materialized, reported as a snackbar) or sets the view's `error`
+ * (installInitAutorun's failure policy). A view with no launch machinery has no
+ * `pendingLaunch` and the term is vacuously satisfied.
+ *
  * Every view exposes a resolved `error` beside `initialized`, so waiting on the
  * pair turns the hang into something reportable. What to report is the caller's,
  * because the vocabularies genuinely differ — an export says "cannot export"
@@ -17,12 +27,15 @@ import { when } from 'mobx';
  * says the launch failed — which is why this returns the answer instead of
  * throwing one wording at both.
  *
- * No time bound, deliberately: `initialized || error` is a terminal pair, so a
- * slow-but-healthy remote assembly is waited out rather than guessed at.
+ * No time bound, deliberately: `(initialized && launch consumed) || error` is a
+ * terminal set, so a slow-but-healthy remote assembly is waited out rather than
+ * guessed at.
  *
- * @returns true if the view initialized, false if it settled on an error
+ * @returns true if the view initialized (and consumed any launch), false if it
+ * settled on an error
  */
 export async function whenViewSettled(view) {
-    await when(() => view.initialized || !!view.error);
-    return view.initialized;
+    const ready = () => view.initialized && view.pendingLaunch === undefined;
+    await when(() => ready() || !!view.error);
+    return ready();
 }

package/esm/util/withLaunchInput.d.ts

@@ -0,0 +1,123 @@
+export { legacyInitMessage, unknownKeysMessage } from './unknownSnapshotKeys.ts';
+import type { IAnyModelType, IModelType, SnapshotIn } from '@jbrowse/mobx-state-tree';
+/**
+ * How a launch key's value is told apart from the state property of the same
+ * name. A key whose name collides with nothing is `launch`; the rest name the
+ * discriminator that splits one authored array into the recipe entries the
+ * launcher resolves and the built snapshots MST restores.
+ *
+ * `replay` is the one that is not remapped at all: the value lands on its
+ * property, and a copy rides in the blob so the launcher can run the ordered
+ * imperative step the property write alone does not produce.
+ */
+export type LaunchKeyKind = 'launch' | 'trackEntries' | 'rows' | 'highlightEntries' | 'replay';
+export interface LaunchKeySpec {
+    kind: LaunchKeyKind;
+}
+export interface LaunchKeyRegistration<Commands, PassThrough extends string = never> {
+    keys: Record<string, LaunchKeySpec>;
+    passThrough: readonly PassThrough[];
+    /** never assigned; it carries `Commands` to `withLaunchInput`'s return type */
+    commands?: Commands;
+}
+/**
+ * The launch keys a view captured, plus what it has to report.
+ *
+ * `Commands` is not made partial: hand-authored JSON is what fills this, so a
+ * key the interface marks required is not a guarantee here either way, and the
+ * launcher already guards the ones it cannot proceed without.
+ */
+export type LaunchInput<Commands> = Commands & {
+    unknown?: Record<string, unknown>;
+    malformed?: Record<string, unknown>;
+    legacyInit?: boolean;
+};
+/**
+ * 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 declare function pendingLaunch<C>(launch: LaunchInput<C> | undefined): LaunchInput<C> | undefined;
+/**
+ * A view's snapshot type, widened to the authored shape: every launch key is
+ * accepted beside the declared properties, and a key that is both takes either
+ * meaning. Excess-property checking then makes a misspelled key an error at
+ * every literal site — a `defaultSession` view, an `addView` call, a
+ * `createViewState` spec.
+ */
+export type LaunchSnapshotIn<M extends IAnyModelType, Commands, PassThrough extends string = never> = Omit<SnapshotIn<M>, keyof Commands> & {
+    [K in keyof Commands]?: K extends keyof SnapshotIn<M> ? Commands[K] | SnapshotIn<M>[K] : Commands[K];
+} & {
+    [K in PassThrough]?: unknown;
+} & {
+    /**
+     * @deprecated v4's nesting. Write every setting directly on the view object;
+     * this is unwrapped on the way in and warns.
+     */
+    init?: Commands;
+};
+type ReservedKey = 'id' | 'type' | 'launch';
+/**
+ * What a view can be launched with, 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 twin of `LaunchSnapshotIn` above, from the other end: that one widens a
+ * snapshot type for a literal MST site, this one is what a caller BUILDING a
+ * spec annotates, so its commands stay required and its properties optional.
+ */
+export type ViewInit<M extends IAnyModelType, Commands> = Commands & Partial<Omit<SnapshotIn<M>, keyof Commands | ReservedKey>>;
+export type LaunchInputModel<M extends IAnyModelType, Commands, PassThrough extends string = never> = M extends IModelType<infer P, infer O, any, infer S> ? IModelType<P, O, LaunchSnapshotIn<M, Commands, PassThrough>, S> : never;
+/**
+ * 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 declare function defineLaunchKeys<Commands>(): <const P extends readonly string[] = readonly never[]>(keys: Record<keyof Commands, LaunchKeySpec>, { passThrough }?: {
+    passThrough?: P;
+}) => LaunchKeyRegistration<Commands, P[number]>;
+/**
+ * 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.
+ *
+ * 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 declare function withLaunchInput<M extends IAnyModelType, Commands, PassThrough extends string>(model: M, registration: LaunchKeyRegistration<Commands, PassThrough>): LaunchInputModel<M, Commands, PassThrough>;

package/esm/util/withLaunchInput.js

@@ -0,0 +1,228 @@
+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';
+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,
+    };
+}
+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.
+ *
+ * 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) {
+    const known = new Set(Object.keys(model.properties));
+    const partitioned = model
+        .preProcessSnapshot((snap) => {
+        if (!isObject(snap)) {
+            return 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 ?? {}));
+        },
+    }))
+        // `legacyInit` names the SPELLING of the snapshot this view was opened from,
+        // and a saved one does not use it — so persisting the flag makes every later
+        // restore report nesting the snapshot it is reading does not contain,
+        // forever, since nothing clears it (`pendingLaunch` excludes the report
+        // keys, so the launch autorun never runs). `unknown` and `malformed` stay:
+        // those name content that was DISCARDED, which is still true of the saved
+        // snapshot, and the blob is the only record of it.
+        .postProcessSnapshot((snap) => {
+        const launch = snap[LAUNCH];
+        if (!isObject(launch) || !launch.legacyInit) {
+            return snap;
+        }
+        const { legacyInit, ...kept } = launch;
+        return Object.keys(kept).length
+            ? { ...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.2",
   "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",
@@ -140,14 +142,12 @@
     "./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/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",
@@ -194,7 +194,9 @@
     "./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",
@@ -235,7 +237,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,9 +256,9 @@
     "@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/icons-material": "^9.4.0",
+    "@mui/material": "^9.4.0",
+    "@mui/system": "^9.4.0",
     "@mui/x-data-grid": "^9.12.0",
     "canvas-sequencer-ts": "^3.1.3",
     "compare-versions": "^6.1.1",
@@ -267,8 +270,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.2",
+    "@jbrowse/render-core": "^5.0.0-beta.2"
   },
   "peerDependencies": {
     "react": ">=19.0.0",

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;