@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/rpc/RpcRegistry.d.ts

@@ -0,0 +1,298 @@
+import type { FeatureDensity } from '../data_adapters/BaseAdapter/featureDensity.ts';
+import type { CoreGetEncodedLayersArgs, EncodedLayersResult } from '../util/markEncodingTypes.ts';
+import type { StatusCallback } from '../util/progress.ts';
+import type { UnwrapRpcResult } from '../util/rpc.ts';
+import type { Feature, SimpleFeatureSerialized } from '../util/simpleFeature.ts';
+import type { NoAssemblyRegion } from '../util/types/data.ts';
+import type { RpcResult } from './RpcServer.ts';
+import type { ByteEstimateScope, RegionTooLargeResult } from './byteBudget.ts';
+export interface RegionLike {
+    refName: string;
+    start: number;
+    end: number;
+    assemblyName: string;
+}
+export interface RpcRegistry {
+    CoreGetRefNames: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+            assemblyName?: string;
+            haplotypes?: string[];
+        };
+        return: string[];
+    };
+    CoreGetRegions: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+        };
+        return: NoAssemblyRegion[];
+    };
+    CoreGetSequence: {
+        args: {
+            region: RegionLike;
+            adapterConfig: Record<string, unknown>;
+        };
+        return: string | undefined;
+    };
+    CoreGetFeatures: {
+        args: {
+            regions: RegionLike[];
+            adapterConfig: Record<string, unknown>;
+            opts?: Record<string, unknown>;
+        };
+        return: Feature[];
+        wire: SimpleFeatureSerialized[];
+    };
+    CoreGetEncodedLayers: {
+        args: CoreGetEncodedLayersArgs;
+        return: EncodedLayersResult | RegionTooLargeResult;
+        transferables: EncodedLayersResult;
+    };
+    CoreGetEncodedFeature: {
+        args: Omit<CoreGetEncodedLayersArgs, 'byteLimit'> & {
+            layer: number;
+            featureIndex: number;
+        };
+        return: SimpleFeatureSerialized | undefined;
+    };
+    CoreGetRegionByteEstimate: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+            regions: RegionLike[];
+            scope: ByteEstimateScope;
+            headers?: Record<string, string>;
+        };
+        return: number | undefined;
+    };
+    CoreGetFeatureDensity: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+            regions: RegionLike[];
+            bpPerPx: number;
+            headers?: Record<string, string>;
+        };
+        return: FeatureDensity[] | undefined;
+    };
+    CoreGetInfo: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+            haplotypes?: string[];
+            assemblyName?: string;
+        };
+        return: unknown;
+    };
+    CoreGetMetadata: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+        };
+        return: unknown;
+    };
+    CoreGetExportData: {
+        args: {
+            regions: RegionLike[];
+            adapterConfig: Record<string, unknown>;
+            formatType: string;
+            opts?: Record<string, unknown>;
+        };
+        return: string | undefined;
+    };
+    CoreFreeResources: {
+        args: Record<string, unknown>;
+        return: void;
+    };
+    CoreLoadAdapterCode: {
+        args: {
+            adapterTypes: string[];
+        };
+        return: void;
+    };
+}
+export type RpcMethodName = keyof RpcRegistry;
+export type RpcArgs<M extends RpcMethodName> = RpcRegistry[M]['args'];
+export type RpcReturn<M extends RpcMethodName> = RpcRegistry[M]['return'];
+/**
+ * The caller's handles on an operation: how to stop it, and where it reports.
+ *
+ * Deliberately NOT part of any method's `args`. They are properties of the
+ * call, not of the payload — every method can be cancelled and every method can
+ * report — so they are part of {@link RpcCallArgs} instead, accepted for every
+ * method whatever its entry says. A registry entry that declares them is stating
+ * something it does not get to decide.
+ *
+ * They used to be per-entry, and the cost was not the 82 repeated lines: it was
+ * that omitting them made a method silently uncancellable and silent, with the
+ * call site still type-checking (an `...opts` spread suppresses the
+ * excess-property check). `CoreGetExportData` shipped that way.
+ *
+ * A `type`, not an `interface`, and that is load-bearing rather than style. An
+ * interface gets no implicit index signature, and an intersection containing one
+ * inherits the lack — so `RpcExecuteArgs<M>` would stop being assignable to the
+ * `Record<string, unknown>` that adapter options are typed as. Handing the whole
+ * args bag to the adapter is how most methods forward these two without naming
+ * them (`getRefNames(deserializedArgs)`), so an interface here breaks exactly
+ * the pattern the type exists to support.
+ */
+export type RpcHandles = {
+    signal?: AbortSignal;
+    statusCallback?: StatusCallback;
+};
+export type RpcSession = {
+    sessionId: string;
+};
+export type RpcReference = {
+    sequenceAdapter?: Record<string, unknown>;
+};
+export type RpcCallContext = RpcSession & RpcHandles;
+/**
+ * What {@link RpcExecuteArgs} and {@link RpcWireReturn} resolve to for a method
+ * name that was written out but has no registry entry: a shape nothing
+ * satisfies, so the miss is a compile error naming the method rather than
+ * silence.
+ *
+ * The silence was the problem. Both derivations are conditionals over `keyof
+ * RpcRegistry`, and a name that misses falls out the bottom — where `unknown`
+ * used to be. So `RpcMethodType<'GetFeatureDetails'>` type-checked with an
+ * `execute` free to take and return anything at all. `GetFeatureDetails` is the
+ * *class* name; the registry key beside it is `GetPileupFeatureDetails`, and
+ * both classes called `GetFeatureDetails` (alignments, canvas) register under a
+ * name their class does not carry — so the wrong guess is the natural one, and
+ * an opt-in that silently opts you back out is worse than none, because it
+ * reads as checked.
+ *
+ * Only for a name written out. The bare default `string` is the escape hatch
+ * documented on {@link RpcMethodType} and still resolves to `unknown`;
+ * `string extends M` is what tells the two apart.
+ */
+export interface NotInRpcRegistry<M extends string> {
+    __rpcRegistryError: `no RpcRegistry entry for '${M}'`;
+}
+/**
+ * What a registered method's `execute` actually receives: its declared args,
+ * plus the session it is pinned to, the handles the driver merged in and the
+ * reference renaming added.
+ *
+ * Derived rather than hand-written, for the reason {@link RpcWireReturn} is:
+ * the return type has been checked against the registry for a while and the
+ * args have not, which is the whole reason the two could drift. A method
+ * parameterized with its own name (`RpcMethodType<'CoreGetSequence'>`) gets
+ * both ends checked.
+ */
+export type RpcExecuteArgs<M extends string> = M extends RpcMethodName ? RpcArgs<M & RpcMethodName> & RpcCallContext & RpcReference : string extends M ? unknown : NotInRpcRegistry<M>;
+/**
+ * What a CALLER passes to `rpcManager.call`: the method's own data, plus the
+ * {@link RpcHandles} every method takes. No {@link RpcSession} — that one is
+ * the call's first parameter, not part of the bag a caller builds.
+ *
+ * Exported and used by everything that types a `call` — `RpcManager` itself and
+ * the structural `RpcMethodCaller` the clustering helpers take — because there
+ * were three hand-written copies of this expression and the third one silently
+ * lagged the other two the moment the handles moved.
+ *
+ * A written-out name with no entry lands on {@link NotInRpcRegistry}; it used to
+ * fall through to `Record<string, unknown>`, so a mistyped name accepted any
+ * args and failed at runtime in the worker. Bare `string` is still the hatch for
+ * a caller dispatching on a variable.
+ */
+export type RpcCallArgs<M extends string> = M extends RpcMethodName ? RpcArgs<M & RpcMethodName> & RpcHandles : string extends M ? Record<string, unknown> & RpcHandles : NotInRpcRegistry<M>;
+/**
+ * What a registered method's `execute` resolves to. An RpcMethodType
+ * parameterized with its own name (`RpcMethodType<'CoreGetRegions'>`) gets its
+ * executor checked against this, so a registry entry can't drift from what the
+ * worker actually sends back. `string` (the default) resolves to `unknown`,
+ * leaving unparameterized methods unconstrained; a name that is not a key
+ * resolves to NotInRpcRegistry, which nothing satisfies.
+ *
+ * `RpcReturn` is what the CALLER gets, this is what went over, and fifteen
+ * entries differ in one of two ways: the return is wrapped in `rpcResult` so
+ * postMessage can transfer its buffers, or `deserializeReturn` rebuilds it
+ * (features travel serialized and arrive as `SimpleFeature`s). An entry says
+ * which, beside the `return` it has to be read against:
+ *
+ * - **`transferables: true`** — the whole return is wrapped. Ten entries.
+ * - **`transferables: T`** — only the `T` arm of a union return is, because only
+ *   that arm owns any buffers; the canvas gates wrap their data half and not
+ *   their region-too-large half. Two entries.
+ * - **`wire: T`** — the return is not what went over at all, and
+ *   `deserializeReturn` is what closes the gap. Three entries.
+ *
+ * The first two are FACTS, not types, so the wire shape is derived from the
+ * `return` and the two cannot come apart. The gates restated theirs until the
+ * fact got an argument — and a restatement of a union some other file owns is
+ * the kind that drifts, since editing `RenderFeatureDataResult` was not visibly
+ * editing this. Only `wire:` restates now, which is why
+ * {@link _NoRedundantWireInRegistry} fails compilation on one the derivation
+ * could have produced: two spellings of "the wire differs" is how the field got
+ * two meanings the first time.
+ *
+ * All of it was a second type parameter on the class until recently, which is a
+ * copy of the registry rather than a reference to it — `RpcResult<
+ * WiggleDataResult[]> | number` on RenderWiggleData type-checked clean while
+ * callers went on receiving `WiggleDataResult[]`.
+ */
+export type RpcWireReturn<M extends string> = M extends RpcMethodName ? WireOf<RpcRegistry[M & RpcMethodName]> : string extends M ? unknown : NotInRpcRegistry<M>;
+type WireOf<Entry> = Entry extends {
+    wire: infer W;
+} ? W : Entry extends {
+    transferables: true;
+    return: infer R;
+} ? RpcResult<R> : Entry extends {
+    transferables: infer Wrapped;
+    return: infer R;
+} ? RpcResult<Wrapped> | Exclude<R, Wrapped> : Entry extends {
+    return: infer R;
+} ? R : never;
+/**
+ * {@link RpcWireReturn} with the `rpcResult` envelope off: what
+ * {@link unwrapRpcResult} hands a `deserializeReturn` to rebuild the caller's
+ * value from, and — for the majority of methods, which do not override it —
+ * what the caller gets.
+ */
+type RpcUnwrappedWireReturn<M extends string> = UnwrapRpcResult<RpcWireReturn<M>>;
+/**
+ * What the CALLER of a registered method ends up holding: the entry's `return`.
+ *
+ * The counterpart of {@link RpcCallArgs}, and here rather than on `RpcManager`
+ * for the reason that one is: `RpcManager.call` is not the only signature that
+ * has to state it. `RpcMethodType.deserializeReturn` — the code that actually
+ * PRODUCES this value, by rebuilding the wire shape — returned `unknown`, so
+ * the registry's `return` was a claim checked against `execute` (through
+ * {@link RpcWireReturn}) and against nothing at all on the way back out;
+ * `RpcManager.call` then cast to it. Typing the hook with this is what closes
+ * that half, and it closes covariantly, which is the direction that bites.
+ */
+export type RpcCallReturn<M extends string> = M extends RpcMethodName ? RpcReturn<M & RpcMethodName> : string extends M ? unknown : NotInRpcRegistry<M>;
+/**
+ * Registry entries that declare a field belonging to the CALL rather than to
+ * the payload. Should always be `never`; {@link AssertNoCallLevelFields} below
+ * is what makes a non-empty one a compile error naming the entry.
+ *
+ * Checked rather than written down because it went wrong the same way twice: a
+ * caller needs the field on one method, it goes into that method's `args`, and
+ * the other forty can no longer be passed it. The handles went that way
+ * (CoreGetExportData shipped uncancellable), and `sessionId` spread to 22 of 41
+ * entries because `RpcCallArgs` had been subtracting it back off.
+ */
+type EntriesDeclaringCallLevelFields = {
+    [K in RpcMethodName]: Extract<keyof RpcArgs<K>, keyof RpcCallContext> extends never ? never : K;
+}[RpcMethodName];
+type AssertNoCallLevelFields<T extends never> = T;
+export type _NoCallLevelFieldsInRegistry = AssertNoCallLevelFields<EntriesDeclaringCallLevelFields>;
+/**
+ * Entries whose `wire` says nothing `transferables` could not have derived —
+ * the wire unwraps to the declared `return`, so no `deserializeReturn` is
+ * closing any gap and the restatement is only waiting to drift from the type it
+ * copies. Should always be `never`.
+ *
+ * The rule this keeps: `wire:` means "the caller does not receive what the
+ * worker sent, and a `deserializeReturn` rebuilds it". It meant that AND "only
+ * part of the return is wrapped" until the latter became `transferables: T`,
+ * and a field with two meanings is one nobody can read off a single entry.
+ */
+type EntriesWithRedundantWire = {
+    [K in RpcMethodName]: RpcRegistry[K] extends {
+        wire: unknown;
+    } ? RpcUnwrappedWireReturn<K> extends RpcReturn<K> ? K : never : never;
+}[RpcMethodName];
+type AssertNoRedundantWire<T extends never> = T;
+export type _NoRedundantWireInRegistry = AssertNoRedundantWire<EntriesWithRedundantWire>;
+export {};

