@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/BaseFeatureWidget/stateModelFactory.js

@@ -1,44 +1,128 @@
 import { addDisposer, types } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
-import { getConf } from "../configuration/index.js";
-import { getSession } from "../util/index.js";
-import { SequenceFeatureDetailsF } from "./SequenceFeatureDetails/model.js";
-import { formatSubfeatures } from "./util.js";
-import { ElementId } from "../util/types/mst.js";
+import { getSession } from '../util/index.js';
+import { ElementId } from '../util/types/mst.js';
+import { SequenceFeatureDetailsF } from './SequenceFeatureDetails/model.js';
+import { applyFormatDetails, formatDetailsNumber } from './formatDetails.js';
+import { nullReplacer } from './util.js';
+/**
+ * #stateModel BaseFeatureWidget
+ * displays data about features, allowing configuration callbacks to modify the
+ * contents of what is displayed
+ *
+ * see: formatDetails-\>feature,formatDetails-\>subfeatures
+ */
 export function stateModelFactory(pluginManager) {
     return types
         .model('BaseFeatureWidget', {
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         type: types.literal('BaseFeatureWidget'),
-        featureData: types.frozen(),
-        formattedFields: types.frozen(),
-        unformattedFeatureData: types.frozen(),
+        /**
+         * #property
+         */
+        featureData: types.optional(types.frozen(), undefined),
+        /**
+         * #property
+         */
+        unformattedFeatureData: types.optional(types.frozen(), undefined),
+        /**
+         * #property
+         */
         view: types.safeReference(pluginManager.pluggableMstType('view', 'stateModel')),
+        /**
+         * #property
+         */
         track: types.safeReference(pluginManager.pluggableMstType('track', 'stateModel')),
+        /**
+         * #property
+         */
         trackId: types.maybe(types.string),
+        /**
+         * #property
+         */
         trackType: types.maybe(types.string),
+        /**
+         * #property
+         */
         maxDepth: types.maybe(types.number),
+        /**
+         * #property
+         */
         sequenceFeatureDetails: types.optional(SequenceFeatureDetailsF(), {}),
-        descriptions: types.frozen(),
+        /**
+         * #property
+         */
+        descriptions: types.optional(types.frozen(), undefined),
     })
         .volatile(() => ({
+        /**
+         * #volatile
+         */
         error: undefined,
+        /**
+         * #volatile
+         * genomic base currently hovered in this widget's sequence panel, read by
+         * the LGV crosshair overlay
+         */
+        sequenceHoverPosition: undefined,
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
+        setSequenceHoverPosition(pos) {
+            // skip no-op updates: mousemove fires per pixel but the base under the
+            // cursor changes far less often, and each change re-renders the LGV
+            // crosshair overlay
+            const prev = self.sequenceHoverPosition;
+            const same = prev === pos ||
+                (prev?.refName === pos?.refName &&
+                    prev?.start === pos?.start &&
+                    prev?.end === pos?.end);
+            if (!same) {
+                self.sequenceHoverPosition = pos;
+            }
+        },
+        /**
+         * #action
+         */
         setFeatureData(featureData) {
             self.unformattedFeatureData = featureData;
         },
+        /**
+         * #action
+         */
         clearFeatureData() {
             self.featureData = undefined;
         },
+        /**
+         * #action
+         */
         setFormattedData(feat) {
             self.featureData = feat;
         },
-        setExtra(type, trackId, maxDepth) {
+        /**
+         * #action
+         */
+        setTrackInfo(type, trackId) {
             self.trackId = trackId;
             self.trackType = type;
+        },
+        /**
+         * #action
+         */
+        setMaxDepth(maxDepth) {
             self.maxDepth = maxDepth;
         },
+        /**
+         * #action
+         */
         setError(e) {
             self.error = e;
         },
@@ -46,36 +130,48 @@ export function stateModelFactory(pluginManager) {
         .actions(self => ({
         afterCreate() {
             addDisposer(self, autorun(function featureWidgetAutorun() {
+                const { track } = self;
+                // read before any config read so the catch below can attribute
+                // the failure without repeating one that may be what threw
+                let trackId;
                 try {
-                    const { unformattedFeatureData, track } = self;
+                    const { unformattedFeatureData } = self;
                     const session = getSession(self);
                     if (track) {
-                        self.setExtra(track.type, track.configuration.trackId, getConf(track, ['formatDetails', 'maxDepth']));
+                        trackId = track.configuration.trackId;
+                        self.setTrackInfo(track.type, trackId);
                     }
+                    // both tiers apply: a widget can outlive its track
+                    // (safeReference) or never have had one, and the session-wide
+                    // `configuration.formatDetails` still means something. The
+                    // reads stay here in the autorun body rather than moving into
+                    // an action, which would run untracked
+                    const tiers = { session, track };
+                    // an unset maxDepth is the meaningful value, not a missing one:
+                    // the panel reads it as no nesting limit
+                    self.setMaxDepth(formatDetailsNumber(tiers, 'maxDepth'));
                     if (unformattedFeatureData) {
-                        const feature = structuredClone(unformattedFeatureData);
-                        const combine = (arg2, feature) => ({
-                            ...getConf(session, ['formatDetails', arg2], { feature }),
-                            ...getConf(track, ['formatDetails', arg2], { feature }),
-                        });
-                        if (track) {
-                            feature.__jbrowsefmt = combine('feature', feature);
-                            formatSubfeatures(feature, getConf(track, ['formatDetails', 'depth']), sub => {
-                                sub.__jbrowsefmt = combine('subfeatures', sub);
-                            });
-                        }
-                        self.setFormattedData(feature);
+                        self.setFormattedData(applyFormatDetails(tiers, unformattedFeatureData));
                     }
                 }
                 catch (e) {
-                    console.error(e);
-                    self.setError(e);
+                    // jexl throws a bare parse/eval message with nothing naming the
+                    // slot or the config it came from, and this banner replaces the
+                    // whole panel -- say where to look
+                    const where = trackId
+                        ? `track "${trackId}"`
+                        : 'the session configuration';
+                    const err = new Error(`Error running the formatDetails callbacks for ${where}: ${e}`, { cause: e });
+                    console.error(err);
+                    self.setError(err);
                 }
             }, { name: 'FeatureWidget' }));
         },
     }))
-        .preProcessSnapshot(snap => {
-        const { featureData, finalizedFeatureData, ...rest } = snap;
+        .preProcessSnapshot((snap) => {
+        // old snapshots used `featureData`, new ones use `finalizedFeatureData`;
+        // accept both for backwards compat
+        const { featureData, finalizedFeatureData, ...rest } = (snap ?? {});
         return {
             unformattedFeatureData: featureData,
             featureData: finalizedFeatureData,
@@ -84,8 +180,11 @@ export function stateModelFactory(pluginManager) {
     })
         .postProcessSnapshot(snap => {
         const { unformattedFeatureData, featureData, ...rest } = snap;
-        const s2 = JSON.stringify(featureData, (_, v) => v === undefined ? null : v);
+        // JSON.stringify can return empty if too large
+        const s2 = JSON.stringify(featureData, nullReplacer);
         const featureTooLargeToBeSerialized = !s2 || s2.length > 2_000_000;
+        // `finalizedFeatureData` is persisted (rather than `featureData`) so
+        // loading from snapshot doesn't re-run the formatter callbacks
         return {
             finalizedFeatureData: featureTooLargeToBeSerialized
                 ? undefined

package/esm/BaseFeatureWidget/types.d.ts

@@ -1,12 +1,13 @@
-import type React from 'react';
-import type { BaseFeatureWidgetModel } from './stateModelFactory.ts';
 import type { SimpleFeatureSerialized } from '../util/simpleFeature.ts';
+import type { BaseFeatureWidgetModel } from './stateModelFactory.ts';
+import type React from 'react';
 export interface Descriptors {
     [key: string]: React.ReactNode | Descriptors;
 }
+export type FeatureFormatter = (value: unknown, key: string, index?: number) => React.ReactNode;
 export interface BaseProps extends BaseCardProps {
     feature: SimpleFeatureSerialized;
-    formatter?: (val: unknown, key: string) => React.ReactNode;
+    formatter?: FeatureFormatter;
     descriptions?: Descriptors;
     model?: BaseFeatureWidgetModel;
 }

package/esm/BaseFeatureWidget/util.d.ts

@@ -1,11 +1,10 @@
 import type { SerializedFeat } from './types.tsx';
-import type { SimpleFeatureSerialized } from '../util/index.ts';
 export interface Feat {
     start: number;
     end: number;
     type?: string;
     name?: string;
-    id?: string;
+    id?: string | number;
     phase?: number;
 }
 export interface ParentFeat extends Feat {
@@ -23,32 +22,8 @@ export interface SeqState {
 export interface ErrorState {
     error: string;
 }
-export declare function stitch(subfeats: {
-    start: number;
-    end: number;
-}[], sequence: string): string;
 export declare function filterSuccessiveElementsWithSameStartAndEndCoord(list: Feat[]): Feat[];
-export declare function revlist(list: Feat[], seqlen: number): {
-    start: number;
-    end: number;
-    type?: string;
-    name?: string;
-    id?: string;
-    phase?: number;
-}[];
-export declare function calculateUTRs(cds: Feat[], exons: Feat[]): {
-    type: string;
-    start: number;
-    end: number;
-    name?: string;
-    id?: string;
-    phase?: number;
-}[];
-export declare function calculateUTRs2(cds: Feat[], parentFeat: Feat): {
-    type: string;
-    start: number;
-    end: number;
-}[];
 export declare function ellipses(slug: string): string;
-export declare function replaceUndefinedWithNull(obj: SimpleFeatureSerialized): any;
-export declare function formatSubfeatures(obj: SerializedFeat, depth: number, parse: (obj: Record<string, unknown>) => void, currentDepth?: number, returnObj?: Record<string, unknown>): void;
+export declare function getStrandStr(strand: number | undefined): "" | "(+)" | "(-)";
+export declare const nullReplacer: (_: string, v: unknown) => {} | null;
+export declare function formatSubfeatures(obj: SerializedFeat, depth: number, parse: (obj: Record<string, unknown>) => void, currentDepth?: number): void;

package/esm/BaseFeatureWidget/util.js

@@ -1,95 +1,31 @@
-export function stitch(subfeats, sequence) {
-    return subfeats.map(sub => sequence.slice(sub.start, sub.end)).join('');
-}
+// filter items if they have the same "ID" or location
 function getItemId(feat) {
     return `${feat.start}-${feat.end}`;
 }
+// filters if successive elements share same start/end
 export function filterSuccessiveElementsWithSameStartAndEndCoord(list) {
     return list.filter((item, pos, ary) => !pos || getItemId(item) !== getItemId(ary[pos - 1]));
 }
-export function revlist(list, seqlen) {
-    return list
-        .map(sub => ({
-        ...sub,
-        start: seqlen - sub.end,
-        end: seqlen - sub.start,
-    }))
-        .sort((a, b) => a.start - b.start);
-}
-export function calculateUTRs(cds, exons) {
-    if (!cds.length) {
-        return [];
-    }
-    if (exons.length < cds.length) {
-        console.warn('exons.length less than cds.length, cant calculate UTR properly', { exons, cds });
-        return [];
-    }
-    const firstCds = cds.at(0);
-    const lastCds = cds.at(-1);
-    const firstCdsIdx = exons.findIndex(exon => exon.end >= firstCds.start && exon.start <= firstCds.start);
-    const lastCdsIdx = exons.findIndex(exon => exon.end >= lastCds.end && exon.start <= lastCds.end);
-    const lastCdsExon = exons[lastCdsIdx];
-    const firstCdsExon = exons[firstCdsIdx];
-    const fivePrimeUTRs = [
-        ...exons.slice(0, firstCdsIdx),
-        {
-            start: firstCdsExon.start,
-            end: firstCds.start,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'five_prime_UTR',
-    }));
-    const threePrimeUTRs = [
-        {
-            start: lastCds.end,
-            end: lastCdsExon.end,
-        },
-        ...exons.slice(lastCdsIdx + 1),
-    ].map(elt => ({
-        ...elt,
-        type: 'three_prime_UTR',
-    }));
-    return [...fivePrimeUTRs, ...threePrimeUTRs];
-}
-export function calculateUTRs2(cds, parentFeat) {
-    if (!cds.length) {
-        return [];
-    }
-    const firstCds = cds.at(0);
-    const lastCds = cds.at(-1);
-    const fivePrimeUTRs = [
-        {
-            start: parentFeat.start,
-            end: firstCds.start,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'five_prime_UTR',
-    }));
-    const threePrimeUTRs = [
-        {
-            start: lastCds.end,
-            end: parentFeat.end,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'three_prime_UTR',
-    }));
-    return [...fivePrimeUTRs, ...threePrimeUTRs];
-}
 export function ellipses(slug) {
     return slug.length > 20 ? `${slug.slice(0, 20)}...` : slug;
 }
-export function replaceUndefinedWithNull(obj) {
-    return JSON.parse(JSON.stringify(obj, (_, v) => (v === undefined ? null : v)));
-}
-export function formatSubfeatures(obj, depth, parse, currentDepth = 0, returnObj = {}) {
-    if (depth <= currentDepth) {
-        return;
+export function getStrandStr(strand) {
+    return strand === -1 ? '(-)' : strand === 1 ? '(+)' : '';
+}
+// JSON only serializes null, not undefined; feature fields are hidden by a
+// formatDetails callback returning undefined (jexl can't produce null), so when
+// persisting we round-trip undefined to null to keep the field hidden after
+// reload (detail components filter with `!= null`). see config guide.
+export const nullReplacer = (_, v) => v === undefined ? null : v;
+// `depth` is how many levels of subfeature the `formatDetails.subfeatures`
+// callback runs on, counted from the clicked feature. The caller resolves it
+// across the session and track tiers and passes 0 when neither declares one, so
+// a config with no formatDetails schema formats nothing rather than every level
+export function formatSubfeatures(obj, depth, parse, currentDepth = 0) {
+    if (currentDepth < depth) {
+        for (const sub of obj.subfeatures ?? []) {
+            formatSubfeatures(sub, depth, parse, currentDepth + 1);
+            parse(sub);
+        }
     }
-    obj.subfeatures?.map(sub => {
-        formatSubfeatures(sub, depth, parse, currentDepth + 1, returnObj);
-        parse(sub);
-    });
 }

package/esm/CorePlugin.js

@@ -1,23 +1,28 @@
 import { lazy } from 'react';
-import { configSchema, stateModelFactory } from "./BaseFeatureWidget/index.js";
-import Plugin from "./Plugin.js";
-import CytobandAdapterF from "./data_adapters/CytobandAdapter/index.js";
-import WidgetType from "./pluggableElementTypes/WidgetType.js";
-import * as coreRpcMethods from "./rpc/coreRpcMethods.js";
+import { configSchema, stateModelFactory } from './BaseFeatureWidget/index.js';
+import Plugin from './Plugin.js';
+import CytobandAdapterF from './data_adapters/CytobandAdapter/index.js';
+import WidgetType from './pluggableElementTypes/WidgetType.js';
+import * as coreRpcMethods from './rpc/coreRpcMethods.js';
+import { installFormatGuessers } from './util/formatGuessers.js';
+// the core plugin, which registers types that ALL JBrowse applications are
+// expected to need.
 export default class CorePlugin extends Plugin {
     name = 'CorePlugin';
     install(pluginManager) {
+        // register all our core rpc methods
         for (const RpcMethod of Object.values(coreRpcMethods)) {
             pluginManager.addRpcMethod(() => new RpcMethod(pluginManager));
         }
         CytobandAdapterF(pluginManager);
+        installFormatGuessers(pluginManager);
         pluginManager.addWidgetType(() => {
             return new WidgetType({
                 name: 'BaseFeatureWidget',
                 heading: 'Feature details',
                 configSchema,
                 stateModel: stateModelFactory(pluginManager),
-                ReactComponent: lazy(() => import("./BaseFeatureWidget/BaseFeatureDetail/index.js")),
+                ReactComponent: lazy(() => import('./BaseFeatureWidget/BaseFeatureDetail/index.js')),
             });
         });
     }

package/esm/PhasedScheduler.d.ts

@@ -1,7 +1,9 @@
+type Callback = () => void;
 export default class PhasedScheduler<PhaseName extends string> {
-    phaseCallbacks: Map<PhaseName, Function[]>;
+    phaseCallbacks: Map<PhaseName, Callback[]>;
     phaseOrder: PhaseName[];
     constructor(...phaseOrder: PhaseName[]);
-    add(phase: PhaseName, callback: Function): void;
+    add(phase: PhaseName, callback: Callback): void;
     run(): void;
 }
+export {};

package/esm/PhasedScheduler.js

@@ -1,3 +1,5 @@
+// helper class that keeps groups of callbacks that are then run in a specified
+// order by group
 export default class PhasedScheduler {
     phaseCallbacks = new Map();
     phaseOrder = [];
@@ -16,10 +18,24 @@ export default class PhasedScheduler {
         phaseCallbacks.push(callback);
     }
     run() {
+        const errors = [];
         for (const phaseName of this.phaseOrder) {
-            for (const callback of this.phaseCallbacks.get(phaseName) || []) {
-                callback();
+            for (const callback of this.phaseCallbacks.get(phaseName) ?? []) {
+                try {
+                    callback();
+                }
+                catch (e) {
+                    errors.push(e);
+                }
             }
         }
+        this.phaseCallbacks.clear();
+        if (errors.length) {
+            // AggregateError's message names none of its causes, and plenty of
+            // surfaces print only `${error}` (the desktop start-screen snackbar, a
+            // console log), so a bare summary loses which plugin actually failed.
+            // formatErrorStack walks .errors for the full stacks.
+            throw new AggregateError(errors, `Errors during pluggable element creation: ${errors.map(e => `${e}`).join('; ')}`);
+        }
     }
 }

package/esm/Plugin.d.ts

@@ -1,13 +1,18 @@
 import type PluginManager from './PluginManager.ts';
 import type { AnyConfigurationSchemaType } from './configuration/index.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * base class for a JBrowse plugin
+ */
 export default abstract class Plugin {
     abstract name: string;
     url?: string;
     version?: string;
     install(_pluginManager: PluginManager): void;
     configure(_pluginManager: PluginManager): void;
+    uninstall(_pluginManager: PluginManager): void;
     configurationSchema?: AnyConfigurationSchemaType;
     configurationSchemaUnnamespaced?: AnyConfigurationSchemaType;
-    rootConfigurationSchema?: (arg: PluginManager) => Record<string, AnyConfigurationSchemaType>;
+    rootConfigurationSchema?: (arg: PluginManager) => Record<string, AnyConfigurationSchemaType | IAnyType>;
 }
 export type PluginConstructor = new (...args: unknown[]) => Plugin;

package/esm/Plugin.js

@@ -1,9 +1,16 @@
+/**
+ * base class for a JBrowse plugin
+ */
 export default class Plugin {
     url;
     version;
     install(_pluginManager) { }
     configure(_pluginManager) { }
+    uninstall(_pluginManager) { }
+    // this is put into configuration.YourPluginName.configSlot
     configurationSchema;
+    // this is put into configuration.configSlot
     configurationSchemaUnnamespaced;
+    // this is spread into the root config, just configSlot
     rootConfigurationSchema;
 }

package/esm/PluginLoader.d.ts

@@ -1,37 +1,5 @@
 import type { PluginConstructor } from './Plugin.ts';
-export interface UMDLocPluginDefinition {
-    umdLoc: {
-        uri: string;
-        baseUri?: string;
-    };
-    name: string;
-}
-export interface UMDUrlPluginDefinition {
-    umdUrl: string;
-    name: string;
-}
-export interface LegacyUMDPluginDefinition {
-    url: string;
-    name: string;
-}
-type UMDPluginDefinition = UMDLocPluginDefinition | UMDUrlPluginDefinition;
-export declare function isUMDPluginDefinition(def: PluginDefinition): def is UMDPluginDefinition | LegacyUMDPluginDefinition;
-export interface ESMLocPluginDefinition {
-    esmLoc: {
-        uri: string;
-        baseUri?: string;
-    };
-}
-export interface ESMUrlPluginDefinition {
-    esmUrl: string;
-}
-export type ESMPluginDefinition = ESMLocPluginDefinition | ESMUrlPluginDefinition;
-export declare function isESMPluginDefinition(def: PluginDefinition): def is ESMPluginDefinition;
-export interface CJSPluginDefinition {
-    cjsUrl: string;
-}
-export declare function isCJSPluginDefinition(def: PluginDefinition): def is CJSPluginDefinition;
-export type PluginDefinition = UMDUrlPluginDefinition | UMDLocPluginDefinition | LegacyUMDPluginDefinition | ESMLocPluginDefinition | ESMUrlPluginDefinition | CJSPluginDefinition;
+import type { CJSPluginDefinition, ESMPluginDefinition, LegacyUMDPluginDefinition, PluginDefinition, UMDPluginDefinition } from './pluginDefinitions.ts';
 export interface PluginRecord {
     plugin: PluginConstructor;
     definition: PluginDefinition;
@@ -39,8 +7,11 @@ export interface PluginRecord {
 export interface LoadedPlugin {
     default: PluginConstructor;
 }
-export declare function pluginDescriptionString(d: PluginDefinition): string;
-export declare function pluginUrl(d: PluginDefinition): any;
+/** A definition that could not be loaded, kept with the reason it failed */
+export interface PluginLoadFailure {
+    definition: PluginDefinition;
+    error: unknown;
+}
 export default class PluginLoader {
     definitions: PluginDefinition[];
     fetchESM?: (url: string) => Promise<LoadedPlugin>;
@@ -55,10 +26,39 @@ export default class PluginLoader {
         default: PluginConstructor;
     }>;
     loadPlugin(def: PluginDefinition, baseUri?: string): Promise<PluginConstructor>;
+    private reExportTarget;
+    /**
+     * Ask for the runtime ABI (`JBrowseExports`) to be published on `target`
+     * before any plugin bundle is evaluated. Records the target; the registry
+     * itself is fetched in `loadSettled` below.
+     *
+     * The split is the point. Every product calls this at startup, synchronously,
+     * whether or not the config names a plugin — so importing the registry here
+     * put it in every host's first paint. It is a ~126 KB gzipped module (see
+     * `ReExports/registry.ts` for why it cannot shrink) that only a runtime plugin
+     * can use, and loading one is async anyway.
+     */
     installGlobalReExports(target: WindowOrWorkerGlobalScope): this;
-    load(baseUri?: string): Promise<{
-        plugin: PluginConstructor;
-        definition: PluginDefinition;
-    }[]>;
+    private publishReExports;
+    /**
+     * Loads every definition and separates the ones that worked from the ones
+     * that didn't, instead of failing the batch on the first error.
+     *
+     * A remote config names its plugins at urls nobody re-checks — a store path
+     * that stops being republished, a bundle that needs a newer host than the one
+     * reading the config — and `load`'s all-or-nothing contract turns any of that
+     * into a dead app rather than a missing feature. That is the widest blast
+     * radius left in config loading: an unknown track/adapter/display type is
+     * already tolerated (the track is simply not usable), so the plugin url was
+     * the only field in a config that could still take a whole session down.
+     *
+     * Callers that can degrade (the apps) use this and report the failures;
+     * callers that cannot (the RPC worker, where a half-loaded plugin set would
+     * fail renders with a much worse message) keep using `load`.
+     */
+    loadSettled(baseUri?: string): Promise<{
+        records: PluginRecord[];
+        failures: PluginLoadFailure[];
+    }>;
+    load(baseUri?: string): Promise<PluginRecord[]>;
 }
-export {};