@jbrowse/app-core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/JbApi/jbApi.js

@@ -1,19 +1,18 @@
-import { setReExportRegistry } from '@jbrowse/core/ReExports/registry';
-import { getConf, getConfigurationSchemaDefinition, isSlotDefinitionEntry, readConfObject, } from '@jbrowse/core/configuration';
+import { getReExportRegistry, setReExportRegistry, } from '@jbrowse/core/ReExports/registry';
+import { getConf, getConfigurationSchemaDefinition, getConfigurationSchemaOptions, isConfigurationSubschema, isSlotDefinitionEntry, readConfObject, } from '@jbrowse/core/configuration';
 import { releaseAdapterSession, retainAdapterSession, } from '@jbrowse/core/data_adapters/adapterSessionRefcount';
 import { adapterConfigCacheKey } from '@jbrowse/core/data_adapters/dataAdapterCache';
-import { getFeatureAdapterOrThrow } from '@jbrowse/core/data_adapters/getFeatureAdapter';
 import { adapterByteLimit } from '@jbrowse/core/rpc/byteBudget';
-import { getRpcSessionId, isElectron, isSessionWithAddSessionTrack, objectHash, parseLocString, renameRegionsIfNeeded, } from '@jbrowse/core/util';
-import { openTracks, openViews } from '@jbrowse/core/util/openViews';
-import { createStopToken, stopStopToken } from '@jbrowse/core/util/stopToken';
+import { isElectron, isSessionWithAddSessionTrack, objectHash, parseLocString, } from '@jbrowse/core/util';
+import { openTracks, openViews, viewAndNested, } from '@jbrowse/core/util/openViews';
 import { allSessionTracks, getConfAssemblyNamesOrNone, guessTrackConfForLocation, isSameAssemblyName, viewCanDisplayTrack, viewDisplayNames, } from '@jbrowse/core/util/tracks';
+import { unknownKeysMessage } from '@jbrowse/core/util/withLaunchInput';
 import * as mst from '@jbrowse/mobx-state-tree';
-import { getSnapshot, getType, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { applySnapshot, getSnapshot, getType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
 import * as mobx from 'mobx';
 // relative, not '@jbrowse/app-core': a package self-import would make this
 // module depend on the barrel that exports it
-import { loadSessionSpec } from '../SessionSpec/index.js';
+import { launchSpecView, launchableSpecView, loadSessionSpec, viewTypeProblem, } from '../SessionSpec/index.js';
 // Matches BaseTrackModel's DEFAULT_EXPORT_BYTE_LIMIT: both bound a fetch
 // someone asked for by name rather than one a view scrolled into, so they
 // should refuse at the same size.
@@ -66,6 +65,7 @@ function displayState(track) {
             ...(display.renderError
                 ? { renderError: String(display.renderError) }
                 : {}),
+            ...(display.notices?.length ? { notices: [...display.notices] } : {}),
         };
     }
     catch (e) {
@@ -115,16 +115,20 @@ export function sessionOf(pluginManager) {
  * The three terms are AppReadyMarker's, and they have to be: the marker decides
  * whether the settle ends, this decides what it says when it doesn't, and a
  * term in one and not the other is a settle that answers `false` with an empty
- * `notReady`. `launching` is the one that was missing — `initialized` goes true
- * the moment a linear view's regions land, while the same apply pass still has
- * the spec's tracks to attach, so a spec load timing out there reported no
- * reason at all.
+ * `notReady`, or one that names a view the marker was content with. `launching`
+ * is the one that was missing — `initialized` goes true the moment a linear
+ * view's regions land, while the same apply pass still has the spec's tracks to
+ * attach, so a spec load timing out there reported no reason at all.
+ *
+ * `showImportForm` excuses `initializing` on the same terms the marker gives
+ * it: a comparative view reads uninitialized for as long as its form is up, and
+ * the form is waiting on a person.
  */
 function viewState(v) {
     if (v.error !== undefined) {
         return { error: String(v.error) };
     }
-    if (v.initialized === false) {
+    if (v.initialized === false && v.showImportForm !== true) {
         return { phase: 'initializing' };
     }
     return v.pendingLaunch === undefined
@@ -157,8 +161,8 @@ function viewSummary(view) {
                 })),
             }
             : {}),
-        ...(Array.isArray(v.views) && v.views.length
-            ? { views: v.views.map(sub => viewSummary(sub)) }
+        ...(view.ownViews.length
+            ? { views: view.ownViews.map(sub => viewSummary(sub)) }
             : {}),
     };
 }
@@ -232,27 +236,25 @@ function memberNames(node) {
     }
     return { getters: getters.sort(), methods: methods.sort() };
 }
