@jbrowse/product-core 4.3.0 → 5.0.0-beta.2

package/esm/Session/shareableSnapshot.js

@@ -0,0 +1,196 @@
+import { getConf, getDisplayTypeDefaultChanges, } from '@jbrowse/core/configuration';
+import { getContainingTrack, mergeTrackConfig, openPromotableDisplays, } from '@jbrowse/core/util';
+import { getSnapshot } from '@jbrowse/mobx-state-tree';
+import { asArray, isRecord } from '../snapshotUtils.js';
+/**
+ * The session snapshot to hand to anyone else — a share link, an exported
+ * `session.json`, a desktop→web export. Snapshotting and baking are one call so
+ * the pair can't be split: a bare `getSnapshot(session)` is never a correct
+ * outgoing snapshot (see `bakeSessionCascades`), and three of the four
+ * boundaries were spelling the two steps out identically.
+ *
+ * The fourth (desktop `ExportToWebDialog`) bakes a *transformed* snapshot from
+ * `planWebExport`, so it calls `bakeSessionCascades` directly.
+ */
+export function getShareableSessionSnapshot(session) {
+    return bakeSessionCascades(session, getSnapshot(session));
+}
+/**
+ * Everything an outgoing snapshot has to resolve because the live session
+ * resolves it at read time against state that is staying behind.
+ *
+ * Two such cascades, and they have nothing to do with each other — promoted
+ * display-type defaults are per-track rendering, workspaces intent is the
+ * session's layout mode. What they share is only this: both live partly in the
+ * sender's own browser, so a raw `getSnapshot` records neither, and the
+ * recipient silently resolves their own.
+ *
+ * They get one entry point rather than a call each because the failure of a
+ * boundary that performs half of them is invisible at that boundary — the
+ * export succeeds, and what is missing only shows up on someone else's screen.
+ * Adding a third cascade should mean editing this function, not auditing four
+ * call sites.
+ */
+export function bakeSessionCascades(session, snapshot) {
+    const snap = bakePromotedDefaultsIntoSnapshot(session, snapshot);
+    bakeWorkspacesIntent(session, snap);
+    return snap;
+}
+/**
+ * The workspaces cascade: session property -> user preference -> admin
+ * `configuration.preferences.useWorkspaces`, of which only the first is in the
+ * snapshot.
+ *
+ * So a sender whose workspace is on because *their admin turned it on* exports
+ * a fully arranged `layout` with no statement that it is a workspace at all,
+ * and a recipient resolving their own cascade to false renders the classic
+ * stack: the arrangement arrives intact and invisible, with nothing to say it
+ * was dropped.
+ *
+ * Only the on case is baked. At `false` there is no arrangement to carry, so
+ * stamping it would be a sender with nothing to say overriding a recipient who
+ * prefers workspaces — the same line the promoted-default bake draws at a slot
+ * the sender was viewing at its base value.
+ *
+ * The paths that build a layout through an explicit user intent already set the
+ * property themselves (`setUseWorkspacesPreference`, ViewMenu's move-view-out,
+ * a spec `layout`), which is exactly what hides this: every arrangement made by
+ * a *drag* — split a cell, drag a tab into it, open a new tab — goes through
+ * `WorkspaceLayoutMixin` alone, which owns the tree and knows nothing about the
+ * preference.
+ *
+ * `effectiveUseWorkspaces` is read behind an `in` guard because
+ * `AbstractSessionModel` cannot name it (it lives on MultipleViewsSessionMixin,
+ * one layer up), so renaming that getter silently stops the bake rather than
+ * failing to compile — the hazard app-core/src/WorkspaceLayout/CLAUDE.md describes for
+ * `setPendingMove`. jbrowse-web's `sessionModel/exportLayout.test.ts` is the
+ * canary, since the bake needs a real session to have a cascade at all.
+ */
+function bakeWorkspacesIntent(session, snap) {
+    if (snap.useWorkspaces === undefined &&
+        'effectiveUseWorkspaces' in session &&
+        session.effectiveUseWorkspaces ===
+            true) {
+        snap.useWorkspaces = true;
+    }
+}
+/**
+ * `getComputedStyle` for the promotable-default cascade.
+ *
+ * A track that "follows" a session-wide promoted display-type default holds no
+ * value of its own — its rendered value is resolved at read time from the
+ * promoted display-type defaults in `preferencesOverrides`, which are personal,
+ * localStorage-backed, and deliberately never serialized into a shared session.
+ * So a raw `getSnapshot(session)` records a track as at-default even when the
+ * sender is looking at a promoted value, and the recipient (who lacks the sender's
+ * preferences) sees something different. This flattens the live cascade into a
+ * self-contained snapshot:
+ *
+ * Every slot an open display *inherits* from a promoted default (i.e.
+ * `getDisplayTypeDefaultChanges` — non-customized, differs from base) is baked
+ * into that track's config layer: its own config for a user-added or connection
+ * track, else a `trackConfigDeltas` entry against the admin base (see
+ * `ownTrackConfig`). So the concrete value travels with the document, and
+ * because it lands in the track's config the recipient reads it as *customized*
+ * — a customized value is the top of the cascade, so their own promoted defaults
+ * never get consulted for it.
+ *
+ * **What this deliberately does not cover**, and the reason there is no flag
+ * here: a slot the sender was viewing at its *base* value. Nothing is baked for
+ * it (the value equals base, and `stripDefault` drops it from the snapshot
+ * regardless), so a recipient who has promoted something else resolves it from
+ * their own cascade and sees their value. There is no value that can express "I
+ * deliberately saw the default" — at-base and unset are byte-identical once
+ * stripped. That case used to be covered by stamping a per-display
+ * `ignorePromotedDefaults` on every open display, which cost a second
+ * shape-aware walk that had to stay in step with `openPromotableDisplays` by
+ * hand, and permanently detached received tracks from the recipient's own pins
+ * until they clicked "use this default" on each one. A promoted default is
+ * personal and local — the same as the theme a session is viewed in, which this
+ * function has never baked either.
+ *
+ * The live session is untouched; a modified deep copy of `snapshot` is returned.
+ * Tracks the sender never opened carry no display state to resolve, so they're
+ * left to pick up the recipient's defaults when opened — matching "export the
+ * actual state of the (open) tracks".
+ *
+ * Reach is `openPromotableDisplays` — literally the same walk the cascade's own
+ * "apply to open tracks" uses, so the two can't drift. It recurses into a
+ * composite view's `views` array (breakpoint-split, the linear-comparative /
+ * synteny family), which holds child views rather than tracks of its own —
+ * `LGVSyntenyDisplay` is only reachable that way, and before the recursion a
+ * shared session containing one rendered differently for the recipient.
+ */
+export function bakePromotedDefaultsIntoSnapshot(session, snapshot) {
+    const snap = structuredClone(snapshot);
+    // `openPromotableDisplays` is the one walk that decides reach — shared with
+    // the cascade's own "apply to open tracks", so the set this bakes and the set
+    // that acts on a promoted default can't drift
+    for (const display of openPromotableDisplays(session)) {
+        const changes = getDisplayTypeDefaultChanges(display);
+        if (changes.length > 0) {
+            bakeValues(snap, {
+                trackId: getConf(getContainingTrack(display), 'trackId'),
+                displayId: getConf(display, 'displayId'),
+                displayType: display.type,
+                values: Object.fromEntries(changes.map(c => [c.path[0], c.to])),
+            });
+        }
+    }
+    return snap;
+}
+// The track's own full config in the snapshot, when it has one: a user-added
+// track's `sessionTracks` entry, or an opened connection track's persisted
+// `connectionTrackConfigs` config. Everything else is an admin-base track,
+// which carries only a delta.
+//
+// The connection case is not optional. `trackConfigDeltas` is merged over
+// `jbrowse.tracks` alone, so a delta written for a connection track resolves
+// nowhere — the recipient would render the base value, which is the exact
+// failure the bake exists to prevent. `updateTrackConfiguration` splits on the
+// same line.
+function ownTrackConfig(snap, trackId) {
+    const sessionTrack = asArray(snap.sessionTracks).find(t => isRecord(t) && t.trackId === trackId);
+    const connectionEntry = isRecord(snap.connectionTrackConfigs)
+        ? snap.connectionTrackConfigs[trackId]
+        : undefined;
+    return isRecord(sessionTrack)
+        ? sessionTrack
+        : isRecord(connectionEntry) && isRecord(connectionEntry.config)
+            ? connectionEntry.config
+            : undefined;
+}
+// Bake one display's inherited values into the config layer: into the matching
+// display of the track's own config when it has one, else merged as a
+// `trackConfigDeltas` entry against the admin base.
+function bakeValues(snap, bake) {
+    const partialDisplay = {
+        type: bake.displayType,
+        displayId: bake.displayId,
+        ...bake.values,
+    };
+    const ownConfig = ownTrackConfig(snap, bake.trackId);
+    if (ownConfig) {
+        const displays = asArray(ownConfig.displays);
+        const target = displays.find(d => isRecord(d) && d.displayId === bake.displayId);
+        if (isRecord(target)) {
+            Object.assign(target, bake.values);
+        }
+        else {
+            ownConfig.displays = [...displays, partialDisplay];
+        }
+    }
+    else {
+        const deltas = isRecord(snap.trackConfigDeltas)
+            ? { ...snap.trackConfigDeltas }
+            : {};
+        const existing = isRecord(deltas[bake.trackId])
+            ? deltas[bake.trackId]
+            : { trackId: bake.trackId };
+        deltas[bake.trackId] = mergeTrackConfig(existing, {
+            trackId: bake.trackId,
+            displays: [partialDisplay],
+        });
+        snap.trackConfigDeltas = deltas;
+    }
+}

