# Legacy lessons & gotchas (Create/Anything export)

Hard-won knowledge mined from the **legacy** code (`apps/mobile`, `apps/web`) and
`.yarn/patches/` before the full clean. The legacy apps are being removed, but the
*reasons* behind these workarounds are worth keeping for the rebuild (`apps/api`,
`packages/shared`, and any future mobile client).

Everything below is reconstructed from real source — each lesson cites the file path
where it lived. None of this code is part of the new stack; it is reference only.

---

## 1. Android font / freeze fixes & platform workarounds

### Font loading must never block render on Android
- **`apps/mobile/src/app/(tabs)/index.tsx`** (Stopwatch screen)
  - Uses `const [fontsLoaded, fontError] = useFonts({ Inter_400Regular, Inter_600SemiBold })`.
  - Gate is `if (!fontsLoaded && !fontError) return null;` — i.e. it returns `null`
    only while fonts are *still loading*. If font loading **errors**, it renders
    anyway. The inline comments call this out explicitly: *"if fonts fail to load on
    Android we still render (no freeze)"* and *"Wait for fonts — but if font loading
    errored, render anyway (prevents Android freeze)"*.
  - When `fontError` is truthy it falls back to `fontFamily: undefined` (system font)
    instead of the named Inter family: `const regular = fontError ? undefined : 'Inter_400Regular'`.
  - **Lesson for rebuild:** never block the whole tree on `fontsLoaded` alone; always
    treat `fontError` as "render with system font". A hard wait on fonts is the classic
    way to get a permanently blank/frozen screen on Android.

### Splash screen has a hard timeout so a stuck session check can't freeze launch
- **`apps/mobile/src/app/_layout.tsx`**
  - `SplashScreen.preventAutoHideAsync()` is called, then the root is gated on
    `useAuth().initiate()` + `isReady`. To stop a hung session restore from freezing on
    the splash forever, there is a `SPLASH_TIMEOUT_MS = 10_000` fallback: after 10s it
    sets `timedOut` and hides the splash / renders regardless of `isReady`.
  - **Lesson:** any "load persisted session before first render" gate needs a timeout
    escape hatch.

### Crash reporter is silenced in dev to avoid the RN red-box/freeze loop
- **`apps/mobile/index.tsx`** (native entry)
  - In `__DEV__` it replaces `react-native/Libraries/Core/ExceptionsManager.handleException`
    with a no-op, and calls `LogBox.ignoreAllLogs()` + `LogBox.uninstall()` (also gated on
    `EXPO_PUBLIC_CREATE_ENV === 'DEVELOPMENT'`). It also installs an empty
    `AppRegistry.setWrapperComponentProvider`. This keeps the Create in-builder preview
    from getting stuck behind RN's error overlay.

### New Architecture is on
- **`apps/mobile/app.json`**: `"newArchEnabled": true`. iOS uses
  `expo-build-properties` with `useFrameworks: "static"`. Worth noting for any native
  module compatibility decisions in the rebuild.

---

## 2. expo-secure-store / SecureStore quirks (token storage)

The richest source of SecureStore wisdom is **`apps/mobile/src/utils/auth/store.ts`**
(a platform-managed `⚠ DO NOT REWRITE` file). Token is the better-auth JWT, stored under
key `` `${EXPO_PUBLIC_PROJECT_GROUP_ID}-jwt` ``.

Explicit `secureStoreOptions` are passed on **every** SecureStore call, and each option
exists for a concrete failure it prevents:

- **`keychainService: 'anything-auth'`** — pinned to a stable, hard-coded service name.
  Without it, SecureStore derives the service name from the bundle, which can **drift
  between Classic and EAS builds**, so reads silently miss writes made by a previous
  build (token "disappears" after a rebuild).
- **`keychainAccessible: AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY`** — lets the token be read
  on every cold launch after the device has been unlocked once since boot. The default
  (`WHEN_UNLOCKED`) refuses access during the first-unlock window — described as *"the
  most common TestFlight failure mode"* (user opens app from a notification before
  unlocking → auth read fails → appears signed out).
