@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/addTrackFromWidget.d.ts

@@ -0,0 +1,94 @@
+import type { AssemblyNameResolver } from './tracks.ts';
+import type { AbstractSessionModel, SessionWithPublishTrackConf, TrackContainer } from './types/index.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Whether the target track list currently displays any of the track's
+ * assemblies, i.e. the track can be shown there after adding it.
+ *
+ * Both sides resolve through the aliases, because the two names meeting here
+ * come from different places: the container holds whatever the session opened
+ * the view on, and the config holds whatever its author wrote. `===` read a
+ * track configured against `hg38` as undisplayable in a view on `GRCh38`, so
+ * the add landed and nothing appeared, under a snackbar naming the assembly the
+ * user was looking at as one this view does not have open.
+ */
+export declare function containerDisplaysAssembly(container: {
+    assemblyNames?: readonly string[];
+} | undefined, assemblyNames: readonly (string | undefined)[] | undefined, assemblyManager: AssemblyNameResolver): boolean;
+/** the slice of the add-track widget every workflow's submit path writes to */
+export interface AddTrackWidgetSelf extends IStateTreeNode {
+    /**
+     * Where a submitted track opens: the view, or one track list within it when
+     * the widget was opened from a synteny level's track selector. Not the same
+     * as `view` — a workflow reaching past this for `view` adds the track to the
+     * wrong list.
+     */
+    trackContainer: TrackContainer | undefined;
+    clearData: () => void;
+}
+/**
+ * The slice of the add-track widget a whole workflow gets: the submit path
+ * above plus the assembly it writes into. Structural rather than the widget's
+ * own model type, so a plugin contributing a workflow doesn't take a package
+ * dependency on the plugin that owns the widget.
+ */
+export interface AddTrackWorkflowModel extends AddTrackWidgetSelf {
+    assembly: string | undefined;
+    setAssembly: (arg: string) => void;
+}
+/**
+ * Reset the form and dismiss the widget after a successful add.
+ *
+ * Only ever on an add that landed something: finishing throws away what the
+ * user assembled, so doing it when every config was rejected buries the
+ * snackbars explaining why behind an empty form with nothing to retry from.
+ */
+export declare function finishAddTrack(model: AddTrackWidgetSelf, session: AbstractSessionModel): void;
+/**
+ * Add one track config from an add-track workflow, reveal it, and dismiss the
+ * widget — the tail every workflow shares, so all of them decide "show vs.
+ * warn vs. dismiss" the same way.
+ *
+ * Three things a workflow doing this by hand has got wrong:
+ *
+ * - It shows the track in `model.view`, which is the wrong list when the widget
+ *   was opened from a synteny level's track selector. `trackContainer` is the
+ *   target.
+ * - It shows a track whose assembly the container doesn't display, which is
+ *   silently nothing on screen. Say so instead.
+ * - It dismisses the widget even when `publishTrackConf` rejected the config,
+ *   wiping the form behind the error snackbar.
+ *
+ * **A track on an assembly the view synthesized takes neither destination.** The
+ * widget reads its assembly off the containing view and offers no choice of one
+ * outside it (`setAssembly` lists `session.assemblyNames`, which excludes the
+ * temporary ones), so a user opening a file in a read-vs-ref panel arrives here
+ * naming an assembly that goes back when that view closes — and a session list
+ * would keep the config, once per file, in the snapshot they save and share.
+ * That is ADR-084's leak reached through the widget rather than through a
+ * launcher, so it takes ADR-084's answer: the config rides on the track as
+ * `showTrack`'s `inlineConf`, works for the life of the view, and goes out with
+ * it. The container is the one this assembly came from, so it displays it.
+ *
+ * Returns the added config, or undefined when `publishTrackConf` rejected it — it
+ * has already surfaced its own error, and a second, vaguer snackbar on top of
+ * that helps nobody.
+ */
+export declare function addTrackFromWidget({ model, session, conf, }: {
+    model: AddTrackWidgetSelf;
+    session: AbstractSessionModel;
+    conf: Parameters<SessionWithPublishTrackConf['publishTrackConf']>[0] & {
+        trackId: string;
+        name?: string;
+        assemblyNames?: (string | undefined)[];
+    };
+}): (import("@jbrowse/mobx-state-tree").$EmptyObjectBrand & Partial<{
+    [x: string]: any;
+}> & {
+    trackId: string;
+    name?: string;
+    assemblyNames?: (string | undefined)[];
+}) | (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
+    setSubschema(slotName: string, data: Record<string, unknown>): any;
+    setSlot(slotName: string, value: unknown): void;
+} & IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>) | undefined;