package/esm/Session/temporaryAssemblyTracks.d.ts

@@ -0,0 +1,24 @@
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+/**
+ * Checks that a track config being written into a session or config list is one
+ * something can still draw tomorrow.
+ *
+ * A config naming nothing but a temporary assembly is dead the moment its view
+ * closes, and no list outside that view has anyone to sweep it — which is the
+ * whole of ADR-084. A track only one view can draw carries its config on the
+ * track instead (`showTrackGeneric`'s `inlineConf`), so reaching a session list
+ * with one is the mistake, not the cleanup afterwards.
+ *
+ * **This reports a write, not a click.** The two flows a user can drive into it
+ * are answered before they get here — the track menu greys its copy actions, and
+ * `addTrackFromWidget` opens the track inline instead of adding it — so what
+ * survives to report is a caller that had `inlineConf` available and did not
+ * take it. That is the reading the message is written for.
+ *
+ * `console.error` and never `throw`, matching `assertDisplayContract`: these
+ * writes happen inside launchers and menu handlers where an exception is caught
+ * and reported as a failed track, which would hide the violation. The jest gate
+ * (`config/jest/contractGate.js`) is what listens in tree; out of tree
+ * `contractReports` does, once a host arms it.
+ */
+export declare function assertTrackConfOutlivesItsAssemblies(session: unknown, trackConf: AnyConfigurationModel | Record<string, unknown>, destination: string): void;

