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

package/esm/sessionUtils.js

@@ -0,0 +1,613 @@
+import { maybePluginUrl } from '@jbrowse/core/pluginDefinitions';
+import { SHARE_PREFIX, diffTrackConfig, flattenTrackConfigDelta, } from '@jbrowse/core/util';
+import { getChildType, getPropertyMembers, getSnapshot, isArrayType, isMapType, isModelType, isReferenceType, isValidReference, } from '@jbrowse/mobx-state-tree';
+import { asArray, isRecord } from './snapshotUtils.js';
+// Cleans a freshly-loaded session in place by dropping any array/map element
+// that can't be hydrated — e.g. an open track whose `configuration` reference
+// resolves to a dangling id or a structurally-invalid config and throws when
+// read. Dropping keeps the invariant that the open set only ever holds usable
+// tracks (matching the open/add paths, which refuse invalid configs), so
+// downstream code never has to defend against a track whose config access
+// throws. Returns the dropped nodes so the caller can tell the user which
+// tracks went missing.
+//
+// Dangling references in collections are NOT this function's job: every session
+// reference is a `types.safeReference`, whose onInvalidated removes the entry
+// from its parent at load. The `isValidReference` branch below is a backstop
+// for any future plain `types.reference` collection.
+export function filterSessionInPlace(node, type, dropped = []) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (node !== undefined) {
+        if (isArrayType(type)) {
+            const array = node;
+            const childType = getChildType(node);
+            const isRef = isReferenceType(childType);
+            for (let i = 0; i < array.length;) {
+                if (!walkChildOrDrop(() => array[i], childType, isRef, dropped)) {
+                    array.splice(i, 1);
+                }
+                else {
+                    i += 1;
+                }
+            }
+        }
+        else if (isMapType(type)) {
+            const map = node;
+            const childType = getChildType(map);
+            const isRef = isReferenceType(childType);
+            for (const key of map.keys()) {
+                if (!walkChildOrDrop(() => map.get(key), childType, isRef, dropped)) {
+                    map.delete(key);
+                }
+            }
+        }
+        else if (isModelType(type)) {
+            const { properties } = getPropertyMembers(node);
+            // A node holding a `configuration` reference is a track/display/
+            // connection. Its only load-time integrity concern is that the config
+            // resolves: reading it throws for a dangling id or a structurally-invalid
+            // config, which the caller turns into a drop. Stop here instead of
+            // recursing — the first config-bearing node on the path to a display is
+            // the track itself, and recursing past it would eagerly instantiate child
+            // state models (displays) and run their afterAttach before the view is
+            // measured. That throws on view.width and would be misread as an invalid
+            // node, dropping a valid track. Display configs resolve through their own
+            // safety net (the track config's preProcessSnapshot injects a stub
+            // display per registered type).
+            if ('configuration' in properties) {
+                void node.configuration;
+            }
+            else {
+                for (const [pname, ptype] of Object.entries(properties)) {
+                    filterSessionInPlace(node[pname], ptype, dropped);
+                }
+            }
+        }
+    }
+    return dropped;
+}
+// Returns false if the collection element should be dropped: a dangling
+// reference (removed silently — see header), or a config-bearing node that
+// throws while hydrating (recorded in `dropped` so the caller can report it).
+// Otherwise recurses into it and returns true.
+function walkChildOrDrop(get, childType, isRef, dropped) {
+    if (isRef) {
+        return isValidReference(get);
+    }
+    let child;
+    try {
+        child = get();
+        filterSessionInPlace(child, childType, dropped);
+        return true;
+    }
+    catch (e) {
+        console.error(e);
+        dropped.push(describeDroppedNode(child));
+        return false;
+    }
+}
+// Identifies a dropped node for a user-facing message by reading its serialized
+// snapshot, which keeps a dangling `configuration` reference (the usual cause of
+// a drop) from throwing again — references serialize to their stored id string.
+function describeDroppedNode(node) {
+    try {
+        if (node !== undefined) {
+            const snap = getSnapshot(node);
+            return {
+                type: typeof snap.type === 'string' ? snap.type : undefined,
+                configuration: typeof snap.configuration === 'string'
+                    ? snap.configuration
+                    : undefined,
+            };
+        }
+    }
+    catch (e) {
+        console.error(e);
+    }
+    return {};
+}
+function locationDisplayName(loc) {
+    switch (loc.locationType) {
+        case 'LocalPathLocation':
+            return typeof loc.localPath === 'string' ? loc.localPath : 'local file';
+        case 'BlobLocation':
+        case 'FileHandleLocation':
+            return typeof loc.name === 'string' ? loc.name : 'local file';
+        case 'UriLocation':
+            return typeof loc.uri === 'string' ? loc.uri : 'remote file';
+        default:
+            return 'unknown location';
+    }
+}
+function walkLocations(node, track, out) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            walkLocations(item, track, out);
+        }
+    }
+    else if (typeof node === 'object' && node !== null) {
+        const obj = node;
+        const nextTrack = typeof obj.trackId === 'string'
+            ? {
+                trackId: obj.trackId,
+                trackName: typeof obj.name === 'string' ? obj.name : undefined,
+            }
+            : track;
+        if (typeof obj.locationType === 'string' &&
+            obj.locationType !== 'UriLocation') {
+            out.push({
+                locationType: obj.locationType,
+                name: locationDisplayName(obj),
+                trackId: nextTrack?.trackId,
+                trackName: nextTrack?.trackName,
+            });
+        }
+        for (const key of Object.keys(obj)) {
+            walkLocations(obj[key], nextTrack, out);
+        }
+    }
+}
+// Walks a session/config snapshot and reports every file location that won't
+// open on jbrowse-web. Anything that isn't a UriLocation (local paths from
+// desktop, or blob/file-handle locations bound to another browser session) is
+// non-portable; a fully-UriLocation snapshot is portable and can be handed to
+// the web app directly.
+export function analyzeWebPortability(snapshot) {
+    const nonPortable = [];
+    walkLocations(snapshot, undefined, nonPortable);
+    return { nonPortable, portable: nonPortable.length === 0 };
+}
+// Distinct file display names of a set of non-portable locations, in first-seen
+// order.
+function distinctNames(locations) {
+    return [...new Set(locations.map(l => l.name))];
+}
+// Reads a `trackId` off a loosely-typed session-track snapshot, or undefined.
+function readTrackId(track) {
+    const id = isRecord(track) ? track.trackId : undefined;
+    return typeof id === 'string' ? id : undefined;
+}
+// Concatenate session-track lists, keeping the last entry per trackId so a track
+// carried by both the prior session and the current snapshot ships once (a
+// duplicate trackId is an MST identifier collision on load). Entries without a
+// readable trackId are kept as-is, in order.
+function concatTracksByTrackId(...lists) {
+    const byId = new Map();
+    const out = [];
+    for (const t of lists.flat()) {
+        const id = readTrackId(t);
+        if (id === undefined) {
+            out.push(t);
+        }
+        else {
+            byId.set(id, t);
+        }
+    }
+    return [...out, ...byId.values()];
+}
+function readAssemblyName(assembly) {
+    const name = isRecord(assembly) ? assembly.name : undefined;
+    return typeof name === 'string' ? name : undefined;
+}
+// Same idea as concatTracksByTrackId for assemblies, whose identifier is their
+// `name`. A duplicate is worse here than for tracks: it doesn't fail at load,
+// it makes every assembly's `configuration` safeReference ambiguous, so the
+// assemblyManager throws on the next read of one and the session is dead.
+function concatAssembliesByName(...lists) {
+    const byName = new Map();
+    const out = [];
+    for (const a of lists.flat()) {
+        const name = readAssemblyName(a);
+        if (name === undefined) {
+            out.push(a);
+        }
+        else {
+            byName.set(name, a);
+        }
+    }
+    return [...out, ...byName.values()];
+}
+// Session assemblies that don't collide with one the recipient's config already
+// provides. `sessionAssemblies` and `jbrowse.assemblies` are concatenated into
+// one namespace on the far side (`AssembliesMixin.assemblies`), and the
+// duplicate-name guard there lives in `addSessionAssembly` — an *add* path,
+// which a deserialized snapshot never goes through. So a name the hosted base
+// also uses is not rejected on load, it silently makes every assembly's
+// `configuration` safeReference ambiguous and takes the session down on the
+// next read. The base's copy wins because it is the one `?config=` guarantees
+// is there.
+//
+// Only the hostedConfigBase strategy needs this. A self-contained export ships
+// no config at all, and concatAssembliesByName already keeps its own two lists
+// from colliding with each other.
+function withoutBaseAssemblies(sessionAssemblies, baseAssemblyNames) {
+    return sessionAssemblies.filter(a => {
+        const name = readAssemblyName(a);
+        return !name || !baseAssemblyNames.has(name);
+    });
+}
+// The assemblies a hosted-base export silently hands back to the hosted config.
+// `coveredByBase` matches on name alone, and nothing ships an assembly edit: a
+// user who attached a refNameAlias or cytoband file to a hub assembly exports a
+// session that quietly uses the hub's original. Both halves of the loss are the
+// same fact to a sender, so they are reported as one list — a config assembly
+// whose config differs from the base's, and a session assembly that
+// `withoutBaseAssemblies` drops to keep the recipient's safeReferences
+// unambiguous.
+//
+// Edited-ness is `flattenTrackConfigDelta`, the same gate `splitTracksAgainstBase`
+// uses, so an export can't call an assembly edited on a diff too thin to be worth
+// shipping for a track.
+function assembliesRevertedToBase(assemblies, sessionAssemblies, baseAssemblies) {
+    const baseByName = new Map(baseAssemblies.map(a => [a.name, a]));
+    const edited = assemblies.flatMap(assembly => {
+        const base = baseByName.get(assembly.name);
+        return base &&
+            flattenTrackConfigDelta(base, diffTrackConfig(base, assembly)).length > 0
+            ? [assembly.name]
+            : [];
+    });
+    const shadowed = sessionAssemblies.flatMap(a => {
+        const name = readAssemblyName(a);
+        return name && baseByName.has(name) ? [name] : [];
+    });
+    return [...new Set([...edited, ...shadowed])];
+}
+// The `sessionAssemblies` override for a hosted-base session, or nothing at all
+// when the session had none — the spread of `defaultSession` is what carries
+// them otherwise, so an unconditional key would add an empty array to every
+// export that never had one.
+function hostedSessionAssemblies(prior, baseAssemblyNames) {
+    return prior.length > 0
+        ? { sessionAssemblies: withoutBaseAssemblies(prior, baseAssemblyNames) }
+        : {};
+}
+// The trackIds the export is free to drop: the ones that name an entry in a
+// track list it actually assembles. Everything else a location can be tagged
+// with is structural and stays — an assembly's own sequence config carries
+// `<name>-ReferenceSequenceTrack`, and an open connection track's config lives
+// in `connectionTrackConfigs`, which rides along inside the session snapshot.
+function droppableTrackIds(tracks, sessionTracks) {
+    return new Set([...tracks, ...sessionTracks].flatMap(t => readTrackId(t) ?? []));
+}
+// Drops a track's `textSearching` when its index is local — the desktop indexer
+// writes the Trix ix/ixx/meta triple as LocalPathLocations
+// (`addTrackTextSearchConf`), so indexing a remote BAM on desktop is enough to
+// make an otherwise perfectly portable track non-portable and get it dropped
+// whole. The data file is the track; the index is a search box over it. Shedding
+// the index costs the recipient that box and nothing else, and under a hosted
+// base the omission also lets the base's own (remote) index resolve, since a
+// delta records adds and changes but never a deletion.
+function withoutLocalTextSearch(track) {
+    if (!isRecord(track) ||
+        !isRecord(track.textSearching) ||
+        analyzeWebPortability(track.textSearching).portable) {
+        return track;
+    }
+    const { textSearching, ...rest } = track;
+    return rest;
+}
+// Display names of the tracks `withoutLocalTextSearch` stripped, for the report.
+function strippedTextIndexNames(before, after) {
+    return [
+        ...new Set(before.flatMap((track, i) => track !== after[i] && isRecord(track)
+            ? [
+                typeof track.name === 'string'
+                    ? track.name
+                    : (readTrackId(track) ?? 'unknown track'),
+            ]
+            : [])),
+    ];
+}
+// The tracks that reference a local file and can be shed by dropping them:
+// their trackIds, to filter the shipped track lists with, and display names, to
+// report to the user. A local file that no droppable track owns can't be shed
+// this way and surfaces as a blockingFile instead.
+function nonPortableUserTracks(report, droppable) {
+    const locs = report.nonPortable.flatMap(l => l.trackId && droppable.has(l.trackId)
+        ? [{ trackId: l.trackId, name: l.trackName ?? l.trackId }]
+        : []);
+    return {
+        ids: new Set(locs.map(l => l.trackId)),
+        names: [...new Set(locs.map(l => l.name))],
+    };
+}
+// Splits the portable tracks against the hosted base. A track with no base entry
+// is user-added and ships whole in `addedTracks` (→ sessionTracks). A track that
+// matches a base entry but differs from it becomes an `editDeltas` entry — the
+// same channel the web session uses — so the recipient's base is overlaid with
+// what the sender has. A track equal to its base entry produces neither and
+// resolves from the base.
+//
+// "Differs" is not the same claim as "the user edited it", and the difference is
+// worth naming. The oracle here is the hub as it is NOW, while desktop's copy is
+// the hub as it was when the session was created (desktop edits jbrowse.tracks in
+// place, keeping the base trackId, and persists the whole config). So a track the
+// hub itself changed since then also lands in `editDeltas`, pinning the recipient
+// to the values the sender is looking at. That is the export's stated intent —
+// reproduce the sender's screen, the same reason `bakeSessionCascades` exists —
+// but the delta channel it travels in means "user override" on the far side, and
+// a delta masks later admin changes to that track. Telling the two apart needs
+// the base as it was at session creation, which nothing persists.
+function splitTracksAgainstBase(tracks, baseTracks) {
+    const baseById = new Map(baseTracks.map(t => [t.trackId, t]));
+    const addedTracks = tracks.filter(t => !baseById.has(t.trackId));
+    const editDeltas = Object.fromEntries(tracks.flatMap((track) => {
+        const base = baseById.get(track.trackId);
+        if (!base) {
+            return [];
+        }
+        const delta = diffTrackConfig(base, track);
+        // gate on real slot changes, not the identity keys / injected display
+        // stubs a raw diff carries (matches the web session's "is edited" test)
+        return flattenTrackConfigDelta(base, delta).length > 0
+            ? [[track.trackId, delta]]
+            : [];
+    }));
+    return { addedTracks, editDeltas };
+}
+// Overlays edited-track deltas onto the session's trackConfigDeltas, preserving
+// any the base session already carried. A no-op (returns the session unchanged)
+// when there are no edits, so the exported snapshot stays minimal.
+function withDeltas(session, editDeltas) {
+    if (Object.keys(editDeltas).length === 0) {
+        return session;
+    }
+    const prior = isRecord(session.trackConfigDeltas)
+        ? session.trackConfigDeltas
+        : {};
+    return { ...session, trackConfigDeltas: { ...prior, ...editDeltas } };
+}
+// The plugin definitions the recipient will not already have, carried in the
+// session as `sessionPlugins` — the one channel a jbrowse-web session has for
+// them, and one it triages before loading (SessionLoader.loadSession). Without
+// this, a desktop session using a plugin's view or track type opens on a
+// jbrowse-web that never registered the type, and the view is dropped on load.
+//
+// Under `hostedConfigBase` jbrowse-web loads the base config's own `plugins[]`,
+// so only the extras ride along; a `selfContained` export opens `?config=none`
+// and has no config to load any from, so it carries them all. Identity is the
+// url a definition loads from (`maybePluginUrl`) rather than its name, since an
+// ESM/CJS definition need not have one; a definition naming no loader at all is
+// never "the same plugin" as another, so it is always carried.
+function extraPlugins(plugins, basePlugins) {
+    const baseUrls = new Set(basePlugins.flatMap(p => maybePluginUrl(p) ?? []));
+    return plugins.filter(p => {
+        const url = maybePluginUrl(p);
+        return !url || !baseUrls.has(url);
+    });
+}
+// Connections the recipient will not already have, carried the same way and for
+// the same reason as the plugins above: desktop keeps them in `jbrowse
+// .connections`, which nothing in the export ships, so without this a session
+// with a track hub arrives on the web with the hub gone. Only the connection
+// tracks the sender had open survive on their own, through the session's
+// `connectionTrackConfigs`; the hub itself — and every track in it the recipient
+// might want to open next — needs `sessionConnections`, jbrowse-web's
+// session-level counterpart of `jbrowse.connections`.
+//
+// Identity is `connectionId`, which is what the recipient's own
+// `connections` getter concatenates on, so shipping one the base already
+// declares would list the same hub twice.
+function extraConnections(connections, baseConnections) {
+    const baseIds = new Set(baseConnections.flatMap(c => readId(c) ?? []));
+    return connections.filter(c => {
+        const id = readId(c);
+        return !id || !baseIds.has(id);
+    });
+}
+function readId(connection) {
+    const id = isRecord(connection) ? connection.connectionId : undefined;
+    return typeof id === 'string' ? id : undefined;
+}
+// Collects every `internetAccountId` a snapshot's file locations name, in
+// first-seen order.
+function referencedAccountIds(node, out) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            referencedAccountIds(item, out);
+        }
+    }
+    else if (isRecord(node)) {
+        if (typeof node.internetAccountId === 'string') {
+            out.add(node.internetAccountId);
+        }
+        for (const value of Object.values(node)) {
+            referencedAccountIds(value, out);
+        }
+    }
+    return out;
+}
+// The accounts a shipped file names that the recipient has no way to build.
+// Internet accounts live in the root config alone — there is no
+// `sessionInternetAccounts` for one to ride in — so a hosted-base export carries
+// exactly the accounts the base config declares, and a self-contained export
+// (`?config=none`) carries none at all. The recipient does not crash on a
+// missing one (`findAppropriateInternetAccount` returns null rather than pushing
+// an unknown type into the union), it fetches the file unauthenticated and
+// reports the 401, which is worth the sender knowing before they send the link.
+function unavailableAccountIds(session, baseAccounts) {
+    const available = new Set(baseAccounts.flatMap(a => a.internetAccountId ?? []));
+    return [...referencedAccountIds(session, new Set())].filter(id => !available.has(id));
+}
+// Adds the session-level carriers to the exported session, leaving each key out
+// entirely when it would be empty so the exported snapshot stays minimal (same
+// rule as withDeltas above).
+function withCarriedConfigs(session, plugins, connections) {
+    return {
+        ...session,
+        ...(plugins.length > 0 ? { sessionPlugins: plugins } : {}),
+        ...(connections.length > 0 ? { sessionConnections: connections } : {}),
+    };
+}
+// Decides how to hand a desktop session to jbrowse-web. When the session was
+// launched from a hosted hub config (sourceConfigUrl) that still covers all of
+// its assemblies, that config is reused as the base and only user-added/edited
+// tracks ride along; otherwise the session is made self-contained. `baseConfig`
+// is the fetched hub config (already rebased with addRelativeUris by the caller),
+// used to tell hub tracks from user-added ones and to diff edited hub tracks.
+export function planWebExport(snapshot, baseConfig) {
+    const sourceConfigUrl = snapshot.configuration?.sourceConfigUrl;
+    const assemblies = snapshot.assemblies ?? [];
+    const defaultSession = snapshot.defaultSession ?? {};
+    const priorSessionAssemblies = asArray(defaultSession.sessionAssemblies);
+    const inputTracks = snapshot.tracks ?? [];
+    const inputSessionTracks = asArray(defaultSession.sessionTracks);
+    const allTracks = inputTracks.map(withoutLocalTextSearch);
+    const allSessionTracks = inputSessionTracks.map(withoutLocalTextSearch);
+    // over the stripped lists, so a track whose only local file was its own search
+    // index is no longer read as one that has to be dropped
+    const report = analyzeWebPortability({
+        ...snapshot,
+        tracks: allTracks,
+        defaultSession: { ...defaultSession, sessionTracks: allSessionTracks },
+    });
+    const dropped = nonPortableUserTracks(report, droppableTrackIds(allTracks, allSessionTracks));
+    const keep = (t) => {
+        const id = readTrackId(t);
+        return !id || !dropped.ids.has(id);
+    };
+    const tracks = allTracks.filter(keep);
+    const priorSessionTracks = allSessionTracks.filter(keep);
+    const baseAssemblyNames = new Set((baseConfig?.assemblies ?? []).map(a => a.name));
+    const coveredByBase = !!sourceConfigUrl &&
+        !!baseConfig &&
+        assemblies.every(a => baseAssemblyNames.has(a.name));
+    // `baseConfig` is undefined only because the caller could not fetch
+    // `sourceConfigUrl` — it is the same fetch that produces it — so the two ways
+    // a hub drops out of the plan are distinguishable here without a flag.
+    const selfContainedReason = coveredByBase
+        ? undefined
+        : !sourceConfigUrl
+            ? 'noSourceConfig'
+            : baseConfig
+                ? 'assembliesNotInBase'
+                : 'baseUnreachable';
+    const plugins = snapshot.plugins ?? [];
+    const connections = snapshot.connections ?? [];
+    // defined exactly when the hostedConfigBase strategy applies, so it doubles as
+    // the strategy flag for the shared tail below
+    const hosted = coveredByBase
+        ? splitTracksAgainstBase(tracks, baseConfig.tracks ?? [])
+        : undefined;
+    const session = withCarriedConfigs(hosted
+        ? withDeltas({
+            ...defaultSession,
+            ...hostedSessionAssemblies(priorSessionAssemblies, baseAssemblyNames),
+            sessionTracks: concatTracksByTrackId(priorSessionTracks, hosted.addedTracks),
+        }, hosted.editDeltas)
+        : {
+            ...defaultSession,
+            sessionAssemblies: concatAssembliesByName(priorSessionAssemblies, assemblies),
+            sessionTracks: concatTracksByTrackId(priorSessionTracks, tracks),
+        }, hosted ? extraPlugins(plugins, baseConfig?.plugins ?? []) : plugins, hosted
+        ? extraConnections(connections, asArray(baseConfig?.connections))
+        : connections);
+    return {
+        strategy: hosted ? 'hostedConfigBase' : 'selfContained',
+        configUrl: hosted ? sourceConfigUrl : undefined,
+        webBaseUrl: resolveWebBaseUrl(snapshot.configuration?.webExportUrl),
+        session,
+        droppedTracks: dropped.names,
+        // Re-run detection over the session that will actually ship rather than
+        // filtering the input report by trackId. The two are not the same set, in
+        // both directions: a hosted-base export leaves the config's assemblies
+        // behind (their local files are the base's problem, not the recipient's)
+        // but still ships the prior session's `sessionAssemblies`, and either
+        // strategy ships `connectionTrackConfigs` that the droppable-track filter
+        // above never touches. Anything non-portable still present here survived
+        // the drop and so blocks the session by definition.
+        blockingFiles: distinctNames(analyzeWebPortability(session).nonPortable),
+        selfContainedReason,
+        droppedTextIndexes: [
+            ...new Set([
+                ...strippedTextIndexNames(inputTracks, allTracks),
+                ...strippedTextIndexNames(inputSessionTracks, allSessionTracks),
+            ]),
+        ],
+        revertedAssemblies: hosted
+            ? assembliesRevertedToBase(assemblies, priorSessionAssemblies, baseConfig?.assemblies ?? [])
+            : [],
+        unavailableAccounts: unavailableAccountIds(session, hosted ? (baseConfig?.internetAccounts ?? []) : []),
+    };
+}
+// The deployed jbrowse-web the desktop "export to web" action targets. Stable
+// per the maintainers; a future target will be added alongside, not replace it.
+export const DEFAULT_WEB_BASE_URL = 'https://jbrowse.org/code/jb2/latest/';
+// Where an export opens. A config can point its users at a different jbrowse-web
+// through the desktop-only `webExportUrl` slot — a site that runs its own
+// deployment, and whose data may only be reachable from it.
+//
+// A value that isn't an absolute http(s) url falls back rather than throwing:
+// this runs inside the export, and a typo in a config slot must not be able to
+// make exporting impossible. Same posture as the base-config fetch, which logs
+// and falls back to a self-contained export.
+function resolveWebBaseUrl(webExportUrl) {
+    if (!webExportUrl) {
+        return DEFAULT_WEB_BASE_URL;
+    }
+    try {
+        const url = new URL(webExportUrl);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new Error(`not an http(s) url: ${webExportUrl}`);
+        }
+        // The slot names a deployment, so whatever params the value came with are
+        // not part of it — and the easiest way to fill the slot is to paste a
+        // jbrowse-web address out of the browser, which carries the pasting user's
+        // own `#config=…&session=…`. Params live in the hash XOR the query string
+        // and the hash wins whenever it holds any (queryParams.ts), so a leftover
+        // hash silently opens that session instead of the exported one.
+        url.search = '';
+        url.hash = '';
+        return url.href;
+    }
+    catch (e) {
+        console.error(e);
+        return DEFAULT_WEB_BASE_URL;
+    }
+}
+// Assembles the jbrowse-web URL for an export plan. `sessionParam` is the
+// ready-made `session` value: `share-<id>` for a short lambda link (pass its
+// `password`) or `encoded-<b64>`/`json-<json>` for an inline long link.
+// `config` points at the hosted base, or `none` for a self-contained session.
+//
+// `exportedFrom` stamps what produced the link. These links are artifacts —
+// papers, supplements, emails — and every other thing they name moves under
+// them: DEFAULT_WEB_BASE_URL is `.../latest/`, so the deployment that opens the
+// session is an unknown future build, and the hosted base config the plan
+// diffed against is fetched fresh on both ends and can be in a third state by
+// then. Pinning either is a deployment decision; recording the producer is not,
+// and it is the difference between a recipient who can say which JBrowse made
+// this and one guessing. jbrowse-web reads a fixed list of params
+// (createSessionLoader) and ignores the rest, so the stamp is inert there and
+// stays in the address bar where a reader can see it.
+//
+// The large inline modes (`encoded-`/`json-`) go in the hash fragment, which is
+// never sent to the server and so can't trip the request-line limit (HTTP 414)
+// the query string can — a self-contained export carries its own assemblies and
+// tracks and is exactly the biggest kind of session. The tiny `share-<id>` short
+// link stays in the query string. Mirrors jbrowse-web's buildShareUrl; the
+// SessionLoader reads `session=`/`config=` from either location (hash XOR query).
+export function buildWebExportUrl(
+// where the link points and what config it loads: the plan's report fields
+// (what was dropped, what reverted) are for the sender's screen, not the URL
+plan, sessionParam, options = {}) {
+    const url = new URL(plan.webBaseUrl);
+    const params = new URLSearchParams();
+    params.set('config', plan.configUrl ?? 'none');
+    params.set('session', sessionParam);
+    if (options.password) {
+        params.set('password', options.password);
+    }
+    if (options.exportedFrom) {
+        params.set('exportedFrom', options.exportedFrom);
+    }
+    const str = params.toString();
+    if (sessionParam.startsWith(SHARE_PREFIX)) {
+        url.search = str;
+    }
+    else {
+        url.hash = str;
+    }
+    return url.href;
+}

