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

package/esm/JbApi/jbApi.js

@@ -0,0 +1,748 @@
+import { setReExportRegistry } from '@jbrowse/core/ReExports/registry';
+import { getConf, getConfigurationSchemaDefinition, isSlotDefinitionEntry, readConfObject, } from '@jbrowse/core/configuration';
+import { getFeatureAdapterOrThrow } from '@jbrowse/core/data_adapters/getFeatureAdapter';
+import { adapterByteLimit, measureRegionBytes, } from '@jbrowse/core/rpc/byteBudget';
+import { getRpcSessionId, isElectron, isSessionWithAddSessionTrack, objectHash, parseLocString, renameRegionsIfNeeded, } from '@jbrowse/core/util';
+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';
+import { 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';
+// 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.
+const DEFAULT_AGENT_BYTE_LIMIT = 5_000_000;
+/**
+ * What jb.getFeatures may pull before it refuses. An explicit request wins so
+ * an agent can mean it; otherwise the adapter's own declared limit, so this
+ * does not disagree with the size the track's display already refuses to
+ * render; otherwise the default.
+ */
+export function agentByteLimit(declaredFetchSizeLimit, requested) {
+    return (requested ??
+        adapterByteLimit(declaredFetchSizeLimit, DEFAULT_AGENT_BYTE_LIMIT));
+}
+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);
+}
+function viewTracks(view) {
+    return view.ownTracks;
+}
+function allTracks(session) {
+    return allViews(session).flatMap(v => viewTracks(v));
+}
+// The drawn display's on-screen state. `displayPhase` is the tree's own
+// single-sourced vocabulary (render-core/displayPhase.ts) and the same one
+// AppReadyMarker reads; `tooLarge` and `renderError` replace the display
+// subtree rather than raising a snackbar, so a settle reporting only
+// notifications calls them ready.
+function displayState(track) {
+    const display = track.displays?.[0];
+    if (!display) {
+        return {};
+    }
+    try {
+        const phase = display.displayPhase;
+        return {
+            display: display.type,
+            // "make it all fit in the window" is a normal thing to be asked, and
+            // without this the only way to answer it is measuring DOM rectangles
+            ...(typeof display.height === 'number' ? { height: display.height } : {}),
+            ...(phase === undefined || phase === 'ready' ? {} : { phase }),
+            ...(phase === 'tooLarge' && display.regionTooLargeReason
+                ? { reason: display.regionTooLargeReason }
+                : {}),
+            ...(display.error ? { error: String(display.error) } : {}),
+        };
+    }
+    catch (e) {
+        return { display: display.type, error: String(e) };
+    }
+}
+export function sessionOf(pluginManager) {
+    return pluginManager?.rootModel?.session;
+}
+function viewSummary(view) {
+    const v = viewSelf(view);
+    return {
+        id: v.id,
+        type: v.type,
+        ...(v.displayName ? { displayName: v.displayName } : {}),
+        ...(v.assemblyNames?.length ? { assemblyNames: v.assemblyNames } : {}),
+        ...(v.coarseVisibleLocStrings
+            ? { visibleRegion: v.coarseVisibleLocStrings }
+            : {}),
+        // the stack's own height, beside each track's below it: "does this all fit
+        // on screen" is then arithmetic rather than three rounds of screenshotting
+        ...(typeof v.height === 'number' ? { height: v.height } : {}),
+        ...(viewTracks(view).length
+            ? {
+                tracks: viewTracks(view).map(t => ({
+                    trackId: t.configuration.trackId,
+                    trackType: t.type,
+                    ...displayState(t),
+                })),
+            }
+            : {}),
+        ...(Array.isArray(v.views) && v.views.length
+            ? { views: v.views.map(sub => viewSummary(sub)) }
+            : {}),
+    };
+}
+function sessionSummary(session) {
+    return {
+        name: session.name,
+        assemblyNames: session.assemblyNames,
+        views: session.views.map(v => viewSummary(v)),
+    };
+}
+// MST nodes serialize as their snapshot (toJSON), so the live-model walk below
+// can stringify whatever it lands on; the replacer guards what a snapshot
+// cannot contain but a getter's return can.
+export function safeJson(value) {
+    // the ANCESTOR chain, not every object seen: MST snapshots are cached and
+    // structurally shared, so the same frozen object legitimately appears at two
+    // paths, and a visited-set reports the second one as a cycle that is not
+    // there. `this` is the holder JSON.stringify is currently walking, which is
+    // what lets the chain unwind on the way back up — so this must stay a
+    // `function`, not an arrow.
+    const chain = [];
+    // typed by hand: JSON.stringify's declared return is string, but a bare
+    // Symbol/undefined at the top level really does yield undefined at runtime
+    const json = JSON.stringify(isStateTreeNode(value) ? getSnapshot(value) : value, function (_key, v) {
+        while (chain.length > 0 && chain.at(-1) !== this) {
+            chain.pop();
+        }
+        if (typeof v === 'function') {
+            return '[function]';
+        }
+        if (typeof v === 'bigint') {
+            return `${v}`;
+        }
+        if (v !== null && typeof v === 'object') {
+            if (chain.includes(v)) {
+                return '[circular]';
+            }
+            chain.push(v);
+        }
+        return v;
+    });
+    return json === undefined ? '"[unserializable]"' : json;
+}
+function describeBrief(value) {
+    if (Array.isArray(value)) {
+        return `array(${value.length})`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const json = safeJson(value);
+        return json.length > 120 ? `object(~${json.length} bytes)` : json;
+    }
+    const json = safeJson(value);
+    return json.length > 120 ? `${json.slice(0, 117)}...` : json;
+}
+// The names a live node answers beyond its snapshot: MST defines views as own
+// getter properties on the instance, which is exactly the high-value surface
+// (visibleLocStrings, assemblyNames, totalBp, ...) a snapshot filters out.
+function memberNames(node) {
+    const getters = [];
+    const methods = [];
+    for (const [key, desc] of Object.entries(Object.getOwnPropertyDescriptors(node))) {
+        if (!key.startsWith('$') && key !== 'toJSON') {
+            if (desc.get) {
+                getters.push(key);
+            }
+            else if (typeof desc.value === 'function') {
+                methods.push(key);
+            }
+        }
+    }
+    return { getters: getters.sort(), methods: methods.sort() };
+}
+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)
+        ? 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,
+        ...(members.getters.length ? { getters: members.getters } : {}),
+        ...(members.methods.length ? { actions: members.methods } : {}),
+    };
+    if (json.length <= maxBytes) {
+        return { ...base, value: JSON.parse(json) };
+    }
+    const plain = JSON.parse(json);
+    return Array.isArray(plain)
+        ? {
+            ...base,
+            note: `too large to return whole — ${plain.length} items; index in with .N 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',
+            keys: Object.fromEntries(Object.entries(plain).map(([k, v]) => [
+                k,
+                describeBrief(v),
+            ])),
+        };
+}
+const delay = (ms) => new Promise(resolve => {
+    setTimeout(resolve, ms);
+});
+// The readiness contract is AppReadyMarker's, not this file's: it publishes
+// data-app-phase from the session (ready = no view resolving an assembly, no
+// display fetching), and says so in its own comment.
+//
+// The hold is why the number is a second: `ready` has to survive past the
+// ~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".
+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
+// settle result for the rest of a run and named no level for the rest. Each
+// toast is delivered to the caller once, by identity: the mobx array keeps the
+// object it was pushed as, and removeSnackbarMessage relies on that too.
+const deliveredNotifications = new WeakMap();
+export function undeliveredNotifications(session) {
+    const entries = 'snackbarMessages' in session
+        ? session.snackbarMessages
+        : [];
+    const known = deliveredNotifications.get(session);
+    const delivered = known ?? new WeakSet();
+    if (!known) {
+        deliveredNotifications.set(session, delivered);
+    }
+    const fresh = entries.filter(m => !delivered.has(m));
+    for (const m of fresh) {
+        delivered.add(m);
+    }
+    return fresh.map(m => ({
+        level: m.level ?? 'info',
+        message: m.message,
+    }));
+}
+export async function waitReady(timeoutMs, session, 
+// scoped rather than document-wide because @jbrowse/react-app2 embeds this
+// app in a host page: two mounted apps publish two ready markers, and a
+// document-wide query answers for whichever is first in document order
+root = document) {
+    const deadline = Date.now() + timeoutMs;
+    let readySince;
+    let outcome;
+    while (outcome === undefined) {
+        const ready = root.querySelector('[data-app-phase="ready"]') !== null &&
+            root.querySelector('[data-testid="loading-overlay"]') === null;
+        readySince = ready ? (readySince ?? Date.now()) : undefined;
+        if (readySince !== undefined && Date.now() - readySince >= READY_HOLD_MS) {
+            outcome = { settled: true };
+        }
+        else if (Date.now() >= deadline) {
+            outcome = {
+                settled: false,
+                note: 'rendering had not settled by the timeout; tracks may still be loading',
+            };
+        }
+        else {
+            await delay(200);
+        }
+    }
+    const messages = session ? undeliveredNotifications(session) : [];
+    // A display that refuses to draw — over the fetch-size gate, or errored —
+    // 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)
+        : [];
+    const offscreen = session ? offscreenViews(session, root) : undefined;
+    return {
+        ...outcome,
+        ...(messages.length ? { notifications: messages } : {}),
+        ...(notReady.length ? { notReady } : {}),
+        ...(offscreen ? { offscreen } : {}),
+    };
+}
+// A session taller than the window scrolls, and a screenshot of the viewport
+// then shows a plausible browser with the bottom view cut off or the top one
+// scrolled away: every filmed take spent turns shrinking tracks after a
+// picture, and one found its genome view at y = -267. Reported from the DOM
+// the views are laid out in, so the agent knows before it looks.
+function offscreenViews(session, root) {
+    const win = root.ownerDocument?.defaultView ?? window;
+    const windowHeight = win.innerHeight;
+    const pageHeight = win.document.documentElement.scrollHeight;
+    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 rect = containers.get(view.id)?.getBoundingClientRect();
+        return rect && (rect.top < 0 || rect.bottom > windowHeight)
+            ? [
+                {
+                    viewId: view.id,
+                    top: Math.round(rect.top),
+                    bottom: Math.round(rect.bottom),
+                },
+            ]
+            : [];
+    });
+    return pageHeight > windowHeight || views.length
+        ? {
+            pageHeight,
+            windowHeight,
+            views,
+            note: 'the session is taller than the window; a viewport screenshot cuts these views off — shrink track heights, or screenshot with fullPage: true',
+        }
+        : undefined;
+}
+function trackEntry(conf) {
+    const adapter = readConfObject(conf, 'adapter');
+    return {
+        trackId: conf.trackId,
+        name: readConfObject(conf, 'name'),
+        type: conf.type,
+        ...(adapter.type ? { adapterType: adapter.type } : {}),
+        assemblyNames: readConfObject(conf, 'assemblyNames'),
+    };
+}
+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)
+        .map(c => trackEntry(c))
+        .filter(t => !search ||
+        t.trackId.toLowerCase().includes(search) ||
+        t.name.toLowerCase().includes(search));
+    return {
+        total: matches.length,
+        ...(matches.length > limit
+            ? { note: `showing ${limit} of ${matches.length}; refine with search` }
+            : {}),
+        tracks: matches.slice(0, limit),
+    };
+}
+function pickView(session, args, capability, wants) {
+    const viewId = typeof args.viewId === 'string' ? args.viewId : '';
+    const candidates = allViews(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 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.`);
+    }
+    // A view on another assembly would show the track and render nothing, with a
+    // successful-looking result — the same silent mismatch visibleRegionsOf
+    // guards against for reads
+    const onAssembly = wants?.assembly
+        ? able.filter(v => viewSelf(v).assemblyNames?.some(name => isSameAssemblyName(name, wants.assembly, session.assemblyManager)))
+        : able;
+    if (!onAssembly.length) {
+        throw new Error(`No open view is on assembly "${wants.assembly}" (open views: ${able.map(v => `${v.id} on ${viewSelf(v).assemblyNames?.join(', ')}`).join('; ')}) — open one, or pass show: false`);
+    }
+    const canDisplay = wants?.trackType && wants.pluginManager
+        ? onAssembly.filter(v => viewCanDisplayTrack(wants.pluginManager, viewDisplayNames(wants.pluginManager, v.type), wants.trackType))
+        : onAssembly;
+    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];
+}
+function shownTrackModel(session, trackId) {
+    return allTracks(session).find(t => t.configuration.trackId === trackId);
+}
+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];
+    if (assemblyName === undefined) {
+        throw new Error('The track names no assembly; pass assembly explicitly');
+    }
+    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));
+    const refName = assembly.getCanonicalRefName(parsed.refName) ?? parsed.refName;
+    const bounds = assembly.regions?.find(r => r.refName === refName);
+    return {
+        assemblyName,
+        refName,
+        start: parsed.start ?? bounds?.start ?? 0,
+        end: parsed.end ?? bounds?.end ?? Number.MAX_SAFE_INTEGER,
+    };
+}
+async function visibleRegionsOf(session, viewId, preferTrackId) {
+    // `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) {
+        throw new Error('No view that shows a region — pass loc, or open a linear view first');
+    }
+    const view = viewSelf(chosen);
+    const deadline = Date.now() + 10_000;
+    let visible;
+    while (visible === undefined) {
+        if (view.initialized !== false) {
+            try {
+                visible = view.visibleRegions;
+            }
+            catch {
+                // not mounted yet
+            }
+        }
+        if (visible?.length) {
+            break;
+        }
+        visible = undefined;
+        if (Date.now() >= deadline) {
+            throw new Error('The view has not finished initializing a visible region — pass loc, or navigate first');
+        }
+        await delay(250);
+    }
+    // whole bases: a block edge is a fractional bp, and 30000.000000000004
+    // reads as a bug in every answer that echoes it
+    return visible.map(({ refName, start, end, assemblyName }) => ({
+        refName,
+        start: Math.floor(start),
+        end: Math.ceil(end),
+        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) {
+    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,
+    });
+    // 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 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 = [];
+    try {
+        for (const region of renamed.regions) {
+            perRegion.push(await dataAdapter.getFeaturesArray(region, { stopToken }));
+        }
+    }
+    finally {
+        clearTimeout(stopTimer);
+    }
+    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
+// 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.
+function fileLocation(spec) {
+    if (/^https?:\/\//.test(spec)) {
+        return { uri: spec, locationType: 'UriLocation' };
+    }
+    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.`);
+    }
+    return { localPath: spec, locationType: 'LocalPathLocation' };
+}
+// A stacked set of bigWigs is one track over a MultiWiggleAdapter, which the
+// per-file guesser cannot express — the web take hand-wrote the config. The
+// subadapters form rather than the `bigWigs` shorthand: that one takes
+// absolute URLs only, and desktop's locations are paths.
+// the file's name without its bigWig extension, or undefined for any other file
+function bigWigStem(location) {
+    const fileName = location.split(/[/\\]/).pop() ?? location;
+    const match = /^(.+)\.(bw|bigwig)$/i.exec(fileName);
+    return match?.[1];
+}
+function multiWiggleTrackConf(locations, assemblyName) {
+    const stems = locations.map(l => bigWigStem(l));
+    const notBigWig = locations.filter((_, i) => stems[i] === undefined);
+    if (notBigWig.length) {
+        throw new Error(`jb.addTrack takes a list of locations only for bigWigs (one stacked MultiQuantitativeTrack); not bigWig: ${notBigWig.join(', ')}. Add other formats one at a time.`);
+    }
+    const adapter = {
+        type: 'MultiWiggleAdapter',
+        subadapters: locations.map((l, i) => ({
+            type: 'BigWigAdapter',
+            name: stems[i],
+            bigWigLocation: fileLocation(l),
+        })),
+    };
+    return {
+        trackId: `multiwiggle-${objectHash(adapter).slice(0, 8)}`,
+        type: 'MultiQuantitativeTrack',
+        name: stems.join(', '),
+        assemblyNames: [assemblyName],
+        adapter,
+    };
+}
+// one location, a list of them, or nothing usable
+function locationsOf(value) {
+    return Array.isArray(value)
+        ? value.filter((l) => typeof l === 'string')
+        : typeof value === 'string'
+            ? 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.
+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,
+                },
+            ],
+        ]
+        : []));
+}
+// 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.
+export async function ensureReExports() {
+    setReExportRegistry((await import('@jbrowse/core/ReExports/modules')).default);
+}
+// 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
+// life of a plugin manager.
+export function createJbApi(pluginManager) {
+    // Resolved per call, never captured: jb.loadSessionSpec REPLACES the session,
+    // and a helper bound to the old one keeps answering from a detached tree —
+    // which reads as stale data rather than throwing, so the agent is told about
+    // a session that no longer exists. `jb.session` is how code re-reads it after
+    // a spec load.
+    const live = () => {
+        const current = sessionOf(pluginManager);
+        if (!current) {
+            throw new Error('No session is open');
+        }
+        return current;
+    };
+    const jb = {
+        get session() {
+            return live();
+        },
+        get rootModel() {
+            return pluginManager.rootModel;
+        },
+        require: pluginManager.jbrequire,
+        ensureRequire: ensureReExports,
+        mst,
+        mobx,
+        readConfObject,
+        getConf,
+        describeSlots,
+        parseLocString,
+        getFeatureAdapterOrThrow,
+        getRpcSessionId,
+        renameRegionsIfNeeded,
+        createStopToken,
+        stopStopToken,
+        waitReady: (timeoutMs) => 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),
+        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;
+            const session = live();
+            const conf = session.getTrackById(fetchArgs.trackId);
+            if (!conf) {
+                throw new Error(`No track with trackId "${fetchArgs.trackId}" — jb.listTracks() shows what is available`);
+            }
+            const regions = fetchArgs.regions ??
+                (fetchArgs.loc !== undefined
+                    ? [
+                        await locToRegion(session, conf, fetchArgs.loc, fetchArgs.assembly),
+                    ]
+                    : await visibleRegionsOf(session, fetchArgs.viewId, fetchArgs.trackId));
+            return fetchFeatures(pluginManager, session, fetchArgs.trackId, regions, fetchArgs.byteLimit);
+        },
+    };
+    return jb;
+}
+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)');
+    }
+    const requested = typeof args.assembly === 'string' ? args.assembly : session.assemblyNames[0];
+    if (requested === undefined) {
+        throw new Error('The session has no assemblies to attach the track to');
+    }
+    // resolved to the session's own spelling: an alias ("vvx" for "volvox",
+    // "GRCh38" for "hg38") names the assembly and would otherwise be refused
+    const assembly = session.assemblyNames.find(name => isSameAssemblyName(name, requested, session.assemblyManager));
+    if (assembly === undefined) {
+        throw new Error(`Assembly "${requested}" is not in this session (has: ${session.assemblyNames.join(', ')})`);
+    }
+    const conf = Array.isArray(location)
+        ? multiWiggleTrackConf(location, assembly)
+        : guessTrackConfForLocation(fileLocation(location), typeof args.index === 'string' ? fileLocation(args.index) : undefined, pluginManager, assembly);
+    session.addSessionTrackConf({
+        ...conf,
+        ...(typeof args.name === 'string' ? { name: args.name } : {}),
+    });
+    const summary = {
+        trackId: conf.trackId,
+        trackType: conf.type,
+        adapterType: conf.adapter.type,
+        assembly,
+    };
+    if (args.show === false) {
+        return summary;
+    }
+    const view = pickView(session, args, 'showTrack', {
+        assembly,
+        trackType: conf.type,
+        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 };
+}
+// 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,
+// while the settle result already names what is still not ready
+const SPEC_SETTLE_DEFAULT_MS = 30_000;
+async function loadSpec(pluginManager, args) {
+    const spec = args.spec;
+    const valid = typeof spec === 'object' &&
+        spec !== null &&
+        Array.isArray(spec.views);
+    if (!valid) {
+        throw new Error('loadSessionSpec needs a spec object with a views array');
+    }
+    await loadSessionSpec(spec, pluginManager);
+    // the session was REPLACED by the spec load — settle against the new one
+    const session = sessionOf(pluginManager);
+    const settle = await waitReady(args.settleMs ?? SPEC_SETTLE_DEFAULT_MS, session);
+    return {
+        ...settle,
+        ...(session ? { session: sessionSummary(session) } : {}),
+    };
+}