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

package/esm/JbApi/jbApi.d.ts

@@ -6,7 +6,7 @@ import * as mst from '@jbrowse/mobx-state-tree';
 import * as mobx from 'mobx';
 import type PluginManager from '@jbrowse/core/PluginManager';
 import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
-import type { AbstractSessionModel } from '@jbrowse/core/util/types';
+import type { AbstractSessionModel, AbstractViewModel } from '@jbrowse/core/util/types';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 /**
  * What jb.getFeatures may pull before it refuses. An explicit request wins so
@@ -28,7 +28,7 @@ interface TrackSelf extends IStateTreeNode {
     configuration: AnyConfigurationModel & {
         trackId: string;
     };
-    displays?: (Record<string, unknown> & DisplaySelf)[];
+    activeDisplay?: Record<string, unknown> & DisplaySelf;
 }
 export declare function sessionOf(pluginManager: PluginManager | undefined): AbstractSessionModel | undefined;
 export declare function safeJson(value: unknown): string;
@@ -42,7 +42,12 @@ export declare function waitReady(timeoutMs: number, session?: AbstractSessionMo
         level: string;
         message: string;
     }[] | undefined;
-    notReady?: (({
+    notReady?: ({
+        error?: string | undefined;
+        phase?: string | undefined;
+        viewId: string;
+        type: string;
+    } | ({
         trackId: string;
     } & Record<"error", unknown>) | ({
         trackId: string;
@@ -50,6 +55,7 @@ export declare function waitReady(timeoutMs: number, session?: AbstractSessionMo
     offscreen?: {
         pageHeight: number;
         windowHeight: number;
+        scrollY: number;
         views: {
             viewId: string;
             top: number;
@@ -64,7 +70,12 @@ export declare function waitReady(timeoutMs: number, session?: AbstractSessionMo
         level: string;
         message: string;
     }[] | undefined;
-    notReady?: (({
+    notReady?: ({
+        error?: string | undefined;
+        phase?: string | undefined;
+        viewId: string;
+        type: string;
+    } | ({
         trackId: string;
     } & Record<"error", unknown>) | ({
         trackId: string;
@@ -72,6 +83,7 @@ export declare function waitReady(timeoutMs: number, session?: AbstractSessionMo
     offscreen?: {
         pageHeight: number;
         windowHeight: number;
+        scrollY: number;
         views: {
             viewId: string;
             top: number;
@@ -94,6 +106,7 @@ interface SlotDescription {
 declare function describeSlots(conf: AnyConfigurationModel): Record<string, SlotDescription>;
 export declare function ensureReExports(): Promise<void>;
 export declare function createJbApi(pluginManager: PluginManager): {
+    help: string;
     readonly session: AbstractSessionModel;
     readonly rootModel: import("@jbrowse/core/util").AbstractRootModel | undefined;
     require: (lib: string | ((...args: any) => any) | {
@@ -111,13 +124,18 @@ export declare function createJbApi(pluginManager: PluginManager): {
     renameRegionsIfNeeded: typeof renameRegionsIfNeeded;
     createStopToken: typeof createStopToken;
     stopStopToken: typeof stopStopToken;
-    waitReady: (timeoutMs: number) => Promise<{
+    waitReady: (timeoutMs?: number) => Promise<{
         settled: boolean;
         notifications?: {
             level: string;
             message: string;
         }[] | undefined;
-        notReady?: (({
+        notReady?: ({
+            error?: string | undefined;
+            phase?: string | undefined;
+            viewId: string;
+            type: string;
+        } | ({
             trackId: string;
         } & Record<"error", unknown>) | ({
             trackId: string;
@@ -125,6 +143,7 @@ export declare function createJbApi(pluginManager: PluginManager): {
         offscreen?: {
             pageHeight: number;
             windowHeight: number;
+            scrollY: number;
             views: {
                 viewId: string;
                 top: number;
@@ -139,7 +158,12 @@ export declare function createJbApi(pluginManager: PluginManager): {
             level: string;
             message: string;
         }[] | undefined;
-        notReady?: (({
+        notReady?: ({
+            error?: string | undefined;
+            phase?: string | undefined;
+            viewId: string;
+            type: string;
+        } | ({
             trackId: string;
         } & Record<"error", unknown>) | ({
             trackId: string;
@@ -147,6 +171,7 @@ export declare function createJbApi(pluginManager: PluginManager): {
         offscreen?: {
             pageHeight: number;
             windowHeight: number;
+            scrollY: number;
             views: {
                 viewId: string;
                 top: number;
@@ -197,7 +222,8 @@ export declare function createJbApi(pluginManager: PluginManager): {
             assemblyNames: string[];
         }[];
     };
-    trackModel: (trackId: string) => TrackSelf | undefined;
+    view: (viewId?: string) => AbstractViewModel;
+    trackModel: (trackId: string, viewId?: string) => TrackSelf;
     visibleRegions: (viewId?: string) => Promise<JbRegion[]>;
     loadSessionSpec: (spec: Record<string, unknown>, settleMs?: number) => Promise<{
         settled: boolean;
@@ -205,7 +231,12 @@ export declare function createJbApi(pluginManager: PluginManager): {
             level: string;
             message: string;
         }[] | undefined;
-        notReady?: (({
+        notReady?: ({
+            error?: string | undefined;
+            phase?: string | undefined;
+            viewId: string;
+            type: string;
+        } | ({
             trackId: string;
         } & Record<"error", unknown>) | ({
             trackId: string;
@@ -213,6 +244,7 @@ export declare function createJbApi(pluginManager: PluginManager): {
         offscreen?: {
             pageHeight: number;
             windowHeight: number;
+            scrollY: number;
             views: {
                 viewId: string;
                 top: number;
@@ -232,7 +264,12 @@ export declare function createJbApi(pluginManager: PluginManager): {
             level: string;
             message: string;
         }[] | undefined;
-        notReady?: (({
+        notReady?: ({
+            error?: string | undefined;
+            phase?: string | undefined;
+            viewId: string;
+            type: string;
+        } | ({
             trackId: string;
         } & Record<"error", unknown>) | ({
             trackId: string;
@@ -240,6 +277,7 @@ export declare function createJbApi(pluginManager: PluginManager): {
         offscreen?: {
             pageHeight: number;
             windowHeight: number;
+            scrollY: number;
             views: {
                 viewId: string;
                 top: number;
@@ -253,64 +291,19 @@ export declare function createJbApi(pluginManager: PluginManager): {
             views: Record<string, unknown>[];
         } | undefined;
     }>;
-    addTrack: (opts: Record<string, unknown>) => Promise<{
-        trackId: string;
-        trackType: string;
-        adapterType: string;
-        assembly: string;
-    } | {
-        settled: boolean;
-        notifications?: {
-            level: string;
-            message: string;
-        }[] | undefined;
-        notReady?: (({
-            trackId: string;
-        } & Record<"error", unknown>) | ({
-            trackId: string;
-        } & Record<"phase", unknown>))[] | undefined;
-        offscreen?: {
-            pageHeight: number;
-            windowHeight: number;
-            views: {
-                viewId: string;
-                top: number;
-                bottom: number;
-            }[];
-            note: string;
-        } | undefined;
-        trackId: string;
-        trackType: string;
-        adapterType: string;
-        assembly: string;
-        shownInView: string;
-    } | {
-        settled: boolean;
-        note: string;
-        notifications?: {
-            level: string;
-            message: string;
-        }[] | undefined;
-        notReady?: (({
-            trackId: string;
-        } & Record<"error", unknown>) | ({
-            trackId: string;
-        } & Record<"phase", unknown>))[] | undefined;
-        offscreen?: {
-            pageHeight: number;
-            windowHeight: number;
-            views: {
-                viewId: string;
-                top: number;
-                bottom: number;
-            }[];
-            note: string;
-        } | undefined;
+    addTrack: (opts: {
+        location: string | string[];
+        index?: string;
+        assembly?: string;
+        name?: string;
+        show?: boolean;
+        viewId?: string;
+        settleMs?: number;
+    }) => Promise<{
         trackId: string;
         trackType: string;
         adapterType: string;
         assembly: string;
-        shownInView: string;
     }>;
     getFeatures: (args: string | {
         trackId: string;
@@ -319,7 +312,11 @@ export declare function createJbApi(pluginManager: PluginManager): {
         regions?: JbRegion[];
         viewId?: string;
         byteLimit?: number;
-    }, positionalLoc?: string) => Promise<import("@jbrowse/core/util").Feature[]>;
+    }, positionalLoc?: string, positionalOpts?: {
+        assembly?: string;
+        viewId?: string;
+        byteLimit?: number;
+    }) => Promise<import("@jbrowse/core/util").Feature[]>;
 };
 export type JbApi = ReturnType<typeof createJbApi>;
 export {};

package/esm/JbApi/jbApi.js

@@ -1,8 +1,11 @@
 import { setReExportRegistry } from '@jbrowse/core/ReExports/registry';
 import { getConf, getConfigurationSchemaDefinition, 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, measureRegionBytes, } from '@jbrowse/core/rpc/byteBudget';
+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 { allSessionTracks, getConfAssemblyNamesOrNone, guessTrackConfForLocation, isSameAssemblyName, viewCanDisplayTrack, viewDisplayNames, } from '@jbrowse/core/util/tracks';
 import * as mst from '@jbrowse/mobx-state-tree';
@@ -28,18 +31,15 @@ export function agentByteLimit(declaredFetchSizeLimit, requested) {
 function viewSelf(view) {
     return view;
 }
-// The views' own census contract (BaseViewModel derives `allViews` and
-// `ownTracks`), so this module carries no copy of the view nesting: a synteny
-// stack's rows and per-band containers, a breakpoint split view's panels, and
-// any depth of nesting all arrive through each view answering for itself.
-function allViews(session) {
-    return session.views.flatMap(v => v.allViews);
-}
+// The census helpers over the views' own `ownViews`/`ownTracks`, so this module
+// carries no copy of the view nesting: a synteny stack's rows and per-band
+// containers, a breakpoint split view's panels, and any depth of nesting all
+// arrive through each view declaring what it holds.
 function viewTracks(view) {
     return view.ownTracks;
 }
 function allTracks(session) {
-    return allViews(session).flatMap(v => viewTracks(v));
+    return openTracks(session);
 }
 // The drawn display's on-screen state. `displayPhase` is the tree's own
 // single-sourced vocabulary (render-core/displayPhase.ts) and the same one
@@ -47,7 +47,7 @@ function allTracks(session) {
 // subtree rather than raising a snackbar, so a settle reporting only
 // notifications calls them ready.
 function displayState(track) {
-    const display = track.displays?.[0];
+    const display = track.activeDisplay;
     if (!display) {
         return {};
     }
@@ -72,11 +72,23 @@ function displayState(track) {
 export function sessionOf(pluginManager) {
     return pluginManager?.rootModel?.session;
 }
+// A view whose init failed (its assembly was never found) paints the error in
+// place of a genome and raises no toast, and stays uninitialized: without
+// this, a spec with "volvix" for "volvox" settled false with nothing said.
+function viewState(v) {
+    return {
+        ...(v.error === undefined ? {} : { error: String(v.error) }),
+        ...(v.error === undefined && v.initialized === false
+            ? { phase: 'initializing' }
+            : {}),
+    };
+}
 function viewSummary(view) {
     const v = viewSelf(view);
     return {
         id: v.id,
         type: v.type,
+        ...viewState(v),
         ...(v.displayName ? { displayName: v.displayName } : {}),
         ...(v.assemblyNames?.length ? { assemblyNames: v.assemblyNames } : {}),
         ...(v.coarseVisibleLocStrings
@@ -225,8 +237,7 @@ const delay = (ms) => new Promise(resolve => {
 // ~600ms FetchVisibleRegions debounce, or one sample taken right after a
 // navigation reads the pre-navigation frame as finished. Same reasoning and
 // same constant as `waitForAppSettled` in products/jbrowse-capture/src/waits.ts
-// (APP_SETTLED_HOLD_MS) — reached independently there, and measured; see
-// REJECTED_IDEAS under "Waiting out a screenshot action's work".
+// (APP_SETTLED_HOLD_MS) — reached independently there, and measured.
 const READY_HOLD_MS = 1000;
 // An error toast stays up until a human dismisses it, and an info toast leaves
 // on its own — so "the last five messages" repeated one stale error in every
@@ -282,9 +293,18 @@ root = document) {
     // replaces its own subtree instead of raising a snackbar, so notifications
     // alone report a clean settle over a browser with a blank track in it.
     const notReady = session
-        ? allTracks(session)
-            .map(t => ({ trackId: t.configuration.trackId, ...displayState(t) }))
-            .filter(t => 'phase' in t || 'error' in t)
+        ? [
+            ...openViews(session)
+                .map(v => ({
+                viewId: v.id,
+                type: v.type,
+                ...viewState(viewSelf(v)),
+            }))
+                .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),
+        ]
         : [];
     const offscreen = session ? offscreenViews(session, root) : undefined;
     return {
@@ -306,7 +326,7 @@ function offscreenViews(session, root) {
     const containers = new Map([
         ...root.querySelectorAll('[data-testid^="view-container-"]'),
     ].map(el => [el.dataset.testid.slice('view-container-'.length), el]));
-    const views = allViews(session).flatMap(view => {
+    const views = openViews(session).flatMap(view => {
         const rect = containers.get(view.id)?.getBoundingClientRect();
         return rect && (rect.top < 0 || rect.bottom > windowHeight)
             ? [
@@ -322,8 +342,9 @@ function offscreenViews(session, root) {
         ? {
             pageHeight,
             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',
+            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',
         }
         : undefined;
 }
@@ -334,16 +355,24 @@ function trackEntry(conf) {
         name: readConfObject(conf, 'name'),
         type: conf.type,
         ...(adapter.type ? { adapterType: adapter.type } : {}),
-        assemblyNames: readConfObject(conf, 'assemblyNames'),
+        // getConfAssemblyNamesOrNone, not the slot: an assembly's sequence track
+        // has no assemblyNames slot and answers through its parent assembly
+        assemblyNames: getConfAssemblyNamesOrNone(conf),
     };
 }
+// Each assembly's own sequence track, which no track list holds: the config
+// keeps it under the assembly as `sequence`, so `jb.getFeatures` on its
+// trackId reads bases while `listTracks` never named it.
+function sequenceTracks(session) {
+    return session.assemblyManager.assemblyList.map(asm => asm.sequence);
+}
 function listTracks(session, searchArg, limitArg) {
     const search = searchArg?.toLowerCase() ?? '';
     const limit = limitArg ?? 100;
     // allSessionTracks, not session.tracks: connection-supplied tracks (hubs,
     // registries) are absent from the session lists but fully showable — a
     // hand-rolled union here hid them from agents entirely
-    const matches = allSessionTracks(session)
+    const matches = [...allSessionTracks(session), ...sequenceTracks(session)]
         .map(c => trackEntry(c))
         .filter(t => !search ||
         t.trackId.toLowerCase().includes(search) ||
@@ -358,7 +387,7 @@ function listTracks(session, searchArg, limitArg) {
 }
 function pickView(session, args, capability, wants) {
     const viewId = typeof args.viewId === 'string' ? args.viewId : '';
-    const candidates = allViews(session);
+    const candidates = openViews(session);
     if (viewId) {
         const named = candidates.find(v => v.id === viewId);
         if (!named) {
@@ -388,18 +417,80 @@ 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 canDisplay[0];
+    return onlyView(canDisplay, 'could take this');
+}
+function describeView(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 [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`);
+    }
+    return first;
+}
+function viewById(session, viewId) {
+    const candidates = openViews(session);
+    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'}`);
+        }
+        return named;
+    }
+    if (!candidates.length) {
+        throw new Error('No view is open — jb.loadSessionSpec can open one');
+    }
+    return onlyView(candidates, 'are open');
 }
-function shownTrackModel(session, trackId) {
-    return allTracks(session).find(t => t.configuration.trackId === trackId);
+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;
+    // 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) {
+        throw new Error(session.getTrackById(trackId)
+            ? `"${trackId}" is not shown in ${viewId === undefined ? 'any open view' : `view ${viewId}`} — view.showTrack("${trackId}") first; jb.sessionSummary() lists what each view shows`
+            : `No track with trackId "${trackId}" — jb.listTracks() shows what is available`);
+    }
+    return track;
 }
 async function locToRegion(session, conf, loc, assemblyArg) {
     // getConfAssemblyNamesOrNone, not the assemblyNames slot: an assembly's own
     // sequence track has no such slot and answers through its parent assembly
-    const assemblyName = assemblyArg ?? getConfAssemblyNamesOrNone(conf)[0];
+    const trackAssemblies = getConfAssemblyNamesOrNone(conf);
+    const assemblyName = assemblyArg ?? 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 &&
+        trackAssemblies.length &&
+        !trackAssemblies.some(name => isSameAssemblyName(name, assemblyArg, session.assemblyManager))) {
+        throw new Error(`Track "${conf.trackId}" is on ${trackAssemblies.join(', ')}, not "${assemblyArg}"`);
+    }
     const assembly = await session.assemblyManager.waitForAssembly(assemblyName);
     if (!assembly) {
         throw new Error(`Assembly "${assemblyName}" could not be loaded`);
@@ -414,24 +505,37 @@ async function locToRegion(session, conf, loc, assemblyArg) {
         end: parsed.end ?? bounds?.end ?? Number.MAX_SAFE_INTEGER,
     };
 }
-async function visibleRegionsOf(session, viewId, preferTrackId) {
+async function visibleRegionsOf(session, viewId, preferTrackId, trackAssemblies = []) {
     // `in`, not evaluation: visibleRegions is a getter that THROWS ("width
     // undefined") until the view's component mounts and sets a width — a
     // 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 candidates = allViews(session).filter(v => (!viewId || v.id === viewId) && 'visibleRegions' in v);
-    // among region-bearing views, the one actually showing the track wins — two
-    // views on two assemblies would otherwise send the first view's namespace to
-    // the second view's file, which answers nothing, silently
-    const chosen = candidates.find(v => viewTracks(v).some(t => t.configuration.trackId === preferTrackId)) ?? candidates[0];
-    if (!chosen) {
+    const regionBearing = openViews(session).filter(v => (!viewId || v.id === viewId) && 'visibleRegions' in v);
+    if (!regionBearing.length) {
         throw new Error('No view that shows a region — pass loc, or open a linear view first');
     }
+    // a view on another assembly than the track would hand its region to a file
+    // that has no such sequence, which answers nothing, silently
+    const candidates = trackAssemblies.length
+        ? regionBearing.filter(v => !viewSelf(v).assemblyNames?.length ||
+            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`);
+    }
+    // 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 view = viewSelf(chosen);
     const deadline = Date.now() + 10_000;
     let visible;
     while (visible === undefined) {
+        if (view.error !== undefined) {
+            throw new Error(`View ${view.id} failed to initialize: ${String(view.error)} — pass loc with assembly, or open a view that loads`);
+        }
         if (view.initialized !== false) {
             try {
                 visible = view.visibleRegions;
@@ -458,78 +562,61 @@ async function visibleRegionsOf(session, viewId, preferTrackId) {
         assemblyName,
     }));
 }
-// Main-thread adapter, not the CoreGetFeatures RPC: the RPC serializes every
-// feature in the region across the worker boundary before any limit can
-// apply. Here the features stay objects. The shown track's own rpcSessionId,
-// so this shares the adapter instance — parsed indexes and chunk caches
-// included — that the display already warmed (rpcSessionId lives on track
-// models, so the walk cannot start at the session; session.id is the
-// cold-namespace fallback for un-shown tracks). Regions are renamed the same
-// way the RPC base class renames them: they arrive carrying the assembly's
-// canonical refNames, and a file spelling them differently would otherwise
-// answer nothing, silently.
-async function fetchFeatures(pluginManager, session, trackId, regions, requestedByteLimit) {
+// The same RPCs the track's display issues, on the same worker: the sessionId
+// is `adapterConfigCacheKey` of the adapter config, which is exactly what
+// `BaseTrackModel.rpcSessionId` derives, so a shown track's parsed index and
+// chunk cache are reused rather than rebuilt in a main-thread twin that nothing
+// ever freed. Retained and released like a track does, so an un-shown track's
+// worker cache is dropped once this read is done. Regions are renamed to the
+// file's own refNames during serialization (RpcMethodTypeWithRenameRegions),
+// and the features come back rebuilt as SimpleFeature. What crosses the worker
+// boundary is bounded by the byte gate that runs first.
+async function fetchFeatures(session, trackId, regions, requestedByteLimit) {
     const conf = session.getTrackById(trackId);
     if (!conf) {
         throw new Error(`No track with trackId "${trackId}" — jb.listTracks() shows what is available`);
     }
-    const trackModel = shownTrackModel(session, trackId);
-    const sessionId = trackModel
-        ? getRpcSessionId(trackModel)
-        : (session.id ?? 'mcp');
-    const renamed = await renameRegionsIfNeeded(session.assemblyManager, {
-        regions,
-        adapterConfig: readConfObject(conf, 'adapter'),
-        sessionId,
-    });
-    const dataAdapter = await getFeatureAdapterOrThrow({
-        pluginManager,
-        sessionId,
-        adapterConfig: renamed.adapterConfig,
-        sequenceAdapter: renamed.sequenceAdapter,
-    });
+    const adapterConfig = readConfObject(conf, 'adapter');
+    const sessionId = adapterConfigCacheKey(adapterConfig);
     // The adapter's own declared limit where it has one, so this does not quietly
     // disagree with the size the track's display already refuses to render —
     // the reasoning BaseTrackModel.exportByteLimit spells out for "Save track
     // data", which is the other path that fetches because someone asked rather
     // than because a view scrolled.
     const byteLimit = agentByteLimit(readConfObject(conf, ['adapter', 'fetchSizeLimit']), requestedByteLimit);
+    const { rpcManager } = session;
     const stopToken = createStopToken();
     // 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);
     }, 120_000);
-    // The agent's "region too large". A display refuses to fetch over its own
-    // gate and paints the reason; this path has no display, so without the same
-    // question asked here an agent that names a whole chromosome pulls it — over
-    // someone else's data host, onto the main thread, in the page it is about to
-    // screenshot. Same index-only estimate the gated RPC takes first, and a
-    // refusal rather than a truncation: a short answer that looked like the whole
-    // answer is the failure this surface exists to prevent.
-    const { tooLarge, bytes } = await measureRegionBytes({
-        dataAdapter,
-        regions: renamed.regions,
-        byteLimit,
-        stopToken,
-    });
-    if (tooLarge) {
-        clearTimeout(stopTimer);
-        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.`);
-    }
-    // one array per region, flattened once at the end: a dense region returns
-    // hundreds of thousands of features, so neither push(...array) — a
-    // RangeError on the argument list — nor a concat per region is available
-    const perRegion = [];
+    retainAdapterSession(rpcManager, sessionId);
     try {
-        for (const region of renamed.regions) {
-            perRegion.push(await dataAdapter.getFeaturesArray(region, { stopToken }));
+        // The agent's "region too large". A display refuses to fetch over its own
+        // gate and paints the reason; this path has no display, so without the
+        // same question asked here an agent that names a whole chromosome pulls it
+        // — over someone else's data host, into the page it is about to
+        // screenshot. Same index-only estimate the gated RPC takes first, and a
+        // refusal rather than a truncation: a short answer that looked like the
+        // 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 });
+        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.`);
         }
+        // eslint-disable-next-line no-restricted-syntax -- reports nothing: see the estimate above
+        return await rpcManager.call(sessionId, 'CoreGetFeatures', {
+            adapterConfig,
+            regions,
+            stopToken,
+        });
     }
     finally {
         clearTimeout(stopTimer);
+        void releaseAdapterSession(rpcManager, sessionId);
     }
-    return perRegion.flat();
 }
 // A LocalPathLocation only reads under Electron: in a browser openLocation
 // throws "can't use local files in the browser" at the FIRST READ, not here, so
@@ -539,6 +626,12 @@ function fileLocation(spec) {
     if (/^https?:\/\//.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)) {
+        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) {
         throw new Error(`jb.addTrack needs a URL in a browser, and "${spec}" is a local path. JBrowse Web cannot read local files except through the Add track file picker, which needs a real file chosen by hand.`);
     }
@@ -586,7 +679,7 @@ 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 otherwise dropped silently, which is this format's known failure mode.
+// key is not an error, only an entry in applyDisplaySettings' `unapplied` list.
 function describeSlots(conf) {
     const definition = getConfigurationSchemaDefinition(conf) ?? {};
     return Object.fromEntries(Object.entries(definition).flatMap(([name, def]) => isSlotDefinitionEntry(def)
@@ -614,6 +707,19 @@ function describeSlots(conf) {
 export async function ensureReExports() {
     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
+// agent has no MCP docs tool and no initialize instructions to learn the
+// 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.
+
+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?, 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.
+
+Views nest and several can be open. jb.view(viewId?) is the open view, and jb.view(), jb.trackModel(trackId), jb.visibleRegions() and jb.addTrack throw naming the candidates rather than picking one when more than one view could answer — pass viewId (from jb.sessionSummary()) to say which.
+
+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...").`;
 // 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
@@ -627,11 +733,12 @@ export function createJbApi(pluginManager) {
     const live = () => {
         const current = sessionOf(pluginManager);
         if (!current) {
-            throw new Error('No session is open');
+            throw new Error('No session is open, so there is nothing for this helper to read. Build one with jb.loadSessionSpec({ views: [...] }), which needs no session of its own, or load a config with the open tool.');
         }
         return current;
     };
     const jb = {
+        help: JB_HELP,
         get session() {
             return live();
         },
@@ -651,19 +758,26 @@ export function createJbApi(pluginManager) {
         renameRegionsIfNeeded,
         createStopToken,
         stopStopToken,
-        waitReady: (timeoutMs) => waitReady(timeoutMs, live()),
+        // 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: (timeoutMs = 30_000) => waitReady(timeoutMs, live()),
         sessionSummary: () => sessionSummary(live()),
         inspect: (path, maxInspectBytes) => inspectSession(live(), { path, maxBytes: maxInspectBytes }),
         listTracks: (search, limit) => listTracks(live(), search, limit),
-        trackModel: (trackId) => shownTrackModel(live(), trackId),
+        view: (viewId) => viewById(live(), viewId),
+        trackModel: (trackId, viewId) => shownTrackModel(live(), trackId, viewId),
         visibleRegions: (viewId) => visibleRegionsOf(live(), viewId),
         loadSessionSpec: (spec, settleMs) => loadSpec(pluginManager, { spec, settleMs }),
         addTrack: (opts) => addTrack(pluginManager, live(), opts),
         // Two of four filmed takes wrote jb.getFeatures('trackId', loc) and lost a
-        // turn to "No track with trackId undefined" — so the positional form is
-        // simply accepted alongside the object it was documented as.
-        getFeatures: async (args, positionalLoc) => {
-            const fetchArgs = typeof args === 'string' ? { trackId: args, loc: positionalLoc } : args;
+        // turn to "No track with trackId undefined", and a third wrote
+        // jb.getFeatures('trackId', loc, { assembly }) and had the options
+        // silently ignored — so the positional form is accepted alongside the
+        // object it was documented as, options third.
+        getFeatures: async (args, positionalLoc, positionalOpts) => {
+            const fetchArgs = typeof args === 'string'
+                ? { trackId: args, loc: positionalLoc, ...positionalOpts }
+                : args;
             const session = live();
             const conf = session.getTrackById(fetchArgs.trackId);
             if (!conf) {
@@ -674,19 +788,22 @@ export function createJbApi(pluginManager) {
                     ? [
                         await locToRegion(session, conf, fetchArgs.loc, fetchArgs.assembly),
                     ]
-                    : await visibleRegionsOf(session, fetchArgs.viewId, fetchArgs.trackId));
-            return fetchFeatures(pluginManager, session, fetchArgs.trackId, regions, fetchArgs.byteLimit);
+                    : await visibleRegionsOf(session, fetchArgs.viewId, fetchArgs.trackId, getConfAssemblyNamesOrNone(conf)));
+            return fetchFeatures(session, fetchArgs.trackId, regions, fetchArgs.byteLimit);
         },
     };
     return jb;
 }
+// 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;
 async function addTrack(pluginManager, session, args) {
     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 (local path or URL)');
+        throw new Error('jb.addTrack needs a location (an absolute local path or a URL)');
     }
     const requested = typeof args.assembly === 'string' ? args.assembly : session.assemblyNames[0];
     if (requested === undefined) {
@@ -720,10 +837,12 @@ async function addTrack(pluginManager, session, args) {
         pluginManager,
     });
     viewSelf(view).showTrack(conf.trackId);
-    // 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 settle = await waitReady(60_000, session);
-    return { ...summary, ...settle, shownInView: view.id };
+    const shown = { ...summary, shownInView: view.id };
+    // 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 settleMs > 0
+        ? { ...shown, ...(await waitReady(settleMs, session)) }
+        : shown;
 }
 // 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,

package/esm/SessionSpec/loadSessionSpec.js

@@ -3,9 +3,7 @@ import { legacyInitMessage, unknownKeysMessage, } from '@jbrowse/core/util/withL
 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 &&
@@ -354,26 +352,14 @@ 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.
                 // Its own try/catch, the same reasoning as the per-view one above: the
                 // resolver throws for a layout it will not arrange, and this is the
                 // LAST thing the spec does — so an unarrangeable layout used to take
-                // the whole load's catch, after `setUseWorkspaces(true)` had already
-                // run, and report itself as the session's error with the views left
-                // unordered. The layout is one statement in the spec; losing it should
-                // cost the spec its layout and nothing else.
+                // 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.orderViews(session.applyLayoutSpec(convertLayoutNode(layout, createdViewIds, knownIds, new Set(pinnedLayoutIds(layout, knownIds)))));
+                    session.layoutViews(convertLayoutNode(layout, createdViewIds, knownIds, new Set(pinnedLayoutIds(layout, knownIds))));
                 }
                 catch (e) {
                     console.error(e);

package/esm/WorkspaceLayout/model.d.ts

@@ -241,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

@@ -5,6 +5,9 @@ import { activeTabIn, addTab, addViewToTab, findTab, homeViews, moveTabToPanel,
 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.
  *
@@ -555,6 +558,30 @@ export function WorkspaceLayoutMixin() {
         tileViews(mode, allViewIds) {
             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;
+        },
     })));
 }
 export function isSessionWithWorkspaceLayout(session) {

package/esm/ui/App/AppReadyMarker.d.ts

@@ -19,9 +19,9 @@ import type { AppSession } from './types.ts';
  * same way the phase publishes whether it is done, so an outside reader asking
  * "is the track I requested actually open" reads one element instead of
  * walking `window.JBrowseSession` with its own copy of the view nesting. The
- * walk itself is the views' own `allViews`/`ownTracks` contract (BaseViewModel
- * derives it), so this component knows nothing about which property a
- * container view keeps its children on either.
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
  *
  * Its own component, and `hidden`, for two reasons: an observer here subscribes
  * to every view's phase without re-rendering the app shell around it, and a

package/esm/ui/App/AppReadyMarker.js

@@ -1,11 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { openTracks, openViews } from '@jbrowse/core/util/openViews';
 import { observer } from 'mobx-react';
 function trackLoading(track) {
     return track.displays.some(d => d.displayPhase === 'loading');
 }
+// A view whose init failed (its assembly was never found) stays uninitialized
+// for good and paints its error, so like a display's terminal phase it is
+// finished, not pending: without this the whole app read `loading` for as long
+// as that view was open, and every settle answered false with no reason.
 function viewLoading(view) {
     const flags = view;
-    return flags.showLoading === true || flags.initialized === false;
+    return (flags.error === undefined &&
+        (flags.showLoading === true || flags.initialized === false));
 }
 /**
  * One element that says whether the whole app has finished, and what is open.
@@ -27,9 +33,9 @@ function viewLoading(view) {
  * same way the phase publishes whether it is done, so an outside reader asking
  * "is the track I requested actually open" reads one element instead of
  * walking `window.JBrowseSession` with its own copy of the view nesting. The
- * walk itself is the views' own `allViews`/`ownTracks` contract (BaseViewModel
- * derives it), so this component knows nothing about which property a
- * container view keeps its children on either.
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
  *
  * Its own component, and `hidden`, for two reasons: an observer here subscribes
  * to every view's phase without re-rendering the app shell around it, and a
@@ -46,8 +52,8 @@ function viewLoading(view) {
  * and says why an error separates them). Both harnesses do it in that order.
  */
 const AppReadyMarker = observer(function AppReadyMarker({ session, }) {
-    const views = session.views.flatMap(v => v.allViews);
-    const tracks = views.flatMap(v => v.ownTracks);
+    const views = openViews(session);
+    const tracks = openTracks(session);
     const loading = views.some(viewLoading) || tracks.some(trackLoading);
     return (_jsx("span", { hidden: true, "data-testid": "app-ready-marker", "data-app-phase": loading ? 'loading' : 'ready', "data-app-views": session.views.length, "data-app-assemblies": JSON.stringify([
             ...new Set(views.flatMap(v => v.assemblyNames ?? [])),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/app-core",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.4",
   "type": "module",
   "description": "JBrowse 2 code shared between the 'full featured' apps e.g. jbrowse-web and jbrowse-desktop",
   "keywords": [
@@ -29,8 +29,8 @@
     "@mui/material": "^9.4.0",
     "mobx": "^7.0.3",
     "mobx-react": "^10.0.2",
-    "@jbrowse/product-core": "^5.0.0-beta.2",
-    "@jbrowse/core": "^5.0.0-beta.2"
+    "@jbrowse/core": "^5.0.0-beta.4",
+    "@jbrowse/product-core": "^5.0.0-beta.4"
   },
   "peerDependencies": {
     "react": ">=19.0.0",