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

package/esm/SessionSpec/loadSessionSpec.js

@@ -0,0 +1,473 @@
+import { isSessionWithAddAssembly, isSessionWithAddSessionTrack, } from '@jbrowse/core/util';
+import { legacyInitMessage, unknownKeysMessage, } from '@jbrowse/core/util/withLaunchInput';
+import { isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { when } from 'mobx';
+// A spec `layout` needs `layoutViews`, which a session composing
+// WorkspaceLayoutMixin and MultipleViewsSessionMixin has and an embedded
+// product's does not. It is looked up behind an `in` guard, so renaming it
+// without renaming it here makes every spec layout silently decline rather than
+// fail to compile; see app-core/src/WorkspaceLayout/CLAUDE.md.
+function hasLayoutViews(session) {
+    return 'layoutViews' in session;
+}
+function isSessionWithSpecConnections(session) {
+    return ('addConnectionConf' in session &&
+        'makeConnection' in session &&
+        'connectionInstances' in session);
+}
+/**
+ * Register `&sessionTracks=` / a spec's `sessionTracks` into a session.
+ *
+ * Exported because the hub launch needs it too and must not reimplement it.
+ *
+ * A track that fails to register does not cost the caller the rest of them —
+ * same reasoning as the per-connection and per-view try/catch around it, one
+ * layer down.
+ */
+export function addSessionTracks(session, tracks) {
+    if (!tracks.length) {
+        return;
+    }
+    if (!isSessionWithAddSessionTrack(session)) {
+        session?.notifyError('This link has "sessionTracks", but this application cannot add tracks to a session');
+        return;
+    }
+    for (const track of tracks) {
+        const label = typeof track.trackId === 'string' ? track.trackId : '?';
+        try {
+            session.addSessionTrackConf(track);
+        }
+        catch (e) {
+            console.error(e);
+            session.notifyError(`Track "${label}" has an invalid configuration: ${e}`, e);
+        }
+    }
+}
+// A connection supplies assemblies and tracks that the spec's views go on to
+// reference by name, and it supplies them from a fetch. Launching a view before
+// that fetch lands gives it an assembly that doesn't exist yet ("Assembly X not
+// found") and a `tracks` list whose ids don't resolve yet.
+//
+// Causal, not timed: every connection reports `loading` from its own
+// afterAttach until its connect() promise settles, success or failure, so this
+// proceeds the moment the last one is done and never waits on one that failed.
+// A session destroyed mid-wait (a StrictMode remount, a session swap) resolves
+// it too — reading a detached node throws, and here that would land in the
+// caller's catch and report a spurious error against the *new* session.
+async function whenConnectionsSettle(session) {
+    // isStateTreeNode first: the liveness question only applies to a real MST
+    // session, and this is called with plain object sessions under test
+    const gone = () => isStateTreeNode(session) && !isAlive(session);
+    await when(() => gone() || session.connectionInstances.every(conn => !conn.loading));
+    return !gone();
+}
+// Resolve a spec layout's view indexes to ids before `applyLayoutSpec` counts
+// them into `session.views`, which is a different list: a spec index names a
+// spec entry, and `createdViewIds[i]` is EVERY view the i-th entry created, in
+// creation order. A connected ProteinView creates its genome view and then
+// itself, and the index names both — stacked in one cell — where recording one
+// id per entry left the structure unaddressable, in no cell, and the panel
+// naming it empty. A string is a view id and passes through; a reference that
+// resolves to nothing is dropped here after `unresolvedLayoutRefs` reported it.
+function convertLayoutNode(node, createdViewIds, knownIds, pinnedIds) {
+    const { views, children, ...rest } = node;
+    return {
+        ...rest,
+        ...(views === undefined
+            ? {}
+            : {
+                views: Array.isArray(views)
+                    ? views.flatMap(ref => typeof ref === 'number'
+                        ? (createdViewIds[ref] ?? []).filter(id => !pinnedIds.has(id))
+                        : knownIds.has(ref)
+                            ? [ref]
+                            : [])
+                    : views,
+            }),
+        ...(children === undefined
+            ? {}
+            : {
+                children: Array.isArray(children)
+                    ? children.map(child => convertLayoutNode(child, createdViewIds, knownIds, pinnedIds))
+                    : children,
+            }),
+    };
+}
+// An index names every view its entry created, so the entry that opens a genome
+// view beside its own puts BOTH in the cell naming it — which is the point, and
+// is wrong the moment another cell names one of them by id. `{views:[0]}` next
+// to `{views:['structure']}` is the obvious spelling of "genome left, structure
+// right", and expanding the index blind seats the structure in both cells: two
+// React trees and two GPU contexts for one model, which `resolveLayoutSpec` now
+// refuses outright. An id stated by hand is the more specific statement, so it
+// wins its view and the index gives it up.
+function pinnedLayoutIds(node, knownIds) {
+    return [
+        ...(Array.isArray(node.views)
+            ? node.views.filter((ref) => typeof ref === 'string' && knownIds.has(ref))
+            : []),
+        ...(Array.isArray(node.children)
+            ? node.children.flatMap(child => pinnedLayoutIds(child, knownIds))
+            : []),
+    ];
+}
+// A layout index is a position in the spec's `views` array, so one past the end
+// (or negative) is an authoring slip that would otherwise silently drop that
+// view from the layout, or, if every reference in a panel is bad, leave an
+// empty panel with no clue why. An id names a view pinned with the spec's `id`
+// key, so one nothing created is the same slip.
+function unresolvedLayoutRefs(node, viewCount, knownIds) {
+    // Array-guarded rather than `?.`: a hand-written `views: 0` is non-nullish,
+    // so `?.` does not short-circuit and `(0).filter` threw a raw TypeError out
+    // of this validator — past `resolveLayoutSpec`, which has a real message for
+    // that exact slip and never got to say it.
+    return [
+        ...(Array.isArray(node.views)
+            ? node.views.filter(ref => typeof ref === 'number'
+                ? ref < 0 || ref >= viewCount
+                : !knownIds.has(ref))
+            : []),
+        ...(Array.isArray(node.children)
+            ? node.children.flatMap(child => unresolvedLayoutRefs(child, viewCount, knownIds))
+            : []),
+    ];
+}
+// A `tabs` node shares one cell between its children rather than dividing the
+// space, so a `size` on one of them describes nothing. This is the ONLY case
+// left where a stated size is dropped.
+//
+// It used to be far wider — dockview forces its branches to alternate
+// orientation by depth, so a nested container had no branch to size against and
+// the whole sizing pass bailed, top-level numbers included. That is gone
+// (ADR-068): the spec's nesting is the tree's nesting, `size` applies wherever
+// it is written, and a bare sibling takes an equal share of the remainder. The
+// wider check outlived the limitation it reported and told an author their
+// nested or partial sizes had been ignored while the layout honoured them —
+// which is also what website/docs/urlparams.md promises.
+function unsizeableLayoutNodes(layout) {
+    const children = Array.isArray(layout.children) ? layout.children : [];
+    const sizedTabsChild = layout.direction === 'tabs' && children.some(c => c.size !== undefined);
+    return sizedTabsChild || children.some(unsizeableLayoutNodes);
+}
+// The other statement a `tabs` node cannot take literally, and the one that
+// used to fail silently rather than partially: a tab holds a FLAT stack of
+// views, so a container child has no split to become. Containers nest
+// arbitrarily deep everywhere else — the docs say so — which is what makes one
+// here easy to write. Its views are flattened into a single tab now; they used
+// to be dropped from the layout, after which homing swept them into whichever
+// tab happened to be showing, so the arrangement was wrong with nothing said.
+function flattenedTabsContainers(layout) {
+    const children = Array.isArray(layout.children) ? layout.children : [];
+    const nestedTabsChild = layout.direction === 'tabs' && children.some(c => c.children !== undefined);
+    return nestedTabsChild || children.some(flattenedTabsContainers);
+}
+function unknownViewTypesMessage(types) {
+    return `Unknown view type(s) in session spec: ${types.join(', ')}. The plugin providing the view may be missing, or the type may be misspelled.`;
+}
+function noLauncherMessage(types) {
+    return `View type(s) ${types.join(', ')} cannot be launched from a session spec: no LaunchView extension point is registered for them.`;
+}
+/**
+ * Why one view type cannot launch from a spec here, or nothing. Two causes,
+ * two messages: the type is unknown at all (a typo, or a plugin that was not
+ * loaded), or it exists but nothing taught it how to launch from a spec, which
+ * only the view's plugin can fix.
+ */
+export function viewTypeProblem(pluginManager, type) {
+    if (pluginManager.extensionPoints.has(`LaunchView-${type}`)) {
+        return undefined;
+    }
+    // the record's `has`, not getElementType, which throws on an unregistered
+    // name rather than returning undefined
+    return pluginManager.getElementTypeRecord('view').has(type)
+        ? noLauncherMessage([type])
+        : unknownViewTypesMessage([type]);
+}
+// v4 nested a view's settings under `init`. A spec never becomes a snapshot, so
+// `withLaunchInput`'s unwrap never runs on one and this surface does it itself,
+// in the same order: the flat spelling wins.
+function flattenSpecView(spec) {
+    const { init, ...view } = spec;
+    if (init) {
+        console.warn(legacyInitMessage(view.type));
+    }
+    return init ? { ...init, ...view } : view;
+}
+/**
+ * A spec view entry as its launcher takes it, and what its type does not take.
+ *
+ * The same classification a view snapshot gets, run here because a spec never
+ * becomes one: `LaunchView-<type>` takes these keys as arguments, so
+ * `withLaunchInput`'s partition never sees them and nothing names a typo.
+ * `{type: 'LinearGenomeView', asembly: 'volvox'}` reported only the launcher's
+ * downstream "No assembly provided", on the one surface written by hand with no
+ * compiler and no editor behind it.
+ *
+ * A view type that registers no launch keys classifies nothing: its launcher's
+ * vocabulary is undeclared, so every argument would read as a typo. A lazily
+ * registered type declares its properties on a state model that is not loaded
+ * yet, so it is loaded first — the launch would have loaded it anyway.
+ */
+export async function launchableSpecView(pluginManager, spec) {
+    const flat = flattenSpecView(spec);
+    if (!pluginManager.getElementTypeRecord('view').has(flat.type)) {
+        return { view: flat };
+    }
+    const viewType = pluginManager.getViewType(flat.type);
+    await viewType.loadStateModel();
+    const accepted = viewType.acceptedKeys;
+    if (!accepted) {
+        return { view: flat };
+    }
+    const { view, problem } = readAssemblyNames(flat, accepted);
+    const { type, ...keyed } = view;
+    const unknown = Object.keys(keyed).filter(key => !accepted.includes(key));
+    const problems = [
+        ...(unknown.length ? [unknownKeysMessage(type, unknown)] : []),
+        ...(problem ? [problem] : []),
+    ];
+    return { view, problem: problems.join('; ') || undefined };
+}
+// An agent reads `assemblyNames` off the live view and writes it back into a
+// spec, where the key the entry takes is `assembly`. One name is that assembly;
+// several are a question one view cannot answer.
+function readAssemblyNames(view, accepted) {
+    const { assemblyNames, ...rest } = view;
+    // Array.isArray, not a length check: a hand-written `assemblyNames: 'volvox'`
+    // has a length too, and reached .join below — a throw, which this one outer
+    // catch turns into every remaining view and the layout being lost
+    if (!Array.isArray(assemblyNames) ||
+        !assemblyNames.length ||
+        !accepted.includes('assembly') ||
+        accepted.includes('assemblyNames')) {
+        return { view };
+    }
+    return assemblyNames.length === 1
+        ? { view: { ...rest, assembly: rest.assembly ?? assemblyNames[0] } }
+        : {
+            view: rest,
+            problem: `${view.type} takes one "assembly", and assemblyNames names ${assemblyNames.length} (${assemblyNames.join(', ')}) — pass assembly, one view per assembly`,
+        };
+}
+/**
+ * Launch one spec view into the session through its `LaunchView-<type>`
+ * extension point, the same door `loadSessionSpec` uses for each of its views
+ * — so `jb.addView` and a spec agree on what a view entry means, a
+ * ProteinView's `connectedView` included.
+ *
+ * Strict so a launch handler that throws (missing/invalid assembly, unresolved
+ * track, ...) is returned as a failure instead of being swallowed by the plain
+ * extension-point runner, which would leave a silent empty session. A handler
+ * that legitimately no-ops returns normally and is unaffected.
+ *
+ * `created` is EVERY view the launch added, in creation order: a connected
+ * ProteinView creates its genome view and then itself. `view` is the entry's
+ * own, the one of the spec's type, which is where `displayName` goes — it used
+ * to land on the genome view a ProteinView opened first, and the structure came
+ * up "Untitled view". `type` is the dispatch key, not a setting: forwarding it
+ * would land in the view's launch blob and trip the "ignored unknown key(s):
+ * type" warning meant to catch typos.
+ */
+export async function launchSpecView(session, pluginManager, spec) {
+    const { type, displayName, ...view } = spec;
+    const before = new Set(session?.views.map(v => v.id));
+    let failure;
+    try {
+        await pluginManager.evaluateAsyncExtensionPointStrict(`LaunchView-${type}`, {
+            ...view,
+            session,
+        });
+    }
+    catch (e) {
+        console.error(e);
+        failure = { message: `Failed to launch ${type} view: ${e}`, cause: e };
+    }
+    const created = session?.views.filter(v => !before.has(v.id)) ?? [];
+    const named = created.find(v => v.type === type) ?? created[0];
+    if (named && displayName) {
+        named.setDisplayName(displayName);
+    }
+    return { created, view: named, ...(failure ? { failure } : {}) };
+}
+const SPEC_KEYS = [
+    'views',
+    'sessionAssemblies',
+    'sessionConnections',
+    'sessionTracks',
+    'layout',
+    'sessionName',
+];
+export async function loadSessionSpec(spec, pluginManager) {
+    const { views, sessionAssemblies = [], sessionConnections = [], sessionTracks = [], layout, sessionName, } = spec;
+    const rootModel = pluginManager.rootModel;
+    try {
+        rootModel.setSession?.({
+            name: sessionName ?? `New session ${new Date().toLocaleString()}`,
+        });
+        const { session } = rootModel;
+        // `tracks` for sessionTracks, `assemblies` for sessionAssemblies, `name`
+        // for sessionName: a top-level key this spec does not define used to be
+        // dropped by the destructure above with nothing said, on the one door every
+        // agent-facing text names first. Reported like the misplaced keys below,
+        // rather than thrown, so the rest of the spec still loads.
+        const unknownKeys = Object.keys(spec).filter(key => !SPEC_KEYS.includes(key));
+        if (unknownKeys.length) {
+            session?.notifyError(`${unknownKeysMessage('Session spec', unknownKeys)} — it takes ${SPEC_KEYS.join(', ')}`);
+        }
+        // Assemblies first: sessionTracks and the views below reference them by
+        // name, so a self-contained spec (novel assemblies + their tracks, no
+        // hosted config) resolves only if the assemblies exist before either runs.
+        if (isSessionWithAddAssembly(session)) {
+            // Per-assembly, like connections and tracks below: an invalid config
+            // fails the array's MST type check and would otherwise cost the spec
+            // everything after it
+            for (const assembly of sessionAssemblies) {
+                try {
+                    session.addSessionAssembly(assembly);
+                }
+                catch (e) {
+                    console.error(e);
+                    const label = typeof assembly.name === 'string' ? assembly.name : '?';
+                    session.notifyError(`Assembly "${label}" has an invalid configuration: ${e}`, e);
+                }
+            }
+        }
+        // Connections after the assemblies (a connection config may name one the
+        // spec defines) and before the tracks and views, which are what reference
+        // the assemblies and tracks a connection brings in.
+        if (sessionConnections.length) {
+            if (session && isSessionWithSpecConnections(session)) {
+                // A connection type nothing registered is a typo or a missing plugin,
+                // the same authoring slip the view check below reports. Caught here
+                // because the config would otherwise fail the connection array's MST
+                // union check and throw past every per-key guard to the catch at the
+                // bottom, costing the spec its tracks, its views and its layout over
+                // one bad entry — and reporting it as a raw union-type dump.
+                const connectionTypes = pluginManager.getElementTypeRecord('connection');
+                for (const conf of sessionConnections) {
+                    const { type } = conf;
+                    const label = typeof conf.connectionId === 'string' ? conf.connectionId : '?';
+                    if (typeof type !== 'string' || !connectionTypes.has(type)) {
+                        session.notifyError(`Session spec connection "${label}" has ${typeof type === 'string'
+                            ? `unknown type "${type}". The plugin providing the connection may be missing, or the type may be misspelled.`
+                            : 'no "type".'}`);
+                        continue;
+                    }
+                    // Per-connection, for the same reason each view gets its own: one
+                    // unusable connection shouldn't cost the spec everything after it.
+                    try {
+                        // silent whenever the spec launches views of its own: a connection
+                        // that opens one on connect (a single-file UCSC hub goes to its
+                        // `defaultPos`) would otherwise open a second view competing with
+                        // the one the spec asked for. With no views the spec is only asking
+                        // to attach the connection, so let it do its own thing.
+                        session.makeConnection(session.addSessionConnectionConf
+                            ? session.addSessionConnectionConf(conf)
+                            : session.addConnectionConf(conf), { silent: views.length > 0 });
+                    }
+                    catch (e) {
+                        console.error(e);
+                        session.notifyError(`Connection "${label}" has an invalid configuration: ${e}`, e);
+                    }
+                }
+            }
+            else {
+                session?.notifyError('Session spec has "sessionConnections", but this application cannot add connections to a session');
+            }
+        }
+        addSessionTracks(session, sessionTracks);
+        // A view type with no registered LaunchView-<type> extension point makes
+        // evaluateAsyncExtensionPoint a silent no-op, leaving an empty session with
+        // no diagnostic. Reported once per type, not per view.
+        const viewTypes = pluginManager.getElementTypeRecord('view');
+        const notLaunchable = [
+            ...new Set(views.flatMap(view => viewTypeProblem(pluginManager, view.type) ? [view.type] : [])),
+        ];
+        const unknown = notLaunchable.filter(type => !viewTypes.has(type));
+        const noLauncher = notLaunchable.filter(type => viewTypes.has(type));
+        if (unknown.length) {
+            session?.notifyError(unknownViewTypesMessage(unknown));
+        }
+        if (noLauncher.length) {
+            session?.notifyError(noLauncherMessage(noLauncher));
+        }
+        // Let any connection this spec registered finish before the views that
+        // reference what it supplies are launched (see whenConnectionsSettle). Gated
+        // on there being views: with none, nothing is waiting on the connection, and
+        // holding the load open until a hub finishes fetching would be pure delay —
+        // the connection is the deliverable. A session that went away while we
+        // waited has nothing left to launch into.
+        if (sessionConnections.length &&
+            views.length &&
+            session &&
+            isSessionWithSpecConnections(session) &&
+            !(await whenConnectionsSettle(session))) {
+            return;
+        }
+        // Launch sequentially and record the ids each spec view created, so the
+        // layout below can map its indices to real views. Reading session.views
+        // positionally afterwards only works while every handler happens to addView
+        // synchronously and in order; capturing the delta per launch instead is
+        // correct even if a handler awaits or adds an auxiliary view, and lets a
+        // later spec view (e.g. a connected MsaView) reference an earlier one that
+        // now already exists.
+        //
+        // An unknown key is an ERROR rather than the snapshot path's warning: this
+        // surface's misplaced keys already report as errors, and the launcher's own
+        // failure lands as an error a line later — a warning under it reads as the
+        // lesser of the two, when it is the cause. Per view, so one bad view
+        // doesn't cost the rest.
+        const createdViewIds = [];
+        for (const spec of views) {
+            const { view, problem } = await launchableSpecView(pluginManager, spec);
+            if (problem) {
+                session?.notifyError(problem);
+            }
+            const { created, failure } = await launchSpecView(session, pluginManager, view);
+            if (failure) {
+                session?.notifyError(failure.message, failure.cause);
+            }
+            createdViewIds.push(created.map(v => v.id));
+        }
+        if (layout && session) {
+            const knownIds = new Set(createdViewIds.flat());
+            const bad = unresolvedLayoutRefs(layout, views.length, knownIds);
+            const badIndices = bad.filter(ref => typeof ref === 'number');
+            const badIds = bad.filter(ref => typeof ref === 'string');
+            if (badIndices.length) {
+                session.notifyError(`Session spec layout references view index ${badIndices.join(', ')}, but the spec has ${views.length} view(s).`);
+            }
+            if (badIds.length) {
+                session.notifyError(`Session spec layout references view id ${badIds.map(id => `"${id}"`).join(', ')}, but no view in the spec has that id (a view's "id" key pins it).`);
+            }
+            if (unsizeableLayoutNodes(layout)) {
+                session.notify('Session spec layout: a "tabs" node shares one cell between its children rather than dividing the space, so the "size" on them was ignored. The rest of the layout is unaffected.', 'info');
+            }
+            if (flattenedTabsContainers(layout)) {
+                session.notify('Session spec layout: a "tabs" node gives each child one tab, and a tab holds a flat stack of views — so a container inside one was flattened into a single tab rather than splitting it. The rest of the layout is unaffected.', 'info');
+            }
+            if (hasLayoutViews(session)) {
+                // Its own try/catch, the same reasoning as the per-view one above: the
+                // resolver throws for a layout it will not arrange, and this is the
+                // LAST thing the spec does — so an unarrangeable layout used to take
+                // the whole load's catch and report itself as the session's error. The
+                // layout is one statement in the spec; losing it should cost the spec
+                // its layout and nothing else.
+                try {
+                    session.layoutViews(convertLayoutNode(layout, createdViewIds, knownIds, new Set(pinnedLayoutIds(layout, knownIds))));
+                }
+                catch (e) {
+                    console.error(e);
+                    session.notifyError(`Session spec layout: ${e}`, e);
+                }
+            }
+            else {
+                session.notifyError('Session spec has a "layout", but this application does not support workspace layouts');
+            }
+        }
+    }
+    catch (e) {
+        console.error(e);
+        rootModel.session?.notifyError(`${e}`, e);
+    }
+}

package/esm/SessionSpec/parseSessionSpecUrl.d.ts

@@ -0,0 +1,7 @@
+import type { SessionSpec } from './loadSessionSpec.ts';
+export interface ParsedSessionSpec {
+    configUrl?: string;
+    spec: Omit<SessionSpec, 'sessionName'>;
+    sessionName?: string;
+}
+export declare function parseSessionSpecUrl(input: string): ParsedSessionSpec;

package/esm/SessionSpec/parseSessionSpecUrl.js

@@ -0,0 +1,181 @@
+import { readAllQueryParams } from '../queryParams.js';
+import { buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, } from './lgvUrlInit.js';
+// A `jbrowse://open?url=<web link>` wrapper carries a JBrowse Web url for
+// Desktop's protocol handler to unwrap. Every page that offers an "Open in
+// Desktop" button puts that link right next to the plain web one — the docs'
+// figure dialogs, genomes.jbrowse.org — so the link someone copies and pastes
+// into "Open JBrowse Web link..." is as often this as the url inside it. It
+// parses as a perfectly good URL whose query has no `session`, which reported
+// "that link has no session in it" about a link that does. Unwrap it instead.
+//
+// Restricted to http(s), and to a single unwrap, for the reason Desktop's own
+// parser is (products/jbrowse-desktop/electron/launchTarget.ts, which gates the
+// OS-delivered copy of this and cannot import from here — it is bundled into the
+// Electron main process): the payload comes from whatever handed us the link.
+function unwrapProtocolUrl(url) {
+    if (url.protocol !== 'jbrowse:') {
+        return url;
+    }
+    const wrapped = url.searchParams.get('url');
+    if (!wrapped) {
+        return url;
+    }
+    try {
+        const inner = new URL(wrapped);
+        return inner.protocol === 'http:' || inner.protocol === 'https:'
+            ? inner
+            : url;
+    }
+    catch {
+        return url;
+    }
+}
+function resolveConfig(params, url) {
+    const config = params.get('config');
+    return {
+        // a relative config (e.g. `test_data/volvox/config.json`) is served by the
+        // instance the link points at, so resolve it there rather than handing back
+        // a path nothing outside that instance could fetch.
+        //
+        // `config=none` is jbrowse-web's "load no config at all" sentinel
+        // (SessionLoader.fetchConfig), and the form a self-contained spec link has to
+        // take — omitting `config` entirely makes web fall back to its own
+        // config.json. Treated as no config here, not resolved, which would hand the
+        // caller `<instance>/none` to fetch.
+        configUrl: config && config !== 'none' ? new URL(config, url.href).href : undefined,
+    };
+}
+/**
+ * The spec a link with no `session=` describes — or the error explaining why it
+ * describes none.
+ *
+ * The branches below are in jbrowse-web's own ranking (SessionLoader's
+ * loadSessionByType), and have to be, because a link can carry several of these
+ * at once and which one wins decides what the link means:
+ *
+ * 1. `&extendSession=true` alongside the shorthand, which outranks even a hub.
+ * 2. `&hubURL=`, above the bare shorthand, because a hub is the only param that
+ *    brings its own assemblies and tracks — a link carrying both is asking to
+ *    navigate *inside* the hub. Ranking the shorthand first builds a bare LGV
+ *    and drops the hub with no diagnostic.
+ * 3. the shorthand on its own.
+ */
+function shorthandSpec(params) {
+    const init = buildLgvInitFromParams(params);
+    // what makes a link a jb1-style one, the same test as jbrowse-web's
+    // isJb1StyleSession. The rest of the shorthand only modifies a view; none of
+    // it can conjure one.
+    const isJb1Style = init.loc !== undefined || init.assembly !== undefined;
+    // `&extendSession=true` means "apply this shorthand to the config's own
+    // defaultSession", and there is no honest way to do that here: this builds a
+    // session spec, and loadSessionSpec replaces the session rather than
+    // navigating one the config supplied. Opening the view without the
+    // defaultSession's curated tracks would quietly be a different session than
+    // the link asks for, so say so instead — and say what to remove, since the
+    // link works fine without it.
+    //
+    // Gated on the shorthand being present for the same reason web's branch is:
+    // the param names the default session as the thing to navigate, and with no
+    // loc or assembly there is no navigation to apply to it.
+    if (isJb1Style && params.get('extendSession') === 'true') {
+        throw new Error('That link uses "&extendSession=true", which layers its location onto a defaultSession that only the JBrowse Web instance it points at can supply. Remove that parameter to open just the view the link describes.');
+    }
+    const hubURL = readHubUrlParam(params.get('hubURL') ?? undefined);
+    if (hubURL.length) {
+        // A track hub is a session connection, which a spec has carried since
+        // sessionConnections landed. So this is no longer the dead end it was
+        // ("that's a track hub, go add it by hand") — the hub attaches, and
+        // loadSessionSpec waits for it to settle before launching anything, because
+        // the assemblies and tracks the view below names are ones the hub brings.
+        return {
+            sessionConnections: hubURL.map(hubConnectionSpec),
+            sessionTracks: readSessionTracks(params),
+            // Only with an assembly. The launcher resolves everything against one,
+            // and a hub's assemblies are genome ids only the hub carries, so `&loc=`
+            // alone has nothing to launch against. Leaving the list empty is what
+            // makes loadSessionSpec register the connection non-silently, so the hub
+            // opens at its own defaultPos — the best guess available without a name,
+            // and what jbrowse-web does with the same link.
+            views: init.assembly === undefined ? [] : [lgvSpec(init)],
+        };
+    }
+    if (!isJb1Style) {
+        throw new Error('That link has no session in it. Copy a JBrowse Web link that contains "&session=spec-...", or one with "&assembly=" and "&loc=".');
+    }
+    return {
+        // `&sessionTracks=` carries whole track configs the views then reference by
+        // id, exactly as in a spec link
+        sessionTracks: readSessionTracks(params),
+        views: [lgvSpec(init)],
+    };
+}
+// The init keys are LGV `InitState` ones the LaunchView-LinearGenomeView
+// extension point partitions for itself; ViewSpec carries only what every view
+// type has, which is why this spreads rather than naming them.
+function lgvSpec(init) {
+    return { type: 'LinearGenomeView', ...init };
+}
+function readSessionTracks(params) {
+    const sessionTracks = params.get('sessionTracks');
+    if (!sessionTracks) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(sessionTracks);
+    }
+    catch (e) {
+        throw new Error(`The "sessionTracks" in that link isn't valid JSON: ${e}`, {
+            cause: e,
+        });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('The "sessionTracks" in that link is not a list of track configurations.');
+    }
+    return parsed;
+}
+export function parseSessionSpecUrl(input) {
+    let url;
+    try {
+        url = unwrapProtocolUrl(new URL(input.trim()));
+    }
+    catch {
+        throw new Error(`Not a URL: ${input}`);
+    }
+    const params = readAllQueryParams(url);
+    const session = params.get('session');
+    if (!session) {
+        return {
+            ...resolveConfig(params, url),
+            spec: shorthandSpec(params),
+            sessionName: params.get('sessionName') ?? undefined,
+        };
+    }
+    if (!session.startsWith('spec-')) {
+        const kind = /^(share|encoded|local|json)-/.exec(session)?.[1];
+        throw new Error(kind
+            ? `This is a "${kind}" session link, which only the JBrowse Web instance that created it can open. Session-spec links (&session=spec-...) work here.`
+            : 'Unrecognized session in that link; only session-spec links (&session=spec-...) can be opened here.');
+    }
+    let spec;
+    try {
+        spec = JSON.parse(session.slice('spec-'.length));
+    }
+    catch (e) {
+        throw new Error(`The session spec in that link isn't valid JSON: ${e}`, {
+            cause: e,
+        });
+    }
+    // `views: []` is legitimate and deliberate — it opens a session showing the
+    // import form (several docs figures are exactly that). Only a spec with no
+    // views *key* is malformed, and would otherwise build an empty session that
+    // reads as a silent failure.
+    if (!Array.isArray(spec.views)) {
+        throw new Error('The session spec in that link has no "views" list, so there is nothing to open.');
+    }
+    return {
+        ...resolveConfig(params, url),
+        spec,
+        sessionName: params.get('sessionName') ?? undefined,
+    };
+}