package/esm/Session/temporaryAssemblyTracks.js

@@ -0,0 +1,37 @@
+import { namesTemporaryAssembly } from '@jbrowse/core/util';
+import { reportContractViolation } from '@jbrowse/render-core/contractReports';
+/**
+ * Checks that a track config being written into a session or config list is one
+ * something can still draw tomorrow.
+ *
+ * A config naming nothing but a temporary assembly is dead the moment its view
+ * closes, and no list outside that view has anyone to sweep it — which is the
+ * whole of ADR-084. A track only one view can draw carries its config on the
+ * track instead (`showTrackGeneric`'s `inlineConf`), so reaching a session list
+ * with one is the mistake, not the cleanup afterwards.
+ *
+ * **This reports a write, not a click.** The two flows a user can drive into it
+ * are answered before they get here — the track menu greys its copy actions, and
+ * `addTrackFromWidget` opens the track inline instead of adding it — so what
+ * survives to report is a caller that had `inlineConf` available and did not
+ * take it. That is the reading the message is written for.
+ *
+ * `console.error` and never `throw`, matching `assertDisplayContract`: these
+ * writes happen inside launchers and menu handlers where an exception is caught
+ * and reported as a failed track, which would hide the violation. The jest gate
+ * (`config/jest/contractGate.js`) is what listens in tree; out of tree
+ * `contractReports` does, once a host arms it.
+ */
+export function assertTrackConfOutlivesItsAssemblies(session, trackConf, destination) {
+    if (!namesTemporaryAssembly(session, trackConf)) {
+        return;
+    }
+    const { trackId } = trackConf;
+    reportContractViolation('session', `${destination} was given "${trackId}", ` +
+        `which names a temporary assembly — one a comparative view synthesized ` +
+        `and gives back when it closes, so this config outlives the only ` +
+        `assembly that could draw it and nothing sweeps the list it landed in. ` +
+        `A track only one view can draw passes its config to that view's ` +
+        `showTrack as \`inlineConf\` instead, which puts it on the track and ` +
+        `takes it out with the view. See ADR-084.`);
+}

