@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/pluggableElementTypes/AdapterType.d.ts

@@ -5,21 +5,71 @@ export interface AdapterMetadata {
     category?: string;
     hiddenFromGUI?: boolean;
     description?: string;
+    /**
+     * File names this adapter is a valid reading of, but which the extension
+     * guess does not hand it — either because another adapter claims the same
+     * extension (an all-vs-all PAF looks like any `.paf`) or because no guesser
+     * claims it at all.
+     *
+     * Purely an "Add track" hint: it does not enter
+     * `Core-guessAdapterForLocation`, which stays a single first-match-wins chain,
+     * so it changes nothing about what a file resolves to headlessly, from the
+     * CLI, or in an existing plugin's guesser. What it does is let the form say
+     * the alternative exists at the moment the adapter is chosen, instead of
+     * leaving it to be found in a dropdown of every adapter JBrowse has.
+     *
+     * State the fact, not a preference — every adapter naming a pattern is
+     * offered together, in registration order, with the guess still selected.
+     */
+    alsoReads?: RegExp;
 }
+/** Expand a raw adapter config snapshot (plain JSON) to its canonical form. */
+export type NormalizeSnapshot = (snap: Record<string, unknown>) => Record<string, unknown>;
 export default class AdapterType extends PluggableElementBase {
     getAdapterClass: () => Promise<AnyAdapter>;
     configSchema: AnyConfigurationSchemaType;
     adapterCapabilities: string[];
     adapterMetadata?: AdapterMetadata;
+    private declaredNormalizeSnapshot?;
+    /**
+     * Normalize a raw adapter config snapshot (plain JSON, before MST
+     * instantiation). Adapters that support shorthand notation (e.g. just
+     * `{type, uri}`) expand it to the canonical form so downstream code can read
+     * location keys without knowing each shorthand.
+     *
+     * **Defaults to the config schema's own `preProcessSnapshot`**, which is the
+     * function that already runs when MST builds the config, so an adapter
+     * declaring the shorthand once gets both. It used to be a second, separate
+     * registration, and five in-tree adapters had only the schema half
+     * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
+     * `AllVsAllPAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * because loading such a config from a URL goes through the schema. Only
+     * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
+     * in the embedded products: the shorthand stayed unexpanded, `uri` never
+     * became a location node, and the blob substitution silently found nothing to
+     * substitute.
+     *
+     * Pass one explicitly only to normalize *differently* here than at MST
+     * create, which nothing in tree needs.
+     */
+    get normalizeSnapshot(): NormalizeSnapshot | undefined;
+    /**
+     * The config key holding the adapter's primary file location (e.g.
+     * `'vcfGzLocation'`). Used by import forms to extract the file location from
+     * a track's adapter config.
+     */
+    locationKey?: string;
     constructor(stuff: {
         name: string;
         configSchema: AnyConfigurationSchemaType;
         displayName?: string;
         adapterCapabilities?: string[];
         adapterMetadata?: AdapterMetadata;
+        normalizeSnapshot?: NormalizeSnapshot;
+        locationKey?: string;
     } & ({
-        AdapterClass: AnyAdapter;
-    } | {
         getAdapterClass: () => Promise<AnyAdapter>;
+    } | {
+        AdapterClass: AnyAdapter;
     }));
 }

package/esm/pluggableElementTypes/AdapterType.js

