@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/types/index.js

@@ -1,5 +1,11 @@
 import { isStateTreeNode } from '@jbrowse/mobx-state-tree';
-export * from "./util.js";
+import { isSessionServices } from './services.js';
+export { isSessionServices } from './services.js';
+// The plain-data half of this file's former self, kept re-exported here so
+// `@jbrowse/core/util/types` still offers it. A module that only needs a
+// `Region` or a `FileLocation` imports './data.ts' directly — see the note at
+// the top of that file.
+export { AuthNeededError, isAuthNeededException, isBlobLocation, isFileHandleLocation, isLocalPathLocation, isUriLocation, } from './data.js';
 export function isViewContainer(thing) {
     return (isStateTreeNode(thing) &&
         'removeView' in thing &&
@@ -7,16 +13,79 @@ export function isViewContainer(thing) {
         'views' in thing);
 }
 export function isSessionModel(thing) {
-    return (typeof thing === 'object' &&
-        thing !== null &&
-        'rpcManager' in thing &&
-        'configuration' in thing);
+    return isSessionServices(thing);
 }
 export function isSessionModelWithConfigEditing(t) {
     return isSessionModel(t) && 'editConfiguration' in t;
 }
-export function isSessionWithAddTracks(t) {
-    return (isSessionModel(t) && 'addTrackConf' in t && !t.disableAddTracks);
+export function isSessionWithViewReplacement(t) {
+    return isSessionModel(t) && 'replaceView' in t;
+}
+/**
+ * Whether `view` is a view a launcher can actually offer to swap out — i.e.
+ * whether "Replace current view" would replace anything.
+ *
+ * Both halves are needed. The session must be able to replace a view at all,
+ * and the view must be one of the session's OWN: a launcher resolves its source
+ * with `getContainingView`, which inside a LinearSyntenyView (or a dotplot)
+ * returns the row's inner LGV, and that view occupies no session slot. Replacing
+ * it falls through to `addView`, so the button did what Submit does while saying
+ * otherwise — the launched view appended below the untouched source. Asking this
+ * instead leaves those cases with the one button that tells the truth.
+ */
+export function canReplaceView(session, view) {
+    return (view !== undefined &&
+        isSessionWithViewReplacement(session) &&
+        session.views.includes(view));
+}
+/**
+ * Open a launched view, either in the slot `replacing` occupies or appended.
+ *
+ * The branch every launcher that offers "Replace current view" would otherwise
+ * write for itself, kept in one place with the guard it depends on. A session
+ * that can't replace a view falls back to appending, so a caller passes the
+ * source view unconditionally and never has to ask twice.
+ */
+export function addOrReplaceView({ session, typeName, initialState, replacing, }) {
+    return replacing && isSessionWithViewReplacement(session)
+        ? session.replaceView(replacing, typeName, initialState)
+        : session.addView(typeName, initialState);
+}
+export function isSessionWithPublishTrackConf(t) {
+    return (isSessionModel(t) &&
+        'publishTrackConf' in t &&
+        !('disableAddTracks' in t && t.disableAddTracks));
+}
+export function isSessionWithSessionTracks(t) {
+    return isSessionModel(t) && 'sessionTracks' in t;
+}
+export function isSessionWithAddSessionTrack(t) {
+    return (isSessionModel(t) &&
+        'addSessionTrackConf' in t &&
+        !('disableAddTracks' in t && t.disableAddTracks));
+}
+/**
+ * @deprecated ask `isSessionWithAddSessionTrack` for a track a feature stands
+ * up on the user's behalf, or `isSessionWithPublishTrackConf` in an Add-track
+ * workflow.
+ *
+ * Kept because a prebuilt plugin bundle links it by name off
+ * `JBrowseExports['@jbrowse/core/util']` and cannot be recompiled:
+ * jbrowse-plugin-protein3d 0.8.0 gates its structure-track launch on it
+ * (`(0,ll.isSessionWithAddTracks)(e)?e:void 0`), so dropping the export makes
+ * the call `undefined is not a function` inside the menu builder rather than
+ * failing a build. It answers the session-scoped question now, which is the one
+ * that caller wanted — its launch goes on to `session.addTrackConf`, the
+ * session-scoped alias. `graphgenomeviewer` does not reference either name.
+ *
+ * Nothing in tree may call it; `no-restricted-syntax` says so.
+ */
+export const isSessionWithAddTracks = isSessionWithAddSessionTrack;
+export function isSessionWithAddAssembly(t) {
+    return isSessionModel(t) && typeof t.addSessionAssembly === 'function';
+}
+export function isSessionWithDeleteTrackConf(t) {
+    return isSessionModel(t) && 'deleteTrackConf' in t;
 }
 export function isSessionWithShareURL(thing) {
     return isSessionModel(thing) && 'shareURL' in thing && !!thing.shareURL;
@@ -33,6 +102,9 @@ export function isSessionModelWithConnectionEditing(thing) {
 export function isSessionWithSessionPlugins(thing) {
     return isSessionModel(thing) && 'sessionPlugins' in thing;
 }
+export function isSessionWithPermanentPlugins(thing) {
+    return isSessionModel(thing) && 'permanentPlugins' in thing;
+}
 export function isSelectionContainer(thing) {
     return (typeof thing === 'object' &&
         thing !== null &&
@@ -49,13 +121,19 @@ export function isTrackModel(thing) {
     return (typeof thing === 'object' &&
         thing !== null &&
         'configuration' in thing &&
-        thing.configuration.trackId);
+        typeof thing.configuration === 'object' &&
+        thing.configuration !== null &&
+        'trackId' in thing.configuration &&
+        !!thing.configuration.trackId);
 }
 export function isDisplayModel(thing) {
     return (typeof thing === 'object' &&
         thing !== null &&
         'configuration' in thing &&
-        thing.configuration.displayId);
+        typeof thing.configuration === 'object' &&
+        thing.configuration !== null &&
+        'displayId' in thing.configuration &&
+        !!thing.configuration.displayId);
 }
 export function isTrackViewModel(thing) {
     return (typeof thing === 'object' &&
@@ -80,58 +158,3 @@ export function isAbstractMenuManager(thing) {
         'appendMenu' in thing &&
         'appendToSubMenu' in thing);
 }
-export function isUriLocation(location) {
-    return (typeof location === 'object' &&
-        location !== null &&
-        'uri' in location &&
-        !!location.uri);
-}
-export function isLocalPathLocation(location) {
-    return (typeof location === 'object' &&
-        location !== null &&
-        'localPath' in location &&
-        !!location.localPath);
-}
-export function isBlobLocation(location) {
-    return (typeof location === 'object' &&
-        location !== null &&
-        'blobId' in location &&
-        !!location.blobId);
-}
-export function isFileHandleLocation(location) {
-    return (typeof location === 'object' &&
-        location !== null &&
-        'handleId' in location &&
-        !!location.handleId);
-}
-export class AuthNeededError extends Error {
-    message;
-    url;
-    constructor(message, url) {
-        super(message);
-        this.message = message;
-        this.url = url;
-        this.name = 'AuthNeededError';
-        Object.setPrototypeOf(this, AuthNeededError.prototype);
-    }
-}
-export class RetryError extends Error {
-    message;
-    internetAccountId;
-    constructor(message, internetAccountId) {
-        super(message);
-        this.message = message;
-        this.internetAccountId = internetAccountId;
-        this.name = 'RetryError';
-    }
-}
-export function isAuthNeededException(exception) {
-    return (exception instanceof Error &&
-        (exception.name === 'AuthNeededError' ||
-            exception.url !== undefined));
-}
-export function isRetryException(exception) {
-    return (exception.name === 'RetryError' ||
-        exception.internetAccountId !== undefined);
-}
-export { default as TextSearchManager } from "../../TextSearch/TextSearchManager.js";

package/esm/util/types/isAny.d.ts

@@ -0,0 +1,11 @@
+/**
+ * True only for `any`. `1 & T` collapses to `any` when T is `any`, and
+ * `0 extends any` holds; for any concrete T it is `0 extends 1 & T` → false.
+ *
+ * Useful because `any` is the one type that passes every other check. A model
+ * surface that degrades to it — a generic MST type parameter that failed to
+ * infer, a plugin-supplied `IAnyType` — keeps tsc, jest and lint green while
+ * silently switching off type checking at every call site downstream. Pair it
+ * with product-core's `AssertNotAny` to turn that into a build error.
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;

package/esm/util/types/isAny.js

@@ -0,0 +1 @@
+export {};

package/esm/util/types/mst.d.ts

@@ -6,32 +6,32 @@ export declare const NoAssemblyRegion: import("@jbrowse/mobx-state-tree").IModel
 }, {
     setRefName(newRefName: string): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
-export declare const Region: import("@jbrowse/mobx-state-tree").IModelType<{
+export declare const Region: import("@jbrowse/mobx-state-tree").IModelType<Omit<{
     refName: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     start: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
     end: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
     reversed: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-} & {
+}, "assemblyName"> & {
     assemblyName: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
 }, {
     setRefName(newRefName: string): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export declare const LocalPathLocation: import("@jbrowse/mobx-state-tree").IModelType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"LocalPathLocation">;
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
     localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
 }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export declare const BlobLocation: import("@jbrowse/mobx-state-tree").IModelType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"BlobLocation">;
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
 }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export declare const FileHandleLocation: import("@jbrowse/mobx-state-tree").IModelType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"FileHandleLocation">;
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
 }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export declare const UriLocationRaw: import("@jbrowse/mobx-state-tree").IModelType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"UriLocation">;
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"UriLocation">;
     uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
     internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
@@ -41,7 +41,7 @@ export declare const UriLocationRaw: import("@jbrowse/mobx-state-tree").IModelTy
     }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
 }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export declare const UriLocation: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").IModelType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"UriLocation">;
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"UriLocation">;
     uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
     internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
@@ -58,27 +58,45 @@ export declare const UriLocation: import("@jbrowse/mobx-state-tree").ISnapshotPr
         authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
     }> | undefined;
 }>;
-export declare const FileLocation: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"UriLocation">;
-    uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IModelType<{
-        internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-        authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
-    }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
-}>> | import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"BlobLocation">;
+export interface LegacyFileLocation {
+    locationType?: undefined;
+    uri?: string;
+    localPath?: string;
+    blob?: string;
+    handleId?: string;
+}
+export declare const FileLocation: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "LocalPathLocation";
+    localPath: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "BlobLocation";
+    name: string;
+    blobId: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "FileHandleLocation";
+    name: string;
+    handleId: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "UriLocation";
+    uri: string;
+    baseUri: string | undefined;
+    internetAccountId: string | undefined;
+    internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+        internetAccountType: string;
+        authInfo: any;
+    }> | undefined;
+}>, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
+    localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+}> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}>> | import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"FileHandleLocation">;
+}> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}>> | import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"LocalPathLocation">;
-    localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}>>, {
+}> | {
     locationType: "UriLocation";
     uri: string;
     internetAccountId: string | undefined;
@@ -86,33 +104,19 @@ export declare const FileLocation: import("@jbrowse/mobx-state-tree").ISnapshotP
         internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
     }> | undefined;
-} | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"BlobLocation">;
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"FileHandleLocation">;
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"LocalPathLocation">;
+}, import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
     localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}>, import("@jbrowse/mobx-state-tree").ModelInstanceType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"BlobLocation">;
+}> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}, {}> | import("@jbrowse/mobx-state-tree").ModelInstanceType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"FileHandleLocation">;
+}> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}, {}> | import("@jbrowse/mobx-state-tree").ModelInstanceType<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"LocalPathLocation">;
-    localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-}, {}> | ({
-    locationType: "UriLocation";
-    uri: string;
-} & Partial<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    locationType: import("@jbrowse/mobx-state-tree").ISimpleType<"UriLocation">;
+}> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+    locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"UriLocation">;
     uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
     internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
@@ -120,5 +124,25 @@ export declare const FileLocation: import("@jbrowse/mobx-state-tree").ISnapshotP
         internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
     }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
-}>> & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject)>, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+}>>, LegacyFileLocation | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "LocalPathLocation";
+    localPath: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "BlobLocation";
+    name: string;
+    blobId: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "FileHandleLocation";
+    name: string;
+    handleId: string;
+}> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+    locationType: "UriLocation";
+    uri: string;
+    baseUri: string | undefined;
+    internetAccountId: string | undefined;
+    internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+        internetAccountType: string;
+        authInfo: any;
+    }> | undefined;
+}>, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export { ElementId, createElementId } from './ElementId.ts';

package/esm/util/types/mst.js

@@ -1,4 +1,5 @@
 import { types } from '@jbrowse/mobx-state-tree';
+// #region regionModel
 export const NoAssemblyRegion = types
     .model('NoAssemblyRegion', {
     refName: types.string,
@@ -14,15 +15,19 @@ export const NoAssemblyRegion = types
 export const Region = types.compose('Region', NoAssemblyRegion, types.model({
     assemblyName: types.string,
 }));
+// #endregion
 export const LocalPathLocation = types.model('LocalPathLocation', {
     locationType: types.literal('LocalPathLocation'),
     localPath: types.string,
 });
+// like how blobId is used to get a blob map
 export const BlobLocation = types.model('BlobLocation', {
     locationType: types.literal('BlobLocation'),
     name: types.string,
     blobId: types.string,
 });
+// FileHandleLocation stores a reference to a FileSystemFileHandle via IndexedDB
+// The handleId is used to retrieve the handle from IndexedDB storage
 export const FileHandleLocation = types.model('FileHandleLocation', {
     locationType: types.literal('FileHandleLocation'),
     name: types.string,
@@ -33,6 +38,8 @@ export const UriLocationRaw = types.model('UriLocation', {
     uri: types.string,
     baseUri: types.maybe(types.string),
     internetAccountId: types.maybe(types.string),
+    // auths information (such as tokens) needed for using this resource.
+    // if provided, these must be completely sufficient for using it
     internetAccountPreAuthorization: types.maybe(types.model('InternetAccountPreAuthorization', {
         internetAccountType: types.string,
         authInfo: types.frozen(),
@@ -40,6 +47,7 @@ export const UriLocationRaw = types.model('UriLocation', {
 });
 export const UriLocation = types.snapshotProcessor(UriLocationRaw, {
     postProcessor: snap => {
+        // xref for Omit https://github.com/mobxjs/mobx-state-tree/issues/1524
         const { baseUri, ...rest } = snap;
         if (!baseUri) {
             return rest;
@@ -47,30 +55,27 @@ export const UriLocation = types.snapshotProcessor(UriLocationRaw, {
         return snap;
     },
 });
-export const FileLocation = types.snapshotProcessor(types.union(LocalPathLocation, UriLocation, BlobLocation, FileHandleLocation), {
+const FileLocationUnion = types.union(LocalPathLocation, UriLocation, BlobLocation, FileHandleLocation);
+export const FileLocation = types.snapshotProcessor(FileLocationUnion, {
+    // legacy untagged snapshots are loosely shaped (e.g. a bare `uri` with no
+    // blobId/name for the blob case), so the inferred result can't statically
+    // satisfy the strict union; MST re-validates it against the union at runtime
+    // @ts-expect-error
     preProcessor(snap) {
-        if (!snap) {
-            return undefined;
+        if (snap.locationType) {
+            return snap;
         }
-        const { locationType, ...rest } = snap;
-        if (!locationType) {
-            const { uri, localPath, blob, handleId } = rest;
-            let locationType = '';
-            if (uri !== undefined) {
-                locationType = 'UriLocation';
-            }
-            else if (localPath !== undefined) {
-                locationType = 'LocalPathLocation';
-            }
-            else if (blob !== undefined) {
-                locationType = 'BlobLocation';
-            }
-            else if (handleId !== undefined) {
-                locationType = 'FileHandleLocation';
-            }
-            return { ...rest, locationType };
+        else {
+            const { uri, localPath, blob } = snap;
+            const inferredLocationType = uri !== undefined
+                ? 'UriLocation'
+                : localPath !== undefined
+                    ? 'LocalPathLocation'
+                    : blob !== undefined
+                        ? 'BlobLocation'
+                        : 'FileHandleLocation';
+            return { ...snap, locationType: inferredLocationType };
         }
-        return snap;
     },
 });
-export { ElementId, createElementId } from "./ElementId.js";
+export { ElementId, createElementId } from './ElementId.js';

package/esm/util/types/predicate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * get the type that a predicate asserts.
+ *
+ * Alone in a file rather than beside its four relatives in `./util.ts`, which
+ * names `PluginManager`: the parent-walk primitives are the one part of the MST
+ * helpers that has no application in its type graph, and this is the only thing
+ * they need from here.
+ */
+export type TypeTestedByPredicate<PREDICATE extends (thing: any) => boolean> = PREDICATE extends ((thing: any) => thing is infer TYPE) ? TYPE : never;

package/esm/util/types/predicate.js

@@ -0,0 +1 @@
+export {};

package/esm/util/types/renderingServices.d.ts

@@ -0,0 +1,16 @@
+import type assemblyManager from '../../assemblyManager/index.ts';
+import type { PaletteHost, RpcHost } from './services.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export type AssemblyManager = Instance<ReturnType<typeof assemblyManager>>;
+export interface AssemblyHost {
+    assemblyManager: AssemblyManager;
+    /**
+     * the assemblies this host offers, which is not the same set the manager can
+     * resolve: an assembly reachable through a track's config is not one a picker
+     * should list.
+     */
+    assemblyNames: string[];
+}
+/** what a display needs of its host in order to draw a region */
+export interface RenderingServices extends AssemblyHost, RpcHost, PaletteHost {
+}

package/esm/util/types/renderingServices.js

@@ -0,0 +1 @@
+export {};

package/esm/util/types/services.d.ts

@@ -0,0 +1,55 @@
+import type { RpcCallArgs, RpcCallReturn } from '../../rpc/RpcRegistry.ts';
+import type { JBrowsePalette } from '../../ui/palette.ts';
+import type { SerializableThemeArgs } from '../../ui/theme.ts';
+import type React from 'react';
+/**
+ * The one thing a fetch needs of an RPC manager: the registry-typed call. A
+ * real {@link RpcManager} satisfies it, and so does a host that routes RPCs
+ * somewhere else entirely.
+ */
+export interface RpcCaller {
+    call<M extends string>(sessionId: string, method: M, args: RpcCallArgs<M>): Promise<RpcCallReturn<M>>;
+}
+export interface RpcHost {
+    rpcManager: RpcCaller;
+}
+/**
+ * The colors a renderer draws with. `palette` is plain data — no toolkit, and
+ * serializable, so a worker baking labels reads the same values the React
+ * chrome does. `themeOptions` is what rebuilds it on the far side of an RPC.
+ */
+export interface PaletteHost {
+    palette: JBrowsePalette;
+    themeOptions?: SerializableThemeArgs;
+}
+export type NotificationLevel = 'error' | 'info' | 'warning' | 'success';
+export interface SnackAction {
+    name: React.ReactElement | string;
+    onClick: () => void;
+}
+/** where a display puts a message it cannot draw itself */
+export interface NotificationSink {
+    notify: (message: string, level?: NotificationLevel, action?: SnackAction | SnackAction[]) => void;
+    notifyError: (message: string, error?: unknown, extra?: unknown, action?: SnackAction) => void;
+}
+export type DialogComponentType = React.LazyExoticComponent<React.FC<any>> | React.FC<any>;
+/**
+ * The single member a host has to implement to be somewhere a display can put a
+ * dialog. It is the most-called session member from plugin code (49 sites), and
+ * nearly all of them are a display saying "the user wants to configure
+ * something" — so a host drawing its own UI needs exactly this one name, not a
+ * session. `agent-docs/ideas/lightweight-toolkit.md` §3.
+ */
+export interface DialogHost {
+    DialogComponent?: DialogComponentType;
+    DialogProps: Record<string, unknown> | undefined;
+    queueDialog<T extends DialogComponentType>(callback: (doneCallback: () => void) => [T, React.ComponentProps<T>]): void;
+}
+/** everything a session offers that costs nothing app-shaped to name */
+export interface SessionServices extends RpcHost, PaletteHost, NotificationSink, DialogHost {
+}
+/**
+ * The one runtime test behind both this and `isSessionModel`: they differ only
+ * in how much of the thing they let the caller see.
+ */
+export declare function isSessionServices(thing: unknown): thing is SessionServices;

package/esm/util/types/services.js

@@ -0,0 +1,10 @@
+/**
+ * The one runtime test behind both this and `isSessionModel`: they differ only
+ * in how much of the thing they let the caller see.
+ */
+export function isSessionServices(thing) {
+    return (typeof thing === 'object' &&
+        thing !== null &&
+        'rpcManager' in thing &&
+        'configuration' in thing);
+}

package/esm/util/types/util.d.ts

@@ -1,6 +1,12 @@
-import type React from 'react';
 import type PluginManager from '../../PluginManager.ts';
+import type React from 'react';
+export type { TypeTestedByPredicate } from './predicate.ts';
+/**
+ * Obtain the return type of a constructor function type.
+ * Differs from core Typescript InstanceType in that it returns never if not matched.
+ */
 export type InstanceTypeRestrictive<CONSTRUCTOR extends new (...args: any[]) => any> = CONSTRUCTOR extends new (...args: any[]) => infer CLASS ? CLASS : never;
+/** extracts the class type from a factory function that returns a constructor */
 export type ClassReturnedBy<FACT extends (pm: PluginManager) => any> = InstanceTypeRestrictive<ReturnType<FACT>>;
+/** A react component with any props. Consider using something more specific if possible */
 export type AnyReactComponentType = React.ComponentType<any>;
-export type TypeTestedByPredicate<PREDICATE extends (thing: any) => boolean> = PREDICATE extends (thing: any) => thing is infer TYPE ? TYPE : never;

package/esm/util/unzip.d.ts

@@ -0,0 +1 @@
+export { unzip } from '@gmod/bgzf-filehandle';

package/esm/util/unzip.js

@@ -0,0 +1,6 @@
+// Deliberately its own entry rather than a name on the util barrel:
+// @gmod/bgzf-filehandle declares no `sideEffects`, so webpack cannot tree-shake
+// a re-export of it out of the barrel, and the barrel has ~1090 importers —
+// including eager plugin entries. Re-exporting `unzip` there put bgzf + pako
+// (~180KB) on the startup path of every page load.
+export { unzip } from '@gmod/bgzf-filehandle';

package/esm/util/useEventCallback.d.ts

@@ -0,0 +1 @@
+export declare function useEventCallback<Args extends unknown[], Return>(fn: (...args: Args) => Return): (...args: Args) => Return;

package/esm/util/useEventCallback.js

@@ -0,0 +1,16 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+// Observer-safe replacement for React's useEffectEvent. Returns a stable
+// callback that always invokes the latest `fn`.
+//
+// React's useEffectEvent reads stale state inside mobx-react `observer()`
+// components (its impl swap does not take effect under observer's reactive
+// render), and nearly every JBrowse component is an observer. Here the ref is
+// updated in a layout effect — which runs before paint and before any browser
+// event can fire the stable callback, so it never reads a stale closure.
+export function useEventCallback(fn) {
+    const ref = useRef(fn);
+    useLayoutEffect(() => {
+        ref.current = fn;
+    });
+    return useCallback((...args) => ref.current(...args), []);
+}