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.
three.ws on iOS
three.ws ships to the App Store as a native iOS app (ws.three.app). Like the
Seeker app, it is a shell around the live web product rather
than a second implementation of it: a Capacitor 8 container whose WKWebView runs
https://three.ws, wrapped in the native layer a website cannot have. For a
WebGL product that is the right shape, and it means the app is never a version
behind the site. What makes it an app is everything around that shell.
This page is the user-facing map. Packaging, signing, App Review posture and the
submission checklist live in ios/README.md.
Status: in-repo, not yet submitted. The Xcode project builds and the web side is live in every deploy. What is outstanding is an Apple Developer organization account and the APNs signing key that comes with it. See "What is missing" below.
What the app does differently from the website
| Surface | In the iOS app | Where it lives |
|---|---|---|
| Sharing out | The system share sheet, with AR captures attached as real image files | ios/src/native-bridge.js (navigator.share shim) |
| Sharing in | three.ws in every app's share sheet. One to three photos open the selfie-to-avatar flow as the front, left and right angles; a .glb from Files opens the upload flow |
ios/native/App/ShareExtension/, src/shared/share-target.js |
| Push notifications | Sales, purchases, follows and every other notification you left push on for, delivered over APNs with the same preference center as the web. A tap opens the page it is about | api/_lib/apns.js, api/push/device.js, src/push-notifications.js |
| Icon badge | The home screen icon shows your unread count, and reading notifications in the app clears it | ios/src/native-bridge.js, ThreeWsAppPlugin.swift |
| Quick actions | Press and hold the icon: Create avatar, Discover, My agents, Notifications | ios/native/App/App/QuickActions.swift, Info.plist |
| Deep links | Any https://three.ws/... link opens in the app once the app association is live |
ios/native/App/App/App.entitlements, api/wk.js |
| Wallet returns | A wallet or OAuth redirect comes back to the exact page that started it, over threews:// |
ios/src/native-bridge.js (appUrlOpen), Info.plist URL types |
| Off-site links | Open in an in-app Safari sheet and return, instead of navigating the app away with no way back | ios/src/native-bridge.js |
| 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 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
Capacitor injects its native bridge into the remote page at document start, so
window.Capacitor exists on https://three.ws whenever the site is being
viewed inside the app, and nowhere else. ios/src/native-bridge.js keys every
behaviour above off that, and ships with the site: the
three-ws-ios-native-bridge plugin in vite.config.js
copies it into dist/ under a content-hashed name and injects a script tag into
every built page except the third-party embed entries.
Two consequences worth knowing:
- App behaviour ships on a web deploy, not an App Store release. Fixing the share sheet or adding a deep-link route is a normal deploy.
- An old web deploy means an app with no native behaviour. The app degrades to a plain WebView rather than breaking, but the shims are simply absent.
Compared with the Android app
The Seeker app is a Trusted Web Activity, so it inherits Chrome's Web Push and the web manifest's share target and shortcuts. The iOS WebView inherits none of those, so each one is rebuilt natively, and in two places the iOS version goes further:
| Android (Seeker, Play) | iOS | |
|---|---|---|
| Launcher shortcuts | Create, Discover, My agents | The same three plus Notifications |
| Share into three.ws | Photos and .glb through the web share target |
Photos and .glb through a share extension. HEIC photos are converted to JPEG on the phone before the page ever sees them |
| Push | Web Push through Chrome | APNs, with the unread count on the icon badge |
| Home screen widget | Agent glance | Agent glance, small, medium and large |
| Car | Android Auto | CarPlay (voice-based conversation) |
| Wallet sign-in | Seed Vault through Mobile Wallet Adapter | The site's wallet flows, with wallet and OAuth redirects returning to the page that started them over threews:// |
Turning on push
Push is off until you ask for it, the same as on the web: open the bell in the
header and tap Turn on push, or use the toggle in the notification
preferences. iOS then shows its permission prompt once. Behind the scenes the
app registers with Apple, sends the device token to POST /api/push/device,
and from then on every notification whose push channel is on in your
preferences arrives on the phone. Turning push off removes that one device and
leaves your other devices alone.
The app re-sends its token once per launch, because Apple can issue a new one after a restore or an OS update. That refresh only succeeds for the account that turned push on: if someone else signs in on the same phone, the device is forgotten rather than moved to their account, and they get push only by turning it on themselves.
Sharing into the app
Share a photo from Photos, Camera or any other app and pick three.ws in the
share sheet. The sheet confirms the photo is ready; open three.ws and it is
waiting in Create as the front view of a selfie-to-avatar run. Two more photos
shared together fill the left and right angles. A .glb shared from Files
lands in the upload flow instead.
The extension cannot open the app on its own (Apple does not give share extensions that ability), so the files wait in the app's shared container for ten minutes and the app collects them the next time it comes forward. If you have push turned on, the sheet also leaves a notification you can tap to go straight there. A share is used once: reloading the page does not bring it back, and anything not collected within a day is deleted.
The app association
GET /.well-known/apple-app-site-association (api/wk.js) is
what tells iOS that three.ws links belong to the app, and that the login form
inside the app may offer a saved three.ws password. It is served from the API
rather than public/.well-known/ because Apple requires an exact path, a JSON
content type, and no redirect.
The app identifier is <Team ID>.ws.three.app, and the Team ID comes from
APPLE_TEAM_ID on the Cloud Run service. Until that is set the endpoint answers
503 not_configured on purpose: publishing an association for a team that
cannot sign anything fails silently on device, where links just keep opening in
Safari and nothing errors.
curl -sS -D- https://three.ws/.well-known/apple-app-site-association
The applinks components hand every path to the app except /api/* (OAuth and
x402 callbacks must finish in the browser that started them) and the /embed*
and /widget* entries (they exist to render inside someone else's page).
Payments open in Safari
App Review does not allow buying digital goods, launching coins or trading
inside an iOS app outside In-App Purchase (guidelines 3.1.1 and 3.1.5). So in
the app, every step that spends money shows a Continue in Safari sheet, and
Open in Safari carries the visitor to the same page in real Safari, still
signed in, through a 60-second single-use code
(/api/auth/handoff).
Wallet custody (viewing, depositing, withdrawing, claiming) stays in the app.
Which surfaces leave, and why, is in
ios/docs/REVIEW-RISK.md.
What is missing
APPLE_TEAM_ID, which needs an Apple Developer Program account enrolled as an organization. Apple only permits wallet functionality from organization accounts, and that enrollment needs a legal entity and a D-U-N-S number.- The APNs signing key. Push is built end to end: the device endpoint,
the sender, the fan-out, the in-app enrolment and tap routing. It stays
dormant (
nativePush.ios: falsein/api/config, so the app never offers it) until a.p8key from the same Apple Developer account is set on the Cloud Run service asAPNS_KEY_IDandAPNS_AUTH_KEY. Steps inios/docs/SUBMISSION.md. - 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). - A signed build. Everything up to signing is in place: privacy manifests
for the app and the share extension, a shared scheme, Xcode Cloud's
ci_scripts/, andnpm run ios:release, which archives with automatic signing and uploads to TestFlight in one command onceAPPLE_TEAM_IDexists. Steps inios/docs/SUBMISSION.md. - Service workers, which
WKWebViewruns 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
- three.ws on Solana Seeker: the Android app
ios/README.md: building and shipping this oneSTRUCTURE.md: where every surface lives