@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/rpc/RpcClient.js

@@ -0,0 +1,189 @@
+import { makeAbortError } from '../util/aborting.js';
+import { deserializeError } from './serializeError/index.js';
+export default class RpcClient {
+    worker;
+    pending = new Map();
+    destroyed = false;
+    events = new Map();
+    counter = 0;
+    constructor(worker) {
+        this.worker = worker;
+        this.worker.addEventListener('message', e => {
+            this.handler(e);
+        });
+        this.worker.addEventListener('error', e => {
+            this.catch(e);
+        });
+        // A frame this realm could not DESERIALIZE, as opposed to `error`, which is
+        // the worker's script throwing. It carries no uid, so the reply it lost
+        // cannot be identified and settling everything is the only move — the same
+        // one `catch` makes, and better than a display spinning on a promise that
+        // can never settle. The worker itself is left alone: it is still healthy,
+        // and a plugin's own non-libRpc traffic on it can be what failed.
+        this.worker.addEventListener('messageerror', () => {
+            this.rejectAllPending(new Error('an RPC worker message could not be deserialized'));
+        });
+    }
+    on(event, listener) {
+        const listeners = this.events.get(event);
+        if (listeners) {
+            listeners.push(listener);
+        }
+        else {
+            this.events.set(event, [listener]);
+        }
+        return this;
+    }
+    off(event, listener) {
+        const listeners = this.events.get(event);
+        if (listeners) {
+            const idx = listeners.indexOf(listener);
+            if (idx !== -1) {
+                listeners.splice(idx, 1);
+            }
+            // drop the emptied key, not just the listener: every reporting call
+            // mints its own status channel (WebWorkerHandle.call), so a retained
+            // empty array is one dead Map entry per call for the life of the page
+            if (listeners.length === 0) {
+                this.events.delete(event);
+            }
+        }
+        return this;
+    }
+    emit(event, data) {
+        const listeners = this.events.get(event);
+        if (listeners) {
+            // over a copy: a listener that removes itself splices the live array, and
+            // a `for...of` over that skips whichever listener moved down into the
+            // index it just read
+            for (const listener of [...listeners]) {
+                listener(data);
+            }
+        }
+        return this;
+    }
+    handler(e) {
+        const { uid, error, eventName, data, libRpc } = e.data;
+        if (!libRpc) {
+            return;
+        }
+        // three frame kinds share the channel: an error (rejects the call), a
+        // named event (status side-channel), and — the default — a call reply.
+        //
+        // Which KIND the frame is, never whether its payload looks useful. A truthy
+        // test read `error: ''` as a reply and resolved the call with `undefined`,
+        // and an empty message is exactly what `RpcServer.throw`'s last-resort
+        // fallback can produce — so the guard against an unsettleable call turned
+        // one class of failure into a wrong value instead. `resolve(uid, undefined)`
+        // then reaches `deserializeReturn` and the caller reads fields off nothing,
+        // blaming its own display.
+        if (error !== undefined) {
+            this.reject(uid, error);
+        }
+        else if (eventName) {
+            this.emit(eventName, data);
+        }
+        else {
+            this.resolve(uid, data);
+        }
+    }
+    // terminating a worker settles nothing on its own: a pending call's reply can
+    // never arrive, so reject it here instead of leaving the caller's promise (and
+    // everything its continuation holds) unsettled forever
+    destroy() {
+        this.destroyed = true;
+        this.rejectAllPending(new Error('RPC worker was terminated'));
+        this.events.clear();
+    }
+    rejectAllPending(error) {
+        // snapshot before clearing so a synchronous reject handler that schedules
+        // a new call() can't have its entry dropped by the clear()
+        const snapshot = [...this.pending.values()];
+        this.pending.clear();
+        for (const { reject } of snapshot) {
+            reject(error);
+        }
+    }
+    catch(e) {
+        this.rejectAllPending(new Error(e.message));
+        this.emit('error', {
+            message: e.message,
+            lineno: e.lineno,
+            filename: e.filename,
+        });
+    }
+    reject(uid, error) {
+        const p = this.pending.get(uid);
+        if (p) {
+            p.reject(deserializeError(error));
+            this.pending.delete(uid);
+        }
+    }
+    resolve(uid, data) {
+        const p = this.pending.get(uid);
+        if (p) {
+            p.resolve(data);
+            this.pending.delete(uid);
+        }
+    }
+    /**
+     * Abort the call `uid`, so the signal it runs under in the worker aborts.
+     * Fire-and-forget: it settles no pending call, and a worker no longer running
+     * that call ignores it.
+     */
+    abort(uid) {
+        this.worker.postMessage({ abort: uid, libRpc: true });
+    }
+    /**
+     * No transfer list: transferables flow only worker → main, in a reply's
+     * rpcResult wrapper. Transferring an argument would neuter the main thread's
+     * own buffer — this took an option for one and nothing ever passed it.
+     *
+     * With a `signal`, the worker runs the method under a signal of its own and
+     * aborts it when this one aborts. The uid is the call's identity on both
+     * sides, so the abort frame needs nothing else; the listener is attached
+     * before the call frame is posted and removed when the call settles, so an
+     * abort in between reaches a worker still running the call, and one after
+     * reaches nothing.
+     */
+    call(method, data, signal) {
+        const uid = String(++this.counter);
+        return new Promise((resolve, reject) => {
+            if (this.destroyed) {
+                reject(new Error('RPC worker was terminated'));
+                return;
+            }
+            if (signal?.aborted) {
+                reject(makeAbortError());
+                return;
+            }
+            const onAbort = () => {
+                this.abort(uid);
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            const detach = () => {
+                signal?.removeEventListener('abort', onAbort);
+            };
+            this.pending.set(uid, {
+                resolve: value => {
+                    detach();
+                    resolve(value);
+                },
+                reject: error => {
+                    detach();
+                    reject(error);
+                },
+            });
+            try {
+                this.worker.postMessage({ method, uid, data, libRpc: true, abortable: signal !== undefined }, []);
+            }
+            catch (e) {
+                // a non-cloneable payload throws here, which rejects this promise; drop
+                // the entry that is now waiting on a reply the worker never received
+                this.pending.delete(uid);
+                detach();
+                throw e;
+            }
+        });
+    }
+}

package/esm/rpc/RpcManager.d.ts

@@ -1,35 +1,128 @@
-import MainThreadRpcDriver from './MainThreadRpcDriver.ts';
-import WebWorkerRpcDriver from './WebWorkerRpcDriver.ts';
-import type BaseRpcDriver from './BaseRpcDriver.ts';
 import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
-type DriverClass = BaseRpcDriver;
-interface BackendConfigurations {
-    WebWorkerRpcDriver?: Omit<ConstructorParameters<typeof WebWorkerRpcDriver>[0], 'config'>;
-    MainThreadRpcDriver?: Omit<ConstructorParameters<typeof MainThreadRpcDriver>[0], 'config'>;
-    [key: string]: unknown;
+import type BaseRpcDriver from './BaseRpcDriver.ts';
+import type { RpcCallArgs, RpcCallReturn } from './RpcRegistry.ts';
+export interface RpcManagerOptions {
+    makeWorkerInstance?: () => Worker;
+    defaultDriverName?: string;
 }
-export type RpcDriverFactory = (config: AnyConfigurationModel, backendConfig: unknown, pluginManager: PluginManager) => BaseRpcDriver;
 export default class RpcManager {
-    pluginManager: PluginManager;
-    mainConfiguration: AnyConfigurationModel;
-    backendConfigurations: BackendConfigurations;
     static configSchema: import("../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        defaultDriver: {
-            type: string;
-            description: string;
+        readonly defaultDriver: {
+            type: "string";
+        } & {
             defaultValue: string;
         };
-        drivers: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<Record<string, any>>> | undefined, import("@jbrowse/mobx-state-tree").ModelSnapshotType<Record<string, any>>, ({} & Partial<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<Record<string, any>>> & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject) | undefined>>, [undefined]>;
-    }, import("../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
-    driverObjects: Map<string, DriverClass>;
-    driverFactories: Map<string, RpcDriverFactory>;
-    constructor(pluginManager: PluginManager, mainConfiguration: AnyConfigurationModel, backendConfigurations: BackendConfigurations);
-    registerDriverFactory(name: string, factory: RpcDriverFactory): void;
-    getDriver(backendName: string): BaseRpcDriver;
-    getDriverForCall(_sessionId: string, _functionName: string, args: {
-        rpcDriverName?: string;
-    }): Promise<BaseRpcDriver>;
-    call(sessionId: string, functionName: string, args: Record<string, unknown>, opts?: {}): Promise<unknown>;
+        readonly workerCount: {
+            type: "number";
+        } & {
+            defaultValue: number;
+        };
+    }, import("../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
+    private pluginManager;
+    private mainConfiguration;
+    private hostDriverName;
+    private makeWorkerInstance?;
+    private driver?;
+    private destroyed;
+    constructor(pluginManager: PluginManager, mainConfiguration: AnyConfigurationModel, { makeWorkerInstance, defaultDriverName, }?: RpcManagerOptions);
+    /**
+     * Which driver this session runs on: the config's `defaultDriver` if set,
+     * otherwise the host application's default.
+     *
+     * A getter rather than the two fields it replaces, because the diagnostic
+     * surfaces that want to print it — the About widget and the error-stack dialog
+     * — were each re-deriving the resolution from `mainConfiguration` and
+     * `defaultDriverName`, so the rule for where a call goes was written three
+     * times and one copy carried a cast.
+     */
+    get driverName(): string;
+    /**
+     * The driver itself, built once and kept. The config read above is a tracked
+     * MobX read and `call` reaches it synchronously, so resolving per call also
+     * made the RPC configuration a dependency of every autorun that fetches.
+     *
+     * There is no per-call, per-track or per-display override. One existed, and
+     * one call site in the app ever passed it — a tag-value scan in the alignments
+     * plugin — so a track pinned to the main thread had its tag scan run there and
+     * every one of its data fetches go to the worker pool anyway. Routing a single
+     * call somewhere else is only meaningful with a backend that differs in what it
+     * can do, which is the tabled server-side-driver idea; add it back with that,
+     * not before.
+     *
+     * There is no registry of driver factories either: naming a driver means
+     * naming `BaseRpcDriver`, which `@jbrowse/core` has no export path for, so
+     * the two built-ins below are the whole set. ADR-086.
+     */
+    getDriver(): BaseRpcDriver;
+    private makeDriver;
+    /**
+     * `args` carries the method's data and the caller's handles on the operation —
+     * the signal and the status callback. Both handles are always accepted,
+     * for every method, because {@link RpcHandles} is part of `RpcCallArgs` rather
+     * than of any registry entry.
+     *
+     * There is deliberately no second position for either. The handles were
+     * accepted in an `opts` parameter as well, and the two disagreed:
+     * `WebWorkerRpcDriver` honored a `statusCallback` there and
+     * `MainThreadRpcDriver` ignored `opts` entirely, so the same call had a
+     * working progress bar under a worker and a silent one under the driver every
+     * embedded component defaults to. One position.
+     *
+     * The cast on the way out is at the driver boundary, where the method is an
+     * unparameterized {@link RpcMethodType} and `deserializeReturn` is therefore
+     * `unknown`. It is not the only thing holding the return type up: the same
+     * type is what that hook is declared to produce, checked against the registry
+     * at each method that overrides it.
+     */
+    call<M extends string>(sessionId: string, functionName: M, args: RpcCallArgs<M>): Promise<RpcCallReturn<M>>;
+    /**
+     * Drop everything held for a session — the worker-side adapter cache, and the
+     * driver's own bookkeeping for it. Reached from `releaseAdapterSession` when
+     * the last track model holding an `rpcSessionId` goes away.
+     *
+     * A lifecycle operation rather than `call(sessionId, 'CoreFreeResources')`,
+     * so that it neither boots a transport to free a session that never used one
+     * nor outlives {@link destroy}; see {@link BaseRpcDriver.freeSession}.
+     *
+     * Silent on a destroyed manager, because the destroy already freed strictly
+     * more than this would: it terminated the workers the cache lived in.
+     */
+    freeSession(sessionId: string): Promise<void>;
+    /**
+     * Run an RPC thunk, and if it fails because a location needs auth, set up
+     * credentials for the origin and run it exactly once more. The single retry
+     * is structural — there is no loop — so a persistent auth failure surfaces
+     * the error instead of spinning. The retry re-runs serializeArguments, which
+     * now finds the new account and injects pre-authorization (prompting the
+     * user). If auth can't be set up, the original error is rethrown unchanged.
+     */
+    private withAuthRetry;
+    /**
+     * Ensure an ephemeral HTTP-basic internet account exists for a location's
+     * origin so a retried RPC call can authenticate. The account id is derived
+     * from the origin and reused if already present: when a track first loads,
+     * many block RPC calls fail auth near-simultaneously, and a single shared
+     * account collapses them into one credential prompt (BaseInternetAccountModel
+     * memoizes the token via a per-account promise). Returns false when the root
+     * model can't hold accounts or no HTTPBasicInternetAccount type is registered
+     * (authentication plugin not loaded), signaling the caller not to retry.
+     */
+    private ensureAuthForOrigin;
+    /**
+     * Terminate the driver's worker threads. Call when discarding the owning root
+     * model (e.g. switching sessions or reloading after a plugin change) so
+     * orphaned workers don't accumulate across a desktop run.
+     *
+     * **Terminal.** ADR-069 destroys the tree a task after `detach()`, so calls
+     * still arrive in that gap; a later one throws rather than quietly building a
+     * second driver and a second pool that nothing will ever destroy. ADR-086.
+     */
+    destroy(): void;
+    /**
+     * Build the driver and let it start what the first call would wait for — a
+     * web worker's bundle and runtime plugins — while the host is still building
+     * its session.
+     */
+    warmUp(): void;
 }
-export {};

package/esm/rpc/RpcManager.js

@@ -1,63 +1,200 @@
-import MainThreadRpcDriver from "./MainThreadRpcDriver.js";
-import WebWorkerRpcDriver from "./WebWorkerRpcDriver.js";
-import rpcConfigSchema from "./configSchema.js";
-import { readConfObject } from "../configuration/index.js";
+import { readConfObject } from '../configuration/index.js';
+import { getNumberGrouping } from '../util/numericUtils.js';
+import { isAppRootModel, isAuthNeededException } from '../util/types/index.js';
+import MainThreadRpcDriver from './MainThreadRpcDriver.js';
+import WebWorkerRpcDriver from './WebWorkerRpcDriver.js';
+import rpcConfigSchema from './configSchema.js';
 export default class RpcManager {
+    static configSchema = rpcConfigSchema;
     pluginManager;
     mainConfiguration;
-    backendConfigurations;
-    static configSchema = rpcConfigSchema;
-    driverObjects;
-    driverFactories;
-    constructor(pluginManager, mainConfiguration, backendConfigurations) {
+    hostDriverName;
+    makeWorkerInstance;
+    driver;
+    destroyed = false;
+    constructor(pluginManager, mainConfiguration, { makeWorkerInstance, defaultDriverName = 'MainThreadRpcDriver', } = {}) {
         this.pluginManager = pluginManager;
         this.mainConfiguration = mainConfiguration;
-        this.backendConfigurations = backendConfigurations;
-        this.driverObjects = new Map();
-        this.driverFactories = new Map();
-        this.registerDriverFactory('MainThreadRpcDriver', (config, backendConfig) => new MainThreadRpcDriver({
-            ...backendConfig,
-            config,
-        }));
-        this.registerDriverFactory('WebWorkerRpcDriver', (config, backendConfig, pm) => new WebWorkerRpcDriver({
-            ...backendConfig,
-            config,
-        }, {
-            plugins: pm.runtimePluginDefinitions,
-            windowHref: typeof window !== 'undefined' ? window.location.href : '',
-        }));
-    }
-    registerDriverFactory(name, factory) {
-        this.driverFactories.set(name, factory);
-    }
-    getDriver(backendName) {
-        const existingDriver = this.driverObjects.get(backendName);
-        if (existingDriver) {
-            return existingDriver;
-        }
-        const factory = this.driverFactories.get(backendName);
-        if (!factory) {
-            throw new Error(`RPC driver "${backendName}" is not registered`);
-        }
-        const backendConfig = this.backendConfigurations[backendName];
-        if (!backendConfig) {
-            throw new Error(`RPC driver "${backendName}" is missing configuration`);
+        this.hostDriverName = defaultDriverName;
+        this.makeWorkerInstance = makeWorkerInstance;
+    }
+    /**
+     * Which driver this session runs on: the config's `defaultDriver` if set,
+     * otherwise the host application's default.
+     *
+     * A getter rather than the two fields it replaces, because the diagnostic
+     * surfaces that want to print it — the About widget and the error-stack dialog
+     * — were each re-deriving the resolution from `mainConfiguration` and
+     * `defaultDriverName`, so the rule for where a call goes was written three
+     * times and one copy carried a cast.
+     */
+    get driverName() {
+        return (readConfObject(this.mainConfiguration, 'defaultDriver') ||
+            this.hostDriverName);
+    }
+    /**
+     * The driver itself, built once and kept. The config read above is a tracked
+     * MobX read and `call` reaches it synchronously, so resolving per call also
+     * made the RPC configuration a dependency of every autorun that fetches.
+     *
+     * There is no per-call, per-track or per-display override. One existed, and
+     * one call site in the app ever passed it — a tag-value scan in the alignments
+     * plugin — so a track pinned to the main thread had its tag scan run there and
+     * every one of its data fetches go to the worker pool anyway. Routing a single
+     * call somewhere else is only meaningful with a backend that differs in what it
+     * can do, which is the tabled server-side-driver idea; add it back with that,
+     * not before.
+     *
+     * There is no registry of driver factories either: naming a driver means
+     * naming `BaseRpcDriver`, which `@jbrowse/core` has no export path for, so
+     * the two built-ins below are the whole set. ADR-086.
+     */
+    getDriver() {
+        if (this.destroyed) {
+            throw new Error('RpcManager was destroyed');
         }
-        const config = this.mainConfiguration.drivers.get('WebWorkerRpcDriver');
-        const newDriver = factory(config, backendConfig, this.pluginManager);
-        this.driverObjects.set(backendName, newDriver);
-        return newDriver;
+        return (this.driver ??= this.makeDriver(this.driverName));
     }
-    async getDriverForCall(_sessionId, _functionName, args) {
-        const backendName = args.rpcDriverName ||
-            readConfObject(this.mainConfiguration, 'defaultDriver');
-        return this.getDriver(backendName);
+    makeDriver(backendName) {
+        if (backendName === 'MainThreadRpcDriver') {
+            return new MainThreadRpcDriver(this.pluginManager, this.mainConfiguration);
+        }
+        else if (backendName === 'WebWorkerRpcDriver') {
+            const { makeWorkerInstance } = this;
+            if (!makeWorkerInstance) {
+                throw new Error('WebWorkerRpcDriver requested but no makeWorkerInstance was provided');
+            }
+            return new WebWorkerRpcDriver(this.pluginManager, this.mainConfiguration, {
+                makeWorkerInstance,
+                plugins: this.pluginManager.runtimePluginDefinitions,
+                windowHref: typeof window === 'undefined' ? '' : window.location.href,
+                // workers format their own strings (a jexl `mouseover` slot runs
+                // against the full feature worker-side), so they need the display
+                // preference too. Read at driver construction — workers boot lazily and
+                // are not rebooted on a preference change, which is why the preference
+                // asks for a reload.
+                numberGrouping: getNumberGrouping(),
+            });
+        }
+        else {
+            throw new Error(`RPC driver "${backendName}" is not registered`);
+        }
     }
-    async call(sessionId, functionName, args, opts = {}) {
+    /**
+     * `args` carries the method's data and the caller's handles on the operation —
+     * the signal and the status callback. Both handles are always accepted,
+     * for every method, because {@link RpcHandles} is part of `RpcCallArgs` rather
+     * than of any registry entry.
+     *
+     * There is deliberately no second position for either. The handles were
+     * accepted in an `opts` parameter as well, and the two disagreed:
+     * `WebWorkerRpcDriver` honored a `statusCallback` there and
+     * `MainThreadRpcDriver` ignored `opts` entirely, so the same call had a
+     * working progress bar under a worker and a silent one under the driver every
+     * embedded component defaults to. One position.
+     *
+     * The cast on the way out is at the driver boundary, where the method is an
+     * unparameterized {@link RpcMethodType} and `deserializeReturn` is therefore
+     * `unknown`. It is not the only thing holding the return type up: the same
+     * type is what that hook is declared to produce, checked against the registry
+     * at each method that overrides it.
+     */
+    async call(sessionId, functionName, args) {
         if (!sessionId) {
             throw new Error('sessionId is required');
         }
-        const driverForCall = await this.getDriverForCall(sessionId, functionName, args);
-        return driverForCall.call(this.pluginManager, sessionId, functionName, args, opts);
+        const driverForCall = this.getDriver();
+        return (await this.withAuthRetry(() => driverForCall.call(sessionId, functionName, { ...args, sessionId })));
+    }
+    /**
+     * Drop everything held for a session — the worker-side adapter cache, and the
+     * driver's own bookkeeping for it. Reached from `releaseAdapterSession` when
+     * the last track model holding an `rpcSessionId` goes away.
+     *
+     * A lifecycle operation rather than `call(sessionId, 'CoreFreeResources')`,
+     * so that it neither boots a transport to free a session that never used one
+     * nor outlives {@link destroy}; see {@link BaseRpcDriver.freeSession}.
+     *
+     * Silent on a destroyed manager, because the destroy already freed strictly
+     * more than this would: it terminated the workers the cache lived in.
+     */
+    async freeSession(sessionId) {
+        if (!this.destroyed) {
+            await this.getDriver().freeSession(sessionId);
+        }
+    }
+    /**
+     * Run an RPC thunk, and if it fails because a location needs auth, set up
+     * credentials for the origin and run it exactly once more. The single retry
+     * is structural — there is no loop — so a persistent auth failure surfaces
+     * the error instead of spinning. The retry re-runs serializeArguments, which
+     * now finds the new account and injects pre-authorization (prompting the
+     * user). If auth can't be set up, the original error is rethrown unchanged.
+     */
+    async withAuthRetry(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (isAuthNeededException(error) && this.ensureAuthForOrigin(error.url)) {
+                return run();
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Ensure an ephemeral HTTP-basic internet account exists for a location's
+     * origin so a retried RPC call can authenticate. The account id is derived
+     * from the origin and reused if already present: when a track first loads,
+     * many block RPC calls fail auth near-simultaneously, and a single shared
+     * account collapses them into one credential prompt (BaseInternetAccountModel
+     * memoizes the token via a per-account promise). Returns false when the root
+     * model can't hold accounts or no HTTPBasicInternetAccount type is registered
+     * (authentication plugin not loaded), signaling the caller not to retry.
+     */
+    ensureAuthForOrigin(url) {
+        const { rootModel } = this.pluginManager;
+        let ready = false;
+        if (isAppRootModel(rootModel)) {
+            try {
+                const internetAccountId = `HTTPBasicInternetAccount-${new URL(url).origin}`;
+                const hasExisting = rootModel.internetAccounts.some(account => account.internetAccountId === internetAccountId);
+                if (!hasExisting) {
+                    rootModel.createEphemeralInternetAccount(internetAccountId, {}, url);
+                }
+                ready = true;
+            }
+            catch {
+                // no HTTPBasicInternetAccount type registered; leave ready=false so the
+                // caller surfaces the original auth error instead of retrying
+            }
+        }
+        return ready;
+    }
+    /**
+     * Terminate the driver's worker threads. Call when discarding the owning root
+     * model (e.g. switching sessions or reloading after a plugin change) so
+     * orphaned workers don't accumulate across a desktop run.
+     *
+     * **Terminal.** ADR-069 destroys the tree a task after `detach()`, so calls
+     * still arrive in that gap; a later one throws rather than quietly building a
+     * second driver and a second pool that nothing will ever destroy. ADR-086.
+     */
+    destroy() {
+        this.destroyed = true;
+        this.driver?.destroy();
+        this.driver = undefined;
+    }
+    /**
+     * Build the driver and let it start what the first call would wait for — a
+     * web worker's bundle and runtime plugins — while the host is still building
+     * its session.
+     */
+    warmUp() {
+        if (!this.destroyed) {
+            this.getDriver().warmUp();
+        }
     }
 }