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): document push, the share extension and quick actions, and how the iPhone app now compares with Android

nirholas625cbb8a62b0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45e51fe2f..cd39ce8cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,11 +7,13 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-09-30
- **Platform Analytics** (`/analytics`): Every three.ws platform total on one page, read live: agents, agents with a wallet, coins launched, 3D models generated, LLM tokens processed, x402 settlements and volume, marketplace sales and agent-to-agent hire volume, each with a daily growth chart over 30 days, 90 days or all time and a note on exactly how it is counted.
+- **Success Stories** (`/stories`): Agents with results anyone can check: coins launched, creator fees and service income, computed by three.ws from launch records and settled payments and shown only when the agent's owner opts in. Grouped by category, each linking to the full Spotlight entry and the coin on Solscan.
- **3D models no longer arrive glued to a floor slab**: The 3D generators sometimes built a thin, wide plate under whatever you asked for: a teapot sitting on a black marble square, a telescope standing in the middle of a grey sheet many times its size. Every finished model is now checked for that plate and has it cut away before it is saved, while anything that really has a base, like a lamp foot, a plinth or a tripod, is left exactly as it was. (`/forge`) `[fix]`
- **59 more pages now read in your language**: Pick any of the 85 languages in the language menu and 59 more pages now follow it, including the Airdrop Checker, Portfolio, Drops, Crews, Launch, the Agent Monitor and the rig and embed doctors. Titles, buttons, form labels, hints, error messages and the text shown when a page is shared all translate. Live numbers and statuses on those pages (counters, balances, scan results, play and pause buttons) keep updating in every language: the translation step now recognises a value the page has already filled in and leaves it alone, instead of putting a placeholder like "Loading" back over it. (`/airdrops`) `[improvement, fix]`
- **Every platform total in one free API call**: GET /api/platform/analytics returns agents, agents with a wallet, coins launched, 3D models generated, LLM tokens processed, x402 settlements and volume, marketplace sales and agent-to-agent hire volume, each with a daily series over 30 days, 90 days or all time and a plain sentence saying exactly which rows were counted. A figure that cannot be read comes back empty with a named reason instead of as zero. It powers the new analytics page and is open to anyone building on three.ws. (`/analytics`) `[feature]`
- **Photo to 3D keeps going when its main engines go down**: When a photo-to-3D job fails partway through, it already moves to the next engine on its own. Until now that only worked while another textured engine was up, so when the two main engines failed together last week, photo generations stopped completely. There is now one more rung: our own TripoSG engine takes over the job and delivers the shape of your model without textures, and the progress screen tells you when that happens. You get a model you can work with instead of an error, and whenever a textured engine is up, it is still used first. (`/image-to-3d`) `[fix, improvement]`
- **See where every $100 paid in $THREE goes**: The $THREE page now shows, for paid compute, marketplace sales, scarcity mints, spins and copy-trading fees, how every $100 splits between the seller, the treasury that funds buybacks, and holder rewards. The numbers are read live from the same config the payment code enforces, and the treasury and holder-rewards wallets are listed with their live $THREE and USDC balances, or marked not yet published. The platform never burns $THREE. The page also follows your light or dark theme now. (`/three-token`) `[feature]`
+- **The coming iPhone app gains notifications, a share sheet entry and quick actions**: The three.ws iOS app, on its way to the App Store, now matches the Android app and goes further. Turn on notifications and sales, follows and remixes arrive on your iPhone with your unread count on the app icon, and a tap opens the page it is about. three.ws appears in the share sheet: share one to three photos and they wait in Create as the front, left and right views of a new 3D avatar, or share a .glb from Files to upload it. Press and hold the icon for Create avatar, Discover, My agents and Notifications. (`/docs/ios-app`) `[feature]`
- **The language menu now offers 69 languages**: The language menu grew from 14 languages to 69, each one fully translated. 55 more pages now follow the language you pick, including Hood Desk, Portfolios, Fee Bridge, Agent Cards, Connect, the CLI sign-in approval, Motion, Docs World and the legal pages. Their titles, headings, buttons and the text shown when a page is shared all translate, and so does the sitemap, so you can find every page on three.ws in your own language. (`/sitemap`) `[feature, improvement]`
- **The Oracle's model now downloads from any website**: The Oracle's conviction model is published data, and the @three-ws/oracle-model package is meant to score coins anywhere. Until now its download endpoint only answered pages on three.ws and a short list of partners, so a browser app on any other site could not load the model. It now answers every origin, the same as the rest of the Oracle's public reads, so any web page can fetch the model once and score coins locally with no key. (`/oracle-lab`) `[improvement]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 133257c8a..d4fd4c9da 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -141,6 +141,7 @@ bottom.
| `/play` friends, presence & verified profiles (drawer, cross-world DMs, in-world profile cards) | Client: [src/game/friends-panel.js](src/game/friends-panel.js) (shared with `/walk`), mounted in [src/game/coincommunities.js](src/game/coincommunities.js) `_openFriends()`/`_closeFriends()`, HUD button + unread badge in [src/game/coincommunities-ui.js](src/game/coincommunities-ui.js), account-level state/polling in [src/friends.js](src/friends.js), profile card in the shared inspector [src/shared/avatar-inspector.js](src/shared/avatar-inspector.js) (`renderProfile`). Server: signed ticket verify + `socialHub` registration + verified `username` on the Player schema in [multiplayer/src/rooms/WalkRoom.js](multiplayer/src/rooms/WalkRoom.js) + [multiplayer/src/schemas.js](multiplayer/src/schemas.js), ticket signer [api/_lib/presence-store.js](api/_lib/presence-store.js) / verifier [multiplayer/src/presence-token.js](multiplayer/src/presence-token.js), hub in [multiplayer/src/social-hub.js](multiplayer/src/social-hub.js) | In-repo | W09+W10 of the World Online program (program brief retired to git history). Press `J` or the HUD `Friends` button to open a right-docked drawer showing your account's friend graph; live online/offline presence per coin world, requests, and DM threads; the same graph and threads `/walk` and the standalone `/friends` page already share. `community-net.js` carries a signed presence ticket into every `walk_world` join and forwards the server's `social` push onto its own event bus, which is what makes a `/play` player visible to friends and able to receive a live DM. W10 makes the platform identity first-class in-world: the ticket also carries the account's username + display name (signed, so nobody can wear a handle they don't own), WalkRoom publishes the verified `username` on the Player schema, nameplates show the @handle, the signed-in lobby defaults to the account's display name with an @handle chip, and clicking any verified player (or `I`) opens their real three.ws profile card in the shared avatar inspector: bio, follower counts, follow/unfollow (`/api/users/:username/follow`), the right friends verb (Message → the in-world DM drawer when already friends, Add friend / Accept otherwise), their latest creations, and a link to `/u/<username>`. Works identically in `/walk` (same room, same inspector). Tests: [tests/play-friends-presence.test.js](tests/play-friends-presence.test.js), [tests/play-profile-identity.test.js](tests/play-profile-identity.test.js). |
| Crew HQ (crews, tags, 3D presence room) | Page [pages/crews.html](pages/crews.html) + [src/crews-page.js](src/crews-page.js) + [src/crews.css](src/crews.css) `→ /crews` and `/crews/<TAG>`, data layer [api/_lib/crews-store.js](api/_lib/crews-store.js), endpoints [api/crews/](api/crews) (`index.js`, `[tag].js`, `search.js`, `directory.js`), presence [api/_lib/presence-store.js](api/_lib/presence-store.js), schema `api/_lib/migrations/2026-06-05-crews.sql` | Live | The group half of the social system: a crew is a set of accounts flying one 2-6 character tag, with one owner, one crew per account, and a public headquarters. The HQ renders the roster as a room rather than a list, each member standing as their own agent's 3D avatar (resolved by `standeesFor()`, private models never emitted) and lit by the same Redis presence the friends drawer reads. Crew colour is an FNV-1a hash of the tag, so a crew looks like itself everywhere without stored art. Live `<agent-3d>` figures are capped and lazily mounted so a large crew cannot exhaust the browser's WebGL contexts. The backend shipped with W09 and had no UI at all until this page; the in-world friends drawer now links to it. Docs: [docs/crews.md](docs/crews.md). Tests: [tests/crews-shared.test.js](tests/crews-shared.test.js), [tests/crews-wiring.test.js](tests/crews-wiring.test.js) |
| Agent Spotlight (community showcase) | Index [pages/spotlight.html](pages/spotlight.html) + [src/spotlight.js](src/spotlight.js) `→ /spotlight`, entry page [pages/spotlight-entry.html](pages/spotlight-entry.html) + [src/spotlight-entry.js](src/spotlight-entry.js) `→ /spotlight/:id`, shared render + form modules [src/spotlight-shared.js](src/spotlight-shared.js) / [src/spotlight-form.js](src/spotlight-form.js), styles [src/spotlight.css](src/spotlight.css), crawler share cards [api/spotlight-og.js](api/spotlight-og.js), HTTP boundary [api/spotlight/[action].js](api/spotlight), queries + ranking [api/_lib/spotlight-store.js](api/_lib/spotlight-store.js), schema `api/_lib/migrations/20260901160000_agent_showcase.sql`, curated seed [scripts/seed-spotlight.mjs](scripts/seed-spotlight.mjs) | Live | The curated half of `/agents`: the index lists every agent ever registered, this lists the ones a person wrote up and the community voted on. An entry stores the pitch only (headline, one-liner, write-up, category, tags, demo link); the agent's name, avatar, skills, on-chain identity, conversation count and builder are read live off `agent_identities` on every request, so a card can never drift from the agent it points at. Ranked by `(votes + 1) / (age_days + 1) ^ 1.2`, computed identically in JS and in the SQL `ORDER BY`; the `+ 1` keeps a brand-new entry on the first page, and the day scale (rather than the hour scale every feed copies from Hacker News) is what stops a low-volume board's `trending` from collapsing into `newest`. One entry per agent (re-submitting edits it), one vote per account, votes counted on read rather than denormalised. Entries badged `Curated` were written by three.ws about someone else's public agent, say so in words on the entry page, and are replaced the moment that builder submits their own. The API lives at `/api/spotlight/*` because `/api/showcase` is the unrelated ERC-8004 directory ([api/showcase.js](api/showcase.js)); the tables keep the `agent_showcase` name they were applied under. Docs: [docs/spotlight.md](docs/spotlight.md). Tests: [tests/spotlight-ranking.test.js](tests/spotlight-ranking.test.js) |
+| Success Stories (verified results) | Page [pages/stories.html](pages/stories.html) + [src/stories.js](src/stories.js) `→ /stories`, shared results renderer [src/spotlight-verified.js](src/spotlight-verified.js) (also drawn as "Verified results" on `/spotlight/:id`), metrics [api/_lib/spotlight-metrics.js](api/_lib/spotlight-metrics.js), actions `stories` / `consent` / `moderate` on [api/spotlight/[action].js](api/spotlight), schema `api/_lib/migrations/20260930171500_agent_showcase_story_consent.sql` | Live | Spotlight entries whose agent OWNER opted in (a checkbox on the submit form, off by default, or "Feature as a success story" on the entry page), shown only when the agent has a verified result: a coin launched (`pump_agent_mints`), service income (`agent_revenue_events` USDC net plus completed `agent_hires`), or creator fees (the agent earnings read model, when it is live). Curated entries never qualify without the owner's consent, and consent given by a previous owner does not carry over. Every figure is computed server-side and links to where it can be checked. Admins hide or restore any entry with `POST /api/spotlight/moderate` (audit-logged); a hidden entry drops out of `/spotlight`, `/stories` and the entry page. Docs: [docs/spotlight.md](docs/spotlight.md). Tests: [tests/spotlight-stories.test.js](tests/spotlight-stories.test.js) |
| `/play` Robinhood Chain worlds (NOXA + The Odyssey coins, live-trade animation) | Firehose worker [workers/robinhood-feed/](workers/robinhood-feed) (watches NOXA + Odyssey launchpads + their Uniswap v3 pools, normalizes to the pump-compatible event shape, serves SSE/WS/REST). API bridge: [api/robinhood/coin-trades.js](api/robinhood/coin-trades.js) (the in-world chart-screen's trade feed), [api/robinhood/play-worlds.js](api/robinhood/play-worlds.js) (the `/worlds` lobby's Robinhood Chain tab). Client: chain-flavored biome `hoodchain` in [src/game/world-env.js](src/game/world-env.js) (auto-pinned in [src/game/coincommunities.js](src/game/coincommunities.js) `isRobinhoodCoin()`), trade-feed endpoint routing in [src/game/chart-screen.js](src/game/chart-screen.js), lobby tab + EVM-address support in [src/worlds-lobby.js](src/worlds-lobby.js) (routes Robinhood coins to `/play`, unchanged pump.fun coins stay on `/temporary`) | In-repo | Every Robinhood Chain memecoin (chain 4663) gets the same treatment pump.fun coins already have: a deterministic 3D world seeded by its contract address, in a distinct dark ticker-tape palette, with real launchpad/Uniswap-v3 trades rippling the space live via `MarketReactor`. Multiplayer (`walk_world`, filtered by `coin`+`tier`) needed zero code changes — it already keys rooms by an opaque coin id string. `isValidToken()` in [api/_lib/coin-communities.js](api/_lib/coin-communities.js) was widened to accept EVM addresses (it previously 400'd every EVM-chain world's Town chat, even though the CHAINS list already declared ethereum/base/bsc support). Tests: [workers/robinhood-feed/tests/normalize.test.js](workers/robinhood-feed/tests/normalize.test.js) (against real captured on-chain logs). |
| Sealed wallet gift drops (send/claim) | Client: [src/pages/sealed-drops.js](src/pages/sealed-drops.js) — create + "My drops" sections mounted into [public/vanity-wallet.html](public/vanity-wallet.html) (`#drop-create`/`#drop-mine`, below the vanity grinder — vanity pattern fields are shared), claim flow on its own page [pages/drop.html](pages/drop.html) `→ /drop/:id` (24-hex-char id, routed in [vite.config.js](vite.config.js) dev middleware + [vercel.json](vercel.json)). Crypto: [src/solana/vanity/sealed-envelope.js](src/solana/vanity/sealed-envelope.js) (ECIES seal/open, X25519 keygen — all client-side, three.ws never sees a plaintext key), [src/solana/vanity/drop-protocol.js](src/solana/vanity/drop-protocol.js) (claim-token derivation). Server: [api/vanity/drops.js](api/vanity/drops.js) (create/claim/reveal/reclaim, on-chain funding), OG card [api/og/sealed-drop.js](api/og/sealed-drop.js) | In-repo | Fund a fresh wallet — optionally vanity-ground with the same prefix/suffix grinder above — wrap it in a sealed link, and send it. Two seal modes: a **bearer link** (the claim key rides in the URL fragment, anyone with the full link claims once) or **sealed to a recipient's X25519 key** (only they can ever open it, even with the link). The create fee settles via x402; the gift amount funds on-chain into a fresh wallet server-side. Claiming decrypts entirely in the browser and offers the recovered seed phrase/secret key for import — the server only ever sees the sealed ciphertext. "My drops" (browser-local, by a random sender tag) lists what you've sent so expired-unclaimed gifts can be reclaimed. |
| Premium vanity inventory (sell pre-ground addresses) | [public/vanity/premium/](public/vanity/premium/index.html) `→ /vanity/premium`, batch grinder [workers/vanity-grinder/](workers/vanity-grinder), store [api/_lib/vanity-inventory-store.js](api/_lib/vanity-inventory-store.js), sell [api/x402/vanity-premium.js](api/x402/vanity-premium.js), replenish [api/cron/vanity-inventory-replenish.js](api/cron/vanity-inventory-replenish.js) | In-repo · GCP spot CPU | Long (4–5+ char) brandable Solana addresses ground ahead of time on cheap spot CPU, sealed at rest (AES-256-GCM or GCP-KMS envelope, [api/_lib/vanity-vault.js](api/_lib/vanity-vault.js)), and sold from stock via x402 — priced by rarity ($1–$50) on `vanity-premium`, or by fixed 4–5 char tiers ($2.50/$10) directly through [`/api/x402/vanity`](docs/vanity.md#tier-1--live-grinder) (instant delivery, `source:"inventory"`) and the [pump-launch vanity upsell](docs/pump-launcher.md) — delivered exactly once, ciphertext destroyed on delivery. An hourly cron watches stock and fires a fresh grind batch (Cloud Run Job) when low. Free `vanity_premium` MCP browse tool. Runbook: [docs/ops/gcp-credits.md](docs/ops/gcp-credits.md) |
@@ -288,7 +289,7 @@ bottom.
| BNB Chain live block race | [pages/bnb-latency.html](pages/bnb-latency.html) + [src/bnb-latency.js](src/bnb-latency.js) `→ /bnb-latency`, pure helpers [src/bnb-latency-helpers.js](src/bnb-latency-helpers.js), live multi-chain API [api/bnb/latency.js](api/bnb/latency.js) over [api/_lib/bnb/latency-lanes.js](api/_lib/bnb/latency-lanes.js) (reuses `probeBlockTime` from [api/_lib/bnb/chains.js](api/_lib/bnb/chains.js) for BNB, adds Base/Ethereum/Solana lanes) | In-repo · shipped | Standalone, shareable proof page: four lanes (BNB Chain, Base, Ethereum, Solana) polled every 5s, each showing a freshly measured average block/slot time and a rolling sparkline — no hardcoded numbers, a down RPC shows "reconnecting" on just that lane. Headline strip shows BNB's live average plus its honest measured-vs-measured speedup over Base/Ethereum. Linked from the [/bnb](pages/bnb.html) hub's "real-time on-chain world" card, which auto-lights-up now that this route resolves. |
| BNB Chain payments (MPP, x402↔MPP bridge, gasless) | Accept [api/_lib/bnb/mpp-server.js](api/_lib/bnb/mpp-server.js) (`mppRequirements`/`mppChallenge`/`mppVerify`/`mppSettle`), pay [api/_lib/bnb/mpp-buyer.js](api/_lib/bnb/mpp-buyer.js) (`mppFetch`, re-exported from [api/_lib/x402-buyer-fetch.js](api/_lib/x402-buyer-fetch.js)), gasless rail [api/_lib/bnb/megafuel.js](api/_lib/bnb/megafuel.js), pilot dual-protocol endpoint [api/x402/three-intel.js](api/x402/three-intel.js) | In-repo · shipped, settlement needs merchant creds | three.ws speaks MPP (BNB Chain's Machine Payments Protocol) additively alongside x402: MPP's `b402` layer is x402 v2 byte-for-byte (same `X-PAYMENT`/`X-PAYMENT-RESPONSE`, same EIP-3009 credential), so a dual-protocol endpoint just advertises an extra BNB (`eip155:56`/`97`) accept entry and routes BNB-network payments to the b402 facilitator while Solana/Base traffic stays on the untouched x402 path. Verify (off-chain, free, replay-guarded via Redis `SET NX PX`) always runs before settle; without `B402_*` merchant credentials, settle fails closed with `mpp_not_configured` (503) rather than fabricating a receipt. Guide: [docs/bnb-payments.md](docs/bnb-payments.md). Wire contract: [specs/x402-mpp-bridge.md](specs/x402-mpp-bridge.md). Tests: [tests/bnb-mpp-server.test.js](tests/bnb-mpp-server.test.js), [tests/bnb-mpp-buyer.test.js](tests/bnb-mpp-buyer.test.js). |
| Seeker / Saga dApp Store app | [solana-mobile/](solana-mobile): TWA wrapper [solana-mobile/twa/](solana-mobile/twa), Publisher Portal listing copy [solana-mobile/publish/](solana-mobile/publish), MWA wallet + Seeker detection [solana-mobile/src/](solana-mobile/src) | Live · v1.0.0 on the Solana dApp Store (submitted 2026-08-28, approved 2026-09-01) | Everything needed to package three.ws as a Solana Mobile app and publish it to the on-chain dApp Store. Targets Seeker first; compatible with Saga Gen 1 and Gen 2. Docs: [solana-mobile/README.md](solana-mobile/README.md) |
-| iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, and marks `html.ios-app`. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. The app also carries the **CarPlay** scene for three.ws Drive: `CarPlaySceneDelegate` renders the car screen's templates while `DriveLink` bridges them to `/drive` in the WebView, gated behind the `com.apple.developer.carplay-voice-based-conversation` entitlement, which is inert until Apple grants it. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md), CarPlay [ios/docs/CARPLAY.md](ios/docs/CARPLAY.md). The project also carries the **Agent glance** WidgetKit extension (`ws.three.app.glance`, iOS 17+), whose sources live in [apple/](apple/README.md) and are shared byte for byte with the Mac app. |
+| iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, marks `html.ios-app`, routes a tapped push to its page and keeps the app icon badge equal to the inbox's unread count. Beyond the Android app it has **push notifications over APNs** (device registry [api/push/device.js](api/push/device.js), sender [api/_lib/apns.js](api/_lib/apns.js), fanned out beside Web Push in [api/_lib/notify.js](api/_lib/notify.js), client in [src/push-notifications.js](src/push-notifications.js); live once `APNS_KEY_ID`/`APNS_AUTH_KEY` are set), a **share extension** ([ios/native/App/ShareExtension/](ios/native/App/ShareExtension), `ws.three.app.share`) that takes one to three photos into `/create/selfie` or a `.glb` into `/create` through the App Group and the app's own `ThreeWsApp` plugin ([ThreeWsAppPlugin.swift](ios/native/App/App/ThreeWsAppPlugin.swift)), and four **home screen quick actions** ([QuickActions.swift](ios/native/App/App/QuickActions.swift)). `npm run check:ios-app` ([scripts/check-ios-app.mjs](scripts/check-ios-app.mjs)) holds the Swift half to its web callers, since no Linux machine can compile it. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. The app also carries the **CarPlay** scene for three.ws Drive: `CarPlaySceneDelegate` renders the car screen's templates while `DriveLink` bridges them to `/drive` in the WebView, gated behind the `com.apple.developer.carplay-voice-based-conversation` entitlement, which is inert until Apple grants it. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md), CarPlay [ios/docs/CARPLAY.md](ios/docs/CARPLAY.md). The project also carries the **Agent glance** WidgetKit extension (`ws.three.app.glance`, iOS 17+), whose sources live in [apple/](apple/README.md) and are shared byte for byte with the Mac app. |
| three.ws Glance for Mac | [apple/](apple/README.md): shared sources [apple/GlanceKit/](apple/GlanceKit), WidgetKit extension [apple/GlanceWidget/](apple/GlanceWidget), menu bar host app [apple/macos/](apple/macos) (XcodeGen spec [apple/macos/project.yml](apple/macos/project.yml)), icon [apple/scripts/make-macos-icon.mjs](apple/scripts/make-macos-icon.mjs) | In-repo · builds with XcodeGen and a Development Team · Developer ID distribution, so it needs no App Store review | The agent in a Mac's Notification Centre, and the same extension on iPhone. A menu bar app whose whole job is to hold a revocable widget token and prove it works: the Mac never sees a password, because signing in happens on three.ws and the page hands back the token through `threews://glance/link` or as a code to paste. The widget fetches `GET /api/glance/mine?format=png` on the system timeline, in both themes so it follows the reader's appearance, caches the last card in the shared App Group container so an offline Mac shows yesterday's card with the time on it, and opens the agent on click. One set of sources builds for both platforms; only the project differs, because an App Group identifier on a Developer ID Mac must carry the team prefix that the same group on iPhone must not. Guard: [scripts/check-apple-widget.mjs](scripts/check-apple-widget.mjs) (`npm run check:apple-widget`, in `npm run gate`) proves both Xcode projects and the client-to-server contract on a machine with no Xcode. Docs: [apple/README.md](apple/README.md), [docs/native-widgets.md](docs/native-widgets.md). |
| Walk Avatar browser extension | [extensions/walk-avatar/](extensions/walk-avatar) — MV3 `manifest.json`, `background.js` | In-repo · Chrome Web Store release checklist staged ([RELEASE.md](extensions/walk-avatar/RELEASE.md)) | Walks your three.ws avatar across any site and reads pages aloud — a browsing companion built on the same rig as the [walk-sdk](walk-sdk). Ships its own store-required [PRIVACY.md](extensions/walk-avatar/PRIVACY.md), [PERMISSIONS.md](extensions/walk-avatar/PERMISSIONS.md), and [TERMS.md](extensions/walk-avatar/TERMS.md). |
| Checkout companion browser extension | [extensions/checkout-companion/](extensions/checkout-companion) (MV3: [extract.js](extensions/checkout-companion/extract.js), [content.js](extensions/checkout-companion/content.js), [panel.js](extensions/checkout-companion/panel.js), [background.js](extensions/checkout-companion/background.js)), analysis [api/_lib/companion/checkout.js](api/_lib/companion/checkout.js), endpoint [api/companion/checkout.js](api/companion/checkout.js) | In-repo | The companion at the moment money moves: on a checkout page it reports the total against the price you were shown, money the page did not itemise, fees named and summed, whether the charge repeats, and the cancellation terms. **Arithmetic is never the model's job** (integer minor units, computed server-side) and **no finding is ever a legal verdict** (`sanitizeModelFindings()` drops any that claims an amount or calls something illegal). With no model reachable the arithmetic findings still stand. The extension **never reads an input**: `collectText`/`collectAmounts` refuse form fields, iframes and editable regions structurally, and redaction runs in the browser before anything is sent; only the hostname travels and nothing about the page is stored. Docs: [docs/checkout-companion.md](docs/checkout-companion.md). Tests: [tests/companion-checkout.test.js](tests/companion-checkout.test.js), [tests/checkout-extract.test.js](tests/checkout-extract.test.js) |
diff --git a/data/changelog.json b/data/changelog.json
index 72586bffb..783d99509 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-30",
+ "title": "The coming iPhone app gains notifications, a share sheet entry and quick actions",
+ "summary": "The three.ws iOS app, on its way to the App Store, now matches the Android app and goes further. Turn on notifications and sales, follows and remixes arrive on your iPhone with your unread count on the app icon, and a tap opens the page it is about. three.ws appears in the share sheet: share one to three photos and they wait in Create as the front, left and right views of a new 3D avatar, or share a .glb from Files to upload it. Press and hold the icon for Create avatar, Discover, My agents and Notifications.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/docs/ios-app"
+ },
{
"date": "2026-09-30",
"title": "Every platform total in one free API call",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 1070b7623..9ae452700 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -4461,6 +4461,19 @@ PATCH /api/notifications/preferences
The bell inbox and its per-user preference matrix. Session required. Event types include `remix`, `dm_received`, `pump_launch_filled` (bonding-curve graduation), and `follow`. Preferences are a category × channel matrix: categories `sales`, `purchases`, `social`, `irl`, `market`, `account`; channels `in_app`, `push`, `email`, `telegram`. The `in_app` channel is always on and cannot be disabled.
+### Push devices
+
+```
+POST /api/push/subscribe { subscription } browser (Web Push)
+DELETE /api/push/subscribe { endpoint }
+POST /api/push/device { token, platform: "ios", app_version?, previous? } the iOS app (APNs)
+DELETE /api/push/device { token }
+```
+
+Where a notification's `push` channel is delivered. Session and CSRF token required; 30 registrations per user per hour. A browser registers the object `pushManager.subscribe()` returns. The [iOS app](ios-app.md) has no service worker, so it registers its APNs device token instead (64 or more hex characters, case-insensitive). Both are unique per device and follow the latest signed-in owner. Every push-enabled notification fans out to both, so the preference matrix above governs a phone and a browser the same way; the iOS delivery also sets the app icon's badge to the recipient's unread count.
+
+`previous` marks a silent refresh (the app re-sending its token on launch). It succeeds only if `previous` is already registered to the caller, and answers `409 not_owner` otherwise, so a phone never enrols for whichever account happens to be signed in now. `GET /api/config` reports `nativePush.ios: true` once APNs is configured on the server (`APNS_KEY_ID`, `APNS_AUTH_KEY`, and `APNS_TEAM_ID` or `APPLE_TEAM_ID`).
+
---
## IRL API — presence, pins, money drops, world lines
diff --git a/docs/ios-app.md b/docs/ios-app.md
index c27c22b84..6dca60aa9 100644
--- a/docs/ios-app.md
+++ b/docs/ios-app.md
@@ -12,13 +12,18 @@ submission checklist live in [`ios/README.md`](../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, app icons, and push. See "What is missing" below.
+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 | The system share sheet, with AR captures attached as real image files | `ios/src/native-bridge.js` (`navigator.share` shim) |
+| 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` |
@@ -47,6 +52,53 @@ Two consequences worth knowing:
- **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](./seeker-app.md) 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`](../api/wk.js)) is
@@ -74,9 +126,12 @@ and `/widget*` entries (they exist to render inside someone else's page).
- **`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.
-- **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.
+- **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: false` in `/api/config`, so the app never offers
+ it) until a `.p8` key from the same Apple Developer account is set on the
+ Cloud Run service as `APNS_KEY_ID` and `APNS_AUTH_KEY`. Steps in
+ [`ios/docs/SUBMISSION.md`](../ios/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`).
diff --git a/ios/README.md b/ios/README.md
index ef246c7d6..e3c66f6fd 100644
--- a/ios/README.md
+++ b/ios/README.md
@@ -2,9 +2,10 @@
The App Store build of three.ws. A Capacitor 8 shell whose WKWebView runs the
live product at `https://three.ws`, wrapped in the native layer an app needs and
-a website cannot have: universal links, the system share sheet, deep links back
-from wallets, haptics, a real launch screen, and the camera / location / motion
-permissions the AR and IRL surfaces depend on.
+a website cannot have: push notifications with an icon badge, a share
+extension, home screen quick actions, universal links, the system share sheet,
+deep links back from wallets, haptics, a real launch screen, and the camera /
+location / motion permissions the AR and IRL surfaces depend on.
The Android counterpart is [`../solana-mobile/`](../solana-mobile), which
packages the same product as a Trusted Web Activity for the Solana dApp Store.
@@ -22,11 +23,18 @@ ios/
├── scripts/make-icons.mjs # derives the icon + launch images from the brand mark
├── native/App/ # the generated Xcode project (committed)
│ ├── App.xcodeproj
-│ ├── App/MainViewController.swift # swipe-back, dark chrome, edge-to-edge insets
+│ ├── App/SceneDelegate.swift # roots MainViewController, quick actions, share pickup
+│ ├── App/AppDelegate.swift # APNs token forwarding, stale share sweep
+│ ├── App/MainViewController.swift # swipe-back, dark chrome, edge-to-edge insets, open(path:)
+│ ├── App/QuickActions.swift # home screen quick action types -> pages
+│ ├── App/ThreeWsAppPlugin.swift # the app's own plugin: takeShare, setBadge
│ ├── App/CarPlaySceneDelegate.swift # the car screen: templates + voice control
│ ├── App/DriveLink.swift # CarPlay <-> /drive channel + audio session
-│ ├── App/Info.plist # usage strings, URL scheme, orientations, scenes
-│ ├── App/App.entitlements # associated domains + APNs + CarPlay
+│ ├── App/Info.plist # usage strings, URL scheme, quick actions, .glb type, scenes
+│ ├── App/App.entitlements # associated domains + APNs + CarPlay + App Group
+│ ├── ShareExtension/ # the share sheet entry (ws.three.app.share)
+│ │ ├── ShareViewController.swift # copies photos (as JPEG) or a .glb out of the sender
+│ │ └── SharedInbox.swift # App Group hand-off, compiled into app and extension
│ └── CapApp-SPM/ # Swift Package Manager plugin graph
└── docs/ # SUBMISSION.md, REVIEW-RISK.md, ASSETS.md, CARPLAY.md
```
@@ -50,6 +58,53 @@ how to build and verify it without a Mac, is in
[`../apple/README.md`](../apple/README.md) and
[`../docs/native-widgets.md`](../docs/native-widgets.md).
+## Push notifications
+
+The WebView has no service worker, so Web Push cannot reach it. The app
+registers with APNs instead and every "turn on push" control on the site works
+unchanged, because [`src/push-notifications.js`](../src/push-notifications.js)
+takes the native path inside the app:
+
+1. `enablePush()` asks iOS for permission through the PushNotifications plugin,
+ calls `register()`, and waits for the device token that
+ [`AppDelegate`](native/App/App/AppDelegate.swift) forwards to Capacitor.
+2. The token goes to `POST /api/push/device`
+ ([`api/push/device.js`](../api/push/device.js)), stored in `apns_devices`.
+3. [`api/_lib/notify.js`](../api/_lib/notify.js) sends every push-enabled
+ notification to Web Push and to APNs
+ ([`api/_lib/apns.js`](../api/_lib/apns.js)) in parallel, with the unread
+ count as the icon badge. A token APNs reports gone is pruned; a development
+ build's sandbox token is found on the sandbox host automatically.
+4. A tap reaches `native-bridge.js`, which opens the page with
+ `?source=push&n=<id>` so the re-engagement funnel records it, or opens an
+ off-site link (an explorer) in the Safari sheet.
+
+It needs `APNS_KEY_ID` and `APNS_AUTH_KEY` on the Cloud Run service (plus the
+Team ID, read from `APNS_TEAM_ID` or the existing `APPLE_TEAM_ID`). Without
+them `/api/config` reports `nativePush.ios: false` and the app never offers push.
+
+## Sharing into the app
+
+`ShareExtension/` puts three.ws in every app's share sheet for one to three
+photos or one `.glb`, the same things the Android app's web share target takes.
+The extension copies the files out of the sending app, converts photos to an
+upright JPEG no larger than 2048px, and parks them in the App Group through
+[`SharedInbox`](native/App/ShareExtension/SharedInbox.swift). Share extensions
+cannot open their host app, so when the app next becomes active
+`SceneDelegate` claims the pending share and loads
+`/create/selfie?shared=1&inbox=<id>` or `/create?shared=glb&inbox=<id>`, and
+[`src/shared/share-target.js`](../src/shared/share-target.js) reads the files
+through `ThreeWsApp.takeShare`. A share is claimable for ten minutes, consumed
+once, and swept after a day.
+
+## Quick actions
+
+Press and hold the icon: Create avatar, Discover, My agents, Notifications.
+They are declared in `Info.plist` so they exist from install, and
+[`QuickActions.swift`](native/App/App/QuickActions.swift) maps each type to its
+page. The first three mirror the Android launcher shortcuts in
+[`../solana-mobile/twa/twa-manifest.json`](../solana-mobile/twa/twa-manifest.json).
+
## CarPlay
The app carries a second scene for **three.ws Drive**, the agent in the car. Apple's
@@ -108,7 +163,10 @@ What it installs, and the breakage each one fixes:
## 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:
+controller. `SceneDelegate` builds the window in code, which overrides whatever
+`Main.storyboard` names, so the scene delegate is what has to create it;
+`npm run check:ios-app` fails if it ever goes back to the stock class. It
+exists first 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
@@ -120,6 +178,11 @@ controller in `Main.storyboard`. It exists for one thing JavaScript cannot do:
`env(safe-area-inset-*)` non-zero inside the page. The padding the bridge
installs has nothing to react to without it.
+It also registers the app's own `ThreeWsApp` plugin in `capacitorDidLoad`
+(the plugin is not a Swift package, so the SPM graph never discovers it) and
+exposes `open(path:)`, which native entry points use to navigate the WebView
+and which refuses anything that does not resolve to `https://three.ws`.
+
The app icon and launch images are generated, not hand-exported:
```bash
@@ -146,6 +209,19 @@ From the repo root:
npm run ios:sync # same as the above, without changing directory
```
+## Verifying without a Mac
+
+`npm run check:ios-app` ([`../scripts/check-ios-app.mjs`](../scripts/check-ios-app.mjs),
+wired into `npm run gate`) is what a Linux machine can prove about the Swift
+half: every source is a member of a target, the share extension is embedded and
+versioned with the app, the extension and the app agree on the App Group and
+the `.glb` type, every quick action routes to a live page, the `ThreeWsApp`
+plugin's methods match their web callers, and push is wired from the app
+delegate to the notification fan-out. It is a structural check, not a build.
+The web half is unit tested: `tests/ios-native-*.test.js`,
+`tests/push-notifications-native.test.js`, `tests/share-target.test.js`,
+`tests/apns.test.js` and `tests/push-device-endpoint.test.js`.
+
## What is not wired yet
Everything here builds and runs; these are the pieces that need an Apple
@@ -156,10 +232,9 @@ them at submission time:
([`../api/wk.js`](../api/wk.js)) answers `503 not_configured` until it is set,
and universal links keep opening in Safari until it serves a real association.
Set it with `gcloud run services update three-ws-api --region us-central1 --update-env-vars APPLE_TEAM_ID=<id>`.
-- **Push notifications.** The plugin, the `remote-notification` background mode
- 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.
+- **The APNs key.** Push is built end to end and dormant until `APNS_KEY_ID`
+ and `APNS_AUTH_KEY` are set; see "Push notifications" above and
+ [`docs/SUBMISSION.md`](docs/SUBMISSION.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.
diff --git a/ios/docs/SUBMISSION.md b/ios/docs/SUBMISSION.md
index 377208363..3fb15cec5 100644
--- a/ios/docs/SUBMISSION.md
+++ b/ios/docs/SUBMISSION.md
@@ -30,8 +30,11 @@ step 3 is blocked on it.
`PRODUCT_BUNDLE_IDENTIFIER` in `native/App/App.xcodeproj/project.pbxproj`
and the `appId` in `capacitor.config.ts`.
2. Register the bundle ID in the Developer portal with the **Associated
- Domains** and **Push Notifications** capabilities enabled; the app's
- entitlements declare both and signing fails without them.
+ Domains**, **Push Notifications** and **App Groups** capabilities enabled;
+ the app's entitlements declare all three and signing fails without them.
+ Register `ws.three.app.share` (the share extension) and
+ `ws.three.app.glance` (the widget) as well, each with **App Groups**, and
+ create the group `group.ws.three.app`.
3. Fill the listing from [`../publish/listing.md`](../publish/listing.md).
4. Answer the content rights, age rating, and privacy questionnaires. The
privacy answers must match what the app actually collects; the camera,
@@ -58,6 +61,31 @@ curl -sS -D- -o- https://three.ws/.well-known/apple-app-site-association
It must be `200`, `content-type: application/json`, **no redirect**, and the
`appIDs` entry must read `<team id>.ws.three.app`.
+## 3b. Turn on push
+
+In the Developer portal, Keys, create a key with **Apple Push Notifications
+service (APNs)** enabled. Download the `.p8` once (Apple never shows it again)
+and note its Key ID. One key serves development and production builds.
+
+Store the key in Secret Manager and point the service at it, the way every
+other credential on the service is held:
+
+```bash
+gcloud secrets create apns-auth-key --project aerial-vehicle-466722-p5 \
+ --data-file=AuthKey_<KEY_ID>.p8
+gcloud run services update three-ws-api \
+ --region us-central1 --project aerial-vehicle-466722-p5 \
+ --update-secrets APNS_AUTH_KEY=apns-auth-key:latest \
+ --update-env-vars APNS_KEY_ID=<KEY_ID>
+```
+
+The Team ID is read from `APPLE_TEAM_ID`, set in step 3. Confirm the server
+now offers push to the app:
+
+```bash
+curl -s https://three.ws/api/config | jq .nativePush # { "ios": true }
+```
+
## 4. Build the web bundle
The app's WebView loads the deployed site, so "building the app" means the site
@@ -93,6 +121,10 @@ In Xcode:
needs the same App Group and Keychain Sharing entries; both expand from
`DEVELOPMENT_TEAM`, so nothing else has to be typed. A build with no team on
this target fails to sign the .appex and the archive is rejected.
+1c. Select the **ShareExtension** target and choose the same team. It needs
+ only the App Group, which is where it parks shared photos and models for the
+ app. Without the group the extension still appears in the share sheet but
+ the app never finds what was shared.
2. Set the marketing version and build number. `MARKETING_VERSION` is `1.0`
and `CURRENT_PROJECT_VERSION` is `1` in the project file; the build number
must increase on every upload.
diff --git a/ios/publish/listing.md b/ios/publish/listing.md
index 702710c5a..2dda22211 100644
--- a/ios/publish/listing.md
+++ b/ios/publish/listing.md
@@ -39,6 +39,12 @@ Leave an agent at a real location and let other people find it there. A characte
TALK TO IT
Give an agent a voice and a personality and have a conversation out loud. It looks at you while you speak.
+SHARE A PHOTO, GET AN AVATAR
+Pick three.ws in the share sheet from Photos or any other app and the photo is waiting in Create, ready to become a 3D avatar of you. Share a GLB model from Files and it goes straight into your library.
+
+NEVER MISS A SALE
+Turn on notifications and hear the moment someone buys from your agent, follows you or remixes your work. The icon shows what you have not read yet, and a tap takes you right to it.
+
BRING IT ANYWHERE
Everything you make exports as a standard GLB and embeds in any website with one line of code. Your work is not trapped in an app.
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index be1832ee2..0148cf3e7 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-09-30T08:19:59.976Z",
+ "generated_at": "2026-09-30T08:27:19.820Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 3788,
+ "total": 3790,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -19,6 +19,16 @@
"launch"
]
},
+ {
+ "date": "2026-09-30",
+ "type": "launch",
+ "title": "Success Stories",
+ "summary": "Agents with results anyone can check: coins launched, creator fees and service income, computed by three.ws from launch records and settled payments and shown only when the agent's owner opts in. Grouped by category, each linking to the full Spotlight entry and the coin on Solscan.",
+ "link": "/stories",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-09-30",
"type": "update",
@@ -71,6 +81,16 @@
"feature"
]
},
+ {
+ "date": "2026-09-30",
+ "type": "update",
+ "title": "The coming iPhone app gains notifications, a share sheet entry and quick actions",
+ "summary": "The three.ws iOS app, on its way to the App Store, now matches the Android app and goes further. Turn on notifications and sales, follows and remixes arrive on your iPhone with your unread count on the app icon, and a tap opens the page it is about. three.ws appears in the share sheet: share one to three photos and they wait in Create as the front, left and right views of a new 3D avatar, or share a .glb from Files to upload it. Press and hold the icon for Create avatar, Discover, My agents and Notifications.",
+ "link": "/docs/ios-app",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-09-30",
"type": "update",
@@ -1565,27 +1585,6 @@
"fix",
"infra"
]
- },
- {
- "date": "2026-09-09",
- "type": "update",
- "title": "New gallery avatars now arrive with a skeleton, so they animate properly out of the box",
- "summary": "Avatars generated for the gallery were published as static meshes: they still moved, but through a fallback that maps a generic body onto them rather than a skeleton of their own. Every new one whose shape a humanoid skeleton can actually drive now goes through our auto-rigger first and arrives with a real 52-bone skeleton, so the whole motion library drives it directly. The ones that are skipped are skipped for a reason we measured: some generated models come out as a figure standing on a wide base slab, and rigging one of those tears the slab apart the moment it moves, so those keep publishing as static models. If the rigger fails or stalls, the avatar is published anyway rather than held back.",
- "link": "/gallery",
- "tags": [
- "improvement",
- "feature"
- ]
- },
- {
- "date": "2026-09-09",
- "type": "update",
- "title": "News cards stop losing their preview picture to a cold cache",
- "summary": "About a fifth of the crypto-news feed ships text-only, so those cards start as a source tile and upgrade in place once the publisher's own preview image is found. That lookup searched all 197 publisher feeds at once and gave up after 2.5 seconds, which on a freshly started server dropped whichever feed had not answered yet, so an article the feed had just served came back as unknown. The reader kept its tile, but the failed lookup was recorded as a public answer for the next ten minutes, so every visitor to /markets and /markets/news got the same dead result and a 404 in their browser console. The lookup now asks the one publisher that could hold the article first and waits for it, and a result that could not be confirmed is held for 30 seconds instead of ten minutes.",
- "link": "/markets/news",
- "tags": [
- "fix"
- ]
}
]
}