feat(app): root error boundary and redacted crash log

A throw anywhere in the render tree unmounted the whole app and left a
black screen: no message, no way back, and for a wallet no indication of
whether funds were affected. There was no error boundary anywhere and no
record of what happened.

- ErrorBoundary wraps the app inside the theme provider, so the fallback is
  themed, and offers a retry that remounts the subtree.
- ErrorUtils.setGlobalHandler catches everything off the render path,
  chaining to the previous handler so the dev red box still appears.
- Entries are capped and persisted.

Redaction is a security control, not cosmetics: this is a wallet, the log
lives in unencrypted key-value storage and is meant to be readable and
shareable, and an error thrown while a mnemonic, WIF or xprv was in scope
can quote it in its message or a stack frame. crash-policy.ts holds the
pure rules so they are unit-testable without pulling React Native into the
test runner, matching the pin-attempts-policy split.

Also fixes two render-phase side effects surfaced while wiring this up:
app/_layout.tsx kicked off async work from the render body behind a ref
guard - which already errored on web with "state update on a component
that hasn't mounted yet" - and hid the splash the same way.

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

Author: NateIsern

app/_layout.tsx

@@ -26,15 +26,6 @@ import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";
 import { KeyboardProvider as NativeKeyboardProvider } from "react-native-keyboard-controller";
 import { SafeAreaProvider } from "react-native-safe-area-context";
-
-// react-native-keyboard-controller ships no web build — its KeyboardControllerView
-// is a native-only component that breaks the flex height chain on web and leaves
-// all scrollables with 0 bounded height. Web has no virtual keyboard anyway, so
-// we pass children straight through.
-const KeyboardProvider =
-  Platform.OS === "web"
-    ? ({ children }: { children: React.ReactNode }) => <>{children}</>
-    : NativeKeyboardProvider;
 import { QueryClientProvider } from "@tanstack/react-query";
 import { BloomThemeProvider, useBloomTheme } from "@oxyhq/bloom/theme";
 import type { ThemeMode } from "@oxyhq/bloom/theme";
@@ -44,6 +35,8 @@ 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 { ErrorBoundary } from "../src/ui/components/ErrorBoundary";
+import { installCrashHandler } from "../src/services/crash-log";
 import { getAutoLockTimeout } from "../src/storage/secure-store";
 import { initLanguage } from "../src/i18n";
 import { useLanguageStore } from "../src/i18n/store";
@@ -54,6 +47,15 @@ import { startPushRegistration } from "../src/services/push-registration";
 import { handleIncomingPush } from "../src/services/push-handler";
 import { registerBackgroundSync } from "../src/services/background-sync";
 
+// react-native-keyboard-controller ships no web build — its KeyboardControllerView
+// is a native-only component that breaks the flex height chain on web and leaves
+// all scrollables with 0 bounded height. Web has no virtual keyboard anyway, so
+// we pass children straight through.
+const KeyboardProvider =
+  Platform.OS === "web"
+    ? ({ children }: { children: React.ReactNode }) => <>{children}</>
+    : NativeKeyboardProvider;
+
 // Module-level initialization. Resolves the persisted or device language,
 // then syncs the reactive store so React components see the correct value.
 const languageInitPromise = initLanguage()
@@ -65,6 +67,10 @@ const languageInitPromise = initLanguage()
     useLanguageStore.getState().hydrate();
   });
 
+// Capture uncaught JS errors before anything else runs, so a crash during the
+// module-scope startup below is still recorded.
+installCrashHandler();
+
 // Start watching wallet transactions for incoming-payment alerts. Must run
 // before any wallet state is hydrated so the subscriber sees every new tx
 // beyond the initial snapshot.
