wasm-idle 1.0.5 → 1.0.7

package/README.md

@@ -15,6 +15,10 @@ Compiler source pins, patches, and reproducible asset builds live in
 [`seo-rii/wasm-llvm`](https://github.com/seo-rii/wasm-llvm); wasm-idle loads the generated
 artifacts from external URLs instead of embedding them in npm packages.
 
+Verified downloads can be retained across reloads using a version-pinned, capacity-bounded
+CacheStorage/IndexedDB cache. See [persistent asset cache configuration and coverage](docs/runtime-asset-cache.md)
+for global/per-call opt-out, cleanup and prefetch APIs.
+
 ## Language support policy
 
 wasm-idle language support must run user code through the real language implementation in the
@@ -221,9 +225,9 @@ when they exist.
 | Language / IDs                     | Package/version base                                                                                                                                                           | Execution defaults / flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Customization                                                                                                                                                                                                                                                                                                                                    |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | C3<br>`C3`                         | wasm-llvm/c3-browser: C3 0.8.3 / LLVM 22.1.8                                                                                                                                   | Verified c3c and builtin LLD compile real C3 in a fresh browser Worker; UTF-8 env.readByte/env.writeByte ABI and exported main; std::io and WASI unavailable                                                                                                                                                                                                                                                                                                                                                                                                            | `runtimeAssets.c3.baseUrl`, `stdin`, `activePath`, `workspaceFiles`; fixed compiler flags and bounded Wasm memories                                                                                                                                                                                                                              |
-| C<br>`C`                           | @wasm-idle/llvm-core@1.0.3 / Clang 22.1.8 WASI sysroot from the `wasm-llvm` producer                                                                                           | `clang` for `wasm32-wasi`; default `-std=gnu11`; LLDB mode compiles untouched source with embedded DWARF at `-g -O0` and runs it in WAMR; normal runs still use the browser WASI host; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                               | `runtimeAssets.clang.baseUrl`/`loader` or `rootUrl`; `compileArgs`, `programArgs`, `cVersion`, `activePath`, `workspaceFiles`, `debugMode`, `breakpoints`, `pauseOnEntry`                                                                                                                                                                        |
-| C++<br>`CPP`                       | @wasm-idle/llvm-core@1.0.3 / Clang 22.1.8 WASI sysroot from the `wasm-llvm` producer                                                                                           | `clang++` for `wasm32-wasi`; default `-std=gnu++20`; LLDB mode compiles untouched source with embedded DWARF at `-g -O0` and runs it in WAMR; normal runs still use the browser WASI host; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                           | `runtimeAssets.clang.baseUrl`/`loader` or `rootUrl`; `compileArgs`, `programArgs`, `cppVersion`, `activePath`, `workspaceFiles`, `debugMode`, `breakpoints`, `pauseOnEntry`                                                                                                                                                                      |
-| Objective-C<br>`OBJC`              | GNUstep libobjc2 v2.3 assets from the `wasm-llvm` producer + @wasm-idle/llvm-core@1.0.3                                                                                        | `clang -x objective-c -fobjc-runtime=gnustep-2.0 -fblocks` for `wasm32-wasi`; links `libobjc.a`, `libgnustep-base.a`, and `libffi.a` when Foundation is imported; Foundation headers are inlined from `foundation-headers.json`; includes a constructor wrapper for Objective-C class registration; auto-compiles `.m`/`.mm`/`.c` workspace files; trace debug instruments active source and uses wasm-idle controls; supports `stdin` and `programArgs`; large Objective-C assets may be served as gzip-only `.gz` files through the service worker or worker fallback | `runtimeAssets.objectivec.baseUrl`/`libobjcUrl`/`headersUrl`/`libgnustepBaseUrl`/`libgnustepBaseObjectUrl`/`foundationHeadersUrl`/`libffiUrl` or `PUBLIC_WASM_OBJECTIVEC_*`; `runtimeAssets.clang.baseUrl`/`loader` for the clang toolchain; `activePath`, `workspaceFiles`, `compileArgs`, `debug`, `breakpoints`, `pauseOnEntry`               |
+| C<br>`C`                           | @wasm-idle/llvm-core@1.0.7 / Clang 22.1.8 WASI sysroot from the `wasm-llvm` producer                                                                                           | `clang` for `wasm32-wasi`; default `-std=gnu11`; LLDB mode compiles untouched source with embedded DWARF at `-g -O0` and runs it in WAMR; normal runs still use the browser WASI host; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                               | `runtimeAssets.clang.baseUrl`/`loader` or `rootUrl`; `compileArgs`, `programArgs`, `cVersion`, `activePath`, `workspaceFiles`, `debugMode`, `breakpoints`, `pauseOnEntry`                                                                                                                                                                        |
+| C++<br>`CPP`                       | @wasm-idle/llvm-core@1.0.7 / Clang 22.1.8 WASI sysroot from the `wasm-llvm` producer                                                                                           | `clang++` for `wasm32-wasi`; default `-std=gnu++20`; LLDB mode compiles untouched source with embedded DWARF at `-g -O0` and runs it in WAMR; normal runs still use the browser WASI host; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                           | `runtimeAssets.clang.baseUrl`/`loader` or `rootUrl`; `compileArgs`, `programArgs`, `cppVersion`, `activePath`, `workspaceFiles`, `debugMode`, `breakpoints`, `pauseOnEntry`                                                                                                                                                                      |
+| Objective-C<br>`OBJC`              | GNUstep libobjc2 v2.3 assets from the `wasm-llvm` producer + @wasm-idle/llvm-core@1.0.7                                                                                        | `clang -x objective-c -fobjc-runtime=gnustep-2.0 -fblocks` for `wasm32-wasi`; links `libobjc.a`, `libgnustep-base.a`, and `libffi.a` when Foundation is imported; Foundation headers are inlined from `foundation-headers.json`; includes a constructor wrapper for Objective-C class registration; auto-compiles `.m`/`.mm`/`.c` workspace files; trace debug instruments active source and uses wasm-idle controls; supports `stdin` and `programArgs`; large Objective-C assets may be served as gzip-only `.gz` files through the service worker or worker fallback | `runtimeAssets.objectivec.baseUrl`/`libobjcUrl`/`headersUrl`/`libgnustepBaseUrl`/`libgnustepBaseObjectUrl`/`foundationHeadersUrl`/`libffiUrl` or `PUBLIC_WASM_OBJECTIVEC_*`; `runtimeAssets.clang.baseUrl`/`loader` for the clang toolchain; `activePath`, `workspaceFiles`, `compileArgs`, `debug`, `breakpoints`, `pauseOnEntry`               |
 | Python<br>`PYTHON3`                | static ESM `static/pyodide/pyodide.mjs` / pyodide@0.29.3                                                                                                                       | loads `pyodide.mjs`, `pyodide.asm.js`, `pyodide.asm.wasm`, and `python_stdlib.zip` from the configured static asset tree on demand; supports `stdin`, workspace files, and trace debugging                                                                                                                                                                                                                                                                                                                                                                              | `runtimeAssets.python.baseUrl`/`loader` or `rootUrl`; `stdin`, `activePath`, `workspaceFiles`, `debug`, `breakpoints`, `pauseOnEntry`, `debugPath`                                                                                                                                                                                               |
 | Java<br>`JAVA`                     | @wasm-idle/runtime-teavm@0.0.0 / TeaVM compiler assets                                                                                                                         | `compiler.wasm` compiles Java to browser WASM/JS; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `runtimeAssets.java.baseUrl`/`loader` or `rootUrl`                                                                                                                                                                                                                                                                                               |
 | Rust<br>`RUST`                     | wasm-rust@0.1.0 / rust-1.99.0-browser-integrated-v1 + integrated LLVM/LLD 22.1.8 from the `wasm-llvm` producer; exact rustc/LLVM provenance is recorded for LLDB compatibility | browser host `wasm32-wasip1-threads`; default target `wasm32-wasip1`, selectable `wasm32-wasip1`, `wasm32-wasip2`, `wasm32-wasip3`; LLDB mode is currently limited to `wasm32-wasip1` and emits embedded DWARF with `-C debuginfo=2 -C opt-level=0`; normal Preview 1/2/3 execution remains unchanged; supports `stdin` and `programArgs`                                                                                                                                                                                                                               | `runtimeAssets.rust.compilerUrl`, `runtimeAssets.rust.debugModuleUrl`, or `PUBLIC_WASM_RUST_COMPILER_URL`; `rootUrl`, `rustTargetTriple`, `programArgs`, `debugMode`; compiler requests accept `edition`, `crateType`, `extendedTimeout`, `log`, and `onProgress`; runtime manifest controls compiler memory, timeout, and shared workspace size |
@@ -261,8 +265,8 @@ when they exist.
 | Ruby<br>`RUBY`                     | receipt-pinned `static/wasm-ruby` profile produced from @ruby/3.4-wasm-wasi@2.9.3-2.9.4 + @ruby/wasm-wasi@2.9.3-2.9.4                                                          | host-verifies the manifest, canonical stored module and gzip bytes, and logical WASM before transferring three owned buffers to a no-fetch CRuby 3.4 worker; supports `stdin`, `programArgs`, and workspace files                                                                                                                                                                                                                                                                                                                                                       | `rootUrl` mirrors reuse the bundled profile; explicit `runtimeAssets.ruby` overrides require one complete profile and same-origin canonical paths; URL-only `PUBLIC_WASM_RUBY_*` overrides fail closed; `stdin`, `programArgs`, `workspaceFiles`                                                                                                 |
 | Haskell<br>`HASKELL`               | ghc-in-browser / GHC 9.14.0.20251031 WASI rootfs                                                                                                                               | loads `dyld.mjs`, `rootfs.tar.zst`, `bsdtar.wasm`; `compileArgs` become GHC args, otherwise legacy `args` become GHC args                                                                                                                                                                                                                                                                                                                                                                                                                                               | `runtimeAssets.haskell.moduleUrl`/`rootfsUrl`/`bsdtarUrl`; `mainSoPath`, `searchDirs`, `activePath`, `workspaceFiles`                                                                                                                                                                                                                            |
 | LFortran<br>`LFORTRAN`             | receipt-pinned `wasm-llvm/producer/lfortran-browser` artifacts in `static/wasm-lfortran`                                                                                       | real LFortran 0.65.0-97-gab867a23 LLVM evaluator compiles and executes Emscripten side modules in a fresh Worker; shared-ring stdin supports delayed READ and EOF; experimental Fortran feature coverage                                                                                                                                                                                                                                                                                                                                                                | `runtimeAssets.lfortran.baseUrl` relocates the reviewed bundle; `stdin`, `activePath`, workspace data/include files, cancellation and execution limits; no program arguments or multi-file module build orchestration                                                                                                                            |
-| Fortran<br>`FORTRAN`               | Netlib f2c 2022-09-09 + `@cowasm/f2c 1.0.0` libf2c + @wasm-idle/llvm-core@1.0.3                                                                                                | runs `f2c.wasm` in WASI, compiles generated C with the llvm-core Clang host, links `libf2c.a`, then executes the resulting WASI module with `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                                                                                   | `runtimeAssets.fortran.baseUrl`/`f2cWasmUrl`/`libf2cUrl`/`f2cHeaderUrl`/`analyzerUrl` or `PUBLIC_WASM_FORTRAN_*`; `runtimeAssets.clang.baseUrl`/`loader` for the C backend; `activePath`, `workspaceFiles`, `compileArgs`                                                                                                                        |
-| COBOL<br>`COBOL`                   | GnuCOBOL 3.2 + GMP 6.3.0 assets from the `wasm-llvm` producer + @wasm-idle/llvm-core@1.0.3                                                                                     | native gzip delivery for the frontend Wasm and filesystem tar assets; translates free-format COBOL with the real GnuCOBOL `cobc` frontend, compiles the generated C with the llvm-core Clang host, links libcob/GMP, and executes the resulting WASI module with `stdin` and `programArgs`                                                                                                                                                                                                                                                                              | `runtimeAssets.cobol.baseUrl` or `PUBLIC_WASM_COBOL_BASE_URL`; `runtimeAssets.clang.baseUrl`/`loader` for the C backend; `activePath`, `workspaceFiles`, `compileArgs`                                                                                                                                                                           |
+| Fortran<br>`FORTRAN`               | Netlib f2c 2022-09-09 + `@cowasm/f2c 1.0.0` libf2c + @wasm-idle/llvm-core@1.0.7                                                                                                | runs `f2c.wasm` in WASI, compiles generated C with the llvm-core Clang host, links `libf2c.a`, then executes the resulting WASI module with `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                                                                                   | `runtimeAssets.fortran.baseUrl`/`f2cWasmUrl`/`libf2cUrl`/`f2cHeaderUrl`/`analyzerUrl` or `PUBLIC_WASM_FORTRAN_*`; `runtimeAssets.clang.baseUrl`/`loader` for the C backend; `activePath`, `workspaceFiles`, `compileArgs`                                                                                                                        |
+| COBOL<br>`COBOL`                   | GnuCOBOL 3.2 + GMP 6.3.0 assets from the `wasm-llvm` producer + @wasm-idle/llvm-core@1.0.7                                                                                     | native gzip delivery for the frontend Wasm and filesystem tar assets; translates free-format COBOL with the real GnuCOBOL `cobc` frontend, compiles the generated C with the llvm-core Clang host, links libcob/GMP, and executes the resulting WASI module with `stdin` and `programArgs`                                                                                                                                                                                                                                                                              | `runtimeAssets.cobol.baseUrl` or `PUBLIC_WASM_COBOL_BASE_URL`; `runtimeAssets.clang.baseUrl`/`loader` for the C backend; `activePath`, `workspaceFiles`, `compileArgs`                                                                                                                                                                           |
 | R<br>`R`                           | versioned static `static/webr/<hash>/webr.js` / webr@0.6.0                                                                                                                     | loads the browser ESM entry `webr.js` and its WebR runtime files from the configured static asset tree on demand; supports `stdin`, `programArgs`, and workspace files                                                                                                                                                                                                                                                                                                                                                                                                  | `runtimeAssets.r.baseUrl` or `PUBLIC_WASM_R_BASE_URL`; `stdin`, `programArgs`, `activePath`, `workspaceFiles`                                                                                                                                                                                                                                    |
 | Octave<br>`OCTAVE`                 | Octave 10.3.0 (octave-10.3.0-pl5321h996e327_3.tar.bz2)                                                                                                                         | Octave CLI Emscripten worker; supports `stdin` and `programArgs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `runtimeAssets.octave.baseUrl`/`workerUrl`/`manifestUrl` or `PUBLIC_WASM_OCTAVE_*`                                                                                                                                                                                                                                                               |
 | DuckDB<br>`DUCKDB`                 | static ESM `static/wasm-duckdb/runtime.mjs` produced from @duckdb/duckdb-wasm@1.33.1-dev45.0                                                                                   | selects the best DuckDB-Wasm MVP/EH bundle on demand and creates a fresh in-memory database per run; `stdin` is registered as `stdin.txt` and `/dev/stdin` rather than terminal stdin                                                                                                                                                                                                                                                                                                                                                                                   | `runtimeAssets.duckdb.moduleUrl` or `PUBLIC_WASM_DUCKDB_MODULE_URL` or `rootUrl`; `stdin`, `activePath`, `workspaceFiles`                                                                                                                                                                                                                        |
@@ -323,6 +327,15 @@ toolchains can be consumed from pinned external runtime repositories:
   normal runtime workspace packages. `tools/dool` contains the Docker judge backend for Elixir and
   the other server-side language runners.
 
+Deployment builds retain both legacy `.gz` and canonical `.gz.bin` URLs by default.
+After building and compressing the page, `pnpm run compact:build-runtimes` reports
+byte-identical duplicates without changing files. Add `--drop-legacy-aliases` to
+remove those duplicate files and add compatibility routing to the generated service
+worker. This only preserves legacy URLs in service-worker-controlled requests:
+external SDKs and uncontrolled first requests to the removed `.gz` URLs need to
+migrate to `.gz.bin` or use server aliases. Opt in only after that migration. Source
+assets and producer receipts stay intact; rerun compaction after each page build.
+
 Useful workspace commands:
 
 ```bash
@@ -900,6 +913,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,9 +1,12 @@
 import playground, { createPlaygroundBinding } from './playground';
 export default playground;
 export { createPlaygroundBinding, playground };
+export { createRuntimeSession } from './playground/runtimeSession';
+export { configureRuntimeAssetCache, createRuntimeAssetCacheBackend, fetchPinnedRuntimeAsset, prefetchRuntimeAssets, resolveRuntimeAssetLockEntry, type PrefetchRuntimeAssetsOptions, type PrefetchRuntimeAssetsResult, type RuntimeAssetCacheStats, type RuntimeAssetCacheBackend, type RuntimeAssetCacheBackendIdentity, type PinnedRuntimeAssetRequest, getRuntimeAssetCacheOptions, getRuntimeAssetCacheStats, clearRuntimeAssetCache, pruneRuntimeAssetCache, requestRuntimeAssetCachePersistence, type RuntimeAssetCacheOptions } from '@wasm-idle/core';
+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';
 export type { PlaygroundRuntimeAssets, RuntimeAssetConfig, RuntimeAssetLoadRequest, RuntimeAssetLoader, RuntimeAssetLoaderResult } from './playground/assets';
 export type { BoundSandbox, PlaygroundBinding, PlaygroundTerminalProps, SandboxProgress, SandboxRuntimeAssets } from './playground/sandbox';
-export type { PlaygroundBindingOptions } from "@wasm-idle/core";
+export type { PlaygroundBindingOptions } from '@wasm-idle/core';

package/dist/index.js

@@ -1,4 +1,6 @@
 import playground, { createPlaygroundBinding } from './playground';
 export default playground;
 export { createPlaygroundBinding, playground };
+export { createRuntimeSession } from './playground/runtimeSession';
+export { configureRuntimeAssetCache, createRuntimeAssetCacheBackend, fetchPinnedRuntimeAsset, prefetchRuntimeAssets, resolveRuntimeAssetLockEntry, getRuntimeAssetCacheOptions, getRuntimeAssetCacheStats, clearRuntimeAssetCache, pruneRuntimeAssetCache, requestRuntimeAssetCachePersistence } from '@wasm-idle/core';
 export { isSharedArrayBufferAvailable, requireSharedArrayBuffer } from './playground/sharedBuffer';

package/dist/playground/assetBridge.d.ts

@@ -1,10 +1,14 @@
 import { type ResolvedRuntimeAssetConfig, type RuntimeAssetRuntime } from './assets';
-import { type ProgressLike } from '@wasm-idle/core';
+import { type RuntimeAssetCacheOptions, type ResolvedRuntimeAssetCacheOptions, 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;
+    private persistentCacheBaseline;
+    private readonly persistentCacheBySignal;
     private progress;
     private expectedAssets;
     private languageSysroots;
@@ -13,8 +17,10 @@ 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;
+    /** Apply one execution's policy without changing the configuration established by load(). */
+    setExecutionPersistentCache(override?: RuntimeAssetCacheOptions): ResolvedRuntimeAssetCacheOptions;
     rebind(worker: Worker, config: ResolvedRuntimeAssetConfig, progress?: ProgressLike, maxAssetBytes?: number, languageSysroots?: boolean): void;
     dispose(): void;
     resetProgress(progress?: ProgressLike): void;
@@ -23,10 +29,13 @@ export declare class WorkerAssetBridge {
     private sourceAssetByteLimit;
     handleMessage(event: MessageEvent<any>): boolean;
     private respond;
+    private loadVerifiedAsset;
+    private validateAssetRequest;
     private loadAsset;
     private verifyIntegrity;
     private normalizeLoaderResult;
     private fetchAsset;
+    private fetchAssetFromNetwork;
     private requireAllowedAssetUrl;
     private abortActiveLoads;
 }

package/dist/playground/assetBridge.js

@@ -1,9 +1,12 @@
 import { RUNTIME_LOAD_ASSETS } from './assets';
-import { ProtocolError, verifyRuntimeAssetIntegrity, verifyRuntimeAssetPair } from '@wasm-idle/core';
+import { ProtocolError, verifyRuntimeAssetIntegrity, verifyRuntimeAssetPair, readPersistentRuntimeAsset, writePersistentRuntimeAsset, resolveRuntimeAssetLockEntry, resolveRuntimeAssetCacheOptions } from '@wasm-idle/core';
 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,9 +375,12 @@ class RuntimeLoadProgress {
     }
 }
 export class WorkerAssetBridge {
+    cache;
     worker;
     runtime;
     config;
+    persistentCacheBaseline;
+    persistentCacheBySignal = new WeakMap();
     progress;
     expectedAssets;
     languageSysroots;
@@ -383,10 +389,12 @@ 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;
+        this.persistentCacheBaseline = resolveRuntimeAssetCacheOptions(config.persistentCache);
+        this.config = { ...config, persistentCache: this.persistentCacheBaseline };
         this.maxAssetBytes = requireBridgeMaxAssetBytes(maxAssetBytes);
         this.languageSysroots = canUseClangLanguageSysroots(runtime, config, languageSysroots);
         this.progress = new RuntimeLoadProgress(runtime, this.languageSysroots);
@@ -402,7 +410,17 @@ export class WorkerAssetBridge {
             this.config.loader === config.loader &&
             integrityKey(this.config) === integrityKey(config) &&
             allowedBaseUrlsKey(this.config) === allowedBaseUrlsKey(config) &&
-            this.config.useAssetBridge === config.useAssetBridge);
+            this.config.useAssetBridge === config.useAssetBridge &&
+            JSON.stringify(this.persistentCacheBaseline) ===
+                JSON.stringify(resolveRuntimeAssetCacheOptions(config.persistentCache)));
+    }
+    /** Apply one execution's policy without changing the configuration established by load(). */
+    setExecutionPersistentCache(override) {
+        if (this.state !== 'active')
+            throw new Error('Cannot configure an inactive worker asset bridge');
+        const cache = resolveRuntimeAssetCacheOptions(this.persistentCacheBaseline, override);
+        this.config = { ...this.config, persistentCache: cache };
+        return cache;
     }
     rebind(worker, config, progress, maxAssetBytes = this.maxAssetBytes, languageSysroots = this.languageSysroots) {
         if (this.state === 'disposed') {
@@ -425,7 +443,8 @@ export class WorkerAssetBridge {
                 throw new Error('Cannot rebind a disposed worker asset bridge');
             }
             this.worker = worker;
-            this.config = config;
+            this.persistentCacheBaseline = resolveRuntimeAssetCacheOptions(config.persistentCache);
+            this.config = { ...config, persistentCache: this.persistentCacheBaseline };
             this.maxAssetBytes = nextMaxAssetBytes;
             this.languageSysroots = nextLanguageSysroots;
             this.expectedAssets = expectedAssetsForRuntime(this.runtime, nextLanguageSysroots);
@@ -520,53 +539,75 @@ export class WorkerAssetBridge {
         const worker = this.worker;
         const generation = this.generation;
         const controller = new AbortController();
+        this.persistentCacheBySignal.set(controller.signal, resolveRuntimeAssetCacheOptions(this.config.persistentCache));
         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),
+                            persistentCache: this.persistentCacheBySignal.get(controller.signal),
+                            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 +630,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);
         }