package/esm/assertExtends.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Compile-time assertion that `Actual` is assignable to `Expected`, evaluating
+ * to `Actual`. There is no runtime component — referencing the alias forces the
+ * check, and a mismatch surfaces as a type error at the reference site.
+ *
+ * The main use is binding a hand-written "shadow" contract to the real type it
+ * shadows so the two can't silently drift. MST's `getParent<T>(self)` is an
+ * unchecked assertion (`T` has no structural link to the actual parent), so a
+ * child model that reaches into its parent via a local shape can keep compiling
+ * after the real parent renames or drops a member — until it throws at runtime.
+ * Pinning `AssertExtends<RealRootModel, ShadowParent>` turns that into a build
+ * error:
+ *
+ * ```ts
+ * interface SessionModelParent {
+ *   version: string
+ *   assemblyManager: AssemblyManager
+ * }
+ * // real root must satisfy the shadow the session reaches for
+ * export type _Check = AssertExtends<ViewModel, SessionModelParent>
+ * ```
+ */
+export type AssertExtends<Actual extends Expected, Expected> = Actual;
+/**
+ * Compile-time assertion that a type has not degraded to `any`. Pass it the
+ * `IsAny` of the type you are pinning; a failure reads `Type 'true' does not
+ * satisfy the constraint 'false'`.
+ *
+ * ```ts
+ * export type _ViewIsTyped = AssertNotAny<IsAny<ViewModel['session']['view']>>
+ * ```
+ *
+ * This is the one check the others cannot make for you. `any` satisfies every
+ * `AssertExtends`, implements every `SessionWith*` contract, and passes tsc,
+ * jest and lint — so a surface that silently becomes `any` switches off type
+ * checking everywhere downstream while every gate stays green.
+ *
+ * Composed MST models are where it happens here. `types.compose`'s overloads
+ * are declared over `IModelType<P, O, FC, FS>`, so a model passed in as a naked
+ * type parameter has nothing to infer those four from and the composed result
+ * degrades.
+ *
+ * Naming `any` twice at the call site is not an oversight. It takes the computed
+ * boolean because the constraint has to be checked where it is concrete, and all
+ * three single-argument spellings were tried and fail:
+ *
+ * - `AssertNotAny<T> = AssertExtends<IsAny<T>, false>` — unbound, `IsAny<T>` is
+ *   `boolean`, so the alias fails at its own declaration.
+ * - `AssertNotAny<T, _ extends false = IsAny<T>> = T` — the tempting one. Same
+ *   declaration-site failure, and it does not even catch: instantiated at `any`
+ *   it reports nothing.
+ * - `AssertNotAny<T extends IsAny<T> extends true ? never : unknown>` — TS2313,
+ *   circular constraint.
+ */
+export type AssertNotAny<IsItAny extends false> = IsItAny;

package/esm/assertExtends.js

@@ -0,0 +1 @@
+export {};

package/esm/controllerTracks.d.ts

