feat(mobile): Android and web support (staging)

.agents/skills/mobile-android-verification/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: mobile-android-verification
+description: Run and verify apps/mobile on a local Android emulator against this worktree's API and relay, with adb and Maestro for input. Use when asked to run, screenshot, verify, or reproduce a mobile change on Android. For iOS use mobile-sim-verification; with no local toolchain (a cloud sandbox) use mobile-eas-dev, which is iOS only.
+---
+
+# Mobile Android Verification
+
+The Android counterpart to `mobile-sim-verification`. Its Rules apply here unchanged: use the real
+screen, drive state through real services, run the edge pass, never show "unknown" as a negative,
+record flashes, attribute failures correctly. This file is the Android mechanics.
+
+`apps/mobile/scripts/android-dev.sh` does the setup. Read its header for the flags.
+
+## Setup
+
+```bash
+apps/mobile/scripts/android-dev.sh --doctor   # what is missing on this machine
+apps/mobile/scripts/android-dev.sh            # boot, build if needed, Metro, open the app
+apps/mobile/scripts/android-dev.sh --user maya@local.test   # also sign in as a dev account
+```
+
+- **Toolchain.** Android Studio's SDK (`~/Library/Android/sdk`) with an AVD, and JDK 17. Gradle for
+  RN 0.88 fails on the Java 8 that macOS often has on `PATH`; `brew install openjdk@17`. The script
+  finds both without `ANDROID_HOME` or `JAVA_HOME` set. For Google sign-in, the AVD needs a Google
+  Play system image and a Google account added on the device.
+- **Services.** Start the API, relay and realtime as in `mobile-sim-verification` (each in a
+  Paradev terminal). The script reverses Metro, `API_PORT`, `RELAY_PORT`, `REALTIME_PORT` and
+  `WEB_PORT` with `adb reverse`, so `localhost` in the app reaches this machine. A port it does not
+  reverse fails in the app as a network error.
+- **Build.** `android/` is generated by `expo prebuild` and gitignored. The first Gradle build takes
+  about 10 minutes; later ones reuse the daemon. The script builds only for the emulator's ABI.
+  JS/TS changes need no rebuild: `android-dev.sh --reload`.
+
+## One emulator, many worktrees
+
+Every worktree installs the same package, `sh.superset.mobile`, so the last install wins.
+
+- The script writes the worktree path and native fingerprint of the installed APK to
+  `/data/local/tmp/superset-mobile-owner` on the device. A mismatch rebuilds, so another worktree's
+  APK is never tested by mistake. Check it before you report: `adb shell cat
+  /data/local/tmp/superset-mobile-owner`.
+- Agents in parallel workspaces take turns. Ask with `superset agents` before you install or
+  launch, and say when you hand it back. Do not boot a second emulator next to a Gradle build: the
+  machine runs out of memory.
+- Each worktree's Metro gets its own port (saved in `.tmp/android-dev/metro.port`). Stop it with
+  `--stop` when you are done.
+
+## Traps
+
+- **Stale Metro cache.** The transform cache is shared across worktrees. A stale entry fails the
+  Android bundle with a 500: ENOENT on `react-native-worklets/.worklets/<hash>.js`. The script
+  starts Metro with `--clear`; if you start Metro yourself, do the same.
+- **Dev auto sign-in.** `EXPO_PUBLIC_DEV_ONE_TIME_TOKEN` in `.env` signs the app in at launch even
+  after `pm clear`. Blank it and restart Metro to see the sign-in screen.
+- **Notification permission.** Home asks for `POST_NOTIFICATIONS` once, when the first agent card
+  would show, and remembers the answer. The script grants it up front; to see the prompt, run
+  `adb shell pm revoke sh.superset.mobile android.permission.POST_NOTIFICATIONS` and `pm clear`.
+- **iOS-only header items.** SF Symbol `Stack.Toolbar` buttons and `Stack.SearchBar` do not render
+  on Android, and a form sheet draws no native bar there (see the sheet convention in
+  `apps/mobile/AGENTS.md`). An empty header on Android is not always a regression.
+- **The iOS fingerprint.** `app.config.ts`, `eas.json`, `apps/mobile/.gitignore` and
+  `packages/shared/src/app-identity.ts` feed the iOS runtime version even for Android-only edits.
+  Changing them rebuilds and resubmits iOS on merge. Check with
+  `MOBILE_EAS_BUILD=1 node_modules/.bin/fingerprint fingerprint:generate . --platform ios` in
+  `apps/mobile`, and keep such a change in its own commit.
+- **The Mobile pane** in the desktop app shows the same emulator (local hub, scrcpy stream). It
+  releases an emulator it booted 60 s after its pane closes, which ends an `adb` session on it. If
+  you booted the emulator yourself, the pane only shows it.
+
+- **Low memory kills the dev app.** The dev build holds about 800 MB (Hermes runs the full dev
+  bundle). An AVD that booted from a 2 GB snapshot loses the app to the low-memory killer as soon as
+  a picker or Chrome opens (`lowmemorykiller: Kill 'sh.superset.mobile'` in logcat). Check
+  `adb shell cat /proc/meminfo`; if `MemTotal` is near 2 GB, restart that AVD with
+  `emulator -avd <avd> -port <port> -memory 4096 -no-snapshot-load`.
+- **The emulator mic.** `adb emu avd hostmicon` feeds the Mac microphone to the AVD, so the
+  speech recogniser hears the room. Speech played through the Mac speakers often reaches it as
+  `NO_SPEECH_DETECTED`, and Google's recogniser needs about 5 s after the mic tap before it listens.
+
+## Input and evidence
+
+```bash
+adb exec-out screencap -p > shot.png                      # or: android-dev.sh --shot shot.png
+adb shell screenrecord /sdcard/run.mp4                    # stop with Ctrl-C, then adb pull
+adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml   # element bounds for taps
+adb shell input tap X Y; adb shell input text 'hello'; adb shell input keyevent 4   # 4 = back
+adb shell am start -a android.intent.action.VIEW -d 'superset://settings' sh.superset.mobile
+adb logcat -d -s ReactNativeJS:V                          # JS console
+adb logcat -d -b crash                                    # native crashes
+adb shell cmd statusbar expand-notifications              # the agent card lives here
+adb shell cmd locale set-app-locales sh.superset.mobile --locales de-DE   # per-app locale
+adb shell settings put system font_scale 1.3              # large text; reset to 1.0
+```
+
+Maestro runs on Android too: `maestro --device emulator-5554 test <flow>`, with `JAVA_HOME` on JDK 17.
+`apps/mobile/.maestro/flows/dev-sign-in.yml` is the sign-in flow `--user` uses. Maestro 2 rejects a
+flow where `optional: true` sits beside a command (`Invalid Command Format`); put it inside the
+command's map. Check a flow with `maestro check-syntax <flow>` before running it.
+
+Reset the locale and font scale, stop Metro (`--stop`) and the services, and remove test data when
+done. Leave the emulator running if another agent is waiting for it.

