@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/wheelZoom.d.ts

@@ -0,0 +1,59 @@
+export declare const MAX_ZOOM_RATE_PER_MS: number;
+export declare const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+export declare function wheelZoomAccum(normalizedDeltaY: number, isCtrlZoom: boolean): number;
+export declare function getZoomNormalizer(deltaY: number): 25 | 75 | 150 | 500;
+export declare function normalizeWheelDelta(delta: number, deltaMode: number, pageHeight?: number): number;
+export declare function wheelFrameElapsedMs(now: number, lastRafTime: number | null): number;
+export declare function accumulateScroll(prev: number, deltaX: number): number;
+export declare const ZOOM_ACTIVE_WINDOW_MS = 100;
+export declare function isActivelyZooming(now: number, lastZoomTime: number | null): boolean;
+export declare function applyZoomAccum(bpPerPx: number, zoomAccum: number, elapsedMs: number): number;
+export interface WheelZoomView {
+    bpPerPx: number;
+    zoomTo: (bpPerPx: number, offset?: number) => void;
+    horizontalScroll: (delta: number) => void;
+}
+export interface WheelZoomTarget {
+    views: WheelZoomView[];
+    scrollZoom: boolean;
+    originElement: () => HTMLElement | undefined;
+}
+export interface WheelZoomControllerOptions {
+    element: HTMLElement;
+    resolveTarget: (event: WheelEvent) => WheelZoomTarget | undefined;
+    swallowUnhandled?: boolean;
+    /**
+     * Abandon the gesture once the pointer leaves `element`, rather than following
+     * the wheel events the browser keeps latching here (see trackPointerPresence).
+     *
+     * Only for an element large and stationary enough that "the pointer left" is a
+     * real exit. On a small or moving target it isn't: a zoom slides a thin svg
+     * ribbon out from under a stationary cursor, the browser fires mouseleave, and
+     * the gesture would die halfway through. So this is opt-in, not the default.
+     */
+    releaseOnPointerLeave?: boolean;
+    onEvent?: (event: WheelEvent) => void;
+}
+/**
+ * The one wheel gesture handler for linear views. Its decision matrix:
+ *
+ *   - ctrl/meta+wheel, or (scrollZoom && |dy| >= |dx|)  → zoom about the cursor
+ *   - shift+wheel while scrollZoom is on                → declined, we pass
+ *   - a horizontal delta, unless one arrives mid-zoom   → pan by dx
+ *
+ * Declining shift is what leaves a nested panel its own scroll
+ * (`usePanelVirtualScroll`) — it is not a way back to the page. Browsers turn
+ * shift+wheel into *horizontal* scrolling, so what a view declines here scrolls
+ * the page sideways or not at all. The vertical way out is spatial rather than
+ * modal: JBrowse binds this below the view's sticky header, leaving that header
+ * as a gutter the wheel still scrolls (LinearGenomeViewContainer's tracksRef).
+ *
+ * The listener is non-passive so it can preventDefault to suppress native scroll
+ * during a zoom. To pay for that it only accumulates deltas: every model write
+ * happens in one requestAnimationFrame, so a burst of events (fast trackpad,
+ * inertial scroll) collapses to a single update per frame instead of thrashing
+ * the views once per event.
+ *
+ * Returns its disposer.
+ */
+export declare function createWheelZoomController({ element, resolveTarget, swallowUnhandled, releaseOnPointerLeave, onEvent, }: WheelZoomControllerOptions): () => void;

package/esm/util/wheelZoom.js