package/esm/rpc/RpcServer.d.ts

@@ -0,0 +1,43 @@
+import type { ErrorObject } from './serializeError/index.ts';
+export interface RpcResult<T = unknown> {
+    __rpcResult: true;
+    value: T;
+    transferables: Transferable[];
+}
+export declare function rpcResult<T>(value: T, transferables: Transferable[]): RpcResult<T>;
+export declare function rpcResultWithArrayBuffers<T extends object>(value: T): RpcResult<T>;
+type Procedure = (data: unknown) => Promise<unknown>;
+interface RpcMessageData {
+    method: string;
+    uid: string;
+    libRpc?: true;
+    data: unknown;
+    abortable?: boolean;
+    abort?: string;
+}
+export default class RpcServer {
+    protected methods: Record<string, Procedure>;
+    private self;
+    private aborters;
+    constructor(methods: Record<string, Procedure>);
+    handler(e: MessageEvent<RpcMessageData>): void;
+    private post;
+    protected reply(uid: string, response: unknown, method?: string): void;
+    /**
+     * The only frame that must never fail to send, because it is the last one: a
+     * `throw` that throws leaves the call unsettled, and an unsettled call is a
+     * display spinning forever with no error to show. Everything upstream of here
+     * routes a failure into this, including {@link reply}'s own catch, so there is
+     * nothing left to catch it.
+     *
+     * It can fail. `serializeError` copies an error's own-enumerable properties so
+     * custom data survives the boundary, and it only skips the ones that are
+     * *themselves* functions — a property holding an object with a method on it
+     * (an arrow-function class field, an adapter, a `cause` that is a `Response`)
+     * is copied whole and is not structured-cloneable. So fall back to the
+     * message, which by construction is a string.
+     */
+    protected throw(uid: string, error: ErrorObject | string): void;
+    emit(eventName: string, data: unknown, transferables?: Transferable[]): void;
+}
+export {};