@@ -753,6 +847,56 @@ export class WorkerAssetBridge {
         return null;
     }
     async fetchAsset(url, asset, signal, maxAssetBytes = this.sourceAssetByteLimit(asset)) {
+        const requestUrl = this.requireAllowedAssetUrl(asset, url);
+        const persistentCache = this.persistentCacheBySignal.get(signal) ?? this.config.persistentCache;
+        const configured = this.config.integrity?.[asset];
+        const expected = typeof configured === 'string' ? { sha256: configured } : configured;
+        const lock = this.config.assetPrefix
+            ? resolveRuntimeAssetLockEntry(requestUrl, {
+                assetRoot: this.config.baseUrl,
+                assetPrefix: this.config.assetPrefix
+            })
+            : undefined;
+        // Existing .gz receipts without a pair describe logical bytes, not stored gzip bytes.
+        const receipt = expected && (!asset.endsWith('.gz') || expected.uncompressedSha256) ? expected : lock;
+        const identity = receipt
+            ? {
+                url: requestUrl.href,
+                sha256: receipt.sha256,
+                bytes: receipt.bytes,
+                validationKey: JSON.stringify([
+                    'bridge-v1',
+                    this.config.baseUrl,
+                    allowedBaseUrlsKey(this.config),
+                    maxAssetBytes
+                ])
+            }
+            : undefined;
+        if (identity && (identity.bytes === undefined || identity.bytes <= maxAssetBytes)) {
+            const bytes = await readPersistentRuntimeAsset({
+                identity,
+                cache: persistentCache,
+                signal
+            });
+            if (bytes) {
+                requireRuntimeAssetSize(asset, bytes.byteLength, maxAssetBytes);
+                this.progress.update(asset, bytes.byteLength, bytes.byteLength);
+                return { bytes, mimeType: receipt?.mediaType, transferOwnership: true };
+            }
+        }
+        const loaded = await this.fetchAssetFromNetwork(url, asset, signal, maxAssetBytes);
+        if (identity && !loaded.contentEncoding) {
+            // Only checksum-matching bytes are published. Existing runtime validation still runs.
+            await writePersistentRuntimeAsset({
+                identity,
+                cache: persistentCache,
+                signal,
+                bytes: loaded.bytes
+            });
+        }
+        return loaded;
+    }
+    async fetchAssetFromNetwork(url, asset, signal, maxAssetBytes = this.sourceAssetByteLimit(asset)) {
         const requestUrl = this.requireAllowedAssetUrl(asset, url);
         if (signal.aborted)
             throw runtimeAssetAbortReason(signal);

package/dist/playground/assets.d.ts

@@ -1,3 +1,4 @@
+import { type RuntimeAssetCacheOptions } from '@wasm-idle/core';
 import { type DOuterAssetReceipts } from './dOuterAssets';
 import type { ElixirRuntimeAssetReceipts } from './elixirAssets';
 import { type FortranExecutionAssetReceipts } from './fortranAssets';
@@ -25,6 +26,7 @@ export type RuntimeAssetLoader = (request: RuntimeAssetLoadRequest) => RuntimeAs
 export type RuntimeAssetIntegrityEntry = CoreRuntimeAssetIntegrityEntry;
 export type RuntimeAssetIntegrityMap = Record<string, string | RuntimeAssetIntegrityEntry>;
 export interface RuntimeAssetConfig {
+    persistentCache?: import('@wasm-idle/core').RuntimeAssetCacheOptions;
     baseUrl?: string;
     loader?: RuntimeAssetLoader;
     loaderKey?: string;
@@ -139,11 +141,14 @@ export interface LispRuntimeAssetConfig {
     moduleUrl?: string;
     manifestUrl?: string;
     manifestFingerprint?: string;
+    /** Optional raw JSON byte receipt; distinct from the canonical manifest fingerprint. */
+    manifestReceipt?: RuntimeAssetIntegrityEntry;
 }
 export interface ResolvedLispRuntimeAssetConfig {
     moduleUrl: string;
     manifestUrl: string;
     manifestFingerprint: string;
+    manifestReceipt?: RuntimeAssetIntegrityEntry;
 }
 export interface RubyRuntimeAssetConfig {
     /** Keep full stdlib compatibility, but load its data separately from the core Wasm. */
@@ -563,6 +568,9 @@ export interface TinyGoRuntimeAssetLoaderRequest {
 export type TinyGoRuntimeAssetLoaderResult = RuntimeAssetDataResult | RuntimeAssetUrlResult | string | URL | ArrayBuffer | Uint8Array | Blob | null | undefined;
 export type TinyGoRuntimeAssetLoader = (request: TinyGoRuntimeAssetLoaderRequest) => TinyGoRuntimeAssetLoaderResult | Promise<TinyGoRuntimeAssetLoaderResult>;
 export interface ResolvedRuntimeAssetConfig {
+    persistentCache?: import('@wasm-idle/core').RuntimeAssetCacheOptions;
+    /** Built-in lock prefix; custom loaders use only explicitly supplied receipts. */
+    assetPrefix?: string;
     baseUrl: string;
     loader?: RuntimeAssetLoader;
     integrity?: RuntimeAssetIntegrityMap;
@@ -607,7 +615,7 @@ export declare const RUNTIME_LOAD_ASSETS: {
     clang: readonly ["runtime-manifest.v1.json", "bin/memfs.wasm.gz", "bin/clang.wasm.gz", "bin/lld.wasm.gz", "bin/sysroot.tar.gz"];
     clangd: readonly ["clangd.js", "clangd.wasm.gz"];
 };
-export declare function resolveRuntimeAssetConfig(runtime: RuntimeAssetRuntime, options: string | PlaygroundRuntimeAssets | undefined, currentUrl?: string): ResolvedRuntimeAssetConfig;
+export declare function resolveRuntimeAssetConfig(runtime: RuntimeAssetRuntime, options: string | PlaygroundRuntimeAssets | undefined, currentUrl?: string, callCache?: RuntimeAssetCacheOptions): ResolvedRuntimeAssetConfig;
 export declare function resolveRustCompilerUrl(options: string | PlaygroundRuntimeAssets | undefined, currentUrl?: string): string;
 export declare function resolveDebugRuntimeUrls(options: string | PlaygroundRuntimeAssets | undefined, currentUrl?: string): {
     baseUrl: string;

package/dist/playground/assets.js

@@ -1,4 +1,5 @@
 import { env as dynamicPublicEnv } from '$env/dynamic/public';
+import { resolveRuntimeAssetCacheOptions, resolveRuntimeAssetLockEntry } from '@wasm-idle/core';
 import { BUNDLED_CLANG_ASSET_INTEGRITY } from './clangAssetIntegrity';
 import { snapshotDOuterAssetConfig } from './dOuterAssets';
 import { snapshotFortranExecutionAssetReceipts } from './fortranAssets';
@@ -100,7 +101,21 @@ const RUNTIME_ASSET_FOLDERS = {
 const resolveRuntimeRootBaseUrl = (config, rootUrl = '', currentUrl = '') => config.resolveRootBaseUrl?.(rootUrl, currentUrl) ||
     resolveFolderRuntimeBaseUrl(config.folder, rootUrl, currentUrl);
 const resolveRuntimeConfiguredBaseUrl = (config, baseUrl, currentUrl = '') => config.resolveConfiguredBaseUrl?.(baseUrl, currentUrl) || normalizeBaseUrl(baseUrl, currentUrl);
-export function resolveRuntimeAssetConfig(runtime, options, currentUrl = '') {
+export function resolveRuntimeAssetConfig(runtime, options, currentUrl = '', callCache) {
+    const config = resolveRuntimeAssetConfigWithoutCache(runtime, options, currentUrl);
+    const runtimeConfig = typeof options === 'object' ? options?.[runtime] : undefined;
+    const persistentCache = resolveRuntimeAssetCacheOptions(typeof options === 'object' ? options?.persistentCache : undefined, runtimeConfig?.persistentCache, callCache);
+    const assetPrefix = !config.loader && !runtimeConfig?.baseUrl
+        ? RUNTIME_ASSET_FOLDERS[runtime].folder
+        : undefined;
+    return {
+        ...config,
+        persistentCache,
+        assetPrefix,
+        useAssetBridge: config.useAssetBridge || (persistentCache.enabled && !!assetPrefix)
+    };
+}
+function resolveRuntimeAssetConfigWithoutCache(runtime, options, currentUrl = '') {
     const runtimeFolder = RUNTIME_ASSET_FOLDERS[runtime];
     if (typeof options === 'string') {
         const integrity = resolveRuntimeAssetIntegrity(runtime, undefined);
@@ -733,12 +748,21 @@ export function resolveLispRuntimeAssetConfig(options, currentUrl = '') {
     const configuredFingerprint = configured?.manifestFingerprint?.trim() ||
         (publicEnv.PUBLIC_WASM_LISP_MANIFEST_FINGERPRINT || '').trim();
     const usesBundledRoot = !configuredModuleUrl && !publicModuleUrl && rootUrl !== undefined;
+    const manifestUrl = configuredManifestUrl
+        ? resolveConfiguredUrl(configuredManifestUrl, currentUrl)
+        : deriveLispManifestUrl(moduleUrl, currentUrl);
+    const manifestReceipt = configured?.manifestReceipt ??
+        (usesBundledRoot && !configuredManifestUrl && !configuredFingerprint
+            ? resolveRuntimeAssetLockEntry(manifestUrl, {
+                assetRoot: new URL('./', new URL(moduleUrl, currentUrl || 'http://localhost/')),
+                assetPrefix: 'wasm-lisp'
+            })
+            : undefined);
     return {
         moduleUrl,
-        manifestUrl: configuredManifestUrl
-            ? resolveConfiguredUrl(configuredManifestUrl, currentUrl)
-            : deriveLispManifestUrl(moduleUrl, currentUrl),
-        manifestFingerprint: configuredFingerprint || (usesBundledRoot ? WASM_LISP_ASSET_VERSION : '')
+        manifestUrl,
+        manifestFingerprint: configuredFingerprint || (usesBundledRoot ? WASM_LISP_ASSET_VERSION : ''),
+        ...(manifestReceipt ? { manifestReceipt: Object.freeze({ ...manifestReceipt }) } : {})
     };
 }
 const RUBY_RUNTIME_CONFIG_KEYS = [

package/dist/playground/awk.js

@@ -40,6 +40,7 @@ class Awk extends StaticWorkerRuntimeSandbox {
                     manifestUrl: resolved.manifestUrl,
                     profile,
                     limits: context.limits,
+                    persistentCache: context.persistentCache,
                     signal: context.signal,
                     reportProgress(progress) {
                         loadedByAsset.set(progress.assetKey, progress.loadedBytes);

package/dist/playground/bash.d.ts

@@ -14,6 +14,7 @@ declare class Bash implements Sandbox {
     private activeOperation;
     private readyWorker;
     private loadedConfig;
+    private persistentCache?;
     private requestUid;
     private sessionUid;
     private disposed;