- **`requireAuthentication: false`** — keeps SecureStore on its non-biometric code path,
  so it never reads `NSFaceIDUsageDescription` or builds a biometry access-control object.
  Both can throw an `NSException` and trip **iOS 26's unhandled async-void TurboModule
  rethrow**, crashing the app.

Other token-storage lessons:
- **Keychain writes are wrapped in `.catch(() => {})`** (in `setAuth`). A failed Keychain
  write must NOT throw — throwing propagates into the unhandled-rejection / TurboModule
  rethrow path and crashes on iOS 26.x. On write failure the app stays *in-memory authed*
  for the session and re-auths via the WebView next launch.
- **Web has no Keychain** — `expo-secure-store` is aliased to a `localStorage` shim on web
  (`apps/mobile/polyfills/web/secureStore.web.ts`). It namespaces keys with
  `_create_secure_store_<key>`, warns (but does not fail) when a value exceeds a 2048-byte
  limit, `isAvailableAsync()` probes localStorage, and `canUseBiometricAuthentication()`
  returns `false`. **Lesson:** if the rebuild stores tokens on a web client, plan a
  non-Keychain fallback — localStorage is not secure storage.
- **Where the token gets read for requests:** `apps/mobile/src/__create/fetch.ts`
  (`SecureStore.getItemAsync(authKey)` → `JSON.parse` → `Bearer <auth.jwt>`), with a
  `.catch(() => null)` so a read failure just sends an unauthenticated request rather than
  crashing.

---

## 3. The global `fetch` monkey-patch (`src/__create/fetch.ts`)

Installed by **`apps/mobile/src/__create/polyfills.ts`**, which does
`global.fetch = updatedFetch` (the default export of `fetch.ts`). App code everywhere just
calls `fetch('/api/...')` and relies on this rewrite.

What `fetchToWeb` (in `apps/mobile/src/__create/fetch.ts`) actually does, in order:

1. **Bails out unchanged** if `EXPO_PUBLIC_BASE_URL` (first-party) or
   `EXPO_PUBLIC_PROXY_BASE_URL` (second-party) is unset — falls back to `expo/fetch`.
2. **Extracts the URL** from whatever form the call used — string, `Request`, or `URL`
   (via a `getURLFromArgs` helper, because the `URL` type isn't always in the fetch TS
   signature).
3. **Passes through static/file URLs untouched** via the *original* native `fetch`
   (not `expo/fetch`): `file://`, `data:`, and static assets matched by extension
   (`.wasm/.png/.jpg/.svg/.woff2/.ttf/...`). These must not get auth headers or rewriting.
4. **Leaves external (third-party) URLs alone** — headers/JWT are only ever added to
   first-party requests. "First-party" = URL starts with `/` **or** with
   `EXPO_PUBLIC_BASE_URL`.
5. **Rewrites first-party URLs onto a base.** A path starting with `/` is prefixed:
   `/_create/...` paths use the **second-party** base (`EXPO_PUBLIC_PROXY_BASE_URL`),
   everything else uses the **first-party** base (`EXPO_PUBLIC_BASE_URL`). Non-string
   inputs (`Request`/`URL`) are *not* rewritten — they fall through to `expo/fetch`.
6. **Injects Create routing headers** on first-party calls:
   `x-createxyz-project-group-id` (= `EXPO_PUBLIC_PROJECT_GROUP_ID`), plus `host`,
   `x-forwarded-host`, and `x-createxyz-host` (all = `EXPO_PUBLIC_HOST`). Only set when the
   env value is truthy.
7. **Attaches auth**: reads the JWT from SecureStore (key `<PROJECT_GROUP_ID>-jwt`,
   JSON-parsed), and if present sets `Authorization: Bearer <auth.jwt>`. Read errors are
   swallowed (`→ null`), so the request still goes out unauthenticated.
8. Dispatches the rewritten request through **`expo/fetch`** (Expo's fetch, for
   streaming/RN compatibility), not the global one (which it has replaced).

