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

package/esm/JbApi/jbApi.js

@@ -63,25 +63,76 @@ function displayState(track) {
                 ? { reason: display.regionTooLargeReason }
                 : {}),
             ...(display.error ? { error: String(display.error) } : {}),
+            ...(display.renderError
+                ? { renderError: String(display.renderError) }
+                : {}),
         };
     }
     catch (e) {
         return { display: display.type, error: String(e) };
     }
 }
+/**
+ * The drawer and any modal, for the same reason `offscreen` is reported: both
+ * are on top of the views in a screenshot that otherwise looks right.
+ *
+ * The drawer takes a column off every view rather than covering them, so a
+ * figure framed with the track selector open is narrower than the one asked
+ * for — which every filmed take worked around by telling the agent in its
+ * system prompt to close it. A modal covers the app outright.
+ */
+function sessionChrome(session) {
+    const s = session;
+    const drawer = s.drawerVisible && s.visibleWidget
+        ? {
+            drawer: {
+                widget: s.visibleWidget.type,
+                ...(typeof s.drawerWidth === 'number'
+                    ? { width: s.drawerWidth }
+                    : {}),
+                note: 'the drawer takes this width off every view; session.hideAllWidgets() closes it',
+            },
+        }
+        : {};
+    const dialog = s.DialogComponent
+        ? {
+            dialog: {
+                note: 'a modal dialog is open over the app, so a screenshot is of the dialog',
+            },
+        }
+        : {};
+    return { ...drawer, ...dialog };
+}
 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.
+/**
+ * Why a view is not finished, or nothing if it is.
+ *
+ * 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.
+ */
 function viewState(v) {
-    return {
-        ...(v.error === undefined ? {} : { error: String(v.error) }),
-        ...(v.error === undefined && v.initialized === false
-            ? { phase: 'initializing' }
-            : {}),
-    };
+    if (v.error !== undefined) {
+        return { error: String(v.error) };
+    }
+    if (v.initialized === false) {
+        return { phase: 'initializing' };
+    }
+    return v.pendingLaunch === undefined
+        ? {}
+        : {
+            phase: 'launching',
+            reason: 'the view is still applying what it was launched with (navigation, tracks)',
+        };
 }
 function viewSummary(view) {
     const v = viewSelf(view);
@@ -115,6 +166,7 @@ function sessionSummary(session) {
     return {
         name: session.name,
         assemblyNames: session.assemblyNames,
+        ...sessionChrome(session),
         views: session.views.map(v => viewSummary(v)),
     };
 }
@@ -312,6 +364,7 @@ root = document) {
         ...(messages.length ? { notifications: messages } : {}),
         ...(notReady.length ? { notReady } : {}),
         ...(offscreen ? { offscreen } : {}),
+        ...(session ? sessionChrome(session) : {}),
     };
 }
 // A session taller than the window scrolls, and a screenshot of the viewport
@@ -471,7 +524,7 @@ function shownTrackModel(session, trackId, viewId) {
     // 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`
+            ? `"${trackId}" is not shown in ${viewId === undefined ? 'any open view' : `view ${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;
@@ -715,16 +768,16 @@ const JB_HELP = `jb drives this JBrowse app programmatically (window.jb in a bro
 
 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.
+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.
 
-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.
+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.
 
 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
 // life of a plugin manager.
-export function createJbApi(pluginManager) {
+export function createJbApi(pluginManager, options = {}) {
     // 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
@@ -737,6 +790,18 @@ export function createJbApi(pluginManager) {
         }
         return current;
     };
+    // Every settle an agent can reach goes through here, so a notification
+    // cannot be consumed by one of these helpers without the caller hearing
+    // about it.
+    // a declaration, not a generic arrow: `<T>(x: T) => …` in a .ts file is a
+    // JSX tag to babel, which is what jest parses these with
+    function reported(settle) {
+        const messages = settle.notifications;
+        if (Array.isArray(messages) && messages.length > 0) {
+            options.onNotifications?.(messages);
+        }
+        return settle;
+    }
     const jb = {
         help: JB_HELP,
         get session() {
@@ -760,15 +825,15 @@ export function createJbApi(pluginManager) {
         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: (timeoutMs = 30_000) => waitReady(timeoutMs, live()),
+        waitReady: async (timeoutMs = 30_000) => reported(await waitReady(timeoutMs, live())),
         sessionSummary: () => sessionSummary(live()),
         inspect: (path, maxInspectBytes) => inspectSession(live(), { path, 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: (spec, settleMs) => loadSpec(pluginManager, { spec, settleMs }),
-        addTrack: (opts) => addTrack(pluginManager, live(), opts),
+        loadSessionSpec: async (spec, settleMs) => reported(await loadSpec(pluginManager, { spec, 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
         // jb.getFeatures('trackId', loc, { assembly }) and had the options
@@ -831,12 +896,16 @@ async function addTrack(pluginManager, session, args) {
     if (args.show === false) {
         return summary;
     }
-    const view = pickView(session, args, 'showTrack', {
+    const view = pickView(session, args, 'launchTrack', {
         assembly,
         trackType: conf.type,
         pluginManager,
     });
-    viewSelf(view).showTrack(conf.trackId);
+    // 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 };
     // 0 skips the settle, so several adds can share one jb.waitReady
     const settleMs = typeof args.settleMs === 'number' ? args.settleMs : ADD_TRACK_SETTLE_MS;

package/esm/ui/App/AppReadyMarker.js

@@ -4,14 +4,30 @@ 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.
+/**
+ * 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.
+ *
+ * `pendingLaunch` is the third term and the one that was missing. `initialized`
+ * goes true mid-launch — LGV's flips the moment displayedRegions land, while
+ * the same apply pass still has the spec's tracks to attach — and `showLoading`
+ * goes false at the same moment, deliberately, so the reader sees the
+ * navigated view rather than a spinner while its tracks arrive. That left a
+ * window, exactly as wide as attaching the tracks, in which the marker said
+ * `ready` over a session missing everything it had been asked for.
+ * `whenViewSettled` states the same rule for the callers that await a single
+ * view, and says why in more detail. Not shared as one predicate: that one
+ * requires `initialized`, while absent here means not loading, and an adapter
+ * between the two null rules would read as agreement it does not have.
+ */
 function viewLoading(view) {
     const flags = view;
     return (flags.error === undefined &&
-        (flags.showLoading === true || flags.initialized === false));
+        (flags.showLoading === true ||
+            flags.initialized === false ||
+            flags.pendingLaunch !== undefined));
 }
 /**
  * One element that says whether the whole app has finished, and what is open.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/app-core",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.8",
   "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/core": "^5.0.0-beta.4",
-    "@jbrowse/product-core": "^5.0.0-beta.4"
+    "@jbrowse/product-core": "^5.0.0-beta.8",
+    "@jbrowse/core": "^5.0.0-beta.8"
   },
   "peerDependencies": {
     "react": ">=19.0.0",