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

package/esm/SessionSpec/loadSessionSpec.js

@@ -0,0 +1,392 @@
+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';
+function isSessionWithWorkspaceLayout(session) {
+    return ('applyLayoutSpec' in session &&
+        'setUseWorkspaces' in session &&
+        'orderViews' 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);
+}
+// use extension point named e.g. LaunchView-LinearGenomeView to initialize an
+// LGV session
+export async function loadSessionSpec({ views, sessionAssemblies = [], sessionConnections = [], sessionTracks = [], layout, sessionName, }, pluginManager) {
+    const rootModel = pluginManager.rootModel;
+    try {
+        rootModel.setSession?.({
+            name: sessionName ?? `New session ${new Date().toLocaleString()}`,
+        });
+        const { session } = rootModel;
+        // 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)) {
+            for (const assembly of sessionAssemblies) {
+                session.addSessionAssembly(assembly);
+            }
+        }
+        // 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. Two different causes, so two messages: the view type is
+        // unknown here at all (a typo, or a plugin that wasn't loaded), or it exists
+        // but nothing taught it how to launch from a spec, which the spec author
+        // can't fix, only the view's plugin can.
+        const notLaunchable = [
+            ...new Set(views.flatMap(view => pluginManager.extensionPoints.has(`LaunchView-${view.type}`)
+                ? []
+                : [view.type])),
+        ];
+        // the record's `has`, not getElementType, which throws on an unregistered
+        // name rather than returning undefined
+        const viewTypes = pluginManager.getElementTypeRecord('view');
+        const unknown = notLaunchable.filter(type => !viewTypes.has(type));
+        const noLauncher = notLaunchable.filter(type => viewTypes.has(type));
+        if (unknown.length) {
+            session?.notifyError(`Unknown view type(s) in session spec: ${unknown.join(', ')}. The plugin providing the view may be missing, or the type may be misspelled.`);
+        }
+        if (noLauncher.length) {
+            session?.notifyError(`View type(s) ${noLauncher.join(', ')} cannot be launched from a session spec: no LaunchView extension point is registered for them.`);
+        }
+        // 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.
+        const specViews = views.map(({ init, ...view }) => {
+            if (init) {
+                console.warn(legacyInitMessage(view.type));
+            }
+            return init ? { ...init, ...view } : view;
+        });
+        // 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.
+        //
+        // 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.
+        //
+        // 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 view type declares its properties on a state model
+        // that is not loaded yet, so it is loaded first — the launch below would
+        // have loaded it anyway.
+        await Promise.all(specViews
+            .filter(({ type }) => viewTypes.has(type))
+            .map(({ type }) => pluginManager.getViewType(type).loadStateModel()));
+        for (const { type, ...view } of specViews) {
+            const accepted = viewTypes.has(type)
+                ? pluginManager.getViewType(type).acceptedKeys
+                : undefined;
+            const unknown = accepted
+                ? Object.keys(view).filter(key => !accepted.includes(key))
+                : [];
+            if (unknown.length) {
+                session?.notifyError(unknownKeysMessage(type, unknown));
+            }
+        }
+        // Launch sequentially and record the id 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. `type` is the dispatch key, not a setting: forwarding
+        // it would land in the view's launch blob and trip the spurious
+        // "ignored unknown key(s): type" warning meant to catch typos.
+        // `displayName` is applied here rather than forwarded because it is a base
+        // view prop every view type has, so one path covers all of them (including
+        // plugin-provided types whose launcher never heard of it).
+        // 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;
+        }
+        const createdViewIds = [];
+        for (const { type, displayName, ...view } of specViews) {
+            const before = new Set(session?.views.map(v => v.id));
+            // Strict so a launch handler that throws (missing/invalid assembly,
+            // unresolved track, ...) surfaces as a snackbar 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. Per-view try/catch so one bad view doesn't abort the rest.
+            try {
+                await pluginManager.evaluateAsyncExtensionPointStrict(`LaunchView-${type}`, {
+                    ...view,
+                    session,
+                });
+            }
+            catch (e) {
+                console.error(e);
+                session?.notifyError(`Failed to launch ${type} view: ${e}`, e);
+            }
+            const created = session?.views.filter(v => !before.has(v.id)) ?? [];
+            // The entry's own view, when its launcher created others beside it: a
+            // connected ProteinView's name went to the genome view it opened first,
+            // and the structure came up "Untitled view".
+            const named = created.find(v => v.type === type) ?? created[0];
+            if (named && displayName) {
+                named.setDisplayName(displayName);
+            }
+            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 (isSessionWithWorkspaceLayout(session)) {
+                // Enable workspaces mode for this session only — a spec URL shouldn't
+                // rewrite the visitor's own preference
+                session.setUseWorkspaces(true);
+                // A tab's `viewIds` is membership, not order: a tab renders its views
+                // in `session.views` order (WorkspaceContainer's `viewsOf`, and
+                // `viewIdsForTab`). So the top-to-bottom order a spec panel states —
+                // `viewIds` is documented as "the views to stack vertically in one tab"
+                // — only takes effect if it is applied to `session.views`, which is
+                // what `applyLayoutSpec`'s return value is for. Drop this call and the
+                // stated order is silently ignored: the tree holds it, nothing reads
+                // it, and the views come back in launch order with no diagnostic.
+                // 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, after `setUseWorkspaces(true)` had already
+                // run, and report itself as the session's error with the views left
+                // unordered. The layout is one statement in the spec; losing it should
+                // cost the spec its layout and nothing else.
+                try {
+                    session.orderViews(session.applyLayoutSpec(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,13 @@
+import type { LayoutNode, ViewSpec } from './types.ts';
+export interface ParsedSessionSpec {
+    configUrl?: string;
+    spec: {
+        views: ViewSpec[];
+        sessionAssemblies?: Record<string, unknown>[];
+        sessionConnections?: Record<string, unknown>[];
+        sessionTracks?: Record<string, unknown>[];
+        layout?: LayoutNode;
+    };
+    sessionName?: string;
+}
+export declare function parseSessionSpecUrl(input: string): ParsedSessionSpec;

package/esm/SessionSpec/parseSessionSpecUrl.js

@@ -0,0 +1,196 @@
+import { buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, } from './lgvUrlInit.js';
+// jbrowse-web keeps its URL params in the hash fragment XOR the query string
+// (the inline `encoded-`/`json-`/`spec-` sessions live in the hash to dodge the
+// server request-line limit; short `share-` links stay in the query). Read from
+// whichever the link uses so a pasted hash-form link parses the same as a
+// query-form one, instead of tripping the "no session in it" error below.
+//
+// This MUST stay identical to jbrowse-web's own reader (`useQueryParam.ts`
+// `paramLocation`: `hash.includes('=') ? hash : search`) — that module's whole
+// point, and this file's, is that a URL resolves the same everywhere. The XOR is
+// a documented invariant its producers (`buildShareUrl`) guarantee, so a
+// both-present link is a non-case; don't "harden" this into a merge that would
+// diverge from the canonical parser.
+function linkParams(url) {
+    const hash = url.hash.slice(1);
+    return new URLSearchParams(hash.includes('=') ? hash : url.search);
+}
+// 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 = linkParams(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,
+    };
+}

package/esm/SessionSpec/types.d.ts

@@ -0,0 +1,31 @@
+import type { LayoutSpecNode } from '../WorkspaceLayout/spec.ts';
+import type { TrackInit } from '@jbrowse/core/util/tracks';
+export interface ViewSpec {
+    type: string;
+    id?: string;
+    displayName?: string;
+    tracks?: TrackInit[];
+    assembly?: string;
+    loc?: string;
+    /**
+     * @deprecated v4's nesting. Write every setting directly on the view object;
+     * this is unwrapped on the way in and warns.
+     */
+    init?: Record<string, unknown>;
+}
+/**
+ * A spec's `layout`: the one layout shape, with a leaf's `views` counting into
+ * the spec's own `views` array (an index names every view that entry created)
+ * or naming a view id the spec pinned with `id`.
+ *
+ * ```json
+ * {
+ *   "direction": "horizontal",
+ *   "children": [
+ *     { "views": [0, 1], "size": 70 },
+ *     { "views": [2], "size": 30 }
+ *   ]
+ * }
+ * ```
+ */
+export type LayoutNode = LayoutSpecNode;

package/esm/SessionSpec/types.js

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

package/esm/WorkspaceLayout/LayoutRenderer.d.ts

@@ -0,0 +1,24 @@
+import type { WorkspaceLayout } from './model.ts';
+import type { PanelChrome } from './panelChrome.ts';
+import type { LayoutTree } from './tree.ts';
+import type { DragState } from './useLayoutDrag.ts';
+/**
+ * The layout, rendered. There is no imperative api and no event to listen to:
+ * the tree is state, this is a function of it, and a gesture is an action.
+ *
+ * Sizes are `flex-grow`, which is why there is no resize handling anywhere in
+ * here. A branch's children divide its space in proportion to their `size`
+ * whatever that space becomes, so a window resize is the browser's problem —
+ * this is the layout maths dockview does in pixels, and it is the part of a
+ * grid engine most likely to be got subtly wrong.
+ */
+interface Props {
+    node: LayoutTree;
+    layout: WorkspaceLayout;
+    /** the app's half of a panel, forwarded unchanged all the way down */
+    chrome: PanelChrome;
+    /** the in-flight drag, so the cell under the pointer can show where it lands */
+    drag?: DragState;
+}
+export declare const LayoutRenderer: (props: Props) => import("react").JSX.Element;
+export {};