.env.example

@@ -33,13 +33,17 @@ NEXT_PUBLIC_DOCS_URL=
 NEXT_PUBLIC_ROOT_DOMAIN=
 # Desktop name in menus, the Dock and dialogs; productName stays "Superset".
 DESKTOP_DISPLAY_NAME=
+# Origins that serve the mobile app on the web, comma-separated, no wildcards.
+# The API allows them for CORS and sign-in; unset = none.
+MOBILE_WEB_ORIGINS=
 
 # -----------------------------------------------------------------------------
 # Mobile (Expo) — read at Metro bundle time; EAS builds get these from eas.json
 # -----------------------------------------------------------------------------
 EXPO_PUBLIC_API_URL=
 EXPO_PUBLIC_ROOT_DOMAIN=
 EXPO_PUBLIC_POSTHOG_KEY=
+EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=
 EXPO_PUBLIC_SENTRY_DSN_MOBILE=
 EXPO_PUBLIC_SENTRY_ENVIRONMENT=
 # App Review demo account, read by apps/mobile/store.config.js for `eas metadata:push`
@@ -139,6 +143,9 @@ R2_ENDPOINT=
 # Where pages are served from, one subdomain per page under it (apps/usercontent):
 # https://frame.supersetusercontent.com
 USERCONTENT_URL=