package/esm/util/addTrackFromWidget.js

@@ -0,0 +1,90 @@
+import { namesTemporaryAssembly } from './temporaryAssembly.js';
+import { isSameAssemblyName } from './tracks.js';
+import { isSessionModelWithWidgets, isSessionWithPublishTrackConf, } from './types/index.js';
+/**
+ * Whether the target track list currently displays any of the track's
+ * assemblies, i.e. the track can be shown there after adding it.
+ *
+ * Both sides resolve through the aliases, because the two names meeting here
+ * come from different places: the container holds whatever the session opened
+ * the view on, and the config holds whatever its author wrote. `===` read a
+ * track configured against `hg38` as undisplayable in a view on `GRCh38`, so
+ * the add landed and nothing appeared, under a snackbar naming the assembly the
+ * user was looking at as one this view does not have open.
+ */
+export function containerDisplaysAssembly(container, assemblyNames, assemblyManager) {
+    return !!container?.assemblyNames?.some(a => assemblyNames?.some(b => isSameAssemblyName(a, b, assemblyManager)));
+}
+/**
+ * Reset the form and dismiss the widget after a successful add.
+ *
+ * Only ever on an add that landed something: finishing throws away what the
+ * user assembled, so doing it when every config was rejected buries the
+ * snackbars explaining why behind an empty form with nothing to retry from.
+ */
+export function finishAddTrack(model, session) {
+    model.clearData();
+    if (isSessionModelWithWidgets(session)) {
+        session.hideWidget(model);
+    }
+}
+/**
+ * Add one track config from an add-track workflow, reveal it, and dismiss the
+ * widget — the tail every workflow shares, so all of them decide "show vs.
+ * warn vs. dismiss" the same way.
+ *
+ * Three things a workflow doing this by hand has got wrong:
+ *
+ * - It shows the track in `model.view`, which is the wrong list when the widget
+ *   was opened from a synteny level's track selector. `trackContainer` is the
+ *   target.
+ * - It shows a track whose assembly the container doesn't display, which is
+ *   silently nothing on screen. Say so instead.
+ * - It dismisses the widget even when `publishTrackConf` rejected the config,
+ *   wiping the form behind the error snackbar.
+ *
+ * **A track on an assembly the view synthesized takes neither destination.** The
+ * widget reads its assembly off the containing view and offers no choice of one
+ * outside it (`setAssembly` lists `session.assemblyNames`, which excludes the
+ * temporary ones), so a user opening a file in a read-vs-ref panel arrives here
+ * naming an assembly that goes back when that view closes — and a session list
+ * would keep the config, once per file, in the snapshot they save and share.
+ * That is ADR-084's leak reached through the widget rather than through a
+ * launcher, so it takes ADR-084's answer: the config rides on the track as
+ * `showTrack`'s `inlineConf`, works for the life of the view, and goes out with
+ * it. The container is the one this assembly came from, so it displays it.
+ *
+ * Returns the added config, or undefined when `publishTrackConf` rejected it — it
+ * has already surfaced its own error, and a second, vaguer snackbar on top of
+ * that helps nobody.
+ */
+export function addTrackFromWidget({ model, session, conf, }) {
+    if (!isSessionWithPublishTrackConf(session)) {
+        throw new Error("Can't add tracks to this session");
+    }
+    const { trackContainer } = model;
+    if (namesTemporaryAssembly(session, conf)) {
+        if (!trackContainer) {
+            session.notify(`Could not add "${conf.name ?? conf.trackId}": the view it was being added to has closed, and it uses an assembly that only that view had.`, 'warning');
+            return undefined;
+        }
+        trackContainer.showTrack(conf.trackId, {}, {}, conf);
+        finishAddTrack(model, session);
+        return conf;
+    }
+    const added = session.publishTrackConf(conf);
+    if (!added) {
+        return undefined;
+    }
+    if (containerDisplaysAssembly(trackContainer, conf.assemblyNames, session.assemblyManager)) {
+        trackContainer?.showTrack(conf.trackId);
+    }
+    else {
+        const assemblies = conf.assemblyNames?.filter(a => !!a) ?? [];
+        session.notify(`Added track "${conf.name ?? conf.trackId}" to the session, but it was not displayed because it uses ${assemblies.length
+            ? `assembly "${assemblies.join('", "')}"`
+            : 'an assembly'}, which is not open in this view. Open a view for that assembly and use its track selector to display it.`, 'warning');
+    }
+    finishAddTrack(model, session);
+    return added;
+}