@@ -90,6 +96,12 @@ SplashScreen.preventAutoHideAsync().catch(() => {
 
 const THEME_MODE_KEY = "fairwallet_theme_mode";
 
+// Read the persisted theme at module scope, alongside `languageInitPromise`, so
+// the storage round-trip is already in flight before the first render instead of
+// being kicked off from inside it (a render-phase side effect that React 19
+// rejects with "state update on a component that hasn't mounted yet").
+const themeModePromise = getItemAsync(THEME_MODE_KEY).catch(() => null);
+
 // ---------------------------------------------------------------------------
 // Hooks
 // ---------------------------------------------------------------------------
@@ -246,19 +258,22 @@ export default function RootLayout() {
   const [languageReady, setLanguageReady] = useState(false);
   const language = useLanguageStore((s) => s.language);
 
-  const hydrated = useRef(false);
-  if (!hydrated.current) {
-    hydrated.current = true;
-    getItemAsync(THEME_MODE_KEY).then((stored) => {
+  useEffect(() => {
+    let active = true;
+    themeModePromise.then((stored) => {
+      if (!active) return;
       if (stored === "light" || stored === "dark" || stored === "system") {
         setMode(stored);
       }
       setThemeReady(true);
     });
     languageInitPromise.then(() => {
-      setLanguageReady(true);
+      if (active) setLanguageReady(true);
     });
-  }
+    return () => {
+      active = false;
+    };
+  }, []);
 
   const handleModeChange = useCallback((next: ThemeMode) => {
     setMode(next);
@@ -277,10 +292,15 @@ export default function RootLayout() {
           >
             <BottomSheetModalProvider>
               <QueryClientProvider client={queryClient}>
-                <AppContent
-                  key={language}
-                  ready={fontsLoaded && themeReady && languageReady}
-                />
+                {/* Inside the theme provider so the fallback screen is themed,
+                    and around AppContent so a throw in any screen is contained
+                    instead of unmounting the app to a black screen. */}
+                <ErrorBoundary>
+                  <AppContent
+                    key={language}
+                    ready={fontsLoaded && themeReady && languageReady}
+                  />
+                </ErrorBoundary>
               </QueryClientProvider>
             </BottomSheetModalProvider>
           </BloomThemeProvider>
@@ -297,12 +317,14 @@ function AppContent({ ready }: { ready: boolean }) {
   // Overview's network stats tick live off the WebSocket.
   useExplorerRealtime();
 
-  // Hide splash screen once fonts and theme are loaded
-  const splashHidden = useRef(false);
-  if (ready && !splashHidden.current) {
-    splashHidden.current = true;
-    SplashScreen.hideAsync();
-  }
+  // Hide the splash once fonts and theme are loaded. `ready` only ever flips
+  // false → true, so this runs exactly once.
+  useEffect(() => {
+    if (!ready) return;
+    SplashScreen.hideAsync().catch(() => {
+      // Already hidden, or no activity attached yet (dev-client reload).
+    });
+  }, [ready]);
 
   return (
     <View style={{ flex: 1 }}>

src/i18n/index.ts

@@ -59,6 +59,12 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
     "common.back": "Back",
     "common.close": "Close",
     "common.retry": "Retry",
+
+    // ---------- Crash recovery ----------
+    "crash.title": "Something went wrong",
+    "crash.subtitle":
+      "Your coins are safe — they live on the FairCoin network, not in this screen. Try again, and if it keeps happening, restart the app.",
+    "crash.retry": "Try again",
     "common.edit": "Edit",
     "common.import": "Import",
     "common.create": "Create",
@@ -513,7 +519,14 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
       "A Pocket is a separate balance inside your wallet. It's still yours (self-custody), just organized.",
     "pockets.create.nameLabel": "POCKET NAME",
     "pockets.create.namePlaceholder": "e.g. Savings",
-    "pockets.create.emojiLabel": "EMOJI",
+    "pockets.create.imageLabel": "IMAGE",
+    "pockets.create.addImage": "Add image",
+    "pockets.create.changeImage": "Change image",
+    "pockets.create.removeImage": "Remove",
+    "pockets.create.imageSourceTitle": "Choose image",
+    "pockets.create.gallery": "Gallery",
+    "pockets.create.camera": "Camera",
+    "pockets.create.permissionDenied": "Permission needed to pick an image",
     "pockets.create.colorLabel": "COLOR",
     "pockets.create.goalLabel": "GOAL (OPTIONAL)",
     "pockets.create.goalPlaceholder": "0.00",
@@ -869,6 +882,12 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
     "common.back": "Atr\u00e1s",
     "common.close": "Cerrar",
     "common.retry": "Reintentar",
+
+    // ---------- Recuperación tras un fallo ----------
+    "crash.title": "Algo ha ido mal",
+    "crash.subtitle":
+      "Tus monedas están a salvo: viven en la red FairCoin, no en esta pantalla. Inténtalo de nuevo y, si sigue ocurriendo, reinicia la app.",
+    "crash.retry": "Reintentar",
     "common.edit": "Editar",
     "common.import": "Importar",
     "common.create": "Crear",
@@ -1345,7 +1364,15 @@ const translations: Record<TranslatedLanguage, Record<string, string>> = {
       "Una pocket es un saldo aparte dentro de tu wallet. Sigue siendo tuyo (self-custody), solo organizado.",
     "pockets.create.nameLabel": "NOMBRE DEL BOLSILLO",
     "pockets.create.namePlaceholder": "p. ej. Ahorros",
-    "pockets.create.emojiLabel": "EMOJI",
+    "pockets.create.imageLabel": "IMAGEN",
+    "pockets.create.addImage": "Añadir imagen",
+    "pockets.create.changeImage": "Cambiar imagen",
+    "pockets.create.removeImage": "Quitar",
+    "pockets.create.imageSourceTitle": "Elegir imagen",
+    "pockets.create.gallery": "Galería",
+    "pockets.create.camera": "Cámara",
+    "pockets.create.permissionDenied":
+      "Se necesita permiso para elegir una imagen",
     "pockets.create.colorLabel": "COLOR",
     "pockets.create.goalLabel": "OBJETIVO (OPCIONAL)",
     "pockets.create.goalPlaceholder": "0.00",

src/services/crash-log.ts

@@ -0,0 +1,114 @@
+/**
+ * Crash capture for FAIRWallet.
+ *
+ * The app had no error boundary and no global handler: a throw during render
+ * left a black screen with no recovery path and no record of what happened.
+ * This module is the record-keeping half — `ErrorBoundary` is the recovery
+ * half, and `crash-policy.ts` holds the pure redaction/trimming rules.
+ *
+ * Two sources feed it:
+ *
+ *  1. `ErrorBoundary.componentDidCatch` — render/lifecycle throws.
+ *  2. `ErrorUtils.setGlobalHandler` — everything else on the JS thread
+ *     (uncaught promise rejections surfaced by the runtime, native-module
+ *     callbacks, timers). The previous handler is always chained so the red
+ *     box still appears in development.
+ */
+
+import { getItemAsync, setItemAsync, deleteItemAsync } from "../storage/kv-store";
+import {
+  appendCrashEntry,
+  toCrashEntry,
+  type CrashEntry,
+} from "./crash-policy";
+
+const CRASH_LOG_KEY = "fairwallet_crash_log";
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+function parseCrashLog(raw: string | null): CrashEntry[] {
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((item): item is CrashEntry => {
+      if (typeof item !== "object" || item === null) return false;
+      const candidate = item as Partial<CrashEntry>;
+      return (
+        typeof candidate.at === "number" &&
+        typeof candidate.name === "string" &&
+        typeof candidate.message === "string"
+      );
+    });
+  } catch {
+    // A corrupt log must never block the app or the next crash write.
+    return [];
+  }
+}
+
+export async function getCrashLog(): Promise<CrashEntry[]> {
+  return parseCrashLog(await getItemAsync(CRASH_LOG_KEY));
+}
+
+export async function clearCrashLog(): Promise<void> {
+  await deleteItemAsync(CRASH_LOG_KEY);
+}
+
+/**
+ * Record a crash. Never throws: it runs from an error path, so a storage
+ * failure here must not mask the original error.
+ */
+export async function recordCrash(
+  error: unknown,
+  fatal: boolean,
+): Promise<void> {
+  try {
+    const entry = toCrashEntry(error, fatal, Math.floor(Date.now() / 1000));
+    const existing = await getCrashLog();
+    await setItemAsync(
+      CRASH_LOG_KEY,
+      JSON.stringify(appendCrashEntry(existing, entry)),
+    );
+  } catch {
+    // Best effort by design.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Global handler
+// ---------------------------------------------------------------------------
+
+type ErrorHandler = (error: unknown, isFatal?: boolean) => void;
+
+interface GlobalErrorUtils {
+  setGlobalHandler(callback: ErrorHandler): void;
+  getGlobalHandler(): ErrorHandler | undefined;
+}
+
+/** React Native installs `ErrorUtils` on the global object; web has none. */
+function getErrorUtils(): GlobalErrorUtils | null {
+  const holder = globalThis as { ErrorUtils?: GlobalErrorUtils };
+  return holder.ErrorUtils ?? null;
+}
+
+let installed = false;
+
+/**
+ * Install the global JS error handler. Idempotent, and a no-op on platforms
+ * that do not expose `ErrorUtils` (web / Electron renderer).
+ */
+export function installCrashHandler(): void {
+  if (installed) return;
+  const errorUtils = getErrorUtils();
+  if (!errorUtils) return;
+  installed = true;
+
+  const previous = errorUtils.getGlobalHandler();
+  errorUtils.setGlobalHandler((error, isFatal) => {
+    void recordCrash(error, isFatal ?? true);
+    // Chain so the dev red box / default fatal handling still happens.
+    previous?.(error, isFatal);
+  });
+}