@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/pluginDefinitions.js

@@ -0,0 +1,220 @@
+/**
+ * What a plugin definition is, and everything that can be answered by looking
+ * at one — its url, its name, whether two describe the same plugin.
+ *
+ * Kept apart from PluginLoader, which pulls in ReExports (effectively all of
+ * core) to be able to run a plugin. Inspecting a definition must not cost that:
+ * the plugin store resolves definitions and would otherwise import core's
+ * config layer back into itself.
+ */
+export function isUMDPluginDefinition(def) {
+    return 'umdUrl' in def || 'url' in def || 'umdLoc' in def;
+}
+export function isESMPluginDefinition(def) {
+    return 'esmUrl' in def || 'esmLoc' in def;
+}
+export function isCJSPluginDefinition(def) {
+    return 'cjsUrl' in def;
+}
+/**
+ * Whether a definition names a store entry to resolve. Deliberately not part of
+ * the CJS/ESM/UMD trio `assertSingleKind` counts: those are loaders, and a ref
+ * is not one. A ref names *which plugin*, and pairing it with a url is the
+ * supported migration shape rather than the two-loaders ambiguity that guard
+ * exists to refuse.
+ */
+export function isStorePluginDefinition(def) {
+    return 'storePlugin' in def && typeof def.storePlugin === 'string';
+}
+/** The store entry a definition names, resolved or not. */
+export function storePluginName(def) {
+    return isStorePluginDefinition(def) ? def.storePlugin : undefined;
+}
+// Plugins that used to ship as external config `plugins[]` entries but are now
+// bundled into the jbrowse-web/desktop core build. Remote configs on jbrowse.org
+// still list them, so we drop those entries before loading: core already
+// registers the same elements (and wins, since core plugins register first), and
+// skipping the external copy avoids a redundant network fetch plus a flurry of
+// "already registered" console warnings. Matched on the config-level `name`
+// (the external plugin's UMD-global name, e.g. "MafViewer"/"GWAS"), not the core
+// class name — so this runs AFTER `resolveStorePluginRefs`, which is where a
+// store ref acquires the name to match on. Run it before, and a config naming a
+// vendored plugin by package slips through and installs a second copy beside
+// core's. Apply only in products whose core bundle actually vendors these —
+// not globally — so CLI indexing, @jbrowse/img, and react-circular (which don't
+// bundle them) still load the external plugin. Also drives the plugin store,
+// which hides these so a user can't install a colliding second copy
+// (`installablePlugins`, util/pluginStore.ts).
+export const vendoredPluginNames = new Set(['MafViewer', 'GWAS']);
+/**
+ * Desktop's half of the same list — a plugin one product bundles and another does
+ * not, which the shared set above cannot express.
+ *
+ * Blat is in Desktop's corePlugins but deliberately not Web's: Web is where
+ * cold-load bundle size is paid, and BLAT is niche. So Desktop's bundled copy is
+ * the only one that ships. It is what gives BLAT on a genome the user opened
+ * from their own disk, where no config names any plugin, and it is the copy that
+ * reaches UCSC through the main-process `blatFetch` bridge and the CAPTCHA-solve
+ * window. Web has to load the external entry to have BLAT at all.
+ *
+ * Naming it drops a config's `plugins[]` entry for Blat before Desktop's loader
+ * sees it, so a config that carries one does not install a second copy beside
+ * the bundled one and append its Tools menu items twice. Nothing carries one
+ * today: jb2hubs stamps `sequence.metadata.blatDb`, which names the UCSC db an
+ * assembly is searchable under and says nothing about loading a plugin. The
+ * entry is a guard for the UMD build (`plugins/blat/scripts/build-umd.ts`),
+ * which a config can name and which is how Web would pick BLAT up.
+ *
+ * It lives here beside the shared set rather than in jbrowse-desktop because the
+ * two are read together — a surface consulting one and not the other offers an
+ * install the loader then drops, which is what Desktop's plugin store and global
+ * plugins dialog both did.
+ */
+export const desktopVendoredPluginNames = ['Blat'];
+export function dropVendoredPlugins(defs, alsoVendored = []) {
+    const vendored = new Set([...vendoredPluginNames, ...alsoVendored]);
+    return defs.filter(d => !(isUMDPluginDefinition(d) && vendored.has(d.name)));
+}
+// The two functions below describe a definition by picking the one url it will
+// be loaded from, so both dispatch in loadPlugin's order — CJS, then ESM, then
+// UMD. Keep them in step with it: they are what the plugin trust gate
+// (checkPlugins) reads and what the untrusted-plugin prompt shows, so an order
+// that disagrees with the loader's vets one url and executes another. They once
+// did disagree, and a definition carrying both `umdUrl` and `cjsUrl` was
+// approved on its jbrowse.org umd url while loadPlugin require()d its cjs one.
+// assertSingleKind now rejects such a definition outright; this order is the
+// second half of that guarantee, since the gate runs before the loader does.
+export function pluginDescriptionString(d) {
+    if (isCJSPluginDefinition(d)) {
+        return `CJS plugin ${d.cjsUrl}`;
+    }
+    else if (isESMPluginDefinition(d)) {
+        return `ESM plugin ${'esmUrl' in d ? d.esmUrl : d.esmLoc.uri}`;
+    }
+    else if (isUMDPluginDefinition(d)) {
+        return `UMD plugin ${d.name}`;
+    }
+    else if (isStorePluginDefinition(d)) {
+        // an unresolved ref, which is what a resolution failure is reported on: it
+        // has no url yet, so the store name is the only thing that identifies it
+        return `store plugin ${d.storePlugin}`;
+    }
+    else {
+        return 'unknown plugin';
+    }
+}
+/**
+ * The url a definition loads from, or undefined when it names no loader at all.
+ * Comparisons between definitions go through this rather than `pluginUrl`, whose
+ * 'unknown url' placeholder is display text: two unloadable definitions are not
+ * the same plugin just because neither has a url.
+ */
+export function maybePluginUrl(d) {
+    if (isCJSPluginDefinition(d)) {
+        return d.cjsUrl;
+    }
+    else if (isESMPluginDefinition(d)) {
+        return 'esmUrl' in d ? d.esmUrl : d.esmLoc.uri;
+    }
+    else if (isUMDPluginDefinition(d)) {
+        return 'umdLoc' in d ? d.umdLoc.uri : 'umdUrl' in d ? d.umdUrl : d.url;
+    }
+    else {
+        return undefined;
+    }
+}
+export function pluginUrl(d) {
+    return maybePluginUrl(d) ?? 'unknown url';
+}
+/**
+ * Whether a definition loads from exactly `url` — the question behind "which
+ * definition is this loaded plugin", "is this one in the session's list", "which
+ * entry does an uninstall remove".
+ *
+ * The two undefined guards are the whole point, and both were live as
+ * `pluginUrl(d) === url` comparisons. A definition naming no loader reads back as
+ * the literal `'unknown url'`, so any two of them compared equal: approving one
+ * marked every other unloadable definition trusted, and removing one filtered
+ * every other unloadable one out of the config. And the url side is absent for a
+ * core or global plugin (no install url was recorded), which must match no
+ * definition rather than the first url-less one.
+ */
+export function isPluginUrl(d, url) {
+    const actual = maybePluginUrl(d);
+    return actual !== undefined && actual === url;
+}
+export function pluginName(definition) {
+    return 'name' in definition ? definition.name : undefined;
+}
+export function pluginDefinitionMetadata(definition) {
+    return {
+        name: pluginName(definition),
+        url: pluginUrl(definition),
+    };
+}
+/**
+ * How to name a definition to a person — a crash marker saying what was
+ * loading, a warning listing what a host did not pass in.
+ *
+ * A ref that has not been resolved yet has no url and often no `name`, and
+ * everything here used to fall through to `pluginUrl`'s 'unknown url' for it:
+ * a marker naming nothing, which is the difference between a banner the user
+ * can act on and one that says only that something went wrong.
+ */
+export function pluginLabel(definition) {
+    const name = pluginName(definition) ?? storePluginName(definition);
+    const url = maybePluginUrl(definition);
+    if (name === undefined) {
+        return pluginUrl(definition);
+    }
+    return url === undefined ? name : `${name} (${url})`;
+}
+/**
+ * Whether two definitions describe the same plugin. They can without being
+ * identical — a UMD name+url in a config, an esmUrl in the global list, a store
+ * ref in one and the pinned definition it resolves to in the other — so a
+ * shared store package, a shared name, or a shared url is each enough. All
+ * three are optional (an ESM definition carries no name, an unloadable one no
+ * url, a hand-written one no package), and a missing field never matches: two
+ * definitions are not the same plugin just because neither names one.
+ *
+ * The store name is checked first because it is the only one of the three that
+ * survives resolution intact. A ref and its resolved form share it; they share
+ * no url, and a *bare* ref has no `name` until the manifest supplies one — so
+ * this clause is doing work even though a resolved definition's `storePlugin`
+ * and `name` agree.
+ *
+ * This is the single answer to "is this plugin already installed" — dedupe
+ * across plugin sources, the plugin store's installed-check — so those cannot
+ * drift apart and disagree about what is a duplicate.
+ */
+export function samePlugin(a, b) {
+    const [refA, refB] = [storePluginName(a), storePluginName(b)];
+    const [nameA, nameB] = [pluginName(a), pluginName(b)];
+    const [urlA, urlB] = [maybePluginUrl(a), maybePluginUrl(b)];
+    return ((refA !== undefined && refA === refB) ||
+        (nameA !== undefined && nameA === nameB) ||
+        (urlA !== undefined && urlA === urlB));
+}
+/**
+ * The candidates no definition in `existing` already describes — `dedupePlugins`
+ * across two lists whose first one is already settled, for a source loaded after
+ * another rather than merged with it.
+ */
+export function pluginsNotIn(candidates, existing) {
+    return candidates.filter(c => !existing.some(e => samePlugin(e, c)));
+}
+/**
+ * Drops later definitions that name a plugin an earlier one already did, so the
+ * first source listed wins: a config's own (version-pinned) entry takes
+ * precedence over the same plugin from the user's global list.
+ */
+export function dedupePlugins(plugins) {
+    const kept = [];
+    for (const plugin of plugins) {
+        if (!kept.some(k => samePlugin(k, plugin))) {
+            kept.push(plugin);
+        }
+    }
+    return kept;
+}