@@ -0,0 +1,231 @@
+// Shared wheel-zoom math and event handling for linear genome views. The LGV
+// wheel handler, the breakpoint-split overlay and the synteny canvas all zoom on
+// ctrl/scroll-zoom wheel gestures and must behave identically, so the normalizer,
+// the rate limit and the whole gesture decision matrix live here —
+// createWheelZoomController below is what each of those three actually runs.
+import { transaction } from 'mobx';
+import { createFrameCoalescer } from './frameCoalescer.js';
+import { trackPointerPresence } from './pointerPresence.js';
+// max zoom delta per millisecond — equivalent to 0.2 per frame at 60fps
+export const MAX_ZOOM_RATE_PER_MS = 0.2 / 16.67;
+// Scroll-zoom (plain wheel with the scrollZoom preference on) divides by a fixed
+// amount for a smooth proportional feel, rather than the adaptive
+// getZoomNormalizer used for ctrl/pinch zoom where device deltas vary wildly.
+export const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+// The per-event contribution to the zoom accumulator, given a wheel delta
+// already normalized to pixels via normalizeWheelDelta. ctrl/pinch zoom uses the
+// adaptive normalizer; scroll-zoom uses the fixed divisor. Single source of the
+// zoom-step feel so every wheel handler (LGV, breakpoint overlay, synteny)
+// zooms identically for the same gesture.
+export function wheelZoomAccum(normalizedDeltaY, isCtrlZoom) {
+    return (normalizedDeltaY /
+        (isCtrlZoom
+            ? getZoomNormalizer(normalizedDeltaY)
+            : SCROLL_ZOOM_FACTOR_DIVISOR));
+}
+// larger wheel deltas (e.g. mouse wheel notches) divide by more so a single
+// notch produces a consistent zoom step regardless of device delta magnitude
+export function getZoomNormalizer(deltaY) {
+    const abs = Math.abs(deltaY);
+    if (abs < 6) {
+        return 25;
+    }
+    if (abs > 150) {
+        return 500;
+    }
+    if (abs > 30) {
+        return 150;
+    }
+    return 75;
+}
+// One wheel notch in line mode (deltaMode 1) is roughly this many pixels, and a
+// page (deltaMode 2) roughly WHEEL_PAGE_HEIGHT — the values Facebook's
+// normalize-wheel uses, the de-facto cross-browser convention. Pixel mode (0),
+// which trackpads and modern mice report, passes through untouched.
+const WHEEL_LINE_HEIGHT = 40;
+const WHEEL_PAGE_HEIGHT = 800;
+// Convert a WheelEvent delta from its deltaMode units to pixels. Panel-scroll
+// callers pass the viewport height as `pageHeight` so a page maps to exactly one
+// screen; the zoom path omits it and takes the default. Single normalizer for
+// both the zoom math here and the vertical-scroll handlers so a notch means the
+// same thing everywhere.
+export function normalizeWheelDelta(delta, deltaMode, pageHeight = WHEEL_PAGE_HEIGHT) {
+    return deltaMode === 1
+        ? delta * WHEEL_LINE_HEIGHT
+        : deltaMode === 2
+            ? delta * pageHeight
+            : delta;
+}
+// elapsed since the previous animation frame, clamped to 100ms and defaulting
+// to one 60fps frame when there is no prior frame (first event or post-resume)
+export function wheelFrameElapsedMs(now, lastRafTime) {
+    return Math.min(100, lastRafTime !== null ? now - lastRafTime : 16.67);
+}
+// Accumulate horizontal scroll across a frame, restarting from zero when the
+// gesture reverses direction so a flick the opposite way isn't cancelled out by
+// leftover momentum.
+export function accumulateScroll(prev, deltaX) {
+    const reversed = prev !== 0 && Math.sign(deltaX) !== Math.sign(prev);
+    return (reversed ? 0 : prev) + deltaX;
+}
+// A pinch/scroll-zoom gesture fires a continuous stream of wheel events, so we
+// treat the view as "actively zooming" until this many ms pass with no zoom
+// event. While actively zooming, callers ignore horizontal deltas: trackpads
+// emit an unintentional side-scroll mid-gesture that would otherwise pan the
+// view out from under the user.
+export const ZOOM_ACTIVE_WINDOW_MS = 100;
+// `now` and `lastZoomTime` are both wheel-event timeStamps (same clock).
+// lastZoomTime is null before any zoom has occurred.
+export function isActivelyZooming(now, lastZoomTime) {
+    return lastZoomTime !== null && now - lastZoomTime < ZOOM_ACTIVE_WINDOW_MS;
+}
+// apply an accumulated zoom amount to bpPerPx, rate-limited so a burst of wheel
+// events can't zoom faster than MAX_ZOOM_RATE_PER_MS over the frame's elapsed
+export function applyZoomAccum(bpPerPx, zoomAccum, elapsedMs) {
+    const max = MAX_ZOOM_RATE_PER_MS * elapsedMs;
+    const d = Math.max(-max, Math.min(max, zoomAccum));
+    return d > 0 ? bpPerPx * (1 + d) : bpPerPx / (1 - d);
+}
+/**
+ * The one wheel gesture handler for linear views. Its decision matrix:
+ *
+ *   - ctrl/meta+wheel, or (scrollZoom && |dy| >= |dx|)  → zoom about the cursor
+ *   - shift+wheel while scrollZoom is on                → declined, we pass
+ *   - a horizontal delta, unless one arrives mid-zoom   → pan by dx
+ *
+ * Declining shift is what leaves a nested panel its own scroll
+ * (`usePanelVirtualScroll`) — it is not a way back to the page. Browsers turn
+ * shift+wheel into *horizontal* scrolling, so what a view declines here scrolls
+ * the page sideways or not at all. The vertical way out is spatial rather than
+ * modal: JBrowse binds this below the view's sticky header, leaving that header
+ * as a gutter the wheel still scrolls (LinearGenomeViewContainer's tracksRef).
+ *
+ * The listener is non-passive so it can preventDefault to suppress native scroll
+ * during a zoom. To pay for that it only accumulates deltas: every model write
+ * happens in one requestAnimationFrame, so a burst of events (fast trackpad,
+ * inertial scroll) collapses to a single update per frame instead of thrashing
+ * the views once per event.
+ *
+ * Returns its disposer.
+ */
+export function createWheelZoomController({ element, resolveTarget, swallowUnhandled = false, releaseOnPointerLeave = false, onEvent, }) {
+    const frame = createFrameCoalescer();
+    const s = {
+        scrollDelta: 0,
+        zoomAccum: 0,
+        target: undefined,
+        lastClientX: 0,
+        originLeft: undefined,
+        lastRafTime: null,
+        lastZoomTime: null,
+        lastEventTime: null,
+        warnedNonCancelable: false,
+    };
+    // see releaseOnPointerLeave: drop any in-flight accumulation and stop consuming
+    // latched wheel events, so a continued gesture pans/zooms nothing and chains to
+    // the page instead of staying stuck to this element
+    const presence = releaseOnPointerLeave
+        ? trackPointerPresence(element, () => {
+            s.scrollDelta = 0;
+            s.zoomAccum = 0;
+            s.originLeft = undefined;
+        })
+        : undefined;
+    function flush(now) {
+        const elapsed = wheelFrameElapsedMs(now, s.lastRafTime);
+        s.lastRafTime = now;
+        const { target } = s;
+        if (target) {
+            const origin = target.originElement();
+            if (s.zoomAccum !== 0 && origin && s.originLeft === undefined) {
+                s.originLeft = origin.getBoundingClientRect().left;
+            }
+            const originLeft = s.originLeft;
+            transaction(() => {
+                if (s.zoomAccum !== 0 && originLeft !== undefined) {
+                    const offset = s.lastClientX - originLeft;
+                    for (const view of target.views) {
+                        view.zoomTo(applyZoomAccum(view.bpPerPx, s.zoomAccum, elapsed), offset);
+                    }
+                }
+                if (s.scrollDelta !== 0) {
+                    for (const view of target.views) {
+                        view.horizontalScroll(s.scrollDelta);
+                    }
+                }
+            });
+        }
+        s.zoomAccum = 0;
+        s.scrollDelta = 0;
+    }
+    function onWheel(event) {
+        onEvent?.(event);
+        const gated = presence !== undefined && !presence.isOver;
+        const target = gated ? undefined : resolveTarget(event);
+        if (target && !(event.shiftKey && target.scrollZoom)) {
+            // a gap longer than the frame-elapsed clamp means this event starts a new
+            // gesture, so the previous frame time is meaningless — including when it
+            // predates a spell in a backgrounded tab, where a huge elapsed would
+            // otherwise lift the zoom rate limit on the first frame back
+            if (!isActivelyZooming(event.timeStamp, s.lastEventTime)) {
+                s.lastRafTime = null;
+                s.originLeft = undefined;
+            }
+            s.lastEventTime = event.timeStamp;
+            s.target = target;
+            const deltaY = normalizeWheelDelta(event.deltaY, event.deltaMode);
+            const deltaX = normalizeWheelDelta(event.deltaX, event.deltaMode);
+            const isCtrlZoom = event.ctrlKey || event.metaKey;
+            const isZoom = isCtrlZoom ||
+                (target.scrollZoom && Math.abs(deltaY) >= Math.abs(deltaX));
+            if (isZoom) {
+                // warn once per latched run, not once per event — a non-cancelable
+                // sequence fires ~100 events/sec and console.warn is not free
+                if (event.cancelable) {
+                    s.warnedNonCancelable = false;
+                }
+                else if (!s.warnedNonCancelable) {
+                    s.warnedNonCancelable = true;
+                    console.warn('[wheelZoom] wheel event not cancelable — scroll sequence already in progress');
+                }
+                event.preventDefault();
+                s.zoomAccum += wheelZoomAccum(deltaY, isCtrlZoom);
+                s.lastClientX = event.clientX;
+                s.lastZoomTime = event.timeStamp;
+                // drop any side-scroll accumulated earlier this frame — we're zooming,
+                // and a deltaX that arrived just before the zoom is part of the same
+                // noisy gesture
+                s.scrollDelta = 0;
+            }
+            else if (isActivelyZooming(event.timeStamp, s.lastZoomTime)) {
+                // ignore stray horizontal deltas that arrive mid-zoom — trackpads emit
+                // an unintentional side-scroll during a pinch/scroll-zoom gesture that
+                // would otherwise pan the view away from where the user is zooming.
+                // preventDefault anyway so the page itself doesn't scroll instead.
+                event.preventDefault();
+            }
+            else {
+                // With scrollZoom on, swallow the gesture even though it fell outside
+                // the zoom threshold: without this, a diagonal trackpad gesture whose
+                // |deltaX| slightly exceeds |deltaY| slips through and scrolls the page
+                // (shift+wheel above is the deliberate exception). With scrollZoom
+                // off, only swallow what we are about to pan with, so a plain vertical
+                // wheel isn't silently eaten.
+                if (swallowUnhandled ||
+                    target.scrollZoom ||
+                    Math.abs(deltaX) > Math.abs(2 * deltaY)) {
+                    event.preventDefault();
+                }
+                s.scrollDelta = accumulateScroll(s.scrollDelta, deltaX);
+            }
+            frame.schedule(flush);
+        }
+    }
+    element.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+        element.removeEventListener('wheel', onWheel);
+        presence?.dispose();
+        // so a flush can't fire against a detached view
+        frame.cancel();
+    };
+}

