@miden-sdk/miden-sdk 0.14.1 → 0.14.2

package/dist/api-types.d.ts

@@ -29,6 +29,7 @@ import type {
   AuthSecretKey,
   AccountStorageRequirements,
   TransactionScript,
+  NoteScript,
   AdviceInputs,
   FeltArray,
 } from "./crates/miden_client_web";
@@ -36,6 +37,13 @@ import type {
 // Import the full namespace for the MidenArrayConstructors type
 import type * as WasmExports from "./crates/miden_client_web";
 
+// Source of truth for standalone-wrapper return types. By deriving them from
+// the wasm-bindgen-generated namespace (rather than hand-writing `: Note`),
+// the declarations below cannot drift from the actual runtime behavior — the
+// exact class of bug behind #2042. Any forwarder-style wrapper should follow
+// the same pattern: `ReturnType<WasmModule["Class"]["method"]>`.
+type WasmModule = typeof import("./crates/miden_client_web");
+
 // ════════════════════════════════════════════════════════════════
 // Callback types for external keystore support
 // ════════════════════════════════════════════════════════════════
@@ -105,6 +113,18 @@ export declare const StorageMode: {
 /** Union of valid StorageMode string values. */
 export type StorageMode = "public" | "private" | "network";
 
+/**
+ * Library linking mode for script compilation.
+ * Use `Linking.Dynamic` or `Linking.Static` instead of raw strings.
+ */
+export declare const Linking: {
+  readonly Dynamic: "dynamic";
+  readonly Static: "static";
+};
+
+/** Union of valid Linking string values. */
+export type Linking = "dynamic" | "static";
+
 /**
  * Union of all values in the AccountType const.
  */
@@ -770,10 +790,10 @@ export interface CompileTxScriptLibrary {
   /** MASM source code for the library. */
   code: string;
   /**
-   * `"dynamic"` (default) — procedures are linked via DYNCALL at runtime.
-   * `"static"` — procedures are inlined at compile time.
+   * `Linking.Dynamic` (default) — procedures are linked via DYNCALL at runtime.
+   * `Linking.Static` — procedures are inlined at compile time.
    */
-  linking?: "dynamic" | "static";
+  linking?: Linking;
 }
 
 export interface CompileTxScriptOptions {
@@ -783,7 +803,33 @@ export interface CompileTxScriptOptions {
   libraries?: CompileTxScriptLibrary[];
 }
 
-export interface CompilerResource {
+export interface CompileNoteScriptOptions {
+  /** MASM source code for the note script. */
+  code: string;
+  /** Component libraries to link. */
+  libraries?: CompileTxScriptLibrary[];
+}
+
+export declare class CompilerResource {
+  /**
+   * Create a standalone `CompilerResource` over a WASM `WebClient` proxy.
+   *
+   * Normally accessed as `client.compile` on a `MidenClient`; construct
+   * directly only when you need the compiler surface without the full
+   * `MidenClient` wrapper (e.g. inside a framework-specific hook).
+   *
+   * @param inner - The WASM `WebClient` (e.g. the `WasmWebClient` proxy).
+   * @param getWasm - Async accessor for the WASM module, used to reach
+   *   `AccountComponent.compile` at runtime. `getWasmOrThrow` satisfies this.
+   * @param client - Optional wrapper with `assertNotTerminated()`; used
+   *   internally by `MidenClient` and may be omitted by external callers.
+   */
+  constructor(
+    inner: WasmExports.WebClient,
+    getWasm: () => Promise<typeof WasmExports>,
+    client?: { assertNotTerminated(): void } | null
+  );
+
   /**
    * Compile MASM source into an AccountComponent.
    *
@@ -796,6 +842,12 @@ export interface CompilerResource {
    * @param options - Script source code and optional libraries to link.
    */
   txScript(options: CompileTxScriptOptions): Promise<TransactionScript>;
+  /**
+   * Compile MASM source into a NoteScript.
+   *
+   * @param options - Script source code and optional libraries to link.
+   */
+  noteScript(options: CompileNoteScriptOptions): Promise<NoteScript>;
 }
 
 export interface TagsResource {
@@ -908,13 +960,19 @@ export declare class MidenClient {
 // ════════════════════════════════════════════════════════════════
 
 /** Creates a P2ID (Pay-to-ID) note. */
-export declare function createP2IDNote(options: NoteOptions): OutputNote;
+export declare function createP2IDNote(
+  options: NoteOptions
+): ReturnType<WasmModule["Note"]["createP2IDNote"]>;
 
 /** Creates a P2IDE (Pay-to-ID with Expiration) note. */
-export declare function createP2IDENote(options: P2IDEOptions): OutputNote;
+export declare function createP2IDENote(
+  options: P2IDEOptions
+): ReturnType<WasmModule["Note"]["createP2IDENote"]>;
 
 /** Builds a swap tag for note matching. Returns a NoteTag (use `.asU32()` for the numeric value). */
-export declare function buildSwapTag(options: BuildSwapTagOptions): NoteTag;
+export declare function buildSwapTag(
+  options: BuildSwapTagOptions
+): ReturnType<WasmModule["WebClient"]["buildSwapTag"]>;
 
 /** Exports the entire contents of an IndexedDB store as a JSON string. */
 export declare function exportStore(storeName: string): Promise<string>;

package/dist/index.js

@@ -1,5 +1,5 @@
 import loadWasm from './wasm.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-BZOulF0S.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-D44KIErf.js';
 
 const WorkerAction = Object.freeze({
   INIT: "init",
@@ -1387,7 +1387,7 @@ class CompilerResource {
   #getWasm;
   #client;
 
-  constructor(inner, getWasm, client) {
+  constructor(inner, getWasm, client = null) {
     this.#inner = inner;
     this.#getWasm = getWasm;
     this.#client = client;
@@ -1400,7 +1400,7 @@ class CompilerResource {
    * @returns {Promise<AccountComponent>}
    */
   async component({ code, slots = [], supportAllTypes = true }) {
-    this.#client.assertNotTerminated();
+    this.#client?.assertNotTerminated();
     const wasm = await this.#getWasm();
     const builder = this.#inner.createCodeBuilder();
     const compiled = builder.compileAccountComponentCode(code);
@@ -1415,26 +1415,45 @@ class CompilerResource {
    * @returns {Promise<TransactionScript>}
    */
   async txScript({ code, libraries = [] }) {
-    this.#client.assertNotTerminated();
+    this.#client?.assertNotTerminated();
     // Ensure WASM is initialized (result unused — only #inner needs it)
     await this.#getWasm();
     const builder = this.#inner.createCodeBuilder();
-    for (const lib of libraries) {
-      if (lib && typeof lib.namespace === "string") {
-        // Inline { namespace, code, linking? } — build and link automatically
-        const built = builder.buildLibrary(lib.namespace, lib.code);
-        if (lib.linking === "static") {
-          builder.linkStaticLibrary(built);
-        } else {
-          // Default: "dynamic" — matches existing tutorial behavior
-          builder.linkDynamicLibrary(built);
-        }
+    linkLibraries(builder, libraries);
+    return builder.compileTxScript(code);
+  }
+
+  /**
+   * Compiles a note script, optionally linking named libraries inline.
+   *
+   * @param {{ code: string, libraries?: Array<{ namespace: string, code: string, linking?: "dynamic" | "static" }> }} opts
+   * @returns {Promise<NoteScript>}
+   */
+  async noteScript({ code, libraries = [] }) {
+    this.#client?.assertNotTerminated();
+    await this.#getWasm();
+    const builder = this.#inner.createCodeBuilder();
+    linkLibraries(builder, libraries);
+    return builder.compileNoteScript(code);
+  }
+}
+
+// Builds and links each library entry against `builder`. Inline
+// `{ namespace, code, linking? }` entries are built via `buildLibrary` and
+// linked according to `linking` (defaulting to dynamic, matching tutorial
+// behavior). Pre-built library objects are linked dynamically.
+function linkLibraries(builder, libraries) {
+  for (const lib of libraries) {
+    if (lib && typeof lib.namespace === "string") {
+      const built = builder.buildLibrary(lib.namespace, lib.code);
+      if (lib.linking === "static") {
+        builder.linkStaticLibrary(built);
       } else {
-        // Pre-built library object — link dynamically
-        builder.linkDynamicLibrary(lib);
+        builder.linkDynamicLibrary(built);
       }
+    } else {
+      builder.linkDynamicLibrary(lib);
     }
-    return builder.compileTxScript(code);
   }
 }
 
@@ -1932,6 +1951,11 @@ const StorageMode = Object.freeze({
   Network: "network",
 });
 
+const Linking = Object.freeze({
+  Dynamic: "dynamic",
+  Static: "static",
+});
+
 const MOCK_STORE_NAME = "mock_client_db";
 
 const buildTypedArraysExport = (exportObject) => {
@@ -2052,6 +2076,46 @@ function createClientProxy(instance) {
 }
 
 class WebClient {
+  /**
+   * Controls which worker variant is spawned when a WebClient is constructed.
+   *
+   * - `"auto"` (default): pick `classic` on Safari/WKWebView (where module
+   *   workers have a very slow cold start), `module` everywhere else.
+   * - `"module"`: always use the `.mjs` ES-module worker. Required for webpack
+   *   5 / Next.js consumers so the asset tracer can see the WASM URL.
+   * - `"classic"`: always use the `.js` classic-script worker. Required on
+   *   Safari/WKWebView. Set this if your consumer bundler (or your host app)
+   *   does not support module workers.
+   *
+   * Set before the first `WebClient.createClient(...)` call.
+   */
+  static workerMode = "auto";
+
+  /**
+   * Decide between the module and classic worker variants based on
+   * `WebClient.workerMode` and (when `auto`) the current user agent.
+   * @returns {boolean} true when the classic script should be used.
+   * @private
+   */
+  static _shouldUseClassicWorker() {
+    const mode = WebClient.workerMode;
+    if (mode === "module") return false;
+    if (mode === "classic") return true;
+    // auto: classic on Safari/WKWebView, module everywhere else.
+    const ua =
+      typeof navigator !== "undefined" && navigator.userAgent
+        ? navigator.userAgent
+        : "";
+    // Chromium-based browsers (Chrome, Edge, Brave, Opera, Chromium-based
+    // Android WebView) handle module workers fine.
+    if (/Chrome\/|Chromium\//.test(ua)) return false;
+    // Safari (desktop + iOS) and WKWebView-without-Chrome (e.g. Capacitor host)
+    // both have AppleWebKit but no Chrome/Chromium in the UA. Prefer classic.
+    if (/AppleWebKit/.test(ua)) return true;
+    // Firefox, jsdom, node without navigator, etc. — module worker is fine.
+    return false;
+  }
+
   /**
    * Create a WebClient wrapper.
    *
@@ -2098,13 +2162,36 @@ class WebClient {
     // Check if Web Workers are available.
     if (typeof Worker !== "undefined") {
       console.log("WebClient: Web Workers are available.");
-      // Create the worker.
-      // Classic worker (not module) — the worker is built as a self-contained
-      // async-IIFE by the rollup config, compatible with all browsers including
-      // Safari/WKWebView which is extremely slow with module workers.
-      this.worker = new Worker(
-        new URL("./workers/web-client-methods-worker.js", import.meta.url)
-      );
+      // Pick between the module and classic worker variants at runtime — see
+      // `WebClient.workerMode` below. Both branches keep the
+      // `new Worker(new URL("...", import.meta.url), ...)` form fully literal:
+      // webpack 5's new-worker detector is PURELY SYNTACTIC and only triggers
+      // a proper worker sub-compilation (with asset+chunk tracing into the
+      // Cargo glue and the sibling WASM) when it sees that exact pattern
+      // spelled inline. Hoisting either URL into a variable downgrades the
+      // detection to a plain "copy file as asset" — which in turn makes the
+      // worker's `await import("./Cargo-*.js")` 404 because webpack never
+      // emitted a chunk for it. The bit of duplication here is load-bearing.
+      //
+      // - module (`.module.js` with `{ type: "module" }`): `import.meta.url`
+      //   inside the Cargo glue is preserved so webpack/Vite can resolve the
+      //   WASM URL statically. Preferred everywhere EXCEPT Safari/WKWebView.
+      // - classic (`.js`, no options): self-contained async IIFE with
+      //   `import.meta.url` rewritten to `self.location.href`; the only form
+      //   Safari/WKWebView can cold-start in a reasonable time.
+      if (WebClient._shouldUseClassicWorker()) {
+        this.worker = new Worker(
+          new URL("./workers/web-client-methods-worker.js", import.meta.url)
+        );
+      } else {
+        this.worker = new Worker(
+          new URL(
+            "./workers/web-client-methods-worker.module.js",
+            import.meta.url
+          ),
+          { type: "module" }
+        );
+      }
 
       // Map to track pending worker requests.
       this.pendingRequests = new Map();
@@ -2901,5 +2988,5 @@ MidenClient._MockWasmWebClient = MockWebClient;
 MidenClient._getWasmOrThrow = getWasmOrThrow;
 _setWebClient(WebClient);
 
-export { AccountType, AuthScheme, MidenArrays, MidenClient, MockWebClient as MockWasmWebClient, NoteVisibility, StorageMode, WebClient as WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, getWasmOrThrow };
+export { AccountType, AuthScheme, CompilerResource, Linking, MidenArrays, MidenClient, MockWebClient as MockWasmWebClient, NoteVisibility, StorageMode, WebClient as WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, getWasmOrThrow };
 //# sourceMappingURL=index.js.map