**Lessons for rebuild:** the new mobile client should centralise (a) base-URL rewriting
and (b) auth-header attachment in one place. The legacy approach monkey-patches the global
`fetch`, which is invisible/magic to app code — a typed API client (the `packages/shared`
zod contracts make this easy) is a cleaner replacement. Note the alternative `authFetch`
in `apps/mobile/src/utils/auth/getSession.ts` does the Bearer-header part explicitly and
is the documented "use this instead of bare fetch" helper.

---

## 4. Web sandbox / iframe plumbing

The mobile app's **web** target runs inside the Create builder as an `<iframe>` and talks
to the parent window over `postMessage`. This is purely a Create-preview affordance; the
rebuild does not need any of it unless it re-targets the Create platform.

- **Entry split by extension** (`apps/mobile/metro.config.js` resolves these):
  - Native: `index.tsx` → `entrypoint.ts` → `App.tsx` (`App.tsx` just wraps
    `expo-router`'s qualified-entry `App` with a `ScreenViewTracker`).
  - Web: `index.web.tsx` → `App.web.tsx`.
- **`apps/mobile/App.web.tsx`** — the iframe/sandbox contract:
  - **Healthcheck handshake** (`useHandshakeParent`): replies to
    `sandbox:mobile:healthcheck` with `sandbox:mobile:healthcheck:response {healthy:true}`,
    and also posts the healthy response immediately on mount in case the healthcheck arrived
    before the listener was attached.
  - **Navigation sync** (both directions): listens for `sandbox:navigation {pathname}` from
    the parent and `router.push`es it; posts `sandbox:mobile:navigation {pathname}` back on
    every `usePathname()` change; posts `sandbox:mobile:ready` once on mount.
  - **Error forwarding** (`GlobalErrorReporter` + `postErrorToParent`): global `error` and
    `unhandledrejection` listeners post `sandbox:error:detected {message,name,stack}` to the
    parent — but **filter out runtime/network errors** (a big `RUNTIME_ERROR_PATTERNS`
    regex list: `fetch failed`, `ECONNREFUSED`, `502/503/504`, `timeout`, etc.) so only
    *code* errors (TypeError/ReferenceError/SyntaxError/`MODULE_RESOLVE_FAILED`) are
    surfaced to the builder. `event.preventDefault()` is called to suppress the default
    overlay.
  - **Faked safe-area insets on web**: `SafeAreaProvider initialMetrics` hard-codes
    `{ top: 64, bottom: 34, ... }` and frame size from `window.innerWidth/Height`, so the
    web preview mimics a phone notch.
- **`apps/mobile/src/__create/ErrorBoundary.tsx`** — a React error boundary that also posts
  `sandbox:error:detected` on `componentDidCatch` and `sandbox:error:resolved` when the user
  taps "Try again". All `postMessage` calls are guarded by `window.parent !== window`.
- **`apps/mobile/index.web.tsx`** — screenshot + Skia + font plumbing:
  - Responds to `sandbox:web:screenshot:request` by rasterising `#root` with
    `html-to-image` `toPng` and posting back `sandbox:web:screenshot:response {dataUrl}`
    (or `...:error`).
  - Before screenshotting it **inlines Google Fonts** (`inlineGoogleFonts`: fetches each
    `fonts.googleapis.com` stylesheet, absolutises `url(...)` refs, injects a `<style>`,
    then awaits `document.fonts.ready`) and waits for all `<img>`s (`crossOrigin =
    'anonymous'`) — otherwise the screenshot renders with missing fonts/images.
  - Loads Skia for web (`LoadSkiaWeb({ locateFile: f => \`/${f}\` })`) and renders the root
    in `.then`/`.catch` so the app still mounts if Skia fails to load.

**Lesson:** all of this is Create-builder coupling. For the rebuild it is dead weight unless
you keep publishing to `*.created.app`. The one genuinely reusable idea is the
*code-vs-runtime* error classification in `App.web.tsx` (don't spam your error channel with
transient network failures).

---

## 5. What each `.yarn/patches/*` file patches, and why

> All are pinned by `patch:` deps + root `resolutions`/`overrides`. Bumping any of these
> packages discards the patch (per project `CLAUDE.md`). One line each:

- **`react-native+0.81.4.patch`** — re-adds a working `Slider` getter to RN's `index.js`
  (forwarding to `@react-native-community/slider`) and removes RN core's "Slider has been
  removed" invariant that otherwise throws on access.
- **`@expo+cli+54.0.1.patch`** — in the Expo Go manifest middleware, generates the manifest
  `id` with `crypto.randomUUID({ disableEntropyCache: true })` to avoid duplicate/cached
  UUIDs across rapid manifest requests.
- **`@expo+metro-runtime+6.1.2.patch`** — short-circuits the dev **error overlay**:
  `LogBoxInspectorContainer` and `ErrorToast` both `return null` immediately, so RN's
  red-box error UI never shows inside the Create preview.
- **`@react-native-community+netinfo+11.4.1.patch`** — makes `nativeInterface.ts` tolerate a
  missing native module: removes the hard `throw` when `RNCNetInfo` is null and returns `{}`
  instead, so NetInfo doesn't crash environments (web/preview) where the native module isn't
  present.
- **`expo-router+6.0.11.patch`** — large patch. (a) Restyles the web `native-tabs` CSS into
  a floating, blurred bottom tab bar + adds an Apple-Settings-style "More" overflow screen
  when there are >5 tabs (incl. extracting `webIcon*`/`webLabel*` options for web rendering).
  (b) Adds an `isAnythingApp` branch (iOS + not Expo Go) that forces `getInitialURL` to `/`
  and skips the `Linking` 'url' subscription, so the Anything native shell always boots at
  root instead of via deep link.
- **`expo-store-review+9.0.8.patch`** — adds `prePromptReview` / `resetReviewState` /
  `hasUserRated` to the JS API and a native iOS `StoreReviewModule` (a custom "Thanks for
  using Anything!" pre-prompt alert that gates the real `AppStore.requestReview`, tracking
  `anything_has_rated` in `UserDefaults`); also guards `ExpoStoreReview.native.js` so it only
  `requireNativeModule`s when the module is actually present (else `{}`). NB: the patch file
  also accidentally committed `.orig`/`.rej` artifacts.
- **`react-native-purchases+9.6.1.patch`** — patches `isExpoGo()` to return `false` when
  `!__DEV__`, and to return `true` when `globalThis.expo.modules.AnythingLauncherModule`
  exists — so RevenueCat detects the Anything launcher/Expo-Go correctly instead of trying to
  hit native StoreKit where it can't.
- **`react-native-purchases-ui+9.6.1.patch`** — same `isExpoGo()` fix as above, applied
  across the package's `commonjs`/`module`/`src` `environment` files (and adds the
  `AnythingLauncherModule` type to the `globalThis.expo.modules` declaration).