package/esm/util/whenViewSettled.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * 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"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * 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 (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

@@ -0,0 +1,41 @@
+import { when } from 'mobx';
+/**
+ * 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
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * 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"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * 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 (and consumed any launch), false if it
+ * settled on an error
+ */
+export async function whenViewSettled(view) {
+    const ready = () => view.initialized && view.pendingLaunch === undefined;
+    await when(() => ready() || !!view.error);
+    return ready();
+}

package/esm/util/withFeatureDetails.d.ts

@@ -0,0 +1,34 @@
+import type { Feature } from './simpleFeature.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export declare function withFeatureDetails(self: IStateTreeNode, fetch: () => Promise<Feature | undefined>, onFeat: (feat: Feature) => void, onMiss?: () => void): Promise<void>;

package/esm/util/withFeatureDetails.js

@@ -0,0 +1,59 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { notifyFeatureDetailsMiss } from './openFeatureWidget.js';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export async function withFeatureDetails(self, fetch, onFeat, onMiss = () => {
+    notifyFeatureDetailsMiss(self);
+}) {
+    try {
+        const feature = await fetch();
+        if (!isAlive(self)) {
+            return;
+        }
+        if (feature) {
+            onFeat(feature);
+        }
+        else {
+            onMiss();
+        }
+    }
+    catch (e) {
+        // Logged whatever happened, and only toasted while the display is still
+        // there: `getSession` throws on a detached node, and a message naming a
+        // track the user has already closed is noise they cannot act on.
+        console.error(e);
+        if (isAlive(self)) {
+            getNotificationSink(self).notifyError(`${e}`, e);
+        }
+    }
+}

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