# @raven/native Capacitor project for the Raven iOS and Android apps. The web content is a native-mode build of `apps/web` (`VITE_NATIVE=1`, output `apps/web/dist-native`), served from the app's own origin (`https://localhost` on Android, `capacitor://localhost` on iOS) and working offline. The app talks to the chosen site with OAuth bearers; the site's CORS hook allows those two origins. Design: `docs/superpowers/specs/2026-09-09-native-bundled-design.md`. ## Build & run ```bash yarn native:build # apps/web native build → apps/web/dist-native yarn native:sync # build + cap sync yarn native:ios # cap open → Xcode yarn native:android # cap open → Android Studio cd apps/native && npx cap run android --target cd apps/native/ios/App && xcodebuild -project App.xcodeproj -scheme App -configuration Debug \ -destination id= -allowProvisioningUpdates build xcrun devicectl device install app --device /Build/Products/Debug-iphoneos/App.app xcrun devicectl device process launch --device raven.thecommit.company ``` Gates for the page: `cd apps/web && yarn tsc -b && yarn vitest run src/native`. ## Local files (gitignored) - `android/app/google-services.json`, `ios/App/App/GoogleService-Info.plist`: Firebase. - `android/local.properties`: SDK path. - `capacitor.config.local.json`: dev overrides, e.g. `android.allowMixedContent: true` so the WebView can call a plain-http bench. Never `androidScheme: "http"`: the site's CORS hook allows `https://localhost` only. - Debug builds allow cleartext for the native HTTP stack too (`android/app/src/debug/AndroidManifest.xml`), so downloads and the media proxy reach a plain-http bench. Release builds do not. ## Native sources - Android: `MainActivity` (plugin registration, the media interceptor, inset publishing, theme canvas, launch-intent replay guard), `RavenApplication` (night mode, notification channel), `RavenShellPlugin` (foreground notifications, share-out chooser, share intake), `ShareOut`, `ConversationNotification`, `RavenSocketPlugin`, `RavenDownloadPlugin`, `RavenMediaPlugin` + `RavenMediaHandler`. - iOS: `RavenBridgeViewController` (plugin registration, the media scheme, canvas), `SceneDelegate` (theme, share extension handoff), `AppDelegate` (APNs token), `RavenShellPlugin`, `RavenSocketPlugin`, `RavenDownloadPlugin`, `RavenMediaPlugin` + `RavenMediaHandler`, and the `RavenShare` extension target. - Page side: `apps/web/src/native/`. Everything outside that directory reaches it behind `import.meta.env.VITE_NATIVE` with a dynamic import, so browser builds carry none of it. Plugin contracts live next to their callers (`shell.ts`, `download.ts`, `media.ts`, `nativeSocket.ts`); `platform.ts` holds the shared helpers (`nativePlugin`, `withPrefs`, `listenNative`). ## Sites and sign-in - A site is added by origin; the app calls `raven.api.raven_mobile.get_client_id` (guest), the endpoint the React Native app used. A site below Raven 3.1.0 (`MIN_SITE_VERSION`, `native/version.ts`) is refused as too old. A site without an OAuth client that lists `raven.thecommit.company://oauth` is refused with a message for its admin. - Sign-in is OAuth PKCE in the system browser (`@capacitor/browser`); tokens live in the keychain per site (`raven.tokens.`) and are refreshed at 80% of their lifetime and once more on a 401. A refresh the site refuses (`invalid_grant`, revoked client) ends the session: the tokens are dropped and the picker signs the same site in again on its own (`pendingRelogin`). A refresh that cannot reach the site keeps the stale tokens and retries every 30 s. - Removing a site in the picker forgets everything local first and at once: its tokens, its record, its scoped `localStorage` keys, its database and the media cache (shared, so all of it goes; `wipeSiteData`). The push unsubscribe and the token revokes then run unawaited, so a site that has stopped answering never holds the picker. The bearer goes only to the active site's origin (`siteFetch`), never to an absolute URL elsewhere. - Nothing is backed up or transferred to another phone (`allowBackup="false"` plus `data_extraction_rules.xml`): the stored tokens are encrypted with a device-bound key, and a copy on another device could not be read. - API calls use the sdk with a bearer token; the site allows the app's origins through `raven.api.native.set_cors` (`before_request`), so sites need no CORS configuration. The app sends `X-Raven-App` on every request to mark it as the app's. The header is not a security check: a page at `https://localhost` could add it too. The origin allowlist is the real boundary, and those origins only exist on the user's own device. For the app's origins the hook's answer overrides a site's own `allow_cors` config. For every other origin the site config applies as before. - The OAuth client (Raven Settings → OAuth Client) is created on install and by the 3.1 migration. To repair one by hand: `bench --site execute raven.api.raven_mobile.create_oauth_client`. - Local bench: add `http://10.0.2.2:8004` on the emulator, `http://127.0.0.1:8004` on the simulator (ATS exception in `Info.plist`); the site's `developer_mode` allows the `http://localhost` origin. ## Version policy A site must run Raven 3.1.0 or newer (`MIN_SITE_VERSION`): the app's server side, `raven.api.native.boot` and `set_cors`, ships from there. The site's `raven_version` is compared with the version the bundle was built from (`__RAVEN_VERSION__`, read from `raven/__init__.py` at build): a different patch is silent; a different minor or major opens with a warning toast naming both versions. `min_app_version` from the site only drives an "update the app" toast, never a block. Both notices are queued in Preferences by the picker (`pendingNotice`) and shown once the app is up. A site older than 3.1.0, or without the mobile API at all (no `get_client_id`), is refused with "runs an older Raven". The site in turn names `min_app_version` (3.1.0, `raven_mobile.py`), which only drives the "update the app" toast. Opening older sites in a bridge-less native WebView screen is planned (spec, layer 7). A site row shows a favicon the site set for itself (`use_website_favicon` in Raven Settings, a public file), and nothing otherwise: Raven's own artwork is the app's logo. ## The app on a site - `src/lib/site.ts` holds the active site: `siteUrl` for site-relative paths, `siteKey` and `siteStorage` for per-site localStorage, `siteFetch` for fetches with the bearer token, `siteToken` for plugins. In the browser all of them are the identity. - Boot comes from `raven.api.native.boot` (`src/native/appBoot.ts`) and the last good copy is kept per site for offline starts. The current user comes from boot through `src/lib/sessionUser.ts`, which replaces the Frappe cookies. - `boot.tsx` imports nothing from the app statically: the store and database modules read the site-scoped keys when they load, so they are imported only after `setActiveSite`. - The emoji data file is bundled (`dist-native/emojis.json`); the site's `/assets` are served without CORS headers. Fonts are bundled too (vite aliases in native mode). - Switch site and log out live on the Profile page. - Realtime runs through a native socket.io client (`RavenSocketPlugin`, Java and Swift) bridged into the sdk's context (`src/native/nativeSocket.ts`). Frappe's realtime server only accepts a socket whose `Origin` is the site and calls the site back on that origin, which a WebView cannot send; the native client sets `Origin`, `Authorization`, and `X-Frappe-Site-Name` itself. `VITE_SOCKET_PORT` applies to plain-http benches only. - Local bench on the emulator: `adb reverse tcp:8004 tcp:8004` and `tcp:9004`, then add the site as `http://127.0.0.1:8004`. The socket server calls the site back on the origin the client sends: `10.0.2.2` is not routable from the host, and the bench's Node resolves `localhost` to `::1`, where nothing listens. ## Error screens `loadBoot` reports why boot failed and `boot.tsx` acts on it (`BootErrorScreen.tsx`): - `connecting`: not a failure. Boot waits on the network before anything renders: the token refresh, the boot request and the status fallback each give up after 8 s. When boot runs past 6 s, `boot.tsx` shows "Connecting to " with Switch site, so a site that does not answer never leaves a screen with nothing to tap. The real result replaces it. - `offline`: no answer, no cached boot, and the device has no network. "You're offline", Retry, Switch site; reloads by itself when the network returns. - `unreachable`: no answer, no cached boot, device online. " isn't responding", it may be down or its address may have changed. Retry, Switch site. - `maintenance` (503): " is under maintenance", Retry, Switch site. A site that allows reads during maintenance answers normally and never reaches this screen. - `unavailable` (any other failure): "Couldn't load Raven", Retry, Switch site. - `unauthorized` (401, 403): the session is dead; the app returns to the picker, which opens the browser login for the same site without a tap. An HTTP answer is never papered over by the cached boot; only a request that got no answer falls back to it. A site in maintenance answers its 503 before its CORS hook runs, so the page's fetch throws on it; `loadBoot` then reads the status once more through `CapacitorHttp`, which has no CORS, to tell maintenance and a dead session from a site that is down. ## Offline - Offline signal (`src/stores/connectionState.ts`, `src/native/reachability.ts`): `navigator.onLine` only covers a device with no network. Native adds the site: while the socket is down (a disconnect, or a first connect that takes more than 10 s) a ping to the site decides, every 15 s, and a failed ping marks the site unreachable after a 5 s debounce. Realtime being down alone never reads as offline. Coming back bumps the freshness counter, so views that failed while offline refetch themselves. The banner, the pagination guard, the static edge rows and the date pill read `isOnline()`. Browser code never calls `setSiteReachable`, so it is unchanged there. - A view that failed to load while offline (messages, threads, notifications) shows `OfflineState` in native, a calm "You're offline" with no retry, and reloads on reconnect. ## Native integrations - Push (`push.ts`): one FCM device token, subscribed per site with that site's bearer (`environment: "Mobile"`), stored site-scoped and mirrored in Preferences under `pushToken.` so removing a site in the picker can unsubscribe it. Foreground pushes are handed to the page (`presentationOptions: []`); ones from another saved site are re-posted through `RavenShell.showNotification`. A tap on the open site's push navigates; on another saved site it sets the default site, stores the path (`pendingPath`), and reloads. The read sweep reads tray entries through the plugin, keyed `:`. - Share-in (`shareIn.ts`, `shareIntent.ts`): Android through `RavenShell.getShareIntent`, iOS through send-intent's share extension. A non-http url is a file whatever the MIME type says (a shared `.txt` arrives as `text/plain`). Delivered to `/share-target?native=1` on the active site; a share that opens the picker waits until a site opens. Files are read through the WebView's file route (`Capacitor.convertFileSrc`) as Blobs and queued for the composer. - Share-out (`share.ts`, `download.ts`): `RavenDownload` streams the file natively with the bearer into `media//` (see the media proxy), with progress and cancel from the common `DownloadToast`, then hands it to the share sheet. A file the proxy already cached opens the sheet at once. Android uses `RavenShell.share` (a plain chooser, Raven excluded): the Share plugin waits for the chooser's result, and a pick of Raven itself relaunches the singleTask activity over the chooser, leaving the plugin "in progress" until a restart. Native labels the actions "Share". - Share in, Android: the sending app picks the URI, so `RavenShellPlugin` accepts only a `content://` URI owned by another app. A `file://` URI or the app's own provider would make Raven read its private files on the sender's behalf. - Orientation: phones are portrait only (manifest `screenOrientation`, iPhone list in `Info.plist`). iPhone plays a fullscreen video in a window of its own, which `AppDelegate` lets rotate. Android's WebView cannot turn the screen by itself, so a fullscreen video stays portrait there. Tablets are not locked: Apple requires every orientation on iPad, and Android 16 ignores the lock on screens 600dp and wider. - Attach on iOS (`pick.ts`): a WKWebView file input always shows iOS's camera / library / files chooser, anchored to a composer sheet that has already closed. The Photos and Files tiles call `@capawesome/capacitor-file-picker` instead: `pickMedia` with transcoding on (JPEG and H.264 copies) or `pickFiles`. The picks are read like shared files. Android and the web keep their inputs. - Links (`links.ts`): the site's own `/raven/…` links route in the app; any other URL keeps Capacitor's default and opens in the system browser. - Android back (`back.ts`): an open sheet or viewer closes first; a root page (footer tab or workspace home) sends the app to the background, as Android apps do; deeper pages go one step back. - `NativeBridge.tsx`, mounted from `AppListeners`, registers the listeners that need the router; the flows themselves live in their modules. - Haptics, badge, drawer, theme: the existing hooks branch to the plugins. iOS share-in is the `RavenShare` extension target (`ios/App/RavenShare/`): it copies each shared item into the app group `group.raven.thecommit.company` and opens `raven://?title&description&type&url`, which `SceneDelegate.receiveShare` turns into send-intent's `sendIntentReceived` event. Both targets carry the app group entitlement; automatic signing registers it on the App IDs on first build. ## Media proxy An `` or `