Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(ios): say why routing payment surfaces to Safari needs a session handoff

nirholas46e36d49cac9
diff --git a/docs/ios-app.md b/docs/ios-app.md
index d8bd2f085..c27c22b84 100644
--- a/docs/ios-app.md
+++ b/docs/ios-app.md
@@ -25,7 +25,10 @@ organization account, app icons, and push. See "What is missing" below.
| Offline | A designed screen that polls `/api/healthz` and recovers on its own, instead of the WebKit error page | `ios/shell/offline.html`, `server.errorPath` |
| Camera, mic, photos, location, motion | Real iOS permission prompts with real usage strings, which is what `/create/selfie`, `/ar/studio` and `/irl` need on iOS | `ios/native/App/App/Info.plist` |
| Launch | The launch screen holds until the first real frame, so a three.js scene never opens onto a black void | `ios/src/native-bridge.js`, `SplashScreen` config |
-| Haptics | A tick on primary actions | `ios/src/native-bridge.js` (`[data-haptic]`) |
+| Haptics | A tick on primary and destructive actions, quiet on a disabled or busy one | `ios/src/native-bridge.js` |
+| Back navigation | Edge-swipe back and forward, which `WKWebView` ships with off and iOS has no button for | `ios/native/App/App/MainViewController.swift` |
+| Status bar | The sticky header clears the notch and the clock. The site's own compensation is behind `@media (display-mode: standalone)`, which a WebView loading a remote URL never matches | `ios/src/native-bridge.js` (injected stylesheet) |
+| Forms | Fields never fall below 16px, so focusing one cannot zoom the page and strand it zoomed | `ios/src/native-bridge.js` |
## How the web half reaches the app
@@ -74,10 +77,18 @@ and `/widget*` entries (they exist to render inside someone else's page).
- **Push notifications.** The entitlement, background mode and plugin are in
place; the APNs key, device-token endpoint and send path are not, and are
absent rather than stubbed.
-- **App icons and launch screen art**, currently Capacitor's template.
+- **Listing screenshots**, which have to be captured on a real device. The icon
+ and launch images are generated from the brand mark (`npm run ios:icons`) and
+ a guard keeps them from drifting (`npm run check:ios-icons`).
- **The App Review posture on crypto surfaces**, which is a product decision
- and not a code one. It is written up in
+ and not a code one, and which costs a session handoff rather than a config
+ flag: `SFSafariViewController` does not share the app WebView's cookie jar, so
+ a surface routed to Safari arrives signed out. Written up in
[`ios/docs/REVIEW-RISK.md`](../ios/docs/REVIEW-RISK.md).
+- **Service workers**, which `WKWebView` runs only for app-bound domains. The
+ app declares none, so the site's offline caching and share-target worker do
+ not run inside it; the native offline screen covers the case that matters.
+ Same doc has the trade.
## Related
diff --git a/ios/README.md b/ios/README.md
index c90c8a8f2..5f96ad89a 100644
--- a/ios/README.md
+++ b/ios/README.md
@@ -19,11 +19,13 @@ ios/
├── capacitor.config.ts # appId, server URL, iOS behaviour, plugin config
├── shell/ # local bundle: bootstrap + the designed offline screen
├── src/native-bridge.js # web-side half; ships with the SITE, not the .ipa
+├── scripts/make-icons.mjs # derives the icon + launch images from the brand mark
├── native/App/ # the generated Xcode project (committed)
│ ├── App.xcodeproj
-│ ├── App/Info.plist # usage strings, URL scheme, orientations
-│ ├── App/App.entitlements # associated domains + APNs
-│ └── CapApp-SPM/ # Swift Package Manager plugin graph
+│ ├── App/MainViewController.swift # swipe-back, dark chrome, edge-to-edge insets
+│ ├── App/Info.plist # usage strings, URL scheme, orientations
+│ ├── App/App.entitlements # associated domains + APNs
+│ └── CapApp-SPM/ # Swift Package Manager plugin graph
└── docs/ # SUBMISSION.md, REVIEW-RISK.md, ASSETS.md
```
@@ -65,7 +67,31 @@ What it installs, and the breakage each one fixes:
| `appUrlOpen` routing (universal links + `threews://`) | A wallet or OAuth redirect reopens the app on whatever page it was last showing |
| Splash hide on first paint | `launchAutoHide` fires on WebView load, minutes before a three.js scene renders |
| `html.ios-app` + safe-area custom properties | Install prompts render inside the installed app; bottom controls sit under the home indicator |
-| Haptics on `[data-haptic]` | No tactile feedback anywhere |
+| Haptics on primary actions | No tactile feedback anywhere |
+| Status-bar padding on the sticky header | The nav renders under the system clock: the site's own compensation is behind `@media (display-mode: standalone)`, which a WKWebView loading a remote URL never matches |
+| 16px minimum on form fields | iOS zooms the page on focus and never zooms back out |
+
+## The native half
+
+`native/App/App/MainViewController.swift` replaces Capacitor's stock bridge
+controller in `Main.storyboard`. It exists for one thing JavaScript cannot do:
+
+- **Edge-swipe back and forward.** `WKWebView` ships with them off, and iOS has
+ no back button. Without this the app is a one-way trip: follow a link into a
+ detail page and the only way out is killing the app.
+- **Dark, edge-to-edge chrome.** The container, the WebView and its scroll view
+ all take the product's `#080814` so there is no white flash behind a loading
+ three.js scene and none at the edges of an over-scroll.
+- **`contentInsetAdjustmentBehavior = .never`**, which is what makes
+ `env(safe-area-inset-*)` non-zero inside the page. The padding the bridge
+ installs has nothing to react to without it.
+
+The app icon and launch images are generated, not hand-exported:
+
+```bash
+npm run ios:icons # re-derive from public/pwa-512x512.png
+npm run check:ios-icons # verify the committed assets match (wired into `npm run gate`)
+```
## Working on it
@@ -100,10 +126,17 @@ them at submission time:
and the `aps-environment` entitlement are in place; the APNs key, the device
token endpoint and the send path are not, and are deliberately absent rather
than stubbed.
-- **App icons and launch screen art.** `native/App/App/Assets.xcassets` still
- holds Capacitor's template. Specs in [`docs/ASSETS.md`](docs/ASSETS.md).
- **Signing.** No team, no provisioning profile, no `ExportOptions.plist`. See
[`docs/SUBMISSION.md`](docs/SUBMISSION.md).
+- **Screenshots** for the listing, which have to be captured on a real device.
+ Specs in [`docs/ASSETS.md`](docs/ASSETS.md).
+
+Two findings that are decisions rather than missing work, both written up in
+[`docs/REVIEW-RISK.md`](docs/REVIEW-RISK.md): the app currently has no service
+workers (`limitsNavigationsToAppBoundDomains: false` disables them in
+`WKWebView`, which is why the offline screen is native rather than the site's
+own), and routing a surface to the Safari sheet signs the visitor out, because
+`SFSafariViewController` does not share the app WebView's cookie jar.
## Related
diff --git a/ios/docs/ASSETS.md b/ios/docs/ASSETS.md
index 99c5f0c7a..570147077 100644
--- a/ios/docs/ASSETS.md
+++ b/ios/docs/ASSETS.md
@@ -4,9 +4,24 @@ What Xcode and App Store Connect refuse to build or accept without. Sizes are
exact; Apple rejects a mismatched pixel dimension and an icon with an alpha
channel.
-Source art lives with the rest of the brand marks in [`../../public/`](../../public):
-`pwa-icon.svg` is the vector master, and `pwa-maskable-512x512.png` shows the
-safe-zone framing the Android app uses.
+**The icon and launch images are generated, not hand-exported.**
+
+```bash
+npm run ios:icons # re-derive everything from the brand mark
+npm run check:ios-icons # verify the committed assets still match (runs in `npm run gate`)
+```
+
+[`../scripts/make-icons.mjs`](../scripts/make-icons.mjs) composites
+`public/pwa-512x512.png` (the chrome wireframe cube the web and Android apps
+also use) onto the product's own background, the same
+`radial-gradient(120% 80% at 50% 0%, #16163a, #080814)` painted by
+`ios/shell/offline.html` and `capacitor.config.ts`, so the icon, the launch
+screen and the app's first frame are one colour. The mark ships with
+transparency, which iOS forbids in an icon, and compositing rather than
+flattening is what removes it without a white halo.
+
+Editing a generated PNG by hand is caught by the `check:ios-icons` guard rather
+than discovered a release later. Change the mark, not the output.
## App icon
@@ -16,19 +31,22 @@ Xcode 15+ takes a single 1024x1024 PNG and derives the rest.
|---|---|---|
| App Store / universal | 1024x1024 | **No alpha channel**, no transparency, no rounded corners. iOS applies the mask. sRGB. |
-Optional and worth doing, since the product is dark-only: supply the dark and
-tinted variants in the same asset set so the icon does not glare on a dark home
-screen.
+Generated into `native/App/App/Assets.xcassets/AppIcon.appiconset/[email protected]`
+at 82% coverage: full-bleed, not the Android maskable framing, because iOS
+applies only a squircle corner radius and the ~20% inset a circle crop needs
+would leave the icon looking small beside every other app on the home screen.
-Drop it into `native/App/App/Assets.xcassets/AppIcon.appiconset/`. Capacitor's
-template icon is what is there now, and an archive with it will upload but must
-not ship.
+Still worth adding by hand, since the product is dark-only: the dark and tinted
+icon variants in the same asset set, so the mark does not glare on a dark home
+screen.
## Launch screen
-`native/App/App/Base.lproj/LaunchScreen.storyboard`. It should be the brand mark
-on `#080814`, matching `backgroundColor` in `capacitor.config.ts` and the
-`--bg` in `shell/offline.html`. Any mismatch reads as a flash.
+`native/App/App/Base.lproj/LaunchScreen.storyboard`, which renders the generated
+`Splash.imageset`. The mark sits at 18% of a 2732 square that Capacitor scales
+to fill, on the same background as `capacitor.config.ts` `ios.backgroundColor`,
+`MainViewController.swift` and `shell/offline.html`. Any mismatch between those
+four reads as a flash between the launch screen and the first frame.
The launch screen is static by definition: no logic, no network, no text that
needs localizing.
diff --git a/ios/docs/REVIEW-RISK.md b/ios/docs/REVIEW-RISK.md
index 254677d87..2ee894192 100644
--- a/ios/docs/REVIEW-RISK.md
+++ b/ios/docs/REVIEW-RISK.md
@@ -45,10 +45,30 @@ route the value-moving surfaces to Safari rather than removing them:
| Talk mode, animation, rigging, exports | Wallet funding and withdrawal |
| Read-only wallet and portfolio views | x402 payment flows |
-`src/native-bridge.js` already sends every off-site link to an in-app Safari
-sheet; the remaining work is a `data-external` opt-out on the same-origin
-surfaces above so they take that path too. That is a small, reversible change,
-and it is the difference between a review conversation and a rejection.
+**This is not a one-line change, and the reason matters.**
+`src/native-bridge.js` already sends every *off-site* link to an in-app Safari
+sheet, so routing a same-origin surface there looks like adding five paths to a
+list. It is not: `SFSafariViewController` runs on Safari's cookie jar, and the
+session cookie that authenticates the visitor was set in the app's `WKWebView`,
+which does not share it. Route `/pay` to the sheet as it stands and the visitor
+arrives signed out, on a page that exists to spend their money.
+
+Doing it properly needs a session handoff: the app mints a short-lived,
+single-use code against the live session and the Safari URL carries it, which
+the site exchanges for a cookie on first load. The closest existing thing is
+`POST /api/auth/extension-token` ([`../../api/auth/extension-token.js`](../../api/auth/extension-token.js)),
+which solves the same shape of problem for the browser extension but mints a
+scoped Bearer token, and a Bearer token cannot authenticate a page load. So this
+is a real, small feature, not a config flag. Size it before promising a date.
+
+The surfaces the list should hold, read off `data/pages.json` rather than
+guessed: `/launch`, `/launcher` and `/pumpfun` (they mint and trade),
+`/pay` and `/payments` (they spend). Deliberately NOT `/wallet` or
+`/agent-wallet`: Apple permits wallet storage and viewing from an organization
+account, and pushing the two most-used surfaces out to Safari would cost far
+more than it buys. Also not `/agent-trade`, `/coin3d`, `/launch-studio` or
+`/pay/simulator`, which read as transactional and are a visualisation, a
+visualisation, a catalogue and a dry run.
## 2. Guideline 4.2: minimum functionality.
@@ -78,6 +98,12 @@ move it from defensible to comfortable, in order of effect per unit of work:
Push notifications count for 4.2 as well and are half-wired (entitlement and
background mode present, APNs key and token endpoint absent).
+Edge-swipe back navigation, added in `MainViewController.swift`, is not a 4.2
+credit on its own, but its absence is a reliable rejection *and* a reliable
+one-star review: `WKWebView` ships with the gesture off and iOS has no back
+button, so without it a visitor who follows one link has no way out of the app
+except killing it.
+
## 3. Guideline 5.1.1: permissions and account deletion.
- Every usage string in `Info.plist` says what the data is for in the user's
@@ -100,7 +126,26 @@ through the Safari sheet rather than the app's WebView. Keep it that way:
running third-party sign-in inside an embedded WebView is both a review problem
and a security one.
-## 5. What is not a risk here.
+## 5. Service workers are off, and that is the current trade.
+
+`limitsNavigationsToAppBoundDomains` is `false`, and `WKWebView` only runs
+service workers for **app-bound domains**. So inside the app the site's service
+worker never registers: no workbox precache, no offline page from
+`public/offline.html`, no `share_target` interception. That is why the app
+carries its own native offline screen (`shell/offline.html`, wired as
+`server.errorPath`) rather than relying on the web one.
+
+Flipping it is tempting and should not be done blind. Declaring
+`WKAppBoundDomains` in `Info.plist` and setting the flag `true` would restore
+service workers, and the app already keeps in-WebView navigation to three.ws
+hosts with everything else going to the Safari sheet, so the restriction is
+close to what the app does anyway. But the limit is ten domains, it cannot be
+changed after install without an app update, and app-bound mode also constrains
+the JavaScript-injection APIs that Capacitor's own bridge depends on. If it is
+wrong, the app does not degrade: it does not work at all. Test it on a real
+device before it ships, not after.
+
+## 6. What is not a risk here.
- **AR.** ARKit Quick Look and WebXR usage are ordinary and uncontroversial.
- **User-generated 3D content.** Standard UGC moderation expectations apply