Nikhil Kothari bf88a36fde chore: README rewrite, iPad fixes and Play Store release build
README: rewritten to the brand voice, with the new logo, Pilot as the
recommended install and a Frappe Cloud button. The old PNG logo is gone.

iPad: the primary rail now pads the status bar inset itself, since it
sits beside <main> and never got it. The bridge view controller overrides
supportedInterfaceOrientations because Capacitor builds its mask from the
iPhone list in Info.plist only, which pinned the iPad to portrait.

Android release: a signing config read from a gitignored
keystore.properties, and scripts/playstore.sh, which builds the signed
bundle the same way testflight.sh archives for iOS. Both are wired to
yarn native:playstore.

Build number 314 for both platforms.

Store screenshot tooling and the demo site seed are ignored; they are
local tooling, not part of the app.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-19 09:46:53 +05:30
..

@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

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 <serial or avd>
cd apps/native/ios/App && xcodebuild -project App.xcodeproj -scheme App -configuration Debug \
  -destination id=<udid> -allowProvisioningUpdates build
xcrun devicectl device install app --device <udid> <DerivedData>/Build/Products/Debug-iphoneos/App.app
xcrun devicectl device process launch --device <udid> 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.<origin>) 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 <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.<origin> 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 <hostname>:<channel_id>.
  • 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/<hash>/<file> (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 <img> or <video> cannot send the bearer, and on hosted sites even a fetch of /private/files/ fails: Frappe Cloud's nginx answers the file routes with a fixed access-control-allow-origin: <site origin>, so the app's origin is refused. Private files therefore load through RavenMedia (src/native/mediaUrl.ts, media.ts):

  • URL shape: iOS raven-media://<folder>/<file>?src=<site url> (a WKURLSchemeHandler); Android https://localhost/_raven_media_/<folder>/<file>?src=<site url> (answered in shouldInterceptRequest ahead of Capacitor's local server; Android's WebView drops unknown schemes for sub-resources before the client sees them). useFileSrc returns it for private files in native; public files load straight from the site.
  • The handler forwards the request with the bearer, passes Range through, and attaches the bearer only when src is on the session's origin (setSession at boot and after every refresh). Anything else is answered 403.
  • <folder> is a hash of the file URL and <file> its own name, the same layout download.ts uses, so a file fetched for viewing serves share-out and the other way round. A full (non-Range) 200 is teed into a part file of its own and renamed when complete; a complete file answers later requests, Range included, from disk. Range answers are streamed only, so a video the WebView fetched by ranges is not cached.
  • Media elements only. A top-level load of a proxy URL is answered 403, HTML types are served as text/plain, and every answer carries nosniff: a site file opened as a page would run inside the app's WebView with the native bridge.
  • Android's WebView applies the request's Range to the stream the client returns: it skips to the start itself and never stops at the end. RangeStream wraps both answers: a cached file is returned whole with an end bound, and a 206 body from the site reads as the whole resource. iOS answers ranges itself.
  • Eviction (watchMediaCache, at boot and on every return to the foreground, at most once an hour): while the folder exceeds 200 MB, the plugin deletes cache folders oldest first.
  • Logout wipes media/.

Insets and keyboard

  • The page pads itself with four tokens defined in index.css: --inset-top, -bottom, -left, -right, defaulting to env(safe-area-inset-*). Every inset utility reads them (pt-[var(--inset-top)] and the like; the standalone variant matches installed PWAs and :root.native).
  • Android publishes the system-bar insets into those tokens from MainActivity: a document-start script (WebViewCompat.addDocumentStartJavaScript) so a reload sees them before first paint, plus evaluateJavascript for the live page, re-run on every inset change. The WebView is not padded natively; the status bar is transparent on every Android version (statusBar.ts only sets the icon style), so the page shows through as it does on 15+. Capacitor's own insetsHandling: "css" is not usable: its listener re-pads the page for the keyboard.
  • iOS defines nothing natively; env() fills the tokens.
  • The offline banner takes the top inset while it shows, so its colour reaches the status bar on both platforms.
  • Reloads (opening a site, switching, relogin, a push for another site) show no other colour on the way: native.html sets the theme class before first paint, the same class index.css reads, so the first frame is already in the app's theme. The canvas behind the page shows for a frame too; RavenShell.applyTheme re-reads the mirrored theme whenever it changes, so that canvas never lags behind until the next launch or resume. The Android WebView stays transparent over the theme canvas, and the theme declares transparent bars for every window.
  • Keyboard: never resizes the page on either platform (iOS Keyboard.resize: "none", Android adjustPan), matching the installed iOS PWA; the composer lifts by --keyboard-height (keyboard.ts) and the OS pans a covered field into view.

Release to TestFlight

yarn native:testflight from the repo root runs every step below: it bumps the build number, builds, archives and uploads. yarn native:testflight --no-upload stops after the archive and leaves the build number alone. The steps, for doing it by hand or in Xcode, run from apps/native, on a Mac signed in to Xcode with the team's Apple account. The upload uses the account's cloud-managed distribution certificate, so no certificate is needed locally.

  1. Bump the build number: every CURRENT_PROJECT_VERSION in ios/App/App.xcodeproj/project.pbxproj (four entries, app and share extension), and versionCode in android/app/build.gradle to match. App Store Connect refuses a build number it has seen.

    sed -i '' 's/CURRENT_PROJECT_VERSION = 301;/CURRENT_PROJECT_VERSION = 302;/' ios/App/App.xcodeproj/project.pbxproj
    
  2. Build the web bundle with the local-only values blanked. Vite reads .env.local and .env.native.local in every mode, so a plain build ships the local socket port and site name; real environment variables take precedence over those files.

    (cd ../web && VITE_SOCKET_PORT= VITE_SITE_NAME= yarn build:native)
    
  3. Sync into the iOS project without the dev override, then put it back.

    mv capacitor.config.local.json /tmp/ 2>/dev/null; npx cap sync ios; mv /tmp/capacitor.config.local.json . 2>/dev/null
    
  4. Archive, then upload. The upload prints Upload succeeded and ends with EXPORT SUCCEEDED.

    xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release \
      -destination 'generic/platform=iOS' -archivePath release/Raven.xcarchive -allowProvisioningUpdates archive
    xcodebuild -exportArchive -archivePath release/Raven.xcarchive -exportPath release/upload \
      -exportOptionsPlist ios/ExportOptions.plist -allowProvisioningUpdates
    
  5. In App Store Connect the build appears after processing, usually 10 to 30 minutes, and reaches testers without an export compliance question: Info.plist declares ITSAppUsesNonExemptEncryption false, since the app uses standard HTTPS only.

Before first store submission

The store versions must be higher than the React Native listing (1.1.4); the project carries 3.1.0 (MARKETING_VERSION in project.pbxproj, versionName in android/app/build.gradle); the build number lives beside each.

  • App icons + splash art: done. The splash is black in both themes, with light status bar icons over it. Android uses vector drawables built from raven/public/raven_logo.svg; iOS carries the 1024 icon and one splash image from the same SVG.
  • Firebase config files present on the release machine (google-services.json, GoogleService-Info.plist); capacitor.config.local.json absent.
  • iOS: verify the archived .ipa entitlement aps-environment=production; Apple Push capability on the App ID raven.thecommit.company; the RavenShare extension in the archive with the app group on both targets.
  • Android: release keystore generated and referenced; no debug manifest overlay in the release APK (cleartext stays off).
  • Manual matrix on real devices, both platforms: sign in; push tap cold and warm; share in (photo, video, .txt, link) and out (image, large file with cancel); private image and video on a hosted site; offline banner reaching the status bar; keyboard over the composer; a revoked token re-opening the login; site down and site in maintenance.