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

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/index.d.ts

@@ -1,5 +1,5 @@
 export { buildLgvInit, buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, readNavParam, readTracklistParam, shortHubLabel, splitHighlights, } from './lgvUrlInit.ts';
-export { addSessionTracks, loadSessionSpec } from './loadSessionSpec.ts';
+export { addSessionTracks, launchSpecView, launchableSpecView, loadSessionSpec, viewTypeProblem, } from './loadSessionSpec.ts';
 export { parseSessionSpecUrl } from './parseSessionSpecUrl.ts';
 export type { LgvUrlInit } from './lgvUrlInit.ts';
 export type { ParsedSessionSpec } from './parseSessionSpecUrl.ts';

package/esm/SessionSpec/index.js

@@ -1,3 +1,3 @@
 export { buildLgvInit, buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, readNavParam, readTracklistParam, shortHubLabel, splitHighlights, } from './lgvUrlInit.js';
-export { addSessionTracks, loadSessionSpec } from './loadSessionSpec.js';
+export { addSessionTracks, launchSpecView, launchableSpecView, loadSessionSpec, viewTypeProblem, } from './loadSessionSpec.js';
 export { parseSessionSpecUrl } from './parseSessionSpecUrl.js';

package/esm/SessionSpec/lgvUrlInit.js

