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

package/esm/SessionSpec/parseSessionSpecUrl.d.ts

@@ -1,13 +1,7 @@
-import type { LayoutNode, ViewSpec } from './types.ts';
+import type { SessionSpec } from './loadSessionSpec.ts';
 export interface ParsedSessionSpec {
     configUrl?: string;
-    spec: {
-        views: ViewSpec[];
-        sessionAssemblies?: Record<string, unknown>[];
-        sessionConnections?: Record<string, unknown>[];
-        sessionTracks?: Record<string, unknown>[];
-        layout?: LayoutNode;
-    };
+    spec: Omit<SessionSpec, 'sessionName'>;
     sessionName?: string;
 }
 export declare function parseSessionSpecUrl(input: string): ParsedSessionSpec;

package/esm/SessionSpec/parseSessionSpecUrl.js

@@ -1,20 +1,5 @@
+import { readAllQueryParams } from '../queryParams.js';
 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'
@@ -157,7 +142,7 @@ export function parseSessionSpecUrl(input) {
     catch {
         throw new Error(`Not a URL: ${input}`);
     }
-    const params = linkParams(url);
+    const params = readAllQueryParams(url);
     const session = params.get('session');
     if (!session) {
         return {

package/esm/SessionSpec/types.d.ts

@@ -1,3 +1,4 @@
+import type { LayoutSpecNode } from '../WorkspaceLayout/spec.ts';
 import type { TrackInit } from '@jbrowse/core/util/tracks';
 export interface ViewSpec {
     type: string;
@@ -5,16 +6,24 @@ export interface ViewSpec {
     displayName?: string;
     tracks?: TrackInit[];
     assembly?: string;
+    /**
+     * The live view's spelling of the key above, accepted because that is where
+     * a spec gets written from: one name is the `assembly`, and several are
+     * refused naming it.
+     */
+    assemblyNames?: 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>;
 }
 /**
- * Nested layout structure for workspaces.
+ * 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`.
  *
- * A LayoutNode is either:
- * - A panel (has `views` array) - displays views stacked vertically
- * - A container (has `children` array) - arranges children horizontally or vertically
- *
- * Example - horizontal split with custom sizes:
  * ```json
  * {
  *   "direction": "horizontal",
@@ -25,9 +34,4 @@ export interface ViewSpec {
  * }
  * ```
  */
-export interface LayoutNode {
-    views?: number[];
-    direction?: 'horizontal' | 'vertical' | 'tabs';
-    children?: LayoutNode[];
-    size?: number;
-}
+export type LayoutNode = LayoutSpecNode;

package/esm/WorkspaceLayout/WorkspaceContainer.js

@@ -1,14 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Suspense, lazy, useCallback, useEffect, useMemo } from 'react';
+import { Suspense, useCallback, useEffect, useMemo } from 'react';
 import { makeStyles } from '@jbrowse/core/util/tss-react';
 import { autorun } from 'mobx';
 import { observer } from 'mobx-react';
 import ViewStack from '../ui/App/ViewStack.js';
+import { ViewLauncher } from '../ui/App/lazyParts.js';
 import { LayoutRenderer } from './LayoutRenderer.js';
 import { WorkspacePanelActions } from './WorkspacePanelActions.js';
 import { WorkspaceTab } from './WorkspaceTab.js';
 import { useLayoutDrag } from './useLayoutDrag.js';
-const ViewLauncher = lazy(() => import('../ui/App/ViewLauncher.js'));
 const useStyles = makeStyles()(theme => ({
     container: {
         height: '100%',
@@ -41,11 +41,13 @@ const useStyles = makeStyles()(theme => ({
 export const WorkspaceContainer = observer(function WorkspaceContainer({ session, }) {
     const { classes } = useStyles();
     const { drag, handlers } = useLayoutDrag(session);
+    // #region autorunInEffect
     useEffect(() => autorun(() => {
         // reads session.views itself, so it re-runs when the view set changes;
         // homeUnassignedViews is an action and would not be tracked from inside
         session.homeUnassignedViews(session.views.map(v => v.id));
     }), [session]);
+    // #endregion
     // The layout does not own views, so closing anything that holds them is
     // explicitly the pair. Stated ONCE, here, because every spelling of it is a
     // chance to drop the node and leave its views in the session forever — and

package/esm/WorkspaceLayout/WorkspaceTab.js

@@ -4,6 +4,7 @@ import { makeStyles } from '@jbrowse/core/util/tss-react';
 import { InputBase, Typography } from '@mui/material';
 import { observer } from 'mobx-react';
 import JBrowseTabMenu from '../ui/App/JBrowseTabMenu.js';
+import { viewName } from '../ui/App/viewTitle.js';
 const useStyles = makeStyles()(theme => ({
     // Only the label and its menu. The background, the selected state and the
     // hover live on the strip's own `[role=tab]` wrapper, which is where the
@@ -52,12 +53,7 @@ export function tabDisplayName(tab, views, session) {
         return 'Empty';
     }
     if (views.length === 1) {
-        const view = views[0];
-        return (view.displayName ||
-            view.assemblyNames
-                ?.map(r => session.assemblyManager.getDisplayName(r))
-                .join(',') ||
-            'View');
+        return viewName(views[0], r => session.assemblyManager.getDisplayName(r));
     }
     return `${views.length} views`;
 }

package/esm/WorkspaceLayout/model.d.ts

@@ -182,6 +182,14 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
     /**
      * Arrange the workspace as a spec states.
      *
+     * The spec is the same shape a session spec's `layout` takes: a leaf's
+     * `views` names views by index into `session.views` or by id, so
+     * `{ direction: 'horizontal', children: [{ views: [0] }, { views: [1] }] }`
+     * means here what it means in a link. A leaf spelled any other way, an
+     * index past the end or an id no view has throws rather than arranging
+     * nothing — an untyped caller used to collapse the workspace into one
+     * blank tab that way.
+     *
      * There is no `init` property and no standing request: the spec is
      * converted and *becomes* the layout, here and now. `init` existed only
      * because dockview had to be told, could not be told before it mounted,
@@ -192,16 +200,16 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
     /**
      * ViewMenu's "move to new tab": the view leaves its tab for a new one.
      *
-     * `allViewIds` is EVERY view in the session, and is required for that
-     * reason — homing drops any view the list does not name, so the
+     * `allViewIds` is EVERY view in the session, defaulting to the host's
+     * own list — homing drops any view the list does not name, so the
      * `[viewId]` default this used to carry unhomed all the others.
      */
-    moveViewToNewTab(viewId: string, allViewIds: string[]): string | undefined;
+    moveViewToNewTab(viewId: string, allViewIds?: string[]): string | undefined;
     /**
      * ViewMenu's "move to split view": the view leaves for a new cell.
      * `allViewIds` is every view in the session — see `moveViewToNewTab`.
      */
-    moveViewToSplitRight(viewId: string, allViewIds: string[]): string | undefined;
+    moveViewToSplitRight(viewId: string, allViewIds?: string[]): string | undefined;
     homeUnassignedViews(viewIds: string[]): void;
 } & {
     /**
@@ -233,6 +241,18 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
      * session spec's layout there is nothing for `orderViews` to apply.
      */
     tileViews(mode: TileMode, allViewIds: string[]): void;
+    /**
+     * #action
+     * Arrange the session's views into panels. Calls `applyLayoutSpec`,
+     * turns workspaces mode on for this session (a layout renders nowhere
+     * else), and orders `session.views` to the spec's top-to-bottom
+     * order, which tabs read their order from. Without the last two steps
+     * the layout applies but does not display, or the tabs appear in the
+     * wrong order. Leaves take view ids or indexes into `session.views`; a
+     * layout that seats no view throws rather than leaving a blank tab. A
+     * session spec's `layout` and an agent's live re-layout both call it.
+     */
+    layoutViews(spec: LayoutSpecNode): string[];
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type WorkspaceLayoutMixinType = ReturnType<typeof WorkspaceLayoutMixin>;
 export interface WorkspaceLayout extends Instance<WorkspaceLayoutMixinType> {

package/esm/WorkspaceLayout/model.js

@@ -1,7 +1,27 @@
 import { createElementId } from '@jbrowse/core/util/types/mst';
 import { cast, getSnapshot, types } from '@jbrowse/mobx-state-tree';
-import { specForPendingMove, tileLayoutSpec, treeFromSpec, viewIdsInSpec, } from './spec.js';
+import { resolveLayoutSpec, specForPendingMove, tileLayoutSpec, treeFromSpec, viewIdsInSpec, } from './spec.js';
 import { activeTabIn, addTab, addViewToTab, findTab, homeViews, moveTabToPanel, normalize, panelContainingView, panels, pruneEmptyPanel, pruneEmptyTabIn, removePanel, removeTab, removeView, renameTab, setActiveTab, setSizes, splitPanel, tabContainingView, tabs, } from './tree.js';
+function sessionViewIds(self) {
+    return self.views?.map(v => v.id);
+}
+/**
+ * A caller-supplied view list narrowed to the views the session actually has.
+ *
+ * The list is the caller's snapshot, and `applyLayoutSpec` refuses an id no
+ * view has — so a view added after the list was built, or removed between
+ * building it and the call, would throw out of a sugar action no plugin wraps.
+ * The arrangement a stale name asks for is still the one it means for every
+ * view that IS there, so the name is dropped rather than the action. A repeat
+ * is dropped for the same reason: it would seat one view in two cells, which
+ * the resolver also refuses.
+ */
+function liveViewIds(self, allViewIds) {
+    const live = sessionViewIds(self);
+    return [
+        ...new Set(live ? allViewIds.filter(id => live.includes(id)) : allViewIds),
+    ];
+}
 /**
  * #stateModel WorkspaceLayoutMixin
  *
@@ -210,6 +230,13 @@ export function WorkspaceLayoutMixin() {
          * Returns where the view came from, or `undefined` if it is not in the
          * session, in which case nothing is applied.
          */
+        function everyViewId(action, allViewIds) {
+            const ids = allViewIds ?? sessionViewIds(self);
+            if (!ids) {
+                throw new Error(`${action}(viewId, allViewIds): allViewIds is every view id in the session, and this session has no view list to default it from`);
+            }
+            return ids;
+        }
         function rehomeView(viewId, allViewIds, place) {
             const tree = home(self.tree, allViewIds);
             const from = tabContainingView(tree, viewId);
@@ -400,6 +427,14 @@ export function WorkspaceLayoutMixin() {
             /**
              * Arrange the workspace as a spec states.
              *
+             * The spec is the same shape a session spec's `layout` takes: a leaf's
+             * `views` names views by index into `session.views` or by id, so
+             * `{ direction: 'horizontal', children: [{ views: [0] }, { views: [1] }] }`
+             * means here what it means in a link. A leaf spelled any other way, an
+             * index past the end or an id no view has throws rather than arranging
+             * nothing — an untyped caller used to collapse the workspace into one
+             * blank tab that way.
+             *
              * There is no `init` property and no standing request: the spec is
              * converted and *becomes* the layout, here and now. `init` existed only
              * because dockview had to be told, could not be told before it mounted,
@@ -407,20 +442,21 @@ export function WorkspaceLayoutMixin() {
              * from the layout living somewhere this action could not reach.
              */
             applyLayoutSpec(spec) {
-                apply(treeFromSpec(spec, nextId));
+                const resolved = resolveLayoutSpec(spec, sessionViewIds(self));
+                apply(treeFromSpec(resolved, nextId));
                 self.activePanelId = panels(self.tree)[0]?.id;
-                return viewIdsInSpec(spec);
+                return viewIdsInSpec(resolved);
             },
             /**
              * ViewMenu's "move to new tab": the view leaves its tab for a new one.
              *
-             * `allViewIds` is EVERY view in the session, and is required for that
-             * reason — homing drops any view the list does not name, so the
+             * `allViewIds` is EVERY view in the session, defaulting to the host's
+             * own list — homing drops any view the list does not name, so the
              * `[viewId]` default this used to carry unhomed all the others.
              */
             moveViewToNewTab(viewId, allViewIds) {
                 const tab = { id: nextId('tab'), viewIds: [viewId] };
-                const from = rehomeView(viewId, allViewIds, (tree, at) => addTab(tree, at.panel.id, tab));
+                const from = rehomeView(viewId, everyViewId('moveViewToNewTab', allViewIds), (tree, at) => addTab(tree, at.panel.id, tab));
                 if (!from) {
                     return undefined;
                 }
@@ -439,7 +475,7 @@ export function WorkspaceLayoutMixin() {
                     tabs: [{ id: tabId, viewIds: [viewId] }],
                     activeTabId: tabId,
                 };
-                const from = rehomeView(viewId, allViewIds, (tree, at) => splitPanel(tree, at.panel.id, 'row', panel));
+                const from = rehomeView(viewId, everyViewId('moveViewToSplitRight', allViewIds), (tree, at) => splitPanel(tree, at.panel.id, 'row', panel));
                 if (!from) {
                     return undefined;
                 }
@@ -480,21 +516,20 @@ export function WorkspaceLayoutMixin() {
          * is spelled.
          */
         setPendingMove(move, allViewIds) {
-            // The session's whole set of views, for the one entry point that cannot
-            // be handed it. Every other one takes it as an argument on purpose —
-            // this mixin owns the tree and knows nothing else — and this would too,
-            // if its caller were ours. Duck-typed because `views` is
-            // MultipleViewsSessionMixin's and composition is the only thing that
-            // puts the two together.
-            const { views } = self;
             // Not `?? []`: homing drops every view the list does not name, so an
             // empty one would answer "put this view beside nothing" and unhome the
             // rest. Nothing to say is nothing to do.
-            const ids = allViewIds ?? views?.map(v => v.id);
+            const ids = allViewIds ?? sessionViewIds(self);
             if (!move || !ids) {
                 return;
             }
-            self.applyLayoutSpec(specForPendingMove(move, ids));
+            const known = liveViewIds(self, ids);
+            // Nothing to move: the view named is not in the session, so there is
+            // no arrangement to state about it.
+            if (sessionViewIds(self) && !known.includes(move.viewId)) {
+                return;
+            }
+            self.applyLayoutSpec(specForPendingMove(move, known));
             // Show where the view went. A spec states an arrangement and not a
             // selection, so `treeFromSpec` shows each cell's FIRST tab — and
             // `newTab` puts the moved view in a tab beside the others, which makes
@@ -518,7 +553,31 @@ export function WorkspaceLayoutMixin() {
          * session spec's layout there is nothing for `orderViews` to apply.
          */
         tileViews(mode, allViewIds) {
-            self.applyLayoutSpec(tileLayoutSpec(allViewIds, mode));
+            self.applyLayoutSpec(tileLayoutSpec(liveViewIds(self, allViewIds), mode));
+        },
+        /**
+         * #action
+         * Arrange the session's views into panels. Calls `applyLayoutSpec`,
+         * turns workspaces mode on for this session (a layout renders nowhere
+         * else), and orders `session.views` to the spec's top-to-bottom
+         * order, which tabs read their order from. Without the last two steps
+         * the layout applies but does not display, or the tabs appear in the
+         * wrong order. Leaves take view ids or indexes into `session.views`; a
+         * layout that seats no view throws rather than leaving a blank tab. A
+         * session spec's `layout` and an agent's live re-layout both call it.
+         */
+        layoutViews(spec) {
+            const host = self;
+            if (!host.setUseWorkspaces || !host.orderViews) {
+                throw new Error('This session has no view list to arrange: layoutViews needs a host composed with MultipleViewsSessionMixin');
+            }
+            host.setUseWorkspaces(true);
+            const ids = self.applyLayoutSpec(spec);
+            if (ids.length === 0) {
+                throw new Error('The layout seats no views: a leaf names its views with "views" (view ids, or indexes into session.views) and a container nests "children"');
+            }
+            host.orderViews(ids);
+            return ids;
         },
     })));
 }

package/esm/WorkspaceLayout/spec.d.ts

@@ -1,19 +1,49 @@
 import type { LayoutTree, NodeKind } from './tree.ts';
+/**
+ * A view named by a layout leaf: an index into the view list the layout is
+ * applied against (a session spec's own `views`, or `session.views` for the
+ * live `applyLayoutSpec`), or a view id.
+ */
+export type LayoutViewRef = number | string;
 /**
  * The `layout` a session spec / URL param states, in the vocabulary users
- * write it in. **This shape is public** — it is documented as a URL parameter —
- * so it keeps `horizontal`/`vertical`/`tabs` and percentage `size` rather than
- * being renamed to match the internal tree.
+ * write it in, and the same shape the live `applyLayoutSpec` action takes — one
+ * shape, so an agent that has written one has written the other. **This shape
+ * is public** — it is documented as a URL parameter — so it keeps
+ * `horizontal`/`vertical`/`tabs` and percentage `size` rather than being
+ * renamed to match the internal tree.
+ *
+ * `resolveLayoutSpec` turns the indexes into ids; the tree builder below takes
+ * the resolved form only.
  */
-export interface LayoutSpecNode {
+export interface LayoutSpecNode<View = LayoutViewRef> {
     /** a leaf: the views to stack vertically in one tab */
-    viewIds?: string[];
+    views?: View[];
     /** how children divide the space; `tabs` puts them in one cell as tabs */
     direction?: 'horizontal' | 'vertical' | 'tabs';
-    children?: LayoutSpecNode[];
+    children?: LayoutSpecNode<View>[];
     /** share of the parent, as a percentage */
     size?: number;
 }
+export type ResolvedLayoutSpecNode = LayoutSpecNode<string>;
+/**
+ * Resolve every view a spec names to an id against `allViewIds`, the list its
+ * indexes count into. Anything that resolves to nothing throws, naming what was
+ * received: an untyped caller (the MCP `run_javascript` tool) that writes
+ * `viewIds` where `views` goes, or an index past the end, used to be accepted
+ * as an empty leaf and collapse the workspace into one blank tab with nothing
+ * said.
+ *
+ * A node stating no `views` and no `children` is NOT that slip — it is the
+ * empty panel `treeFromSpec` has always built, and refusing it here made the
+ * two surfaces disagree about the one shape they share. The slip is an
+ * unrecognized KEY, which is what `viewIds` actually is, and naming it beats
+ * the old message that could only say the node needed something else.
+ *
+ * `allViewIds` is undefined only on a model that composes no view list, where
+ * an id cannot be checked and an index cannot mean anything.
+ */
+export declare function resolveLayoutSpec(spec: LayoutSpecNode, allViewIds: string[] | undefined): ResolvedLayoutSpecNode;
 /** A request to move one view relative to the others. Public plugin API. */
 export interface PendingMove {
     type: 'newTab' | 'splitRight';
@@ -29,9 +59,9 @@ export interface PendingMove {
  * nesting, so `size` applies wherever it is written and there is no all-or-
  * nothing pass.
  */
-export declare function treeFromSpec(spec: LayoutSpecNode, nextId: (kind: NodeKind) => string): LayoutTree;
+export declare function treeFromSpec(spec: ResolvedLayoutSpecNode, nextId: (kind: NodeKind) => string): LayoutTree;
 /** Every viewId a spec names, depth-first — the order it states. */
-export declare function viewIdsInSpec(spec: LayoutSpecNode): string[];
+export declare function viewIdsInSpec(spec: ResolvedLayoutSpecNode): string[];
 /** How "arrange everything" lays the whole session out. */
 export type TileMode = 'tabs' | 'horizontal' | 'vertical' | 'grid';
 /**
@@ -49,10 +79,10 @@ export type TileMode = 'tabs' | 'horizontal' | 'vertical' | 'grid';
  * width, since `resolveSizes` reads bare siblings as an even share of their own
  * branch rather than of the grid.
  */
-export declare function tileLayoutSpec(viewIds: string[], mode: TileMode): LayoutSpecNode;
+export declare function tileLayoutSpec(viewIds: string[], mode: TileMode): ResolvedLayoutSpecNode;
 /**
  * `setPendingMove` as a spec: everything else keeps its side, the named view
  * takes the other. With nothing else on screen there is nothing to split from,
  * so the view just takes the space.
  */
-export declare function specForPendingMove(move: PendingMove, allViewIds: string[]): LayoutSpecNode;
+export declare function specForPendingMove(move: PendingMove, allViewIds: string[]): ResolvedLayoutSpecNode;

package/esm/WorkspaceLayout/spec.js

@@ -1,4 +1,77 @@
 import { normalize } from './tree.js';
+// `views`/`children` are pulled off by name; the rest pass through to the tree,
+// so an unrecognized one is a key the writer expected to mean something
+const layoutNodeKeys = new Set(['views', 'direction', 'children', 'size']);
+/**
+ * Resolve every view a spec names to an id against `allViewIds`, the list its
+ * indexes count into. Anything that resolves to nothing throws, naming what was
+ * received: an untyped caller (the MCP `run_javascript` tool) that writes
+ * `viewIds` where `views` goes, or an index past the end, used to be accepted
+ * as an empty leaf and collapse the workspace into one blank tab with nothing
+ * said.
+ *
+ * A node stating no `views` and no `children` is NOT that slip — it is the
+ * empty panel `treeFromSpec` has always built, and refusing it here made the
+ * two surfaces disagree about the one shape they share. The slip is an
+ * unrecognized KEY, which is what `viewIds` actually is, and naming it beats
+ * the old message that could only say the node needed something else.
+ *
+ * `allViewIds` is undefined only on a model that composes no view list, where
+ * an id cannot be checked and an index cannot mean anything.
+ */
+export function resolveLayoutSpec(spec, allViewIds) {
+    const describe = (value) => typeof value === 'string' ? `"${value}"` : String(value);
+    const resolveRef = (ref) => {
+        if (typeof ref === 'number') {
+            if (!allViewIds) {
+                throw new Error(`Layout names view index ${ref}, but this session has no view list for an index to count into; name the view by id`);
+            }
+            const id = allViewIds[ref];
+            if (id === undefined) {
+                throw new Error(`Layout names view index ${ref}, but the session has ${allViewIds.length} view(s)${allViewIds.length ? ` (indexes 0-${allViewIds.length - 1})` : ''}`);
+            }
+            return id;
+        }
+        if (typeof ref !== 'string') {
+            throw new Error(`Layout "views" entries are view indexes or view ids; received ${describe(ref)}`);
+        }
+        if (allViewIds && !allViewIds.includes(ref)) {
+            throw new Error(`Layout names view id ${describe(ref)}, which is not a view in this session (ids: ${allViewIds.map(describe).join(', ') || 'none'})`);
+        }
+        return ref;
+    };
+    const resolveNode = (node) => {
+        const { views, children, ...rest } = node;
+        const unknown = Object.keys(rest).filter(key => !layoutNodeKeys.has(key));
+        if (unknown.length > 0) {
+            throw new Error(`Layout node has unrecognized key(s) ${unknown.map(describe).join(', ')}; a leaf names its views with "views" (view indexes or ids) and a container nests "children"`);
+        }
+        if (views !== undefined && !Array.isArray(views)) {
+            throw new Error(`Layout "views" is an array of view indexes or ids; received ${describe(views)}`);
+        }
+        if (children !== undefined && !Array.isArray(children)) {
+            throw new Error(`Layout "children" is an array of layout nodes; received ${describe(children)}`);
+        }
+        return {
+            ...rest,
+            ...(views === undefined ? {} : { views: views.map(resolveRef) }),
+            ...(children === undefined
+                ? {}
+                : { children: children.map(resolveNode) }),
+        };
+    };
+    const resolved = resolveNode(spec);
+    const seen = new Set();
+    const repeated = new Set(viewIdsInSpec(resolved).filter(id => {
+        const already = seen.has(id);
+        seen.add(id);
+        return already;
+    }));
+    if (repeated.size > 0) {
+        throw new Error(`Layout seats view ${[...repeated].map(describe).join(', ')} in more than one cell; a view lives in exactly one tab, so name it once`);
+    }
+    return resolved;
+}
 /**
  * The effective size of each child of one branch.
  *
@@ -44,11 +117,11 @@ function resolveSizes(children) {
  */
 export function treeFromSpec(spec, nextId) {
     function build(node, size) {
-        if (node.viewIds) {
+        if (node.views) {
             return {
                 id: nextId('panel'),
                 size,
-                tabs: [{ id: nextId('tab'), viewIds: [...node.viewIds] }],
+                tabs: [{ id: nextId('tab'), viewIds: [...node.views] }],
                 activeTabId: undefined,
             };
         }
@@ -67,7 +140,7 @@ export function treeFromSpec(spec, nextId) {
         if (node.direction === 'tabs') {
             const tabs = children.flatMap(child => {
                 const viewIds = viewIdsInSpec(child);
-                return child.viewIds === undefined && viewIds.length === 0
+                return child.views === undefined && viewIds.length === 0
                     ? []
                     : [{ id: nextId('tab'), viewIds }];
             });
@@ -98,7 +171,7 @@ export function treeFromSpec(spec, nextId) {
 /** Every viewId a spec names, depth-first — the order it states. */
 export function viewIdsInSpec(spec) {
     return [
-        ...(spec.viewIds ?? []),
+        ...(spec.views ?? []),
         ...(spec.children ?? []).flatMap(viewIdsInSpec),
     ];
 }
@@ -121,9 +194,9 @@ export function tileLayoutSpec(viewIds, mode) {
     // Nothing to arrange: one view is the whole workspace whatever the mode, and
     // no views leaves the empty panel the tree already guarantees.
     if (viewIds.length <= 1) {
-        return { viewIds: [...viewIds] };
+        return { views: [...viewIds] };
     }
-    const cell = (id) => ({ viewIds: [id] });
+    const cell = (id) => ({ views: [id] });
     if (mode !== 'grid') {
         return { direction: mode, children: viewIds.map(cell) };
     }
@@ -147,7 +220,7 @@ export function specForPendingMove(move, allViewIds) {
     return others.length > 0
         ? {
             direction: move.type === 'splitRight' ? 'horizontal' : 'tabs',
-            children: [{ viewIds: others }, { viewIds: [move.viewId] }],
+            children: [{ views: others }, { views: [move.viewId] }],
         }
-        : { viewIds: [move.viewId] };
+        : { views: [move.viewId] };
 }

package/esm/index.d.ts

@@ -1,4 +1,4 @@
-export { App, AppReadyMarker, DialogQueue } from './ui/index.ts';
+export { App, DialogQueue, preloadAppFrame, preloadAppShell, } from './ui/index.ts';
 export { HistoryManagementMixin } from './HistoryManagement/index.ts';
 export { DEFAULT_SHARE_URL, JBrowseConfigF } from './JBrowseConfig/index.ts';
 export { JBrowseModelF } from './JBrowseModel/index.ts';
@@ -13,4 +13,6 @@ export type { LayoutNode, LgvUrlInit, ParsedSessionSpec, ViewSpec, } from './Ses
 export type { SessionModelFactory } from './sessionModelFactory.ts';
 export { deleteQueryParams, readAllQueryParams, readQueryParams, setQueryParams, useQueryParam, } from './queryParams.ts';
 export { processMutableMenuActions, resolveMenus } from './menus.ts';
-export type { Menu, MenuAction, MenuDefinition } from './menus.ts';
+export type { Menu, MenuAction } from './menus.ts';
+export { createJbApi, ensureReExports, safeJson, sessionOf, undeliveredNotifications, waitReady, } from './JbApi/index.ts';
+export type { JbApi } from './JbApi/index.ts';

package/esm/index.js

@@ -1,4 +1,4 @@
-export { App, AppReadyMarker, DialogQueue } from './ui/index.js';
+export { App, DialogQueue, preloadAppFrame, preloadAppShell, } from './ui/index.js';
 export { HistoryManagementMixin } from './HistoryManagement/index.js';
 export { DEFAULT_SHARE_URL, JBrowseConfigF } from './JBrowseConfig/index.js';
 export { JBrowseModelF } from './JBrowseModel/index.js';
@@ -11,3 +11,6 @@ export { addSessionTracks, buildLgvInit, buildLgvInitFromParams, hubConnectionSp
 // embedded product must not rewrite its host's URL — see queryParams.ts
 export { deleteQueryParams, readAllQueryParams, readQueryParams, setQueryParams, useQueryParam, } from './queryParams.js';
 export { processMutableMenuActions, resolveMenus } from './menus.js';
+// The helper library an agent drives the app through: desktop serves it to
+// run_javascript over MCP, web hands it to the page as window.jb
+export { createJbApi, ensureReExports, safeJson, sessionOf, undeliveredNotifications, waitReady, } from './JbApi/index.js';