+// The node itself. An agent writing `run_javascript` holds it already —
+// jb.view(), session.views[0], track.activeDisplay — so there is nothing to
+// learn here. A dot-path string used to be the only way to ask, which had
+// agents reconstructing a path to a node in hand, in a grammar ("views.0")
+// that is not JavaScript.
+function inspectTarget(session, target) {
+    if (typeof target === 'string') {
+        throw new Error(`jb.inspect takes the node itself, not the name "${target}" — jb.inspect(jb.view()), jb.inspect(jb.trackModel('someTrackId')), jb.inspect(session.views[0].tracks[0]). Bare jb.inspect() is the session.`);
+    }
+    return target ?? session;
+}
 function inspectSession(session, args) {
-    const path = typeof args.path === 'string' ? args.path : '';
     const maxBytes = typeof args.maxBytes === 'number' ? args.maxBytes : 20_000;
-    let node = session;
-    const walked = [];
-    for (const segment of path.split('.').filter(Boolean)) {
-        node =
-            node !== null && typeof node === 'object'
-                ? node[segment]
-                : undefined;
-        if (node === undefined) {
-            throw new Error(`Nothing at "${path}" (undefined after "${walked.join('.') || '(root)'}"). Inspect the parent path to see its keys and getters.`);
-        }
-        walked.push(segment);
-    }
-    const members = node !== null && typeof node === 'object' && !Array.isArray(node)
+    const node = inspectTarget(session, args.target);
+    const members = typeof node === 'object' && !Array.isArray(node)
         ? memberNames(node)
         : { getters: [], methods: [] };
     const json = safeJson(node);
     const base = {
-        path: path || '(session root)',
         // the name the docs tool files a type under: docs topic "model:<modelType>"
         ...(isStateTreeNode(node) ? { modelType: getType(node).name } : {}),
         bytes: json.length,
@@ -266,12 +268,12 @@ function inspectSession(session, args) {
     return Array.isArray(plain)
         ? {
             ...base,
-            note: `too large to return whole — ${plain.length} items; index in with .N or raise maxBytes`,
+            note: `too large to return whole — ${plain.length} items; inspect one of them or raise maxBytes`,
             items: plain.slice(0, 20).map(item => describeBrief(item)),
         }
         : {
             ...base,
-            note: 'too large to return whole — drill down by path or raise maxBytes',
+            note: 'too large to return whole — inspect a child of it or raise maxBytes',
             keys: Object.fromEntries(Object.entries(plain).map(([k, v]) => [
                 k,
                 describeBrief(v),
@@ -325,7 +327,8 @@ root = document) {
     let outcome;
     while (outcome === undefined) {
         const ready = root.querySelector('[data-app-phase="ready"]') !== null &&
-            root.querySelector('[data-testid="loading-overlay"]') === null;
+            root.querySelector('[data-testid="loading-overlay"]') === null &&
+            root.querySelector('[data-display-animating="true"]') === null;
         readySince = ready ? (readySince ?? Date.now()) : undefined;
         if (readySince !== undefined && Date.now() - readySince >= READY_HOLD_MS) {
             outcome = { settled: true };
@@ -355,7 +358,7 @@ root = document) {
                 .filter(v => 'phase' in v || 'error' in v),
             ...allTracks(session)
                 .map(t => ({ trackId: t.configuration.trackId, ...displayState(t) }))
-                .filter(t => 'phase' in t || 'error' in t),
+                .filter(t => 'phase' in t || 'error' in t || 'notices' in t),
         ]
         : [];
     const offscreen = session ? offscreenViews(session, root) : undefined;
@@ -375,7 +378,7 @@ root = document) {
 function offscreenViews(session, root) {
     const win = root.ownerDocument?.defaultView ?? window;
     const windowHeight = win.innerHeight;
-    const pageHeight = win.document.documentElement.scrollHeight;
+    const measured = overflow(root);
     const containers = new Map([
         ...root.querySelectorAll('[data-testid^="view-container-"]'),
     ].map(el => [el.dataset.testid.slice('view-container-'.length), el]));
@@ -391,23 +394,154 @@ function offscreenViews(session, root) {
             ]
             : [];
     });
-    return pageHeight > windowHeight || views.length
+    return measured.pageHeight > measured.windowHeight || views.length
         ? {
-            pageHeight,
-            windowHeight,
+            pageHeight: measured.pageHeight,
+            windowHeight: measured.windowHeight,
             scrollY: Math.round(win.scrollY),
             views,
-            note: 'the session is taller than the window; a viewport screenshot cuts these views off — shrink track heights, or screenshot with fullPage: true. A view with a negative top is scrolled out above the viewport (scrollY says by how much), not missing',
+            note: 'the session is taller than the window; a viewport screenshot cuts these views off — await jb.fitToWindow() to shrink what is open until it fits, or screenshot with fullPage: true. A view with a negative top is scrolled out above the viewport (scrollY says by how much), not missing',
         }
         : undefined;
 }
+// Neither app scrolls the document: a column inside the app scrolls, so the
+// document's scrollHeight equals the window's height with a view running 700
+// px past it. The overflow is the scrolling ancestor's, when one exists.
+function scrollerOf(root) {
+    const container = root.querySelector('[data-testid^="view-container-"]');
+    const win = root.ownerDocument?.defaultView ?? window;
+    for (let el = container?.parentElement; el; el = el.parentElement) {
+        const { overflowY } = win.getComputedStyle(el);
+        if ((overflowY === 'auto' || overflowY === 'scroll') &&
+            el.scrollHeight > el.clientHeight) {
+            return el;
+        }
+    }
+    return undefined;
+}
+// The trailing overscroll ViewStack renders below the last view, which exists so
+// a newly-added view can scroll to the middle of the port. It is room, not
+// content, and it is up to 300px of a scrollHeight, so a shrink that charges it
+// to the views leaves them that much short of the window — the E. coli take's
+// dotplot was cut to 312px of the 600 that fit.
+function overscrollHeight(scroller) {
+    const spacer = scroller.querySelector('[data-testid="view-stack-overscroll"]');
+    return spacer ? Math.round(spacer.getBoundingClientRect().height) : 0;
+}
+function overflow(root) {
+    const scroller = scrollerOf(root);
+    if (scroller) {
+        return {
+            pageHeight: scroller.scrollHeight - overscrollHeight(scroller),
+            windowHeight: scroller.clientHeight,
+        };
+    }
+    const win = root.ownerDocument?.defaultView ?? window;
+    return {
+        pageHeight: win.document.documentElement.scrollHeight,
+        windowHeight: win.innerHeight,
+    };
+}
+// What a shrink can leave a display, a synteny band or a dotplot at: enough to
+// still read a track's name and see that it drew.
+const MIN_HEIGHT_PX = 40;
+// Everything on screen whose height is its own state: each shown track's
+// display, each synteny band, and a view whose height is a declared property
+// rather than the sum of its tracks (a dotplot). A linear view's `height` is a
+// getter over its tracks, so shrinking it is shrinking them.
+function shrinkables(session) {
+    return openViews(session).flatMap(view => {
+        const v = view;
+        const declared = isStateTreeNode(view) &&
+            getType(view).properties
+                ?.height !== undefined;
+        const own = declared && typeof v.height === 'number' && v.setHeight
+            ? [{ what: `view ${v.id}`, height: v.height, setHeight: v.setHeight }]
+            : [];
+        const bands = (v.levels ?? []).flatMap((level, i) => typeof level.height === 'number' && level.setHeight
+            ? [
+                {
+                    what: `view ${v.id} band ${i}`,
+                    height: level.height,
+                    setHeight: level.setHeight,
+                },
+            ]
+            : []);
+        const displays = viewTracks(view).flatMap(track => {
+            const d = track.activeDisplay;
+            return d && typeof d.height === 'number' && d.setHeight
+                ? [
+                    {
+                        what: track.configuration.trackId,
+                        height: d.height,
+                        setHeight: d.setHeight,
+                    },
+                ]
+                : [];
+        });
+        return [...own, ...bands, ...displays];
+    });
+}
+/**
+ * Shrink what is open until the session fits the window, and say what moved.
+ *
+ * Every filmed take spent two to five screenshot rounds on this by hand: the
+ * settle reported `offscreen`, the agent guessed which heights to cut and by
+ * how much, and looked again. The overflow is arithmetic the settle already
+ * does; this spends it across every display, band and dotplot in proportion to
+ * the headroom each has above the floor, so tall tracks give up the most and
+ * nothing goes below readable.
+ */
+async function fitToWindow(session, settleMs, root = document) {
+    const before = overflow(root);
+    const excess = before.pageHeight - before.windowHeight;
+    if (excess <= 0) {
+        return { fits: true, ...before };
+    }
+    const items = shrinkables(session);
+    const headroom = items.map(i => Math.max(0, i.height - MIN_HEIGHT_PX));
+    const available = headroom.reduce((a, b) => a + b, 0);
+    const cut = Math.min(excess, available);
+    const shrunk = items.flatMap((item, i) => {
+        const share = available ? Math.round((cut * headroom[i]) / available) : 0;
+        if (share <= 0) {
+            return [];
+        }
+        const to = item.height - share;
+        item.setHeight(to);
+        return [{ what: item.what, from: item.height, to }];
+    });
+    const settle = await waitReady(settleMs, session, root);
+    const after = overflow(root);
+    const left = after.pageHeight - after.windowHeight;
+    return {
+        fits: left <= 0,
+        overflowBefore: excess,
+        overflowAfter: Math.max(0, left),
+        shrunk,
+        ...(left > 0
+            ? {
+                note: available < excess
+                    ? `everything shrinkable is at its ${MIN_HEIGHT_PX} px floor — hide a track or a view, or screenshot with fullPage: true`
+                    : 'still taller than the window after the settle — call jb.fitToWindow() again',
+            }
+            : {}),
+        ...settle,
+    };
+}
+// The catalog is the largest result of nearly every agent run — the 129 volvox
+// rows were 20 KB — so a row carries what picks a track out of the list and
+// nothing more. The adapter type is `jb.inspect`'s or `jb.describeSlots`' to
+// answer for the one track an agent went on to use.
+//
+// Dropping assemblyNames wherever the session has a single assembly saved
+// nothing and made the row shape vary by session: a config declares far more
+// assemblies than it opens, and volvox — every eval run's config — declares 10.
 function trackEntry(conf) {
-    const adapter = readConfObject(conf, 'adapter');
     return {
         trackId: conf.trackId,
         name: readConfObject(conf, 'name'),
         type: conf.type,
-        ...(adapter.type ? { adapterType: adapter.type } : {}),
         // getConfAssemblyNamesOrNone, not the slot: an assembly's sequence track
         // has no assemblyNames slot and answers through its parent assembly
         assemblyNames: getConfAssemblyNamesOrNone(conf),
@@ -439,21 +573,11 @@ function listTracks(session, searchArg, limitArg) {
     };
 }
 function pickView(session, args, capability, wants) {
-    const viewId = typeof args.viewId === 'string' ? args.viewId : '';
-    const candidates = openViews(session);
-    if (viewId) {
-        const named = candidates.find(v => v.id === viewId);
-        if (!named) {
-            throw new Error(`No view with id "${viewId}". Open views: ${candidates.map(v => `${v.id} (${v.type})`).join(', ')}`);
-        }
-        if (typeof viewSelf(named)[capability] !== 'function') {
-            throw new Error(`View ${named.id} (${named.type}) does not support this`);
-        }
-        return named;
-    }
+    const viewId = typeof args.viewId === 'string' ? args.viewId : undefined;
+    const candidates = viewScope(session, viewId);
     const able = candidates.filter(v => typeof viewSelf(v)[capability] === 'function');
     if (!able.length) {
-        throw new Error(`No open view supports this. Open views: ${candidates.map(v => v.type).join(', ') || 'none'} — jb.loadSessionSpec can open one.`);
+        throw new Error(`No ${inScope(viewId)} supports this (${candidates.map(v => v.type).join(', ') || 'none open'}) — jb.loadSessionSpec can open one.`);
     }
     // A view on another assembly would show the track and render nothing, with a
     // successful-looking result — the same silent mismatch visibleRegionsOf
@@ -470,26 +594,33 @@ function pickView(session, args, capability, wants) {
     if (!canDisplay.length) {
         throw new Error(`No open view can display a ${wants.trackType} (open views: ${onAssembly.map(v => v.type).join(', ')})`);
     }
-    return onlyView(canDisplay, 'could take this');
+    return onlyView(session, canDisplay, 'could take this', viewId);
+}
+// A synteny view's rows count as open views (they are what shows a region and
+// a track), and an agent looking at one synteny view read "3 views are open"
+// with nothing saying two of them were its rows.
+function parentView(session, view) {
+    return openViews(session).find(v => v.ownViews.includes(view));
 }
-function describeView(view) {
+function describeView(session, view) {
     const v = viewSelf(view);
     const on = v.assemblyNames?.length ? ` on ${v.assemblyNames.join(', ')}` : '';
     const at = v.coarseVisibleLocStrings ? ` at ${v.coarseVisibleLocStrings}` : '';
-    return `${v.id} (${v.type}${on}${at})`;
-}
-// A name that matches several views has no right first answer: two linear
-// views of one assembly at two loci both "show the track", and taking the
-// first restyles one row or reads one region while the settle reports both.
-// The named-but-missing case already throws and lists the open views, so the
-// unnamed-and-plural case does the same.
-function onlyView(candidates, relation) {
+    const parent = parentView(session, view);
+    const row = parent ? `, a row of ${parent.id}` : '';
+    return `${v.id} (${v.type}${on}${at}${row})`;
+}
+function onlyView(session, candidates, relation, viewId) {
+    const named = candidates.find(v => v.id === viewId);
+    if (named) {
+        return named;
+    }
     const [first, ...rest] = candidates;
     if (!first) {
         throw new Error('No open view');
     }
     if (rest.length) {
-        throw new Error(`${candidates.length} views ${relation}: ${candidates.map(v => describeView(v)).join('; ')} — pass viewId to say which`);
+        throw new Error(`${candidates.length} views ${relation}: ${candidates.map(v => describeView(session, v)).join('; ')} — pass viewId to say which`);
     }
     return first;
 }
@@ -498,58 +629,77 @@ function viewById(session, viewId) {
     if (viewId !== undefined) {
         const named = candidates.find(v => v.id === viewId);
         if (!named) {
-            throw new Error(`No view with id "${viewId}". Open views: ${candidates.map(v => describeView(v)).join('; ') || 'none'}`);
+            throw new Error(`No view with id "${viewId}". Open views: ${candidates.map(v => describeView(session, v)).join('; ') || 'none'}`);
         }
         return named;
     }
     if (!candidates.length) {
         throw new Error('No view is open — jb.loadSessionSpec can open one');
     }
-    return onlyView(candidates, 'are open');
+    return onlyView(session, candidates, 'are open');
+}
+function inScope(viewId) {
+    return viewId === undefined ? 'open view' : `view in ${viewId}`;
+}
+function viewScope(session, viewId) {
+    return viewId === undefined
+        ? openViews(session)
+        : viewAndNested(viewById(session, viewId));
 }
 function shownTrackModel(session, trackId, viewId) {
-    const pool = viewId === undefined
-        ? allTracks(session)
-        : viewTracks(viewById(session, viewId));
-    const shown = pool.filter(t => t.configuration.trackId === trackId);
-    if (shown.length > 1) {
-        const where = openViews(session)
-            .filter(v => viewTracks(v).some(t => t.configuration.trackId === trackId))
-            .map(v => describeView(v));
-        throw new Error(`"${trackId}" is shown in ${shown.length} views: ${where.join('; ')} — pass viewId to say which`);
-    }
-    const [track] = shown;
+    const trackOf = (v) => viewTracks(v).find(t => t.configuration.trackId === trackId);
+    const showing = viewScope(session, viewId).filter(v => trackOf(v));
     // undefined here was followed by ".activeDisplay" on the next line of every
     // agent's code, and a TypeError says nothing about which of the two causes
     // it was
-    if (!track) {
+    if (!showing.length) {
         throw new Error(session.getTrackById(trackId)
-            ? `"${trackId}" is not shown in ${viewId === undefined ? 'any open view' : `view ${viewId}`} — await view.launchTrack("${trackId}") first; jb.sessionSummary() lists what each view shows`
+            ? `"${trackId}" is not shown in any ${inScope(viewId)} — await view.launchTrack("${trackId}") first; jb.sessionSummary() lists what each view shows`
             : `No track with trackId "${trackId}" — jb.listTracks() shows what is available`);
     }
-    return track;
+    return trackOf(onlyView(session, showing, `show "${trackId}"`, viewId));
 }
-async function locToRegion(session, conf, loc, assemblyArg) {
+function isRegionLoc(loc) {
+    return (!!loc &&
+        typeof loc === 'object' &&
+        typeof loc.refName === 'string');
+}
+async function trackAssembly(session, conf, requested) {
     // getConfAssemblyNamesOrNone, not the assemblyNames slot: an assembly's own
     // sequence track has no such slot and answers through its parent assembly
     const trackAssemblies = getConfAssemblyNamesOrNone(conf);
-    const assemblyName = assemblyArg ?? trackAssemblies[0];
+    const assemblyName = requested ?? trackAssemblies[0];
     if (assemblyName === undefined) {
         throw new Error('The track names no assembly; pass assembly explicitly');
     }
     // a named assembly the track is not on renames the region against the wrong
     // alias set and answers with the wrong assembly's coordinates, or nothing
-    if (assemblyArg !== undefined &&
+    if (requested !== undefined &&
         trackAssemblies.length &&
-        !trackAssemblies.some(name => isSameAssemblyName(name, assemblyArg, session.assemblyManager))) {
-        throw new Error(`Track "${conf.trackId}" is on ${trackAssemblies.join(', ')}, not "${assemblyArg}"`);
+        !trackAssemblies.some(name => isSameAssemblyName(name, requested, session.assemblyManager))) {
+        throw new Error(`Track "${conf.trackId}" is on ${trackAssemblies.join(', ')}, not "${requested}"`);
     }
     const assembly = await session.assemblyManager.waitForAssembly(assemblyName);
     if (!assembly) {
         throw new Error(`Assembly "${assemblyName}" could not be loaded`);
     }
-    const parsed = parseLocString(loc, refName => assembly.isValidRefName(refName));
+    return { assembly, assemblyName };
+}
+async function locToRegion(session, conf, loc, assemblyArg) {
+    if (typeof loc !== 'string' && !isRegionLoc(loc)) {
+        throw new Error(`jb.getFeatures takes loc as ONE place — a locstring ("ctgA:1-100") or a region object ({ refName, start, end }) — and got ${JSON.stringify(loc)}${Array.isArray(loc) ? '; several regions go in regions: [...]' : ''}`);
+    }
+    const { assembly, assemblyName } = await trackAssembly(session, conf, assemblyArg ?? (typeof loc === 'string' ? undefined : loc.assemblyName));
+    const parsed = typeof loc === 'string'
+        ? parseLocString(loc, refName => assembly.isValidRefName(refName))
+        : loc;
     const refName = assembly.getCanonicalRefName(parsed.refName) ?? parsed.refName;
+    // parseLocString asks this for the string form. A region object skipping it
+    // read empty on a name the assembly does not have, which is the answer this
+    // surface exists to turn into an error.
+    if (!assembly.isValidRefName(refName)) {
+        throw new Error(`"${parsed.refName}" is not a sequence in ${assemblyName} — jb.visibleRegions() and jb.sessionSummary() name what is there`);
+    }
     const bounds = assembly.regions?.find(r => r.refName === refName);
     return {
         assemblyName,
@@ -564,9 +714,9 @@ async function visibleRegionsOf(session, viewId, preferTrackId, trackAssemblies
     // freshly spec-loaded view stays in that state briefly even after the
     // app-phase marker reads ready, since a view with no width has no display
     // fetching anything.
-    const regionBearing = openViews(session).filter(v => (!viewId || v.id === viewId) && 'visibleRegions' in v);
+    const regionBearing = viewScope(session, viewId).filter(v => 'visibleRegions' in v);
     if (!regionBearing.length) {
-        throw new Error('No view that shows a region — pass loc, or open a linear view first');
+        throw new Error(`No ${inScope(viewId)} shows a region — pass loc, or open a linear view`);
     }
     // a view on another assembly than the track would hand its region to a file
     // that has no such sequence, which answers nothing, silently
@@ -575,13 +725,13 @@ async function visibleRegionsOf(session, viewId, preferTrackId, trackAssemblies
             viewSelf(v).assemblyNames.some(name => trackAssemblies.some(t => isSameAssemblyName(name, t, session.assemblyManager))))
         : regionBearing;
     if (!candidates.length) {
-        throw new Error(`No open view is on ${trackAssemblies.join(', ')} (open views: ${regionBearing.map(v => describeView(v)).join('; ')}) — pass loc, or open a view on that assembly`);
+        throw new Error(`No open view is on ${trackAssemblies.join(', ')} (open views: ${regionBearing.map(v => describeView(session, v)).join('; ')}) — pass loc, or open a view on that assembly`);
     }
     // among region-bearing views, the ones actually showing the track — two
     // views on two assemblies would otherwise send the first view's namespace to
     // the second view's file, which answers nothing, silently
     const showing = candidates.filter(v => viewTracks(v).some(t => t.configuration.trackId === preferTrackId));
-    const chosen = onlyView(showing.length ? showing : candidates, showing.length ? `show "${preferTrackId}"` : 'show a region');
+    const chosen = onlyView(session, showing.length ? showing : candidates, showing.length ? `show "${preferTrackId}"` : 'show a region', viewId);
     const view = viewSelf(chosen);
     const deadline = Date.now() + 10_000;
     let visible;
@@ -638,11 +788,12 @@ async function fetchFeatures(session, trackId, regions, requestedByteLimit) {
     // than because a view scrolled.
     const byteLimit = agentByteLimit(readConfObject(conf, ['adapter', 'fetchSizeLimit']), requestedByteLimit);
     const { rpcManager } = session;
-    const stopToken = createStopToken();
+    const controller = new AbortController();
+    const { signal } = controller;
     // desktop's MCP relay gives up at 150s, so the read must not outlive it —
     // and an agent-triggered read of a dense region wants a ceiling either way
     const stopTimer = setTimeout(() => {
-        stopStopToken(stopToken);
+        controller.abort();
     }, 120_000);
     retainAdapterSession(rpcManager, sessionId);
     try {
@@ -655,7 +806,7 @@ async function fetchFeatures(session, trackId, regions, requestedByteLimit) {
         // whole answer is the failure this surface exists to prevent.
         const bytes = await rpcManager.call(sessionId, 'CoreGetRegionByteEstimate', 
         // eslint-disable-next-line no-restricted-syntax -- reports nothing: an agent awaits the returned features and no display or dialog exists to show a phase label or bar
-        { adapterConfig, regions, scope: 'largestRegion', stopToken });
+        { adapterConfig, regions, scope: 'largestRegion', signal });
         if (bytes !== undefined && bytes > byteLimit) {
             throw new Error(`region too large for jb.getFeatures: the largest region is ~${bytes} bytes against a limit of ${byteLimit}. Narrow the region, or pass an explicit byteLimit if you mean to pull this much.`);
         }
@@ -663,7 +814,7 @@ async function fetchFeatures(session, trackId, regions, requestedByteLimit) {
         return await rpcManager.call(sessionId, 'CoreGetFeatures', {
             adapterConfig,
             regions,
-            stopToken,
+            signal,
         });
     }
     finally {
@@ -675,14 +826,19 @@ async function fetchFeatures(session, trackId, regions, requestedByteLimit) {
 // throws "can't use local files in the browser" at the FIRST READ, not here, so
 // accepting one would report a track added and then fail inside the display
 // where the agent is least likely to connect it to what it asked for.
+const URL_TEXT = /^https?:\/\//;
+const ABSOLUTE_PATH = /^(?:\/|[a-zA-Z]:[\\/]|\\\\)/;
+function isFileLocationText(spec) {
+    return URL_TEXT.test(spec) || ABSOLUTE_PATH.test(spec);
+}
 function fileLocation(spec) {
-    if (/^https?:\/\//.test(spec)) {
+    if (URL_TEXT.test(spec)) {
         return { uri: spec, locationType: 'UriLocation' };
     }
     // The app's working directory is not the agent's, and a relative path
     // resolves against the app's: under a packaged app that is "/", so the read
     // fails at the first fetch and reports through the display, not here.
-    if (!/^(?:\/|[a-zA-Z]:[\\/]|\\\\)/.test(spec)) {
+    if (!ABSOLUTE_PATH.test(spec)) {
         throw new Error(`jb.addTrack needs an absolute local path or a URL: "${spec}" is relative and would resolve against the app's working directory, not yours.`);
     }
     if (!isElectron) {
@@ -733,32 +889,55 @@ function locationsOf(value) {
 // Vocabulary introspection: every config slot a live config node's schema
 // defines, so code never has to guess which settings keys exist — an unknown
 // key is not an error, only an entry in applyDisplaySettings' `unapplied` list.
+// A nested object (`facet`, `color`) lists its own slots, and the slot its
+// string shorthand lifts into.
 function describeSlots(conf) {
     const definition = getConfigurationSchemaDefinition(conf) ?? {};
-    return Object.fromEntries(Object.entries(definition).flatMap(([name, def]) => isSlotDefinitionEntry(def)
-        ? [
-            [
-                name,
-                {
-                    type: def.type,
-                    ...(def.description ? { description: def.description } : {}),
-                    defaultValue: def.defaultValue,
-                },
-            ],
-        ]
-        : []));
+    return Object.fromEntries(Object.entries(definition).flatMap(([name, def]) => {
+        if (isSlotDefinitionEntry(def)) {
+            return [
+                [
+                    name,
+                    {
+                        type: def.type,
+                        ...(def.description ? { description: def.description } : {}),
+                        defaultValue: def.defaultValue,
+                    },
+                ],
+            ];
+        }
+        if (isConfigurationSubschema(conf, name)) {
+            const node = conf[name];
+            const shorthand = getConfigurationSchemaOptions(node)?.shorthand;
+            return [
+                [
+                    name,
+                    {
+                        type: mst
+                            .getType(node)
+                            .name.replace(/ConfigurationSchema$/, ''),
+                        slots: describeSlots(node),
+                        ...(shorthand ? { shorthand } : {}),
+                    },
+                ],
+            ];
+        }
+        return [];
+    }));
 }
 // The raw primitive under all of the above: Claude-authored code against the
 // live model graph. The renderer already runs with nodeIntegration and the
 // bridge socket is user-only, so this grants what the surface as a whole
 // already grants — expressed directly instead of through a curated verb.
-// The re-export registry is what pluginManager.jbrequire serves: the same
-// pinned ABI module names external plugins link against (ReExports/modules.ts,
-// abiBaseline.json). It stays empty until a runtime plugin loads, so each
-// evaluate (re)installs it — import() is memoized, so this is one lookup and
-// an idempotent assignment, with no module-level flag to hold.
+// The re-export registry is what pluginManager.jbrequire serves, the modules
+// external plugins link against. It stays empty until a runtime plugin loads,
+// and a loaded plugin fills it with the product's map, which serves every
+// bundled @jbrowse package rather than core alone — so this fills only an
+// empty registry.
 export async function ensureReExports() {
-    setReExportRegistry((await import('@jbrowse/core/ReExports/modules')).default);
+    if (Object.keys(getReExportRegistry()).length === 0) {
+        setReExportRegistry((await import('@jbrowse/core/ReExports/modules')).default);
+    }
 }
 // The front door for an agent that just found `jb` and knows nothing else —
 // jbrowse-web's console banner and meta tag point here, because a browser
@@ -766,13 +945,13 @@ export async function ensureReExports() {
 // contract from.
 const JB_HELP = `jb drives this JBrowse app programmatically (window.jb in a browser; the same object is the "jb" argument of JBrowse Desktop's run_javascript MCP tool).
 
-Orient first: jb.sessionSummary(). Introspect, never guess: jb.listTracks(search?, limit?) answers { total, tracks } with the trackIds; jb.describeSlots(jb.trackModel('someTrackId').activeDisplay.configuration) for the settings keys a display accepts — an unknown settings key is not an error, it lands in applyDisplaySettings' "unapplied" list, so read the report; jb.inspect('views.0') for a live node's getters, actions and modelType.
+Orient first: jb.sessionSummary(). Introspect, never guess: jb.listTracks(search?, limit?) answers { total, tracks } with the trackIds; jb.describeSlots(jb.trackModel('someTrackId').activeDisplay.configuration) for the settings keys a display accepts — an unknown settings key is not an error, it lands in applyDisplaySettings' "unapplied" list as { key, reason }, so read the report; jb.inspect(node) — jb.view(), jb.trackModel('someTrackId'), session.views[0] — for its getters, actions and modelType.
 
-The model is mobx-state-tree: mutate only through actions (raw assignment throws), and write display settings with track.applyDisplaySettings(settings). Build views declaratively with jb.loadSessionSpec({ views: [{ type: 'LinearGenomeView', assembly, loc, tracks: [...] }] }); arrange the views already open into panels with session.layoutViews({ direction: 'horizontal', children: [{ views: [viewId] }, ...] }) — leaves name view ids or indexes into session.views; add data with jb.addTrack({ location }) (an absolute path or a URL); read data with await jb.getFeatures({ trackId, loc?, assembly?, viewId?, regions?, byteLimit? }) (or jb.getFeatures(trackId, loc?, opts?)), which renames refNames ("chr1" vs "1") so the file answers and reads on the worker the track's display uses — raw adapter code must call jb.renameRegionsIfNeeded itself. After changing anything, await jb.waitReady(ms) and read its notifications and notReady lists before trusting the screen.
+The model is mobx-state-tree: mutate only through actions (raw assignment throws), and write display settings with track.applyDisplaySettings(settings). A feature or variant track groups and colors through two settings, track.applyDisplaySettings({ facet: 'strand' or { field, domain? }, color: a CSS color or { field: 'type', domain?, range? } }), where null resets any setting; it filters with activeDisplay.setJexlFilters([jexl]). An alignments track takes the same facet, its field a read dimension ('pairOrientation', 'mapq', ...) or a tag ('tags.HP'). Build views declaratively with jb.loadSessionSpec({ views: [{ type: 'LinearGenomeView', assembly, loc, tracks: [...] }] }), which replaces the session; jb.addView(oneViewSpec) opens one more view beside what is open; jb.setSession(document) rewrites the session as a document — what jb.mst.getSnapshot(jb.session) answers, edited: a view keeps its id and is patched in place, loc on it navigates, a { trackId } entry in its tracks opens that track. Act on a view with await view.navToLocString('BRCA1' or 'chr1:1-1000'), which also SHOWS the track whose search index answered a gene name unless a 4th arg { showHitTrack: false } says not to; await view.launchTrack(trackId, {}, settings) shows a track with settings, view.hideTrack(trackId) hides it. Arrange open views into panels with session.layoutViews({ direction: 'horizontal', children: [{ views: [viewId] }, ...] }), a leaf naming view ids or session.views indexes; await jb.fitToWindow() shrinks what is open until the session fits the window; add data with jb.addTrack({ location }) (an absolute path or a URL), or show a track the catalog already holds with jb.addTrack({ trackId, settings? }); read data with await jb.getFeatures({ trackId, loc?, assembly?, viewId?, regions?, byteLimit? }), which renames refNames ("chr1" vs "1") so the file answers and reads on the worker the track's display uses. Anything lower level is jb.require('@jbrowse/core/util') and friends, the module registry plugins link against. After changing anything, await jb.waitReady(ms) and read its notifications and notReady lists before trusting the screen.
 
-Views nest and several can be open. jb.view(viewId?) is the open view, and jb.view(), jb.trackModel(trackId), jb.visibleRegions(), jb.addTrack and jb.getFeatures over a visible region throw naming the candidates rather than picking one when more than one view could answer — pass viewId (from jb.sessionSummary()) to say which.
+Views nest and several can be open. jb.view(viewId?) is the open view, and jb.view(), jb.trackModel(trackId), jb.visibleRegions(), jb.addTrack and jb.getFeatures over a visible region throw naming the candidates rather than picking one when more than one view could answer — pass viewId (from jb.sessionSummary()) to say which. A synteny or breakpoint view's viewId also covers its rows: the named view answers when it can, and otherwise its rows do.
 
-Full guide: https://jbrowse.org/jb2/docs/agents_live_model (JBrowse Desktop serves the same guide offline through its MCP docs tool — Help menu, "Connect an AI agent...").`;
+Full guide: https://jbrowse.org/jb2/docs/agents_live_model (offline in JBrowse Desktop's MCP docs tool).`;
 // The helper library an agent drives the app through. Built from the plugin
 // manager alone, so one of these serves a whole app rather than one session —
 // which is what lets jbrowse-web hand the same object to every caller for the
@@ -817,22 +996,19 @@ export function createJbApi(pluginManager, options = {}) {
         readConfObject,
         getConf,
         describeSlots,
-        parseLocString,
-        getFeatureAdapterOrThrow,
-        getRpcSessionId,
-        renameRegionsIfNeeded,
-        createStopToken,
-        stopStopToken,
         // a default because an omitted number made the deadline NaN, and a view
         // that never readied then held the call open to the relay's own timeout
         waitReady: async (timeoutMs = 30_000) => reported(await waitReady(timeoutMs, live())),
         sessionSummary: () => sessionSummary(live()),
-        inspect: (path, maxInspectBytes) => inspectSession(live(), { path, maxBytes: maxInspectBytes }),
+        inspect: (target, maxInspectBytes) => inspectSession(live(), { target, maxBytes: maxInspectBytes }),
         listTracks: (search, limit) => listTracks(live(), search, limit),
         view: (viewId) => viewById(live(), viewId),
         trackModel: (trackId, viewId) => shownTrackModel(live(), trackId, viewId),
         visibleRegions: (viewId) => visibleRegionsOf(live(), viewId),
         loadSessionSpec: async (spec, settleMs) => reported(await loadSpec(pluginManager, { spec, settleMs })),
+        addView: async (spec, settleMs = SPEC_SETTLE_DEFAULT_MS) => reported(await addView(pluginManager, live(), spec, settleMs)),
+        setSession: async (document, settleMs = SPEC_SETTLE_DEFAULT_MS) => reported(await setSession(pluginManager, live(), document, settleMs)),
+        fitToWindow: async (settleMs = 30_000) => reported(await fitToWindow(live(), settleMs)),
         addTrack: (opts) => addTrack(pluginManager, live(), opts).then(reported),
         // Two of four filmed takes wrote jb.getFeatures('trackId', loc) and lost a
         // turn to "No track with trackId undefined", and a third wrote
@@ -848,12 +1024,17 @@ export function createJbApi(pluginManager, options = {}) {
             if (!conf) {
                 throw new Error(`No track with trackId "${fetchArgs.trackId}" — jb.listTracks() shows what is available`);
             }
-            const regions = fetchArgs.regions ??
-                (fetchArgs.loc !== undefined
+            // `regions` entries go through locToRegion as `loc` does. Passed
+            // straight to the fetch they skipped the canonical rename, and an entry
+            // carrying no assemblyName reached renameRegionsIfNeeded with nothing to
+            // rename against — an alias spelling then read empty and said nothing.
+            const regions = fetchArgs.regions
+                ? await Promise.all(fetchArgs.regions.map(region => locToRegion(session, conf, region, fetchArgs.assembly)))
+                : fetchArgs.loc !== undefined
                     ? [
                         await locToRegion(session, conf, fetchArgs.loc, fetchArgs.assembly),
                     ]
-                    : await visibleRegionsOf(session, fetchArgs.viewId, fetchArgs.trackId, getConfAssemblyNamesOrNone(conf)));
+                    : await visibleRegionsOf(session, fetchArgs.viewId, fetchArgs.trackId, getConfAssemblyNamesOrNone(conf));
             return fetchFeatures(session, fetchArgs.trackId, regions, fetchArgs.byteLimit);
         },
     };
@@ -862,13 +1043,45 @@ export function createJbApi(pluginManager, options = {}) {
 // a spec load on a busy machine passed 30s and answered settled:false over
 // views that were fine; the wait exits the moment they are ready
 const ADD_TRACK_SETTLE_MS = 60_000;
+function namesAFile(value) {
+    return Array.isArray(value)
+        ? value.some(l => typeof l === 'string' && isFileLocationText(l))
+        : typeof value === 'string' && isFileLocationText(value);
+}
+// The name an agent meant as a catalog trackId: `trackId`, or a `location`
+// that is neither a URL nor a path. Agent runs reached for jb.addTrack to SHOW
+// a track already in the catalog in both spellings, and each paid a round trip
+// for a refusal that only named another helper.
+//
+// A location that names a file is the file route whatever else came with it:
+// `trackId` beside `location` is how a track CONFIG spells this, and taking it
+// as the catalog route would refuse the file the caller asked to add.
+function catalogName(args) {
+    if (namesAFile(args.location)) {
+        return undefined;
+    }
+    if (typeof args.trackId === 'string') {
+        return args.trackId;
+    }
+    return typeof args.location === 'string' ? args.location : undefined;
+}
 async function addTrack(pluginManager, session, args) {
+    const named = catalogName(args);
+    const inCatalog = named === undefined ? undefined : session.getTrackById(named);
+    // before the add-rights check: showing a track the catalog already holds
+    // adds nothing to it
+    if (inCatalog) {
+        return showCatalogTrack(pluginManager, session, inCatalog, args);
+    }
+    if (named !== undefined && typeof args.trackId === 'string') {
+        throw new Error(`No track with trackId "${args.trackId}" — jb.listTracks() shows what the catalog holds, and jb.addTrack({ location }) adds a file to it.`);
+    }
     if (!isSessionWithAddSessionTrack(session)) {
         throw new Error('This session cannot add tracks');
     }
     const location = locationsOf(args.location);
     if (!location.length) {
-        throw new Error('jb.addTrack needs a location (an absolute local path or a URL)');
+        throw new Error('jb.addTrack needs a location (an absolute local path or a URL) to add a file, or the trackId of a track already in the catalog to show it — jb.listTracks() lists those.');
     }
     const requested = typeof args.assembly === 'string' ? args.assembly : session.assemblyNames[0];
     if (requested === undefined) {
@@ -893,25 +1106,182 @@ async function addTrack(pluginManager, session, args) {
         adapterType: conf.adapter.type,
         assembly,
     };
-    if (args.show === false) {
-        return summary;
+    return args.show === false
+        ? summary
+        : {
+            ...summary,
+            ...(await showTrack(pluginManager, session, { trackId: conf.trackId, trackType: conf.type, assembly }, args)),
+        };
+}
+// A track already in the catalog, shown: the same view choice and the same
+// settle the file route ends in.
+// `conf` is whatever `session.getTrackById` answered, which is a track config
+// but not necessarily a `BaseTrackConfig` — an assembly's ReferenceSequenceTrack
+// declares a subset of those slots. The four reads below are all ones it has.
+async function showCatalogTrack(pluginManager, session, conf, args) {
+    // index, assembly and name describe the file being added, and the catalog's
+    // copy already has all three — taking them here would drop them in silence
+    const fileArgs = ['index', 'assembly', 'name'].filter(key => args[key] !== undefined);
+    if (fileArgs.length) {
+        throw new Error(`"${conf.trackId}" is in the catalog already, so ${fileArgs.join(' and ')} would be ignored — drop ${fileArgs.length > 1 ? 'them' : 'it'}, or pass a location to add a new file.`);
     }
-    const view = pickView(session, args, 'launchTrack', {
-        assembly,
+    const track = {
+        trackId: conf.trackId,
         trackType: conf.type,
+        assembly: getConfAssemblyNamesOrNone(conf)[0],
+    };
+    const adapterType = readConfObject(conf, ['adapter', 'type']);
+    const summary = { ...track, ...(adapterType ? { adapterType } : {}) };
+    // show:false over a catalog trackId asks for nothing — there is no file to
+    // add — and showing it anyway would contradict the flag
+    return args.show === false
+        ? summary
+        : {
+            ...summary,
+            ...(await showTrack(pluginManager, session, track, args)),
+        };
+}
+function isSettings(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+async function showTrack(pluginManager, session, track, args) {
+    const view = pickView(session, args, 'launchTrack', {
+        assembly: track.assembly,
+        trackType: track.trackType,
         pluginManager,
     });
     // awaited: a display state model is lazy in every plugin here, and the
     // synchronous showTrack answers before the chunk lands — so the settle below
     // would run against a session that does not hold the track yet, and report
     // ready over it
-    await viewSelf(view).launchTrack(conf.trackId);
-    const shown = { ...summary, shownInView: view.id };
+    await viewSelf(view).launchTrack(track.trackId, {}, isSettings(args.settings) ? args.settings : undefined);
     // 0 skips the settle, so several adds can share one jb.waitReady
     const settleMs = typeof args.settleMs === 'number' ? args.settleMs : ADD_TRACK_SETTLE_MS;
+    return {
+        shownInView: view.id,
+        ...(settleMs > 0 ? await waitReady(settleMs, session) : {}),
+    };
+}
+/**
+ * One view from one spec entry, into the open session, through the same
+ * launcher extension point `jb.loadSessionSpec` takes for each of its views —
+ * so the entry means the same thing in both places, a ProteinView's
+ * `connectedView` included. `session.launchView` is the other route and does
+ * not: it is `addView` with a snapshot, so it never runs a view's launcher.
+ *
+ * A key the view does not take throws before anything opens. A spec has no
+ * return channel and launches anyway with an error toast; an awaited call has
+ * one, and a view that opened without the setting the agent typed is the
+ * quietly-wrong answer this surface exists to refuse.
+ */
+async function addView(pluginManager, session, spec, settleMs) {
+    if (typeof spec !== 'object' || typeof spec.type !== 'string') {
+        throw new Error('jb.addView takes one view spec — an entry of a session spec\'s "views" array, e.g. { type: "LinearGenomeView", assembly, loc, tracks } (docs topic "session-spec")');
+    }
+    const unlaunchable = viewTypeProblem(pluginManager, spec.type);
+    if (unlaunchable) {
+        throw new Error(unlaunchable);
+    }
+    const { view: entry, problem } = await launchableSpecView(pluginManager, spec);
+    if (problem) {
+        throw new Error(`${problem} — nothing was opened. docs topic "session-spec" lists the keys ${entry.type} takes`);
+    }
+    const { created, view, failure } = await launchSpecView(session, pluginManager, entry);
+    if (failure) {
+        throw new Error(failure.message, { cause: failure.cause });
+    }
+    if (!view) {
+        throw new Error(`${entry.type} opened no view`);
+    }
+    const summary = {
+        viewId: view.id,
+        ...(created.length > 1 ? { created: created.map(v => v.id) } : {}),
+    };
     return settleMs > 0
-        ? { ...shown, ...(await waitReady(settleMs, session)) }
-        : shown;
+        ? { ...summary, ...(await waitReady(settleMs, session)) }
+        : summary;
+}
+/**
+ * The session as one document, rewritten: what `getSnapshot(session)` answers,
+ * edited, handed back. MST reconciles by identifier, so a view, track or
+ * display whose `id` the document keeps is patched in place and stays mounted,
+ * one the document drops is closed, and an entry with no id is new. A view's
+ * launch keys are accepted beside its built state — `loc` navigates it, a
+ * `{ trackId }` entry in its `tracks` opens that track — because the partition
+ * that sorts them runs on every snapshot the view is given, not only its
+ * first.
+ *
+ * Top-level keys the document leaves out keep their current value, so
+ * `{ views: [...] }` is a complete instruction.
+ *
+ * Views leave through the session's own detach first (ADR-069): `applySnapshot`
+ * destroys what the target lacks in place, under components still mounted
+ * over it, which is what undo had to route around.
+ */
+// A key nothing on the far side takes, per view entry. MST drops one silently,
+// and the partition that names it runs at attach — which a view the document
+// KEEPS never reaches, so the commonest edit was the quiet one.
+//
+// Reported, not refused, like the same mistake on a session spec: a document
+// that works today must not cost the whole call. `acceptedKeys` answers for a
+// legacy spelling too — a view's `passThrough` declares the ones its own
+// preProcessSnapshot converts, which is what makes this a question about the
+// view type rather than about whatever members the live node happens to have.
+function unknownViewKeys(pluginManager, entry) {
+    if (typeof entry !== 'object' ||
+        entry === null ||
+        typeof entry.type !== 'string') {
+        return [];
+    }
+    const { type, views, ...keyed } = entry;
+    const nested = Array.isArray(views)
+        ? views.flatMap(view => unknownViewKeys(pluginManager, view))
+        : [];
+    if (!pluginManager.getElementTypeRecord('view').has(type)) {
+        return nested;
+    }
+    const viewType = pluginManager.getViewType(type);
+    const accepted = viewType.acceptedKeys ??
+        Object.keys(viewType.stateModel.properties);
+    const unknown = Object.keys(keyed).filter(key => !accepted.includes(key));
+    return [
+        ...(unknown.length
+            ? [
+                `${unknownKeysMessage(type, unknown)}${viewType.launchKeys
+                    ? ''
+                    : ' — a document runs no launcher, so its launch keys go through jb.addView'}`,
+            ]
+            : []),
+        ...nested,
+    ];
+}
+async function setSession(pluginManager, session, document, settleMs) {
+    if (typeof document !== 'object' ||
+        document === null ||
+        Array.isArray(document)) {
+        throw new Error('jb.setSession takes the session as a document: what jb.mst.getSnapshot(jb.session) answers, edited. Top-level keys left out keep their current value.');
+    }
+    const next = {
+        ...getSnapshot(session),
+        ...document,
+    };
+    // a lazily registered view or display type is not in the session's type union
+    // until its model loads, and applySnapshot is synchronous
+    await pluginManager.preloadSessionTypes(next);
+    for (const problem of (Array.isArray(next.views) ? next.views : []).flatMap(entry => unknownViewKeys(pluginManager, entry))) {
+        session.notifyError(problem);
+    }
+    try {
+        ;
+        session.takeOutViewsMissingFrom?.(next);
+        applySnapshot(session, next);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`jb.setSession refused the document: ${detail.length > 1500 ? `${detail.slice(0, 1500)}…` : detail}`, { cause: e });
+    }
+    const settle = await waitReady(settleMs, session);
+    return { ...settle, session: sessionSummary(session) };
 }
 // Under the 45 s one evaluation gets from the Claude in Chrome extension: a
 // cold hosted config settling for the full minute answered nothing there,