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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mdindex 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 inplace; the APNs key, device-token endpoint and send path are not, and areabsent 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.## Relateddiff --git a/ios/README.md b/ios/README.mdindex 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 devicetoken endpoint and the send path are not, and are deliberately absent ratherthan 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.## Relateddiff --git a/ios/docs/ASSETS.md b/ios/docs/ASSETS.mdindex 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 areexact; Apple rejects a mismatched pixel dimension and an icon with an alphachannel.-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 thatneeds localizing.diff --git a/ios/docs/REVIEW-RISK.md b/ios/docs/REVIEW-RISK.mdindex 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 andbackground 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 problemand 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