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

package/esm/util/renameRegions.js

@@ -1,5 +1,4 @@
 import { getSnapshot, isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { getSequenceAdapterConfig } from '../assemblyManager/getSequenceAdapterConfig.js';
 // Maps a region's refName to the track adapter's name (via refNameMap), and
 // sets originalRefName to the seq adapter (FASTA) name so that CRAM/BAM
 // adapters can fetch reference sequence correctly.
@@ -27,9 +26,10 @@ import { getSequenceAdapterConfig } from '../assemblyManager/getSequenceAdapterC
 // file being read and the ordinary pass is simply right — MAF's annotation
 // overlay is called that way. Thread a second name only when the two results
 // cannot be joined by the caller: GWAS LD coloring can't, because the r²-to-
-// feature join is per feature and features never cross the boundary, so it
-// resolves a second pass in `serializeArguments` and ships `ldRefName`
-// (`plugins/gwas/src/ManhattanRPC/GetManhattanData.ts`). That and
+// feature join is per feature and features never cross the boundary, so the
+// display resolves the LD file's name before the RPC and hands it to the
+// adapter in `opts.ld.refName`
+// (`plugins/gwas/src/LinearManhattanDisplay/ldJoinResolver.ts`). That and
 // `originalRefName` are the only two, and there is no reason to expect a third:
 // a sub-adapter is normally the same data in another form, named the same way.
 export function renameRegionIfNeeded(refNameMap, region, getSeqAdapterRefName) {
@@ -57,8 +57,7 @@ function isRegionShaped(r) {
         'start' in r &&
         'end' in r);
 }
-export async function renameRegionsIfNeeded(assemblyManager, args) {
-    const { regions = [], adapterConfig } = args;
+function checkRenameArgs(args) {
     if (!args.sessionId) {
         throw new Error('sessionId is required');
     }
@@ -69,61 +68,76 @@ export async function renameRegionsIfNeeded(assemblyManager, args) {
     // `chr5`. The legitimate singular base class (RpcMethodTypeWithRenameRegion)
     // always mirrors `region` into a populated `regions`, so flag only the
     // un-mirrored case and fail loudly instead of returning wrong data.
-    if (regions.length === 0 &&
+    if (!args.regions?.length &&
         isRegionShaped(args.region)) {
         throw new Error('renameRegionsIfNeeded got a singular `region` but no `regions` array; ' +
             'refName renaming applies only to `regions`. Pass `regions: [region]` ' +
             '(or extend RpcMethodTypeWithRenameRegion) so the region is renamed.');
     }
-    // capture assembly names before the await, since MST regions may be dead after
+}
+// What one assembly contributes to a rename, off the loaded assembly: resolved
+// via requireAssembly (which awaits registration and load) so the refName map
+// and getSeqAdapterRefName come from one handle. A synchronous
+// assemblyManager.get() could miss an assembly still registering, leaving
+// originalRefName (CRAM/BAM's reference fetch name) on the canonical name
+// instead of the FASTA's. Require, not wait: a region names an assembly, so
+// failing to resolve it is renaming that cannot be done, not nothing to rename,
+// and an empty map would query un-renamed refNames and draw an empty track
+// with no word about why. Only an unnamed assembly is a legitimate no-op.
+async function assemblyRenameData(assemblyManager, assemblyName, args) {
+    if (!assemblyName) {
+        return undefined;
+    }
+    const assembly = await assemblyManager.requireAssembly(assemblyName);
+    return {
+        refNameMap: await assembly.getRefNameMapForAdapter(args.adapterConfig, args),
+        getSeqAdapterRefName: (r) => assembly.getSeqAdapterRefName(r),
+    };
+}
+function renamed(region, data) {
+    return renameRegionIfNeeded(data?.refNameMap, region, data?.getSeqAdapterRefName);
+}
+/**
+ * Rename for a request about one genome, which is every request but a
+ * comparative one. The call's genome is its regions' genome, and renaming
+ * writes it as the call's `assemblyName`, the one field a call names its
+ * genome in: `RpcMethodType.serializeArguments` turns it into the reference a
+ * BAM/CRAM or scan adapter is built with. A region on another assembly is
+ * refused: a request over a synteny adapter renames with
+ * {@link renameComparativeRegions}.
+ */
+export async function renameRegionsIfNeeded(assemblyManager, args) {
+    checkRenameArgs(args);
+    const { regions = [] } = args;
+    // read before the await, since MST regions may be dead after
+    const assemblyName = regions[0]?.assemblyName;
+    const stray = regions.find(r => r.assemblyName !== assemblyName);
+    if (stray) {
+        throw new Error(`regions on ${assemblyName} and ${stray.assemblyName} in one request: a request is about one genome, and a comparative request (synteny, dotplot) renames with renameComparativeRegions`);
+    }
+    const data = await assemblyRenameData(assemblyManager, assemblyName, args);
+    return {
+        ...args,
+        assemblyName,
+        regions: regions.map(region => renamed(region, data)),
+    };
+}
+/**
+ * Rename for a comparative request (synteny, dotplot, chords), whose regions
+ * sit on two or more assemblies and are each renamed against their own. Such a
+ * request has no genome of its own, so it names none and no reference rides
+ * on it; a synteny adapter reads no reference.
+ */
+export async function renameComparativeRegions(assemblyManager, args) {
+    checkRenameArgs(args);
+    const { regions = [] } = args;
     const assemblyNames = regions.map(r => r.assemblyName);
-    const uniqueAssemblyNames = [...new Set(assemblyNames)];
-    // annotated, because Object.fromEntries over an array whose element type is
-    // not a tuple selects its `any` overload — which left refNameMap and
-    // getSeqAdapterRefName unchecked all the way to renameRegionIfNeeded
-    const assemblyData = Object.fromEntries(await Promise.all(uniqueAssemblyNames.map(async (name) => {
-        // resolve the assembly once via requireAssembly (which awaits both
-        // registration and load) and derive the refName map AND
-        // getSeqAdapterRefName from this single loaded handle. A synchronous
-        // assemblyManager.get() here could miss an assembly still being
-        // registered, leaving getSeqAdapterRefName undefined so
-        // originalRefName (used by CRAM/BAM to fetch reference bases) falls
-        // back to the canonical name instead of the FASTA name.
-        //
-        // require, not wait: a region names an assembly, so failing to
-        // resolve it is not "nothing to rename", it is renaming that cannot
-        // be done. Substituting an empty map leaves the adapter querying
-        // un-renamed refNames, which finds nothing and draws an empty track
-        // with no indication that the assembly is what is missing. Only an
-        // unnamed assembly is a legitimate no-op.
-        const assembly = name
-            ? await assemblyManager.requireAssembly(name)
-            : undefined;
-        return [
-            name,
-            {
-                refNameMap: assembly
-                    ? await assembly.getRefNameMapForAdapter(adapterConfig, args)
-                    : {},
-                getSeqAdapterRefName: assembly
-                    ? (r) => assembly.getSeqAdapterRefName(r)
-                    : undefined,
-                sequenceAdapter: getSequenceAdapterConfig(assembly),
-            },
-        ];
-    })));
+    const data = new Map(await Promise.all([...new Set(assemblyNames)].map(async (name) => [
+        name,
+        await assemblyRenameData(assemblyManager, name, args),
+    ])));
     return {
         ...args,
-        // Supplied here, not by each caller: this is the one place that has already
-        // resolved the assembly a fetch is against, and it is the same handle
-        // `originalRefName` is a name into. Every caller that passed its own wrote
-        // these same two lines, and the three that forgot — `CoreGetExportData`,
-        // `BreakpointGetFeatures`, `fetchTrackData` — failed silently, saved only by
-        // whichever call happened to prime the adapter instance first.
-        sequenceAdapter: assemblyData[assemblyNames[0]]?.sequenceAdapter,
-        regions: regions.map((region, i) => {
-            const data = assemblyData[assemblyNames[i]];
-            return renameRegionIfNeeded(data?.refNameMap, region, data?.getSeqAdapterRefName);
-        }),
+        regions: regions.map((region, i) => renamed(region, data.get(assemblyNames[i]))),
     };
 }

package/esm/util/renderToStaticMarkup.js

@@ -7,6 +7,18 @@ import { createRoot } from 'react-dom/client';
 // reason to pull react/react-dom/@emotion, and the barrel is imported by
 // worker-side adapter code that never renders.
 //
+// It is not part of the plugin ABI either, and that removal did break two
+// published bundles before anyone noticed: react-msaview's SVG export read it
+// off `@jbrowse/core/util`, and jbrowse-plugin-msaview and -tview bundle
+// react-msaview. Resolved on their side -- react-msaview owns its own copy now
+// (packages/lib/src/renderToStaticMarkup.ts there) -- because a rendering
+// library asking its host for a renderer was the coupling worth removing, and
+// because react-dom is a host external for a plugin anyway, so it costs them a
+// few hundred bytes rather than a duplicate react. Re-exporting it from the
+// barrel would also stub `@jbrowse/core/util` in the worker, since the
+// generator stubs a module whose graph reaches react-dom; workerModules.test.ts
+// fails on that.
+//
 // https://react.dev/reference/react-dom/server/renderToString#removing-rendertostring-from-the-client-code
 export function renderToStaticMarkup(node) {
     const div = document.createElement('div');
@@ -15,13 +27,23 @@ export function renderToStaticMarkup(node) {
     // jbrowse-img) loads @emotion/react before `document` exists, so its default
     // cache context is null — provide one explicitly here.
     const cache = createCache({ key: 'css' });
-    const root = createRoot(div);
+    // a client root reports a render error and unmounts, so without this the
+    // export is an empty string its caller writes as a file
+    const uncaught = [];
+    const root = createRoot(div, {
+        onUncaughtError: error => {
+            uncaught.push(error);
+        },
+    });
     let html;
     try {
         // eslint-disable-next-line @eslint-react/dom-no-flush-sync
         flushSync(() => {
             root.render(React.createElement(CacheProvider, { value: cache }, node));
         });
+        if (uncaught.length > 0) {
+            throw uncaught[0];
+        }
         html = div.innerHTML;
     }
     finally {
@@ -34,17 +56,5 @@ export function renderToStaticMarkup(node) {
         // once the markup is a string, which no longer depends on the DOM.
         root.unmount();
     }
-    // SVG 1.1 presentation attributes (`fill`, `stroke`) take a <color>, which
-    // does not include rgba() — alpha belongs in a separate fill-opacity /
-    // stroke-opacity. Illustrator and older Inkscape drop an element whose fill
-    // they cannot parse, so the alpha is stripped rather than left to break the
-    // whole shape. It is *dropped*, not converted, so a translucent color exports
-    // fully opaque: components that need transparency to survive set a separate
-    // opacity attribute instead (`CrossHatches`, `MultiWiggleOverlayLines`).
-    //
-    // Rewriting `fill="rgba(r,g,b,a)"` into `fill="rgb(r,g,b)" fill-opacity="a"`
-    // would preserve the appearance and let those two drop their workarounds, but
-    // it changes the pixels of every export carrying an rgba color, so it needs a
-    // visual pass before the snapshots are regenerated.
-    return html.replaceAll(/\brgba\((.+?),[^,]+?\)/g, 'rgb($1)');
+    return html;
 }

package/esm/util/rxjs.d.ts

@@ -1,17 +1,32 @@
 import { Observable } from 'rxjs';
-import type { StopToken } from './stopToken.ts';
 import type { Observer } from 'rxjs';
 /**
  * Wrapper for rxjs Observable.create with improved error handling and aborting
  * support.
  *
- * A `stopToken` errors the subscriber with an abort error the moment the token
- * is stopped, rather than waiting for `func` to finish work whose result is
- * already discarded. The fetch paths filter abort errors out (`isAbortException`)
- * so a cancel does not surface as a track error. It cannot interrupt `func`
- * itself — a body doing long synchronous work still needs its own
- * `checkStopToken` ticks — but it does stop delivery downstream.
+ * A `signal` errors the subscriber with an abort error the moment it aborts,
+ * rather than waiting for `func` to finish work whose result is already
+ * discarded. The fetch paths filter abort errors out (`isAbortException`) so a
+ * cancel does not surface as a track error. It cannot interrupt `func` itself
+ * — a body doing long synchronous work still needs its own `checkAbortSignal`
+ * ticks — but it does stop delivery downstream.
  *
  * @param func - observer function, could be async
  */
-export declare function ObservableCreate<T>(func: (arg: Observer<T>) => void | Promise<void>, stopToken?: StopToken): Observable<T>;
+export declare function ObservableCreate<T>(func: (arg: Observer<T>) => void | Promise<void>, signal?: AbortSignal): 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

@@ -1,30 +1,28 @@
 import { Observable } from 'rxjs';
-import { stopTokenSignal } from './stopToken.js';
 /**
  * Wrapper for rxjs Observable.create with improved error handling and aborting
  * support.
  *
- * A `stopToken` errors the subscriber with an abort error the moment the token
- * is stopped, rather than waiting for `func` to finish work whose result is
- * already discarded. The fetch paths filter abort errors out (`isAbortException`)
- * so a cancel does not surface as a track error. It cannot interrupt `func`
- * itself — a body doing long synchronous work still needs its own
- * `checkStopToken` ticks — but it does stop delivery downstream.
+ * A `signal` errors the subscriber with an abort error the moment it aborts,
+ * rather than waiting for `func` to finish work whose result is already
+ * discarded. The fetch paths filter abort errors out (`isAbortException`) so a
+ * cancel does not surface as a track error. It cannot interrupt `func` itself
+ * — a body doing long synchronous work still needs its own `checkAbortSignal`
+ * ticks — but it does stop delivery downstream.
  *
  * @param func - observer function, could be async
  */
-export function ObservableCreate(func, stopToken) {
+export function ObservableCreate(func, signal) {
     return new Observable((observer) => {
-        const { signal, dispose } = stopTokenSignal(stopToken);
         const stop = () => {
-            observer.error(signal.reason);
+            observer.error(signal?.reason);
         };
-        if (signal.aborted) {
-            // stopped before subscribe: no 'abort' event is coming
+        if (signal?.aborted) {
+            // aborted before subscribe: no 'abort' event is coming
             stop();
         }
         else {
-            signal.addEventListener('abort', stop);
+            signal?.addEventListener('abort', stop);
             try {
                 const ret = func(observer);
                 if (ret?.catch) {
@@ -38,8 +36,56 @@ export function ObservableCreate(func, stopToken) {
             }
         }
         return () => {
-            signal.removeEventListener('abort', stop);
-            dispose();
+            signal?.removeEventListener('abort', stop);
         };
     });
 }
+/**
+ * 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/samplesTsv.d.ts

@@ -0,0 +1,49 @@
+import type PluginManager from '../PluginManager.ts';
+import type { BaseOptions } from '../data_adapters/BaseAdapter/types.ts';
+import type { FileLocation } from './types/data.ts';
+export type SamplesTsvRow = Record<string, string> & {
+    name: string;
+};
+export interface SamplesTsvResult {
+    sources: SamplesTsvRow[];
+    warnings: string[];
+}
+export declare const samplesTsvAdapterConfigSchemaFields: {
+    /**
+     * #slot
+     */
+    readonly samplesTsvLocation: {
+        readonly type: 'maybeFileLocation';
+        readonly description: "optional tab-separated table of per-sample metadata. It needs a header row, and its first column is the sample name exactly as the adapter spells it: a VCF sample, a MultiWiggle subtrack's name, a MAF species id. Every other column (`population`, `tissue`, ...) becomes an attribute of that sample, which the multi-row displays group, sort, color and tooltip rows by; a MAF adapter reads the `label`, `color` and `assemblyName` columns onto its species rows, over its `samples` entries. The table also narrows the adapter's samples to the ones it lists, and a table naming none of them is an error. An adapter that lists no samples of its own (a MAF track discovering its species from the file) takes the table's rows as its samples";
+    };
+};
+/**
+ * The metadata rows for the samples an adapter names, plus a warning for the
+ * samples the table leaves out, which no row is drawn for. Rows naming samples
+ * the adapter lacks are dropped silently: one project-wide table serving
+ * several tracks is the normal shape. `names` undefined means the adapter lists
+ * no samples of its own, so the rows become the set.
+ *
+ * A table matching none of `names` throws. Falling back to `names` would show
+ * every sample when the config asked for a curated subset, and an empty result
+ * draws a blank track with no banner. The message quotes both sides of the
+ * mismatch, because a prefix is what separates `1000GP_HG00096` from
+ * `HG00096`.
+ *
+ * `fileLabel` names the file in a message; `namesLabel` names where `names`
+ * came from ("the VCF").
+ */
+export declare function parseSamplesTsv(txt: string, names: readonly string[] | undefined, fileLabel: string, namesLabel: string): SamplesTsvResult;
+/**
+ * An adapter's samples merged with its `samplesTsvLocation` table: the bare
+ * `names` when the slot is unset, otherwise {@link parseSamplesTsv}'s rows.
+ * The warnings come back rather than going to `console.warn`, because this runs
+ * in a worker whose console nobody reads.
+ */
+export declare function getSamplesTsvSources({ location, names, namesLabel, pluginManager, opts, }: {
+    location: FileLocation | undefined;
+    names: readonly string[] | undefined;
+    namesLabel: string;
+    pluginManager?: PluginManager;
+    opts?: BaseOptions;
+}): Promise<SamplesTsvResult>;

package/esm/util/samplesTsv.js

@@ -0,0 +1,86 @@
+import { fetchAndMaybeUnzipText } from './fetchAndMaybeUnzip.js';
+import { getFileName } from './getFileName.js';
+import { openLocation } from './io/index.js';
+import { shorten2 } from './stringUtils.js';
+export const samplesTsvAdapterConfigSchemaFields = {
+    /**
+     * #slot
+     */
+    samplesTsvLocation: {
+        type: 'maybeFileLocation',
+        description: "optional tab-separated table of per-sample metadata. It needs a header row, and its first column is the sample name exactly as the adapter spells it: a VCF sample, a MultiWiggle subtrack's name, a MAF species id. Every other column (`population`, `tissue`, ...) becomes an attribute of that sample, which the multi-row displays group, sort, color and tooltip rows by; a MAF adapter reads the `label`, `color` and `assemblyName` columns onto its species rows, over its `samples` entries. The table also narrows the adapter's samples to the ones it lists, and a table naming none of them is an error. An adapter that lists no samples of its own (a MAF track discovering its species from the file) takes the table's rows as its samples",
+    },
+};
+/**
+ * The metadata rows for the samples an adapter names, plus a warning for the
+ * samples the table leaves out, which no row is drawn for. Rows naming samples
+ * the adapter lacks are dropped silently: one project-wide table serving
+ * several tracks is the normal shape. `names` undefined means the adapter lists
+ * no samples of its own, so the rows become the set.
+ *
+ * A table matching none of `names` throws. Falling back to `names` would show
+ * every sample when the config asked for a curated subset, and an empty result
+ * draws a blank track with no banner. The message quotes both sides of the
+ * mismatch, because a prefix is what separates `1000GP_HG00096` from
+ * `HG00096`.
+ *
+ * `fileLabel` names the file in a message; `namesLabel` names where `names`
+ * came from ("the VCF").
+ */
+export function parseSamplesTsv(txt, names, fileLabel, namesLabel) {
+    const lines = txt.split(/\n|\r\n|\r/);
+    const header = lines[0].split('\t');
+    const metadataSet = new Set();
+    const duplicates = new Set();
+    const metadataLines = lines
+        .slice(1)
+        .filter(Boolean)
+        .map(line => {
+        const [name, ...rest] = line.split('\t');
+        return {
+            ...Object.fromEntries(header.slice(1).map((col, idx) => [col, rest[idx] ?? ''])),
+            name: name,
+        };
+    })
+        .filter(row => {
+        if (metadataSet.has(row.name)) {
+            duplicates.add(row.name);
+            return false;
+        }
+        metadataSet.add(row.name);
+        return true;
+    });
+    const warnings = [];
+    if (duplicates.size) {
+        warnings.push(`${duplicates.size} samples appear more than once in the metadata file ${fileLabel}; the first row of each is used: ${shorten2([...duplicates].join(','))}`);
+    }
+    if (!names) {
+        return { sources: metadataLines, warnings };
+    }
+    const nameSet = new Set(names);
+    const namesNotInMetadata = [...nameSet].filter(f => !metadataSet.has(f));
+    const sources = metadataLines.filter(f => nameSet.has(f.name));
+    if (sources.length === 0 && names.length > 0) {
+        const example = metadataLines[0]?.name;
+        throw new Error(example === undefined
+            ? `The samples metadata file ${fileLabel} has a header but no sample rows, so this track has no rows to draw`
+            : `No sample in the metadata file ${fileLabel} matches ${namesLabel}, so this track has no rows to draw: its first column reads "${example}" where ${namesLabel} names "${names[0]}". Check for an added prefix or suffix, or for the sample IDs being in a different column.`);
+    }
+    if (namesNotInMetadata.length) {
+        warnings.push(`${namesNotInMetadata.length} of the ${names.length} samples in ${namesLabel} are not in the metadata file ${fileLabel} (${metadataLines.length} lines) and are not shown: ${shorten2(namesNotInMetadata.join(','))}`);
+    }
+    return { sources, warnings };
+}
+/**
+ * An adapter's samples merged with its `samplesTsvLocation` table: the bare
+ * `names` when the slot is unset, otherwise {@link parseSamplesTsv}'s rows.
+ * The warnings come back rather than going to `console.warn`, because this runs
+ * in a worker whose console nobody reads.
+ */
+export async function getSamplesTsvSources({ location, names, namesLabel, pluginManager, opts, }) {
+    if (!location) {
+        return { sources: (names ?? []).map(name => ({ name })), warnings: [] };
+    }
+    const txt = await fetchAndMaybeUnzipText(openLocation(location, pluginManager), opts, 'Downloading sample metadata');
+    return parseSamplesTsv(txt, names, 'uri' in location ? location.uri : getFileName(location), namesLabel);
+}

package/esm/util/scheduleDetachedDestroy.d.ts

@@ -0,0 +1,18 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export declare function scheduleDetachedDestroy(node: IAnyStateTreeNode): void;

package/esm/util/scheduleDetachedDestroy.js

@@ -0,0 +1,24 @@
+import { destroy, isAlive } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export function scheduleDetachedDestroy(node) {
+    setTimeout(() => {
+        if (isAlive(node)) {
+            destroy(node);
+        }
+    }, 0);
+}

package/esm/util/scrollLatch.d.ts

@@ -1,4 +1,5 @@
 export declare function createScrollLatch(timeoutMs?: number): {
     scroll(e: WheelEvent, cur: number, delta: number, max: number, min?: number): number | null;
+    holds(e: WheelEvent): boolean;
     reset(): void;
 };

package/esm/util/scrollLatch.js

@@ -47,6 +47,14 @@ export function createScrollLatch(timeoutMs = LATCH_TIMEOUT_MS) {
             }
             return null;
         },
+        // Whether this panel already owns the gesture `e` belongs to, i.e. it has
+        // scrolled during a run of events this one continues. Callers ask before
+        // declining an event on their own rules: a gesture that has latched keeps
+        // every event it fires, cross-axis momentum included, which is the whole
+        // point of latching.
+        holds(e) {
+            return latched && e.timeStamp - lastEvent < timeoutMs;
+        },
         // Forget the gesture state so the next event is treated as a fresh gesture.
         // Called when the pointer leaves the panel: a gesture the browser has
         // latched to this element must not keep the page suppressed once the cursor

package/esm/util/selectEncodedFeature.d.ts

@@ -0,0 +1,16 @@
+import type { createAbortRotation } from './createAbortRotation.ts';
+import type { CoreGetEncodedLayersArgs } from './markEncodingTypes.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api
+ * Open the feature widget on the feature behind one instance of a
+ * `CoreGetEncodedLayers` answer. A display holds channels, not records, so it
+ * sends `CoreGetEncodedFeature` the request the instance's region came back
+ * under, and the worker answers the entry of `layer`'s list that the
+ * instance's `featureIndex` names: the record as the adapter wrote it, or the
+ * bin or run the steps made. A second click aborts the first.
+ */
+export declare function selectEncodedFeature(self: IStateTreeNode, rotation: ReturnType<typeof createAbortRotation>, args: Omit<CoreGetEncodedLayersArgs, 'byteLimit'> & {
+    layer: number;
+    featureIndex: number;
+}): void;

package/esm/util/selectEncodedFeature.js

@@ -0,0 +1,34 @@
+import { openFeatureWidget } from './openFeatureWidget.js';
+import { getRpcSessionId } from './parentWalk.js';
+import { getRpcHost } from './sessionServices.js';
+import SimpleFeature from './simpleFeature.js';
+import { withFeatureDetails } from './withFeatureDetails.js';
+/**
+ * #api
+ * Open the feature widget on the feature behind one instance of a
+ * `CoreGetEncodedLayers` answer. A display holds channels, not records, so it
+ * sends `CoreGetEncodedFeature` the request the instance's region came back
+ * under, and the worker answers the entry of `layer`'s list that the
+ * instance's `featureIndex` names: the record as the adapter wrote it, or the
+ * bin or run the steps made. A second click aborts the first.
+ */
+export function selectEncodedFeature(self, rotation, args) {
+    const fetch = rotation.begin();
+    void withFeatureDetails(self, async () => {
+        try {
+            const feature = await getRpcHost(self).rpcManager.call(getRpcSessionId(self), 'CoreGetEncodedFeature', {
+                ...args,
+                signal: fetch.signal,
+                statusCallback: fetch.statusCallback,
+            });
+            return feature && fetch.isCurrent()
+                ? new SimpleFeature(feature)
+                : undefined;
+        }
+        finally {
+            fetch.end();
+        }
+    }, feature => {
+        openFeatureWidget(self, feature.toJSON(), { feature });
+    });
+}

package/esm/util/sessionSharing.d.ts

@@ -2,6 +2,9 @@ export declare function b64PadSuffix(b64: string): string;
 /**
  * Decode and inflate a url-safe base64 to a string
  * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ *
+ * A truncated input rejects rather than inflating to a prefix: a link cut short
+ * in transit has to say so, not fail later as a JSON syntax error.
  */
 export declare function fromUrlSafeB64(b64: string): Promise<string>;
 /**
@@ -10,9 +13,9 @@ export declare function fromUrlSafeB64(b64: string): Promise<string>;
  */
 export declare function toUrlSafeB64(str: string): Promise<string>;
 /**
- * The `?session=` value prefixes, named here because this module is what
- * produces them. The decoder half (jbrowse-web's SessionLoader) has its own
- * list covering the two prefixes nothing here writes (`spec-`, `local-`).
+ * The `?session=` value prefixes for a session carried by or behind the link.
+ * The decoder half (jbrowse-web's SessionLoader) has its own list covering
+ * `spec-` and `local-` too.
  */
 export declare const SHARE_PREFIX = "share-";
 export declare const ENCODED_PREFIX = "encoded-";
@@ -25,11 +28,10 @@ export declare const JSON_PREFIX = "json-";
  * alone: web honors an explicit empty string as "resolve relative to the page".
  */
 export declare function shareEndpoint(shareURL: string, path: 'share' | 'load'): string;
-export type SessionShareMode = 'short' | 'long' | 'json';
+export type SessionShareMode = 'short' | 'long';
 export interface EncodedSessionParam {
     sessionParam: string;
     password?: string;
-    plaintext?: string;
 }
 export declare function encodeSessionParam(mode: SessionShareMode, session: unknown, options: {
     shareURL: string;