@@ -66,8 +66,11 @@ export function buildLgvInit(args) {
     if (assembly !== undefined) {
         init.assembly = assembly;
     }
-    if (tracks !== undefined) {
-        init.tracks = tracks.split(',');
+    // empty entries dropped, like `regions`: `&tracks=a,` asked for no track
+    // named ''
+    const trackIds = tracks?.split(',').filter(Boolean);
+    if (trackIds?.length) {
+        init.tracks = trackIds;
     }
     if (tracklist !== undefined) {
         init.tracklist = tracklist;

package/esm/SessionSpec/loadSessionSpec.d.ts

@@ -11,11 +11,65 @@ import type { AbstractSessionModel } from '@jbrowse/core/util';
  * layer down.
  */
 export declare function addSessionTracks(session: AbstractSessionModel | undefined, tracks: Record<string, unknown>[]): void;
-export declare function loadSessionSpec({ views, sessionAssemblies, sessionConnections, sessionTracks, layout, sessionName, }: {
+/**
+ * Why one view type cannot launch from a spec here, or nothing. Two causes,
+ * two messages: the type is unknown at all (a typo, or a plugin that was not
+ * loaded), or it exists but nothing taught it how to launch from a spec, which
+ * only the view's plugin can fix.
+ */
+export declare function viewTypeProblem(pluginManager: PluginManager, type: string): string | undefined;
+/**
+ * A spec view entry as its launcher takes it, and what its type does not take.
+ *
+ * The same classification a view snapshot gets, run here because a spec never
+ * becomes one: `LaunchView-<type>` takes these keys as arguments, so
+ * `withLaunchInput`'s partition never sees them and nothing names a typo.
+ * `{type: 'LinearGenomeView', asembly: 'volvox'}` reported only the launcher's
+ * downstream "No assembly provided", on the one surface written by hand with no
+ * compiler and no editor behind it.
+ *
+ * A view type that registers no launch keys classifies nothing: its launcher's
+ * vocabulary is undeclared, so every argument would read as a typo. A lazily
+ * registered type declares its properties on a state model that is not loaded
+ * yet, so it is loaded first — the launch would have loaded it anyway.
+ */
+export declare function launchableSpecView(pluginManager: PluginManager, spec: ViewSpec): Promise<{
+    view: ViewSpec;
+    problem?: string;
+}>;
+/**
+ * Launch one spec view into the session through its `LaunchView-<type>`
+ * extension point, the same door `loadSessionSpec` uses for each of its views
+ * — so `jb.addView` and a spec agree on what a view entry means, a
+ * ProteinView's `connectedView` included.
+ *
+ * Strict so a launch handler that throws (missing/invalid assembly, unresolved
+ * track, ...) is returned as a failure instead of being swallowed by the plain
+ * extension-point runner, which would leave a silent empty session. A handler
+ * that legitimately no-ops returns normally and is unaffected.
+ *
+ * `created` is EVERY view the launch added, in creation order: a connected
+ * ProteinView creates its genome view and then itself. `view` is the entry's
+ * own, the one of the spec's type, which is where `displayName` goes — it used
+ * to land on the genome view a ProteinView opened first, and the structure came
+ * up "Untitled view". `type` is the dispatch key, not a setting: forwarding it
+ * would land in the view's launch blob and trip the "ignored unknown key(s):
+ * type" warning meant to catch typos.
+ */
+export declare function launchSpecView(session: AbstractSessionModel | undefined, pluginManager: PluginManager, spec: ViewSpec): Promise<{
+    created: import("@jbrowse/core/util").AbstractViewModel[];
+    view: import("@jbrowse/core/util").AbstractViewModel | undefined;
+    failure?: {
+        message: string;
+        cause: unknown;
+    } | undefined;
+}>;
+export interface SessionSpec {
     views: ViewSpec[];
     sessionAssemblies?: Record<string, unknown>[];
     sessionConnections?: Record<string, unknown>[];
     sessionTracks?: Record<string, unknown>[];
     layout?: LayoutNode;
     sessionName?: string;
-}, pluginManager: PluginManager): Promise<void>;
+}
+export declare function loadSessionSpec(spec: SessionSpec, pluginManager: PluginManager): Promise<void>;

package/esm/SessionSpec/loadSessionSpec.js

@@ -1,10 +1,14 @@
 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);
+// A spec `layout` needs `layoutViews`, which a session composing
+// WorkspaceLayoutMixin and MultipleViewsSessionMixin has and an embedded
+// product's does not. It is looked up behind an `in` guard, so renaming it
+// without renaming it here makes every spec layout silently decline rather than
+// fail to compile; see app-core/src/WorkspaceLayout/CLAUDE.md.
+function hasLayoutViews(session) {
+    return 'layoutViews' in session;
 }
 function isSessionWithSpecConnections(session) {
     return ('addConnectionConf' in session &&
@@ -57,37 +61,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 +145,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,25 +157,179 @@ 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);
+}
+function unknownViewTypesMessage(types) {
+    return `Unknown view type(s) in session spec: ${types.join(', ')}. The plugin providing the view may be missing, or the type may be misspelled.`;
+}
+function noLauncherMessage(types) {
+    return `View type(s) ${types.join(', ')} cannot be launched from a session spec: no LaunchView extension point is registered for them.`;
+}
+/**
+ * Why one view type cannot launch from a spec here, or nothing. Two causes,
+ * two messages: the type is unknown at all (a typo, or a plugin that was not
+ * loaded), or it exists but nothing taught it how to launch from a spec, which
+ * only the view's plugin can fix.
+ */
+export function viewTypeProblem(pluginManager, type) {
+    if (pluginManager.extensionPoints.has(`LaunchView-${type}`)) {
+        return undefined;
+    }
+    // the record's `has`, not getElementType, which throws on an unregistered
+    // name rather than returning undefined
+    return pluginManager.getElementTypeRecord('view').has(type)
+        ? noLauncherMessage([type])
+        : unknownViewTypesMessage([type]);
+}
+// v4 nested a view's settings under `init`. A spec never becomes a snapshot, so
+// `withLaunchInput`'s unwrap never runs on one and this surface does it itself,
+// in the same order: the flat spelling wins.
+function flattenSpecView(spec) {
+    const { init, ...view } = spec;
+    if (init) {
+        console.warn(legacyInitMessage(view.type));
+    }
+    return init ? { ...init, ...view } : view;
+}
+/**
+ * A spec view entry as its launcher takes it, and what its type does not take.
+ *
+ * The same classification a view snapshot gets, run here because a spec never
+ * becomes one: `LaunchView-<type>` takes these keys as arguments, so
+ * `withLaunchInput`'s partition never sees them and nothing names a typo.
+ * `{type: 'LinearGenomeView', asembly: 'volvox'}` reported only the launcher's
+ * downstream "No assembly provided", on the one surface written by hand with no
+ * compiler and no editor behind it.
+ *
+ * A view type that registers no launch keys classifies nothing: its launcher's
+ * vocabulary is undeclared, so every argument would read as a typo. A lazily
+ * registered type declares its properties on a state model that is not loaded
+ * yet, so it is loaded first — the launch would have loaded it anyway.
+ */
+export async function launchableSpecView(pluginManager, spec) {
+    const flat = flattenSpecView(spec);
+    if (!pluginManager.getElementTypeRecord('view').has(flat.type)) {
+        return { view: flat };
+    }
+    const viewType = pluginManager.getViewType(flat.type);
+    await viewType.loadStateModel();
+    const accepted = viewType.acceptedKeys;
+    if (!accepted) {
+        return { view: flat };
+    }
+    const { view, problem } = readAssemblyNames(flat, accepted);
+    const { type, ...keyed } = view;
+    const unknown = Object.keys(keyed).filter(key => !accepted.includes(key));
+    const problems = [
+        ...(unknown.length ? [unknownKeysMessage(type, unknown)] : []),
+        ...(problem ? [problem] : []),
+    ];
+    return { view, problem: problems.join('; ') || undefined };
+}
+// An agent reads `assemblyNames` off the live view and writes it back into a
+// spec, where the key the entry takes is `assembly`. One name is that assembly;
+// several are a question one view cannot answer.
+function readAssemblyNames(view, accepted) {
+    const { assemblyNames, ...rest } = view;
+    // Array.isArray, not a length check: a hand-written `assemblyNames: 'volvox'`
+    // has a length too, and reached .join below — a throw, which this one outer
+    // catch turns into every remaining view and the layout being lost
+    if (!Array.isArray(assemblyNames) ||
+        !assemblyNames.length ||
+        !accepted.includes('assembly') ||
+        accepted.includes('assemblyNames')) {
+        return { view };
+    }
+    return assemblyNames.length === 1
+        ? { view: { ...rest, assembly: rest.assembly ?? assemblyNames[0] } }
+        : {
+            view: rest,
+            problem: `${view.type} takes one "assembly", and assemblyNames names ${assemblyNames.length} (${assemblyNames.join(', ')}) — pass assembly, one view per assembly`,
+        };
+}
+/**
+ * Launch one spec view into the session through its `LaunchView-<type>`
+ * extension point, the same door `loadSessionSpec` uses for each of its views
+ * — so `jb.addView` and a spec agree on what a view entry means, a
+ * ProteinView's `connectedView` included.
+ *
+ * Strict so a launch handler that throws (missing/invalid assembly, unresolved
+ * track, ...) is returned as a failure instead of being swallowed by the plain
+ * extension-point runner, which would leave a silent empty session. A handler
+ * that legitimately no-ops returns normally and is unaffected.
+ *
+ * `created` is EVERY view the launch added, in creation order: a connected
+ * ProteinView creates its genome view and then itself. `view` is the entry's
+ * own, the one of the spec's type, which is where `displayName` goes — it used
+ * to land on the genome view a ProteinView opened first, and the structure came
+ * up "Untitled view". `type` is the dispatch key, not a setting: forwarding it
+ * would land in the view's launch blob and trip the "ignored unknown key(s):
+ * type" warning meant to catch typos.
+ */
+export async function launchSpecView(session, pluginManager, spec) {
+    const { type, displayName, ...view } = spec;
+    const before = new Set(session?.views.map(v => v.id));
+    let failure;
+    try {
+        await pluginManager.evaluateAsyncExtensionPointStrict(`LaunchView-${type}`, {
+            ...view,
+            session,
+        });
+    }
+    catch (e) {
+        console.error(e);
+        failure = { message: `Failed to launch ${type} view: ${e}`, cause: e };
+    }
+    const created = session?.views.filter(v => !before.has(v.id)) ?? [];
+    const named = created.find(v => v.type === type) ?? created[0];
+    if (named && displayName) {
+        named.setDisplayName(displayName);
+    }
+    return { created, view: named, ...(failure ? { failure } : {}) };
 }
-// 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 SPEC_KEYS = [
+    'views',
+    'sessionAssemblies',
+    'sessionConnections',
+    'sessionTracks',
+    'layout',
+    'sessionName',
+];
+export async function loadSessionSpec(spec, pluginManager) {
+    const { views, sessionAssemblies = [], sessionConnections = [], sessionTracks = [], layout, sessionName, } = spec;
     const rootModel = pluginManager.rootModel;
     try {
         rootModel.setSession?.({
             name: sessionName ?? `New session ${new Date().toLocaleString()}`,
         });
         const { session } = rootModel;
+        // `tracks` for sessionTracks, `assemblies` for sessionAssemblies, `name`
+        // for sessionName: a top-level key this spec does not define used to be
+        // dropped by the destructure above with nothing said, on the one door every
+        // agent-facing text names first. Reported like the misplaced keys below,
+        // rather than thrown, so the rest of the spec still loads.
+        const unknownKeys = Object.keys(spec).filter(key => !SPEC_KEYS.includes(key));
+        if (unknownKeys.length) {
+            session?.notifyError(`${unknownKeysMessage('Session spec', unknownKeys)} — it takes ${SPEC_KEYS.join(', ')}`);
+        }
         // Assemblies first: sessionTracks and the views below reference them by
         // name, so a self-contained spec (novel assemblies + their tracks, no
         // hosted config) resolves only if the assemblies exist before either runs.
         if (isSessionWithAddAssembly(session)) {
+            // Per-assembly, like connections and tracks below: an invalid config
+            // fails the array's MST type check and would otherwise cost the spec
+            // everything after it
             for (const assembly of sessionAssemblies) {
-                session.addSessionAssembly(assembly);
+                try {
+                    session.addSessionAssembly(assembly);
+                }
+                catch (e) {
+                    console.error(e);
+                    const label = typeof assembly.name === 'string' ? assembly.name : '?';
+                    session.notifyError(`Assembly "${label}" has an invalid configuration: ${e}`, e);
+                }
             }
         }
         // Connections after the assemblies (a connection config may name one the
@@ -180,63 +376,21 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
             }
         }
         addSessionTracks(session, sessionTracks);
-        // a view type with no registered LaunchView-<type> extension point makes
+        // 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.
+        // no diagnostic. Reported once per type, not per view.
+        const viewTypes = pluginManager.getElementTypeRecord('view');
         const notLaunchable = [
-            ...new Set(views.flatMap(view => pluginManager.extensionPoints.has(`LaunchView-${view.type}`)
-                ? []
-                : [view.type])),
+            ...new Set(views.flatMap(view => viewTypeProblem(pluginManager, 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.`);
+            session?.notifyError(unknownViewTypesMessage(unknown));
         }
         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:
-        //
-        // - 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
-        //
-        // 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.`);
+            session?.notifyError(noLauncherMessage(noLauncher));
         }
-        // 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 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.
-        // `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.
         // 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
@@ -250,54 +404,62 @@ export async function loadSessionSpec({ views, sessionAssemblies = [], sessionCo
             !(await whenConnectionsSettle(session))) {
             return;
         }
+        // Launch sequentially and record the ids each spec view created, so the
+        // layout below can map its indices to real views. Reading session.views
+        // positionally afterwards only works while every handler happens to addView
+        // synchronously and in order; capturing the delta per launch instead is
+        // correct even if a handler awaits or adds an auxiliary view, and lets a
+        // later spec view (e.g. a connected MsaView) reference an earlier one that
+        // now already exists.
+        //
+        // An unknown key is an ERROR rather than the snapshot path's warning: this
+        // surface's misplaced keys already report as errors, and the launcher's own
+        // failure lands as an error a line later — a warning under it reads as the
+        // lesser of the two, when it is the cause. Per view, so one bad view
+        // doesn't cost the rest.
         const createdViewIds = [];
-        for (const { type, displayName, ...view } of views) {
-            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);
+        for (const spec of views) {
+            const { view, problem } = await launchableSpecView(pluginManager, spec);
+            if (problem) {
+                session?.notifyError(problem);
             }
-            const created = session?.views.find(v => !before.has(v.id));
-            if (created && displayName) {
-                created.setDisplayName(displayName);
+            const { created, failure } = await launchSpecView(session, pluginManager, view);
+            if (failure) {
+                session?.notifyError(failure.message, failure.cause);
             }
-            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');
             }
             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.
-                session.orderViews(session.applyLayoutSpec(convertLayoutNode(layout, createdViewIds)));
+            if (hasLayoutViews(session)) {
+                // Its own try/catch, the same reasoning as the per-view one above: the
+                // resolver throws for a layout it will not arrange, and this is the
+                // LAST thing the spec does — so an unarrangeable layout used to take
+                // the whole load's catch and report itself as the session's error. The
+                // layout is one statement in the spec; losing it should cost the spec
+                // its layout and nothing else.
+                try {
+                    session.layoutViews(convertLayoutNode(layout, createdViewIds, knownIds, new Set(pinnedLayoutIds(layout, knownIds))));
+                }
+                catch (e) {
+                    console.error(e);
+                    session.notifyError(`Session spec layout: ${e}`, e);
+                }
             }
             else {
                 session.notifyError('Session spec has a "layout", but this application does not support workspace layouts');