package/esm/siblingCast.d.ts

@@ -0,0 +1,14 @@
+import type { BaseRootModel } from './RootModel/BaseRootModel.ts';
+import type { BaseSession } from './Session/BaseSession.ts';
+/**
+ * `types.compose` can't thread the types of sibling mixins into one another, so
+ * a mixin that reaches members contributed by a co-composed base (`jbrowse`,
+ * `adminMode`, `session`, ...) must assert that base onto its own partial
+ * `self`. These helpers name that assertion in one place — instead of the
+ * ad-hoc inline `s as typeof s & BaseSession` scattered across mixins — so the
+ * assert target is fixed (can't drift to the wrong type) and the seam is
+ * greppable. The cast is unavoidable: it encodes the compose-time invariant
+ * that these mixins are only ever composed onto the named base.
+ */
+export declare function asSession<S>(self: S): S & BaseSession;
+export declare function asRoot<S>(self: S): S & BaseRootModel;

package/esm/siblingCast.js

@@ -0,0 +1,16 @@
+/**
+ * `types.compose` can't thread the types of sibling mixins into one another, so
+ * a mixin that reaches members contributed by a co-composed base (`jbrowse`,
+ * `adminMode`, `session`, ...) must assert that base onto its own partial
+ * `self`. These helpers name that assertion in one place — instead of the
+ * ad-hoc inline `s as typeof s & BaseSession` scattered across mixins — so the
+ * assert target is fixed (can't drift to the wrong type) and the seam is
+ * greppable. The cast is unavoidable: it encodes the compose-time invariant
+ * that these mixins are only ever composed onto the named base.
+ */
+export function asSession(self) {
+    return self;
+}
+export function asRoot(self) {
+    return self;
+}

package/esm/snapshotUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The two guards every loosely-typed snapshot walk in this package needs. A
+ * session or config snapshot arrives as `unknown` at these boundaries — it is
+ * `types.frozen` data, or a plain object read back off disk — so it is narrowed
+ * by hand rather than by MST.
+ */
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+export declare function asArray(v: unknown): unknown[];

package/esm/snapshotUtils.js

@@ -0,0 +1,12 @@
+/**
+ * The two guards every loosely-typed snapshot walk in this package needs. A
+ * session or config snapshot arrives as `unknown` at these boundaries — it is
+ * `types.frozen` data, or a plain object read back off disk — so it is narrowed
+ * by hand rather than by MST.
+ */
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}