+# The agents web app (apps/mobile web export), which apps/web serves at /agents:
+# https://superset-agents.vercel.app
+AGENTS_URL=
 # App-referenced files with tickets (apps/usercontent, same Worker); must match
 # the Worker's own MEDIA_URL: https://media.supersetusercontent.com
 MEDIA_URL=

.env.local.example

@@ -42,13 +42,16 @@ NEXT_PUBLIC_MARKETING_URL=http://localhost:3002
 NEXT_PUBLIC_DOCS_URL=http://localhost:3004
 NEXT_PUBLIC_ROOT_DOMAIN=
 DESKTOP_DISPLAY_NAME=
+# `expo start --web` in apps/mobile
+MOBILE_WEB_ORIGINS=http://localhost:8081
 
 # -----------------------------------------------------------------------------
 # Mobile (Expo) — setup.local.sh overrides these with allocated ports.
 # -----------------------------------------------------------------------------
 EXPO_PUBLIC_API_URL=http://localhost:3001
 EXPO_PUBLIC_ROOT_DOMAIN=
 EXPO_PUBLIC_POSTHOG_KEY=phc_local_dev_disabled
+EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=
 # A syntactically valid but inert DSN: @sentry/react-native's useNativeInit
 # crashes the app on launch (SIGSEGV, before any JS runs) if this fails to
 # parse as a URL, which an empty or missing value does. Needs a well-formed
@@ -129,6 +132,9 @@ R2_ENDPOINT=http://localhost:9000
 USERCONTENT_URL=http://frame.usercontent.localhost:8787
 MEDIA_URL=http://media.usercontent.localhost:8787
 STATIC_URL=http://static.usercontent.localhost:8787
+# Setup writes AGENTS_PORT (base+19) and this URL; serve the agents web export
+# there with apps/mobile/scripts/serve-web.ts (docs/agents-web.md).
+AGENTS_URL=http://localhost:3019
 USERCONTENT_TOKEN_SECRET=local-dev-usercontent-secret-change-me-32
 AGENT_WORKER_SECRET=local-dev-agent-worker-secret-change-me-32
 AGENT_TURN_SIGNING_SECRET=local-dev-agent-turn-signing-secret-change-me-32

.github/templates/preview-comment.md

@@ -24,6 +24,11 @@
 <td>$WEB_LINK</td>
 </tr>
 <tr>
+<td><img src="https://vercel.com/favicon.ico" width="20" height="20" alt="Vercel"> <strong>Agents Web (Vercel)</strong></td>
+<td align="center">$AGENTS_STATUS</td>
+<td>$AGENTS_LINK</td>
+</tr>
+<tr>
 <td><img src="https://vercel.com/favicon.ico" width="20" height="20" alt="Vercel"> <strong>Marketing (Vercel)</strong></td>
 <td align="center">$MARKETING_STATUS</td>
 <td>$MARKETING_LINK</td>

.github/workflows/deploy-preview.yml

@@ -13,6 +13,7 @@ env:
   PR_NUMBER: ${{ github.event.pull_request.number }}
   API_ALIAS: api-pr-${{ github.event.pull_request.number }}-superset.vercel.app
   WEB_ALIAS: web-pr-${{ github.event.pull_request.number }}-superset.vercel.app
+  AGENTS_ALIAS: agents-pr-${{ github.event.pull_request.number }}-superset.vercel.app
   MARKETING_ALIAS: marketing-pr-${{ github.event.pull_request.number }}-superset.vercel.app
   ADMIN_ALIAS: admin-pr-${{ github.event.pull_request.number }}-superset.vercel.app
   DOCS_ALIAS: docs-pr-${{ github.event.pull_request.number }}-superset.vercel.app
