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

package/esm/Session/shareableSnapshot.js

@@ -0,0 +1,66 @@
+import { getSnapshot } from '@jbrowse/mobx-state-tree';
+/**
+ * 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 — currently the
+ * workspaces intent alone.
+ *
+ * It keeps its own entry point rather than being inlined into the one caller
+ * 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.
+ */
+export function bakeSessionCascades(session, snapshot) {
+    const snap = structuredClone(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 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;
+    }
+}

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,76 @@
+import type { BlobLocation } from '@jbrowse/core/util';
+import type { LooseSearchIndex } from '@jbrowse/core/util/expandLooseSearchIndex';
+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, the trackId of one the
+ * catalog already holds (a hub's, when the assembly came from one), 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. A string the catalog already resolves is
+ * that track, and is tried before the file guess: "not URL-shaped" cannot tell
+ * an id from a relative path like `data/reads.bam`.
+ */
+export declare function resolveTracks(tracks: TrackInput[], session: ControllerSession, 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>;
+/**
+ * A hub's entries followed by the host's own, the host's winning where both
+ * carry the same id: the `idKey` member, or what an `idKey` function returns.
+ */
+export declare function withHostOverrides<T>(hub: readonly T[] | undefined, host: readonly T[] | undefined, idKey: string | ((entry: T) => unknown)): T[];
+/**
+ * A search index is the trix file it reads, so a host's entry naming the same
+ * file replaces the hub's, however each spells it: a hub's relative `.ix` is
+ * resolved against its `baseUri`. An index with no trix file is only ever
+ * itself.
+ */
+export declare function searchIndexKey(entry: LooseSearchIndex): string | {
+    uri: string;
+    baseUri?: string;
+    assemblyNames?: string[];
+} | {
+    [key: string]: unknown;
+    type: string;
+};
+export {};

package/esm/controllerTracks.js

@@ -0,0 +1,125 @@
+import { getEnv } from '@jbrowse/core/util';
+import { withPageBaseUri } from '@jbrowse/core/util/addRelativeUris';
+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. A string the catalog already resolves is
+ * that track, and is tried before the file guess: "not URL-shaped" cannot tell
+ * an id from a relative path like `data/reads.bam`.
+ */
+export function resolveTracks(tracks, session, assemblyName, localFiles) {
+    const { pluginManager } = getEnv(session);
+    return tracks.map(track => {
+        if (typeof track === 'string' && session.getTrackById(track)) {
+            return { trackId: 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 withPageBaseUri(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);
+    }
+}
+/**
+ * A hub's entries followed by the host's own, the host's winning where both
+ * carry the same id: the `idKey` member, or what an `idKey` function returns.
+ */
+export function withHostOverrides(hub = [], host = [], idKey) {
+    const idOf = (entry) => typeof idKey === 'function'
+        ? idKey(entry)
+        : entry[idKey];
+    const hostIds = new Set(host.map(idOf).filter(id => id !== undefined));
+    return [...hub.filter(entry => !hostIds.has(idOf(entry))), ...host];
+}
+/**
+ * A search index is the trix file it reads, so a host's entry naming the same
+ * file replaces the hub's, however each spells it: a hub's relative `.ix` is
+ * resolved against its `baseUri`. An index with no trix file is only ever
+ * itself.
+ */
+export function searchIndexKey(entry) {
+    if (typeof entry === 'string') {
+        return entry;
+    }
+    const { uri, baseUri, ixFilePath } = entry;
+    return ixFilePath?.uri !== undefined
+        ? resolved(ixFilePath.uri, ixFilePath.baseUri)
+        : (ixFilePath?.localPath ??
+            (uri !== undefined ? resolved(uri, baseUri) : entry));
+}
+function resolved(uri, baseUri) {
+    try {
+        return baseUri ? new URL(uri, baseUri).href : uri;
+    }
+    catch {
+        return uri;
+    }
+}

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/embeddedController.d.ts

@@ -0,0 +1,57 @@
+import type { ControllerSession, TrackConf, TrackInput } from './controllerTracks.ts';
+import type { EmbeddedRoot } from './destroyViewState.ts';
+import type { LocalFileInput } from './localFiles.ts';
+import type { ObservedSession, SessionObservers } from './observeSession.ts';
+import type { AssemblyInput, ResolvedAssembly } from './resolveAssemblies.ts';
+import type { ComponentType } from 'react';
+/** The fields every embedded controller's `update` takes. */
+export interface ControllerState {
+    tracks?: TrackInput[];
+    localFiles?: LocalFileInput;
+}
+interface ControllerRoot extends EmbeddedRoot {
+    session: ControllerSession & ObservedSession & {
+        view: {
+            setLaunch(launch: {
+                assembly: string;
+            }): void;
+        };
+    };
+}
+export interface EngineSeed<Launch> {
+    resolved: ResolvedAssembly;
+    /** the hub's catalog and the host's full configs, the host's winning an id */
+    tracks: TrackConf[];
+    /** the view to open, absent when a restored session positions it */
+    view: Launch | undefined;
+}
+export interface EmbeddedControllerSpec<VM, State, Launch> {
+    assembly: AssemblyInput;
+    /** a restored session, which owns the initial layout */
+    session?: unknown;
+    state: NoInfer<State>;
+    observers: SessionObservers;
+    onError?: (error: unknown) => void;
+    Component: ComponentType<{
+        viewState: VM;
+    }>;
+    build: (seed: EngineSeed<Launch>) => Promise<VM>;
+    /**
+     * The view launch `stated` asks for, read off `wanted` and less its
+     * assembly, or undefined when `stated` names nothing a launch carries. The
+     * build asks with the initial state as both.
+     */
+    launchFor: (stated: State, wanted: State) => Launch | undefined;
+}
+/**
+ * The lifecycle behind each embedded product's imperative controller: resolve
+ * the genome, build the engine, open the wanted tracks, mount, then reconcile
+ * each `update` and tear everything down on `destroy`. The product supplies
+ * the engine and the view launch its own state fields ask for.
+ */
+export declare function createEmbeddedController<VM extends ControllerRoot, State extends ControllerState, Launch extends object>(el: HTMLElement, spec: EmbeddedControllerSpec<VM, State, Launch>): {
+    whenReady(): Promise<VM>;
+    update(stated: State): Promise<void>;
+    destroy(): void;
+};
+export {};

package/esm/embeddedController.js

@@ -0,0 +1,100 @@
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { isLooseTrack, reconcileTracks, resolveTracks, withAssemblyName, withHostOverrides, } from './controllerTracks.js';
+import { destroyViewState } from './destroyViewState.js';
+import { mergeLocalFiles, registerLocalFiles, resolveLocalFileUris, } from './localFiles.js';
+import { observeSession } from './observeSession.js';
+import { resolveAssembly } from './resolveAssemblies.js';
+function restate(wanted, stated) {
+    const next = { ...wanted };
+    for (const key of Object.keys(stated)) {
+        if (stated[key] !== undefined) {
+            next[key] = stated[key];
+        }
+    }
+    return next;
+}
+/**
+ * The lifecycle behind each embedded product's imperative controller: resolve
+ * the genome, build the engine, open the wanted tracks, mount, then reconcile
+ * each `update` and tear everything down on `destroy`. The product supplies
+ * the engine and the view launch its own state fields ask for.
+ */
+export function createEmbeddedController(el, spec) {
+    const { Component, launchFor, onError = (e) => {
+        console.error(e);
+    }, } = spec;
+    const hasSession = spec.session !== undefined;
+    let wanted = spec.state;
+    let localFiles = registerLocalFiles(wanted.localFiles ?? {});
+    let assemblyName;
+    let current;
+    let stopObserving;
+    let destroyed = false;
+    const root = createRoot(el);
+    function wantedTracks(viewState) {
+        return resolveTracks(wanted.tracks ?? [], viewState.session, assemblyName, localFiles);
+    }
+    async function build() {
+        const resolved = await resolveAssembly(spec.assembly);
+        const { name } = resolved.assembly;
+        assemblyName = typeof name === 'string' ? name : undefined;
+        const viewState = await spec.build({
+            resolved,
+            tracks: withHostOverrides(resolved.tracks, (wanted.tracks ?? [])
+                .filter((track) => !isLooseTrack(track))
+                .map(track => resolveLocalFileUris(withAssemblyName(track, assemblyName), localFiles)), 'trackId'),
+            view: hasSession ? undefined : launchFor(wanted, wanted),
+        });
+        if (!hasSession) {
+            await reconcileTracks(viewState.session, wantedTracks(viewState));
+        }
+        // destroy() can land during any await above, before there was an engine
+        // for it to tear down
+        if (destroyed) {
+            destroyViewState(viewState);
+            return viewState;
+        }
+        current = viewState;
+        stopObserving = observeSession(viewState, spec.observers);
+        root.render(createElement(Component, { viewState }));
+        return viewState;
+    }
+    const ready = build();
+    ready.catch(onError);
+    async function apply(stated) {
+        const viewState = current;
+        if (!viewState) {
+            return;
+        }
+        if (stated.tracks) {
+            await reconcileTracks(viewState.session, wantedTracks(viewState));
+        }
+        const launch = launchFor(stated, wanted);
+        if (launch && assemblyName && !destroyed) {
+            viewState.session.view.setLaunch({ ...launch, assembly: assemblyName });
+        }
+    }
+    return {
+        whenReady() {
+            return ready;
+        },
+        async update(stated) {
+            if (stated.localFiles) {
+                localFiles = mergeLocalFiles(localFiles, stated.localFiles);
+            }
+            wanted = restate(wanted, stated);
+            await ready;
+            await apply(stated);
+        },
+        destroy() {
+            destroyed = true;
+            stopObserving?.();
+            root.unmount();
+            if (current) {
+                destroyViewState(current);
+            }
+            current = undefined;
+        },
+    };
+}

package/esm/index.d.ts

@@ -1,4 +1,32 @@
-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 '@jbrowse/core/util';
+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, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, hydratedForms, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, storedThemeArgs, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.ts';
+export type { AssertSessionModel, BaseSession, BaseSessionType, ConnectionTrackConfigEntry, EditableTrackConfig, HydratedForms, PlainTrackConfig, ReferringNode, SessionWithConnections, SessionWithConnectionsType, SessionWithDrawerWidgets, SessionWithDrawerWidgetsType, SessionWithMultipleViews, SessionWithMultipleViewsType, SessionWithReferenceManagement, SessionWithReferenceManagementType, SessionWithSessionTracks, SessionWithSessionTracksType, SessionWithThemes, SessionWithThemesType, SessionWithTracks, SessionWithTracksType, ThemeModeSelection, } from './Session/index.ts';
+export { AboutDialog, AppReadyMarker, Drawer, DrawerControls, DrawerHeader, DrawerWidget, DrawerWidgetSelector, ModalWidget, ModalWidgetAppBar, PreferencesDialog, WidgetBody, WidgetHeading, drawerGridTemplateColumns, } from './ui/index.ts';
+export type { AboutPanelProps, 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 { normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.ts';
+export type { LocalFileInput } from './localFiles.ts';
+export { searchIndexKey, withHostOverrides } from './controllerTracks.ts';
+export type { TrackInput } from './controllerTracks.ts';
+export { createEmbeddedController } from './embeddedController.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 { migrateSessionSnapshot, migratedDisplayInstanceKeys, } from './sessionMigrations/index.ts';
+export { DEFAULT_WEB_BASE_URL, analyzeWebPortability, buildWebExportUrl, filterSessionInPlace, planWebExport, } from './sessionUtils.ts';
+export type { AssemblySnapshot, DroppedSessionNode, HostedBase, HostedBaseConfig, NonPortableLocation, SelfContainedReason, TrackSnapshot, WebExportInput, WebExportPlan, WebPortabilityReport, } from './sessionUtils.ts';
+export { describeUnbuildableNodes, pruneUnbuildableNodes, } from './pruneUnbuildableNodes.ts';
+export type { HeldNode, UnbuildableNode } from './pruneUnbuildableNodes.ts';