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

package/esm/RootMenu/index.d.ts

@@ -1,20 +1,11 @@
-import type { MenuAction, MenuDefinition } from '../menus.ts';
-import type { MenuItem } from '@jbrowse/core/ui/Menu';
+import type { MenuAction } from '../menus.ts';
+import type { MenuItem } from '@jbrowse/core/ui/menuItems';
 /**
  * #stateModel RootAppMenuMixin
  */
 export declare function RootAppMenuMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     mutableMenuActions: MenuAction[];
 } & {
-    /**
-     * #action
-     * Replace the menu bar wholesale. Item contributions recorded before
-     * this one are dropped along with the menus they targeted, so a plugin
-     * adding to the existing bar wants `appendToMenu` instead.
-     *
-     * @param newMenus - The complete new set of top-level menus.
-     */
-    setMenus(newMenus: MenuDefinition[]): void;
     /**
      * #action
      * Add a top-level menu, if the app bar does not already have one with

package/esm/RootMenu/index.js

@@ -14,17 +14,6 @@ export function RootAppMenuMixin() {
             self.mutableMenuActions = [...self.mutableMenuActions, action];
         }
         return {
-            /**
-             * #action
-             * Replace the menu bar wholesale. Item contributions recorded before
-             * this one are dropped along with the menus they targeted, so a plugin
-             * adding to the existing bar wants `appendToMenu` instead.
-             *
-             * @param newMenus - The complete new set of top-level menus.
-             */
-            setMenus(newMenus) {
-                pushAction({ type: 'setMenus', newMenus });
-            },
             /**
              * #action
              * Add a top-level menu, if the app bar does not already have one with

package/esm/SessionSpec/loadSessionSpec.js

@@ -1,10 +1,9 @@
 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);
+    return 'layoutViews' in session;
 }
 function isSessionWithSpecConnections(session) {
     return ('addConnectionConf' in session &&
@@ -57,37 +56,75 @@ async function whenConnectionsSettle(session) {
     await when(() => gone() || session.connectionInstances.every(conn => !conn.loading));
     return !gone();
 }
-// Convert LayoutNode (view indices into the spec's `views` array) to
-// LayoutSpecNode (view IDs). `viewIds` is indexed the same as that spec
-// array — element i is the id of the view the i-th spec entry created, or
-// undefined if it created none — so a layout index maps to the right view
-// regardless of what order the views ended up in on the session.
-function convertLayoutNode(node, viewIds) {
-    if (node.views !== undefined) {
-        // Panel node - convert view indices to view IDs
-        const ids = node.views
-            .map(idx => viewIds[idx])
-            .filter((id) => id !== undefined);
-        return { viewIds: ids, size: node.size };
-    }
-    if (node.children) {
-        // Container node - recursively convert children
-        return {
-            direction: node.direction,
-            children: node.children.map(child => convertLayoutNode(child, viewIds)),
-            size: node.size,
-        };
-    }
-    return {};
+// 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 index in a panel is bad, leave an empty
-// panel with no clue why.
-function outOfRangeLayoutIndices(node, viewCount) {
+// 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 [
-        ...(node.views?.filter(idx => idx < 0 || idx >= viewCount) ?? []),
-        ...(node.children?.flatMap(child => outOfRangeLayoutIndices(child, viewCount)) ?? []),
+        ...(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
@@ -103,9 +140,9 @@ function outOfRangeLayoutIndices(node, viewCount) {
 // 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 sizedTabsChild = layout.direction === 'tabs' &&
-        (layout.children?.some(c => c.size !== undefined) ?? false);
-    return (sizedTabsChild || (layout.children?.some(unsizeableLayoutNodes) ?? false));
+    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
@@ -115,9 +152,9 @@ function unsizeableLayoutNodes(layout) {
 // 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 nestedTabsChild = layout.direction === 'tabs' &&
-        (layout.children?.some(c => c.children !== undefined) ?? false);
-    return (nestedTabsChild || (layout.children?.some(flattenedTabsContainers) ?? false));
+    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
@@ -202,27 +239,47 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
         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.`);
         }
-        // The two ways of writing a view are not the same shape, and this is the
-        // confusable pair:
+        // 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 spec view is flat *arguments* to LaunchView-<type>, in that launcher's
-        //   own vocabulary (a dotplot takes `views`, a spreadsheet takes `uri`), and
-        //   the launcher sorts them into what the new view needs
-        // - a config/defaultSession view is MST *state*, so keys that need resolving
-        //   on load have nowhere to live but the view's own `init` property
+        // A view type that registers no launch keys classifies nothing: its
+        // launcher's vocabulary is undeclared, so every argument would read as a
+        // typo.
         //
-        // Reported rather than unwrapped here, deliberately: only a launcher knows
-        // which of its keys are one-shot commands versus plain view props, so
-        // flattening `init` centrally would erase that distinction and let a view prop
-        // nested inside it be honored from a spec while the identical config drops it.
-        // Teaching each launcher to accept both instead is per-view-type work that
-        // every future launcher has to remember — the shapes then differ by view type,
-        // which is worse than differing by surface. One check here covers every view
-        // type, including plugin-provided ones. Without it the LGV reports the
-        // downstream symptom, "No assembly provided", for a misplaced block.
-        const nested = views.filter(view => 'init' in view).map(view => view.type);
-        if (nested.length) {
-            session?.notifyError(`Session spec view(s) ${nested.join(', ')} nest their settings under "init". A spec takes those keys flat (assembly, loc, tracks, …); "init" is the config/defaultSession form.`);
+        // 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
@@ -230,13 +287,12 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
         // 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 view init data:
-        // forwarding it would land in the view's declarative init blob and trip the
-        // spurious "init ignored unknown key(s): type" warning meant to catch typos.
+        // 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). A nested `init` is
-        // NOT unwrapped the same way — see the diagnostic above for why.
+        // 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
@@ -251,7 +307,7 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
             return;
         }
         const createdViewIds = [];
-        for (const { type, displayName, ...view } of views) {
+        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
@@ -268,17 +324,27 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
                 console.error(e);
                 session?.notifyError(`Failed to launch ${type} view: ${e}`, e);
             }
-            const created = session?.views.find(v => !before.has(v.id));
-            if (created && displayName) {
-                created.setDisplayName(displayName);
+            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?.id);
+            createdViewIds.push(created.map(v => v.id));
         }
         if (layout && session) {
-            const badIndices = outOfRangeLayoutIndices(layout, views.length);
+            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');
             }
@@ -286,18 +352,19 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
                 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.
-                session.orderViews(session.applyLayoutSpec(convertLayoutNode(layout, createdViewIds)));
+                // 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');

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;
@@ -6,15 +7,17 @@ export interface ViewSpec {
     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>;
 }
 /**
- * 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 +28,4 @@ export interface ViewSpec {
  * }
  * ```
  */
-export interface LayoutNode {
-    views?: number[];
-    direction?: 'horizontal' | 'vertical' | 'tabs';
-    children?: LayoutNode[];
-    size?: number;
-}
+export type LayoutNode = LayoutSpecNode;

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: `applyLayoutSpec` plus the
+     * two things it does not do on its own, each of which fails silently
+     * without it — turning workspaces mode on for this session (a layout
+     * renders nowhere else) and ordering `session.views` to the spec's
+     * top-to-bottom statement, which is where a tab reads its order from.
+     * Leaves take view ids or indexes into `session.views`; a layout that
+     * seats no view throws rather than leaving a blank tab. What a session
+     * spec's `layout` and an agent's live re-layout both call.
+     */
+    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,30 @@
 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);
+}
+function layoutHost(self) {
+    return self;
+}
+/**
+ * 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 +233,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 +430,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 +445,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 +478,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 +519,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 +556,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: `applyLayoutSpec` plus the
+         * two things it does not do on its own, each of which fails silently
+         * without it — turning workspaces mode on for this session (a layout
+         * renders nowhere else) and ordering `session.views` to the spec's
+         * top-to-bottom statement, which is where a tab reads its order from.
+         * Leaves take view ids or indexes into `session.views`; a layout that
+         * seats no view throws rather than leaving a blank tab. What a session
+         * spec's `layout` and an agent's live re-layout both call.
+         */
+        layoutViews(spec) {
+            const host = layoutHost(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;
         },
     })));
 }