@@ -1,17 +1,56 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import { getConfigurationSchemaMetadata } from '../configuration/schemaRegistry.js';
+import PluggableElementBase from './PluggableElementBase.js';
 export default class AdapterType extends PluggableElementBase {
     getAdapterClass;
     configSchema;
     adapterCapabilities;
     adapterMetadata;
+    declaredNormalizeSnapshot;
+    /**
+     * Normalize a raw adapter config snapshot (plain JSON, before MST
+     * instantiation). Adapters that support shorthand notation (e.g. just
+     * `{type, uri}`) expand it to the canonical form so downstream code can read
+     * location keys without knowing each shorthand.
+     *
+     * **Defaults to the config schema's own `preProcessSnapshot`**, which is the
+     * function that already runs when MST builds the config, so an adapter
+     * declaring the shorthand once gets both. It used to be a second, separate
+     * registration, and five in-tree adapters had only the schema half
+     * (`MafTabixAdapter`, `BgzipMafAdapter`, `BgzipTaffyAdapter`,
+     * `AllVsAllPAFAdapter`, `MCScanBlocksAdapter`) — which reads as working,
+     * because loading such a config from a URL goes through the schema. Only
+     * `normalizeAdapterSnapshots` consults *this*, so what broke was `localFiles`
+     * in the embedded products: the shorthand stayed unexpanded, `uri` never
+     * became a location node, and the blob substitution silently found nothing to
+     * substitute.
+     *
+     * Pass one explicitly only to normalize *differently* here than at MST
+     * create, which nothing in tree needs.
+     */
+    get normalizeSnapshot() {
+        return (this.declaredNormalizeSnapshot ??
+            getConfigurationSchemaMetadata(this.configSchema)?.options
+                .preProcessSnapshot);
+    }
+    /**
+     * The config key holding the adapter's primary file location (e.g.
+     * `'vcfGzLocation'`). Used by import forms to extract the file location from
+     * a track's adapter config.
+     */
+    locationKey;
+    // `AdapterClass` is retained for backward compatibility with third-party
+    // plugins that pass an eager class reference; new code should prefer
+    // `getAdapterClass` for code splitting.
     constructor(stuff) {
         super(stuff);
         this.getAdapterClass =
-            'AdapterClass' in stuff
-                ? async () => stuff.AdapterClass
-                : stuff.getAdapterClass;
+            'getAdapterClass' in stuff
+                ? stuff.getAdapterClass
+                : async () => stuff.AdapterClass;
         this.configSchema = stuff.configSchema;
-        this.adapterCapabilities = stuff.adapterCapabilities || [];
+        this.adapterCapabilities = stuff.adapterCapabilities ?? [];
         this.adapterMetadata = stuff.adapterMetadata;
+        this.declaredNormalizeSnapshot = stuff.normalizeSnapshot;
+        this.locationKey = stuff.locationKey;
     }
 }

package/esm/pluggableElementTypes/AddTrackWorkflowType.d.ts

@@ -1,15 +1,20 @@
-import type React from 'react';
 import PluggableElementBase from './PluggableElementBase.ts';
 import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
+import type React from 'react';
 type BasicComponent = React.ComponentType<{
     model: any;
+    switchWorkflow: (name: string) => void;
 }>;
 type AddTrackWorkflowComponentType = React.LazyExoticComponent<BasicComponent> | BasicComponent;