@@ -0,0 +1,56 @@
+import type { BlobLocation } from '@jbrowse/core/util';
+import type { LooseTrackInput } from '@jbrowse/core/util/tracks';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export type TrackConf = Record<string, unknown>;
+/**
+ * What a controller accepts per track: a full config, a bare data-file URL, or
+ * `{ uri, index?, ...extra }`. The loose forms expand through core's
+ * `guessTrackConf`, the same inference the "Add track" flow runs.
+ */
+export type TrackInput = string | TrackConf;
+interface ControllerView {
+    tracks: {
+        configuration: {
+            trackId: string;
+        };
+    }[];
+    launchTrack: (trackId: string) => Promise<unknown>;
+    hideTrack: (trackId: string) => unknown;
+}
+export interface ControllerSession extends IStateTreeNode {
+    view: ControllerView;
+    getTrackById: (trackId: string) => unknown;
+    addSessionTrackConf: (conf: TrackConf) => unknown;
+}
+export declare function isLooseTrack(track: TrackInput): track is string | LooseTrackInput;
+/**
+ * Stamp the view's assembly onto a full-config track that omits
+ * `assemblyNames`. A single-view embed has exactly one assembly, so it is
+ * unambiguous — and doing it here frees every host (R htmlwidgets, anywidget,
+ * vanilla JS) from computing the name itself, which it often cannot: the
+ * assembly may have arrived as a hub name only the view resolved. Loose tracks
+ * take the same name through `guessTrackConf`'s `assemblyName` argument.
+ */
+export declare function withAssemblyName(track: TrackConf, assemblyName?: string): TrackConf;
+/**
+ * Expand every loose entry into a full track config; stamp the assembly name
+ * onto the ones already written out. `node` is any node of the live tree — the
+ * pluginManager whose format plugins drive the guess comes off its env.
+ */
+export declare function resolveTracks(tracks: TrackInput[], node: IStateTreeNode, assemblyName?: string, localFiles?: Record<string, BlobLocation>): TrackConf[];
+/**
+ * Register each track config only if the session cannot already resolve it, then
+ * show it. `getTrackById` resolves catalog + connection + session tracks, so a
+ * config already seeded into the catalog is left alone rather than shadowed by a
+ * duplicate in `sessionTracks` — which is also what `addSessionTrackConf`
+ * dedupes on, so this states the intent rather than supplying it.
+ *
+ * Session-scoped: these are the host's declared tracks for one embed, not a
+ * catalog an admin curates.
+ */
+export declare function openTracks(session: ControllerSession, tracks: TrackConf[]): Promise<void>;
+/** Open every wanted track and close any others the view currently shows. */
+export declare function reconcileTracks(session: ControllerSession, tracks: TrackConf[]): Promise<void>;
+/** Merge a hub's own search adapters with the ones the caller supplied. */
+export declare function mergeSearchAdapters<T>(a: readonly T[] | undefined, b: readonly T[] | undefined): T[] | undefined;
+export {};

package/esm/controllerTracks.js

@@ -0,0 +1,90 @@
+import { getEnv } from '@jbrowse/core/util';
+import { guessTrackConf } from '@jbrowse/core/util/tracks';
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { resolveLocalFileUris } from './localFiles.js';
+export function isLooseTrack(track) {
+    return typeof track === 'string' || (!('adapter' in track) && 'uri' in track);
+}
+/**
+ * Stamp the view's assembly onto a full-config track that omits
+ * `assemblyNames`. A single-view embed has exactly one assembly, so it is
+ * unambiguous — and doing it here frees every host (R htmlwidgets, anywidget,
+ * vanilla JS) from computing the name itself, which it often cannot: the
+ * assembly may have arrived as a hub name only the view resolved. Loose tracks
+ * take the same name through `guessTrackConf`'s `assemblyName` argument.
+ */
+export function withAssemblyName(track, assemblyName) {
+    return assemblyName !== undefined && !('assemblyNames' in track)
+        ? { ...track, assemblyNames: [assemblyName] }
+        : track;
+}
+/**
+ * Expand every loose entry into a full track config; stamp the assembly name
+ * onto the ones already written out. `node` is any node of the live tree — the
+ * pluginManager whose format plugins drive the guess comes off its env.
+ */
+export function resolveTracks(tracks, node, assemblyName, localFiles) {
+    const { pluginManager } = getEnv(node);
+    return tracks.map(track => {
+        const conf = isLooseTrack(track)
+            ? guessTrackConf(track, pluginManager, assemblyName)
+            : // full configs are stamped here too, not just in the build() catalog
+                // seed: a config that first appears through addTrack never passes
+                // through that seed, and would otherwise reach addSessionTrackConf with no
+                // assemblyNames and silently fail to display
+                withAssemblyName(track, assemblyName);
+        // after the guess, so the adapter has already derived its index sibling
+        // from the uri string and both get swapped for blobs together
+        return localFiles ? resolveLocalFileUris(conf, localFiles) : conf;
+    });
+}
+/**
+ * Register each track config only if the session cannot already resolve it, then
+ * show it. `getTrackById` resolves catalog + connection + session tracks, so a
+ * config already seeded into the catalog is left alone rather than shadowed by a
+ * duplicate in `sessionTracks` — which is also what `addSessionTrackConf`
+ * dedupes on, so this states the intent rather than supplying it.
+ *
+ * Session-scoped: these are the host's declared tracks for one embed, not a
+ * catalog an admin curates.
+ */
+export async function openTracks(session, tracks) {
+    // sequential, not Promise.all: each display's state model may be a separate
+    // dynamic import, and racing them would land the tracks on the view in
+    // whatever order the chunks happen to resolve rather than the caller's
+    for (const conf of tracks) {
+        // the engine can be destroyed while a chunk is in flight (an unmounted
+        // embed); reading the dead tree from this floating promise would throw
+        // uncatchably
+        if (!isAlive(session.view)) {
+            return;
+        }
+        const trackId = conf.trackId;
+        if (!session.getTrackById(trackId)) {
+            session.addSessionTrackConf(conf);
+        }
+        await session.view.launchTrack(trackId);
+    }
+}
+/** Open every wanted track and close any others the view currently shows. */
+export async function reconcileTracks(session, tracks) {
+    const { view } = session;
+    const wanted = new Set(tracks.map(t => t.trackId));
+    await openTracks(session, tracks);
+    if (!isAlive(view)) {
+        return;
+    }
+    // materialize the ids first: hideTrack splices view.tracks, so iterating it
+    // live would skip entries
+    const unwanted = view.tracks
+        .map(track => track.configuration.trackId)
+        .filter(trackId => !wanted.has(trackId));
+    for (const trackId of unwanted) {
+        view.hideTrack(trackId);
+    }
+}
+/** Merge a hub's own search adapters with the ones the caller supplied. */
+export function mergeSearchAdapters(a, b) {
+    const merged = [...(a ?? []), ...(b ?? [])];
+    return merged.length ? merged : undefined;
+}

