@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.2

package/esm/util/legendCandidates.js

@@ -0,0 +1,87 @@
+// How many distinct colors a derived key may name and still BE a key. Past this
+// the data is not a categorical vocabulary (a track keyed by unique per-feature
+// names), and a list of every feature is the thing a key exists instead of.
+//
+// A different question from `legendIsReadable`'s lower bar, which asks whether a
+// key a display already has is worth the rows it costs.
+export const MAX_LEGEND_ENTRIES = 30;
+// Bound on the candidate list one region ships. Far above MAX_LEGEND_ENTRIES, so
+// a vocabulary that is categorical at all crosses whole, and a track with a name
+// per feature ships a prefix that reads the same way it would have.
+export const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export function createLegendCandidateCollector(maxCandidates = MAX_LEGEND_CANDIDATES) {
+    const candidates = [];
+    const colorsSeen = new Map();
+    return {
+        candidates,
+        add(rowIndex, label, color) {
+            if (label !== '' && candidates.length < maxCandidates) {
+                let byLabel = colorsSeen.get(rowIndex);
+                if (byLabel === undefined) {
+                    byLabel = new Map();
+                    colorsSeen.set(rowIndex, byLabel);
+                }
+                let colors = byLabel.get(label);
+                if (colors === undefined) {
+                    colors = new Set();
+                    byLabel.set(label, colors);
+                }
+                if (!colors.has(color)) {
+                    colors.add(color);
+                    candidates.push({ rowIndex, label, color });
+                }
+            }
+        },
+    };
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export function unionLegendCandidates(regions, resolve, maxEntries = MAX_LEGEND_ENTRIES) {
+    const entries = [];
+    const seenColors = new Set();
+    const seenLabels = new Set();
+    for (const region of regions) {
+        const { candidates, rowPaintsCandidateColor } = resolve(region);
+        for (const { rowIndex, label, color } of candidates) {
+            if (rowPaintsCandidateColor(rowIndex) &&
+                !seenLabels.has(label) &&
+                !seenColors.has(color)) {
+                seenLabels.add(label);
+                seenColors.add(color);
+                entries.push({ label, color });
+                if (entries.length > maxEntries) {
+                    return [];
+                }
+            }
+        }
+    }
+    return entries;
+}

package/esm/util/mstUtils.d.ts

@@ -1,5 +1,5 @@
 import type PluginManager from '../PluginManager.ts';
-import type { AbstractDisplayModel, AbstractSessionModel, AbstractTrackModel, AbstractViewModel } from './types/index.ts';
+import type { AbstractDisplayModel, AbstractSessionModel, AbstractViewContainer, AbstractTrackModel, AbstractViewModel } from './types/index.ts';
 import type { AssemblyHost, RenderingServices } from './types/renderingServices.ts';
 import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
 export { findParentThat, findParentThatIs, getRpcSessionId, } from './parentWalk.ts';
@@ -85,5 +85,16 @@ export declare function canonicalizeViewRefName(node: IAnyStateTreeNode, refName
 export declare function getEnv(obj: IAnyStateTreeNode): {
     pluginManager: PluginManager;
 };
+/**
+ * #api core/util
+ * `addOrReplaceView` for view types whose state model may be lazily loaded;
+ * the synchronous `addOrReplaceView` requires it loaded already.
+ */
+export declare function launchOrReplaceView(args: {
+    session: AbstractViewContainer;
+    typeName: string;
+    initialState?: Record<string, unknown>;
+    replacing?: AbstractViewModel;
+}): Promise<AbstractViewModel>;
 export declare function hashCode(str: string): number;
 export declare function objectHash(obj: object): string;

package/esm/util/mstUtils.js

@@ -1,6 +1,6 @@
-import { getEnv as getEnvMST } from '@jbrowse/mobx-state-tree';
+import { getEnv as getEnvMST, isStateTreeNode } from '@jbrowse/mobx-state-tree';
 import { cachedParent, findParentThatIs } from './parentWalk.js';
-import { isDisplayModel, isSessionModel, isTrackModel, isViewModel, } from './types/index.js';
+import { addOrReplaceView, isDisplayModel, isSessionModel, isTrackModel, isViewModel, } from './types/index.js';
 export { findParentThat, findParentThatIs, getRpcSessionId, } from './parentWalk.js';
 const containingDisplayCache = new WeakMap();
 const containingTrackCache = new WeakMap();
@@ -105,6 +105,24 @@ export function canonicalizeViewRefName(node, refName) {
 export function getEnv(obj) {
     return getEnvMST(obj);
 }
+/**
+ * #api core/util
+ * `addOrReplaceView` for view types whose state model may be lazily loaded;
+ * the synchronous `addOrReplaceView` requires it loaded already.
+ */
+export async function launchOrReplaceView(args) {
+    // a test's fake session is not an MST node; addView's own guard is the
+    // error path there
+    if (isStateTreeNode(args.session)) {
+        const { pluginManager } = getEnvMST(args.session);
+        await pluginManager?.getViewType(args.typeName).loadStateModel();
+        // the displays of the tracks a launch opens with are dynamic imports too
+        await pluginManager?.preloadSessionTypes({
+            views: [{ type: args.typeName, ...args.initialState }],
+        });
+    }
+    return addOrReplaceView(args);
+}
 export function hashCode(str) {
     let hash = 0;
     if (str.length === 0) {

package/esm/util/pluginStore.d.ts

@@ -34,6 +34,7 @@ export interface PluginUpdate {
     name: string;
     definition: PluginDefinition;
 }
+export declare function releaseVersion(jbrowseVersion: string): string;
 export declare function resolvePlugin(plugin: JBrowsePlugin, jbrowseVersion: string): ResolvedPlugin;
 export declare function installedVersionFromUrl(url: string | undefined, packageName: string | undefined): string | undefined;
 /**

package/esm/util/pluginStore.js

@@ -37,6 +37,13 @@ export function installablePlugins(plugins, isElectron) {
         (isElectron ||
             publishedBuilds(plugin).some(b => b.esmUrl ?? b.url ?? b.umdUrl)));
 }
+// A prerelease host is its release for compatibility purposes. Under semver
+// 5.0.0-beta.1 sorts below 5.0.0, so a range written to keep a plugin off v5
+// (`<5.0.0`) would serve it to every beta host and a v5-only range (`>=5.0.0`)
+// would hide it from them. Store ranges are written against release versions.
+export function releaseVersion(jbrowseVersion) {
+    return jbrowseVersion.split('-')[0];
+}
 // `*` (and empty) mean "any JBrowse version"; compare-versions throws on those,
 // so handle them directly. A malformed range simply fails to match rather than
 // breaking the store UI — producer-side validation is the place to reject those.
@@ -44,7 +51,7 @@ function rangeMatches(jbrowseVersion, range) {
     let matched = range === '*' || range === '';
     if (!matched) {
         try {
-            matched = satisfies(jbrowseVersion, range);
+            matched = satisfies(releaseVersion(jbrowseVersion), range);
         }
         catch {
             matched = false;

package/esm/util/range.d.ts

@@ -20,9 +20,15 @@ export declare function doesIntersect2(left1: number, right1: number, left2: num
 /**
  * Compute the expanded fetch range a tabix adapter must "redispatch" to when
  * features found in a query extend past the requested window. Returns the union
- * of the query with the bounds of every feature whose type is not in
- * `dontRedispatchSet`, or `undefined` when nothing extends past the query (no
- * redispatch needed).
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
  *
  * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
  * the index's coordinate offset before invoking the line callback, so a GFF/GTF
@@ -30,15 +36,13 @@ export declare function doesIntersect2(left1: number, right1: number, left2: num
  *
  * Seeding the accumulator with the query bounds is what makes the result a
  * union rather than just the feature bounds. A redispatch narrower than the
- * original window would drop a dontRedispatch-typed feature that the first
- * fetch found inside the query but that falls outside the expanded range, since
- * those types are deliberately excluded from the bounds.
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
  */
-export declare function calculateRedispatchRange(features: {
+export declare function calculateRedispatchRange<T extends {
     start: number;
     end: number;
-    type: string;
-}[], dontRedispatchSet: Set<string>, queryStart: number, queryEnd: number): {
+}>(features: T[], expands: (feature: T) => boolean, queryStart: number, queryEnd: number): {
     start: number;
     end: number;
 } | undefined;

package/esm/util/range.js

@@ -45,9 +45,15 @@ export function doesIntersect2(left1, right1, left2, right2) {
 /**
  * Compute the expanded fetch range a tabix adapter must "redispatch" to when
  * features found in a query extend past the requested window. Returns the union
- * of the query with the bounds of every feature whose type is not in
- * `dontRedispatchSet`, or `undefined` when nothing extends past the query (no
- * redispatch needed).
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
  *
  * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
  * the index's coordinate offset before invoking the line callback, so a GFF/GTF
@@ -55,15 +61,18 @@ export function doesIntersect2(left1, right1, left2, right2) {
  *
  * Seeding the accumulator with the query bounds is what makes the result a
  * union rather than just the feature bounds. A redispatch narrower than the
- * original window would drop a dontRedispatch-typed feature that the first
- * fetch found inside the query but that falls outside the expanded range, since
- * those types are deliberately excluded from the bounds.
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
  */
-export function calculateRedispatchRange(features, dontRedispatchSet, queryStart, queryEnd) {
+export function calculateRedispatchRange(features, expands, queryStart, queryEnd) {
     let minStart = queryStart;
     let maxEnd = queryEnd;
+    // bounds first: only a line reaching past the current bound can widen it, so
+    // the predicate, which may scan the line's text, runs on those few lines and
+    // not on every line in the window
     for (const feature of features) {
-        if (!dontRedispatchSet.has(feature.type)) {
+        if ((feature.start < minStart || feature.end > maxEnd) &&
+            expands(feature)) {
             if (feature.start < minStart) {
                 minStart = feature.start;
             }

package/esm/util/rxjs.d.ts

@@ -15,3 +15,19 @@ import type { Observer } from 'rxjs';
  * @param func - observer function, could be async
  */
 export declare function ObservableCreate<T>(func: (arg: Observer<T>) => void | Promise<void>, stopToken?: StopToken): Observable<T>;
+/**
+ * Subscribe to an observable and resolve when it completes, running `onNext` per
+ * item as it arrives — the streaming shape for parsing items out of a feature
+ * stream rather than collecting them first.
+ *
+ * **`onNext` throwing rejects the promise.** rxjs does not do that on its own:
+ * an exception out of a `next` handler goes to its global unhandled-error hook,
+ * so the subscriber keeps being fed and `complete` still fires — a bare promise
+ * around that resolves as *success* with the items silently missing. Beside
+ * `ObservableCreate` because it is the other half of the pattern: the adapter
+ * wraps its body in that, the RPC `await`s this, so a per-item parse failure
+ * surfaces as a track error instead of a blank-but-loaded track.
+ *
+ * The source is unsubscribed on the first throw.
+ */
+export declare function subscribeToObservable<T>(observable: Observable<T>, onNext: (item: T) => void): Promise<void>;

package/esm/util/rxjs.js

@@ -43,3 +43,52 @@ export function ObservableCreate(func, stopToken) {
         };
     });
 }
+/**
+ * Subscribe to an observable and resolve when it completes, running `onNext` per
+ * item as it arrives — the streaming shape for parsing items out of a feature
+ * stream rather than collecting them first.
+ *
+ * **`onNext` throwing rejects the promise.** rxjs does not do that on its own:
+ * an exception out of a `next` handler goes to its global unhandled-error hook,
+ * so the subscriber keeps being fed and `complete` still fires — a bare promise
+ * around that resolves as *success* with the items silently missing. Beside
+ * `ObservableCreate` because it is the other half of the pattern: the adapter
+ * wraps its body in that, the RPC `await`s this, so a per-item parse failure
+ * surfaces as a track error instead of a blank-but-loaded track.
+ *
+ * The source is unsubscribed on the first throw.
+ */
+export function subscribeToObservable(observable, onNext) {
+    return new Promise((resolve, reject) => {
+        // A box rather than two bare `let`s: oxlint narrows a flag assigned only
+        // inside a closure to its initializer and reports the reads as always-false.
+        // `subscription` is genuinely still undefined during a synchronous source's
+        // first emissions, which is why it is read optionally below.
+        const state = {
+            failed: false,
+        };
+        state.subscription = observable.subscribe({
+            next: item => {
+                if (!state.failed) {
+                    try {
+                        onNext(item);
+                    }
+                    catch (e) {
+                        state.failed = true;
+                        // A parser throws an Error in every real case here; the wrap is for
+                        // the rule that a rejection reason must be one, and keeps whatever
+                        // was actually thrown as the `cause`.
+                        reject(e instanceof Error ? e : new Error(String(e), { cause: e }));
+                        state.subscription?.unsubscribe();
+                    }
+                }
+            },
+            error: reject,
+            complete: () => {
+                if (!state.failed) {
+                    resolve();
+                }
+            },
+        });
+    });
+}

package/esm/util/tabix.d.ts

@@ -45,9 +45,15 @@ export declare function readTabixLines(gff: TabixLineSource, refName: string, st
  * Read a region's tabix lines, then — if any feature found there extends past
  * the query — read the overhang on either side, so a parent line's children (a
  * gene's exons, a transcript's CDS) outside the original window are pulled in
- * and the parent/child tree resolves fully. Types in `dontRedispatchSet` are
- * excluded from the bounds, so one chromosome-spanning record can't force a
- * whole-chromosome refetch.
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
  *
  * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
  * everything the first read already had — a second full read of the query range
@@ -76,7 +82,7 @@ export declare function readTabixLinesRedispatched(file: TabixLineSource, query:
     refName: string;
     start: number;
     end: number;
-}, dontRedispatchSet: Set<string>, opts?: {
+}, expands: (line: TabixLine) => boolean, opts?: {
     statusCallback?: StatusCallback;
     stopToken?: StopToken;
 }): Promise<TabixLine[]>;

package/esm/util/tabix.js

@@ -44,9 +44,15 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
  * Read a region's tabix lines, then — if any feature found there extends past
  * the query — read the overhang on either side, so a parent line's children (a
  * gene's exons, a transcript's CDS) outside the original window are pulled in
- * and the parent/child tree resolves fully. Types in `dontRedispatchSet` are
- * excluded from the bounds, so one chromosome-spanning record can't force a
- * whole-chromosome refetch.
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
  *
  * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
  * everything the first read already had — a second full read of the query range
@@ -74,13 +80,13 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
 export async function readTabixLinesRedispatched(file, 
 // the region's locus only — kept structural, like TabixLineSource above, so
 // this module stays free of the `types` barrel and its MST models
-query, dontRedispatchSet, opts = {}) {
+query, expands, opts = {}) {
     const { statusCallback, stopToken } = opts;
     // `cb` is not optional: each read decides where it reports, and the flanks
     // report somewhere the first read does not
     const read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, stopToken);
     const lines = await read(query.start, query.end, statusCallback);
-    const redispatch = calculateRedispatchRange(lines, dontRedispatchSet, query.start, query.end);
+    const redispatch = calculateRedispatchRange(lines, expands, query.start, query.end);
     if (redispatch) {
         const slot = createStatusFanOut(statusCallback);
         const flanks = await Promise.all([

package/esm/util/tracks.d.ts

@@ -3,6 +3,7 @@ export { getRpcSessionId } from './parentWalk.ts';
 import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
 import type { BlobLocation, FileHandleLocation, FileLocation, PreFileLocation } from './types/data.ts';
+import type { AbstractViewContainer } from './types/index.ts';
 import type { IAnyStateTreeNode, IAnyType, IStateTreeNode, Instance, types } from '@jbrowse/mobx-state-tree';
 export declare function getTrackAssemblyNames(track: IStateTreeNode & {
     configuration: AnyConfigurationModel;
@@ -242,6 +243,23 @@ export declare function guessTrackConf(input: string | LooseTrackInput, pluginMa
     assemblyNames: string[];
     adapter: AdapterConfig;
 };
+/**
+ * {@link guessTrackConf} over an already-built {@link FileLocation}, for a
+ * caller holding a location the loose `{ uri }` vocabulary cannot spell — a
+ * desktop local path. Kept separate so `LooseTrackInput` stays URI-only: it
+ * sits on the track-config union and the root config's `tracks`, where a
+ * local path would be a config a web deployment could not open.
+ *
+ * The `trackId` is a content hash of the adapter, not a timestamp, so adding
+ * the same file twice is idempotent — `addToSession` dedupes on it.
+ */
+export declare function guessTrackConfForLocation(file: FileLocation, index: FileLocation | undefined, pluginManager: PluginManager, assemblyName?: string): {
+    trackId: string;
+    type: string;
+    name: string;
+    assemblyNames: string[];
+    adapter: AdapterConfig;
+};
 /**
  * Whether a track snapshot is the loose `{ uri, ... }` form — a data file with
  * no `adapter` — that {@link expandLooseTrackConfig} expands.
@@ -294,6 +312,7 @@ interface MinimalTrack extends IAnyType {
 interface GenericView {
     type: string;
     tracks: MSTArray<MinimalTrack>;
+    showTrack?: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>) => unknown;
 }
 /**
  * The display-snapshot argument of `showTrackGeneric`, exported so a view's own
@@ -403,6 +422,8 @@ export declare function stripTrackIds(tracks: TrackSnapshot[]): {
 }[];
 export declare function hideTrackGeneric(self: GenericView, trackId: string): boolean;
 export declare function toggleTrackGeneric(self: GenericView, trackId: string): boolean;
+export declare function launchTrackGeneric(self: GenericView, trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>): Promise<any>;
+export declare function launchToggleTrackGeneric(self: GenericView, trackId: string): Promise<boolean>;
 /**
  * Every track config the session can show, connection-supplied ones included.
  *
@@ -424,3 +445,30 @@ export declare function allSessionTracks(session: {
     setSubschema(slotName: string, data: Record<string, unknown>): any;
     setSlot(slotName: string, value: unknown): void;
 } & IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>)[];
+/**
+ * The session's annotation for `assemblyName`, as trackIds: what a view opened
+ * on another genome starts with. Only FeatureTracks, not everything configured
+ * for the assembly — an alignments track turned on behind the user's back
+ * fetches data nobody asked for, and a FeatureTrack over a few kb is one tabix
+ * range query.
+ */
+export declare function annotationTrackIds(session: {
+    tracks: AnyConfigurationModel[];
+    connectionInstances?: {
+        tracks: AnyConfigurationModel[];
+    }[];
+    assemblyManager: AssemblyNameResolver;
+}, assemblyName: string): string[];
+/**
+ * One assembly on its own in a linear genome view, at `loc`. Keyed on `id`:
+ * following several alignments to one genome re-navigates the view rather than
+ * stacking a new one each time.
+ */
+export declare function openAssemblyInLinearView({ session, id, assemblyName, loc, tracks, }: {
+    session: AbstractViewContainer;
+    id: string;
+    assemblyName: string;
+    loc: string;
+    tracks: TrackInit[];
+}): Promise<void>;
+export declare function openMateLabel(assemblyName: string): string;