wasm-idle 1.0.4 → 1.0.6

package/README.md

@@ -900,6 +900,40 @@ The pack contains the same locked upstream files, not an import-based subset. Ea
 
 `node scripts/sync-runtime.mjs wasm-ruby` regenerates both profiles from the pinned producer inputs. `node scripts/sync-wasm-ruby-split.mjs --verify` additionally checks split-profile freshness without replacing published files.
 
+### Retaining compiler caches across editor navigation
+
+Create one `createRuntimeSession(assets)` owner per browser application and use
+`session.createBinding()` for each editor or execution panel. C/C++ and Python
+keep immutable compiler/runtime modules outside their disposable execution Workers:
+
+```ts
+import { createRuntimeSession } from 'wasm-idle';
+
+const session = createRuntimeSession(assets); // browser scope, not an SSR singleton
+const panel = session.createBinding();
+const sandbox = await panel.load('PYTHON');
+await sandbox.load('print("hi")', false);
+await sandbox.clear(); // reset execution state; retain compiler/runtime cache
+await panel.dispose(); // close this panel; retain the session's cache
+
+const nextPanel = session.createBinding(); // another problem, same language
+await nextPanel.load('PYTHON');
+await session.selectLanguage('CPP'); // release old-language panels and cache
+await session.dispose(); // full, terminal release of this owner
+```
+
+Selecting a language does not download assets. The owner retains only one language;
+selecting an unsupported/server-only language also releases the previous cache.
+Executions never share mutable Wasm instances, user files or stdin. C/C++ additionally
+reuse compiled programs when source, workspace and compiler options match, while
+custom loaders and debugging retain the original execution path. Python still creates
+a fresh interpreter after `clear()`; module reuse does not eliminate interpreter startup.
+
+The asset cache is LRU-bounded to 64 entries and 256 MiB of logical asset bytes
+(not a measurement of the browser engine's compiled-code memory). C/C++ program
+artifacts are independently bounded to 8 entries and 32 MiB. `getCacheStats()` exposes
+cache counters for diagnostics. Other languages currently keep their existing lifecycle.
+
 ### Optional idle runtime prewarming
 
 `createPlaygroundBinding(assets, { prewarm: true })` enables explicit

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import playground, { createPlaygroundBinding } from './playground';
 export default playground;
 export { createPlaygroundBinding, playground };
+export { createRuntimeSession } from './playground/runtimeSession';
+export type { PlaygroundRuntimeSession } from './playground/runtimeSession';
 export { isSharedArrayBufferAvailable, requireSharedArrayBuffer } from './playground/sharedBuffer';
 export type { DebugCommand, DebugFrame, DebugSessionEvent, DebugVariable, TerminalControl } from '@wasm-idle/core';
 export type { CompilerDiagnostic, SandboxExecutionOptions } from './playground/options';

package/dist/index.js

@@ -1,4 +1,5 @@
 import playground, { createPlaygroundBinding } from './playground';
 export default playground;
 export { createPlaygroundBinding, playground };
+export { createRuntimeSession } from './playground/runtimeSession';
 export { isSharedArrayBufferAvailable, requireSharedArrayBuffer } from './playground/sharedBuffer';

package/dist/playground/assetBridge.d.ts

@@ -1,7 +1,9 @@
 import { type ResolvedRuntimeAssetConfig, type RuntimeAssetRuntime } from './assets';
 import { type ProgressLike } from '@wasm-idle/core';
+import { RuntimeAssetCache } from './runtimeAssetCache';
 export declare const boundedUtf8ByteLength: (value: string, maxBytes?: number) => number;
 export declare class WorkerAssetBridge {
+    private readonly cache?;
     private worker;
     private readonly runtime;
     private config;
@@ -13,7 +15,7 @@ export declare class WorkerAssetBridge {
     private state;
     private readonly activeLoads;
     private maxAssetBytes;
-    constructor(worker: Worker, runtime: RuntimeAssetRuntime, config: ResolvedRuntimeAssetConfig, progress?: ProgressLike, maxAssetBytes?: number, languageSysroots?: boolean);
+    constructor(worker: Worker, runtime: RuntimeAssetRuntime, config: ResolvedRuntimeAssetConfig, progress?: ProgressLike, maxAssetBytes?: number, languageSysroots?: boolean, cache?: RuntimeAssetCache | undefined);
     matches(config: ResolvedRuntimeAssetConfig, maxAssetBytes?: number, languageSysroots?: boolean): boolean;
     rebind(worker: Worker, config: ResolvedRuntimeAssetConfig, progress?: ProgressLike, maxAssetBytes?: number, languageSysroots?: boolean): void;
     dispose(): void;
@@ -23,6 +25,8 @@ export declare class WorkerAssetBridge {
     private sourceAssetByteLimit;
     handleMessage(event: MessageEvent<any>): boolean;
     private respond;
+    private loadVerifiedAsset;
+    private validateAssetRequest;
     private loadAsset;
     private verifyIntegrity;
     private normalizeLoaderResult;

package/dist/playground/assetBridge.js

@@ -4,6 +4,9 @@ import { decompressGzip } from '@wasm-idle/llvm-core';
 import { readPythonPackageAssets } from './pythonPackageLock';
 import { BUNDLED_CLANG_LANGUAGE_SYSROOT_PROFILES } from './clangAssetIntegrity';
 import { shouldStreamBundledClang } from './clangStreamingPolicy';
+import { compileVerifiedWasmAsset } from '@wasm-idle/llvm-core/core/verified-wasm';
+import { BUNDLED_CLANG_ASSET_INTEGRITY } from './clangAssetIntegrity';
+import { RuntimeAssetCache } from './runtimeAssetCache';
 const encoder = new TextEncoder();
 const DEFAULT_STREAM_BUFFER_BYTES = 64 * 1024;
 const MAX_RUNTIME_ASSET_BYTES = 128 * 1024 * 1024;
@@ -372,6 +375,7 @@ class RuntimeLoadProgress {
     }
 }
 export class WorkerAssetBridge {
+    cache;
     worker;
     runtime;
     config;
@@ -383,7 +387,8 @@ export class WorkerAssetBridge {
     state = 'active';
     activeLoads = new Set();
     maxAssetBytes;
-    constructor(worker, runtime, config, progress, maxAssetBytes = MAX_RUNTIME_ASSET_BYTES, languageSysroots = false) {
+    constructor(worker, runtime, config, progress, maxAssetBytes = MAX_RUNTIME_ASSET_BYTES, languageSysroots = false, cache) {
+        this.cache = cache;
         this.worker = worker;
         this.runtime = runtime;
         this.config = config;
@@ -522,51 +527,71 @@ export class WorkerAssetBridge {
         const controller = new AbortController();
         this.activeLoads.add(controller);
         try {
-            const loaded = await this.loadAsset(request.asset, controller.signal);
-            const deliveryBytes = canonicalUint8Array(loaded.bytes);
-            const sourceAssetByteLimit = this.sourceAssetByteLimit(request.asset);
-            const runtimeAssetByteLimit = this.runtimeAssetByteLimit(request.asset);
-            requireRuntimeAssetSize(request.asset, deliveryBytes.byteLength, sourceAssetByteLimit);
-            let normalizedRuntimeBytes;
-            if (request.asset.endsWith('.gz')) {
-                this.progress.activity('decompressing', request.asset);
-                normalizedRuntimeBytes = await decompressGzip(deliveryBytes, request.asset, runtimeAssetByteLimit, controller.signal);
-            }
-            else {
-                normalizedRuntimeBytes = deliveryBytes;
-            }
-            const runtimeBytes = canonicalUint8Array(normalizedRuntimeBytes);
-            requireRuntimeAssetSize(request.asset, runtimeBytes.byteLength, runtimeAssetByteLimit);
-            const httpDecodedGzip = (loaded.contentEncoding || '')
-                .toLowerCase()
-                .split(',')
-                .map((encoding) => encoding.trim())
-                .includes('gzip');
-            if (controller.signal.aborted || generation !== this.generation)
-                return;
-            let cancelOnAbort;
-            const aborted = new Promise((_resolve, reject) => {
-                cancelOnAbort = () => reject(runtimeAssetAbortReason(controller.signal));
-                controller.signal.addEventListener('abort', cancelOnAbort, { once: true });
-            });
-            try {
-                if (this.config.integrity?.[request.asset]) {
-                    this.progress.activity('verifying', request.asset);
+            this.validateAssetRequest(request.asset);
+            const key = JSON.stringify([
+                this.runtime,
+                this.config.baseUrl,
+                this.cache?.identity(this.config.loader),
+                integrityKey(this.config),
+                allowedBaseUrlsKey(this.config),
+                this.config.useAssetBridge,
+                this.maxAssetBytes,
+                this.languageSysroots,
+                request.asset,
+                request.module === true ? 'module' : 'bytes'
+            ]);
+            if (request.module === true) {
+                if (!/\.wasm(?:\.gz)?$/u.test(request.asset)) {
+                    throw new Error('Only runtime Wasm assets can be compiled');
                 }
-                const verification = this.verifyIntegrity(request.asset, deliveryBytes, runtimeBytes, loaded.mimeType, !httpDecodedGzip);
-                await Promise.race([verification, aborted]);
+                let module = this.cache?.get(key);
+                if (!module) {
+                    const streaming = this.runtime === 'clang' &&
+                        shouldStreamBundledClang(this.config) &&
+                        (request.asset === 'bin/clang.wasm.gz' ||
+                            request.asset === 'bin/lld.wasm.gz');
+                    let bytes;
+                    if (streaming) {
+                        const receipt = BUNDLED_CLANG_ASSET_INTEGRITY[request.asset];
+                        module = await compileVerifiedWasmAsset(new URL(request.asset, this.config.baseUrl).href, receipt, {
+                            fetch: globalThis.fetch.bind(globalThis),
+                            maxAssetBytes: this.maxAssetBytes,
+                            signal: controller.signal,
+                            onProgress: (loaded, total) => this.progress.update(request.asset, loaded, total)
+                        });
+                        bytes = receipt.uncompressedBytes;
+                    }
+                    else {
+                        const loaded = await this.loadVerifiedAsset(request.asset, controller.signal);
+                        bytes = loaded.bytes.byteLength;
+                        module = await WebAssembly.compile(Uint8Array.from(loaded.bytes));
+                    }
+                    if (controller.signal.aborted || generation !== this.generation)
+                        return;
+                    this.cache?.set(key, module, bytes);
+                }
+                if (controller.signal.aborted || generation !== this.generation)
+                    return;
+                worker.postMessage({ assetResponse: { id: request.id, ok: true, module } });
+                return;
             }
-            finally {
-                if (cancelOnAbort) {
-                    controller.signal.removeEventListener('abort', cancelOnAbort);
+            let loaded = this.cache?.get(key);
+            if (!loaded) {
+                loaded = await this.loadVerifiedAsset(request.asset, controller.signal);
+                if (controller.signal.aborted || generation !== this.generation)
+                    return;
+                // Keep private copies: never transfer or lend the owner cache's backing buffer.
+                if (this.cache) {
+                    loaded = { bytes: Uint8Array.from(loaded.bytes), mimeType: loaded.mimeType };
+                    this.cache.set(key, loaded, loaded.bytes.byteLength);
                 }
             }
-            if (controller.signal.aborted || generation !== this.generation)
-                return;
             if (this.runtime === 'python' && request.asset === 'pyodide-lock.json') {
-                this.pythonPackageAssets = readPythonPackageAssets(runtimeBytes);
+                this.pythonPackageAssets = readPythonPackageAssets(loaded.bytes);
             }
-            const buffer = transferBuffer(runtimeBytes, normalizedRuntimeBytes === deliveryBytes ? loaded.transferOwnership : true);
+            if (controller.signal.aborted || generation !== this.generation)
+                return;
+            const buffer = transferBuffer(loaded.bytes, this.cache ? false : loaded.transferOwnership);
             worker.postMessage({
                 assetResponse: {
                     id: request.id,
@@ -589,20 +614,73 @@ export class WorkerAssetBridge {
                 });
             }
             catch {
-                // The worker may already be terminated. There is no remaining response channel.
+                // The worker may already be terminated.
             }
         }
         finally {
             this.activeLoads.delete(controller);
         }
     }
-    async loadAsset(asset, signal) {
+    async loadVerifiedAsset(asset, signal) {
+        const loaded = await this.loadAsset(asset, signal);
+        const deliveryBytes = canonicalUint8Array(loaded.bytes);
+        const sourceAssetByteLimit = this.sourceAssetByteLimit(asset);
+        const runtimeAssetByteLimit = this.runtimeAssetByteLimit(asset);
+        requireRuntimeAssetSize(asset, deliveryBytes.byteLength, sourceAssetByteLimit);
+        let normalizedRuntimeBytes;
+        if (asset.endsWith('.gz')) {
+            this.progress.activity('decompressing', asset);
+            normalizedRuntimeBytes = await decompressGzip(deliveryBytes, asset, runtimeAssetByteLimit, signal);
+        }
+        else {
+            normalizedRuntimeBytes = deliveryBytes;
+        }
+        const runtimeBytes = canonicalUint8Array(normalizedRuntimeBytes);
+        requireRuntimeAssetSize(asset, runtimeBytes.byteLength, runtimeAssetByteLimit);
+        const httpDecodedGzip = (loaded.contentEncoding || '')
+            .toLowerCase()
+            .split(',')
+            .map((encoding) => encoding.trim())
+            .includes('gzip');
+        if (signal.aborted)
+            throw runtimeAssetAbortReason(signal);
+        let cancelOnAbort;
+        const aborted = new Promise((_resolve, reject) => {
+            cancelOnAbort = () => reject(runtimeAssetAbortReason(signal));
+            signal.addEventListener('abort', cancelOnAbort, { once: true });
+        });
+        try {
+            if (this.config.integrity?.[asset]) {
+                this.progress.activity('verifying', asset);
+            }
+            const verification = this.verifyIntegrity(asset, deliveryBytes, runtimeBytes, loaded.mimeType, !httpDecodedGzip);
+            await Promise.race([verification, aborted]);
+        }
+        finally {
+            if (cancelOnAbort) {
+                signal.removeEventListener('abort', cancelOnAbort);
+            }
+        }
+        if (signal.aborted)
+            throw runtimeAssetAbortReason(signal);
+        if (this.runtime === 'python' && asset === 'pyodide-lock.json')
+            readPythonPackageAssets(runtimeBytes);
+        return {
+            bytes: runtimeBytes,
+            mimeType: loaded.mimeType,
+            transferOwnership: normalizedRuntimeBytes === deliveryBytes ? loaded.transferOwnership : true
+        };
+    }
+    validateAssetRequest(asset) {
         if (!this.expectedAssets.has(asset) && !this.pythonPackageAssets.has(asset)) {
             throw new Error(`Unexpected ${this.runtime} runtime asset: ${asset}`);
         }
         if (this.config.integrity && !Object.hasOwn(this.config.integrity, asset)) {
             throw new Error(`Runtime asset ${asset} is missing integrity metadata`);
         }
+    }
+    async loadAsset(asset, signal) {
+        this.validateAssetRequest(asset);
         if (signal.aborted) {
             throw runtimeAssetAbortReason(signal);
         }

package/dist/playground/cachedClang.d.ts

@@ -0,0 +1,10 @@
+import { type Sandbox } from '@wasm-idle/core';
+import type { RuntimeAssetCache } from './runtimeAssetCache';
+import { CompiledArtifactCache } from './compiledArtifactCache';
+type WorkerFactories = {
+    compile(): Worker | Promise<Worker>;
+    execute(): Worker | Promise<Worker>;
+};
+/** Wrap the public sandbox contract; all other languages and debugger operations stay unchanged. */
+export declare function createCachedClangSandbox(legacy: Sandbox, language: 'C' | 'CPP', runtimeCache: RuntimeAssetCache, cache?: CompiledArtifactCache, factories?: WorkerFactories): Sandbox;
+export {};

package/dist/playground/cachedClang.js

@@ -0,0 +1,323 @@
+import { resolveExecutionLimits } from '@wasm-idle/core';
+import { resolveRuntimeAssetConfig } from './assets';
+import { WorkerAssetBridge } from './assetBridge';
+import { shouldStreamBundledClang } from './clangStreamingPolicy';
+import { CompiledArtifactCache, clangCompileKey } from './compiledArtifactCache';
+const workers = {
+    async compile() {
+        const { default: CompileWorker } = await import('./worker/cachedClangCompile?worker');
+        return new CompileWorker();
+    },
+    async execute() {
+        const { default: ExecuteWorker } = await import('./worker/cachedClangExecute?worker');
+        return new ExecuteWorker();
+    }
+};
+/** Wrap the public sandbox contract; all other languages and debugger operations stay unchanged. */
+export function createCachedClangSandbox(legacy, language, runtimeCache, cache = new CompiledArtifactCache(), factories = workers) {
+    let cached = false;
+    let loadedAssets = '';
+    let runtimeBaseUrl = '';
+    let assetConfig;
+    let maxAssetBytes = 0;
+    let languageSysroots = false;
+    let activeWorker;
+    let cancelWorker;
+    let generation = 0;
+    let running = false;
+    let disposed = false;
+    let disposal;
+    let inputBuffer;
+    let inputRequested = false;
+    let pendingEof = false;
+    const pendingInput = [];
+    const encoder = new TextEncoder();
+    function resetInput() {
+        pendingInput.length = 0;
+        pendingEof = false;
+        inputRequested = false;
+        inputBuffer = undefined;
+    }
+    function flushInput() {
+        if (!inputRequested || !inputBuffer)
+            return;
+        const control = new Int32Array(inputBuffer, 0, 2);
+        const payload = new Uint8Array(inputBuffer, 8);
+        const next = pendingInput[0];
+        if (next) {
+            const length = Math.min(next.byteLength, payload.byteLength);
+            payload.set(next.subarray(0, length));
+            if (length === next.byteLength)
+                pendingInput.shift();
+            else
+                pendingInput[0] = next.subarray(length);
+            Atomics.store(control, 1, length);
+            Atomics.store(control, 0, 1);
+        }
+        else if (pendingEof) {
+            Atomics.store(control, 1, 0);
+            Atomics.store(control, 0, 2);
+        }
+        else
+            return;
+        inputRequested = false;
+        Atomics.notify(control, 0);
+    }
+    function stop() {
+        generation++;
+        running = false;
+        cancelWorker?.(new Error('Process terminated'));
+        resetInput();
+    }
+    async function workerOperation(factory, message, token, progress, compileLimit = 0, signal) {
+        const worker = await factory();
+        if (token !== generation || signal?.aborted) {
+            worker.terminate();
+            throw signal?.reason ?? new Error('Process terminated');
+        }
+        return new Promise((resolve, reject) => {
+            let bridge;
+            try {
+                if (compileLimit)
+                    bridge = new WorkerAssetBridge(worker, 'clang', assetConfig, progress, compileLimit, languageSysroots, runtimeCache);
+            }
+            catch (error) {
+                worker.terminate();
+                reject(error);
+                return;
+            }
+            activeWorker = worker;
+            const abort = () => finish(signal?.reason instanceof Error
+                ? signal.reason
+                : new Error('Process terminated'));
+            const finish = (error, value) => {
+                if (activeWorker !== worker)
+                    return;
+                activeWorker = undefined;
+                cancelWorker = undefined;
+                signal?.removeEventListener('abort', abort);
+                bridge?.dispose();
+                worker.onmessage = null;
+                worker.onerror = null;
+                worker.onmessageerror = null;
+                worker.terminate();
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            cancelWorker = finish;
+            signal?.addEventListener('abort', abort, { once: true });
+            worker.onerror = (event) => finish(new Error(event.message || 'C/C++ worker failed'));
+            worker.onmessageerror = () => finish(new Error('C/C++ worker message could not be decoded'));
+            worker.onmessage = (event) => {
+                if (activeWorker !== worker)
+                    return;
+                try {
+                    if (bridge?.handleMessage(event))
+                        return;
+                    const { data } = event;
+                    if (data.type === 'output')
+                        legacy.output?.(data.output);
+                    else if (data.type === 'progress') {
+                        progress?.set?.(data.progress.percent / 100);
+                        progress?.report?.({
+                            kind: 'activity',
+                            phase: 'compiling',
+                            label: data.progress.message
+                        });
+                    }
+                    else if (data.type === 'stdin') {
+                        inputRequested = true;
+                        progress?.report?.({
+                            kind: 'ready',
+                            state: 'waiting-input',
+                            reason: 'stdin-request',
+                            label: 'Runtime ready for input'
+                        });
+                        flushInput();
+                    }
+                    else if (data.type === 'compiled' || data.type === 'error') {
+                        if (data.stdout)
+                            legacy.output?.(data.stdout);
+                        if (data.stderr)
+                            legacy.output?.(data.stderr);
+                        if (data.type === 'error')
+                            finish(new Error(data.error));
+                        else
+                            finish(undefined, data.artifact);
+                    }
+                    else if (data.type === 'done') {
+                        if (data.exitCode !== 0 && data.exitCode !== null)
+                            finish(new Error(`Program exited with code ${data.exitCode}`));
+                        else
+                            finish(undefined, true);
+                    }
+                }
+                catch (error) {
+                    finish(error instanceof Error ? error : new Error(String(error)));
+                }
+            };
+            try {
+                worker.postMessage(message);
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    const overrides = {
+        async load(assets = '', code = '', log = true, args = [], options = {}, progress) {
+            if (disposed)
+                throw new Error('C/C++ sandbox was disposed');
+            loadedAssets = assets;
+            const config = typeof assets === 'object' ? assets : undefined;
+            assetConfig = resolveRuntimeAssetConfig('clang', assets, globalThis.location?.href || 'http://localhost/');
+            const debugMode = options.debugMode || (options.debug ? 'trace' : 'none');
+            const cacheEligible = debugMode === 'none' &&
+                shouldStreamBundledClang(assetConfig) &&
+                !options.workspaceFiles?.some((file) => typeof file.content !== 'string') &&
+                (options.stdin === undefined || typeof options.stdin === 'string') &&
+                typeof SharedArrayBuffer !== 'undefined';
+            if (!cached)
+                await legacy.clear();
+            if (disposed)
+                throw new Error('C/C++ sandbox was disposed');
+            stop();
+            cached = cacheEligible;
+            if (!cached)
+                return legacy.load(assets, code, log, args, options, progress);
+            runtimeBaseUrl = assetConfig.baseUrl;
+            maxAssetBytes = resolveExecutionLimits(options.limits).maxAssetBytes;
+            languageSysroots = config?.clang?.bundledLanguageSysroots === true;
+        },
+        async run(code, prepare, log = true, progress, args = [], options = {}) {
+            if (disposed)
+                throw new Error('C/C++ sandbox was disposed');
+            if (cached &&
+                ((options.debugMode || (options.debug ? 'trace' : 'none')) !== 'none' ||
+                    (options.stdin !== undefined && typeof options.stdin !== 'string') ||
+                    options.workspaceFiles?.some((file) => typeof file.content !== 'string'))) {
+                await overrides.load(loadedAssets, code, log, args, options, progress);
+            }
+            if (!cached)
+                return legacy.run(code, prepare, log, progress, args, options);
+            if (running)
+                throw new Error('C/C++ sandbox is already running');
+            options.signal?.throwIfAborted();
+            const token = ++generation;
+            // Reactive UI arrays/records are Proxies and cannot cross postMessage.
+            // Snapshot known fields before awaiting compilation, so the cache key,
+            // compiler and executor also observe the same input values.
+            const request = {
+                code,
+                language,
+                activePath: options.activePath,
+                workspaceFiles: options.workspaceFiles === undefined
+                    ? undefined
+                    : Array.from(options.workspaceFiles, (file) => ({
+                        path: file.path,
+                        content: file.content
+                    })),
+                compileArgs: Array.from(options.compileArgs ?? args),
+                cVersion: options.cVersion,
+                cppVersion: options.cppVersion
+            };
+            const programArgs = Array.from(options.programArgs ?? []);
+            const env = options.env === undefined
+                ? undefined
+                : Object.fromEntries(Object.entries(options.env));
+            const stdin = options.stdin;
+            const limit = Math.min(maxAssetBytes, resolveExecutionLimits(options.limits).maxAssetBytes);
+            const key = clangCompileKey(runtimeBaseUrl, limit, request, languageSysroots);
+            let artifact = cache.get(key);
+            running = true;
+            try {
+                if (!artifact) {
+                    artifact = await workerOperation(() => factories.compile(), {
+                        request,
+                        runtimeBaseUrl,
+                        maxAssetBytes: limit,
+                        languageSysroots,
+                        log,
+                        assets: {
+                            baseUrl: runtimeBaseUrl,
+                            maxAssetBytes: limit,
+                            useAssetBridge: assetConfig.useAssetBridge,
+                            useModuleBridge: true
+                        }
+                    }, token, progress, limit, options.signal);
+                    if (token !== generation)
+                        throw new Error('Process terminated');
+                    cache.set(key, artifact);
+                }
+                progress?.set?.(1);
+                if (prepare)
+                    return true;
+                inputBuffer = new SharedArrayBuffer(65536 + 8);
+                return await workerOperation(() => factories.execute(), {
+                    artifact,
+                    code,
+                    activePath: request.activePath,
+                    workspaceFiles: request.workspaceFiles,
+                    programArgs,
+                    env,
+                    stdin,
+                    inputBuffer
+                }, token, progress, 0, options.signal);
+            }
+            finally {
+                if (token === generation) {
+                    running = false;
+                    if (!prepare)
+                        resetInput();
+                }
+            }
+        },
+        write(input) {
+            if (!cached)
+                return legacy.write?.(input);
+            if (input)
+                pendingInput.push(encoder.encode(input));
+            flushInput();
+        },
+        eof() {
+            if (!cached)
+                return legacy.eof();
+            pendingEof = true;
+            flushInput();
+        },
+        async clear() {
+            stop();
+            if (!cached)
+                await legacy.clear();
+        },
+        async terminate() {
+            stop();
+            if (!cached)
+                await legacy.terminate();
+        },
+        async kill() {
+            await overrides.terminate();
+        },
+        async cancel() {
+            await overrides.terminate();
+        },
+        dispose() {
+            if (disposal)
+                return disposal;
+            disposed = true;
+            stop();
+            disposal = Promise.resolve(legacy.dispose ? legacy.dispose() : legacy.terminate());
+            return disposal;
+        }
+    };
+    return new Proxy(legacy, {
+        get(target, property) {
+            if (Object.hasOwn(overrides, property))
+                return overrides[property];
+            const value = Reflect.get(target, property);
+            return typeof value === 'function' ? value.bind(target) : value;
+        }
+    });
+}

package/dist/playground/clang.d.ts

@@ -1,5 +1,6 @@
 import type { DebugCommand, DebugDataBreakpoint, DebugDataBreakpointInfoArguments, DebugSessionEvent, SandboxExecutionOptions } from './options';
 import { WorkerAssetBridge } from './assetBridge';
+import { RuntimeAssetCache } from './runtimeAssetCache';
 import { type PlaygroundRuntimeAssets, type RuntimeAssetIntegrityEntry } from './assets';
 import type { Sandbox } from './sandbox';
 import { type ProgressSink } from './workerProgress';
@@ -27,6 +28,10 @@ declare class Clang implements Sandbox {
     debugManifestUrl: string;
     debugManifestReceipt?: Readonly<RuntimeAssetIntegrityEntry>;
     private lldbSession?;
+    private runtimeAssetCache;
+    private ownsRuntimeAssetCache;
+    private disposed;
+    private disposal?;
     private debugMode;
     private readonly lldbBreakpoints;
     private debugEvaluationQueue;
@@ -56,5 +61,7 @@ declare class Clang implements Sandbox {
     kill(): Promise<void>;
     terminate(): Promise<void>;
     clear(): Promise<void>;
+    setRuntimeAssetCache(cache: RuntimeAssetCache): void;
+    dispose(): Promise<void>;
 }
 export default Clang;