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>
@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: trueso the WebView can call a plain-http bench. NeverandroidScheme: "http": the site's CORS hook allowshttps://localhostonly.- 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 theRavenShareextension target. - Page side:
apps/web/src/native/. Everything outside that directory reaches it behindimport.meta.env.VITE_NATIVEwith 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.tsholds 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 listsraven.thecommit.company://oauthis 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
localStoragekeys, 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"plusdata_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 sendsX-Raven-Appon every request to mark it as the app's. The header is not a security check: a page athttps://localhostcould 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 ownallow_corsconfig. 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:8004on the emulator,http://127.0.0.1:8004on the simulator (ATS exception inInfo.plist); the site'sdeveloper_modeallows thehttp://localhostorigin.
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.tsholds the active site:siteUrlfor site-relative paths,siteKeyandsiteStoragefor per-site localStorage,siteFetchfor fetches with the bearer token,siteTokenfor 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 throughsrc/lib/sessionUser.ts, which replaces the Frappe cookies. boot.tsximports nothing from the app statically: the store and database modules read the site-scoped keys when they load, so they are imported only aftersetActiveSite.- The emoji data file is bundled (
dist-native/emojis.json); the site's/assetsare 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 whoseOriginis the site and calls the site back on that origin, which a WebView cannot send; the native client setsOrigin,Authorization, andX-Frappe-Site-Nameitself.VITE_SOCKET_PORTapplies to plain-http benches only. - Local bench on the emulator:
adb reverse tcp:8004 tcp:8004andtcp:9004, then add the site ashttp://127.0.0.1:8004. The socket server calls the site back on the origin the client sends:10.0.2.2is not routable from the host, and the bench's Node resolveslocalhostto::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.tsxshows "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.onLineonly 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 readisOnline(). Browser code never callssetSiteReachable, so it is unchanged there. - A view that failed to load while offline (messages, threads, notifications) shows
OfflineStatein 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 underpushToken.<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 throughRavenShell.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 throughRavenShell.getShareIntent, iOS through send-intent's share extension. A non-http url is a file whatever the MIME type says (a shared.txtarrives astext/plain). Delivered to/share-target?native=1on 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):RavenDownloadstreams the file natively with the bearer intomedia/<hash>/<file>(see the media proxy), with progress and cancel from the commonDownloadToast, then hands it to the share sheet. A file the proxy already cached opens the sheet at once. Android usesRavenShell.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
RavenShellPluginaccepts only acontent://URI owned by another app. Afile://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 inInfo.plist). iPhone plays a fullscreen video in a window of its own, whichAppDelegatelets 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-pickerinstead:pickMediawith transcoding on (JPEG and H.264 copies) orpickFiles. 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 fromAppListeners, 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>(aWKURLSchemeHandler); Androidhttps://localhost/_raven_media_/<folder>/<file>?src=<site url>(answered inshouldInterceptRequestahead of Capacitor's local server; Android's WebView drops unknown schemes for sub-resources before the client sees them).useFileSrcreturns it for private files in native; public files load straight from the site. - The handler forwards the request with the bearer, passes
Rangethrough, and attaches the bearer only whensrcis on the session's origin (setSessionat 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 layoutdownload.tsuses, 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 carriesnosniff: 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
Rangeto the stream the client returns: it skips to the start itself and never stops at the end.RangeStreamwraps 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 toenv(safe-area-inset-*). Every inset utility reads them (pt-[var(--inset-top)]and the like; thestandalonevariant 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, plusevaluateJavascriptfor 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.tsonly sets the icon style), so the page shows through as it does on 15+. Capacitor's owninsetsHandling: "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.htmlsets the theme class before first paint, the same classindex.cssreads, so the first frame is already in the app's theme. The canvas behind the page shows for a frame too;RavenShell.applyThemere-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", AndroidadjustPan), 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.
-
Bump the build number: every
CURRENT_PROJECT_VERSIONinios/App/App.xcodeproj/project.pbxproj(four entries, app and share extension), andversionCodeinandroid/app/build.gradleto 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 -
Build the web bundle with the local-only values blanked. Vite reads
.env.localand.env.native.localin 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) -
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 -
Archive, then upload. The upload prints
Upload succeededand ends withEXPORT 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 -
In App Store Connect the build appears after processing, usually 10 to 30 minutes, and reaches testers without an export compliance question:
Info.plistdeclaresITSAppUsesNonExemptEncryptionfalse, 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.jsonabsent. - iOS: verify the archived
.ipaentitlementaps-environment=production; Apple Push capability on the App IDraven.thecommit.company; theRavenShareextension 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.