@@ -172,6 +173,7 @@ jobs:
           GOOGLE_CONNECTIONS_CLIENT_SECRET: ${{ secrets.GOOGLE_CONNECTIONS_CLIENT_SECRET }}
           GH_CLIENT_ID: ${{ secrets.GH_CLIENT_ID }}
           GH_CLIENT_SECRET: ${{ secrets.GH_CLIENT_SECRET }}
+          MOBILE_WEB_ORIGINS: ${{ secrets.MOBILE_WEB_ORIGINS }}
           NEXT_PUBLIC_SENTRY_DSN_API: ${{ secrets.NEXT_PUBLIC_SENTRY_DSN_API }}
           NEXT_PUBLIC_SENTRY_ENVIRONMENT: ${{ secrets.NEXT_PUBLIC_SENTRY_ENVIRONMENT }}
           NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.NEXT_PUBLIC_POSTHOG_KEY }}
@@ -255,6 +257,7 @@ jobs:
             --env GOOGLE_CONNECTIONS_CLIENT_SECRET=$GOOGLE_CONNECTIONS_CLIENT_SECRET \
             --env GH_CLIENT_ID=$GH_CLIENT_ID \
             --env GH_CLIENT_SECRET=$GH_CLIENT_SECRET \
+            --env MOBILE_WEB_ORIGINS=$MOBILE_WEB_ORIGINS \
             --env NEXT_PUBLIC_SENTRY_DSN_API=$NEXT_PUBLIC_SENTRY_DSN_API \
             --env NEXT_PUBLIC_SENTRY_ENVIRONMENT=$NEXT_PUBLIC_SENTRY_ENVIRONMENT \
             --env NEXT_PUBLIC_POSTHOG_KEY=$NEXT_PUBLIC_POSTHOG_KEY \
@@ -409,6 +412,7 @@ jobs:
           SERVER_ANTHROPIC_API_KEY: ${{ secrets.SERVER_ANTHROPIC_API_KEY }}
           RELAY_URL: ${{ secrets.RELAY_URL }}
           RELAY_BACKUP_URL: ${{ secrets.RELAY_BACKUP_URL }}
+          AGENTS_URL: https://${{ env.AGENTS_ALIAS }}
         run: |
           vercel pull --yes --environment=preview --token=$VERCEL_TOKEN
           vercel build --token=$VERCEL_TOKEN
@@ -418,6 +422,7 @@ jobs:
             --env BETTER_AUTH_SECRET=$BETTER_AUTH_SECRET \
             --env NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL \
             --env NEXT_PUBLIC_WEB_URL=$NEXT_PUBLIC_WEB_URL \
+            --env AGENTS_URL=$AGENTS_URL \
             --env NEXT_PUBLIC_MARKETING_URL=$NEXT_PUBLIC_MARKETING_URL \
             --env NEXT_PUBLIC_ROOT_DOMAIN=$NEXT_PUBLIC_ROOT_DOMAIN \
             --env NEXT_PUBLIC_ADMIN_URL=$NEXT_PUBLIC_ADMIN_URL \
@@ -465,6 +470,85 @@ jobs:
           name: web-status
           path: web-status.env
 
