@caatinga/cli 2.1.0 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @caatinga/cli
 
-Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, and `invoke`.
+Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, `status`, and `invoke`.
 
 ## Install
 
@@ -35,11 +35,11 @@ npm install
 
 npx caatinga build counter
 npx caatinga deploy counter --network testnet --source alice
-npx caatinga generate counter --network testnet
+npx caatinga status --network testnet
 npx caatinga invoke counter.increment --network testnet --source alice
 ```
 
-`build` only compiles the WASM file. `deploy` writes contract IDs to `caatinga.artifacts.json`, and the frontend/client flow needs those IDs before it can resolve a contract. `generate` creates TypeScript bindings under the path configured in `caatinga.config.ts` (templates default to `contracts/generated/`).
+`build` only compiles the WASM file. `deploy` writes contract IDs to `caatinga.artifacts.json` and then generates TypeScript bindings automatically under the path configured in `caatinga.config.ts` (templates default to `contracts/generated/`); pass `--no-generate` to skip. `status` shows what's deployed per network and whether bindings are fresh.
 
 ## Commands
 
@@ -49,10 +49,11 @@ npx caatinga invoke counter.increment --network testnet --source alice
 | `caatinga doctor [--network <network>] [--source <identity>]` | Check local Node, Stellar CLI, Rust, config, artifacts, network, and source identity setup |
 | `caatinga build [contract]` | Compile contract WASM through Stellar CLI (default contract: `counter`) |
 | `caatinga deploy [contract]` | Deploy one contract or the full configured graph; record IDs in artifacts |
-| `caatinga generate [contract]` | Generate TypeScript bindings from a deployed contract ID; omit the name to generate for all deployed contracts |
+| `caatinga generate [contract]` | (Re)generate TypeScript bindings; omit the name to generate for all deployed contracts |
+| `caatinga status [--network <name>] [--json]` | Show deployed contracts and binding freshness per network |
 | `caatinga invoke <contract.method>` | Invoke a deployed contract method; extra args forward to Stellar CLI |
 
-The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
+The supported CLI flow is `init -> build -> deploy (bindings auto-generate) -> invoke`.
 
 ### `init`
 
@@ -78,12 +79,17 @@ The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
 - `-s, --source <identity>` is required; must be a Stellar CLI identity alias that can sign (for example `alice`)
 - `--force` redeploys even when artifacts already store a contract ID
 - `--no-deps` skips dependency deployment for a single named contract (`--no-deps` requires `[contract]`)
+- `--no-generate` skips the automatic bindings generation after deploy
 
 Dependencies listed in `dependsOn` deploy first unless `--no-deps` is set. Deploy args may reference `${contracts.<name>.contractId}` placeholders resolved from artifacts.
 
-### `generate` and `invoke`
+After a successful deploy, bindings generate automatically for the deployed contracts. A generation failure never fails the deploy — the CLI prints a warning plus the recovery command (`npx caatinga generate --network <network>`).
+
+### `generate`, `status`, and `invoke`
 
 - `-n, --network <network>` selects the network used to resolve deployed contract IDs
+- `generate` prints binding freshness per contract before regenerating in all-contracts mode
+- `status` prints a per-network table (contract ID, WASM hash, deployed, binding freshness, dependencies); `--json` emits the machine-readable structure
 - `invoke` expects `<contract.method>` (for example `counter.increment`) and forwards `[args...]` to the underlying Stellar invocation
 
 `caatinga dev` is reserved, hidden in pre-v1 builds, and not part of the stability promise. Use your frontend dev server (for example Vite) alongside the commands above.

package/dist/index.js

@@ -161,9 +161,16 @@ async function warnIfDefaultNetworkNeedsDeploy(config) {
 }
 
 // src/commands/deploy.command.ts
-import { deployContractGraph, CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode2, loadConfig as loadConfig3 } from "@caatinga/core";
+import {
+  deployContractGraph,
+  generateBindingsGraph,
+  toCaatingaError as toCaatingaError2,
+  CaatingaError as CaatingaError2,
+  CaatingaErrorCode as CaatingaErrorCode2,
+  loadConfig as loadConfig3
+} from "@caatinga/core";
 function registerDeployCommand(program2) {
-  program2.command("deploy").description("Deploy one or all configured Soroban contracts").argument("[contract]", "Contract name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--no-stale-check", "Do not warn when WASM may be older than contract sources").option("--verify-deps", "Verify dependency contract IDs exist on-chain before deploy").action((contractName, options) => runCliAction(async () => {
+  program2.command("deploy").description("Deploy one or all configured Soroban contracts").argument("[contract]", "Contract name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--no-stale-check", "Do not warn when WASM may be older than contract sources").option("--verify-deps", "Verify dependency contract IDs exist on-chain before deploy").option("--no-generate", "Skip TypeScript bindings generation after deploy").action((contractName, options) => runCliAction(async () => {
     if (options.deps === false && !contractName) {
       throw new CaatingaError2(
         "`--no-deps` requires a contract name.",
@@ -197,15 +204,44 @@ function registerDeployCommand(program2) {
       logger.info(`  Contract ID: ${contract.contractId}`);
     }
     logger.info("Artifacts updated: caatinga.artifacts.json");
-    if (result.deployedContracts.length > 0) {
+    if (result.deployedContracts.length === 0) {
+      return;
+    }
+    if (options.generate === false) {
       logger.info("");
+      logger.info("Bindings generation skipped (--no-generate).");
       logger.info("Next:");
       for (const contract of result.deployedContracts) {
         logger.info(`  npx caatinga generate ${contract.name} --network ${result.network.name}`);
       }
       logger.info("  npm run dev");
+      return;
+    }
+    try {
+      const generated = await generateBindingsGraph({
+        config,
+        contractNames: result.deployedContracts.map((contract) => contract.name),
+        networkName: result.network.name
+      });
+      logger.info("");
+      logger.success("Bindings generated");
+      for (const binding of generated.results) {
+        logger.info(`  ${binding.contractName} \u2192 ${binding.importPath}`);
+      }
+      logger.info("");
+      logger.info("Next:");
+      logger.info("  npm run dev");
+    } catch (error) {
+      const caatingaError = toCaatingaError2(error);
       logger.info("");
-      logger.info("Run generate before npm run dev so the app uses real bindings, not the stub.");
+      logger.warn("Deploy succeeded, but bindings generation failed.");
+      logger.warn(`  ${caatingaError.message} (${caatingaError.code})`);
+      if (caatingaError.hint) {
+        logger.warn(`  Hint: ${caatingaError.hint}`);
+      }
+      logger.info("");
+      logger.info("Recover with:");
+      logger.info(`  npx caatinga generate --network ${result.network.name}`);
     }
   }));
 }
@@ -398,6 +434,33 @@ function printFixes(diagnostics) {
   }
 }
 
+// src/commands/doctor-bindings.ts
+import {
+  evaluateBindingsFreshness,
+  loadConfig as loadConfig5,
+  readArtifacts as readArtifacts3,
+  resolveNetwork as resolveNetwork3
+} from "@caatinga/core";
+async function evaluateBindingCoverage(options) {
+  const cwd = options.cwd;
+  const config = await loadConfig5({ cwd });
+  const network = resolveNetwork3(config, options.networkName);
+  const artifacts = await readArtifacts3(cwd);
+  const freshness = await evaluateBindingsFreshness({
+    config,
+    artifacts,
+    networkName: network.name,
+    cwd
+  });
+  const lines = freshness.map((entry) => ({
+    name: entry.contractName,
+    status: entry.status,
+    reason: entry.reason,
+    ...entry.status === "fresh" ? {} : { fix: `Run: caatinga generate ${entry.contractName} --network ${network.name}` }
+  }));
+  return { lines, allFresh: lines.every((line) => line.status === "fresh") };
+}
+
 // src/commands/doctor.command.ts
 function printDeployCoverageLine(line) {
   if (line.ok) {
@@ -424,6 +487,25 @@ async function reportDeployCoverage(networkName) {
   }
   return true;
 }
+function printBindingCoverageLine(line) {
+  if (line.status === "fresh") {
+    logger.info(`\u2713 ${line.name} \u2014 bindings fresh`);
+    return;
+  }
+  logger.info(`\u2717 ${line.name} \u2014 bindings ${line.status}${line.reason ? ` (${line.reason})` : ""}`);
+  if (line.fix) logger.info(`  ${line.fix}`);
+}
+async function reportBindingCoverage(networkName) {
+  const coverage = await evaluateBindingCoverage({ networkName });
+  if (coverage.lines.length === 0) {
+    return;
+  }
+  logger.info("");
+  logger.info(`Bindings (${networkName}):`);
+  for (const line of coverage.lines) {
+    printBindingCoverageLine(line);
+  }
+}
 function registerDoctorCommand(program2) {
   program2.command("doctor").description("Check local Caatinga, Stellar CLI, Rust, config, and source identity setup").option("-n, --network <network>", "Configured network name to validate").option("-s, --source <source>", "Stellar CLI identity alias to validate").action((options) => runCliAction(async () => {
     logger.info("Caatinga Doctor");
@@ -441,6 +523,7 @@ function registerDoctorCommand(program2) {
         ready = false;
         throw error;
       }
+      await reportBindingCoverage(options.network);
     }
     logger.info("");
     logger.info(`Status: ${ready ? "ready" : "blocked"}`);
@@ -451,11 +534,41 @@ function registerDoctorCommand(program2) {
 }
 
 // src/commands/generate.command.ts
-import { generateBindingsGraph, loadConfig as loadConfig5 } from "@caatinga/core";
+import {
+  evaluateBindingsFreshness as evaluateBindingsFreshness2,
+  generateBindingsGraph as generateBindingsGraph2,
+  loadConfig as loadConfig6,
+  readArtifacts as readArtifacts4,
+  resolveNetwork as resolveNetwork4
+} from "@caatinga/core";
+async function printFreshnessPreState(config, networkName) {
+  try {
+    const network = resolveNetwork4(config, networkName);
+    const artifacts = await readArtifacts4();
+    const freshness = await evaluateBindingsFreshness2({
+      config,
+      artifacts,
+      networkName: network.name
+    });
+    if (freshness.length === 0) {
+      return;
+    }
+    logger.info("Current bindings:");
+    for (const entry of freshness) {
+      const reason = entry.reason ? ` \u2014 ${entry.reason}` : "";
+      logger.info(`  [${entry.status}] ${entry.contractName}${reason}`);
+    }
+    logger.info("");
+  } catch {
+  }
+}
 function registerGenerateCommand(program2) {
   program2.command("generate").description("Generate TypeScript bindings for deployed contracts").argument("[contract]", "Contract name (defaults to all deployed contracts)").option("-n, --network <network>", "Configured network name").action((contractName, options) => runCliAction(async () => {
-    const config = await loadConfig5();
-    const { network, results } = await generateBindingsGraph({
+    const config = await loadConfig6();
+    if (!contractName) {
+      await printFreshnessPreState(config, options.network);
+    }
+    const { network, results } = await generateBindingsGraph2({
       config,
       contractName,
       networkName: options.network
@@ -562,26 +675,25 @@ function registerInitCommand(program2) {
       logger.info(
         `  npx caatinga deploy   ${defaultContract} --network testnet --source <identity>`
       );
-      logger.info(`  npx caatinga generate ${defaultContract} --network testnet`);
     } else {
       logger.info("  npx caatinga build");
       logger.info("  npx caatinga deploy   --network testnet --source <identity>");
-      logger.info("  npx caatinga generate --network testnet");
     }
     logger.info("  npm run dev");
     logger.info("");
     logger.info(
-      "Note: deploy and generate the contract before interacting in the frontend \u2014"
+      "Note: deploy generates TypeScript bindings automatically (--no-generate to skip) \u2014"
     );
     logger.info("the dApp reads the contract ID from caatinga.artifacts.json.");
+    logger.info("If generation fails, recover with: npx caatinga generate --network testnet");
   }));
 }
 
 // src/commands/invoke.command.ts
-import { invokeContract, loadConfig as loadConfig6 } from "@caatinga/core";
+import { invokeContract, loadConfig as loadConfig7 } from "@caatinga/core";
 function registerInvokeCommand(program2) {
   program2.command("invoke").description("Invoke a deployed contract function").argument("<target>", "Invoke target in contract.method format").argument("[args...]", "Arguments forwarded to Stellar CLI after the method name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").allowUnknownOption(true).allowExcessArguments(true).action((target, args, options) => runCliAction(async () => {
-    const config = await loadConfig6();
+    const config = await loadConfig7();
     const result = await invokeContract({
       config,
       target,
@@ -601,8 +713,77 @@ function registerInvokeCommand(program2) {
   }));
 }
 
+// src/commands/status.command.ts
+import { collectProjectStatus, loadConfig as loadConfig8 } from "@caatinga/core";
+
+// src/utils/table.ts
+function renderTable(headers, rows) {
+  const widths = headers.map(
+    (header, column) => Math.max(header.length, ...rows.map((row) => (row[column] ?? "").length))
+  );
+  const renderRow = (cells) => cells.map((cell, column) => (cell ?? "").padEnd(widths[column])).join("  ").trimEnd();
+  return [
+    renderRow(headers),
+    widths.map((width) => "\u2500".repeat(width)).join("  "),
+    ...rows.map((row) => renderRow(row))
+  ];
+}
+
+// src/commands/status.command.ts
+function shortId(value) {
+  if (!value) return "\u2014";
+  return value.length > 12 ? `${value.slice(0, 5)}\u2026${value.slice(-4)}` : value;
+}
+function shortHash(value) {
+  if (!value) return "\u2014";
+  return value.slice(0, 8);
+}
+function toRow(entry) {
+  return [
+    entry.name,
+    shortId(entry.contractId),
+    shortHash(entry.wasmHash),
+    entry.deployed ? "\u2713" : "\u2717",
+    entry.bindings.status,
+    entry.dependencies.length > 0 ? entry.dependencies.join(", ") : "\u2014"
+  ];
+}
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show deployed contracts and binding freshness per network").option("-n, --network <network>", "Configured network name").option("--json", "Print machine-readable JSON instead of the table").action((options) => runCliAction(async () => {
+    const config = await loadConfig8();
+    const status = await collectProjectStatus({
+      config,
+      networkName: options.network
+    });
+    if (options.json) {
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+    logger.success(`Project: ${status.project}`);
+    for (const network of status.networks) {
+      logger.info("");
+      logger.info(`Network: ${network.network}`);
+      const lines = renderTable(
+        ["CONTRACT", "CONTRACT ID", "WASM HASH", "DEPLOYED", "BINDINGS", "DEPS"],
+        network.contracts.map(toRow)
+      );
+      for (const line of lines) {
+        logger.info(line);
+      }
+      const needsAttention = network.contracts.filter(
+        (entry) => entry.deployed && entry.bindings.status !== "fresh"
+      );
+      for (const entry of needsAttention) {
+        logger.warn(
+          `Bindings ${entry.bindings.status} for ${entry.name}${entry.bindings.reason ? ` (${entry.bindings.reason})` : ""} \u2014 run: npx caatinga generate ${entry.name} --network ${network.network}`
+        );
+      }
+    }
+  }));
+}
+
 // src/version.ts
-var CAATINGA_CLI_VERSION = "2.1.0";
+var CAATINGA_CLI_VERSION = "2.2.0";
 
 // src/program.ts
 function createProgram() {
@@ -615,6 +796,7 @@ function createProgram() {
   registerDeployCommand(program2);
   registerGenerateCommand(program2);
   registerInvokeCommand(program2);
+  registerStatusCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Caatinga CLI for building dApps on Stellar/Soroban",
   "keywords": [
     "stellar",
@@ -43,7 +43,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^2.1.0",
+    "@caatinga/core": "^2.2.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0"
   },
@@ -54,7 +54,7 @@
     "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && cp -r ../templates ./templates",
+    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && mkdir ./templates && (cd ../templates && tar --exclude=node_modules --exclude=dist -cf - .) | (cd ./templates && tar -xf -)",
     "predev": "pnpm --filter @caatinga/core build",
     "dev": "tsx src/index.ts",
     "test": "vitest run --pool=threads",

package/templates/marketplace-with-token/caatinga.template.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "description": "Experimental multi-contract Soroban template with token dependency injection.",
   "caatinga": {
-    "compatibleCore": "^2.1.0",
+    "compatibleCore": "^2.2.0",
     "templateVersion": 1
   },
   "frontend": {

package/templates/marketplace-with-token/package.json

@@ -12,15 +12,15 @@
     "caatinga:generate": "caatinga generate token && caatinga generate marketplace"
   },
   "dependencies": {
-    "@caatinga/client": "^2.1.0",
-    "@caatinga/core": "^2.1.0",
+    "@caatinga/client": "^2.2.0",
+    "@caatinga/core": "^2.2.0",
     "@vitejs/plugin-react": "^4.3.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^2.1.0",
+    "@caatinga/cli": "^2.2.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

package/templates/react-vite-counter/caatinga.template.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "description": "Minimal Vite + React + Soroban counter dApp.",
   "caatinga": {
-    "compatibleCore": "^2.1.0",
+    "compatibleCore": "^2.2.0",
     "templateVersion": 1
   },
   "frontend": {

package/templates/react-vite-counter/package.json

@@ -7,14 +7,14 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "caatinga:build": "caatinga build counter",
-    "caatinga:deploy": "caatinga deploy counter",
-    "caatinga:generate": "caatinga generate counter"
+    "caatinga:build": "npx caatinga build counter",
+    "caatinga:deploy": "npx caatinga deploy counter --network testnet --source ${CAATINGA_SOURCE:-alice}",
+    "caatinga:generate": "npx caatinga generate counter --network testnet"
   },
   "dependencies": {
-    "@caatinga/client": "^2.1.0",
-    "@caatinga/core": "^2.1.0",
-    "@creit.tech/stellar-wallets-kit": "^1.9.5",
+    "@caatinga/client": "^2.2.0",
+    "@caatinga/core": "^2.2.0",
+    "@creit.tech/stellar-wallets-kit": "^2.3.0",
     "@stellar/stellar-sdk": "^14.5.0",
     "buffer": "^6.0.3",
     "@vitejs/plugin-react": "^4.3.4",
@@ -23,7 +23,7 @@
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^2.1.0",
+    "@caatinga/cli": "^2.2.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

package/templates/react-vite-counter/pnpm-workspace.yaml

@@ -1,12 +1,6 @@
-# pnpm 10.26+ / 11.x block lifecycle scripts by default; vite depends on esbuild.
+# pnpm-only file (npm / yarn / bun ignore it). pnpm 10.26+/11.x block lifecycle
+# scripts by default; vite depends on esbuild's, so allow it. All dependency
+# stubbing now happens at the build layer (see vite.config.ts), so no pnpm-only
+# `overrides` are needed and this template installs identically on every PM.
 allowBuilds:
   esbuild: true
-
-# stellar-wallets-kit@0.0.7 is unpublished from npm and is therefore pinned
-# to a github: URL in package.json. Its own dependencies also reference
-# @creit.tech/xbull-wallet-connect via a github: URL, and pnpm 10.26+ (and
-# 11.x) defaults blockExoticSubdeps to true, which would refuse to install
-# that exotic subdep. Allow it explicitly. This is a targeted opt-out for
-# this one transitive dep; direct dependencies in package.json still must
-# come from a trusted source.
-blockExoticSubdeps: false

package/templates/react-vite-counter/src/App.tsx

@@ -1,6 +1,15 @@
+import { WalletProvider, useWallet } from "@caatinga/client/react";
+import type { CaatingaArtifacts } from "@caatinga/core/browser";
+import artifactsJson from "../caatinga.artifacts.json";
+import { ContractNotDeployed } from "./components/ContractNotDeployed";
 import { CounterCard } from "./components/CounterCard";
 import { WalletButton } from "./components/WalletButton";
-import { WalletProvider, useWallet } from "./context/WalletContext";
+import { WalletModal } from "./components/WalletModal";
+import { stellarWalletAdapter } from "./wallet.js";
+
+const artifacts = artifactsJson as CaatingaArtifacts;
+const counterContractId = artifacts.networks?.testnet?.contracts?.counter?.contractId;
+const isDeployed = Boolean(counterContractId);
 
 function AppBody() {
   const { publicKey } = useWallet();
@@ -15,7 +24,9 @@ function AppBody() {
         <WalletButton />
       </header>
 
-      {publicKey ? (
+      {!isDeployed ? (
+        <ContractNotDeployed />
+      ) : publicKey ? (
         <CounterCard />
       ) : (
         <section className="counter-panel" aria-labelledby="connect-title">
@@ -35,8 +46,11 @@ function AppBody() {
 
 export default function App() {
   return (
-    <WalletProvider>
+    // persist keeps the session across reloads; the provider silently
+    // reconnects on mount (autoConnect defaults to true when persisting).
+    <WalletProvider adapter={stellarWalletAdapter} options={{ persist: true }}>
       <AppBody />
+      <WalletModal />
     </WalletProvider>
   );
 }

package/templates/react-vite-counter/src/components/ContractNotDeployed.tsx

@@ -0,0 +1,27 @@
+export function ContractNotDeployed() {
+  return (
+    <section className="counter-panel" aria-labelledby="not-deployed-title">
+      <div className="counter-panel__header">
+        <div>
+          <p className="eyebrow">Get started</p>
+          <h2 id="not-deployed-title">Contract not deployed</h2>
+        </div>
+        <span className="network-pill">testnet</span>
+      </div>
+      <p>
+        The counter contract has no on-chain ID yet, so the frontend can&apos;t read or update it.
+        Build and deploy first — the dApp reads the contract ID from{" "}
+        <code>caatinga.artifacts.json</code>. Deploy also generates TypeScript bindings
+        automatically.
+      </p>
+      <pre className="counter-error" role="note">
+        {`npx caatinga build    counter
+npx caatinga deploy   counter --network testnet --source <identity>
+npm run dev
+
+# If bindings generation failed after deploy:
+npx caatinga generate counter --network testnet`}
+      </pre>
+    </section>
+  );
+}

package/templates/react-vite-counter/src/components/CounterCard.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { caatingaClient } from "../caatinga.js";
 import { formatCaatingaError } from "@caatinga/core/browser";
-import { useWallet } from "../context/WalletContext.js";
+import { useWallet } from "@caatinga/client/react";
 import { LoadingModal } from "./LoadingModal.js";
 
 export function CounterCard() {

package/templates/react-vite-counter/src/components/WalletButton.tsx

@@ -1,4 +1,5 @@
-import { useWallet } from "../context/WalletContext.js";
+import { useWallet } from "@caatinga/client/react";
+import { WALLET_SELECTION_CLOSED_ERROR } from "../wallet-modal-controller.js";
 
 function shortenAddress(address: string): string {
   if (address.length <= 12) {
@@ -9,23 +10,23 @@ function shortenAddress(address: string): string {
 }
 
 export function WalletButton() {
-  const { publicKey, loading, error, connect, disconnect } = useWallet();
+  const { publicKey, connecting, error, connect, disconnect } = useWallet();
 
   return (
     <div className="wallet-shell">
       <button
         className="wallet-button"
         type="button"
-        onClick={publicKey ? () => void disconnect() : () => void connect()}
-        disabled={loading}
+        onClick={publicKey ? () => void disconnect() : () => void connect().catch(() => {})}
+        disabled={connecting}
         aria-live="polite"
       >
         <span className={publicKey ? "status-dot status-dot--on" : "status-dot"} />
-        {loading ? "Connecting..." : publicKey ? shortenAddress(publicKey) : "Connect"}
+        {connecting ? "Connecting..." : publicKey ? shortenAddress(publicKey) : "Connect"}
       </button>
-      {error ? (
+      {error && error.name !== WALLET_SELECTION_CLOSED_ERROR ? (
         <p className="wallet-error" role="alert">
-          {error}
+          {error.message}
         </p>
       ) : null}
     </div>

package/templates/react-vite-counter/src/components/WalletModal.tsx

@@ -0,0 +1,248 @@
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { formatCaatingaError } from "@caatinga/core/browser";
+import type { ISupportedWallet } from "@creit.tech/stellar-wallets-kit/types";
+import { stellarWalletAdapter } from "../wallet.js";
+import {
+  cancelWalletSelection,
+  getWalletModalState,
+  resolveWalletSelection,
+  subscribeWalletModal
+} from "../wallet-modal-controller.js";
+
+const LEARN_MORE_URL = "https://developers.stellar.org/docs/build/apps/wallet/overview";
+
+// SWK wallet modules reject with plain `{ code, message }` objects, not Errors.
+function describeWalletError(caught: unknown): string {
+  if (caught && typeof caught === "object" && "message" in caught) {
+    const message = (caught as { message?: unknown }).message;
+    if (typeof message === "string" && message) {
+      return message;
+    }
+  }
+  return formatCaatingaError(caught);
+}
+
+function walletBadge(wallet: ISupportedWallet): string | null {
+  if (!wallet.isAvailable) {
+    return "Install ↗";
+  }
+  // Bridge wallets (WalletConnect) hand off to a QR code instead of an extension.
+  return wallet.type === "BRIDGE_WALLET" ? "QR code" : null;
+}
+
+interface WalletOptionProps {
+  wallet: ISupportedWallet;
+  connectingId: string | null;
+  onSelect(wallet: ISupportedWallet): void;
+}
+
+function WalletOption({ wallet, connectingId, onSelect }: WalletOptionProps) {
+  const connecting = connectingId === wallet.id;
+  const badge = walletBadge(wallet);
+
+  return (
+    <li>
+      <button
+        type="button"
+        className={connecting ? "wallet-option wallet-option--connecting" : "wallet-option"}
+        onClick={() => onSelect(wallet)}
+        disabled={connectingId !== null && !connecting}
+      >
+        <img className="wallet-option__icon" src={wallet.icon} alt="" />
+        <span className="wallet-option__name">
+          {connecting ? `Connecting to ${wallet.name}…` : wallet.name}
+        </span>
+        {connecting ? (
+          <span className="wallet-option__spinner" aria-hidden="true" />
+        ) : badge ? (
+          <span className="wallet-option__badge">{badge}</span>
+        ) : (
+          <span className="status-dot status-dot--on" aria-hidden="true" />
+        )}
+      </button>
+    </li>
+  );
+}
+
+export function WalletModal() {
+  const { open } = useSyncExternalStore(
+    subscribeWalletModal,
+    getWalletModalState,
+    getWalletModalState
+  );
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [wallets, setWallets] = useState<ISupportedWallet[] | null>(null);
+  const [connectingId, setConnectingId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    setWallets(null);
+    setConnectingId(null);
+    setError(null);
+
+    // Availability probes can take a moment; ignore the result if the modal
+    // closed (or reopened) before they resolve.
+    let cancelled = false;
+    stellarWalletAdapter
+      .getSupportedWallets()
+      .then((list) => {
+        if (!cancelled) {
+          setWallets(list);
+        }
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled) {
+          setWallets([]);
+          setError(describeWalletError(caught));
+        }
+      });
+
+    panelRef.current?.focus();
+
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") {
+        cancelWalletSelection();
+      }
+    }
+    window.addEventListener("keydown", onKeyDown);
+
+    return () => {
+      cancelled = true;
+      window.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  if (!open) {
+    return null;
+  }
+
+  async function selectWallet(wallet: ISupportedWallet) {
+    if (connectingId) {
+      return;
+    }
+
+    if (!wallet.isAvailable) {
+      window.open(wallet.url, "_blank", "noopener");
+      return;
+    }
+
+    setError(null);
+    setConnectingId(wallet.id);
+    try {
+      stellarWalletAdapter.setWallet(wallet.id);
+      const address = await stellarWalletAdapter.getPublicKey();
+      resolveWalletSelection(address);
+    } catch (caught) {
+      setError(describeWalletError(caught));
+    } finally {
+      setConnectingId(null);
+    }
+  }
+
+  const detected = wallets?.filter((wallet) => wallet.isAvailable) ?? [];
+  const others = wallets?.filter((wallet) => !wallet.isAvailable) ?? [];
+
+  return (
+    <div
+      className="wallet-modal"
+      role="presentation"
+      onClick={(event) => {
+        if (event.target === event.currentTarget) {
+          cancelWalletSelection();
+        }
+      }}
+    >
+      <div
+        ref={panelRef}
+        className="wallet-modal__panel"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="wallet-modal-title"
+        tabIndex={-1}
+      >
+        <header className="wallet-modal__header">
+          <h2 id="wallet-modal-title">Connect a wallet</h2>
+          <button
+            type="button"
+            className="wallet-modal__close"
+            onClick={() => cancelWalletSelection()}
+            aria-label="Close"
+          >
+            ✕
+          </button>
+        </header>
+
+        {error ? (
+          <p className="wallet-modal__error" role="alert">
+            {error}
+          </p>
+        ) : null}
+
+        <div className="wallet-modal__body">
+          {wallets === null ? (
+            <ul className="wallet-modal__list" aria-label="Loading wallets">
+              {[0, 1, 2].map((row) => (
+                <li key={row} className="wallet-option wallet-option--skeleton" aria-hidden="true">
+                  <span className="wallet-skeleton__icon" />
+                  <span className="wallet-skeleton__line" />
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <>
+              {detected.length > 0 ? (
+                <>
+                  <p className="eyebrow wallet-modal__section">Detected</p>
+                  <ul className="wallet-modal__list">
+                    {detected.map((wallet) => (
+                      <WalletOption
+                        key={wallet.id}
+                        wallet={wallet}
+                        connectingId={connectingId}
+                        onSelect={(selected) => void selectWallet(selected)}
+                      />
+                    ))}
+                  </ul>
+                </>
+              ) : null}
+
+              {others.length > 0 ? (
+                <>
+                  <p className="eyebrow wallet-modal__section">More wallets</p>
+                  <ul className="wallet-modal__list">
+                    {others.map((wallet) => (
+                      <WalletOption
+                        key={wallet.id}
+                        wallet={wallet}
+                        connectingId={connectingId}
+                        onSelect={(selected) => void selectWallet(selected)}
+                      />
+                    ))}
+                  </ul>
+                </>
+              ) : null}
+
+              {detected.length === 0 && others.length === 0 && !error ? (
+                <p className="wallet-modal__empty">
+                  No wallets available. Install a Stellar wallet to continue.
+                </p>
+              ) : null}
+            </>
+          )}
+
+        </div>
+
+        <footer className="wallet-modal__footer">
+          <span>New to Stellar wallets?</span>
+          <a href={LEARN_MORE_URL} target="_blank" rel="noreferrer">
+            Learn more ↗
+          </a>
+        </footer>
+      </div>
+    </div>
+  );
+}

package/templates/react-vite-counter/src/stubs/empty-wallet-dep/index.cjs

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = {};

package/templates/react-vite-counter/src/stubs/empty-wallet-dep/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "empty-wallet-dep",
+  "version": "1.0.0",
+  "private": true,
+  "main": "./index.cjs"
+}

package/templates/react-vite-counter/src/stubs/hot-wallet-sdk/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+
+exports.HOT = {
+  request() {
+    return Promise.reject(new Error("HOT Wallet is not supported in this build."));
+  }
+};

package/templates/react-vite-counter/src/stubs/hot-wallet-sdk/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@hot-wallet/sdk",
+  "version": "1.0.11",
+  "private": true,
+  "main": "./index.cjs"
+}

package/templates/react-vite-counter/src/styles.css

@@ -239,6 +239,232 @@ button:hover {
   background: #f4f2ec;
 }
 
+.wallet-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  background: rgba(32, 35, 42, 0.45);
+  backdrop-filter: blur(3px);
+}
+
+.wallet-modal__panel {
+  display: flex;
+  flex-direction: column;
+  width: min(400px, 100%);
+  max-height: min(600px, calc(100vh - 32px));
+  border: 1px solid #d9d5ca;
+  border-radius: 12px;
+  background: #fffdf7;
+  box-shadow: 0 18px 60px rgba(32, 35, 42, 0.22);
+  outline: none;
+  animation: wallet-modal-pop 0.18s ease;
+}
+
+@keyframes wallet-modal-pop {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.98);
+  }
+}
+
+.wallet-modal__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 20px 20px 8px;
+}
+
+.wallet-modal__header h2 {
+  margin: 0;
+  color: #16181d;
+  font-size: 1.2rem;
+}
+
+.wallet-modal__close {
+  width: 32px;
+  min-height: 32px;
+  padding: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: #697076;
+  font-size: 0.95rem;
+  font-weight: 400;
+  line-height: 1;
+}
+
+.wallet-modal__close:hover {
+  background: #f4f2ec;
+  color: #20232a;
+}
+
+.wallet-modal__body {
+  overflow-y: auto;
+  padding: 0 12px 16px;
+}
+
+.wallet-modal__section {
+  margin: 14px 10px 6px;
+}
+
+.wallet-modal__list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.wallet-option {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  min-height: 56px;
+  padding: 8px 12px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  background: transparent;
+  color: #20232a;
+  font-weight: 700;
+  text-align: left;
+  transition:
+    background 0.15s ease,
+    border-color 0.15s ease;
+}
+
+.wallet-option:hover {
+  background: #f4f2ec;
+  border-color: #d9d5ca;
+}
+
+.wallet-option:disabled {
+  background: transparent;
+  border-color: transparent;
+  opacity: 0.5;
+  cursor: default;
+}
+
+.wallet-option--connecting,
+.wallet-option--connecting:hover {
+  background: #f4f2ec;
+  border-color: #d9d5ca;
+}
+
+.wallet-option__icon {
+  width: 36px;
+  height: 36px;
+  border: 1px solid #eee9dd;
+  border-radius: 8px;
+  background: #ffffff;
+  object-fit: contain;
+}
+
+.wallet-option__name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.wallet-option__badge {
+  border: 1px solid #d9d5ca;
+  border-radius: 999px;
+  padding: 3px 10px;
+  background: #ffffff;
+  color: #45515a;
+  font-size: 0.7rem;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.wallet-option__spinner {
+  width: 16px;
+  height: 16px;
+  border: 3px solid #d9d5ca;
+  border-top-color: #1d6154;
+  border-radius: 50%;
+  animation: loading-spin 0.7s linear infinite;
+}
+
+.wallet-option--skeleton {
+  pointer-events: none;
+}
+
+.wallet-skeleton__icon,
+.wallet-skeleton__line {
+  border-radius: 8px;
+  background: #ece8dc;
+  animation: wallet-skeleton-pulse 1.2s ease-in-out infinite;
+}
+
+.wallet-skeleton__icon {
+  flex: none;
+  width: 36px;
+  height: 36px;
+}
+
+.wallet-skeleton__line {
+  width: 45%;
+  height: 14px;
+}
+
+@keyframes wallet-skeleton-pulse {
+  50% {
+    opacity: 0.55;
+  }
+}
+
+.wallet-modal__empty {
+  margin: 14px 10px;
+  color: #45515a;
+  font-size: 0.88rem;
+  line-height: 1.4;
+}
+
+.wallet-modal__error {
+  margin: 0 20px 4px;
+  max-height: 72px;
+  overflow-y: auto;
+  border: 1px solid #e7c8c8;
+  border-radius: 8px;
+  padding: 8px 10px;
+  background: #fbf1f1;
+  color: #8b1e1e;
+  font-size: 0.82rem;
+  line-height: 1.4;
+  white-space: pre-wrap;
+}
+
+.wallet-modal__footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 14px 20px;
+  border-top: 1px solid #eee9dd;
+  color: #697076;
+  font-size: 0.82rem;
+}
+
+.wallet-modal__footer a {
+  color: #1d6154;
+  font-weight: 700;
+  text-decoration: none;
+  white-space: nowrap;
+}
+
+.wallet-modal__footer a:hover {
+  text-decoration: underline;
+}
+
 @media (max-width: 560px) {
   .topbar,
   .counter-panel__header {
@@ -254,4 +480,39 @@ button:hover {
     width: 100%;
     justify-content: center;
   }
+
+  .wallet-modal {
+    align-items: flex-end;
+    padding: 0;
+  }
+
+  .wallet-modal__panel {
+    width: 100%;
+    max-height: 80vh;
+    border-bottom: 0;
+    border-radius: 16px 16px 0 0;
+    animation: wallet-modal-rise 0.2s ease;
+  }
+}
+
+@keyframes wallet-modal-rise {
+  from {
+    opacity: 0;
+    transform: translateY(24px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .wallet-modal__panel {
+    animation: none;
+  }
+
+  .wallet-option__spinner {
+    animation-duration: 1.6s;
+  }
+
+  .wallet-skeleton__icon,
+  .wallet-skeleton__line {
+    animation: none;
+  }
 }

package/templates/react-vite-counter/src/wallet-modal-controller.ts

@@ -0,0 +1,73 @@
+// Promise bridge between the wallet adapter's `openModal()` capability and the
+// <WalletModal> component. The adapter resolves the same promise the wallet
+// session awaits, so connect/persist/restore flows stay untouched.
+
+export interface WalletModalState {
+  open: boolean;
+}
+
+/**
+ * `error.name` used when the user closes the modal without picking a wallet.
+ * Closing on purpose is not a failure, so the UI can suppress this one.
+ */
+export const WALLET_SELECTION_CLOSED_ERROR = "WalletSelectionClosedError";
+
+interface PendingSelection {
+  resolve(address: string): void;
+  reject(error: Error): void;
+}
+
+let state: WalletModalState = { open: false };
+let pending: PendingSelection | null = null;
+const listeners = new Set<() => void>();
+
+function setState(next: WalletModalState): void {
+  state = next;
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+export function getWalletModalState(): WalletModalState {
+  return state;
+}
+
+export function subscribeWalletModal(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Opens the modal. Resolves with the connected address, rejects when closed. */
+export function requestWalletSelection(): Promise<string> {
+  // A connect while the modal is already open supersedes the previous request.
+  cancelWalletSelection();
+
+  return new Promise<string>((resolve, reject) => {
+    pending = { resolve, reject };
+    setState({ open: true });
+  });
+}
+
+export function resolveWalletSelection(address: string): void {
+  const current = pending;
+  pending = null;
+  if (state.open) {
+    setState({ open: false });
+  }
+  current?.resolve(address);
+}
+
+export function cancelWalletSelection(): void {
+  const current = pending;
+  pending = null;
+  if (state.open) {
+    setState({ open: false });
+  }
+  if (current) {
+    const error = new Error("Wallet selection closed.");
+    error.name = WALLET_SELECTION_CLOSED_ERROR;
+    current.reject(error);
+  }
+}

package/templates/react-vite-counter/src/wallet.ts

@@ -4,12 +4,20 @@ import {
   WalletNetwork,
   type StellarWalletsKitMetadata
 } from "@caatinga/client/stellar-wallets-kit";
+import { requestWalletSelection } from "./wallet-modal-controller.js";
 
-export const stellarWalletAdapter = createStellarWalletsKitAdapter({
+const baseWalletAdapter = createStellarWalletsKitAdapter({
   network: WalletNetwork.TESTNET,
   walletConnectMetadata: getWalletConnectMetadata()
 });
 
+// Route connect() through the custom <WalletModal> instead of SWK's built-in
+// authModal. Everything else (persistence, restore, signing) is untouched.
+export const stellarWalletAdapter = {
+  ...baseWalletAdapter,
+  openModal: () => requestWalletSelection()
+};
+
 export { WalletNetwork };
 
 function getWalletConnectMetadata(): StellarWalletsKitMetadata | undefined {

package/templates/react-vite-counter/vite.config.ts

@@ -2,6 +2,14 @@ import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import { fileURLToPath } from "node:url";
 
+// Empty CJS module. Aliasing browser-hostile wallet sub-deps here keeps them out
+// of the bundle on every package manager — no install-time dependency overrides
+// (which differ per pnpm/npm/yarn/bun) required. CJS interop lets any named
+// import resolve to `undefined` without an esbuild "not exported" error.
+const emptyStub = fileURLToPath(
+  new URL("./src/stubs/empty-wallet-dep/index.cjs", import.meta.url)
+);
+
 export default defineConfig({
   plugins: [react()],
   resolve: {
@@ -9,7 +17,15 @@ export default defineConfig({
       // Stellar Wallets Kit drags NEAR's @hot-wallet/sdk (Node-only crypto) into
       // the browser bundle. The adapter filters HOT Wallet out, so stub the SDK
       // to keep the NEAR chain out of the build. See src/stubs/hot-wallet.ts.
-      "@hot-wallet/sdk": fileURLToPath(new URL("./src/stubs/hot-wallet.ts", import.meta.url))
+      "@hot-wallet/sdk": fileURLToPath(new URL("./src/stubs/hot-wallet.ts", import.meta.url)),
+      // SWK + Reown/WalletConnect pull Trezor Connect (Node-only) and Safe Global
+      // SDKs that none of the wallets Caatinga ships actually use. Stub them so the
+      // bundle builds without pnpm-only "-" dependency overrides.
+      "@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
     }
   }
 });

package/templates/react-vite-counter/src/context/WalletContext.tsx

@@ -1,64 +0,0 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useMemo,
-  useState,
-  type ReactNode
-} from "react";
-import { stellarWalletAdapter } from "../wallet.js";
-
-interface WalletContextValue {
-  publicKey: string | null;
-  loading: boolean;
-  error: string | null;
-  connect: () => Promise<void>;
-  disconnect: () => Promise<void>;
-}
-
-const WalletContext = createContext<WalletContextValue | null>(null);
-
-export function WalletProvider({ children }: { children: ReactNode }) {
-  const [publicKey, setPublicKey] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const connect = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-
-    try {
-      // openModal lists only installed/available wallets and resolves with the
-      // chosen account address (rejects if the user dismisses the modal).
-      const address = await stellarWalletAdapter.openModal();
-      setPublicKey(address);
-    } catch (caught) {
-      const message = caught instanceof Error ? caught.message : String(caught);
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  const disconnect = useCallback(async () => {
-    await stellarWalletAdapter.disconnect();
-    setPublicKey(null);
-    setError(null);
-  }, []);
-
-  const value = useMemo<WalletContextValue>(
-    () => ({ publicKey, loading, error, connect, disconnect }),
-    [publicKey, loading, error, connect, disconnect]
-  );
-
-  return <WalletContext.Provider value={value}>{children}</WalletContext.Provider>;
-}
-
-export function useWallet(): WalletContextValue {
-  const context = useContext(WalletContext);
-  if (!context) {
-    throw new Error("useWallet must be used within a WalletProvider");
-  }
-
-  return context;
-}