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
feat(android): put the agent on the home screen with an Agent glance app widget (1.1.0)
nirholas7a73da13ab98
diff --git a/docs/seeker-app.md b/docs/seeker-app.mdindex 26e7c0f32..37dec174d 100644--- a/docs/seeker-app.md+++ b/docs/seeker-app.md@@ -41,13 +41,20 @@ The handoff is one-shot and expires after ten minutes, so a stale share can neveThe APK can be exercised in a stock Android emulator (Pixel 7, Android 14 image). Everything except the Seed Vault itself works there: install, launch, shortcuts, the share intent, deep-link verification state. The recipe is in [solana-mobile/README.md](../solana-mobile/README.md#emulator-qa). For the wallet flows, `tests/solana-mobile-*.test.js` drive the MWA wrapper against a fake transport, and the Solana Mobile reference wallet can be sideloaded into the emulator for an end-to-end sign-in.-## What is next: a home screen widget--The app currently earns its place on the home screen only while you are using it. The next-piece is an Android app widget: your agent, one live number about it, and a tap that lands you-back in the right screen, refreshed by the system without opening the app. The shell for it-already exists (this APK) and so does the image source (`POST /api/render/avatar-clip`, the-same headless renderer behind the OG cards), because no Android widget can run WebGL. Windows-11 follows through the installed PWA's manifest, then macOS and iOS through a shared WidgetKit-extension. The scoped work order is [prompts/roadmap/native-widgets.md](../prompts/roadmap/native-widgets.md),-and it is Phase 5 of the [roadmap](../README.md#roadmap).+## The home screen widget++Version 1.1 adds **Agent glance**, an Android app widget: your agent's avatar, its name, and how+many moves it made today, refreshed by the system about every 30 minutes without opening the app,+with a tap that opens the agent inside the app. Link the phone from [three.ws/glance](https://three.ws/glance)+(one tap, signed in), then add the widget from the launcher's picker. It keeps the last card it+downloaded when the phone is offline and can be revoked from the same page. Everything about it,+including every state it can be in and how it authenticates, is in+[native-widgets.md](native-widgets.md#android); the native sources are in+[solana-mobile/android-overlay/](../solana-mobile/android-overlay/README.md).++## What is next++Windows 11 already gets the same card through the installed PWA's manifest. macOS and iOS follow+through a shared WidgetKit extension against the same endpoint and widget token; that is Phase 5+of the [roadmap](../README.md#roadmap) and the scoped work order is+[prompts/roadmap/native-widgets.md](../prompts/roadmap/native-widgets.md).diff --git a/solana-mobile/README.md b/solana-mobile/README.mdindex 26e525500..b499c0d70 100644--- a/solana-mobile/README.md+++ b/solana-mobile/README.md@@ -2,6 +2,8 @@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](../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 submitted to the Solana dApp Store on 2026-08-28 and in review** (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](../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/`](publish-play/README.md)). 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.@@ -131,6 +133,36 @@ adb exec-out screencap -p > shot.pngUntil 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:++```bash+# 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 "<agent name>, <metric>" and the footer `TextView` (`ws.three.app:id/glance_updated`) carries the refresh time.+## What still needs a physical SeekerListing 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.diff --git a/solana-mobile/android-overlay/AndroidManifest.application.xml b/solana-mobile/android-overlay/AndroidManifest.application.xmlnew file mode 100644index 000000000..f5f80bad2--- /dev/null+++ b/solana-mobile/android-overlay/AndroidManifest.application.xml@@ -0,0 +1,26 @@+ <!-- glance widget (solana-mobile/android-overlay) -->+ <receiver+ android:name=".glance.GlanceWidget"+ android:exported="true"+ android:label="@string/glance_widget_label">+ <intent-filter>+ <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />+ </intent-filter>+ <meta-data+ android:name="android.appwidget.provider"+ android:resource="@xml/glance_widget_info" />+ </receiver>++ <activity+ android:name=".glance.GlanceLinkActivity"+ android:exported="true"+ android:excludeFromRecents="true"+ android:noHistory="true"+ android:theme="@android:style/Theme.Translucent.NoTitleBar">+ <intent-filter>+ <action android:name="android.intent.action.VIEW" />+ <category android:name="android.intent.category.DEFAULT" />+ <category android:name="android.intent.category.BROWSABLE" />+ <data android:scheme="threews" android:host="glance" />+ </intent-filter>+ </activity>diff --git a/solana-mobile/android-overlay/AndroidManifest.permissions.xml b/solana-mobile/android-overlay/AndroidManifest.permissions.xmlnew file mode 100644index 000000000..1bd4dd41f--- /dev/null+++ b/solana-mobile/android-overlay/AndroidManifest.permissions.xml@@ -0,0 +1,4 @@+ <!-- glance widget (solana-mobile/android-overlay): fetched by WorkManager+ from an OS process, so the app itself declares the network. -->+ <uses-permission android:name="android.permission.INTERNET"/>+ <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>diff --git a/solana-mobile/android-overlay/README.md b/solana-mobile/android-overlay/README.mdnew file mode 100644index 000000000..fdce231ef--- /dev/null+++ b/solana-mobile/android-overlay/README.md@@ -0,0 +1,42 @@+# 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`](../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`](../scripts/build-apk.sh)+runs [`../scripts/apply-overlay.mjs`](../scripts/apply-overlay.mjs) in exactly that slot, and+fails the build if this directory is missing.++## What is in it++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`](../../docs/native-widgets.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. |+| `AndroidManifest.permissions.xml` | Spliced after the `<manifest>` tag: `INTERNET`, `ACCESS_NETWORK_STATE`. |+| `AndroidManifest.application.xml` | Spliced before `</application>`: the widget receiver and the link activity. |+| `build.gradle.fragment` | Appended to `app/build.gradle`: `androidx.work:work-runtime`. |++## Rules++- Every file name and resource id starts with `glance`, so the overlay can never collide with a+ Bubblewrap-generated file. `apply-overlay.mjs` refuses to overwrite anything it does not own.+- 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:++```bash+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+```diff --git a/solana-mobile/android-overlay/app/src/debug/AndroidManifest.xml b/solana-mobile/android-overlay/app/src/debug/AndroidManifest.xmlnew file mode 100644index 000000000..3d5a845c7--- /dev/null+++ b/solana-mobile/android-overlay/app/src/debug/AndroidManifest.xml@@ -0,0 +1,11 @@+<?xml version="1.0" encoding="utf-8"?>+<!-- Debug variant only (never merged into the release APK): lets the emulator+ recipe in solana-mobile/README.md point the glance widget at a local+ server over plain http (threews://glance/link?token=...&origin=http://10.0.2.2:8080).+ GlanceLinkActivity honours that origin only when the build is debuggable. -->+<manifest xmlns:android="http://schemas.android.com/apk/res/android"+ xmlns:tools="http://schemas.android.com/tools">+ <application+ android:usesCleartextTraffic="true"+ tools:replace="android:usesCleartextTraffic" />+</manifest>diff --git a/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceApi.java b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceApi.javanew file mode 100644index 000000000..ffa534518--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceApi.java@@ -0,0 +1,109 @@+package ws.three.app.glance;++import android.content.Context;+import android.content.pm.PackageInfo;+import android.content.pm.PackageManager;+import android.net.Uri;++import java.io.ByteArrayOutputStream;+import java.io.IOException;+import java.io.InputStream;+import java.net.HttpURLConnection;+import java.net.URL;++/**+ * One request: GET /api/glance/mine?format=png for a size, with the widget+ * token as a bearer. The response is the bitmap plus the card's facts in+ * headers (state, tap target, name, metric), so a refresh is a single+ * round-trip per size and never needs a JSON parser.+ */+final class GlanceApi {+ static final class Card {+ final byte[] png;+ final String state;+ final String url;+ final String name;+ final String metric;++ Card(byte[] png, String state, String url, String name, String metric) {+ this.png = png;+ this.state = state;+ this.url = url;+ this.name = name;+ this.metric = metric;+ }+ }++ private static final int CONNECT_TIMEOUT_MS = 10_000;+ private static final int READ_TIMEOUT_MS = 20_000;+ // A 3x large card is under 400 KB; anything past this is not a card.+ private static final int MAX_BYTES = 4 * 1024 * 1024;++ private GlanceApi() {}++ static Card fetch(Context context, GlanceStore store, String size, int scale) throws IOException {+ Uri uri = Uri.parse(store.origin()).buildUpon()+ .path("/api/glance/mine")+ .appendQueryParameter("format", "png")+ .appendQueryParameter("size", size)+ .appendQueryParameter("theme", "dark")+ .appendQueryParameter("scale", String.valueOf(scale))+ .build();++ HttpURLConnection conn = (HttpURLConnection) new URL(uri.toString()).openConnection();+ try {+ conn.setConnectTimeout(CONNECT_TIMEOUT_MS);+ conn.setReadTimeout(READ_TIMEOUT_MS);+ conn.setRequestProperty("Accept", "image/png");+ conn.setRequestProperty("User-Agent", userAgent(context));+ String token = store.token();+ if (token != null) conn.setRequestProperty("Authorization", "Bearer " + token);++ int status = conn.getResponseCode();+ String type = conn.getContentType();+ if (status != 200 || type == null || !type.startsWith("image/png")) {+ throw new IOException("glance card answered " + status + " " + type);+ }++ byte[] png = readAll(conn.getInputStream());+ return new Card(+ png,+ header(conn, "x-glance-state", GlanceStore.STATE_AGENT),+ header(conn, "x-glance-url", store.origin() + "/glance"),+ header(conn, "x-glance-name", ""),+ header(conn, "x-glance-metric", ""));+ } finally {+ conn.disconnect();+ }+ }++ private static String header(HttpURLConnection conn, String name, String fallback) {+ String value = conn.getHeaderField(name);+ return value == null || value.isEmpty() ? fallback : value;+ }++ private static byte[] readAll(InputStream in) throws IOException {+ ByteArrayOutputStream out = new ByteArrayOutputStream(64 * 1024);+ byte[] buf = new byte[16 * 1024];+ int total = 0;+ int n;+ while ((n = in.read(buf)) > 0) {+ total += n;+ if (total > MAX_BYTES) throw new IOException("glance card too large");+ out.write(buf, 0, n);+ }+ if (total == 0) throw new IOException("glance card was empty");+ return out.toByteArray();+ }++ private static String userAgent(Context context) {+ String version = "unknown";+ try {+ PackageInfo info = context.getPackageManager().getPackageInfo(context.getPackageName(), 0);+ if (info.versionName != null) version = info.versionName;+ } catch (PackageManager.NameNotFoundException ignored) {+ // Our own package is always installed; the fallback only guards the API contract.+ }+ return "three.ws-android-widget/" + version;+ }+}diff --git a/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceLinkActivity.java b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceLinkActivity.javanew file mode 100644index 000000000..14ef68552--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceLinkActivity.java@@ -0,0 +1,80 @@+package ws.three.app.glance;++import android.app.Activity;+import android.appwidget.AppWidgetManager;+import android.content.ComponentName;+import android.content.Intent;+import android.content.pm.ApplicationInfo;+import android.net.Uri;+import android.os.Build;+import android.os.Bundle;+import android.widget.Toast;++import ws.three.app.R;++/**+ * The hand-off from the web to the widget. /glance mints a widget token and+ * opens+ *+ * intent://glance/link?token=glw_…#Intent;scheme=threews;package=ws.three.app;end+ *+ * which Chrome routes here. The token is stored, a refresh is queued, and if+ * no widget is on the home screen yet the launcher is asked to offer one.+ * threews://glance/unlink drops the token; the server-side revoke on /glance+ * does the same on the widget's next refresh.+ *+ * Nothing is shown but a toast: the activity is translucent and finishes at+ * once, so the person stays where they were.+ */+public final class GlanceLinkActivity extends Activity {+ @Override+ protected void onCreate(Bundle savedInstanceState) {+ super.onCreate(savedInstanceState);+ handle(getIntent());+ finish();+ }++ private void handle(Intent intent) {+ Uri data = intent == null ? null : intent.getData();+ if (data == null || !"threews".equals(data.getScheme()) || !"glance".equals(data.getHost())) return;++ GlanceStore store = new GlanceStore(this);+ String path = data.getPath() == null ? "" : data.getPath();++ if ("/unlink".equals(path)) {+ store.unlink();+ GlanceWidget.updateAll(this);+ Toast.makeText(this, R.string.glance_toast_unlinked, Toast.LENGTH_SHORT).show();+ return;+ }+ if (!"/link".equals(path)) return;++ String token = data.getQueryParameter("token");+ if (!store.link(token)) {+ Toast.makeText(this, R.string.glance_toast_bad_link, Toast.LENGTH_LONG).show();+ return;+ }++ // The origin override is for the emulator recipe (a debug build pointed+ // at a local server). A release build ignores it, so a crafted link+ // can never redirect a shipped widget's token to another host.+ String origin = data.getQueryParameter("origin");+ boolean debuggable = (getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;+ store.setOrigin(debuggable && origin != null && origin.startsWith("http") ? origin : GlanceStore.DEFAULT_ORIGIN);++ GlanceWidget.updateAll(this);+ GlanceWidget.refreshNow(this);+ Toast.makeText(this, R.string.glance_toast_linked, Toast.LENGTH_SHORT).show();+ offerPin();+ }++ /** Ask the launcher to place the widget when none is on the home screen yet. */+ private void offerPin() {+ if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return;+ AppWidgetManager manager = AppWidgetManager.getInstance(this);+ ComponentName provider = new ComponentName(this, GlanceWidget.class);+ if (manager.getAppWidgetIds(provider).length > 0) return;+ if (!manager.isRequestPinAppWidgetSupported()) return;+ manager.requestPinAppWidget(provider, null, null);+ }+}diff --git a/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceRefreshWorker.java b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceRefreshWorker.javanew file mode 100644index 000000000..0556823f3--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceRefreshWorker.java@@ -0,0 +1,103 @@+package ws.three.app.glance;++import android.appwidget.AppWidgetManager;+import android.content.ComponentName;+import android.content.Context;+import android.os.Bundle;+import android.util.Log;++import androidx.annotation.NonNull;+import androidx.work.Worker;+import androidx.work.WorkerParameters;++import java.io.File;+import java.io.FileOutputStream;+import java.io.IOException;+import java.util.LinkedHashSet;+import java.util.Set;++/**+ * The refresh. WorkManager runs it every 30 minutes while a widget is placed+ * (battery-aware, coalesced with the system's other periodic work) and once+ * on demand after a link or a tap on "refresh". It fetches one bitmap per+ * size currently on screen, writes each one atomically, and then repaints+ * every widget instance.+ *+ * Failure is the designed path: no network, a timeout, a 5xx all return+ * retry, the cached bitmap stays on screen, and the footer says the card is+ * from earlier. Nothing here ever clears a card it cannot replace.+ */+public final class GlanceRefreshWorker extends Worker {+ private static final String TAG = "GlanceWidget";++ public GlanceRefreshWorker(@NonNull Context context, @NonNull WorkerParameters params) {+ super(context, params);+ }++ @NonNull+ @Override+ public Result doWork() {+ Context context = getApplicationContext();+ GlanceStore store = new GlanceStore(context);+ AppWidgetManager manager = AppWidgetManager.getInstance(context);+ int[] ids = manager.getAppWidgetIds(new ComponentName(context, GlanceWidget.class));++ if (ids.length == 0) {+ GlanceWidget.cancelPeriodic(context);+ return Result.success();+ }+ if (!store.linked()) {+ GlanceWidget.updateAll(context, manager, ids);+ return Result.success();+ }++ Set<String> sizes = new LinkedHashSet<>();+ for (int id : ids) {+ Bundle options = manager.getAppWidgetOptions(id);+ sizes.add(GlanceWidget.sizeFor(options));+ }++ int scale = GlanceWidget.scaleFor(context);+ boolean anyFailed = false;+ for (String size : sizes) {+ try {+ GlanceApi.Card card = GlanceApi.fetch(context, store, size, scale);+ writeAtomically(store, size, card.png);+ if (GlanceStore.STATE_UNLINKED.equals(card.state)) {+ // The owner revoked this widget from /glance. Drop the token so+ // the tap goes to the link flow instead of retrying a dead one.+ store.unlink();+ store.recordCard(card.state, card.url, card.name, card.metric, System.currentTimeMillis());+ GlanceWidget.updateAll(context, manager, ids);+ return Result.success();+ }+ store.recordCard(card.state, card.url, card.name, card.metric, System.currentTimeMillis());+ } catch (IOException e) {+ // Logged, never surfaced: the slot keeps its last card, and the+ // footer says it is from earlier. logcat is where a tester looks.+ Log.w(TAG, "glance refresh failed for size " + size + ": " + e.getMessage());+ anyFailed = true;+ store.recordFailure(System.currentTimeMillis());+ }+ }++ GlanceWidget.updateAll(context, manager, ids);+ return anyFailed ? Result.retry() : Result.success();+ }++ private static void writeAtomically(GlanceStore store, String size, byte[] png) throws IOException {+ File dir = store.dir();+ if (!dir.isDirectory() && !dir.mkdirs()) throw new IOException("cannot create " + dir);+ File tmp = store.bitmapTempFile(size);+ File target = store.bitmapFile(size);+ try (FileOutputStream out = new FileOutputStream(tmp)) {+ out.write(png);+ out.getFD().sync();+ }+ if (!tmp.renameTo(target)) {+ //noinspection ResultOfMethodCallIgnored+ tmp.delete();+ throw new IOException("cannot replace " + target);+ }+ }+}diff --git a/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceStore.java b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceStore.javanew file mode 100644index 000000000..528a9a2a4--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceStore.java@@ -0,0 +1,157 @@+package ws.three.app.glance;++import android.content.Context;+import android.content.SharedPreferences;++import java.io.File;+import java.util.regex.Pattern;++/**+ * Everything the widget remembers between refreshes: the widget token the+ * owner linked from /glance, and the last card the server handed back (the+ * bitmap per size on disk, its tap target and timestamp in preferences).+ *+ * The bitmap is the source of truth for what is on screen. A refresh that+ * fails leaves it untouched, so an offline phone keeps showing the last real+ * card with its own timestamp rather than a spinner or a broken image.+ */+public final class GlanceStore {+ private static final String PREFS = "glance_widget";+ private static final String KEY_TOKEN = "token";+ private static final String KEY_ORIGIN = "origin";+ private static final String KEY_STATE = "state";+ private static final String KEY_URL = "url";+ private static final String KEY_NAME = "name";+ private static final String KEY_METRIC = "metric";+ private static final String KEY_UPDATED_AT = "updated_at";+ private static final String KEY_LAST_ERROR_AT = "last_error_at";++ public static final String DEFAULT_ORIGIN = "https://three.ws";+ public static final String STATE_AGENT = "agent";+ public static final String STATE_UNLINKED = "unlinked";+ public static final String STATE_NO_AGENT = "no-agent";+ public static final String STATE_SIGNED_OUT = "signed-out";++ /** The server's token shape; anything else is refused before it is stored. */+ private static final Pattern TOKEN_SHAPE = Pattern.compile("^glw_[A-Za-z0-9_-]{32}$");++ private final SharedPreferences prefs;+ private final File dir;++ public GlanceStore(Context context) {+ Context app = context.getApplicationContext();+ prefs = app.getSharedPreferences(PREFS, Context.MODE_PRIVATE);+ dir = new File(app.getFilesDir(), "glance");+ }++ public static boolean isToken(String value) {+ return value != null && TOKEN_SHAPE.matcher(value).matches();+ }++ public String token() {+ return prefs.getString(KEY_TOKEN, null);+ }++ public boolean linked() {+ return isToken(token());+ }++ public boolean link(String token) {+ if (!isToken(token)) return false;+ prefs.edit()+ .putString(KEY_TOKEN, token)+ .remove(KEY_STATE)+ .remove(KEY_URL)+ .remove(KEY_NAME)+ .remove(KEY_METRIC)+ .remove(KEY_UPDATED_AT)+ .remove(KEY_LAST_ERROR_AT)+ .apply();+ clearBitmaps();+ return true;+ }++ public void unlink() {+ prefs.edit().clear().apply();+ clearBitmaps();+ }++ /**+ * The origin the card is fetched from. Fixed to three.ws in the shipped+ * app: the setter exists for the emulator recipe, which points a debug+ * build at a local server, and it only takes effect in a debuggable build+ * (see GlanceLinkActivity).+ */+ public String origin() {+ return prefs.getString(KEY_ORIGIN, DEFAULT_ORIGIN);+ }++ public void setOrigin(String origin) {+ prefs.edit().putString(KEY_ORIGIN, origin).apply();+ }++ public File bitmapFile(String size) {+ return new File(dir, size + ".png");+ }++ public File bitmapTempFile(String size) {+ return new File(dir, size + ".png.part");+ }++ public File dir() {+ return dir;+ }++ public void recordCard(String state, String url, String name, String metric, long updatedAt) {+ prefs.edit()+ .putString(KEY_STATE, state)+ .putString(KEY_URL, url)+ .putString(KEY_NAME, name)+ .putString(KEY_METRIC, metric)+ .putLong(KEY_UPDATED_AT, updatedAt)+ .remove(KEY_LAST_ERROR_AT)+ .apply();+ }++ public void recordFailure(long at) {+ prefs.edit().putLong(KEY_LAST_ERROR_AT, at).apply();+ }++ public String state() {+ return prefs.getString(KEY_STATE, null);+ }++ public String url() {+ return prefs.getString(KEY_URL, null);+ }++ public String name() {+ return prefs.getString(KEY_NAME, null);+ }++ public String metric() {+ return prefs.getString(KEY_METRIC, null);+ }++ public long updatedAt() {+ return prefs.getLong(KEY_UPDATED_AT, 0L);+ }++ public long lastErrorAt() {+ return prefs.getLong(KEY_LAST_ERROR_AT, 0L);+ }++ /** True when the last refresh failed after a card had already been shown. */+ public boolean stale() {+ return lastErrorAt() > updatedAt();+ }++ private void clearBitmaps() {+ File[] files = dir.listFiles();+ if (files == null) return;+ for (File f : files) {+ //noinspection ResultOfMethodCallIgnored+ f.delete();+ }+ }+}diff --git a/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceWidget.java b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceWidget.javanew file mode 100644index 000000000..dd194e220--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/java/ws/three/app/glance/GlanceWidget.java@@ -0,0 +1,265 @@+package ws.three.app.glance;++import android.app.PendingIntent;+import android.appwidget.AppWidgetManager;+import android.appwidget.AppWidgetProvider;+import android.content.ComponentName;+import android.content.Context;+import android.content.Intent;+import android.graphics.Bitmap;+import android.graphics.BitmapFactory;+import android.net.Uri;+import android.os.Build;+import android.os.Bundle;+import android.text.format.DateFormat;+import android.view.View;+import android.widget.RemoteViews;++import androidx.work.Constraints;+import androidx.work.ExistingPeriodicWorkPolicy;+import androidx.work.ExistingWorkPolicy;+import androidx.work.NetworkType;+import androidx.work.OneTimeWorkRequest;+import androidx.work.PeriodicWorkRequest;+import androidx.work.WorkManager;++import java.io.File;+import java.util.Date;+import java.util.concurrent.TimeUnit;++import ws.three.app.R;++/**+ * The three.ws home screen widget: the owner's agent as a glance card, one+ * live number, and a tap that lands back in the app on that agent.+ *+ * The card itself is a bitmap the server renders (GET /api/glance/mine+ * ?format=png), because no Android widget can run WebGL and RemoteViews can+ * draw a bitmap on any launcher. This class only decides which size to ask+ * for, paints what is cached, and wires the taps.+ */+public final class GlanceWidget extends AppWidgetProvider {+ public static final String ACTION_REFRESH = "ws.three.app.glance.REFRESH";++ static final String SIZE_SMALL = "small";+ static final String SIZE_MEDIUM = "medium";+ static final String SIZE_LARGE = "large";++ private static final String PERIODIC_WORK = "glance-refresh-periodic";+ private static final String ONCE_WORK = "glance-refresh-now";+ // WorkManager's floor is 15 minutes; 30 keeps the number honest for a card+ // whose metric is "moves today" while staying inside the battery budget+ // the OS grants a background app.+ private static final long PERIOD_MINUTES = 30;++ private static final String UTM = "utm_source=android_widget";++ @Override+ public void onUpdate(Context context, AppWidgetManager manager, int[] ids) {+ updateAll(context, manager, ids);+ schedulePeriodic(context);+ refreshNow(context);+ }++ @Override+ public void onAppWidgetOptionsChanged(Context context, AppWidgetManager manager, int id, Bundle options) {+ manager.updateAppWidget(id, buildViews(context, manager, id));+ // A resize may need a size that has never been fetched.+ refreshNow(context);+ }++ @Override+ public void onEnabled(Context context) {+ schedulePeriodic(context);+ }++ @Override+ public void onDisabled(Context context) {+ cancelPeriodic(context);+ }++ @Override+ public void onReceive(Context context, Intent intent) {+ super.onReceive(context, intent);+ if (ACTION_REFRESH.equals(intent.getAction())) refreshNow(context);+ }++ // ── scheduling ─────────────────────────────────────────────────────────++ static void schedulePeriodic(Context context) {+ Constraints constraints = new Constraints.Builder()+ .setRequiredNetworkType(NetworkType.CONNECTED)+ .build();+ PeriodicWorkRequest request = new PeriodicWorkRequest.Builder(+ GlanceRefreshWorker.class, PERIOD_MINUTES, TimeUnit.MINUTES)+ .setConstraints(constraints)+ .build();+ WorkManager.getInstance(context).enqueueUniquePeriodicWork(+ PERIODIC_WORK, ExistingPeriodicWorkPolicy.KEEP, request);+ }++ static void cancelPeriodic(Context context) {+ WorkManager.getInstance(context).cancelUniqueWork(PERIODIC_WORK);+ }++ public static void refreshNow(Context context) {+ // No network constraint on purpose: a tap on "refresh" while offline+ // should answer at once with the "(offline)" footer, not sit silently+ // until a connection appears. The periodic job keeps the constraint.+ OneTimeWorkRequest request = new OneTimeWorkRequest.Builder(GlanceRefreshWorker.class).build();+ // REPLACE, not KEEP: a tap on "refresh" while an earlier attempt is+ // sitting in retry backoff must run now, not wait out the backoff.+ WorkManager.getInstance(context).enqueueUniqueWork(ONCE_WORK, ExistingWorkPolicy.REPLACE, request);+ }++ // ── painting ───────────────────────────────────────────────────────────++ public static void updateAll(Context context) {+ AppWidgetManager manager = AppWidgetManager.getInstance(context);+ int[] ids = manager.getAppWidgetIds(new ComponentName(context, GlanceWidget.class));+ updateAll(context, manager, ids);+ }++ static void updateAll(Context context, AppWidgetManager manager, int[] ids) {+ for (int id : ids) manager.updateAppWidget(id, buildViews(context, manager, id));+ }++ /** Which server size fits the cells this instance was given. */+ static String sizeFor(Bundle options) {+ if (options == null) return SIZE_MEDIUM;+ int minWidth = options.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_WIDTH, 0);+ int minHeight = options.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT, 0);+ if (minHeight >= 190) return SIZE_LARGE;+ if (minWidth < 200) return SIZE_SMALL;+ return SIZE_MEDIUM;+ }++ /** The bitmap density to request: 3x on xxhdpi and denser, 2x elsewhere. */+ static int scaleFor(Context context) {+ float density = context.getResources().getDisplayMetrics().density;+ return density >= 2.5f ? 3 : 2;+ }++ static RemoteViews buildViews(Context context, AppWidgetManager manager, int id) {+ GlanceStore store = new GlanceStore(context);+ Bundle options = manager.getAppWidgetOptions(id);+ String size = sizeFor(options);+ boolean wide = !SIZE_SMALL.equals(size);+ RemoteViews views = new RemoteViews(context.getPackageName(),+ wide ? R.layout.glance_widget_wide : R.layout.glance_widget_small);++ Bitmap bitmap = store.linked() || store.state() != null ? loadBitmap(context, store, size, options) : null;++ if (bitmap != null) {+ views.setImageViewBitmap(R.id.glance_card, bitmap);+ views.setViewVisibility(R.id.glance_card, View.VISIBLE);+ views.setViewVisibility(R.id.glance_notice, View.GONE);+ views.setContentDescription(R.id.glance_card, describe(store));+ } else {+ views.setViewVisibility(R.id.glance_card, View.GONE);+ views.setViewVisibility(R.id.glance_notice, View.VISIBLE);+ if (store.linked()) {+ views.setTextViewText(R.id.glance_notice_title, context.getString(R.string.glance_loading_title));+ views.setTextViewText(R.id.glance_notice_body, context.getString(R.string.glance_loading_body));+ } else {+ views.setTextViewText(R.id.glance_notice_title, context.getString(R.string.glance_link_title));+ views.setTextViewText(R.id.glance_notice_body, context.getString(R.string.glance_link_body));+ }+ }++ if (wide) {+ views.setTextViewText(R.id.glance_updated, footer(context, store));+ views.setOnClickPendingIntent(R.id.glance_action_create,+ open(context, id, 1, "https://three.ws/create?" + UTM));+ views.setOnClickPendingIntent(R.id.glance_action_agents,+ open(context, id, 2, "https://three.ws/my-agents?" + UTM));+ views.setOnClickPendingIntent(R.id.glance_updated, refreshIntent(context, id));+ views.setViewVisibility(R.id.glance_actions, SIZE_LARGE.equals(size) ? View.VISIBLE : View.GONE);+ }++ views.setOnClickPendingIntent(R.id.glance_root, open(context, id, 0, tapTarget(store)));+ return views;+ }++ private static String tapTarget(GlanceStore store) {+ if (!store.linked() && !GlanceStore.STATE_UNLINKED.equals(store.state())) {+ return "https://three.ws/glance?link=android&" + UTM;+ }+ String url = store.url();+ if (url == null || !url.startsWith("https://")) url = "https://three.ws/glance";+ return url + (url.contains("?") ? "&" : "?") + UTM;+ }++ private static String describe(GlanceStore store) {+ String name = store.name();+ String metric = store.metric();+ if (name == null || name.isEmpty()) return "three.ws agent card";+ return metric == null || metric.isEmpty() ? name : name + ", " + metric;+ }++ private static CharSequence footer(Context context, GlanceStore store) {+ long at = store.updatedAt();+ if (at <= 0) return context.getString(R.string.glance_footer_never);+ String time = DateFormat.getTimeFormat(context).format(new Date(at));+ return context.getString(store.stale() ? R.string.glance_footer_stale : R.string.glance_footer_updated, time);+ }++ /**+ * Decode the cached PNG at no more than the pixels this instance can show.+ * RemoteViews ships the bitmap across Binder, so a 3x large card is+ * downsampled for a 2x2 slot instead of being sent at full size.+ */+ private static Bitmap loadBitmap(Context context, GlanceStore store, String size, Bundle options) {+ File file = store.bitmapFile(size);+ if (!file.isFile()) {+ // A size that has not been fetched yet borrows the nearest cached one+ // rather than flashing the notice layout during a resize.+ for (String other : new String[] {SIZE_MEDIUM, SIZE_LARGE, SIZE_SMALL}) {+ File candidate = store.bitmapFile(other);+ if (candidate.isFile()) {+ file = candidate;+ break;+ }+ }+ if (!file.isFile()) return null;+ }++ BitmapFactory.Options bounds = new BitmapFactory.Options();+ bounds.inJustDecodeBounds = true;+ BitmapFactory.decodeFile(file.getPath(), bounds);+ if (bounds.outWidth <= 0) return null;++ float density = context.getResources().getDisplayMetrics().density;+ int maxWidthDp = options == null ? 0 : options.getInt(AppWidgetManager.OPTION_APPWIDGET_MAX_WIDTH, 0);+ int targetPx = maxWidthDp > 0 ? Math.round(maxWidthDp * density) : bounds.outWidth;+ int sample = 1;+ while (bounds.outWidth / (sample * 2) >= targetPx) sample *= 2;++ BitmapFactory.Options decode = new BitmapFactory.Options();+ decode.inSampleSize = sample;+ decode.inPreferredConfig = Bitmap.Config.ARGB_8888;+ return BitmapFactory.decodeFile(file.getPath(), decode);+ }++ // ── taps ───────────────────────────────────────────────────────────────++ private static PendingIntent open(Context context, int widgetId, int slot, String url) {+ Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));+ // Explicit to our own package: the https filter on LauncherActivity+ // takes it, so the tap lands inside the app, never in a browser tab.+ intent.setPackage(context.getPackageName());+ intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);+ return PendingIntent.getActivity(context, widgetId * 8 + slot, intent, flags());+ }++ private static PendingIntent refreshIntent(Context context, int widgetId) {+ Intent intent = new Intent(context, GlanceWidget.class).setAction(ACTION_REFRESH);+ return PendingIntent.getBroadcast(context, widgetId * 8 + 3, intent, flags());+ }++ private static int flags() {+ int flags = PendingIntent.FLAG_UPDATE_CURRENT;+ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) flags |= PendingIntent.FLAG_IMMUTABLE;+ return flags;+ }+}diff --git a/solana-mobile/android-overlay/app/src/main/res/drawable/glance_action_bg.xml b/solana-mobile/android-overlay/app/src/main/res/drawable/glance_action_bg.xmlnew file mode 100644index 000000000..a04391b13--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/drawable/glance_action_bg.xml@@ -0,0 +1,6 @@+<?xml version="1.0" encoding="utf-8"?>+<shape xmlns:android="http://schemas.android.com/apk/res/android" android:shape="rectangle">+ <solid android:color="@color/glance_panel" />+ <stroke android:width="1dp" android:color="@color/glance_line" />+ <corners android:radius="12dp" />+</shape>diff --git a/solana-mobile/android-overlay/app/src/main/res/drawable/glance_widget_bg.xml b/solana-mobile/android-overlay/app/src/main/res/drawable/glance_widget_bg.xmlnew file mode 100644index 000000000..5984d6fd4--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/drawable/glance_widget_bg.xml@@ -0,0 +1,6 @@+<?xml version="1.0" encoding="utf-8"?>+<shape xmlns:android="http://schemas.android.com/apk/res/android" android:shape="rectangle">+ <solid android:color="@color/glance_bg" />+ <stroke android:width="1dp" android:color="@color/glance_line" />+ <corners android:radius="@dimen/glance_radius" />+</shape>diff --git a/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_small.xml b/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_small.xmlnew file mode 100644index 000000000..629d54da8--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_small.xml@@ -0,0 +1,45 @@+<?xml version="1.0" encoding="utf-8"?>+<!-- 2x2: the square card and nothing else. The tap is the whole widget. -->+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"+ android:id="@+id/glance_root"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:background="@drawable/glance_widget_bg"+ android:clipToOutline="true">++ <ImageView+ android:id="@+id/glance_card"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:scaleType="fitCenter"+ android:adjustViewBounds="true"+ android:contentDescription="@string/glance_widget_description" />++ <LinearLayout+ android:id="@+id/glance_notice"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:orientation="vertical"+ android:gravity="center_vertical"+ android:padding="@dimen/glance_pad"+ android:visibility="gone">++ <TextView+ android:id="@+id/glance_notice_title"+ android:layout_width="wrap_content"+ android:layout_height="wrap_content"+ android:text="@string/glance_link_title"+ android:textColor="@color/glance_text"+ android:textSize="16sp"+ android:textStyle="bold" />++ <TextView+ android:id="@+id/glance_notice_body"+ android:layout_width="wrap_content"+ android:layout_height="wrap_content"+ android:layout_marginTop="4dp"+ android:text="@string/glance_link_body"+ android:textColor="@color/glance_muted"+ android:textSize="12sp" />+ </LinearLayout>+</FrameLayout>diff --git a/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_wide.xml b/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_wide.xmlnew file mode 100644index 000000000..fcd7164c7--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/layout/glance_widget_wide.xml@@ -0,0 +1,93 @@+<?xml version="1.0" encoding="utf-8"?>+<!-- 4x2 and larger: the card bitmap, a footer with the refresh time, and on+ 4x3 two quick actions. Every view here is one RemoteViews supports. -->+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"+ android:id="@+id/glance_root"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:orientation="vertical"+ android:background="@drawable/glance_widget_bg"+ android:clipToOutline="true">++ <FrameLayout+ android:layout_width="match_parent"+ android:layout_height="0dp"+ android:layout_weight="1">++ <ImageView+ android:id="@+id/glance_card"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:scaleType="fitCenter"+ android:adjustViewBounds="true"+ android:contentDescription="@string/glance_widget_description" />++ <LinearLayout+ android:id="@+id/glance_notice"+ android:layout_width="match_parent"+ android:layout_height="match_parent"+ android:orientation="vertical"+ android:gravity="center_vertical"+ android:padding="@dimen/glance_pad"+ android:visibility="gone">++ <TextView+ android:id="@+id/glance_notice_title"+ android:layout_width="wrap_content"+ android:layout_height="wrap_content"+ android:text="@string/glance_link_title"+ android:textColor="@color/glance_text"+ android:textSize="18sp"+ android:textStyle="bold" />++ <TextView+ android:id="@+id/glance_notice_body"+ android:layout_width="wrap_content"+ android:layout_height="wrap_content"+ android:layout_marginTop="4dp"+ android:text="@string/glance_link_body"+ android:textColor="@color/glance_muted"+ android:textSize="13sp" />+ </LinearLayout>+ </FrameLayout>++ <LinearLayout+ android:layout_width="match_parent"+ android:layout_height="wrap_content"+ android:orientation="horizontal"+ android:gravity="center_vertical"+ android:paddingStart="@dimen/glance_pad"+ android:paddingEnd="@dimen/glance_pad"+ android:paddingBottom="8dp">++ <TextView+ android:id="@+id/glance_updated"+ android:layout_width="0dp"+ android:layout_height="wrap_content"+ android:layout_weight="1"+ android:text="@string/glance_footer_never"+ android:textColor="@color/glance_muted"+ android:textSize="11sp"+ android:singleLine="true"+ android:ellipsize="end" />++ <LinearLayout+ android:id="@+id/glance_actions"+ android:layout_width="wrap_content"+ android:layout_height="wrap_content"+ android:orientation="horizontal"+ android:visibility="gone">++ <TextView+ android:id="@+id/glance_action_create"+ style="@style/GlanceAction"+ android:text="@string/glance_action_create" />++ <TextView+ android:id="@+id/glance_action_agents"+ style="@style/GlanceAction"+ android:layout_marginStart="6dp"+ android:text="@string/glance_action_agents" />+ </LinearLayout>+ </LinearLayout>+</LinearLayout>diff --git a/solana-mobile/android-overlay/app/src/main/res/values/glance.xml b/solana-mobile/android-overlay/app/src/main/res/values/glance.xmlnew file mode 100644index 000000000..460cd8a0e--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/values/glance.xml@@ -0,0 +1,43 @@+<?xml version="1.0" encoding="utf-8"?>+<resources>+ <string name="glance_widget_label">Agent glance</string>+ <string name="glance_widget_description">Your three.ws agent, one live number, one tap back in.</string>++ <string name="glance_link_title">Add your agent</string>+ <string name="glance_link_body">Tap to link this widget to your three.ws account.</string>+ <string name="glance_loading_title">Fetching your agent</string>+ <string name="glance_loading_body">The card appears as soon as it is downloaded.</string>++ <string name="glance_footer_never">Not refreshed yet</string>+ <string name="glance_footer_updated">Updated %1$s. Tap to refresh.</string>+ <string name="glance_footer_stale">From %1$s (offline). Tap to retry.</string>++ <string name="glance_action_create">Create</string>+ <string name="glance_action_agents">My agents</string>++ <string name="glance_toast_linked">Widget linked to your three.ws account</string>+ <string name="glance_toast_unlinked">Widget unlinked</string>+ <string name="glance_toast_bad_link">That link is not a valid three.ws widget link</string>++ <color name="glance_bg">#0B0B16</color>+ <color name="glance_text">#F6F7FB</color>+ <color name="glance_muted">#A2A7BD</color>+ <color name="glance_line">#262842</color>+ <color name="glance_panel">#15162A</color>++ <dimen name="glance_pad">14dp</dimen>+ <dimen name="glance_radius">20dp</dimen>++ <style name="GlanceAction">+ <item name="android:layout_width">wrap_content</item>+ <item name="android:layout_height">wrap_content</item>+ <item name="android:background">@drawable/glance_action_bg</item>+ <item name="android:paddingStart">10dp</item>+ <item name="android:paddingEnd">10dp</item>+ <item name="android:paddingTop">5dp</item>+ <item name="android:paddingBottom">5dp</item>+ <item name="android:textColor">@color/glance_text</item>+ <item name="android:textSize">11sp</item>+ <item name="android:textStyle">bold</item>+ </style>+</resources>diff --git a/solana-mobile/android-overlay/app/src/main/res/xml/glance_widget_info.xml b/solana-mobile/android-overlay/app/src/main/res/xml/glance_widget_info.xmlnew file mode 100644index 000000000..ea8236841--- /dev/null+++ b/solana-mobile/android-overlay/app/src/main/res/xml/glance_widget_info.xml@@ -0,0 +1,19 @@+<?xml version="1.0" encoding="utf-8"?>+<!-- updatePeriodMillis is 0 on purpose: refreshes come from WorkManager+ (GlanceRefreshWorker), which is battery-aware and coalesced, not from the+ AppWidget alarm. -->+<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"+ android:minWidth="250dp"+ android:minHeight="110dp"+ android:minResizeWidth="110dp"+ android:minResizeHeight="110dp"+ android:targetCellWidth="4"+ android:targetCellHeight="2"+ android:maxResizeWidth="420dp"+ android:maxResizeHeight="320dp"+ android:resizeMode="horizontal|vertical"+ android:updatePeriodMillis="0"+ android:initialLayout="@layout/glance_widget_wide"+ android:previewLayout="@layout/glance_widget_wide"+ android:description="@string/glance_widget_description"+ android:widgetCategory="home_screen" />diff --git a/solana-mobile/android-overlay/build.gradle.fragment b/solana-mobile/android-overlay/build.gradle.fragmentnew file mode 100644index 000000000..2a97e9704--- /dev/null+++ b/solana-mobile/android-overlay/build.gradle.fragment@@ -0,0 +1,4 @@+// glance widget (solana-mobile/android-overlay): background refresh.+dependencies {+ implementation 'androidx.work:work-runtime:2.9.1'+}diff --git a/solana-mobile/docs/CHECKLIST.md b/solana-mobile/docs/CHECKLIST.mdindex a2c3a38f0..d3badd969 100644--- a/solana-mobile/docs/CHECKLIST.md+++ b/solana-mobile/docs/CHECKLIST.md@@ -71,6 +71,13 @@ Work top-to-bottom. Do not submit until every box is checked. A date after a box- [ ] Camera permission shows a visible justification at first prompt (device check on `/create/selfie`).- [x] A wallet rejection (`USER_REJECTED`) is handled without crashing: `src/wallet.js` swallows it with no toast, everything else gets a retry toast. (unit + code review 2026-08-27)+## 7b. Home screen widget (1.1+)++- [x] `build-apk.sh` printed `[apply-overlay] overlay applied` before `bubblewrap build` (2026-08-29, versionCode 2, 1.1.0, 4.4 MB, same release key `98:0A:1A:AB:…:11:13:D7`); a build without that line has no widget and must not ship.+- [x] `aapt dump badging build/three-ws-release.apk` lists `ws.three.app.glance.GlanceWidget` as a receiver and `uses-permission: android.permission.INTERNET` (2026-08-29, read back from the R8-minified release APK).+- [x] Emulator (Pixel 7, Android 14, 2026-08-29): the release APK registers **Agent glance** with the launcher (`dumpsys appwidget`), the link intent opens the pin dialog and places a 3x2 instance, and WorkManager runs the refresh with no app UI open. The debug variant against a local API with a real token then passed all five checks: card downloaded and painted (content description "My First Agent, 0 Moves today"), refreshed without opening the app, kept after `am force-stop`, back after `adb reboot`, and held with a "From 5:38 AM (offline). Tap to retry." footer in airplane mode, refreshing again once it was off. Recipe: `README.md#the-home-screen-widget`.+- [ ] `/api/glance/mine?format=png` and `/api/glance/token` are deployed before the APK is published; the widget shows "Fetching your agent" until they are. (Not yet deployed as of 2026-08-29; deploys are owner-gated.)+## 8. Repeat builds- [ ] `KEYSTORE_PASSWORD=... ./scripts/build-apk.sh` runs end-to-end unattended on the release machine (no interactive prompts).diff --git a/solana-mobile/publish/listing/new-in-version.txt b/solana-mobile/publish/listing/new-in-version.txtindex 0e2d8211e..c37017e84 100644--- a/solana-mobile/publish/listing/new-in-version.txt+++ b/solana-mobile/publish/listing/new-in-version.txt@@ -1,9 +1,7 @@-First Seeker release of three.ws.+Home screen widget.-• One-tap Sign-In With Solana through Seed Vault (Mobile Wallet Adapter).-• Selfie to rigged 3D avatar, captured with the on-device camera.-• Deploy an agent on-chain as a Metaplex Core asset held by your wallet.-• Marketplace of community agents, each with a live 3D viewer and chat.-• Embed any agent in Telegram, X, or your own site with one URL.+• Agent glance: your agent's avatar, its name, and how many moves it made today, on your home screen. Refreshes itself about every 30 minutes without opening the app, keeps the last card when you are offline, and opens your agent with a tap.+• Link a phone from three.ws/glance in one tap; every linked widget is listed there with a revoke button.+• Comes in 2x2, 4x2 and 4x3, with Create and My agents shortcuts on the largest.-Built for Seeker. Signed by Seed Vault. Seed phrases never leave the secure element.+Everything from 1.0 is still here: one-tap Sign-In With Solana through Seed Vault, selfie to rigged 3D avatar, on-chain agents as Metaplex Core assets, the marketplace, and sharing into three.ws from any app.diff --git a/solana-mobile/scripts/apply-overlay.mjs b/solana-mobile/scripts/apply-overlay.mjsnew file mode 100755index 000000000..654997fad--- /dev/null+++ b/solana-mobile/scripts/apply-overlay.mjs@@ -0,0 +1,114 @@+#!/usr/bin/env node+// Apply solana-mobile/android-overlay/ to the Bubblewrap-generated project.+//+// `bubblewrap update` regenerates the whole Android project from+// twa/twa-manifest.json on every build, so anything native (the glance home+// screen widget) has to be laid on top AFTER update and BEFORE build. This+// script is that step, and build-apk.sh runs it in exactly that slot.+//+// node scripts/apply-overlay.mjs --project build [--overlay android-overlay]+//+// What it does:+// 1. copies every file under <overlay>/app/ into <project>/app/ (sources,+// layouts, drawables, values, xml), refusing to clobber a generated file+// it does not own;+// 2. splices AndroidManifest.permissions.xml after the <manifest> opening+// tag and AndroidManifest.application.xml before </application>;+// 3. appends build.gradle.fragment to app/build.gradle.+//+// It is idempotent (a marker comment guards each splice) and it fails loudly+// on a missing overlay or a manifest it cannot parse: the listing says the app+// has a widget, so a build that silently dropped it would ship a lie.++import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const here = path.dirname(fileURLToPath(import.meta.url));+const root = path.resolve(here, '..');++const args = process.argv.slice(2);+const opt = (name, fallback) => {+ const i = args.indexOf(name);+ return i >= 0 && args[i + 1] ? args[i + 1] : fallback;+};+const projectDir = path.resolve(root, opt('--project', 'build'));+const overlayDir = path.resolve(root, opt('--overlay', 'android-overlay'));++const log = (msg) => console.log(`[apply-overlay] ${msg}`);+const fail = (msg) => {+ console.error(`[apply-overlay] ERROR: ${msg}`);+ process.exit(1);+};++const REQUIRED = [+ 'AndroidManifest.permissions.xml',+ 'AndroidManifest.application.xml',+ 'build.gradle.fragment',+ 'app/src/main/java/ws/three/app/glance/GlanceWidget.java',+ 'app/src/main/res/xml/glance_widget_info.xml',+];+for (const rel of REQUIRED) {+ if (!fs.existsSync(path.join(overlayDir, rel))) fail(`overlay is missing ${rel} (${overlayDir})`);+}++const manifestPath = path.join(projectDir, 'app/src/main/AndroidManifest.xml');+const gradlePath = path.join(projectDir, 'app/build.gradle');+if (!fs.existsSync(manifestPath)) fail(`no generated manifest at ${manifestPath}; run bubblewrap update first`);+if (!fs.existsSync(gradlePath)) fail(`no generated build.gradle at ${gradlePath}; run bubblewrap update first`);++// 1. Sources and resources. Every overlay file is namespaced "glance", so a+// collision with a generated file means the generator changed under us.+let copied = 0;+function copyTree(from, to) {+ for (const entry of fs.readdirSync(from, { withFileTypes: true })) {+ const src = path.join(from, entry.name);+ const dst = path.join(to, entry.name);+ if (entry.isDirectory()) {+ fs.mkdirSync(dst, { recursive: true });+ copyTree(src, dst);+ continue;+ }+ if (fs.existsSync(dst) && fs.readFileSync(dst).equals(fs.readFileSync(src)) === false && !entry.name.includes('glance')) {+ fail(`refusing to overwrite generated file ${dst}`);+ }+ fs.copyFileSync(src, dst);+ copied++;+ }+}+copyTree(path.join(overlayDir, 'app'), path.join(projectDir, 'app'));+log(`copied ${copied} files into ${path.relative(root, projectDir)}/app`);++// 2. Manifest.+const MARK_PERMS = '<!-- glance widget (solana-mobile/android-overlay): fetched';+const MARK_APP = '<!-- glance widget (solana-mobile/android-overlay) -->';+let manifest = fs.readFileSync(manifestPath, 'utf8');+if (!manifest.includes(MARK_PERMS)) {+ const open = manifest.match(/<manifest\b[^>]*>/);+ if (!open) fail('cannot find the <manifest> opening tag');+ const at = open.index + open[0].length;+ manifest = `${manifest.slice(0, at)}\n\n${fs.readFileSync(path.join(overlayDir, 'AndroidManifest.permissions.xml'), 'utf8')}${manifest.slice(at)}`;+}+if (!manifest.includes(MARK_APP)) {+ const at = manifest.lastIndexOf('</application>');+ if (at < 0) fail('cannot find </application>');+ manifest = `${manifest.slice(0, at)}${fs.readFileSync(path.join(overlayDir, 'AndroidManifest.application.xml'), 'utf8')}\n ${manifest.slice(at)}`;+}+fs.writeFileSync(manifestPath, manifest);+for (const needle of ['.glance.GlanceWidget', '.glance.GlanceLinkActivity', 'android.permission.INTERNET']) {+ if (!manifest.includes(needle)) fail(`manifest merge lost ${needle}`);+}+log('merged the widget receiver, link activity, and permissions into AndroidManifest.xml');++// 3. Gradle.+const fragment = fs.readFileSync(path.join(overlayDir, 'build.gradle.fragment'), 'utf8');+let gradle = fs.readFileSync(gradlePath, 'utf8');+const fragmentMark = fragment.split('\n')[0];+if (!gradle.includes(fragmentMark)) {+ gradle = `${gradle.trimEnd()}\n\n${fragment}`;+ fs.writeFileSync(gradlePath, gradle);+}+if (!gradle.includes('androidx.work:work-runtime')) fail('build.gradle merge lost the WorkManager dependency');+log('appended the WorkManager dependency to app/build.gradle');++log('overlay applied');diff --git a/solana-mobile/scripts/build-apk.sh b/solana-mobile/scripts/build-apk.shindex 08bdc0619..1b03bc232 100755--- a/solana-mobile/scripts/build-apk.sh+++ b/solana-mobile/scripts/build-apk.sh@@ -8,7 +8,8 @@# KEYSTORE_PASSWORD='...' ./scripts/build-apk.sh## Environment:-# KEYSTORE_PASSWORD keystore password (required)+# KEYSTORE_PASSWORD keystore password (required; SOLANA_MOBILE_KEYSTORE_PASSWORD,+# the name used in the repo's .env, is accepted as a fallback)# KEYSTORE_PATH path to release.keystore (default: ./android.keystore)# KEY_ALIAS release key alias (default: threews)# KEY_PASSWORD key password (defaults to KEYSTORE_PASSWORD)@@ -41,8 +42,12 @@ require noderequire npxrequire keytool-if [[ -z "${KEYSTORE_PASSWORD:-}" ]]; then- echo "[build-apk] KEYSTORE_PASSWORD must be set" >&2+# The repo's .env stores the password as SOLANA_MOBILE_KEYSTORE_PASSWORD (a+# name that cannot collide with any other keystore on the machine); accept it+# so `set -a; . ../.env; set +a; ./scripts/build-apk.sh` just works.+KEYSTORE_PASSWORD="${KEYSTORE_PASSWORD:-${SOLANA_MOBILE_KEYSTORE_PASSWORD:-}}"+if [[ -z "$KEYSTORE_PASSWORD" ]]; then+ echo "[build-apk] KEYSTORE_PASSWORD (or SOLANA_MOBILE_KEYSTORE_PASSWORD) must be set" >&2exit 1fi@@ -213,6 +218,20 @@ console.log('[build-apk] patched ' + p + ' with resConfigs "en"');NODEfi+# ── 5b. Lay the native overlay over the generated project ─────────────────+# `bubblewrap update` regenerates everything, so the glance home screen widget+# (an AppWidgetProvider, its layouts, a link activity, the WorkManager+# dependency) is applied here, after update and before build. The script exits+# non-zero on a missing overlay or a failed manifest merge: the store listing+# says the app has a widget, so a widget-less APK must never ship silently.+OVERLAY_DIR="$(cd .. && pwd)/android-overlay"+if [[ ! -d "$OVERLAY_DIR" ]]; then+ echo "[build-apk] ERROR: native overlay missing at $OVERLAY_DIR" >&2+ exit 1+fi+echo "[build-apk] applying native overlay (home screen widget)"+node ../scripts/apply-overlay.mjs --project "$BUILD_DIR" --overlay "$OVERLAY_DIR"+# ── 6. Build & sign the APK ────────────────────────────────────────────────echo "[build-apk] building signed release APK"BUBBLEWRAP_KEYSTORE_PASSWORD="$KEYSTORE_PASSWORD" \diff --git a/solana-mobile/twa/twa-manifest.json b/solana-mobile/twa/twa-manifest.jsonindex 76b8d038a..5b434dd17 100644--- a/solana-mobile/twa/twa-manifest.json+++ b/solana-mobile/twa/twa-manifest.json@@ -17,8 +17,8 @@"iconUrl": "https://three.ws/pwa-512x512.png","maskableIconUrl": "https://three.ws/pwa-maskable-512x512.png","monochromeIconUrl": "https://three.ws/pwa-icon.svg",- "appVersion": "1.0.0",- "appVersionCode": 1,+ "appVersion": "1.1.0",+ "appVersionCode": 2,"shortcuts": [{"name": "Create avatar",