+  deploy-agents:
+    name: Deploy Agents Web
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    environment:
+      name: preview
+      url: https://${{ env.WEB_ALIAS }}/agents
+
+    steps:
+      - name: Check the agents project is configured
+        id: agents-config
+        env:
+          AGENTS_PROJECT_ID: ${{ secrets.VERCEL_AGENTS_PROJECT_ID }}
+        run: echo "configured=$([ -n "$AGENTS_PROJECT_ID" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout repository
+        if: steps.agents-config.outputs.configured == 'true'
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Bun
+        if: steps.agents-config.outputs.configured == 'true'
+        id: setup-bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version-file: .bun-version
+
+      - name: Cache dependencies
+        if: steps.agents-config.outputs.configured == 'true'
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ steps.setup-bun.outputs.bun-revision }}-${{ hashFiles('bun.lock') }}
+
+      - name: Install dependencies
+        if: steps.agents-config.outputs.configured == 'true'
+        run: bun install --frozen --ignore-scripts
+
+      - name: Compile translations
+        if: steps.agents-config.outputs.configured == 'true'
+        run: bun run --filter=@superset/i18n build
+
+      - name: Install Vercel CLI
+        if: steps.agents-config.outputs.configured == 'true'
+        run: bun add --global vercel@$VERCEL_CLI_VERSION
+
+      - name: Build and Deploy Agents Web
+        if: steps.agents-config.outputs.configured == 'true'
+        working-directory: apps/mobile
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_AGENTS_PROJECT_ID }}
+          EXPO_PUBLIC_API_URL: https://${{ env.API_ALIAS }}
+          EXPO_PUBLIC_WEB_URL: https://${{ env.WEB_ALIAS }}
+          EXPO_PUBLIC_RELAY_URL: ${{ secrets.RELAY_URL }}
+          EXPO_PUBLIC_REALTIME_URL: ${{ secrets.REALTIME_URL }}
+          EXPO_PUBLIC_POSTHOG_KEY: ${{ secrets.NEXT_PUBLIC_POSTHOG_KEY }}
+          EXPO_PUBLIC_SENTRY_DSN_MOBILE: ${{ secrets.EXPO_PUBLIC_SENTRY_DSN_MOBILE }}
+          EXPO_PUBLIC_SENTRY_ENVIRONMENT: ${{ secrets.NEXT_PUBLIC_SENTRY_ENVIRONMENT }}
+        run: |
+          bun scripts/build-web.ts
+          VERCEL_URL=$(vercel deploy --prebuilt --archive=tgz --token=$VERCEL_TOKEN)
+          vercel alias $VERCEL_URL ${{ env.AGENTS_ALIAS }} --scope=$VERCEL_ORG_ID --token=$VERCEL_TOKEN
+
+      - name: Save agents success status
+        if: steps.agents-config.outputs.configured == 'true'
+        run: |
+          cat > agents-status.env << EOF
+          AGENTS_STATUS="✅"
+          AGENTS_LINK="<a href=\"https://${{ env.WEB_ALIAS }}/agents\">Open Preview</a>"
+          EOF
+
+      - name: Upload agents status
+        if: steps.agents-config.outputs.configured == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: agents-status
+          path: agents-status.env
+
   deploy-marketing:
     name: Deploy Marketing
     runs-on: blacksmith-4vcpu-ubuntu-2404
@@ -708,7 +792,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     if: always()
-    needs: [create-database, deploy-database, deploy-api, deploy-web, deploy-marketing, deploy-docs]
+    needs: [create-database, deploy-database, deploy-api, deploy-web, deploy-agents, deploy-marketing, deploy-docs]
     permissions:
       contents: read
       pull-requests: write
@@ -731,6 +815,8 @@ jobs:
           API_LINK="Failed to deploy"
           WEB_STATUS="❌"
           WEB_LINK="Failed to deploy"
+          AGENTS_STATUS="❌"
+          AGENTS_LINK="Failed to deploy"
           MARKETING_STATUS="❌"
           MARKETING_LINK="Failed to deploy"
           DOCS_STATUS="❌"
@@ -751,6 +837,10 @@ jobs:
             source web-status.env
           fi
 
+          if [[ "${{ needs.deploy-agents.result }}" == "success" ]]; then
+            source agents-status.env
+          fi
+
           if [[ "${{ needs.deploy-marketing.result }}" == "success" ]]; then
             source marketing-status.env
           fi
@@ -759,7 +849,7 @@ jobs:
             source docs-status.env
           fi
 
-          export DATABASE_STATUS DATABASE_LINK API_STATUS API_LINK WEB_STATUS WEB_LINK MARKETING_STATUS MARKETING_LINK DOCS_STATUS DOCS_LINK
+          export DATABASE_STATUS DATABASE_LINK API_STATUS API_LINK WEB_STATUS WEB_LINK AGENTS_STATUS AGENTS_LINK MARKETING_STATUS MARKETING_LINK DOCS_STATUS DOCS_LINK
           envsubst < .github/templates/preview-comment.md > final-comment.md
 
       - name: Post final deployment comment