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.
solana-mobile/: the three.ws Android app
Everything needed to package three.ws as an Android app and publish it: the Mobile Wallet Adapter (MWA) wallet that signs through the on-device Seed Vault, the Trusted Web Activity (TWA) wrapper, the release pipeline, and the listing copy for both stores.
Next: v1.1.0 (versionCode 2) adds the Agent glance home screen widget (../docs/native-widgets.md); it is built and emulator-verified (2026-08-29) and ships once its API lane is deployed.
Status: v1.0.0 approved and live on the Solana dApp Store (submitted 2026-08-28, approved 2026-09-01) (release #331044442814, versionCode 1). The reviewed bytes are the v1.0.0 GitHub release. Identifiers and what the portal recorded: ../docs/seeker-submission-day.md.
One package id, two channels. ws.three.app ships to the Solana dApp Store (Seeker and Saga, listing copy in publish/) and to Google Play (every Android phone, listing copy and submission runbook in publish-play/). Same build, same app, two store listings that must describe the same product. The Play path has one trap with no local symptom, and it is documented in publish-play/README.md step 6: Play re-signs the bundle with Google's own key, so Google's certificate fingerprint has to be added to twa/extra-fingerprints.json or every Play install loses full-screen mode.
Layout
solana-mobile/
├── twa/twa-manifest.json # Bubblewrap input: wraps three.ws as an Android TWA
├── well-known/ # assetlinks.json template (real file: /public/.well-known/)
├── src/ # MWA wallet wrapper (drop-in for the existing Solana code)
│ ├── seeker-detect.js # TWA/Seeker detection + isMwaSupported() capability probe
│ ├── mwa-wallet.js # Phantom-shaped wallet backed by the on-device Seed Vault
│ ├── mwa-errors.js # normalizes MWA errors (user decline -> code 4001)
│ ├── index.js # single-import boot; sets window.solana when on Seeker
│ └── package.json # declares MWA peer/runtime deps
│ └── extra-fingerprints.json # certificates OTHER than our keystore that may sign the app
├── scripts/
│ ├── setup-android-sdk.sh # headless machines: stage JDK 17 + Android SDK for Bubblewrap
│ ├── build-apk.sh # generate keystore (if needed), build + sign release APK
│ ├── assetlinks.mjs # build the Digital Asset Links file from every signing certificate
│ ├── make-media.mjs # generate icon/banner/feature listing assets from the live product
│ ├── update-assetlinks.sh # refresh /public/.well-known/assetlinks.json from the keystore
│ └── publish.sh # upload the APK to the Publisher Portal (dapp-store-cli 1.x)
├── publish/ # Solana dApp Store: Publisher Portal worksheet + listing + media
│ ├── config.yaml # every value the owner enters in the portal, in one place
│ ├── listing/ # description, short description, what's new, Seeker features
│ └── media/ # icon, banner, feature graphic (screenshots need a real Seeker)
├── publish-play/ # Google Play: submission runbook, worksheet, listing, declarations
│ ├── README.md # the account-type decision that sets the timeline, then the steps
│ ├── config.yaml # every value the owner enters in Play Console
│ └── listing/ # title/short/full copy, data safety, content rating, financial features
└── docs/
├── ASSETS.md # exact pixel specs for icon/banner/screenshots
├── CHECKLIST.md # end-to-end submission checklist with verification dates
└── INTEGRATION.md # how the wallet is wired into the three.ws bundle
The web manifest is NOT duplicated here: the live one is generated by vite-plugin-pwa from vite.config.js (webManifestUrl in twa/twa-manifest.json points at it). The app-only surfaces live with the rest of the site:
/seeker(pages/seeker.html,src/seeker.js): the TWA's start URL. One-tap Seed Vault sign-in, Create / Explore grid, the owner's agents, and Seeker Genesis Token verification.- Share target:
public/share-target-sw.jshandlesPOST /create/sharefrom the Android share sheet;src/shared/share-target.jshands the file to/create/selfie(photos) or/create(GLB). The APK registers the same target throughshareTargetintwa/twa-manifest.json(MIME types only; Android rejects file extensions there). - Offline:
public/offline.htmlis precached and served by the workboxprecacheFallbackrule invite.config.jswhen a navigation fails. - Icons:
public/pwa-maskable-*.pngkeep the glyph inside Android's safe zone;build-apk.shservespublic/locally during the build so the APK embeds this commit's icons rather than whatever the last deploy shipped. - Seeker verification API:
api/seeker/[action].js, documented indocs/api-reference.md. Product doc:docs/seeker-app.md.
How the wallet works
The MWA wallet is already wired into the bundle: src/wallet.js and src/game/play-auth.js import solana-mobile/src/index.js, and @solana-mobile/mobile-wallet-adapter-protocol-web3js is a root dependency. Inside the TWA the import installs an MwaWallet at window.threeWsWallet (mirrored onto window.solana); everywhere else it is a no-op. src/onchain/adapters/solana.js uses the Seed Vault's one-tap Sign-In With Solana (signIn()) for wallet linking and falls back to the two-step signMessage flow on injected wallets.
The MWA auth token is persisted in localStorage (with a sessionStorage fallback), so a session survives Android killing the backgrounded TWA process: the next signature is a silent reauthorize, not a new Seed Vault prompt. A token the wallet has revoked is dropped on the first failed reauthorize and the wallet emits disconnect. The wrapper is unit-tested against a fake transport:
npx vitest run tests/solana-mobile-mwa-wallet.test.js \
tests/solana-mobile-mwa-errors.test.js tests/solana-mobile-seeker-detect.test.js
Details: docs/INTEGRATION.md.
Release pipeline
The full runbook, including the Publisher Portal steps the owner does once, is docs/seeker-publishing.md. The short version:
Publishing is Publisher Portal backed (dapp-store-cli 1.0, May 2026). The publisher profile, KYC, the App NFT, and the listing live in https://publish.solanamobile.com; the CLI only uploads one signed APK per release and the portal matches it to the app by package name (ws.three.app).
cd solana-mobile
# 0. Headless machine (codespace/container) with no Android toolchain yet:
# stages JDK 17 + Android SDK under ~/.bubblewrap. Idempotent.
./scripts/setup-android-sdk.sh
# 1. Restore the release keystore (it is gitignored). Both halves live in
# Secret Manager since 2026-08-27; the password also sits in .env as
# SOLANA_MOBILE_KEYSTORE_PASSWORD. Losing this key means the app can never
# be updated, so never generate a second one while this one exists.
gcloud secrets versions access latest --secret three-ws-seeker-release-keystore \
--project aerial-vehicle-466722-p5 | base64 -d > android.keystore
export SOLANA_MOBILE_KEYSTORE_PASSWORD="$(gcloud secrets versions access latest \
--secret three-ws-seeker-keystore-password --project aerial-vehicle-466722-p5)"
# 2. Build the signed APK. Also writes /public/.well-known/assetlinks.json
# with the key's fingerprint (98:0A:1A:AB:...:11:13:D7).
KEYSTORE_PASSWORD="$SOLANA_MOBILE_KEYSTORE_PASSWORD" ACCEPT_ANDROID_SDK_LICENSES=1 ./scripts/build-apk.sh
# 3. Deploy three.ws so assetlinks.json is live (npm run deploy:gcp from the
# repo root; production is Cloud Run), then confirm Google sees it:
curl -fsSL https://three.ws/.well-known/assetlinks.json | jq .
curl -fsSL 'https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://three.ws&relation=delegate_permission/common.handle_all_urls'
# 4. First release only, in the portal (owner): create the publisher profile,
# pass KYC/KYB, "Add a dApp" using publish/config.yaml + publish/listing/ +
# publish/media/, mint the App NFT (~0.2 SOL in the publisher wallet), and
# create an API key under Settings > API keys.
# 5. Submit the release.
SOLANA_KEYPAIR=~/.config/solana/publisher.json \
DAPP_STORE_API_KEY='portal-api-key' \
./scripts/publish.sh
For later releases, bump appVersionCode / appVersion in twa/twa-manifest.json (or pass VERSION_CODE / VERSION_NAME), then repeat steps 2 and 5. publish.sh refuses to re-submit a versionCode it already shipped from the same machine. Releases are run locally by the owner; this repo does not use GitHub Actions.
Emulator QA
Everything except the Seed Vault itself can be verified in a stock emulator; this is how the 2026-08-27 build was checked.
# One-time: emulator, platform tools, and an Android 14 image (KVM needed: sudo chmod 666 /dev/kvm in a codespace).
SDK=~/.bubblewrap/android_sdk/cmdline-tools
$SDK/bin/sdkmanager --sdk_root=$SDK "platform-tools" "emulator" "build-tools;34.0.0" "system-images;android-34;google_apis;x86_64"
echo no | $SDK/bin/avdmanager create avd -n seeker -k "system-images;android-34;google_apis;x86_64" -d pixel_7
# The SDK root is the cmdline-tools dir, so fix the image path avdmanager writes:
sed -i 's#^image.sysdir.1=.*#image.sysdir.1=system-images/android-34/google_apis/x86_64/#' ~/.android/avd/seeker.avd/config.ini
ANDROID_SDK_ROOT=$SDK $SDK/emulator/emulator -avd seeker -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect &
adb install -r build/three-ws-release.apk
adb shell am start -n ws.three.app/.LauncherActivity # first launch shows Chrome's welcome sheet once
adb shell dumpsys shortcut | grep -A40 "Package: ws.three.app" | grep shortLabel
adb shell pm get-app-links ws.three.app # state 1 after assetlinks.json is live for this key
adb push ../public/pwa-512x512.png /sdcard/Download/selfie.png
adb shell am start -a android.intent.action.SEND -t image/png \
--eu android.intent.extra.STREAM file:///sdcard/Download/selfie.png -n ws.three.app/.LauncherActivity --grant-read-uri-permission
adb exec-out screencap -p > shot.png
Until the commit that adds /seeker and the share handler is deployed, the emulator opens production and shows the site's 404 for both; that is the deploy gate, not an app bug.
The home screen widget
The release APK fetches its card from https://three.ws, so a widget in a release build shows "Fetching your agent" until /api/glance/mine?format=png is deployed. To exercise the whole loop against a local server before that, build the debug variant of the same overlaid project (only the debug variant allows plain http and honours the origin override; see android-overlay/app/src/debug/AndroidManifest.xml) and link it with a real token:
# After scripts/build-apk.sh (which applies android-overlay/ to build/):
(cd build && JAVA_HOME=~/.bubblewrap/jdk/jdk-17.0.20.1+1 ./gradlew assembleDebug -q)
adb install -r build/app/build/outputs/apk/debug/app-debug.apk
# A local API on :8080 (from the repo root: PORT=8080 node --env-file=.env --env-file=.env.local server/index.mjs),
# a session for the QA account, and a widget token from it:
TOKEN=$(curl -s -c /tmp/j -H 'content-type: application/json' -H 'origin: https://three.ws' \
-d "{\"email\":\"$AUDIT_EMAIL\",\"password\":\"$AUDIT_PASSWORD\"}" http://127.0.0.1:8080/api/auth/login >/dev/null && \
curl -s -b /tmp/j -H 'content-type: application/json' -H 'origin: https://three.ws' \
-d '{"platform":"android","label":"emulator"}' http://127.0.0.1:8080/api/glance/token | jq -r .token)
# Link the widget (the inner quotes keep the & away from the emulator's shell) and accept the launcher's pin dialog:
adb shell am start -a android.intent.action.VIEW -d "'threews://glance/link?token=$TOKEN&origin=http://10.0.2.2:8080'"
adb shell uiautomator dump /sdcard/ui.xml && adb shell cat /sdcard/ui.xml | grep -o 'text="Add to home screen"[^>]*bounds="[^"]*"' # then `adb shell input tap` inside those bounds
# The five checks (the widget lands on home screen page 2; `input swipe 900 1200 200 1200 300` gets there):
adb logcat -d | grep WM-WorkerWrapper # SUCCESS: refreshed with no app UI open
adb shell run-as ws.three.app ls -la files/glance # the cached bitmap per size
adb shell am force-stop ws.three.app # widget keeps its card
adb shell cmd connectivity airplane-mode enable # then tap "Updated …" on the widget: footer says "(offline)", card stays
adb reboot && adb wait-for-device # widget comes back with its card
uiautomator dump is the reliable way to read the widget's state headless: the card ImageView carries a content description of ", " and the footer TextView (ws.three.app:id/glance_updated) carries the refresh time.
What still needs a physical Seeker
Listing media is no longer on that list. Everything the portal asks for is generated and checked in under publish/media/: npm run build:dapp-store-media writes the icon, banner, feature graphic, and the 1200x1200 Editor's Choice card, and npm run build:dapp-store-previews builds the five 1080x1920 previews as one carousel (see docs/ASSETS.md). Real Seeker captures dropped into publish/media/device/ replace the browser ones and the carousel rebuilds around them.
- Device smoke (install, Seed Vault sheet, suspend/resume, deep links): section 3, 4, and 9 of
docs/CHECKLIST.md. - Promo video: optional;
publish/media/video.mp4if ever added.
Privacy policy and EULA are content of the main site and are live at /legal/privacy and /legal/eula.
See also
docs/CHECKLIST.md: the only doc you need open during submission.docs/INTEGRATION.md: how the wallet is wired and how it fails.docs/ASSETS.md: pixel specs and capture instructions.- Solana Mobile: https://docs.solanamobile.com/dapp-store/publishing-cli and https://docs.solanamobile.com/dapp-store/submit-new-app