@coti-io/coti-wallet-plugin 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -574,6 +574,7 @@ var init_plugin = __esm({
       defaultNetworkId: void 0,
       debug: false,
       clearSessionKeyOnWagmiDisconnect: false,
+      waitForBalanceRefreshAfterTransfer: false,
       onboardingServices: { mode: "disabled" },
       onboardingGrantMinBalanceWei: 0,
       onboardingGrantPollIntervalMs: 2e3,
@@ -3672,6 +3673,17 @@ var usePrivateTokenBalance = () => {
       if (error instanceof CotiPluginError) {
         throw error;
       }
+      const message = error instanceof Error ? error.message : String(error?.message ?? error ?? "");
+      const code = error?.code;
+      const isDecryptPayloadFailure = message.includes("Invalid encrypted payload") || code === -32603 && /encrypt|decrypt|ciphertext/i.test(message);
+      if (isDecryptPayloadFailure || canUseSnapDecrypt) {
+        logger.error(`\u274C Failed to decrypt private balance for ${contractAddress}`, error);
+        throw new CotiPluginError(
+          "AES_KEY_MISMATCH" /* AES_KEY_MISMATCH */,
+          isDecryptPayloadFailure ? "Could not decrypt private balances. The Snap AES key may be missing or invalid \u2014 re-onboarding is required." : "Could not decrypt private balances via Snap. Re-onboarding may be required.",
+          message
+        );
+      }
       logger.error(`\u274C Failed to fetch/decrypt for ${contractAddress}`, error);
       return "0.00";
     }
@@ -4072,7 +4084,7 @@ var useBalanceUpdater = ({
                   return { symbol: token.symbol, value, isMismatch: false };
                 } catch (e) {
                   const msg = e?.message || "";
-                  const isMismatch = msg.includes("AES key mismatch") || msg.includes("onboarding") || msg.includes("ACCOUNT_NOT_ONBOARDED") || msg.includes("implausible decrypted balance");
+                  const isMismatch = e instanceof CotiPluginError && (e.code === "AES_KEY_MISMATCH" /* AES_KEY_MISMATCH */ || e.code === "ACCOUNT_NOT_ONBOARDED" /* ACCOUNT_NOT_ONBOARDED */) || msg.includes("AES key mismatch") || msg.includes("Invalid encrypted payload") || msg.includes("onboarding") || msg.includes("ACCOUNT_NOT_ONBOARDED") || msg.includes("implausible decrypted balance");
                   if (isMismatch) {
                     logger.warn(`\u26A0\uFE0F Private token decrypt mismatch for ${tokenAddress}. Falling back to 0.`);
                     return { symbol: token.symbol, value: "0", isMismatch: true };
@@ -7363,7 +7375,7 @@ var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function useAesKeyProvider(walletTypeInfo) {
   const [isOnboarding, setIsOnboarding] = useState10(false);
   const [onboardingError, setOnboardingError] = useState10(null);
-  const [onboardingWarning, setOnboardingWarning] = useState10(null);
+  const [onboardingWarnings, setOnboardingWarnings] = useState10({});
   const [wasRestoreCancelled, setWasRestoreCancelled] = useState10(false);
   const [currentStep, setCurrentStep] = useState10("idle");
   const progressCallbackRef = useRef7();
@@ -7384,7 +7396,7 @@ function useAesKeyProvider(walletTypeInfo) {
       progressCallbackRef.current = onProgress ?? options.onProgress;
       setOnboardingError(null);
       debugTraceRef.current.clear();
-      setOnboardingWarning(null);
+      setOnboardingWarnings({});
       setWasRestoreCancelled(false);
       const forceContractOnboarding = options?.forceContractOnboarding === true;
       if (!forceContractOnboarding) {
@@ -7493,7 +7505,9 @@ function useAesKeyProvider(walletTypeInfo) {
               }
             } catch (restoreError) {
               if (isUserRejection(restoreError)) {
-                setOnboardingWarning("Backup restore was cancelled. Approve the wallet signature to unlock from your encrypted backup.");
+                setOnboardingWarnings({
+                  intro: "Backup restore was cancelled. Approve the wallet signature to unlock from your encrypted backup."
+                });
                 setWasRestoreCancelled(true);
                 options.onRestoreCancelled?.();
                 emitStep("idle");
@@ -7502,7 +7516,9 @@ function useAesKeyProvider(walletTypeInfo) {
               const message = restoreError instanceof Error ? restoreError.message : "Encrypted AES backup could not be restored.";
               logger.warn("\u26A0\uFE0F AES backup restore failed, falling back to contract onboarding:", restoreError);
               restoreBackupFailed = true;
-              setOnboardingWarning(`Encrypted backup could not be restored. Continuing with onboarding. ${message}`);
+              setOnboardingWarnings({
+                intro: `Encrypted backup could not be restored. Continuing with onboarding. ${message}`
+              });
             }
           }
           if (options.restoreOnly) {
@@ -7663,9 +7679,9 @@ function useAesKeyProvider(walletTypeInfo) {
             savedToSnap = await saveAESKeyToSnap(aesKey, address);
             if (!savedToSnap) {
               logger.warn("\u26A0\uFE0F AES key retrieved but could not persist to Snap");
-              setOnboardingWarning(
-                "Onboarding succeeded, but the AES key could not be saved to MetaMask Snap. You can retry by unlocking again."
-              );
+              setOnboardingWarnings({
+                success: "Onboarding succeeded, but the AES key could not be saved to MetaMask Snap. You can retry by unlocking again."
+              });
             }
           } else if (aesKey && walletTypeInfo.walletType === "metamask" && canPersistAesKeyToSnap() && !walletTypeInfo.isMetaMaskWithSnap) {
             logger.log(
@@ -7687,14 +7703,14 @@ function useAesKeyProvider(walletTypeInfo) {
                 "\u26A0\uFE0F AES key retrieved but encrypted backup save failed:",
                 backupResult.message
               );
-              setOnboardingWarning(
-                `Onboarding succeeded, but encrypted backup was not saved. ${backupResult.message}`
-              );
+              setOnboardingWarnings({
+                success: `Onboarding succeeded, but encrypted backup was not saved. ${backupResult.message}`
+              });
             } else if (backupResult.status === "cancelled") {
               logger.warn("\u26A0\uFE0F AES key retrieved but encrypted backup save was cancelled");
-              setOnboardingWarning(
-                "Onboarding succeeded, but encrypted backup save was cancelled. You can save it later by re-entering your AES key."
-              );
+              setOnboardingWarnings({
+                success: "Onboarding succeeded, but encrypted backup save was cancelled. You can save it later by re-entering your AES key."
+              });
             }
           }
           if (aesKey && isValidAesKey(aesKey)) {
@@ -7758,7 +7774,7 @@ function useAesKeyProvider(walletTypeInfo) {
     getAesKey,
     isOnboarding,
     onboardingError,
-    onboardingWarning,
+    onboardingWarnings,
     wasRestoreCancelled,
     currentStep
   };
@@ -7866,7 +7882,7 @@ var usePrivacyBridgeSessionCore = ({
     getAesKey: getAesKeyFromProvider,
     isOnboarding,
     onboardingError,
-    onboardingWarning
+    onboardingWarnings
   } = useAesKeyProvider(walletTypeInfo);
   const { fetchPrivateBalance } = usePrivateTokenBalance();
   useEffect9(() => {
@@ -7922,7 +7938,7 @@ var usePrivacyBridgeSessionCore = ({
     fetchPrivateBalance,
     getAesKeyFromProvider,
     onboardingError,
-    onboardingWarning
+    onboardingWarnings
   };
 };
 
@@ -8554,6 +8570,7 @@ var usePrivacyBridgeWalletConnection = ({
 };
 
 // src/context/privacyBridge/usePrivacyBridgeUnlockSession.ts
+init_plugin();
 init_logger();
 import { useCallback as useCallback17 } from "react";
 import { useAccount as useAccount9 } from "wagmi";
@@ -8825,6 +8842,13 @@ var usePrivacyBridgeUnlockSession = ({
   }, [resolveAesAccess, resolveSessionAesKey, walletAddress, aesKeyChainId, checkSnapStatus, hasAesKeyInSnap, walletTypeInfo.walletType, currentChainId]);
   const refreshPrivateBalances = useCallback17(async (aesKeyOptions) => {
     if (!walletAddress) return false;
+    const lockSessionOnAesFailure = !aesKeyOptions?.preserveSessionOnError;
+    const clearSessionAfterAesFailure = () => {
+      setSessionAesKey(null);
+      clearAesKeyValidatedForUnlock(walletAddress);
+      clearSnapCache();
+      setArePrivateBalancesHidden(true);
+    };
     logger.log("Triggering private balance fetch...");
     try {
       const chainOverride = wagmiSyncRef.current ? wagmiChainId : void 0;
@@ -8903,10 +8927,7 @@ var usePrivacyBridgeUnlockSession = ({
         );
       }
       if (errorInfo.message?.includes("ACCOUNT_NOT_ONBOARDED")) {
-        setSessionAesKey(null);
-        clearAesKeyValidatedForUnlock(walletAddress);
-        clearSnapCache();
-        setArePrivateBalancesHidden(true);
+        if (lockSessionOnAesFailure) clearSessionAfterAesFailure();
         throw new CotiPluginError(
           "ACCOUNT_NOT_ONBOARDED" /* ACCOUNT_NOT_ONBOARDED */,
           "Account has not been onboarded to the COTI network.",
@@ -8914,17 +8935,11 @@ var usePrivacyBridgeUnlockSession = ({
         );
       }
       if (err instanceof CotiPluginError && err.code === "AES_KEY_MISMATCH" /* AES_KEY_MISMATCH */) {
-        setSessionAesKey(null);
-        clearAesKeyValidatedForUnlock(walletAddress);
-        clearSnapCache();
-        setArePrivateBalancesHidden(true);
+        if (lockSessionOnAesFailure) clearSessionAfterAesFailure();
         throw err;
       }
       if (errorInfo.message?.includes("AES key") || errorInfo.message?.includes("onboarding")) {
-        setSessionAesKey(null);
-        clearAesKeyValidatedForUnlock(walletAddress);
-        clearSnapCache();
-        setArePrivateBalancesHidden(true);
+        if (lockSessionOnAesFailure) clearSessionAfterAesFailure();
         throw new CotiPluginError(
           "AES_KEY_MISMATCH" /* AES_KEY_MISMATCH */,
           "AES key mismatch or onboarding error.",
@@ -8969,7 +8984,13 @@ var usePrivacyBridgeUnlockSession = ({
       hasSnap: strategy.snapInstalled,
       getAESKeyFromSnap: strategy.snapInstalled ? getAESKeyFromSnap : void 0
     });
-    await refreshPrivateBalances();
+    if (getPluginConfig().waitForBalanceRefreshAfterTransfer) {
+      await refreshPrivateBalances();
+    } else {
+      void refreshPrivateBalances({ preserveSessionOnError: true }).catch(
+        (err) => logger.error("Background balance refresh after transfer failed", err)
+      );
+    }
     return result;
   }, [
     walletAddress,
@@ -9119,7 +9140,7 @@ var usePrivacyBridgeSession = ({ modals }) => {
     refreshPublicBalances: unlock.refreshPublicBalances,
     refreshPrivateBalances: unlock.refreshPrivateBalances,
     onboardingError: core.onboardingError,
-    onboardingWarning: core.onboardingWarning,
+    onboardingWarnings: core.onboardingWarnings,
     lockPrivateBalances: unlock.lockPrivateBalances,
     saveManualAesKey: unlock.saveManualAesKey,
     sendPrivateToken: unlock.sendPrivateToken,
@@ -9492,6 +9513,40 @@ function deriveOnboardScreen({
 
 // src/components/OnboardModal.tsx
 init_logger();
+
+// src/lib/onboardModalWarnings.ts
+function mergeOnboardModalWarnings(...sources) {
+  const merged = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const page of Object.keys(source)) {
+      const message = source[page];
+      if (message) {
+        merged[page] = message;
+      }
+    }
+  }
+  return merged;
+}
+function getDefaultSuccessWarning(saveBackup) {
+  return saveBackup ? "Important: An encrypted backup can help restore this key later, but you should still store it safely." : "Important: This key will be lost when you refresh the page. Store it in a secure location.";
+}
+function resolveOnboardPageWarning(page, options) {
+  const runtime = options.runtimeWarnings?.[page]?.trim();
+  if (runtime) return runtime;
+  const app = options.warnings?.[page]?.trim();
+  if (app) return app;
+  if (page === "success") {
+    return getDefaultSuccessWarning(options.saveBackup ?? true);
+  }
+  return null;
+}
+function hasOnboardModalWarnings(warnings) {
+  if (!warnings) return false;
+  return Object.values(warnings).some((message) => !!message?.trim());
+}
+
+// src/components/OnboardModal.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var defaultStyles = {
   backdrop: {
@@ -9663,28 +9718,23 @@ var defaultStyles = {
   },
   saveOptionBody: {
     flex: 1,
-    minWidth: 0
+    minWidth: 0,
+    display: "flex",
+    alignItems: "center",
+    minHeight: "32px"
   },
   saveOptionTitleRow: {
     display: "flex",
     alignItems: "center",
-    gap: "5px",
-    marginBottom: "2px"
+    gap: "5px"
   },
   saveOptionTitle: {
     fontSize: "13px",
     fontWeight: 600,
-    lineHeight: 1.25,
-    color: "#ffffff"
-  },
-  saveOptionDescription: {
-    fontSize: "11px",
-    lineHeight: 1.3,
-    color: "rgba(255, 255, 255, 0.55)",
-    margin: 0,
-    whiteSpace: "nowrap",
-    overflow: "hidden",
-    textOverflow: "ellipsis"
+    lineHeight: "14px",
+    color: "#ffffff",
+    display: "inline-flex",
+    alignItems: "center"
   },
   saveOptionSwitchTrack: {
     position: "relative",
@@ -9726,12 +9776,13 @@ var defaultStyles = {
   tooltipButton: {
     width: "14px",
     height: "14px",
+    boxSizing: "border-box",
     borderRadius: "50%",
     border: "1px solid rgba(255, 255, 255, 0.25)",
     backgroundColor: "rgba(255, 255, 255, 0.08)",
     color: "rgba(255, 255, 255, 0.8)",
     fontSize: "9px",
-    lineHeight: 1,
+    lineHeight: "12px",
     padding: 0,
     cursor: "help",
     flexShrink: 0,
@@ -10035,8 +10086,7 @@ var MUTED_TEXT_KEYS = [
   "closeButton",
   "tooltipButton",
   "cancelButton",
-  "stepDescription",
-  "saveOptionDescription"
+  "stepDescription"
 ];
 var ACCENT_TEXT_KEYS = [
   "keyInput",
@@ -10086,7 +10136,8 @@ var LIGHT_INTERACTIVE_SURFACE_KEYS = [
   "saveOptionCard",
   "saveOptionIconWrap",
   "saveOptionSwitchTrackOff",
-  "saveOptionSwitchTrackOn"
+  "saveOptionSwitchTrackOn",
+  "tooltipButton"
 ];
 function isDefaultDarkSurfaceBackground(backgroundColor) {
   if (!backgroundColor) return true;
@@ -10170,6 +10221,11 @@ function applyLightInteractiveSurfaceGaps(merged, theme) {
     saveOptionSwitchTrackOn: {
       backgroundColor: primary,
       borderColor: colorWithAlpha(primary, 0.45)
+    },
+    tooltipButton: {
+      color: muted2,
+      backgroundColor: colorWithAlpha(foreground, 0.08),
+      border: `1px solid ${colorWithAlpha(foreground, 0.2)}`
     }
   };
   for (const key of LIGHT_INTERACTIVE_SURFACE_KEYS) {
@@ -10316,7 +10372,8 @@ var OnboardModal = ({
   showSaveBackupOption = true,
   onSaveBackupChange,
   onManualAesKeySubmit,
-  warning,
+  warnings,
+  runtimeWarnings,
   theme
 }) => {
   const [copied, setCopied] = useState14(false);
@@ -10362,6 +10419,15 @@ var OnboardModal = ({
     /* @__PURE__ */ jsx("div", { style: styles2.iconContainer, children: icon }),
     /* @__PURE__ */ jsx("h2", { id: "onboard-modal-title", style: styles2.title, children: title })
   ] });
+  const renderPageWarning = (page) => {
+    const message = resolveOnboardPageWarning(page, {
+      warnings,
+      runtimeWarnings,
+      saveBackup
+    });
+    if (!message) return null;
+    return /* @__PURE__ */ jsx("div", { style: warningStyles.box, children: /* @__PURE__ */ jsx("p", { style: warningStyles.text, children: message }) });
+  };
   const renderSaveLocallyOption = () => {
     if (!showSaveBackupOption) return null;
     return /* @__PURE__ */ jsxs(
@@ -10373,29 +10439,26 @@ var OnboardModal = ({
         },
         children: [
           /* @__PURE__ */ jsx("div", { style: styles2.saveOptionIconWrap, "aria-hidden": "true", children: /* @__PURE__ */ jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ jsx("path", { d: "M21 2l-2 2m-7.61 7.61a5.5 5.5 0 1 1-7.778 7.778 5.5 5.5 0 0 1 7.777-7.777zm0 0L15.5 7.5m0 0 3 3L22 7l-3-3m-3.5 3.5L19 4" }) }) }),
-          /* @__PURE__ */ jsxs("div", { style: styles2.saveOptionBody, children: [
-            /* @__PURE__ */ jsxs("div", { style: styles2.saveOptionTitleRow, children: [
-              /* @__PURE__ */ jsx("span", { style: styles2.saveOptionTitle, children: "Save Locally" }),
-              /* @__PURE__ */ jsxs("span", { style: styles2.tooltipWrap, children: [
-                /* @__PURE__ */ jsx(
-                  "button",
-                  {
-                    type: "button",
-                    "aria-label": "How local save works",
-                    "aria-describedby": showBackupTooltip ? "backup-details-tooltip" : void 0,
-                    onMouseEnter: () => setShowBackupTooltip(true),
-                    onMouseLeave: () => setShowBackupTooltip(false),
-                    onFocus: () => setShowBackupTooltip(true),
-                    onBlur: () => setShowBackupTooltip(false),
-                    style: styles2.tooltipButton,
-                    children: "?"
-                  }
-                ),
-                showBackupTooltip && /* @__PURE__ */ jsx("span", { id: "backup-details-tooltip", role: "tooltip", style: styles2.tooltipBubble, children: "Only an encrypted blob is stored locally. Restoring it requires a wallet signature." })
-              ] })
-            ] }),
-            /* @__PURE__ */ jsx("p", { style: styles2.saveOptionDescription, children: "Encrypted locally. Restore via wallet signature." })
-          ] }),
+          /* @__PURE__ */ jsx("div", { style: styles2.saveOptionBody, children: /* @__PURE__ */ jsxs("div", { style: styles2.saveOptionTitleRow, children: [
+            /* @__PURE__ */ jsx("span", { style: styles2.saveOptionTitle, children: "Save Locally" }),
+            /* @__PURE__ */ jsxs("span", { style: styles2.tooltipWrap, children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  "aria-label": "How local save works",
+                  "aria-describedby": showBackupTooltip ? "backup-details-tooltip" : void 0,
+                  onMouseEnter: () => setShowBackupTooltip(true),
+                  onMouseLeave: () => setShowBackupTooltip(false),
+                  onFocus: () => setShowBackupTooltip(true),
+                  onBlur: () => setShowBackupTooltip(false),
+                  style: styles2.tooltipButton,
+                  children: "?"
+                }
+              ),
+              showBackupTooltip && /* @__PURE__ */ jsx("span", { id: "backup-details-tooltip", role: "tooltip", style: styles2.tooltipBubble, children: "Only an encrypted blob is stored locally. Restoring it requires a wallet signature." })
+            ] })
+          ] }) }),
           /* @__PURE__ */ jsx(
             "button",
             {
@@ -10591,7 +10654,7 @@ var OnboardModal = ({
                   "Onboard User"
                 ),
                 /* @__PURE__ */ jsx("p", { id: "onboard-modal-description", style: styles2.description, children: "This will execute a transaction on the COTI Network to retrieve your encryption key." }),
-                warning && /* @__PURE__ */ jsx("div", { style: warningStyles.box, children: /* @__PURE__ */ jsx("p", { style: warningStyles.text, children: warning }) }),
+                renderPageWarning("intro"),
                 renderSaveLocallyOption(),
                 /* @__PURE__ */ jsxs(
                   "div",
@@ -10608,7 +10671,7 @@ var OnboardModal = ({
                             type: "text",
                             value: manualAesKey,
                             onChange: (event) => setManualAesKey(event.target.value),
-                            placeholder: "Paste AES key",
+                            placeholder: "Paste key",
                             "aria-label": "Manual AES key",
                             disabled: isSubmittingManualKey,
                             style: { ...styles2.manualKeyInput, ...styles2.actionPrimary },
@@ -10682,7 +10745,7 @@ var OnboardModal = ({
                   /* @__PURE__ */ jsx("div", { style: styles2.spinner }),
                   getProgressTitle(currentStep)
                 ),
-                warning && /* @__PURE__ */ jsx("div", { style: warningStyles.box, children: /* @__PURE__ */ jsx("p", { style: warningStyles.text, children: warning }) }),
+                renderPageWarning("progress"),
                 /* @__PURE__ */ jsx("div", { style: styles2.stepperContainer, children: displaySteps.map((step) => {
                   const status = getOnboardingStepStatus(step.id, currentStep, !!error, includePersistStep);
                   const isActive = status === "active";
@@ -10780,12 +10843,7 @@ var OnboardModal = ({
                     )
                   ] })
                 ] }),
-                /* @__PURE__ */ jsx("div", { style: warningStyles.box, children: /* @__PURE__ */ jsxs("p", { style: warningStyles.text, children: [
-                  /* @__PURE__ */ jsx("strong", { children: "Important:" }),
-                  " ",
-                  saveBackup ? "An encrypted backup can help restore this key later, but you should still store it safely." : "This key will be lost when you refresh the page. Store it in a secure location."
-                ] }) }),
-                warning && /* @__PURE__ */ jsx("div", { style: warningStyles.box, children: /* @__PURE__ */ jsx("p", { style: warningStyles.text, children: warning }) }),
+                renderPageWarning("success"),
                 /* @__PURE__ */ jsx(
                   "button",
                   {
@@ -10819,6 +10877,7 @@ var OnboardModal = ({
                 ),
                 /* @__PURE__ */ jsx("p", { id: "onboard-modal-description", style: styles2.description, children: "The onboarding process encountered an error. You can retry the signature request." }),
                 /* @__PURE__ */ jsx("div", { style: styles2.errorBox, children: /* @__PURE__ */ jsx("p", { style: styles2.errorText, children: error || "An unknown error occurred" }) }),
+                renderPageWarning("error"),
                 /* @__PURE__ */ jsx(
                   "button",
                   {
@@ -10929,14 +10988,14 @@ function keepForwardContractProgress(previous, next) {
   return nextOrder >= previousOrder ? next : previous;
 }
 function usePrivateUnlockController(options = {}) {
-  const { theme, warning, onUnlocked, onRestoreCancelled, onOnboardingCancelled } = options;
+  const { theme, warnings, onUnlocked, onRestoreCancelled, onOnboardingCancelled } = options;
   const unlock = usePrivacyBridgeUnlock();
   const wallet = usePrivacyBridgeWallet();
   const walletTypeInfo = useWalletType();
   const [showOnboardModal, setShowOnboardModal] = useState15(false);
   const [isUnlocking, setIsUnlocking] = useState15(false);
   const [modalError, setModalError] = useState15(null);
-  const [modalWarning, setModalWarning] = useState15(null);
+  const [modalRuntimeWarnings, setModalRuntimeWarnings] = useState15({});
   const [snapConnectedInModal, setSnapConnectedInModal] = useState15(false);
   const [saveBackup, setSaveBackup] = useState15(true);
   const [currentStep, setCurrentStep] = useState15("idle");
@@ -10973,7 +11032,7 @@ function usePrivateUnlockController(options = {}) {
     pendingActionOwnerRef.current = null;
     setCurrentStep("idle");
     setModalError(null);
-    setModalWarning(null);
+    setModalRuntimeWarnings({});
     backupSaveProgressStartedAtRef.current = null;
     pendingCompleteRequestIdRef.current = null;
     contractOnboardingCancelledRef.current = false;
@@ -11002,7 +11061,7 @@ function usePrivateUnlockController(options = {}) {
     setShowOnboardModal(false);
     setCurrentStep("idle");
     setModalError(null);
-    setModalWarning(null);
+    setModalRuntimeWarnings({});
     setIsUnlockInProgress(false);
     setIsUnlocking(false);
     backupSaveProgressStartedAtRef.current = null;
@@ -11027,7 +11086,7 @@ function usePrivateUnlockController(options = {}) {
     setShowOnboardModal(false);
     setCurrentStep("idle");
     setModalError(null);
-    setModalWarning(null);
+    setModalRuntimeWarnings({});
     unlockInProgressOwnerRef.current = null;
     setIsUnlockInProgress(false);
     setIsUnlocking(false);
@@ -11063,14 +11122,18 @@ function usePrivateUnlockController(options = {}) {
     try {
       const connected = await unlock.requestSnapConnection();
       if (!connected) {
-        setModalWarning("Snap connection was skipped or rejected. Continuing without Snap storage.");
+        setModalRuntimeWarnings({
+          intro: "Snap connection was skipped or rejected. Continuing without Snap storage."
+        });
         return false;
       }
       snapConnectedInModalRef.current = true;
       setSnapConnectedInModal(true);
       return true;
     } catch {
-      setModalWarning("Snap connection failed. Continuing without Snap storage.");
+      setModalRuntimeWarnings({
+        intro: "Snap connection failed. Continuing without Snap storage."
+      });
       return false;
     }
   }, [canAttemptSnapInstall, unlock]);
@@ -11104,15 +11167,13 @@ function usePrivateUnlockController(options = {}) {
     if (failureMessage) {
       setCurrentStep("error");
       setModalError(failureMessage);
-      setModalWarning(unlock.onboardingWarning ?? null);
       releaseUnlockInProgress(requestId);
       return;
     }
     setCurrentStep("error");
     setModalError("Onboarding did not complete. Please retry.");
-    setModalWarning(unlock.onboardingWarning ?? null);
     releaseUnlockInProgress(requestId);
-  }, [dismissOnboardModal, isActiveUnlockRequest, onOnboardingCancelled, releaseUnlockInProgress, unlock.onboardingWarning]);
+  }, [dismissOnboardModal, isActiveUnlockRequest, onOnboardingCancelled, releaseUnlockInProgress]);
   const handleStaleRestoreCompletion = useCallback19((requestId, refreshSucceeded) => {
     clearPendingActionForRequest(requestId);
     const unlocked = refreshSucceeded || isPrivateUnlockedRef.current;
@@ -11128,7 +11189,7 @@ function usePrivateUnlockController(options = {}) {
       setPendingActionForRequest(requestId, pendingAction);
     }
     setModalError(null);
-    setModalWarning(null);
+    setModalRuntimeWarnings({});
     inFlightRestoreRequestIdRef.current = requestId;
     setIsUnlocking(true);
     try {
@@ -11162,7 +11223,6 @@ function usePrivateUnlockController(options = {}) {
         return false;
       }
       setCurrentStep("idle");
-      setModalWarning(unlock.onboardingWarning ?? null);
       setShowOnboardModal(true);
       return false;
     } catch (error) {
@@ -11224,7 +11284,6 @@ function usePrivateUnlockController(options = {}) {
         contractOnboardingFailureRef.current = failureMessage;
         setCurrentStep("error");
         setModalError(failureMessage);
-        setModalWarning(unlock.onboardingWarning ?? null);
         releaseUnlockInProgress(unlockRequestIdRef.current);
       }
       return;
@@ -11236,7 +11295,7 @@ function usePrivateUnlockController(options = {}) {
     if (step === "idle") {
       setModalError(null);
     }
-  }, [currentStep, showOnboardModal, releaseUnlockInProgress, unlock.onboardingWarning]);
+  }, [currentStep, showOnboardModal, releaseUnlockInProgress]);
   const showOnboardingComplete = useCallback19((requestId) => {
     if (!isActiveUnlockRequest(requestId)) return;
     pendingCompleteRequestIdRef.current = null;
@@ -11254,7 +11313,7 @@ function usePrivateUnlockController(options = {}) {
     if (!connectedAddress) return;
     const requestId = unlockRequestIdRef.current;
     setModalError(null);
-    setModalWarning(null);
+    setModalRuntimeWarnings({});
     setIsUnlocking(true);
     setShowOnboardModal(true);
     setCurrentStep("preparing-onboard");
@@ -11289,7 +11348,7 @@ function usePrivateUnlockController(options = {}) {
         currentStep,
         hasSessionAesKey: !!unlock.sessionAesKey,
         hasOnboardingError: !!unlock.onboardingError,
-        hasOnboardingWarning: !!unlock.onboardingWarning
+        hasOnboardingWarning: hasOnboardModalWarnings(unlock.onboardingWarnings)
       });
       const backupSaveProgressStartedAt = backupSaveProgressStartedAtRef.current;
       if (backupSaveProgressStartedAt !== null) {
@@ -11405,7 +11464,7 @@ function usePrivateUnlockController(options = {}) {
       onSaveBackupChange: setSaveBackup,
       onManualAesKeySubmit: async (aesKey, { saveBackup: shouldSaveBackup }) => {
         const requestId = unlockRequestIdRef.current;
-        setModalWarning(null);
+        setModalRuntimeWarnings({});
         const manualSaveResult = await unlock.saveManualAesKey(aesKey, {
           saveBackup: shouldSaveBackup,
           onProgress: (step) => {
@@ -11426,7 +11485,7 @@ function usePrivateUnlockController(options = {}) {
           return;
         }
         if (manualSaveResult.backupWarning) {
-          setModalWarning(manualSaveResult.backupWarning);
+          setModalRuntimeWarnings({ success: manualSaveResult.backupWarning });
           setShowOnboardModal(true);
           setCurrentStep("complete");
           releaseUnlockInProgress(requestId);
@@ -11435,7 +11494,8 @@ function usePrivateUnlockController(options = {}) {
         await completeUnlock(requestId);
       },
       theme,
-      warning: modalWarning ?? unlock.onboardingWarning ?? warning ?? null
+      warnings,
+      runtimeWarnings: mergeOnboardModalWarnings(unlock.onboardingWarnings, modalRuntimeWarnings)
     }
   );
   return {
@@ -11608,7 +11668,7 @@ var PrivacyBridgeProvider = ({
       decryptPrivateValue: session.decryptPrivateValue,
       refreshPrivateBalances: session.refreshPrivateBalances,
       onboardingError: session.onboardingError,
-      onboardingWarning: session.onboardingWarning,
+      onboardingWarnings: session.onboardingWarnings,
       lockPrivateBalances: session.lockPrivateBalances,
       handleOnboard: session.handleOnboard,
       saveManualAesKey: session.saveManualAesKey,