340 lines
21 KiB
Markdown
340 lines
21 KiB
Markdown
# @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 <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 <host>" 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. "<host> isn't responding", it may be down
|
|
or its address may have changed. Retry, Switch site.
|
|
- `maintenance` (503): "<host> 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
(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.
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
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.
|