@caatinga/client 2.3.0 → 2.4.0

package/dist/index.cjs

@@ -279,10 +279,10 @@ function createDefaultBindingAdapter(binding) {
 }
 
 // src/client/create-caatinga-client.ts
-var import_browser8 = require("@caatinga/core/browser");
+var import_browser9 = require("@caatinga/core/browser");
 
 // src/client/caatinga-contract-client.ts
-var import_browser7 = require("@caatinga/core/browser");
+var import_browser8 = require("@caatinga/core/browser");
 
 // src/xdr/build-xdr.ts
 var import_browser4 = require("@caatinga/core/browser");
@@ -383,28 +383,62 @@ function splitReadArgsAndOptions(argsOrOptions, maybeOptions) {
 var import_browser5 = require("@caatinga/core/browser");
 async function prepareReadTransaction(transaction, contractName, method, rpcUrl) {
   const candidate = transaction;
-  if (typeof candidate.prepare !== "function") {
-    return transaction;
+  if (typeof candidate.prepare === "function") {
+    try {
+      return await candidate.prepare.call(transaction);
+    } catch (error) {
+      if (error instanceof import_browser5.CaatingaError) {
+        throw error;
+      }
+      throw new import_browser5.CaatingaError(
+        `Failed to prepare XDR for "${contractName}.${method}".`,
+        import_browser5.CaatingaErrorCode.XDR_PREPARE_FAILED,
+        `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
+        error
+      );
+    }
   }
-  try {
-    return await candidate.prepare.call(transaction);
-  } catch (error) {
-    if (error instanceof import_browser5.CaatingaError) {
-      throw error;
+  if (typeof candidate.simulate === "function") {
+    try {
+      return await candidate.simulate.call(transaction);
+    } catch (error) {
+      if (error instanceof import_browser5.CaatingaError) {
+        throw error;
+      }
+      throw new import_browser5.CaatingaError(
+        `Failed to simulate "${contractName}.${method}".`,
+        import_browser5.CaatingaErrorCode.XDR_PREPARE_FAILED,
+        `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
+        error
+      );
     }
+  }
+  return transaction;
+}
+function isStellarContractResult(value) {
+  return value !== null && typeof value === "object" && typeof value.isOk === "function" && typeof value.unwrap === "function";
+}
+function normalizeSimulationValue(value, contractName, method) {
+  if (!isStellarContractResult(value)) {
+    return value;
+  }
+  if (value.isErr()) {
+    const err = value.unwrapErr();
+    const message = err !== null && typeof err === "object" && "message" in err ? String(err.message) : String(err);
     throw new import_browser5.CaatingaError(
-      `Failed to prepare XDR for "${contractName}.${method}".`,
-      import_browser5.CaatingaErrorCode.XDR_PREPARE_FAILED,
-      `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
-      error
+      `Simulation for "${contractName}.${method}" returned a contract error: ${message}.`,
+      import_browser5.CaatingaErrorCode.XDR_RESULT_FAILED,
+      "Check contract inputs and binding argument encoding.",
+      err
     );
   }
+  return value.unwrap();
 }
 function readSimulationResult(raw, contractName, method) {
   if (raw !== null && typeof raw === "object" && "result" in raw) {
     const result = raw.result;
     if (result !== void 0) {
-      return result;
+      return normalizeSimulationValue(result, contractName, method);
     }
   }
   throw new import_browser5.CaatingaError(
@@ -415,7 +449,38 @@ function readSimulationResult(raw, contractName, method) {
 }
 
 // src/client/transaction-submit.ts
+var import_browser7 = require("@caatinga/core/browser");
+
+// src/client/read-call-error.ts
 var import_browser6 = require("@caatinga/core/browser");
+
+// src/client/read-call-pattern.ts
+var READ_CALL_FAILURE_REGEX = /this is a read call|read-only/i;
+
+// src/client/read-call-error.ts
+function enrichReadCallInvokeError(error, contractName, method) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = error instanceof import_browser6.CaatingaError ? error.hint ?? "" : "";
+  const haystack = `${message}
+${hint}`;
+  if (!READ_CALL_FAILURE_REGEX.test(haystack)) {
+    return null;
+  }
+  return new import_browser6.CaatingaError(
+    `Failed to submit XDR for "${contractName}.${method}".`,
+    import_browser6.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+    [
+      `"${contractName}.${method}" is a read-only contract method.`,
+      "Use read() or simulate() instead of invoke():",
+      `  client.contract("${contractName}").read("${method}")`,
+      `  client.contract("${contractName}").simulate("${method}")`,
+      "Pass method args as the second argument to read() when the contract method takes parameters."
+    ].join("\n"),
+    error
+  );
+}
+
+// src/client/transaction-submit.ts
 async function submitTransaction(transaction, signTransaction, contractName, method, rpcUrl) {
   const candidate = transaction;
   if (typeof candidate.signAndSend === "function") {
@@ -424,12 +489,16 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof import_browser6.CaatingaError) {
+      if (error instanceof import_browser7.CaatingaError) {
         throw error;
       }
-      throw new import_browser6.CaatingaError(
+      const readCallError = enrichReadCallInvokeError(error, contractName, method);
+      if (readCallError) {
+        throw readCallError;
+      }
+      throw new import_browser7.CaatingaError(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        import_browser6.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+        import_browser7.CaatingaErrorCode.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
@@ -441,20 +510,24 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof import_browser6.CaatingaError) {
+      if (error instanceof import_browser7.CaatingaError) {
         throw error;
       }
-      throw new import_browser6.CaatingaError(
+      const readCallError = enrichReadCallInvokeError(error, contractName, method);
+      if (readCallError) {
+        throw readCallError;
+      }
+      throw new import_browser7.CaatingaError(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        import_browser6.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+        import_browser7.CaatingaErrorCode.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
     }
   }
-  throw new import_browser6.CaatingaError(
+  throw new import_browser7.CaatingaError(
     `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
-    import_browser6.CaatingaErrorCode.XDR_SUBMIT_FAILED,
+    import_browser7.CaatingaErrorCode.XDR_SUBMIT_FAILED,
     "Regenerate bindings or provide a compatible binding adapter."
   );
 }
@@ -468,9 +541,9 @@ function assertSubmitResultRecognized(raw, contractName, method) {
   if (hasTransactionId || hasResult) {
     return;
   }
-  throw new import_browser6.CaatingaError(
+  throw new import_browser7.CaatingaError(
     `Submit returned an unrecognized payload for "${contractName}.${method}".`,
-    import_browser6.CaatingaErrorCode.XDR_RESULT_FAILED,
+    import_browser7.CaatingaErrorCode.XDR_RESULT_FAILED,
     "Expected txHash, transactionHash, hash, sendTransactionResponse.hash, or result on the submit response. Use debugRaw to inspect the binding output."
   );
 }
@@ -535,20 +608,20 @@ var CaatingaContractClient = class {
           })
         );
       } catch (error) {
-        if (error instanceof import_browser7.CaatingaError) {
+        if (error instanceof import_browser8.CaatingaError) {
           throw error;
         }
-        throw new import_browser7.CaatingaError(
+        throw new import_browser8.CaatingaError(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          import_browser7.CaatingaErrorCode.XDR_SIGN_FAILED,
+          import_browser8.CaatingaErrorCode.XDR_SIGN_FAILED,
           "Connect a wallet and approve the transaction.",
           error
         );
       }
       if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
-        throw new import_browser7.CaatingaError(
+        throw new import_browser8.CaatingaError(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          import_browser7.CaatingaErrorCode.XDR_SIGN_FAILED,
+          import_browser8.CaatingaErrorCode.XDR_SIGN_FAILED,
           "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
           signedXdr
         );
@@ -563,9 +636,9 @@ var CaatingaContractClient = class {
       this.config.network.rpcUrl
     );
     if (typeof transaction.signAndSend === "function" && signedXdr === void 0) {
-      throw new import_browser7.CaatingaError(
+      throw new import_browser8.CaatingaError(
         `Failed to sign XDR for "${this.contractName}.${method}".`,
-        import_browser7.CaatingaErrorCode.XDR_SIGN_FAILED,
+        import_browser8.CaatingaErrorCode.XDR_SIGN_FAILED,
         "Wallet returned an empty or invalid signed XDR. The generated transaction did not request a wallet signature."
       );
     }
@@ -625,12 +698,12 @@ var CaatingaContractClient = class {
         () => this.config.wallet.getPublicKey()
       );
     } catch (error) {
-      if (error instanceof import_browser7.CaatingaError) {
+      if (error instanceof import_browser8.CaatingaError) {
         throw error;
       }
-      throw new import_browser7.CaatingaError(
+      throw new import_browser8.CaatingaError(
         `Wallet is not connected or the public key is unavailable for "${this.contractName}".`,
-        import_browser7.CaatingaErrorCode.WALLET_NOT_CONNECTED,
+        import_browser8.CaatingaErrorCode.WALLET_NOT_CONNECTED,
         "Connect the wallet and grant account access, then retry.",
         error
       );
@@ -652,9 +725,9 @@ function createCaatingaClient(config) {
     contract(contractName) {
       const registration = config.contracts[contractName];
       if (!registration) {
-        throw new import_browser8.CaatingaError(
+        throw new import_browser9.CaatingaError(
           `Contract "${contractName}" is not registered.`,
-          import_browser8.CaatingaErrorCode.CONTRACT_NOT_FOUND,
+          import_browser9.CaatingaErrorCode.CONTRACT_NOT_FOUND,
           "Add the contract binding to createCaatingaClient()."
         );
       }

package/dist/index.js

@@ -89,10 +89,10 @@ function createDefaultBindingAdapter(binding) {
 }
 
 // src/client/create-caatinga-client.ts
-import { CaatingaError as CaatingaError7, CaatingaErrorCode as CaatingaErrorCode7 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError8, CaatingaErrorCode as CaatingaErrorCode8 } from "@caatinga/core/browser";
 
 // src/client/caatinga-contract-client.ts
-import { CaatingaError as CaatingaError6, CaatingaErrorCode as CaatingaErrorCode6 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError7, CaatingaErrorCode as CaatingaErrorCode7 } from "@caatinga/core/browser";
 
 // src/xdr/build-xdr.ts
 import { CaatingaError as CaatingaError3, CaatingaErrorCode as CaatingaErrorCode3 } from "@caatinga/core/browser";
@@ -193,28 +193,62 @@ function splitReadArgsAndOptions(argsOrOptions, maybeOptions) {
 import { CaatingaError as CaatingaError4, CaatingaErrorCode as CaatingaErrorCode4 } from "@caatinga/core/browser";
 async function prepareReadTransaction(transaction, contractName, method, rpcUrl) {
   const candidate = transaction;
-  if (typeof candidate.prepare !== "function") {
-    return transaction;
+  if (typeof candidate.prepare === "function") {
+    try {
+      return await candidate.prepare.call(transaction);
+    } catch (error) {
+      if (error instanceof CaatingaError4) {
+        throw error;
+      }
+      throw new CaatingaError4(
+        `Failed to prepare XDR for "${contractName}.${method}".`,
+        CaatingaErrorCode4.XDR_PREPARE_FAILED,
+        `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
+        error
+      );
+    }
   }
-  try {
-    return await candidate.prepare.call(transaction);
-  } catch (error) {
-    if (error instanceof CaatingaError4) {
-      throw error;
+  if (typeof candidate.simulate === "function") {
+    try {
+      return await candidate.simulate.call(transaction);
+    } catch (error) {
+      if (error instanceof CaatingaError4) {
+        throw error;
+      }
+      throw new CaatingaError4(
+        `Failed to simulate "${contractName}.${method}".`,
+        CaatingaErrorCode4.XDR_PREPARE_FAILED,
+        `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
+        error
+      );
     }
+  }
+  return transaction;
+}
+function isStellarContractResult(value) {
+  return value !== null && typeof value === "object" && typeof value.isOk === "function" && typeof value.unwrap === "function";
+}
+function normalizeSimulationValue(value, contractName, method) {
+  if (!isStellarContractResult(value)) {
+    return value;
+  }
+  if (value.isErr()) {
+    const err = value.unwrapErr();
+    const message = err !== null && typeof err === "object" && "message" in err ? String(err.message) : String(err);
     throw new CaatingaError4(
-      `Failed to prepare XDR for "${contractName}.${method}".`,
-      CaatingaErrorCode4.XDR_PREPARE_FAILED,
-      `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
-      error
+      `Simulation for "${contractName}.${method}" returned a contract error: ${message}.`,
+      CaatingaErrorCode4.XDR_RESULT_FAILED,
+      "Check contract inputs and binding argument encoding.",
+      err
     );
   }
+  return value.unwrap();
 }
 function readSimulationResult(raw, contractName, method) {
   if (raw !== null && typeof raw === "object" && "result" in raw) {
     const result = raw.result;
     if (result !== void 0) {
-      return result;
+      return normalizeSimulationValue(result, contractName, method);
     }
   }
   throw new CaatingaError4(
@@ -225,7 +259,38 @@ function readSimulationResult(raw, contractName, method) {
 }
 
 // src/client/transaction-submit.ts
+import { CaatingaError as CaatingaError6, CaatingaErrorCode as CaatingaErrorCode6 } from "@caatinga/core/browser";
+
+// src/client/read-call-error.ts
 import { CaatingaError as CaatingaError5, CaatingaErrorCode as CaatingaErrorCode5 } from "@caatinga/core/browser";
+
+// src/client/read-call-pattern.ts
+var READ_CALL_FAILURE_REGEX = /this is a read call|read-only/i;
+
+// src/client/read-call-error.ts
+function enrichReadCallInvokeError(error, contractName, method) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = error instanceof CaatingaError5 ? error.hint ?? "" : "";
+  const haystack = `${message}
+${hint}`;
+  if (!READ_CALL_FAILURE_REGEX.test(haystack)) {
+    return null;
+  }
+  return new CaatingaError5(
+    `Failed to submit XDR for "${contractName}.${method}".`,
+    CaatingaErrorCode5.XDR_SUBMIT_FAILED,
+    [
+      `"${contractName}.${method}" is a read-only contract method.`,
+      "Use read() or simulate() instead of invoke():",
+      `  client.contract("${contractName}").read("${method}")`,
+      `  client.contract("${contractName}").simulate("${method}")`,
+      "Pass method args as the second argument to read() when the contract method takes parameters."
+    ].join("\n"),
+    error
+  );
+}
+
+// src/client/transaction-submit.ts
 async function submitTransaction(transaction, signTransaction, contractName, method, rpcUrl) {
   const candidate = transaction;
   if (typeof candidate.signAndSend === "function") {
@@ -234,12 +299,16 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof CaatingaError5) {
+      if (error instanceof CaatingaError6) {
         throw error;
       }
-      throw new CaatingaError5(
+      const readCallError = enrichReadCallInvokeError(error, contractName, method);
+      if (readCallError) {
+        throw readCallError;
+      }
+      throw new CaatingaError6(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        CaatingaErrorCode5.XDR_SUBMIT_FAILED,
+        CaatingaErrorCode6.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
@@ -251,20 +320,24 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof CaatingaError5) {
+      if (error instanceof CaatingaError6) {
         throw error;
       }
-      throw new CaatingaError5(
+      const readCallError = enrichReadCallInvokeError(error, contractName, method);
+      if (readCallError) {
+        throw readCallError;
+      }
+      throw new CaatingaError6(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        CaatingaErrorCode5.XDR_SUBMIT_FAILED,
+        CaatingaErrorCode6.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
     }
   }
-  throw new CaatingaError5(
+  throw new CaatingaError6(
     `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
-    CaatingaErrorCode5.XDR_SUBMIT_FAILED,
+    CaatingaErrorCode6.XDR_SUBMIT_FAILED,
     "Regenerate bindings or provide a compatible binding adapter."
   );
 }
@@ -278,9 +351,9 @@ function assertSubmitResultRecognized(raw, contractName, method) {
   if (hasTransactionId || hasResult) {
     return;
   }
-  throw new CaatingaError5(
+  throw new CaatingaError6(
     `Submit returned an unrecognized payload for "${contractName}.${method}".`,
-    CaatingaErrorCode5.XDR_RESULT_FAILED,
+    CaatingaErrorCode6.XDR_RESULT_FAILED,
     "Expected txHash, transactionHash, hash, sendTransactionResponse.hash, or result on the submit response. Use debugRaw to inspect the binding output."
   );
 }
@@ -345,20 +418,20 @@ var CaatingaContractClient = class {
           })
         );
       } catch (error) {
-        if (error instanceof CaatingaError6) {
+        if (error instanceof CaatingaError7) {
           throw error;
         }
-        throw new CaatingaError6(
+        throw new CaatingaError7(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          CaatingaErrorCode6.XDR_SIGN_FAILED,
+          CaatingaErrorCode7.XDR_SIGN_FAILED,
           "Connect a wallet and approve the transaction.",
           error
         );
       }
       if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
-        throw new CaatingaError6(
+        throw new CaatingaError7(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          CaatingaErrorCode6.XDR_SIGN_FAILED,
+          CaatingaErrorCode7.XDR_SIGN_FAILED,
           "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
           signedXdr
         );
@@ -373,9 +446,9 @@ var CaatingaContractClient = class {
       this.config.network.rpcUrl
     );
     if (typeof transaction.signAndSend === "function" && signedXdr === void 0) {
-      throw new CaatingaError6(
+      throw new CaatingaError7(
         `Failed to sign XDR for "${this.contractName}.${method}".`,
-        CaatingaErrorCode6.XDR_SIGN_FAILED,
+        CaatingaErrorCode7.XDR_SIGN_FAILED,
         "Wallet returned an empty or invalid signed XDR. The generated transaction did not request a wallet signature."
       );
     }
@@ -435,12 +508,12 @@ var CaatingaContractClient = class {
         () => this.config.wallet.getPublicKey()
       );
     } catch (error) {
-      if (error instanceof CaatingaError6) {
+      if (error instanceof CaatingaError7) {
         throw error;
       }
-      throw new CaatingaError6(
+      throw new CaatingaError7(
         `Wallet is not connected or the public key is unavailable for "${this.contractName}".`,
-        CaatingaErrorCode6.WALLET_NOT_CONNECTED,
+        CaatingaErrorCode7.WALLET_NOT_CONNECTED,
         "Connect the wallet and grant account access, then retry.",
         error
       );
@@ -462,9 +535,9 @@ function createCaatingaClient(config) {
     contract(contractName) {
       const registration = config.contracts[contractName];
       if (!registration) {
-        throw new CaatingaError7(
+        throw new CaatingaError8(
           `Contract "${contractName}" is not registered.`,
-          CaatingaErrorCode7.CONTRACT_NOT_FOUND,
+          CaatingaErrorCode8.CONTRACT_NOT_FOUND,
           "Add the contract binding to createCaatingaClient()."
         );
       }

package/dist/vite.cjs

@@ -0,0 +1,93 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  walletStubOverrides: () => walletStubOverrides,
+  walletStubPnpmWorkspaceYaml: () => walletStubPnpmWorkspaceYaml,
+  walletStubViteAliases: () => walletStubViteAliases
+});
+module.exports = __toCommonJS(vite_exports);
+
+// src/vite/wallet-stubs.ts
+var import_node_path = __toESM(require("path"), 1);
+function walletStubOverrides(stubsDir = "./src/stubs") {
+  const posixStubsDir = stubsDir.split(import_node_path.default.sep).join("/");
+  return {
+    uuid: "^14.0.0",
+    "@creit.tech/stellar-wallets-kit": {
+      "@trezor/connect-web": `file:${posixStubsDir}/empty-wallet-dep`,
+      "@trezor/connect-plugin-stellar": `file:${posixStubsDir}/empty-wallet-dep`,
+      "@hot-wallet/sdk": `file:${posixStubsDir}/hot-wallet-sdk`
+    },
+    "@reown/appkit-utils": {
+      "@safe-global/safe-apps-sdk": "-",
+      "@safe-global/safe-apps-provider": "-"
+    },
+    "@safe-global/safe-apps-sdk": {
+      "@safe-global/safe-gateway-typescript-sdk": "-"
+    }
+  };
+}
+function walletStubViteAliases(stubsDir) {
+  const emptyStub = import_node_path.default.join(stubsDir, "empty-wallet-dep", "index.cjs");
+  return {
+    "@hot-wallet/sdk": import_node_path.default.join(stubsDir, "hot-wallet.ts"),
+    "@trezor/connect-web": emptyStub,
+    "@trezor/connect-plugin-stellar": emptyStub,
+    "@safe-global/safe-apps-sdk": emptyStub,
+    "@safe-global/safe-apps-provider": emptyStub,
+    "@safe-global/safe-gateway-typescript-sdk": emptyStub
+  };
+}
+function walletStubPnpmWorkspaceYaml() {
+  return `allowBuilds:
+  esbuild: true
+
+ignoredOptionalDependencies:
+  - "@safe-global/safe-apps-provider"
+  - "@safe-global/safe-apps-sdk"
+
+overrides:
+  uuid: "^14.0.0"
+  "@creit.tech/stellar-wallets-kit>@trezor/connect-web": "-"
+  "@creit.tech/stellar-wallets-kit>@trezor/connect-plugin-stellar": "-"
+  "@creit.tech/stellar-wallets-kit>@hot-wallet/sdk": "-"
+  "@reown/appkit-utils>@safe-global/safe-apps-sdk": "-"
+  "@reown/appkit-utils>@safe-global/safe-apps-provider": "-"
+  "@safe-global/safe-apps-sdk>@safe-global/safe-gateway-typescript-sdk": "-"
+`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  walletStubOverrides,
+  walletStubPnpmWorkspaceYaml,
+  walletStubViteAliases
+});

package/dist/vite.d.cts

@@ -0,0 +1,8 @@
+type WalletStubPaths = {
+    stubsDir: string;
+};
+declare function walletStubOverrides(stubsDir?: string): Record<string, unknown>;
+declare function walletStubViteAliases(stubsDir: string): Record<string, string>;
+declare function walletStubPnpmWorkspaceYaml(): string;
+
+export { type WalletStubPaths, walletStubOverrides, walletStubPnpmWorkspaceYaml, walletStubViteAliases };

package/dist/vite.d.ts

@@ -0,0 +1,8 @@
+type WalletStubPaths = {
+    stubsDir: string;
+};
+declare function walletStubOverrides(stubsDir?: string): Record<string, unknown>;
+declare function walletStubViteAliases(stubsDir: string): Record<string, string>;
+declare function walletStubPnpmWorkspaceYaml(): string;
+
+export { type WalletStubPaths, walletStubOverrides, walletStubPnpmWorkspaceYaml, walletStubViteAliases };

package/dist/vite.js

@@ -0,0 +1,54 @@
+// src/vite/wallet-stubs.ts
+import path from "path";
+function walletStubOverrides(stubsDir = "./src/stubs") {
+  const posixStubsDir = stubsDir.split(path.sep).join("/");
+  return {
+    uuid: "^14.0.0",
+    "@creit.tech/stellar-wallets-kit": {
+      "@trezor/connect-web": `file:${posixStubsDir}/empty-wallet-dep`,
+      "@trezor/connect-plugin-stellar": `file:${posixStubsDir}/empty-wallet-dep`,
+      "@hot-wallet/sdk": `file:${posixStubsDir}/hot-wallet-sdk`
+    },
+    "@reown/appkit-utils": {
+      "@safe-global/safe-apps-sdk": "-",
+      "@safe-global/safe-apps-provider": "-"
+    },
+    "@safe-global/safe-apps-sdk": {
+      "@safe-global/safe-gateway-typescript-sdk": "-"
+    }
+  };
+}
+function walletStubViteAliases(stubsDir) {
+  const emptyStub = path.join(stubsDir, "empty-wallet-dep", "index.cjs");
+  return {
+    "@hot-wallet/sdk": path.join(stubsDir, "hot-wallet.ts"),
+    "@trezor/connect-web": emptyStub,
+    "@trezor/connect-plugin-stellar": emptyStub,
+    "@safe-global/safe-apps-sdk": emptyStub,
+    "@safe-global/safe-apps-provider": emptyStub,
+    "@safe-global/safe-gateway-typescript-sdk": emptyStub
+  };
+}
+function walletStubPnpmWorkspaceYaml() {
+  return `allowBuilds:
+  esbuild: true
+
+ignoredOptionalDependencies:
+  - "@safe-global/safe-apps-provider"
+  - "@safe-global/safe-apps-sdk"
+
+overrides:
+  uuid: "^14.0.0"
+  "@creit.tech/stellar-wallets-kit>@trezor/connect-web": "-"
+  "@creit.tech/stellar-wallets-kit>@trezor/connect-plugin-stellar": "-"
+  "@creit.tech/stellar-wallets-kit>@hot-wallet/sdk": "-"
+  "@reown/appkit-utils>@safe-global/safe-apps-sdk": "-"
+  "@reown/appkit-utils>@safe-global/safe-apps-provider": "-"
+  "@safe-global/safe-apps-sdk>@safe-global/safe-gateway-typescript-sdk": "-"
+`;
+}
+export {
+  walletStubOverrides,
+  walletStubPnpmWorkspaceYaml,
+  walletStubViteAliases
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/client",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Browser and Node client for Soroban smart contracts — connects generated bindings, Caatinga artifacts, and wallet adapters",
   "keywords": [
     "stellar",
@@ -48,6 +48,11 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js",
       "require": "./dist/react.cjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "require": "./dist/vite.cjs"
     }
   },
   "files": [
@@ -56,7 +61,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^2.3.0"
+    "@caatinga/core": "^2.4.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -87,7 +92,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/freighter.ts src/stellar-wallets-kit.ts src/react.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts src/freighter.ts src/stellar-wallets-kit.ts src/react.ts src/vite.ts --format esm,cjs --dts",
     "test": "vitest run --pool=threads",
     "typecheck": "tsc --noEmit"
   }