package/esm/util/analytics.d.ts

@@ -1,3 +1,32 @@
-export declare function writeAWSAnalytics(rootModel: any, initialTimeStamp: number, sessionQuery?: string | null): Promise<void>;
-export declare function writeGAAnalytics(rootModel: any, initialTimestamp: number): Promise<void>;
-export declare function doAnalytics(rootModel: any, initialTimestamp: number, initialSessionQuery: string | null | undefined): void;
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+declare global {
+    interface Window {
+        ga?: (...args: unknown[]) => void;
+    }
+}
+type TrackConfig = AnyConfigurationModel & {
+    type: string;
+};
+interface AnalyticsRootModel {
+    jbrowse: {
+        tracks: TrackConfig[];
+        assemblies: unknown[];
+        plugins?: {
+            name?: string;
+        }[];
+    };
+    session?: {
+        sessionTracks: TrackConfig[];
+        views: unknown[];
+    };
+    version: string;
+}
+type AnalyticsRootModelWithConfig = AnalyticsRootModel & {
+    jbrowse: {
+        configuration: AnyConfigurationModel;
+    };
+};
+export declare function writeAWSAnalytics(rootModel: AnalyticsRootModel, initialTimestamp: number, sessionQuery?: string | null): Promise<void>;
+export declare function writeGAAnalytics(rootModel: AnalyticsRootModel, initialTimestamp: number): Promise<void>;
+export declare function doAnalytics(rootModel: AnalyticsRootModelWithConfig | undefined, initialTimestamp: number, initialSessionQuery: string | null | undefined): void;
+export {};

package/esm/util/analytics.js