+export type AddTrackWorkflowCategory = 'general' | 'specialized';
 export default class AddTrackWorkflow extends PluggableElementBase {
     ReactComponent: AddTrackWorkflowComponentType;
+    category: AddTrackWorkflowCategory;
     stateModel: IAnyModelType;
     constructor(stuff: {
         name: string;
+        displayName?: string;
+        category?: AddTrackWorkflowCategory;
         ReactComponent: AddTrackWorkflowComponentType;
         stateModel: IAnyModelType;
     });

package/esm/pluggableElementTypes/AddTrackWorkflowType.js

@@ -1,10 +1,12 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class AddTrackWorkflow extends PluggableElementBase {
     ReactComponent;
+    category;
     stateModel;
     constructor(stuff) {
         super(stuff);
         this.ReactComponent = stuff.ReactComponent;
+        this.category = stuff.category ?? 'specialized';
         this.stateModel = stuff.stateModel;
     }
 }

package/esm/pluggableElementTypes/ConnectionType.d.ts

@@ -5,16 +5,16 @@ import type { IAnyModelType } from '@jbrowse/mobx-state-tree';
 export default class ConnectionType extends PluggableElementBase {
     stateModel: IAnyModelType;
     configSchema: AnyConfigurationSchemaType;
-    description: string;
-    url: string;
+    description?: string;
+    url?: string;
     configEditorComponent?: AnyReactComponentType;
     constructor(stuff: {
         name: string;
         stateModel: IAnyModelType;
         configSchema: AnyConfigurationSchemaType;
-        displayName: string;
-        description: string;
+        displayName?: string;
+        description?: string;
         configEditorComponent?: AnyReactComponentType;
-        url: string;
+        url?: string;
     });
 }

package/esm/pluggableElementTypes/ConnectionType.js

@@ -1,4 +1,4 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class ConnectionType extends PluggableElementBase {
     stateModel;
     configSchema;

package/esm/pluggableElementTypes/DisplayType.d.ts

@@ -6,12 +6,21 @@ export default class DisplayType extends PluggableElementBase {
     stateModel: IAnyModelType;
     configSchema: AnyConfigurationSchemaType;
     ReactComponent: AnyReactComponentType;
+    /**
+     * The track type the display is associated with
+     */
     trackType: string;
     subDisplay?: {
         type: string;
         [key: string]: unknown;
     };
+    /**
+     * The view type the display is associated with
+     */
     viewType: string;
+    /**
+     * Help text describing the display type
+     */
     helpText?: string;
     constructor(stuff: {
         name: string;
@@ -26,5 +35,6 @@ export default class DisplayType extends PluggableElementBase {
         configSchema: AnyConfigurationSchemaType;
         ReactComponent: AnyReactComponentType;
         helpText?: string;
+        aliases?: string[];
     });
 }

package/esm/pluggableElementTypes/DisplayType.js

@@ -1,11 +1,24 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class DisplayType extends PluggableElementBase {
     stateModel;
     configSchema;
     ReactComponent;
+    /**
+     * The track type the display is associated with
+     */
     trackType;
+    /*
+     * Indicates that this display type can be a "sub-display" of another type of
+     * display, e.g. in AlignmentsDisplay, has Pileup and SNPCoverage subDisplays
+     */
     subDisplay;
+    /**
+     * The view type the display is associated with
+     */
     viewType;
+    /**
+     * Help text describing the display type
+     */
     helpText;
     constructor(stuff) {
         super(stuff);

package/esm/pluggableElementTypes/InternetAccountType.js

@@ -1,4 +1,4 @@
-import PluggableElementBase from "./PluggableElementBase.js";
+import PluggableElementBase from './PluggableElementBase.js';
 export default class InternetAccountType extends PluggableElementBase {
     stateModel;
     configSchema;

package/esm/pluggableElementTypes/PluggableElementBase.d.ts

@@ -1,9 +1,22 @@
 export default abstract class PluggableElementBase {
     name: string;
     maybeDisplayName?: string;
+    /**
+     * Older names for this element that should be remapped to it when a session
+     * or config names one. Each entry is a legacy `type` value previously used.
+     *
+     * Lets an element own its renames instead of a central migration file, so a
+     * plugin can be renamed out of tree. A per-element `preProcessSnapshot` hook
+     * then handles any property migrations within the renamed type; for a
+     * migration that rewrites the value of an existing constrained slot (an enum
+     * rename, a type narrow) use `addDisplayConfigMigration` instead — see that
+     * helper for why.
+     */
+    aliases?: string[];
     constructor(args?: {
         name?: string;
         displayName?: string;
+        aliases?: string[];
     });
     get displayName(): string;
 }

package/esm/pluggableElementTypes/PluggableElementBase.js

@@ -1,9 +1,22 @@
 export default class PluggableElementBase {
     name;
     maybeDisplayName;
+    /**
+     * Older names for this element that should be remapped to it when a session
+     * or config names one. Each entry is a legacy `type` value previously used.
+     *
+     * Lets an element own its renames instead of a central migration file, so a
+     * plugin can be renamed out of tree. A per-element `preProcessSnapshot` hook
+     * then handles any property migrations within the renamed type; for a
+     * migration that rewrites the value of an existing constrained slot (an enum
+     * rename, a type narrow) use `addDisplayConfigMigration` instead — see that
+     * helper for why.
+     */
+    aliases;
     constructor(args) {
         this.name = args?.name || 'UNKNOWN';
         this.maybeDisplayName = args?.displayName;
+        this.aliases = args?.aliases;
     }
     get displayName() {
         return this.maybeDisplayName || this.name;

package/esm/pluggableElementTypes/RpcMethodType.d.ts

@@ -1,20 +1,140 @@
 import PluggableElementBase from './PluggableElementBase.ts';
 import type PluginManager from '../PluginManager.ts';
+import type { RpcCallContext, RpcCallReturn, RpcExecuteArgs, RpcSession, RpcWireReturn } from '../rpc/RpcRegistry.ts';
+import type { Region } from '../util/index.ts';
 import type { UriLocation } from '../util/types/index.ts';
 export type RpcMethodConstructor = new (pm: PluginManager) => RpcMethodType;
-export declare function convertFileHandleLocations(obj: unknown, blobMap: Record<string, File>, seen?: WeakSet<object>): void;
-export default abstract class RpcMethodType extends PluggableElementBase {
+export type RenameRegionsArgs = RpcCallContext & {
+    assemblyName?: string;
+    regions?: Region[];
+    adapterConfig: Record<string, unknown>;
+};
+export type RenameRegionArgs = RpcSession & {
+    region: Region;
+    adapterConfig: Record<string, unknown>;
+};
+export declare function convertFileHandleLocations(obj: unknown, blobMap: Record<string, File>): void;
+/**
+ * Base for an RPC method. Parameterize with the method's own registry name —
+ * `class CoreGetRegions extends RpcMethodType<'CoreGetRegions'>` — and `execute`
+ * is then checked against that entry's declared `return` (bare or wrapped in
+ * rpcResult), so the registry stays an assertion about the worker rather than a
+ * hand-maintained guess. Left unparameterized, `execute` resolves to `unknown`
+ * as before; that's the escape hatch, and it should be rare.
+ *
+ * The name is checked twice over, because parameterizing used to be a claim
+ * rather than a fact: it must be a key of the registry (a miss lands on
+ * {@link NotInRpcRegistry} instead of quietly on `unknown`), and it must be the
+ * key this class sets as its {@link name}. Both are compile errors, so the
+ * escape hatch is the only way to end up unchecked, and taking it is visible.
+ *
+ * A method whose worker sends something other than the registry `return` — a
+ * result wrapped in `rpcResult` to hand its buffers to postMessage, or one
+ * `deserializeReturn` rebuilds — says so in the registry entry, beside the
+ * `return` it has to be read against. There is deliberately no second type
+ * parameter for it. As one it was a copy of the registry rather than a
+ * reference to it, and fifteen classes kept the copy in step by hand.
+ *
+ * The name is the ONLY parameter, and that is what makes this shape uniform:
+ * a second one survives only where a base is still GENERIC over its name, since
+ * `RpcWireReturn<MethodName>` is then a conditional TypeScript will not resolve
+ * and the shared body has nothing to check against. Such a base has to pin the
+ * wire return by hand and constrain `MethodName` to keep the pin honest — which
+ * is a mechanism, and the last one that needed it was sharing a three-line
+ * delegation two subclasses could each just write (see `runDiagonalize` in
+ * @jbrowse/synteny-core). Share an RPC body as a FUNCTION, not as a base
+ * generic over the key.
+ *
+ * The way back is {@link deserializeReturn}, checked against the same entry's
+ * `return`.
+ */
+export default abstract class RpcMethodType<MethodName extends string = string> extends PluggableElementBase {
+    /**
+     * The key this method is registered under, and the same one the class is
+     * parameterized with — `pluginManager.getRpcMethodType` looks it up by this
+     * string, so it is what a caller's `rpcManager.call` names.
+     *
+     * Narrowed to `MethodName` because the parameter was otherwise a claim about
+     * a method that nothing checked was this one: `RpcMethodType<'A'>` with
+     * `name = 'B'` type-checked, and then `execute` was checked against B's
+     * registry entry while the worker ran it for A. Not hypothetical here —
+     * `GetPileupFeatureDetails` and `GetCanvasFeatureDetails` are two registry
+     * keys held by two same-bodied classes both called `GetFeatureDetails`.
+     *
+     * A class field initializer is not contextually typed by the base property,
+     * so a parameterized subclass writes `name = 'CoreGetRegions' as const`.
+     * Omitting the `as const` is a compile error on `name`, which is the point:
+     * the tie is either made or reported, never silently absent. Unparameterized
+     * subclasses keep plain `string` and need nothing.
+     */
+    name: MethodName;
     pluginManager: PluginManager;
     constructor(pluginManager: PluginManager);
-    serializeArguments(args: Record<string, unknown>, rpcDriverClassName: string): Promise<Record<string, unknown>>;
-    serializeNewAuthArguments(loc: UriLocation, _rpcDriverClassName: string): Promise<UriLocation>;
-    deserializeArguments<T>(args: T & {
-        blobMap?: Record<string, File>;
-    }, _rpcDriverClassName: string): Promise<T>;
-    abstract execute(serializedArgs: unknown, rpcDriverClassName: string): Promise<unknown>;
-    executeDirect(_args: Record<string, unknown>): Promise<unknown>;
-    supportsDirectExecution(): boolean;
-    serializeReturn(originalReturn: unknown, _args: unknown, _rpcDriverClassName: string): Promise<unknown>;
-    deserializeReturn(serializedReturn: unknown, _args: unknown, _rpcDriverClassName: string): Promise<unknown>;
+    serializeArguments(args: object): Promise<Record<string, unknown>>;
+    protected renameRegions<T extends RenameRegionsArgs>(args: T): Promise<T>;
+    /**
+     * The root model to resolve internet accounts against, but only while it is
+     * still attached to its tree. An RPC's promise can settle after the session it
+     * belongs to is gone — jbrowse-web loading a new session, or a headless
+     * renderer (jbrowse-img) destroying its model once the SVG is out — and
+     * reading `internetAccounts` off a destroyed node logs an MST dead-node
+     * warning for work whose result is already discarded. A torn-down root has no
+     * accounts to consult, so it reads as "none" rather than as an error.
+     */
+    private get authRootModel();
+    serializeNewAuthArguments(loc: UriLocation): Promise<UriLocation>;
+    /**
+     * What both drivers call: deserialize, then `execute`.
+     *
+     * Each `execute` used to open with the deserialize call itself, and eleven
+     * methods across seven plugins had silently drifted off it. `RpcExecuteArgs`
+     * describes the DESERIALIZED shape — an entry declares `filters?:
+     * SerializableFilterChain` where the wire carries a `string[]` — so skipping
+     * it made the declared type false rather than erroring. Here it is true by
+     * construction.
+     */
+    invoke(serializedArgs: RpcExecuteArgs<MethodName>): Promise<RpcWireReturn<MethodName>>;
+    /**
+     * The far side of `serializeArguments`; {@link invoke} calls it. Override to
+     * add to the step, not to call it — and **an override must tolerate running
+     * twice on the same object**, since an external plugin written against the
+     * older contract still calls it from its own `execute`.
+     */
+    deserializeArguments<T>(args: T): Promise<T>;
+    /**
+     * The args are {@link RpcExecuteArgs} rather than `unknown` so that a method
+     * parameterized with its own name has BOTH ends checked against the registry.
+     * The return has been checked for a while; the args were hand-written in each
+     * of 45 subclasses, which is the asymmetry that let them drift — and the drift
+     * is not cosmetic, because the two handles every method receives are the two
+     * an author who did not write them down never forwards.
+     *
+     * `CoreGetExportData` is the worked example: the stop token and status
+     * callback arrived on every call and its `execute` destructured neither, so
+     * the Save-track-data dialog's cancel did nothing and its progress never moved
+     * on the adapter-export branch. Nothing was mistyped — the fields simply were
+     * not in a signature anyone read.
+     */
+    abstract execute(serializedArgs: RpcExecuteArgs<MethodName>): Promise<RpcWireReturn<MethodName>>;
+    /**
+     * The wire shape, rebuilt into what the caller of `rpcManager.call` holds —
+     * the registry entry's `return`. Overridden by the three methods whose two
+     * differ (features travel serialized and arrive as `SimpleFeature`s); for
+     * everyone else the whole job is taking off the `rpcResult` envelope, which
+     * MainThreadRpcDriver needs because nothing stripped it on that path.
+     *
+     * The registry `return` is checked against `execute` on the way in (through
+     * {@link RpcWireReturn}) and this is what checks it on the way back out. It
+     * checks covariantly, so unlike the arguments it cannot be widened past.
+     *
+     * An override calls {@link unwrapRpcResult} rather than `super`, because the
+     * envelope is all it wants and `super` now promises the rebuilt value it is
+     * the one rebuilding. The cast below is the claim that stands for every
+     * method that does NOT override: unwrapped wire is the declared `return`.
+     * True by construction for a `transferables: true` or bare entry, since both
+     * derive their wire from that `return`; an explicit `wire:` restates, so it
+     * is the one that has to override or agree.
+     */
+    deserializeReturn(serializedReturn: RpcWireReturn<MethodName>, _args: unknown): Promise<RpcCallReturn<MethodName>>;
     private augmentLocationObjects;
 }