package/esm/rpc/BaseRpcDriver.d.ts

@@ -1,40 +1,32 @@
 import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
-export interface WorkerHandle {
-    status?: string;
-    error?: unknown;
-    on?: (channel: string, callback: (message: unknown) => void) => void;
-    off?: (channel: string, callback: (message: unknown) => void) => void;
-    destroy(): void;
-    call(functionName: string, args?: unknown, options?: {
-        statusCallback?(message: string): void;
-        rpcDriverClassName: string;
-    }): Promise<unknown>;
-}
-export interface RpcDriverConstructorArgs {
-    config: AnyConfigurationModel;
-}
-declare class LazyWorker {
-    driver: BaseRpcDriver;
-    workerP?: Promise<WorkerHandle> | undefined;
-    constructor(driver: BaseRpcDriver);
-    getWorker(): Promise<WorkerHandle>;
-}
+import type RpcMethodType from '../pluggableElementTypes/RpcMethodType.ts';
+import type { StatusCallback } from '../util/progress.ts';
+import type { RpcHandles } from './RpcRegistry.ts';
+/**
+ * The method that drops a session's cached adapters, named once because
+ * {@link BaseRpcDriver.freeSession} is the only thing that dispatches it.
+ */
+export declare const CORE_FREE_RESOURCES = "CoreFreeResources";
 export default abstract class BaseRpcDriver {
-    abstract name: string;
-    private lastWorkerAssignment;
-    private workerAssignments;
-    abstract makeWorker(): Promise<WorkerHandle>;
-    private workerPool?;
+    protected pluginManager: PluginManager;
     config: AnyConfigurationModel;
-    constructor(args: RpcDriverConstructorArgs);
-    filterArgs<THING_TYPE>(thing: THING_TYPE, sessionId: string): THING_TYPE;
-    remoteAbort(sessionId: string, functionName: string, stopTokenId: number): Promise<void>;
-    createWorkerPool(): LazyWorker[];
-    getWorkerPool(): LazyWorker[];
-    getWorker(sessionId: string): Promise<WorkerHandle>;
-    call(pluginManager: PluginManager, sessionId: string, functionName: string, args: {
-        statusCallback?: (message: unknown) => void;
-    }, options?: {}): Promise<unknown>;
+    abstract name: string;
+    constructor(pluginManager: PluginManager, config: AnyConfigurationModel);
+    /**
+     * Drop everything this driver holds for a session — the worker-side adapter
+     * cache, and whatever bookkeeping the transport keeps alongside it.
+     *
+     * A driver operation rather than a `call`, because a free has nothing to do on
+     * a transport that never ran this session and must not outlive `destroy`;
+     * routing it through `call` did both. ADR-086.
+     *
+     * The base behavior is the main-thread one: run the method in this realm,
+     * where `dataAdapterCache` lives. `invoke`, not `execute`, for the reason
+     * `MainThreadRpcDriver.transport` uses it.
+     */
+    freeSession(sessionId: string): Promise<void>;
+    destroy(): void;
+    call(sessionId: string, functionName: string, args: Record<string, unknown> & RpcHandles): Promise<unknown>;
+    protected abstract transport(sessionId: string, rpcMethod: RpcMethodType, serializedArgs: Record<string, unknown>, statusCallback: StatusCallback | undefined): Promise<unknown>;
 }