package/esm/destroyViewState.d.ts

@@ -0,0 +1,21 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface EmbeddedRoot extends IStateTreeNode {
+    session?: unknown;
+    rpcManager: {
+        destroy: () => void;
+    };
+}
+/**
+ * Tear down an engine built by an embedded product's `createViewState`:
+ * terminate its RPC worker threads and destroy the MST tree so its
+ * `addDisposer`'d autoruns stop.
+ *
+ * Unmounting the React tree is not enough — the engine is not owned by React.
+ * A host that builds and discards engines (a Jupyter cell re-run, an SPA route
+ * change, a controller's `destroy()`) otherwise orphans a whole worker pool and
+ * a live autorun set per discarded engine. A component that owns one engine for
+ * the lifetime of the page never needs this.
+ *
+ * Idempotent: destroying an already-destroyed engine is a no-op.
+ */
+export declare function destroyViewState(viewState: EmbeddedRoot): void;

package/esm/destroyViewState.js

@@ -0,0 +1,29 @@
+import { destroy, isAlive } from '@jbrowse/mobx-state-tree';
+/**
+ * Tear down an engine built by an embedded product's `createViewState`:
+ * terminate its RPC worker threads and destroy the MST tree so its
+ * `addDisposer`'d autoruns stop.
+ *
+ * Unmounting the React tree is not enough — the engine is not owned by React.
+ * A host that builds and discards engines (a Jupyter cell re-run, an SPA route
+ * change, a controller's `destroy()`) otherwise orphans a whole worker pool and
+ * a live autorun set per discarded engine. A component that owns one engine for
+ * the lifetime of the page never needs this.
+ *
+ * Idempotent: destroying an already-destroyed engine is a no-op.
+ */
+export function destroyViewState(viewState) {
+    if (isAlive(viewState)) {
+        // Materialize the session before killing the tree. MST snapshots each dying
+        // node on the way down, and snapshotting a node that was never observed
+        // instantiates it right then — running its afterAttach during death
+        // finalization, where creating a further observable (the config it reads)
+        // throws "the creation of the observable instance must be done on the
+        // initializing phase". Reachable whenever an engine is destroyed before it
+        // ever rendered, which is exactly what React StrictMode does to the
+        // build-in-a-ref-callback pattern: mount, clean up, mount again.
+        void viewState.session;
+        viewState.rpcManager.destroy();
+        destroy(viewState);
+    }
+}

package/esm/index.d.ts

