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.

4.7 KB
Raw Blame

android-overlay: native sources for the three.ws Android app

The Android app (ws.three.app) is a Trusted Web Activity that Bubblewrap regenerates from ../twa/twa-manifest.json on every build. Bubblewrap owns that generated project completely, so anything native lives here and is laid over the generated tree after bubblewrap update and before bubblewrap build. ../scripts/build-apk.sh runs ../scripts/apply-overlay.mjs in exactly that slot, and fails the build if this directory is missing.

What is in it

Two features, namespaced so they can never collide with each other or with a generated file.

The home screen widget ("Agent glance"): the owner's agent as a card, one live number, and a tap that opens the app on that agent. Product docs: docs/native-widgets.md.

three.ws Drive (drive*): the agent in the car, on Android Auto. The car screen is four rows rendered by Android Auto's template host; the conversation runs in a web view inside a foreground service, because during a drive the phone screen belongs to Android Auto and a background process may not hold the microphone. Docs: ../docs/ANDROID-AUTO.md and docs/carplay.md.

File Role
app/src/main/java/ws/three/app/glance/GlanceWidget.java The AppWidgetProvider: picks the card size from the cells, paints the cached bitmap, wires the taps, schedules the refresh.
.../GlanceRefreshWorker.java The WorkManager job: fetches GET /api/glance/mine?format=png per size in use, writes each bitmap atomically, repaints. Failure keeps the last card.
.../GlanceApi.java The one HTTP call, with the widget token as a bearer and the card's facts read from response headers.
.../GlanceStore.java Token, cached bitmaps, tap target and timestamp.
.../GlanceLinkActivity.java Handles threews://glance/link?token=… from the /glance page, stores the token, offers to pin the widget.
app/src/main/res/layout/glance_widget_{small,wide}.xml RemoteViews layouts for 2x2 and 4x2 / 4x3.
app/src/main/res/xml/glance_widget_info.xml Widget metadata: sizes, resize modes, no AppWidget alarm (updatePeriodMillis=0, WorkManager refreshes).
app/src/main/res/values/glance.xml, res/drawable/glance_*.xml Strings, colors, the rounded card background, the action chip.
.../drive/DriveCarAppService.java The CarAppService: declares the IOT category, pins the production host allowlist.
.../drive/DriveSession.java One connection to the car; opens the screen.
.../drive/DriveScreen.java The four controls as a ListTemplate, and the microphone-permission screen that precedes them.
.../drive/DriveLink.java The channel to the page: state in, presses out, everything marshalled to the main looper.
.../drive/DriveWebService.java The typed foreground service hosting the web view that runs /drive?surface=androidauto.
app/src/main/res/xml/drive_automotive_app_desc.xml <uses name="template" />: how Android Auto discovers the car app at all.
app/src/main/res/values/drive.xml Every string on the car screen and in the session notification.
AndroidManifest.permissions.xml Spliced after the <manifest> tag: INTERNET, ACCESS_NETWORK_STATE, RECORD_AUDIO, the typed foreground-service permissions, POST_NOTIFICATIONS.
AndroidManifest.application.xml Spliced before </application>: the widget receiver, the link activity, the car app service, and the drive web service.
build.gradle.fragment Appended to app/build.gradle: androidx.work:work-runtime, androidx.car.app:app, androidx.car.app:app-projected.

Rules

  • Every file name and resource id starts with its feature (glance, drive), so the overlay can never collide with a Bubblewrap-generated file. apply-overlay.mjs refuses to overwrite anything it does not own.
  • Both manifest splices and the gradle fragment are fenced and REPLACED on re-apply, not skipped when a marker is present. Editing a fragment therefore works the obvious way; a presence check would have left the old block in place and silently dropped the new declaration.
  • Java 8 source level (that is what the generated project compiles at). No Kotlin, no Compose.
  • The widget never renders WebGL or HTML. It shows the PNG the server renders and nothing else.
  • Applying the overlay by hand, for a debug build:
cd solana-mobile/build
npx --no-install @bubblewrap/cli update --skipVersionUpgrade
node ../scripts/apply-overlay.mjs --project . --overlay ../android-overlay
JAVA_HOME=~/.bubblewrap/jdk/jdk-17.0.20.1+1 ./gradlew assembleDebug