@@ -1,80 +1,133 @@
-import { readConfObject } from "../configuration/index.js";
-import { isElectron } from "../util/index.js";
-export async function writeAWSAnalytics(rootModel, initialTimeStamp, sessionQuery) {
+import { effectiveRenderer, getGraphicsCapabilities, } from '@jbrowse/render-core/graphicsCapabilities';
+import { readConfObject } from '../configuration/index.js';
+import { isElectron, rIC } from '../util/index.js';
+// Both writers are fire-and-forget from several call sites, so they swallow
+// their own failures rather than rejecting: a floating rejected promise trips
+// the webpack-dev-server overlay (it listens for unhandledrejection), and an
+// analytics ping is never worth interrupting a session for.
+export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuery) {
     try {
         const url = 'https://analytics.jbrowse.org/api/v1';
-        const multiAssemblyTracks = rootModel.jbrowse.tracks.filter((track) => (readConfObject(track, 'assemblyNames') || []).length > 1).length;
-        const savedSessionCount = Object.keys(localStorage).filter(name => name.includes('localSaved-')).length;
+        const multiAssemblyTracks = rootModel.jbrowse.tracks.filter(track => readConfObject(track, 'assemblyNames').length > 1).length;
+        // which rendering backend is actually drawing (WebGPU/WebGL2/Canvas2D) —
+        // capabilities *and* any page-wide pin, so a session that fell back to
+        // Canvas2D is counted as Canvas2D rather than as what the hardware could
+        // have done. Reporting the capability answer here is what made "how many
+        // users end up on Canvas2D" unanswerable.
+        const capabilities = await getGraphicsCapabilities();
+        const renderer = effectiveRenderer(capabilities);
+        // The coarse bit only. `glRenderer` names the exact driver and stays local
+        // to the stack-trace dialog, the same line vendor/architecture hold — this
+        // says whether a WebGL2 user is on a rasterizer, which is the population
+        // that pays ~25x Canvas2D on the main thread and the number that decides
+        // whether the ladder should route around it. 'unknown' where nothing probed
+        // or the browser withholds the extension, which must not read as 'false'.
+        const softwareRendering = capabilities.softwareWebgl ?? 'unknown';
         const { jbrowse: config, session, version: ver } = rootModel;
         const { tracks, assemblies, plugins } = config;
+        // stats to be recorded in db
         const stats = {
             ver,
-            'plugins-count': plugins?.length || 0,
-            'plugin-names': plugins?.map((p) => p.name).join(','),
+            'plugins-count': plugins?.length ?? 0,
+            'plugin-names': plugins?.map(p => p.name).join(','),
             'assemblies-count': assemblies.length,
             'tracks-count': tracks.length,
-            'session-tracks-count': session?.sessionTracks.length || 0,
-            'open-views': session?.views.length || 0,
+            'session-tracks-count': session?.sessionTracks.length ?? 0,
+            'open-views': session?.views.length ?? 0,
             'synteny-tracks-count': multiAssemblyTracks,
-            'saved-sessions-count': savedSessionCount,
-            'existing-session-param-type': sessionQuery?.split('-')[0] || 'none',
+            // No `saved-sessions-count`: it counted localStorage keys matching
+            // `localSaved-`, a format nothing has written since autosaved sessions
+            // moved to IndexedDB (`sessionsDB`), so it reported 0 for every user. The
+            // live count is `savedSessionMetadata`, which is web-only and populated by
+            // an async open — reporting it here would race the boot rather than
+            // measure anything, so the field is gone instead of re-sourced.
+            // field if existing session param in query before autogenerated param
+            'existing-session-param-type': sessionQuery?.split('-', 1)[0] || 'none',
+            // screen geometry
             'scn-h': window.screen.height,
             'scn-w': window.screen.width,
+            // window geometry
             'win-h': window.innerHeight,
             'win-w': window.innerWidth,
+            dpr: window.devicePixelRatio,
             electron: isElectron,
-            loadTime: (Date.now() - initialTimeStamp) / 1000,
+            renderer,
+            'software-rendering': softwareRendering,
+            loadTime: (Date.now() - initialTimestamp) / 1000,
             jb2: true,
         };
-        tracks.forEach((track) => {
+        // tallies get processed in the lambda, keyed as e.g. track-types-FeatureTrack
+        const trackTypeCounts = {};
+        for (const track of tracks) {
             const key = `track-types-${track.type}`;
-            stats[key] = stats[key] + 1 || 1;
-        });
-        session?.sessionTracks.forEach((track) => {
+            trackTypeCounts[key] = (trackTypeCounts[key] ?? 0) + 1;
+        }
+        const sessionTrackTypeCounts = {};
+        for (const track of session?.sessionTracks ?? []) {
             const key = `sessionTrack-types-${track.type}`;
-            stats[key] = stats[key] + 1 || 1;
-        });
-        const qs = Object.keys(stats)
-            .map(key => `${key}=${stats[key]}`)
-            .join('&');
+            sessionTrackTypeCounts[key] = (sessionTrackTypeCounts[key] ?? 0) + 1;
+        }
+        Object.assign(stats, trackTypeCounts, sessionTrackTypeCounts);
+        const qs = new URLSearchParams(Object.entries(stats).map(([key, value]) => [key, String(value)])).toString();
         await fetch(`${url}?${qs}`);
     }
     catch (e) {
-        console.error('Failed to write analytics to AWS.', e);
+        console.warn('Failed to write analytics to AWS.', e);
     }
 }
 export async function writeGAAnalytics(rootModel, initialTimestamp) {
-    const jbrowseUser = 'UA-7115575-5';
-    const stats = {
-        'tracks-count': rootModel.jbrowse.tracks.length,
-        ver: rootModel.version,
-        electron: isElectron,
-        loadTime: Date.now() - initialTimestamp,
-        pluginNames: rootModel.jbrowse.plugins?.map((plugin) => plugin.name) || '',
-    };
-    let analyticsScript = "(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){";
-    analyticsScript +=
-        '(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),';
-    analyticsScript +=
-        'm=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)';
-    analyticsScript +=
-        "})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');";
-    analyticsScript += `ga('create', '${jbrowseUser}', 'auto', 'jbrowseTracker');`;
-    const gaData = {};
-    const googleDimensions = 'tracks-count ver electron loadTime pluginNames';
-    for (const [index, key] of googleDimensions.split(/\s+/).entries()) {
-        gaData[`dimension${index + 1}`] = stats[key];
+    try {
+        const jbrowseUser = 'UA-7115575-5';
+        const loadTime = Date.now() - initialTimestamp;
+        // custom dimension/metric indices are wired up on the GA property side, so
+        // this order (tracks-count, ver, electron, loadTime, pluginNames) must stay
+        // dimension1..5
+        const gaData = {
+            dimension1: rootModel.jbrowse.tracks.length, // this is all possible tracks
+            dimension2: rootModel.version,
+            dimension3: isElectron,
+            dimension4: loadTime,
+            dimension5: rootModel.jbrowse.plugins?.map(p => p.name).join(',') ?? '',
+            metric1: Math.round(loadTime),
+        };
+        // Plugin names come from the loaded config and are not trusted content (a
+        // config can be loaded from an arbitrary URL). Only this static bootstrap,
+        // with no interpolated data, is ever parsed as script source; gaData is
+        // handed to ga() as a real JS value afterward so untrusted strings can never
+        // break out of the <script> tag the way interpolating them into it would.
+        const analyticsBootstrap = "(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){" +
+            '(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),' +
+            'm=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)' +
+            "})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');";
+        const analyticsScriptNode = document.createElement('script');
+        analyticsScriptNode.innerHTML = analyticsBootstrap;
+        document.head.append(analyticsScriptNode);
+        window.ga?.('create', jbrowseUser, 'auto', 'jbrowseTracker');
+        window.ga?.('jbrowseTracker.send', 'pageview', gaData);
+    }
+    catch (e) {
+        console.warn('Failed to write analytics to GA.', e);
     }
-    gaData.metric1 = Math.round(stats.loadTime);
-    analyticsScript += `ga('jbrowseTracker.send', 'pageview',${JSON.stringify(gaData)});`;
-    const analyticsScriptNode = document.createElement('script');
-    analyticsScriptNode.innerHTML = analyticsScript;
-    document.getElementsByTagName('head')[0].append(analyticsScriptNode);
 }
+// One pageview per page load, not per pluginManager. jbrowse-web rebuilds the
+// whole pluginManager (and rootModel) whenever plugins change, and StrictMode
+// builds it twice on mount — without this guard each rebuild re-pings AWS and
+// appends another Google Analytics <script> to <head>, inflating pageviews and
+// growing the document on every plugin install.
+let analyticsSent = false;
 export function doAnalytics(rootModel, initialTimestamp, initialSessionQuery) {
     if (rootModel &&
+        !analyticsSent &&
         !readConfObject(rootModel.jbrowse.configuration, 'disableAnalytics')) {
-        writeAWSAnalytics(rootModel, initialTimestamp, initialSessionQuery);
-        writeGAAnalytics(rootModel, initialTimestamp);
+        analyticsSent = true;
+        // Defer off the critical load path: writeGAAnalytics injects a third-party
+        // Google Analytics script and writeAWSAnalytics probes graphics
+        // capabilities, together ~hundreds of ms of main-thread work at startup.
+        // loadTime is still measured from initialTimestamp, so the reported metric
+        // is unaffected by running these when the browser is idle.
+        rIC(() => {
+            void writeAWSAnalytics(rootModel, initialTimestamp, initialSessionQuery);
+            void writeGAAnalytics(rootModel, initialTimestamp);
+        });
     }
 }

package/esm/util/animationAllowed.d.ts

@@ -0,0 +1,17 @@
+import type { AnimationMode } from './types/index.ts';
+/**
+ * Whether a motion may play at all, before anything about what would move is
+ * consulted: a frame clock has to exist, and the resolved animation mode has to
+ * allow motion — 'enabled' always does, 'disabled' never does, and 'system'
+ * honors the OS prefers-reduced-motion setting, so reduced-motion users get
+ * instant snaps unless they explicitly opt in. The mode comes from the session
+ * preference (`configuration.preferences.animationMode` + user override), which
+ * is `getSession(self).animationMode`.
+ *
+ * In core rather than beside either caller because the two that ask are a
+ * feature-layout morph in the canvas plugin and a viewport flight in the LGV,
+ * and a second copy of this check is a second answer to "does this user want
+ * motion" — the one a reduced-motion reader notices when only half the app
+ * honors it.
+ */
+export declare function animationAllowed(mode: AnimationMode): boolean;

package/esm/util/animationAllowed.js

@@ -0,0 +1,22 @@
+/**
+ * Whether a motion may play at all, before anything about what would move is
+ * consulted: a frame clock has to exist, and the resolved animation mode has to
+ * allow motion — 'enabled' always does, 'disabled' never does, and 'system'
+ * honors the OS prefers-reduced-motion setting, so reduced-motion users get
+ * instant snaps unless they explicitly opt in. The mode comes from the session
+ * preference (`configuration.preferences.animationMode` + user override), which
+ * is `getSession(self).animationMode`.
+ *
+ * In core rather than beside either caller because the two that ask are a
+ * feature-layout morph in the canvas plugin and a viewport flight in the LGV,
+ * and a second copy of this check is a second answer to "does this user want
+ * motion" — the one a reduced-motion reader notices when only half the app
+ * honors it.
+ */
+export function animationAllowed(mode) {
+    const hasFrameClock = typeof requestAnimationFrame === 'function';
+    const prefersReduced = typeof matchMedia === 'function' &&
+        matchMedia('(prefers-reduced-motion: reduce)').matches;
+    return (hasFrameClock &&
+        (mode === 'enabled' || (mode === 'system' && !prefersReduced)));
+}

package/esm/util/applyInitSettings.d.ts

@@ -0,0 +1,79 @@
+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

@@ -0,0 +1,91 @@
+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(', ')}`);
+    }
+}

package/esm/util/applyRowResizeWheel.d.ts

@@ -0,0 +1,10 @@
+interface RowResizeTarget {
+    effectiveRowHeight: number;
+    scrollTop: number;
+    nrow: number;
+    viewportHeight: number;
+    setRowHeight: (n: number) => void;
+    setScrollTop: (n: number) => void;
+}
+export declare function applyRowResizeWheel(e: WheelEvent, el: HTMLElement, model: RowResizeTarget): void;
+export {};