@@ -1,4 +1,31 @@
-export * from './RootModel/index.ts';
-export * from './Session/index.ts';
-export * from './ui/index.ts';
-export * from './rpcWorker.ts';
+export type { AssertExtends, AssertNotAny } from './assertExtends.ts';
+export { asRoot, asSession } from './siblingCast.ts';
+export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.ts';
+export { BaseRootModelFactory, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, HierarchicalConfigSchemaFactory, InternetAccountsRootModelMixin, PreferencesConfigSchemaFactory, createConfigModel, exportSessionMenuItem, importSessionMenuItem, isRootModel, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './RootModel/index.ts';
+export type { BaseRootModel, BaseRootModelType, RootConfigurationSnapshot, RootModelWithInternetAccounts, RootModelWithInternetAccountsType, } from './RootModel/index.ts';
+export { BaseSessionModel, ConnectionManagementSessionMixin, DrawerWidgetSessionMixin, MultipleViewsSessionMixin, PreferencesSessionMixin, ReferenceManagementSessionMixin, SessionTracksManagerSessionMixin, ThemeManagerSessionMixin, TrackMenuItemsSessionMixin, TrackMenuSessionMixin, TracksManagerSessionMixin, aboutTrackMenuItem, bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.ts';
+export type { AssertSessionModel, BaseSession, BaseSessionType, ConnectionTrackConfigEntry, EditableTrackConfig, PlainTrackConfig, ReferringNode, SessionWithConnections, SessionWithConnectionsType, SessionWithDrawerWidgets, SessionWithDrawerWidgetsType, SessionWithMultipleViews, SessionWithMultipleViewsType, SessionWithReferenceManagement, SessionWithReferenceManagementType, SessionWithSessionTracks, SessionWithSessionTracksType, SessionWithThemes, SessionWithThemesType, SessionWithTracks, SessionWithTracksType, } from './Session/index.ts';
+export { AboutDialog, Drawer, DrawerControls, DrawerHeader, DrawerWidget, DrawerWidgetSelector, ModalWidget, ModalWidgetAppBar, PreferencesDialog, WidgetBody, WidgetHeading, drawerGridTemplateColumns, } from './ui/index.ts';
+export type { PreferencesDialogSession, PreferencesPanelDescriptor, } from './ui/index.ts';
+export { initializeWorker } from './rpcWorker.ts';
+export { toPluginLoadRecord } from './pluginInput.ts';
+export type { PluginInput } from './pluginInput.ts';
+export { loadRuntimePlugins } from './loadPlugins.ts';
+export type { LoadPluginsArgs } from './loadPlugins.ts';
+export { decodeSessionFromUrl, encodeSessionToUrl } from './sessionUrl.ts';
+export type { SessionSnapshot } from './sessionUrl.ts';
+export { mergeLocalFiles, normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.ts';
+export type { LocalFileInput } from './localFiles.ts';
+export { isLooseTrack, mergeSearchAdapters, openTracks, reconcileTracks, resolveTracks, withAssemblyName, } from './controllerTracks.ts';
+export type { ControllerSession, TrackConf, TrackInput, } from './controllerTracks.ts';
+export { resolveAssemblies, resolveAssembly } from './resolveAssemblies.ts';
+export type { AssemblyInput, ResolvedAssemblies } from './resolveAssemblies.ts';
+export { destroyViewState } from './destroyViewState.ts';
+export { useAsyncEngineLifecycle, useCreateOnce, useCreateOnceAsync, useDestroyOnUnmount, } from './useEngineLifecycle.ts';
+export { getSessionSnapshot, observeSession } from './observeSession.ts';
+export type { SessionObservers, ViewLocation } from './observeSession.ts';
+export { MIGRATED_DISPLAY_INSTANCE_KEYS, migrateConfigSnapshot, migrateSessionSnapshot, } from './sessionMigrations/index.ts';
+export { DEFAULT_WEB_BASE_URL, analyzeWebPortability, buildWebExportUrl, filterSessionInPlace, planWebExport, } from './sessionUtils.ts';
+export type { AssemblySnapshot, DroppedSessionNode, HostedBaseConfig, NonPortableLocation, SelfContainedReason, TrackSnapshot, WebExportInput, WebExportPlan, WebPortabilityReport, } from './sessionUtils.ts';
+export { describeUnbuildableNodes, pruneUnbuildableNodes, } from './pruneUnbuildableNodes.ts';
+export type { HeldNode, UnbuildableNode } from './pruneUnbuildableNodes.ts';

package/esm/index.js

@@ -1,4 +1,31 @@
-export * from "./RootModel/index.js";
-export * from "./Session/index.js";
-export * from "./ui/index.js";
-export * from "./rpcWorker.js";
+export { asRoot, asSession } from './siblingCast.js';
+export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.js';
+export { BaseRootModelFactory, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, HierarchicalConfigSchemaFactory, InternetAccountsRootModelMixin, PreferencesConfigSchemaFactory, createConfigModel, exportSessionMenuItem, importSessionMenuItem, isRootModel, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './RootModel/index.js';
+export { BaseSessionModel, ConnectionManagementSessionMixin, DrawerWidgetSessionMixin, MultipleViewsSessionMixin, PreferencesSessionMixin, ReferenceManagementSessionMixin, SessionTracksManagerSessionMixin, ThemeManagerSessionMixin, TrackMenuItemsSessionMixin, TrackMenuSessionMixin, TracksManagerSessionMixin, aboutTrackMenuItem, bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.js';
+export { AboutDialog, Drawer, DrawerControls, DrawerHeader, DrawerWidget, DrawerWidgetSelector, ModalWidget, ModalWidgetAppBar, PreferencesDialog, WidgetBody, WidgetHeading, drawerGridTemplateColumns, } from './ui/index.js';
+export { initializeWorker } from './rpcWorker.js';
+export { toPluginLoadRecord } from './pluginInput.js';
+export { loadRuntimePlugins } from './loadPlugins.js';
+export { decodeSessionFromUrl, encodeSessionToUrl } from './sessionUrl.js';
+// in-memory files as tracks, for hosts whose data lives in a process rather
+// than at a URL (a notebook kernel, an R session) — read by byte range, so an
+// indexed file stays indexed
+export { mergeLocalFiles, normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.js';
+// the track half of an imperative controller: loose track specs -> configs, and
+// opening exactly the wanted set
+export { isLooseTrack, mergeSearchAdapters, openTracks, reconcileTracks, resolveTracks, withAssemblyName, } from './controllerTracks.js';
+// hub names, sequence URIs and hub configs -> assembly configs, so every
+// product takes the same assembly vocabulary
+export { resolveAssemblies, resolveAssembly } from './resolveAssemblies.js';
+// engine teardown, for a host that builds and discards engines — React unmount
+// alone leaves the RPC workers and autoruns running
+export { destroyViewState } from './destroyViewState.js';
+// the two halves of "React owns this engine", both of which have a StrictMode
+// trap in them that the obvious spelling walks straight into
+export { useAsyncEngineLifecycle, useCreateOnce, useCreateOnceAsync, useDestroyOnUnmount, } from './useEngineLifecycle.js';
+// the JS -> host direction of an embedded controller: where each view is
+// looking, what got selected, and the layout as plain JSON
+export { getSessionSnapshot, observeSession } from './observeSession.js';
+export { MIGRATED_DISPLAY_INSTANCE_KEYS, migrateConfigSnapshot, migrateSessionSnapshot, } from './sessionMigrations/index.js';
+export { DEFAULT_WEB_BASE_URL, analyzeWebPortability, buildWebExportUrl, filterSessionInPlace, planWebExport, } from './sessionUtils.js';
+export { describeUnbuildableNodes, pruneUnbuildableNodes, } from './pruneUnbuildableNodes.js';

package/esm/loadPlugins.d.ts

@@ -0,0 +1,33 @@
+import type { LoadedPlugin } from '@jbrowse/core/PluginLoader';
+import type { PluginDefinition } from '@jbrowse/core/pluginDefinitions';
+export interface LoadPluginsArgs {
+    fetchESM?: (url: string) => Promise<LoadedPlugin>;
+    /**
+     * Resolve relative plugin urls against this instead of the page. A config
+     * fetched from somewhere else names its plugins relative to itself, so pass
+     * that config's url — otherwise a `"url": "umd_plugin.js"` entry is looked
+     * for next to your own app and 404s.
+     */
+    baseUri?: string;
+    /** @deprecated the pre-4.4 spelling of `baseUri` */
+    baseUrl?: string;
+}
+/**
+ * The body of every embedded product's `loadPlugins`. Each product keeps its own
+ * one-line wrapper, because the doc comment on it is the published API surface
+ * and names that product's own entry points — but the behavior is here, so the
+ * two things that differed between the copies can't drift again: react-app's
+ * accepted no `baseUrl`, and only two of the three defaulted the base url at
+ * all.
+ *
+ * `dropVendored` is the one difference that is real, so it is a required
+ * argument rather than a default. A product that bundles the vendored plugins
+ * (see `vendoredPluginNames`) must drop a config's entry for them or it installs
+ * a second copy beside its own; a product that does not bundle them — the
+ * circular-genome-view build has neither MafViewer nor GWAS in its corePlugins —
+ * must still fetch one a config names, or the config silently loses the plugin.
+ */
+export declare function loadRuntimePlugins(pluginDefinitions: PluginDefinition[], { dropVendored, jbrowseVersion, ...args }: LoadPluginsArgs & {
+    dropVendored: boolean;
+    jbrowseVersion: string;
+}): Promise<never[] | import("@jbrowse/core/PluginLoader").PluginRecord[]>;