@trustware/sdk-staging 1.1.8-staging.8 → 1.1.9-staging.3

package/README.md

@@ -105,7 +105,6 @@ type TrustwareConfigOptions = {
     fromAddress?: string;
     toAddress?: string;
     defaultSlippage?: number;
-    routeType?: string;
     options?: {
       routeRefreshMs?: number;
       fixedFromAmount?: string | number;
@@ -132,7 +131,6 @@ type TrustwareConfigOptions = {
 - `routes.fromAddress`: optional source wallet override.
 - `routes.toAddress`: optional destination address override.
 - `routes.defaultSlippage`: optional slippage percentage. Defaults to `1`.
-- `routes.routeType`: optional route flavor. Defaults to `"swap"`.
 
 ### Route Options
 

package/dist/{blockchain-BONedEsU.d.cts → blockchain-BxAFzp0s.d.cts}

@@ -52,6 +52,10 @@ type BalanceStreamOptions = {
     signal?: AbortSignal;
     strict?: boolean;
 };
+type GetBalancesOptions = {
+    /** Bypass the in-memory balance cache and re-fetch fresh data from the network. */
+    forceRefresh?: boolean;
+};
 type ChainType = "evm" | "cosmos" | "solana" | "btc" | string;
 interface NativeCurrency {
     symbol: string;
@@ -107,4 +111,4 @@ type TokenWithBalance = TokenDef & {
     balance?: bigint;
 };
 
-export type { BalanceRow as B, ChainDef as C, NativeCurrency as N, TokenDef as T, WalletAddressBalanceWrapper as W, BalanceStreamOptions as a, ChainMeta as b, ChainType as c, TokenMeta as d, TokenPageInfo as e, TokenPageOptions as f, TokenPageResult as g, TokenType as h, TokenWithBalance as i };
+export type { BalanceRow as B, ChainDef as C, GetBalancesOptions as G, NativeCurrency as N, TokenDef as T, WalletAddressBalanceWrapper as W, BalanceStreamOptions as a, ChainMeta as b, ChainType as c, TokenMeta as d, TokenPageInfo as e, TokenPageOptions as f, TokenPageResult as g, TokenType as h, TokenWithBalance as i };

package/dist/{blockchain-BONedEsU.d.ts → blockchain-BxAFzp0s.d.ts}

@@ -52,6 +52,10 @@ type BalanceStreamOptions = {
     signal?: AbortSignal;
     strict?: boolean;
 };
+type GetBalancesOptions = {
+    /** Bypass the in-memory balance cache and re-fetch fresh data from the network. */
+    forceRefresh?: boolean;
+};
 type ChainType = "evm" | "cosmos" | "solana" | "btc" | string;
 interface NativeCurrency {
     symbol: string;
@@ -107,4 +111,4 @@ type TokenWithBalance = TokenDef & {
     balance?: bigint;
 };
 
-export type { BalanceRow as B, ChainDef as C, NativeCurrency as N, TokenDef as T, WalletAddressBalanceWrapper as W, BalanceStreamOptions as a, ChainMeta as b, ChainType as c, TokenMeta as d, TokenPageInfo as e, TokenPageOptions as f, TokenPageResult as g, TokenType as h, TokenWithBalance as i };
+export type { BalanceRow as B, ChainDef as C, GetBalancesOptions as G, NativeCurrency as N, TokenDef as T, WalletAddressBalanceWrapper as W, BalanceStreamOptions as a, ChainMeta as b, ChainType as c, TokenMeta as d, TokenPageInfo as e, TokenPageOptions as f, TokenPageResult as g, TokenType as h, TokenWithBalance as i };

package/dist/constants.cjs

@@ -30,7 +30,7 @@ __export(constants_exports, {
 });
 module.exports = __toCommonJS(constants_exports);
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.1.8-staging.8";
+var SDK_VERSION = "1.1.9-staging.3";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var GTM_ID = "GTM-TZDGNCXB";
 var API_PREFIX = "/api";

package/dist/constants.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["// constants.ts\ndeclare const __SDK_VERSION__: string;\ndeclare const __API_ROOT__: string;\ndeclare const __GTM_ID__: string;\ndeclare const __WALLETCONNECT_PROJECT_ID__: string;\n\nexport const SDK_NAME = \"@trustware/sdk\";\nexport const SDK_VERSION: string = __SDK_VERSION__;\nexport const API_ROOT: string = __API_ROOT__;\nexport const GTM_ID: string = __GTM_ID__;\nexport const API_PREFIX = \"/api\";\nexport const WALLETCONNECT_PROJECT_ID = __WALLETCONNECT_PROJECT_ID__;\n\n// Assets base URL for wallet logos and other static assets\nexport const ASSETS_BASE_URL = \"https://app.trustware.io\";\n\n// WalletConnect Cloud project ID - built into the SDK for seamless wallet connections\n// This is a public identifier (not a secret) registered with WalletConnect Cloud\n// export const WALLETCONNECT_PROJECT_ID = \"4ead125c-63be-4b1a-a835-cef2dce67b84\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,IAAM,WAAW;AACjB,IAAM,cAAsB;AAC5B,IAAM,WAAmB;AACzB,IAAM,SAAiB;AACvB,IAAM,aAAa;AACnB,IAAM,2BAA2B;AAGjC,IAAM,kBAAkB;","names":[]}
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["// constants.ts\ndeclare const __SDK_VERSION__: string;\ndeclare const __API_ROOT__: string;\ndeclare const __GTM_ID__: string;\ndeclare const __WALLETCONNECT_PROJECT_ID__: string;\n\nexport const SDK_NAME = \"@trustware/sdk\";\nexport const SDK_VERSION: string = __SDK_VERSION__;\nexport const API_ROOT: string = __API_ROOT__;\nexport const GTM_ID: string = __GTM_ID__;\nexport const API_PREFIX = \"/api\";\nexport const WALLETCONNECT_PROJECT_ID = __WALLETCONNECT_PROJECT_ID__;\n\n// Assets base URL for wallet logos and other static assets\nexport const ASSETS_BASE_URL = \"https://app.trustware.io\";\n// export const ASSETS_BASE_URL = \"https://bv.trustware.io\";\n\n// WalletConnect Cloud project ID - built into the SDK for seamless wallet connections\n// This is a public identifier (not a secret) registered with WalletConnect Cloud\n// export const WALLETCONNECT_PROJECT_ID = \"4ead125c-63be-4b1a-a835-cef2dce67b84\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,IAAM,WAAW;AACjB,IAAM,cAAsB;AAC5B,IAAM,WAAmB;AACzB,IAAM,SAAiB;AACvB,IAAM,aAAa;AACnB,IAAM,2BAA2B;AAGjC,IAAM,kBAAkB;","names":[]}

package/dist/constants.mjs

@@ -1,6 +1,6 @@
 // src/constants.ts
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.1.8-staging.8";
+var SDK_VERSION = "1.1.9-staging.3";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var GTM_ID = "GTM-TZDGNCXB";
 var API_PREFIX = "/api";

package/dist/constants.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["// constants.ts\ndeclare const __SDK_VERSION__: string;\ndeclare const __API_ROOT__: string;\ndeclare const __GTM_ID__: string;\ndeclare const __WALLETCONNECT_PROJECT_ID__: string;\n\nexport const SDK_NAME = \"@trustware/sdk\";\nexport const SDK_VERSION: string = __SDK_VERSION__;\nexport const API_ROOT: string = __API_ROOT__;\nexport const GTM_ID: string = __GTM_ID__;\nexport const API_PREFIX = \"/api\";\nexport const WALLETCONNECT_PROJECT_ID = __WALLETCONNECT_PROJECT_ID__;\n\n// Assets base URL for wallet logos and other static assets\nexport const ASSETS_BASE_URL = \"https://app.trustware.io\";\n\n// WalletConnect Cloud project ID - built into the SDK for seamless wallet connections\n// This is a public identifier (not a secret) registered with WalletConnect Cloud\n// export const WALLETCONNECT_PROJECT_ID = \"4ead125c-63be-4b1a-a835-cef2dce67b84\";\n"],"mappings":";AAMO,IAAM,WAAW;AACjB,IAAM,cAAsB;AAC5B,IAAM,WAAmB;AACzB,IAAM,SAAiB;AACvB,IAAM,aAAa;AACnB,IAAM,2BAA2B;AAGjC,IAAM,kBAAkB;","names":[]}
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["// constants.ts\ndeclare const __SDK_VERSION__: string;\ndeclare const __API_ROOT__: string;\ndeclare const __GTM_ID__: string;\ndeclare const __WALLETCONNECT_PROJECT_ID__: string;\n\nexport const SDK_NAME = \"@trustware/sdk\";\nexport const SDK_VERSION: string = __SDK_VERSION__;\nexport const API_ROOT: string = __API_ROOT__;\nexport const GTM_ID: string = __GTM_ID__;\nexport const API_PREFIX = \"/api\";\nexport const WALLETCONNECT_PROJECT_ID = __WALLETCONNECT_PROJECT_ID__;\n\n// Assets base URL for wallet logos and other static assets\nexport const ASSETS_BASE_URL = \"https://app.trustware.io\";\n// export const ASSETS_BASE_URL = \"https://bv.trustware.io\";\n\n// WalletConnect Cloud project ID - built into the SDK for seamless wallet connections\n// This is a public identifier (not a secret) registered with WalletConnect Cloud\n// export const WALLETCONNECT_PROJECT_ID = \"4ead125c-63be-4b1a-a835-cef2dce67b84\";\n"],"mappings":";AAMO,IAAM,WAAW;AACjB,IAAM,cAAsB;AAC5B,IAAM,WAAmB;AACzB,IAAM,SAAiB;AACvB,IAAM,aAAa;AACnB,IAAM,2BAA2B;AAGjC,IAAM,kBAAkB;","names":[]}

package/dist/{core-BQ0mFnLc.d.ts → core-CwT8Wd1x.d.ts}

@@ -1,6 +1,6 @@
-import { B as BuildRouteResult, T as Transaction, v as TrustwareConfigOptions, P as WalletInterFaceAPI, j as ResolvedTrustwareConfig, M as WalletIdentity, a7 as walletManager, C as WalletAddressResolution, X as buildRoute, V as buildDepositAddress, a1 as submitReceipt, _ as getStatus, $ as pollStatus } from './manager-aOd3vkF9.js';
-import { C as ChainDef, c as ChainType, B as BalanceRow, a as BalanceStreamOptions, W as WalletAddressBalanceWrapper } from './blockchain-BONedEsU.js';
-import { T as Token } from './types-MtdjJgwT.js';
+import { B as BuildRouteResult, b as Transaction, T as TrustwareConfigOptions, W as WalletInterFaceAPI, m as ResolvedTrustwareConfig, y as TrustwareTheme, N as WalletIdentity, a0 as walletManager, G as WalletAddressResolution, a3 as buildRoute, a4 as buildDepositAddress, a5 as submitReceipt, a6 as getStatus, a7 as pollStatus } from './manager-xFiq0SHr.js';
+import { C as ChainDef, c as ChainType, G as GetBalancesOptions, B as BalanceRow, a as BalanceStreamOptions, W as WalletAddressBalanceWrapper } from './blockchain-BxAFzp0s.js';
+import { T as Token } from './types-BJY9r-mz.js';
 
 type AddressValidationResult = {
     isValid: boolean;
@@ -21,7 +21,7 @@ declare function validateRouteAddresses(params: {
 }): AddressValidationResult;
 
 /** Map chain reference -> backend chain_key and return enriched balances */
-declare function getBalances(chainRef: string | number, address: string): Promise<BalanceRow[]>;
+declare function getBalances(chainRef: string | number, address: string, opts?: GetBalancesOptions): Promise<BalanceRow[]>;
 declare function getBalancesByAddress(address: string, opts?: BalanceStreamOptions): Promise<WalletAddressBalanceWrapper[]>;
 declare function getBalancesByAddressStream(address: string, opts?: BalanceStreamOptions): AsyncGenerator<WalletAddressBalanceWrapper[], void, void>;
 
@@ -85,6 +85,34 @@ declare const Trustware: {
     autoDetect(_timeoutMs?: number): Promise<boolean>;
     /** Read resolved config */
     getConfig(): ResolvedTrustwareConfig;
+    /**
+     * Read the SDK's currently configured theme mode.
+     *
+     * Returns the raw setting — `"light" | "dark" | "system"` — i.e. whatever
+     * was last passed to `init()` or `setTheme()`. When the mode is `"system"`,
+     * the widget resolves the actual light/dark appearance itself (from the OS
+     * `prefers-color-scheme`, or a saved preference if the user has used the
+     * widget's built-in theme toggle), so this getter still reports `"system"`
+     * rather than the resolved value.
+     */
+    getTheme(): TrustwareTheme;
+    /**
+     * Set the widget's theme at runtime.
+     *
+     * Call this from your own app's theme toggle to keep an embedded
+     * `TrustwareWidget` in sync with your UI — no remount required, any
+     * mounted widget picks up the change immediately.
+     *
+     * Passing `"light"` or `"dark"` pins the widget to that mode. Passing
+     * `"system"` makes it follow the OS preference again — unless the user
+     * previously used the widget's own in-widget theme toggle, in which case
+     * their saved choice takes precedence until they toggle it again.
+     *
+     * @example
+     * // In your app's own dark-mode toggle handler:
+     * Trustware.setTheme(isDark ? "dark" : "light");
+     */
+    setTheme(theme: TrustwareTheme): /*elided*/ any;
     setDestinationAddress(address?: string | null): /*elided*/ any;
     setDestinationChain(chain: string): /*elided*/ any;
     setDestinationToken(token: string): /*elided*/ any;

package/dist/{core-BjQwlpoI.d.cts → core-Dy_rZl5y.d.cts}

@@ -1,6 +1,6 @@
-import { B as BuildRouteResult, T as Transaction, v as TrustwareConfigOptions, P as WalletInterFaceAPI, j as ResolvedTrustwareConfig, M as WalletIdentity, a7 as walletManager, C as WalletAddressResolution, X as buildRoute, V as buildDepositAddress, a1 as submitReceipt, _ as getStatus, $ as pollStatus } from './manager-DKVW7zeh.cjs';
-import { C as ChainDef, c as ChainType, B as BalanceRow, a as BalanceStreamOptions, W as WalletAddressBalanceWrapper } from './blockchain-BONedEsU.cjs';
-import { T as Token } from './types-B3nKHW6H.cjs';
+import { B as BuildRouteResult, b as Transaction, T as TrustwareConfigOptions, W as WalletInterFaceAPI, m as ResolvedTrustwareConfig, y as TrustwareTheme, N as WalletIdentity, a0 as walletManager, G as WalletAddressResolution, a3 as buildRoute, a4 as buildDepositAddress, a5 as submitReceipt, a6 as getStatus, a7 as pollStatus } from './manager-B5aklGtm.cjs';
+import { C as ChainDef, c as ChainType, G as GetBalancesOptions, B as BalanceRow, a as BalanceStreamOptions, W as WalletAddressBalanceWrapper } from './blockchain-BxAFzp0s.cjs';
+import { T as Token } from './types-DX3HtFcn.cjs';
 
 type AddressValidationResult = {
     isValid: boolean;
@@ -21,7 +21,7 @@ declare function validateRouteAddresses(params: {
 }): AddressValidationResult;
 
 /** Map chain reference -> backend chain_key and return enriched balances */
-declare function getBalances(chainRef: string | number, address: string): Promise<BalanceRow[]>;
+declare function getBalances(chainRef: string | number, address: string, opts?: GetBalancesOptions): Promise<BalanceRow[]>;
 declare function getBalancesByAddress(address: string, opts?: BalanceStreamOptions): Promise<WalletAddressBalanceWrapper[]>;
 declare function getBalancesByAddressStream(address: string, opts?: BalanceStreamOptions): AsyncGenerator<WalletAddressBalanceWrapper[], void, void>;
 
@@ -85,6 +85,34 @@ declare const Trustware: {
     autoDetect(_timeoutMs?: number): Promise<boolean>;
     /** Read resolved config */
     getConfig(): ResolvedTrustwareConfig;
+    /**
+     * Read the SDK's currently configured theme mode.
+     *
+     * Returns the raw setting — `"light" | "dark" | "system"` — i.e. whatever
+     * was last passed to `init()` or `setTheme()`. When the mode is `"system"`,
+     * the widget resolves the actual light/dark appearance itself (from the OS
+     * `prefers-color-scheme`, or a saved preference if the user has used the
+     * widget's built-in theme toggle), so this getter still reports `"system"`
+     * rather than the resolved value.
+     */
+    getTheme(): TrustwareTheme;
+    /**
+     * Set the widget's theme at runtime.
+     *
+     * Call this from your own app's theme toggle to keep an embedded
+     * `TrustwareWidget` in sync with your UI — no remount required, any
+     * mounted widget picks up the change immediately.
+     *
+     * Passing `"light"` or `"dark"` pins the widget to that mode. Passing
+     * `"system"` makes it follow the OS preference again — unless the user
+     * previously used the widget's own in-widget theme toggle, in which case
+     * their saved choice takes precedence until they toggle it again.
+     *
+     * @example
+     * // In your app's own dark-mode toggle handler:
+     * Trustware.setTheme(isDark ? "dark" : "light");
+     */
+    setTheme(theme: TrustwareTheme): /*elided*/ any;
     setDestinationAddress(address?: string | null): /*elided*/ any;
     setDestinationChain(chain: string): /*elided*/ any;
     setDestinationToken(token: string): /*elided*/ any;

package/dist/core.cjs

@@ -75,7 +75,7 @@ var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
     SDK_NAME = "@trustware/sdk";
-    SDK_VERSION = "1.1.8-staging.8";
+    SDK_VERSION = "1.1.9-staging.3";
     API_ROOT = "https://bv-staging-api.trustware.io";
     API_PREFIX = "/api";
     WALLETCONNECT_PROJECT_ID = "72ea74c400f5111d43aea638d7d83a24";
@@ -93,16 +93,6 @@ var init_config2 = __esm({
 });
 
 // src/core/http.ts
-var http_exports = {};
-__export(http_exports, {
-  RateLimitError: () => RateLimitError,
-  apiBase: () => apiBase,
-  assertOK: () => assertOK,
-  jsonHeaders: () => jsonHeaders,
-  parseRateLimitHeaders: () => parseRateLimitHeaders,
-  rateLimitedFetch: () => rateLimitedFetch,
-  validateSdkAccess: () => validateSdkAccess
-});
 function apiBase() {
   return `${API_ROOT}${API_PREFIX}`;
 }
@@ -300,11 +290,6 @@ var init_chains = __esm({
 });
 
 // src/registry.ts
-var registry_exports = {};
-__export(registry_exports, {
-  NATIVE: () => NATIVE,
-  Registry: () => Registry
-});
 function getChainAliases(chain) {
   const values = [
     chain.chainId,
@@ -1838,7 +1823,7 @@ async function parseStreamingBalances(response, address, options = {}) {
   }
   return stream();
 }
-async function getBalances(chainRef, address) {
+async function getBalances(chainRef, address, opts) {
   const reg = await ensureRegistry();
   const chain = reg.chain(chainRef);
   if (!chain) return [];
@@ -1853,8 +1838,10 @@ async function getBalances(chainRef, address) {
     chain.nativeCurrency?.decimals ?? "",
     normalizeChainType(chain) ?? ""
   ].join(":");
-  const cached = balanceCache.get(cacheKey);
-  if (cached) return cached;
+  if (!opts?.forceRefresh) {
+    const cached = balanceCache.get(cacheKey);
+    if (cached) return cached;
+  }
   const url = `${apiBase()}/v1/data/wallets/${encodeURIComponent(chainKey)}/${trimmedAddress}/balances`;
   const response = await fetch(url, {
     method: "GET",
@@ -2167,11 +2154,27 @@ function toSolanaWalletInterface(provider) {
         serializedTransactionBase64
       );
       if (provider.signAndSendTransaction) {
-        const result = await provider.signAndSendTransaction(transaction, {
-          preflightCommitment: "confirmed"
-        });
-        if (typeof result === "string") return result;
-        if (result?.signature) return result.signature;
+        const MAX_INTERNAL_ERROR_ATTEMPTS = 3;
+        const INTERNAL_ERROR_RETRY_DELAY_MS = 500;
+        for (let attempt = 1; attempt <= MAX_INTERNAL_ERROR_ATTEMPTS; attempt++) {
+          try {
+            const result = await provider.signAndSendTransaction(transaction, {
+              skipPreflight: true
+            });
+            if (typeof result === "string") return result;
+            if (result?.signature) return result.signature;
+            break;
+          } catch (err) {
+            const code = err?.code;
+            if (code === -32603 && attempt < MAX_INTERNAL_ERROR_ATTEMPTS) {
+              await new Promise(
+                (resolve) => setTimeout(resolve, INTERNAL_ERROR_RETRY_DELAY_MS * attempt)
+              );
+              continue;
+            }
+            throw err;
+          }
+        }
       }
       if (!provider.signTransaction) {
         throw new Error("Connected Solana wallet cannot sign transactions");
@@ -3901,6 +3904,10 @@ var init_routes = __esm({
 });
 
 // src/core/registryClient.ts
+var registryClient_exports = {};
+__export(registryClient_exports, {
+  getSharedRegistry: () => getSharedRegistry
+});
 function registryCacheKey() {
   const base = apiBase();
   const apiKey = TrustwareConfigStore.peek()?.apiKey ?? "__uninitialized__";
@@ -6068,7 +6075,6 @@ function resolveConfig(input) {
     defaultSlippage: normalizeSlippage(
       input.routes.defaultSlippage ?? DEFAULT_SLIPPAGE
     ),
-    routeType: input.routes.routeType ?? "swap",
     options: {
       ...input.routes.options
     }
@@ -6268,10 +6274,9 @@ async function sendRouteTransaction(b, fallbackChainId) {
     if (w.ecosystem !== "solana") {
       throw new Error("A Solana wallet is required for this route");
     }
-    const { Registry: Registry2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-    const { apiBase: apiBase2 } = await Promise.resolve().then(() => (init_http(), http_exports));
-    const registry = new Registry2(apiBase2());
-    await registry.ensureLoaded();
+    const { getSharedRegistry: getSharedRegistry2 } = await Promise.resolve().then(() => (init_registryClient(), registryClient_exports));
+    const registry = getSharedRegistry2();
+    await registry.ensureChainsLoaded();
     const chain = registry.chain(
       String(fallbackChainId ?? txReq.chainId ?? "")
     );
@@ -6285,9 +6290,8 @@ async function sendRouteTransaction(b, fallbackChainId) {
 async function runTopUp(params) {
   const w = walletManager.wallet;
   if (!w) throw new Error("Trustware.wallet not configured");
-  const { Registry: Registry2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-  const { apiBase: apiBase2 } = await Promise.resolve().then(() => (init_http(), http_exports));
-  const reg = new Registry2(apiBase2());
+  const { getSharedRegistry: getSharedRegistry2 } = await Promise.resolve().then(() => (init_registryClient(), registryClient_exports));
+  const reg = getSharedRegistry2();
   await reg.ensureLoaded();
   const fromAddress = await w.getAddress();
   const currentChainRef = w.ecosystem === "evm" ? String(await w.getChainId()) : await w.getChainKey?.() ?? "solana-mainnet-beta";
@@ -6398,6 +6402,39 @@ var init_core = __esm({
       getConfig() {
         return TrustwareConfigStore.get();
       },
+      /**
+       * Read the SDK's currently configured theme mode.
+       *
+       * Returns the raw setting — `"light" | "dark" | "system"` — i.e. whatever
+       * was last passed to `init()` or `setTheme()`. When the mode is `"system"`,
+       * the widget resolves the actual light/dark appearance itself (from the OS
+       * `prefers-color-scheme`, or a saved preference if the user has used the
+       * widget's built-in theme toggle), so this getter still reports `"system"`
+       * rather than the resolved value.
+       */
+      getTheme() {
+        return TrustwareConfigStore.get().theme;
+      },
+      /**
+       * Set the widget's theme at runtime.
+       *
+       * Call this from your own app's theme toggle to keep an embedded
+       * `TrustwareWidget` in sync with your UI — no remount required, any
+       * mounted widget picks up the change immediately.
+       *
+       * Passing `"light"` or `"dark"` pins the widget to that mode. Passing
+       * `"system"` makes it follow the OS preference again — unless the user
+       * previously used the widget's own in-widget theme toggle, in which case
+       * their saved choice takes precedence until they toggle it again.
+       *
+       * @example
+       * // In your app's own dark-mode toggle handler:
+       * Trustware.setTheme(isDark ? "dark" : "light");
+       */
+      setTheme(theme) {
+        TrustwareConfigStore.update({ theme });
+        return Trustware;
+      },
       setDestinationAddress(address) {
         const prev = TrustwareConfigStore.get();
         TrustwareConfigStore.update({