package/esm/rpc/RpcServer.js

@@ -0,0 +1,242 @@
+import { isRpcResult } from '../util/rpc.js';
+import { bufferPaths, containerEntries, explainTransferError, } from './explainTransferError.js';
+import { serializeError } from './serializeError/index.js';
+// `self` is a DedicatedWorkerGlobalScope in the worker, but the DOM lib types the
+// ambient `self` as Window (whose postMessage overloads differ), so narrow it to
+// the surface RpcServer uses. Absent entirely under plain node.
+const workerSelf = typeof self === 'undefined' ? undefined : self;
+/**
+ * Under test, report a hand-built transfer list that disagrees with the payload
+ * it describes. Nothing else checks one, and neither direction shows up as a
+ * failure of its own:
+ *
+ * - a field added to the result and forgotten here is silently STRUCTURE-CLONED,
+ *   a copy per fetch of the largest arrays a worker produces;
+ * - an entry naming a buffer the payload does not carry detaches something for
+ *   nobody, and the throw lands on a later call as a `DataCloneError` naming an
+ *   index.
+ *
+ * A check rather than a derivation, which is the whole reason it is safe to
+ * apply to every result at once. Deriving the list would mean transferring
+ * whatever a walk finds, and transferring MOVES: `positionOrder` returned a
+ * module-level empty result, a wider walk swept it in, and every
+ * `hg002_haplotypes_*` figure was unrenderable until it was fixed (2026-08-15).
+ * This reports and transfers nothing.
+ *
+ * Test-only because it walks the payload, which also carries plain data — a
+ * `featureIds` array of half a million strings — and `bufferPaths` was written
+ * for the error path for exactly that reason. `rpcResultWithArrayBuffers`
+ * derives its own list and so cannot disagree with itself; it is checked anyway,
+ * since its walk stops one level down and the deeper one here is what would
+ * catch a producer that nests further.
+ */
+function checkTransferList(value, transferables) {
+    const listed = new Set(transferables.filter(t => t instanceof ArrayBuffer));
+    const carried = bufferPaths(value);
+    const missing = [];
+    for (const [buffer, paths] of carried) {
+        // A SharedArrayBuffer cannot be transferred at all, only cloned, so its
+        // absence from the list is the correct answer rather than an omission.
+        if (buffer instanceof ArrayBuffer && !listed.has(buffer)) {
+            missing.push(paths.join(' = '));
+        }
+    }
+    const stray = [...listed].filter(b => !carried.has(b)).length;
+    if (missing.length > 0 || stray > 0) {
+        const parts = [
+            missing.length > 0
+                ? `not transferred, so structure-cloned: ${missing.join(', ')}`
+                : undefined,
+            stray > 0
+                ? `${stray} transfer-list entr${stray === 1 ? 'y is' : 'ies are'} not in the payload`
+                : undefined,
+        ].filter(p => p !== undefined);
+        throw new Error(`RPC transfer list disagrees with its payload — ${parts.join('; ')}`);
+    }
+}
+export function rpcResult(value, transferables) {
+    if (process.env.NODE_ENV === 'test') {
+        checkTransferList(value, transferables);
+    }
+    return { __rpcResult: true, value, transferables };
+}
+// A buffer postMessage will refuse, and which field it arrived on. `detached` is
+// ES2024 and is what a moved buffer reports; the byteLength fallback is for a
+// runtime without it, where a detached buffer measures 0 under a view that does
+// not.
+//
+// Worth naming rather than letting postMessage throw: its own message is
+// "ArrayBuffer at index N is already detached", and N is a position in a list
+// the reader cannot see. One of those cost a figure a release cycle.
+function detachedFieldName(view, path) {
+    const { buffer } = view;
+    const detached = 'detached' in buffer
+        ? buffer.detached
+        : buffer.byteLength === 0 && view.byteLength > 0;
+    return detached ? path : undefined;
+}
+// rpcResult with transferables auto-derived from the result's TypedArray fields,
+// so a newly-added one is transferred (moved, zero-copy) rather than silently
+// structurally cloned just because a hand-maintained buffer list wasn't
+// extended. Use for any worker RPC whose result is typed arrays (canvas /
+// synteny / dotplot / wiggle packers).
+//
+// Walks one level into plain-object fields, because a packer that groups its
+// arrays (`{ ...featureData, instanceData }`) is otherwise back to maintaining
+// the nested half by hand — which is where the bug this guards against lived.
+//
+// A Map or Set counts as a container, so a matrix keyed by sample name — what
+// the wiggle score matrix and the variant genotype matrix return — derives its
+// list here rather than looping at the call site. Both had to, because
+// `Object.entries` is blank on either.
+export function rpcResultWithArrayBuffers(value) {
+    // A Set because several fields can be views onto one allocation (subarrays of
+    // a shared buffer), and postMessage rejects a transfer list with a duplicate
+    // entry outright. SharedArrayBuffer-backed views are skipped for the same
+    // reason: a SAB can't be transferred, only cloned.
+    const transferables = new Set();
+    const detached = [];
+    function collect(obj, prefix, depth) {
+        for (const [path, field] of containerEntries(obj, prefix)) {
+            if (ArrayBuffer.isView(field)) {
+                if (field.buffer instanceof ArrayBuffer) {
+                    const bad = detachedFieldName(field, path);
+                    if (bad) {
+                        detached.push(bad);
+                    }
+                    transferables.add(field.buffer);
+                }
+            }
+            else if (depth > 0 &&
+                field !== null &&
+                typeof field === 'object' &&
+                !Array.isArray(field)) {
+                collect(field, path, depth - 1);
+            }
+        }
+    }
+    collect(value, '', 1);
+    if (detached.length > 0) {
+        throw new Error(`RPC result carries already-detached buffer(s): ${detached.join(', ')}. ` +
+            'A typed array is being held across calls and re-posted; allocate it per call.');
+    }
+    return rpcResult(value, [...transferables]);
+}
+export default class RpcServer {
+    methods;
+    self;
+    aborters = new Map();
+    constructor(methods) {
+        if (!workerSelf) {
+            throw new Error('RpcServer must be constructed in a worker global scope');
+        }
+        this.methods = methods;
+        this.self = workerSelf;
+        this.self.addEventListener('message', (e) => {
+            this.handler(e);
+        });
+        // A call frame this realm could not deserialize. It carries no uid, so
+        // there is nothing to reply to and the caller's promise is already lost —
+        // all this can do is say so, which beats the silence it replaced.
+        this.self.addEventListener('messageerror', () => {
+            console.error('[Worker RPC] a message could not be deserialized');
+        });
+    }
+    handler(e) {
+        const { libRpc, method, uid, data, abort, abortable } = e.data;
+        if (!libRpc) {
+            return;
+        }
+        if (abort !== undefined) {
+            // Handled ahead of the method lookup: this frame has no method name and
+            // would otherwise land in the unknown method branch with no uid to reply
+            // to. A call that already settled left no controller, so a late abort is
+            // a no-op.
+            this.aborters.get(abort)?.abort();
+            return;
+        }
+        const methodFn = Object.hasOwn(this.methods, method)
+            ? this.methods[method]
+            : undefined;
+        if (methodFn) {
+            const controller = abortable ? new AbortController() : undefined;
+            if (controller) {
+                this.aborters.set(uid, controller);
+            }
+            const args = controller
+                ? { ...data, signal: controller.signal }
+                : data;
+            (async () => methodFn(args))()
+                .then(response => {
+                this.reply(uid, response, method);
+            })
+                .catch((error) => {
+                this.throw(uid, serializeError(error));
+            })
+                .finally(() => {
+                this.aborters.delete(uid);
+            });
+        }
+        else {
+            this.throw(uid, `Unknown RPC method "${method}"`);
+        }
+    }
+    // every outgoing message carries the libRpc tag so the client can tell our
+    // frames apart from unrelated worker traffic
+    post(payload, transferables) {
+        this.self.postMessage({ ...payload, libRpc: true }, transferables);
+    }
+    reply(uid, response, method) {
+        // a renderer may return an rpcResult wrapper carrying transferables for
+        // zero-copy; a plain return travels as data with nothing to transfer
+        const { value, transferables } = isRpcResult(response)
+            ? response
+            : { value: response, transferables: [] };
+        try {
+            this.post({ uid, data: value }, transferables);
+        }
+        catch (e) {
+            // postMessage blames a transfer-list entry by index alone, into a list
+            // assembled by hand here in the worker — so name the method and the field
+            // before the error leaves. The method is not otherwise recoverable: the
+            // throw happens in a `.then`, so the stack is `post`/`reply` and nothing
+            // above them. See explainTransferError; it only runs here.
+            this.throw(uid, serializeError(explainTransferError(e, value, transferables, method)));
+        }
+    }
+    /**
+     * The only frame that must never fail to send, because it is the last one: a
+     * `throw` that throws leaves the call unsettled, and an unsettled call is a
+     * display spinning forever with no error to show. Everything upstream of here
+     * routes a failure into this, including {@link reply}'s own catch, so there is
+     * nothing left to catch it.
+     *
+     * It can fail. `serializeError` copies an error's own-enumerable properties so
+     * custom data survives the boundary, and it only skips the ones that are
+     * *themselves* functions — a property holding an object with a method on it
+     * (an arrow-function class field, an adapter, a `cause` that is a `Response`)
+     * is copied whole and is not structured-cloneable. So fall back to the
+     * message, which by construction is a string.
+     */
+    throw(uid, error) {
+        try {
+            this.post({ uid, error }, []);
+        }
+        catch {
+            const message = typeof error === 'string' ? error : error.message;
+            // Never empty. `new Error()` has an empty message, and the client tells an
+            // error frame from a reply by which key the frame carries — so an empty
+            // one is a rejection the caller cannot read a reason from, and used to be
+            // a frame it read as a reply. Naming the error's own class is the most the
+            // fallback still has to work with.
+            this.post({
+                uid,
+                error: message ||
+                    `${typeof error === 'string' ? 'Error' : (error.name ?? 'Error')} (no message)`,
+            }, []);
+        }
+    }
+    emit(eventName, data, transferables) {
+        this.post({ eventName, data }, transferables ?? []);
+    }
+}