- **`react-native-web-refresh-control+1.1.2.patch`** — replaces the deprecated/removed
  `findNodeHandle(containerRef.current)` with `containerRef.current?.firstChild` to read
  `scrollTop` in `RefreshControl.web.js`, fixing pull-to-refresh detection on web.
- **`sonner-native+0.21.0.patch`** — on web, moves the toast `Positioner`'s
  `pointerEvents: 'box-none'` from a `View` prop into the `style` array (RNW expects
  `pointerEvents` in style), so toasts don't block clicks behind them on web.

---

## 6. Other gotchas worth remembering

- **Web support is Metro module aliasing, not separate code** —
  `apps/mobile/metro.config.js` swaps ~25 native modules for web shims in `polyfills/web/`
  via `resolver.resolveRequest` keyed on `platform === 'web'` (e.g. `expo-secure-store`,
  `react-native-webview`, `react-native-safe-area-context`, `expo-haptics`,
  `react-native-maps`, several `react-native-web/dist/exports/*`). **Adding a native dep that
  is imported on web requires adding a web alias here or the web build breaks.**
- **Dev-only native aliases stop Expo Go from black-screening** — `DEV_ONLY_NATIVE_ALIASES`
  swaps `react-native-purchases` for a stub *outside production*. The inline comment explains
  why: the real module's browser-mode shims pull in DOM-only code that throws on Hermes;
  expo-router then silently swallows the load error and warns *"Route is missing the required
  default export"*, leaving the app on a black/splash screen. EAS production builds keep the
  real module. **Lesson:** a native module that throws at import time on Hermes manifests as a
  confusing "missing default export" route error, not as the real error.