-export {};

package/esm/rpc/BaseRpcDriver.js

@@ -1,116 +1,83 @@
-import { isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { readConfObject } from "../configuration/index.js";
-import { clamp } from "../util/index.js";
-function isCloneable(thing) {
-    return !(typeof thing === 'function') && !(thing instanceof Error);
-}
-function detectHardwareConcurrency() {
-    const mainThread = typeof window !== 'undefined';
-    const canDetect = mainThread && 'hardwareConcurrency' in window.navigator;
-    return mainThread && canDetect ? window.navigator.hardwareConcurrency : 1;
-}
-class LazyWorker {
-    driver;
-    workerP;
-    constructor(driver) {
-        this.driver = driver;
-    }
-    async getWorker() {
-        if (!this.workerP) {
-            this.workerP = this.driver.makeWorker().catch((e) => {
-                this.workerP = undefined;
-                throw e;
-            });
-        }
-        return this.workerP;
-    }
-}
+import { isStopToken, withStopTokenCheck } from '../util/stopToken.js';
+/**
+ * The method that drops a session's cached adapters, named once because
+ * {@link BaseRpcDriver.freeSession} is the only thing that dispatches it.
+ */
+export const CORE_FREE_RESOURCES = 'CoreFreeResources';
 export default class BaseRpcDriver {
-    lastWorkerAssignment = -1;
-    workerAssignments = new Map();
-    workerPool;
+    pluginManager;
     config;
-    constructor(args) {
-        this.config = args.config;
+    // Held, not threaded. `call`, `transport` and `freeSession` each took one as
+    // their first parameter and `RpcManager` passed the same object to all of
+    // them on every RPC — a driver is built by the manager that owns it, so it
+    // can just have one. Holding it is also what lets `Core-extendWorker` fire
+    // where a worker boots rather than on the dispatch path. ADR-086.
+    constructor(pluginManager, config) {
+        this.pluginManager = pluginManager;
+        this.config = config;
     }
-    filterArgs(thing, sessionId) {
-        if (thing === null || thing === undefined) {
-            return thing;
-        }
-        const type = typeof thing;
-        if (type === 'string' || type === 'number' || type === 'boolean') {
-            return thing;
-        }
-        if (type !== 'object') {
-            return undefined;
-        }
-        if (Array.isArray(thing)) {
-            return thing
-                .filter(thing => isCloneable(thing))
-                .map(t => this.filterArgs(t, sessionId));
-        }
-        else if (isStateTreeNode(thing) && !isAlive(thing)) {
-            throw new Error('dead state tree node passed to RPC call');
-        }
-        else if (thing instanceof File) {
-            return thing;
-        }
-        else {
-            return Object.fromEntries(Object.entries(thing)
-                .filter(e => isCloneable(e[1]))
-                .map(([k, v]) => [k, this.filterArgs(v, sessionId)]));
-        }
-    }
-    async remoteAbort(sessionId, functionName, stopTokenId) {
-        const worker = await this.getWorker(sessionId);
-        await worker.call(functionName, { stopTokenId }, { rpcDriverClassName: this.name });
-    }
-    createWorkerPool() {
-        const hardwareConcurrency = detectHardwareConcurrency();
-        const workerCount = readConfObject(this.config, 'workerCount') ||
-            clamp(1, Math.max(1, hardwareConcurrency - 1), 5);
-        const workers = [];
-        for (let i = 0; i < workerCount; i++) {
-            workers.push(new LazyWorker(this));
-        }
-        return workers;
+    /**
+     * Drop everything this driver holds for a session — the worker-side adapter
+     * cache, and whatever bookkeeping the transport keeps alongside it.
+     *
+     * A driver operation rather than a `call`, because a free has nothing to do on
+     * a transport that never ran this session and must not outlive `destroy`;
+     * routing it through `call` did both. ADR-086.
+     *
+     * The base behavior is the main-thread one: run the method in this realm,
+     * where `dataAdapterCache` lives. `invoke`, not `execute`, for the reason
+     * `MainThreadRpcDriver.transport` uses it.
+     */
+    async freeSession(sessionId) {
+        await this.pluginManager
+            .getRpcMethodType(CORE_FREE_RESOURCES)
+            .invoke({ sessionId });
     }
-    getWorkerPool() {
-        if (!this.workerPool) {
-            const res = this.createWorkerPool();
-            this.workerPool = res;
-            return res;
-        }
-        return this.workerPool;
-    }
-    async getWorker(sessionId) {
-        const workers = this.getWorkerPool();
-        let workerNumber = this.workerAssignments.get(sessionId);
-        if (workerNumber === undefined) {
-            const workerAssignment = (this.lastWorkerAssignment + 1) % workers.length;
-            this.workerAssignments.set(sessionId, workerAssignment);
-            this.lastWorkerAssignment = workerAssignment;
-            workerNumber = workerAssignment;
-        }
-        return workers[workerNumber].getWorker();
-    }
-    async call(pluginManager, sessionId, functionName, args, options = {}) {
+    destroy() { }
+    async call(sessionId, functionName, args) {
         if (!sessionId) {
             throw new TypeError('sessionId is required');
         }
-        const unextendedWorker = await this.getWorker(sessionId);
-        const worker = pluginManager.evaluateExtensionPoint('Core-extendWorker', unextendedWorker);
-        const rpcMethod = pluginManager.getRpcMethodType(functionName);
-        if (!rpcMethod) {
-            throw new Error(`unknown RPC method ${functionName}`);
-        }
-        const serializedArgs = await rpcMethod.serializeArguments(args, this.name);
-        const filteredAndSerializedArgs = this.filterArgs(serializedArgs, sessionId);
-        const call = await worker.call(functionName, filteredAndSerializedArgs, {
-            statusCallback: args.statusCallback,
-            rpcDriverClassName: this.name,
-            ...options,
-        });
-        return rpcMethod.deserializeReturn(call, args, this.name);
+        // An RPC method is addressed by string, so a removed or renamed one is not
+        // a type error anywhere — it fails here. It fails WELL: `TypeRecord.get`
+        // throws naming the method and listing what is registered, which is the
+        // "which plugin is missing" answer. No `undefined` check belongs here; one
+        // was added and lint called it dead, correctly.
+        const rpcMethod = this.pluginManager.getRpcMethodType(functionName);
+        // statusCallback is an out-of-band progress handle, not data: each transport
+        // wires up its own channel for it, so it must not reach the serialized
+        // payload. Everything that does must be structured-cloneable; the worker
+        // postMessage clones it and throws on anything that isn't, surfacing bad data
+        // at the boundary instead of silently dropping it.
+        //
+        // Stripped on the way OUT rather than on the way in, so `serializeArguments`
+        // can see it. That is not cosmetic: serialization is where the refName map
+        // is resolved, and resolving one downloads the adapter's index (and for an
+        // in-memory adapter, the whole file). Destructuring the callback off first
+        // left that download with nothing to report through — `loadRefNameMap`
+        // forwards a `statusCallback` for exactly this and, for every RPC, was
+        // handed undefined. The wire payload is identical either way.
+        //
+        // Serialization is the one long await here, and it is wrapped rather than
+        // fenced by hand-placed checks so the check on the FAR side comes with the
+        // near one — that is the whole point of `withStopTokenCheck`, and the far
+        // one is what was missing. A call whose token was already stopped has
+        // nothing to deliver to, so refuse it rather than serializing args, waking a
+        // worker and racing a stop notification against the call it means to cancel;
+        // and a stop landing DURING serialization had nowhere to be seen at all,
+        // because the broadcast it fires reaches only *booted* workers and on a
+        // driver's first call `LazyWorker.workerP` is undefined until `transport`
+        // reaches `getWorker`. The worker never learned the token was stopped and
+        // ground the fetch to completion. SharedArrayBuffer tokens see the stop
+        // through shared memory regardless; this is the string-token path, which is
+        // every deployment we ship — `stopToken.ts`, "Which path runs where".
+        //
+        // Callers already treat an abort as the ordinary outcome of a superseded
+        // fetch.
+        const stopToken = isStopToken(args.stopToken) ? args.stopToken : undefined;
+        const { statusCallback } = args;
+        const { statusCallback: _outOfBand, ...serializedArgs } = await withStopTokenCheck(stopToken, () => rpcMethod.serializeArguments(args));
+        const result = await this.transport(sessionId, rpcMethod, serializedArgs, statusCallback);
+        return rpcMethod.deserializeReturn(result, args);
     }
 }

package/esm/rpc/MainThreadRpcDriver.d.ts

@@ -1,14 +1,13 @@
 import BaseRpcDriver from './BaseRpcDriver.ts';
-import type { RpcDriverConstructorArgs } from './BaseRpcDriver.ts';
-import type PluginManager from '../PluginManager.ts';
-declare class DummyHandle {
-    destroy(): void;
-    call(_functionName: string, _filteredArgs?: Record<string, unknown>, _options?: {}): Promise<unknown>;
-}
+import type RpcMethodType from '../pluggableElementTypes/RpcMethodType.ts';
+import type { StatusCallback } from '../util/progress.ts';
+/**
+ * RPC driver that runs RPC functions in-band on the main thread. It owns no
+ * worker pool, so `destroy` stays the BaseRpcDriver no-op and `freeSession`
+ * stays that class's in-realm free — the adapter cache this driver fills is the
+ * main thread's own.
+ */
 export default class MainThreadRpcDriver extends BaseRpcDriver {
     name: string;
-    makeWorker: () => Promise<DummyHandle>;
-    constructor(args: RpcDriverConstructorArgs);
-    call(pm: PluginManager, sessionId: string, funcName: string, args: Record<string, unknown>): Promise<unknown>;
+    protected transport(_sessionId: string, rpcMethod: RpcMethodType, serializedArgs: Record<string, unknown>, statusCallback: StatusCallback | undefined): Promise<unknown>;
 }
-export {};

package/esm/rpc/MainThreadRpcDriver.js

@@ -1,33 +1,22 @@
-import BaseRpcDriver from "./BaseRpcDriver.js";
-class DummyHandle {
-    destroy() { }
-    async call(_functionName, _filteredArgs, _options = {}) {
-        return undefined;
-    }
-}
+import BaseRpcDriver from './BaseRpcDriver.js';
+/**
+ * RPC driver that runs RPC functions in-band on the main thread. It owns no
+ * worker pool, so `destroy` stays the BaseRpcDriver no-op and `freeSession`
+ * stays that class's in-realm free — the adapter cache this driver fills is the
+ * main thread's own.
+ */
 export default class MainThreadRpcDriver extends BaseRpcDriver {
     name = 'MainThreadRpcDriver';
-    makeWorker;
-    constructor(args) {
-        super(args);
-        this.makeWorker = async () => new DummyHandle();
-    }
-    async call(pm, sessionId, funcName, args) {
-        if (!sessionId) {
-            throw new TypeError('sessionId is required');
-        }
-        const rpcMethod = pm.getRpcMethodType(funcName);
-        if (!rpcMethod) {
-            throw new Error(`unknown RPC method ${funcName}`);
-        }
-        if (rpcMethod.supportsDirectExecution()) {
-            const result = await rpcMethod.executeDirect(args);
-            if (result !== undefined) {
-                return result;
-            }
-        }
-        const serializedArgs = await rpcMethod.serializeArguments(args, this.name);
-        const result = await rpcMethod.execute(serializedArgs, this.name);
-        return rpcMethod.deserializeReturn(result, args, this.name);
+    async transport(_sessionId, rpcMethod, serializedArgs, statusCallback) {
+        // re-attach the out-of-band statusCallback that BaseRpcDriver.call split off,
+        // mirroring how the worker re-wires it on the far side of postMessage —
+        // including the case where there is none, which `wrapForRpc` answers by
+        // adding no key at all. Spreading `statusCallback: undefined` in would leave
+        // the two drivers handing `execute` bags that differ by a key, which is the
+        // kind of difference nothing tests and something eventually reads.
+        //
+        // `invoke`, not `execute` — it is the entry point that deserializes the
+        // arguments first, and the worker binds the same one
+        return rpcMethod.invoke(statusCallback ? { ...serializedArgs, statusCallback } : serializedArgs);
     }
 }

package/esm/rpc/RpcClient.d.ts

@@ -0,0 +1,38 @@
+import type { ErrorObject } from './serializeError/index.ts';
+type Listener = (arg: unknown) => void;
+interface RpcMessageData {
+    uid: string;
+    libRpc?: true;
+    error?: string | ErrorObject;
+    eventName?: string;
+    data?: unknown;
+}
+interface PendingCall {
+    resolve: (data: unknown) => void;
+    reject: (error: Error) => void;
+}
+export default class RpcClient {
+    worker: Worker;
+    pending: Map<string, PendingCall>;
+    private events;
+    private counter;
+    constructor(worker: Worker);
+    on(event: string, listener: Listener): this;
+    off(event: string, listener: Listener): this;
+    emit(event: string, data: unknown): this;
+    protected handler(e: MessageEvent<RpcMessageData>): void;
+    destroy(): void;
+    private rejectAllPending;
+    protected catch(e: ErrorEvent): void;
+    protected reject(uid: string, error: string | ErrorObject): void;
+    protected resolve(uid: string, data: unknown): void;
+    /**
+     * Tell this worker that a stop token has been stopped, so the calls running
+     * there see it at their next await boundary and drop their in-flight reads.
+     * Fire-and-forget: it settles no pending call, and a worker holding nothing
+     * under that id ignores it.
+     */
+    notifyStopToken(id: string): void;
+    call(method: string, data: unknown): Promise<unknown>;
+}
+export {};