feat(web): say once what the browser build cannot protect

The web bundle is the same wallet, but its at-rest container is not: in a plain
browser `kv-store` falls back to plaintext `localStorage` because there is no OS
keychain to reach, there is no biometric unlock, and clearing site data destroys
the wallet. wallet.fairco.in says that on the first visit and points at the
native builds.

Electron ships the SAME web bundle and is `Platform.OS === "web"`, but it
reaches the OS keychain through its preload bridge and IS the native desktop
app, so the notice would be wrong there — hence the `electronAPI` test rather
than a bare platform check.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: NateIsern

app/_layout.tsx

@@ -36,6 +36,7 @@ import { useExplorerRealtime } from "../src/hooks/useExplorerRealtime";
 import { useWalletStore } from "../src/wallet/wallet-store";
 import { useLockStore } from "../src/wallet/lock-store";
 import { LockGate } from "../src/ui/components/LockGate";
+import { WebWelcomeDialog } from "../src/ui/components/WebWelcomeDialog";
 import { ErrorBoundary } from "../src/ui/components/ErrorBoundary";
 import { installCrashHandler } from "../src/services/crash-log";
 import { getAutoLockTimeout } from "../src/storage/secure-store";
@@ -363,6 +364,10 @@ function AppContent({ ready }: { ready: boolean }) {
       {/* Full-screen lock overlay: covers every authenticated route while the
           app is locked so no screen can be reached behind it (finding C1). */}
       <LockGate />
+      {/* Browser-only first-visit notice: the web build stores keys in plain
+          site storage, so it says so once before the wallet is used. Renders
+          null on native and under Electron. */}
+      <WebWelcomeDialog />
     </View>
   );
 }

src/i18n/index.ts

@@ -866,6 +866,15 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
     "notificationsSettings.events.incomingPending": "Incoming (pending)",
     "notificationsSettings.events.incomingConfirmed": "Incoming (confirmed)",
     "notificationsSettings.events.outgoingConfirmed": "Sent (confirmed)",
+
+    // ---------- Web build welcome ----------
+    "webWelcome.title": "FAIRWallet in your browser",
+    "webWelcome.description": "This is the full wallet, running entirely in this tab — your keys never leave it. The native apps still protect them better.",
+    "webWelcome.caveat.storage": "In a browser your keys sit in this site's storage as plain text: there is no Keychain or Android keystore to lock them into.",
+    "webWelcome.caveat.lock": "No biometric or device unlock — anyone with access to this browser profile reaches the wallet.",
+    "webWelcome.caveat.siteData": "Clearing site data deletes the wallet. Back up your recovery phrase before you fund it.",
+    "webWelcome.getApp": "Get the app",
+    "webWelcome.continue": "Continue in browser",
   },
   es: {
     // ---------- Common ----------
@@ -1724,6 +1733,15 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
     "notificationsSettings.events.incomingPending": "Entrante (pendiente)",
     "notificationsSettings.events.incomingConfirmed": "Entrante (confirmado)",
     "notificationsSettings.events.outgoingConfirmed": "Enviado (confirmado)",
+
+    // ---------- Bienvenida a la versión web ----------
+    "webWelcome.title": "FAIRWallet en tu navegador",
+    "webWelcome.description": "Es la billetera completa, funcionando entera en esta pestaña: tus claves no salen de aquí. Aun así, las apps nativas las protegen mejor.",
+    "webWelcome.caveat.storage": "En el navegador tus claves se guardan en texto plano en el almacenamiento del sitio: no hay Keychain ni keystore de Android donde encerrarlas.",
+    "webWelcome.caveat.lock": "Sin desbloqueo biométrico ni del dispositivo: quien tenga acceso a este perfil del navegador llega a la billetera.",
+    "webWelcome.caveat.siteData": "Si borras los datos del sitio, borras la billetera. Guarda tu frase de recuperación antes de meterle fondos.",
+    "webWelcome.getApp": "Descargar la app",
+    "webWelcome.continue": "Seguir en el navegador",
   },
 };
 

src/ui/components/WebWelcomeDialog.tsx

@@ -0,0 +1,105 @@
+/**
+ * One-time welcome dialog for the browser build (wallet.fairco.in).
+ *
+ * The web bundle is the same wallet as the native app, but its at-rest
+ * container is not: `kv-store` falls back to plaintext `localStorage` in a
+ * plain browser because there is no OS keychain to reach — no Keychain /
+ * EncryptedSharedPreferences, no biometric unlock, and clearing site data
+ * destroys the wallet. That is a real difference in custody, so the browser
+ * says it out loud once, on first visit, and points at the native builds.
+ *
+ * Electron ships the SAME web bundle but reaches the OS keychain through its
+ * preload bridge and IS the native desktop app, so the warning would be wrong
+ * there — hence the `electronAPI` check rather than a bare `Platform.OS`
+ * test.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { Linking, Platform, Text, View } from "react-native";
+import MaterialCommunityIcons from "@expo/vector-icons/MaterialCommunityIcons";
+import { Dialog } from "@oxyhq/bloom/dialog";
+import { useTheme } from "@oxyhq/bloom/theme";
+import { t } from "../../i18n";
+import { getItemAsync, setItemAsync } from "../../storage/kv-store";
+
+const SEEN_KEY = "fairwallet_web_welcome_seen";
+
+const DOWNLOAD_URL = "https://fairco.in/wallet";
+
+/**
+ * True only in a plain browser tab. Electron's renderer is also
+ * `Platform.OS === "web"`, but it exposes the preload bridge, and it is the
+ * desktop app this dialog would otherwise be recommending.
+ */
+const isBrowser =
+  Platform.OS === "web" &&
+  typeof window !== "undefined" &&
+  !("electronAPI" in window);
+
+// Kick the storage round-trip off at module scope, like the root layout does
+// for the theme, so the flag is already in flight before the first render.
+const seenPromise = isBrowser
+  ? getItemAsync(SEEN_KEY).catch(() => null)
+  : Promise.resolve("1");
+
+const CAVEATS = [
+  "webWelcome.caveat.storage",
+  "webWelcome.caveat.lock",
+  "webWelcome.caveat.siteData",
+] as const;
+
+export function WebWelcomeDialog() {
+  const theme = useTheme();
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+    let active = true;
+    seenPromise.then((seen) => {
+      if (active && seen === null) setOpen(true);
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const dismiss = useCallback(() => {
+    setOpen(false);
+    void setItemAsync(SEEN_KEY, "1");
+  }, []);
+
+  const openDownloads = useCallback(() => {
+    void Linking.openURL(DOWNLOAD_URL);
+  }, []);
+
+  if (!isBrowser) return null;
+
+  return (
+    <Dialog
+      open={open}
+      onClose={dismiss}
+      placement={{ base: "bottom", md: "center" }}
+      title={t("webWelcome.title")}
+      description={t("webWelcome.description")}
+      actions={[
+        { label: t("webWelcome.getApp"), onPress: openDownloads },
+        { label: t("webWelcome.continue"), color: "cancel" },
+      ]}
+    >
+      <View className="gap-3 mt-2">
+        {CAVEATS.map((key) => (
+          <View key={key} className="flex-row gap-2.5">
+            <MaterialCommunityIcons
+              name="alert-circle-outline"
+              size={18}
+              color={theme.colors.textSecondary}
+            />
+            <Text className="text-muted-foreground text-sm flex-1">
+              {t(key)}
+            </Text>
+          </View>
+        ))}
+      </View>
+    </Dialog>
+  );
+}