- **`anything-menu` is compiled out in production** — `metro.config.js` aliases
  `./src/__create/anything-menu` to `polyfills/shared/empty-component.tsx` when
  `EXPO_PUBLIC_CREATE_ENV === 'PRODUCTION'`. The in-app dev menu (`anything-menu.tsx`) talks
  to a native `AnythingLauncherModule` and should never ship to end users.
- **Expo Google Fonts wildcard alias** — any `@expo-google-fonts/*` import (except
  `@expo-google-fonts/dev`) is redirected to `@expo-google-fonts/dev` by the resolver, so the
  template can reference arbitrary font families without bundling each one.
- **Custom Metro resolver swallows unresolved-module errors in dev** —
  `apps/mobile/__create/handle-resolve-request-error.js` catches resolution failures and, in
  dev only (not Android, not production), writes a deterministic "throwing" virtual module so
  the error surfaces in-app at runtime instead of killing the bundler. It only rewrites the
  virtual file when content changed, *to avoid a Metro rebuild loop from mtime bumps*. On
  Android / production it rethrows.
- **Metro reporter forwards bundling errors to a remote logging endpoint** — both
  `metro.config.js` (`reportErrorToRemote` on `error`/`bundling_error`/`cache_read_error`/
  `hmr_client_error`/`transformer_load_failed`) and
  `apps/mobile/__create/report-error-to-remote.js` post to `EXPO_PUBLIC_LOGS_ENDPOINT` with a
  `Bearer EXPO_PUBLIC_CREATE_TEMP_API_KEY`. This is Create telemetry; the rebuild should not
  carry the temp API key.
- **Metro cache is wiped on production builds** — `config.transformer.getTransformOptions`
  deletes the `caches/` dir when `options.dev === false`. The repo also ships a populated
  `apps/mobile/caches/.metro-cache/` (build artifacts — safe to drop in the clean).
- **Analytics/Sentry/TestFlight logging are all gated the same way** — `isActive()` =
  `!__DEV__ && EXPO_PUBLIC_CREATE_ENV !== 'DEVELOPMENT'` (see
  `apps/mobile/src/__create/analytics.ts`). The anonymous per-install visitor id lives in
  **AsyncStorage**, not the Keychain — explicitly *"not a secret"*. Analytics calls are fully
  try/caught so they can never crash or block the host app.
- **better-auth dual mode** — web uses cookie sessions; mobile uses
  `Authorization: Bearer <jwt>` validated by better-auth's `bearer()` plugin
  (`apps/mobile/src/utils/auth/getSession.ts`, `apps/web/src/lib/auth.ts`). The JWT comes
  from `/api/auth/token` (native WebView) or an `AUTH_SUCCESS` postMessage from
  `/api/auth/expo-web-success` (web iframe) — see `apps/mobile/src/utils/auth/AuthWebView.tsx`.
  **The new `apps/api` already uses better-auth, so this dual-mode pattern is directly
  relevant.**
- **Origin check normalises with `new URL(raw).origin`** — `AuthWebView.tsx` learned (the
  hard way, per its comment) that a stray trailing slash in `EXPO_PUBLIC_PROXY_BASE_URL`
  silently dropped *every* postMessage; it now compares normalised origins and `console.warn`s
  on a drop instead of swallowing it. Good defensive pattern for any postMessage receiver.
- **RevenueCat offerings load with retries** — `apps/mobile/src/utils/iap/useInAppPurchase.ts`
  retries `getOfferings()` 3× with a 1.5s delay because a freshly-configured RevenueCat client
  often returns no `current` offering on the first call.
- **The `/api/logs` route was missing from the legacy `apps/web` export** — the mobile History
  tab (`GET /api/logs`) and Stop & Save (`POST /api/logs`) 404'd against the local backend
  (only `/api/export` existed). Documented in the repo `CLAUDE.md`; the rebuild's `apps/api`
  owns this contract now.