test(expo): reorient Maestro e2e to the bridge layer + add run_e2e toggle

The native UI is covered by clerk-ios/clerk-android's own tests; the Expo
Maestro suite now targets only what those can't reach — the bridge/integration
layer.

- Cut native-UI-content flows (edit-first-name, email-verification,
  open-inline-profile).
- Un-skip the re-auth cycle; add session/persists-across-restart (token-cache
  rehydration across a cold restart — a pure-Expo concern).
- Un-skip theming flows and rework verification: Maestro's JS sandbox can't
  decode PNGs, so the in-flow runScript never worked. check-theme-color.js now
  counts themed-color pixels (resolution-robust) and runs as a Node post-step
  via verify-themes.sh, wired into the runners + a CI 'Verify theming' step.
- Add run_e2e workflow input (default true) gating both jobs, so e2e can be
  toggled off for unit-only runs once the suite is trusted.

Author: chriscanin

.github/workflows/mobile-e2e.yml

@@ -39,6 +39,11 @@ on:
         description: "Optional: when set together with clerk_android_ref, the workflow checks out clerk-android at that ref, bumps CLERK_*_VERSION by appending this suffix (e.g. '-expo-compat-123'), publishes to mavenLocal, and pins @clerk/expo to the resulting version. Used by clerk-android's expo-compat release gate."
         required: false
         default: ""
+      run_e2e:
+        description: "Run the e2e build + Maestro jobs. Set false to skip e2e entirely (the fast JS unit tests still run separately in ci.yml). Default true while we validate the suite; flip to false for unit-only once the suite is trusted."
+        required: false
+        type: boolean
+        default: true
   workflow_call:
     inputs:
       quickstart_ref:
@@ -65,6 +70,10 @@ on:
         type: string
         required: false
         default: ""
+      run_e2e:
+        type: boolean
+        required: false
+        default: true
 
 env:
   EXPO_INSTANCE_NAME: clerkstage-with-native-components
@@ -91,7 +100,7 @@ jobs:
     # clerk-ios's expo-compat release gate (passes clerk_ios_ref without
     # clerk_android_ref). Manual dispatches without ref inputs still run
     # both jobs.
-    if: inputs.clerk_ios_ref == '' || inputs.clerk_android_ref != ''
+    if: inputs.run_e2e && (inputs.clerk_ios_ref == '' || inputs.clerk_android_ref != '')
     runs-on: 'blacksmith-8vcpu-ubuntu-2204'
     timeout-minutes: 45
     defaults:
@@ -588,6 +597,15 @@ jobs:
             | while read f; do grep -qE "^[[:space:]]*-[[:space:]]*(${pattern})[[:space:]]*$" "$f" || printf '%s\n' "$f"; done
             | xargs -n 1 -I FLOW bash -c 'flow="$1"; for a in 1 2; do if maestro test --env CLERK_TEST_EMAIL="$CLERK_TEST_EMAIL" --env CLERK_TEST_PASSWORD="$CLERK_TEST_PASSWORD" --flatten-debug-output "$flow"; then exit 0; fi; if [ "$a" -eq 2 ]; then echo "::error::Flow $flow failed after 2 attempts"; exit 1; fi; echo "::warning::Flow $flow failed attempt $a, retrying after 10s..."; adb shell am force-stop com.clerk.clerkexpoquickstart >/dev/null 2>&1 || true; sleep 10; done' _ FLOW
 
+      # Theme verification is a Node post-step (Maestro can't decode PNGs in its
+      # JS sandbox). The theming flows wrote theme-light.png / theme-dark.png to
+      # integration/mobile; this asserts each contains a large region of the
+      # expected themed color. Runs on success OR failure so a flaked flow
+      # doesn't hide a theming regression; skips cleanly if no theme shots exist.
+      - name: Verify Android theming
+        if: success() || failure()
+        run: bash integration/mobile/scripts/verify-themes.sh
+
       - name: Upload Maestro artifacts on failure or cancel
         if: failure() || cancelled()
         uses: actions/upload-artifact@v4
@@ -616,7 +634,7 @@ jobs:
     # clerk-android's expo-compat release gate, which passes clerk_android_ref
     # (and clerk_android_snapshot_suffix) but not clerk_ios_ref. Manual
     # dispatches without ref inputs still run both jobs.
-    if: inputs.clerk_android_ref == '' || inputs.clerk_ios_ref != ''
+    if: inputs.run_e2e && (inputs.clerk_android_ref == '' || inputs.clerk_ios_ref != '')
     # GitHub-hosted runner. Blacksmith macOS-15 didn't pick up the job in
     # our trial (capacity / label availability) — revisit when Blacksmith
     # exposes a label we know is provisioned on this account.
@@ -1021,6 +1039,13 @@ jobs:
               done
             ' _ FLOW
 
+      # Theme verification is a Node post-step (Maestro can't decode PNGs in its
+      # JS sandbox). iOS runs the light theme only (dark-mode is androidOnly);
+      # verify-themes.sh skips any theme shot that wasn't produced.
+      - name: Verify iOS theming
+        if: success() || failure()
+        run: bash integration/mobile/scripts/verify-themes.sh
+
       - name: Upload Maestro artifacts on failure or cancel
         if: failure() || cancelled()
         uses: actions/upload-artifact@v4

integration/mobile/flows/cycles/sign-in-sign-out-sign-in.yaml

@@ -16,7 +16,6 @@
 appId: com.clerk.clerkexpoquickstart
 tags:
   - regression
-  - skip
 ---
 - runFlow: ../common/open-app.yaml
 # First sign-in

integration/mobile/flows/profile/edit-first-name.yaml

@@ -0,0 +1,54 @@
+# PERSISTENCE: the Expo token cache (expo-secure-store) must rehydrate the
+# Clerk session across a full app restart. This is a pure-Expo concern — the
+# native SDKs don't own JS-side session persistence — so it's exactly the
+# bridge/integration coverage the native UI suites (Sam/Sean) can't provide.
+#
+# Sign in, FULLY kill the app (cold start, not background), relaunch WITHOUT
+# clearing state, and assert we land on the signed-in home screen without
+# re-entering credentials. If the token cache regresses, this lands on the
+# signed-out AuthView instead.
+appId: com.clerk.clerkexpoquickstart
+tags:
+  - regression
+  - persistence
+---
+# Clean start → sign in.
+- runFlow: ../common/open-app.yaml
+- runFlow: ../common/assert-signed-out.yaml
+- runFlow: ../common/sign-in-email-password.yaml
+- runFlow: ../common/assert-signed-in.yaml
+# Fully terminate the app to force a cold start that must rehydrate the
+# session from secure-store rather than from in-memory state.
+- stopApp
+- waitForAnimationToEnd:
+    timeout: 2000
+# Relaunch WITHOUT clearState — the persisted session must survive.
+- launchApp
+- waitForAnimationToEnd:
+    timeout: 5000
+# Dev build: reconnect to the dev server if the launcher reappears after a
+# cold start (iOS: localhost, Android: 10.0.2.2 — both end in :8081).
+- runFlow:
+    when:
+      visible: "Development Build"
+    commands:
+      - tapOn:
+          text: ".*:8081"
+      - waitForAnimationToEnd:
+          timeout: 10000
+- runFlow:
+    when:
+      visible: ".*developer menu.*"
+    commands:
+      - tapOn:
+          text: "Close"
+          optional: true
+- waitForAnimationToEnd:
+    timeout: 3000
+# The whole point: signed in WITHOUT re-entering credentials. extendedWaitUntil
+# tolerates cold-start rehydration time; if the cache regressed we'd instead
+# see the AuthView's "Welcome! Sign in to continue".
+- extendedWaitUntil:
+    visible: "Sign Out"
+    timeout: 30000
+- takeScreenshot: session-persisted

integration/mobile/flows/profile/open-inline-profile.yaml

@@ -1,33 +1,25 @@
-# REGRESSION: Native theming was not applied because Clerk.initialize() on
-# Android was resetting customTheme to its default (null) parameter.
+# REGRESSION: native theming wasn't reaching the rendered component. This has
+# broken two ways, both invisible to the native SDK's own tests:
+#   1. The Expo config plugin not embedding clerk-theme.json (the app.json
+#      plugin entry was missing the `theme` prop) — so Info.plist / Android
+#      assets never carried the theme.
+#   2. Android's Clerk.initialize() resetting customTheme to its default.
+# Either way the AuthView renders with default styling instead of the theme.
 #
-# This flow takes a screenshot of the AuthView and uses scripts/check-theme-color.js
-# to assert that a sampled pixel matches the expected primary color.
+# This flow only CAPTURES the signed-out AuthView screenshot. The actual color
+# assertion runs as a Node POST-STEP in the runner (scripts/check-theme-color.js)
+# — Maestro's runScript sandbox is GraalJS and can't decode a PNG. The post-step
+# asserts the screenshot contains a large region of the themed primary (#FF4444),
+# which is resolution-independent (no fragile pixel coordinates).
 appId: com.clerk.clerkexpoquickstart
-# TODO: the check-theme-color.js script requires pngjs (install in the
-# quickstart app) and the NativeComponentQuickstart currently doesn't
-# bundle the clerk-theme.json for iOS — so the iOS AuthView renders
-# with default purple not the themed red. Skip until theming is wired
-# through to iOS in the quickstart.
 tags:
   - regression
   - theming
-  - skip
 ---
 - runFlow: ../common/open-app.yaml
 - runFlow: ../common/assert-signed-out.yaml
 - waitForAnimationToEnd:
     timeout: 3000
-# Take a screenshot of the AuthView
-- takeScreenshot: theme-screenshot
-# Run the pixel-check helper. Coordinates target the primary "Continue" button.
-# The script exits non-zero if the sampled pixel is more than tolerance away
-# from the expected color.
-- runScript:
-    file: ../../scripts/check-theme-color.js
-    env:
-      THEME_IMAGE: theme-screenshot.png
-      THEME_X: "200"
-      THEME_Y: "560"
-      THEME_EXPECTED: "#FF4444"
-      THEME_TOLERANCE: "20"
+# Written to integration/mobile/theme-light.png (maestro's CWD). The runner's
+# theme-check post-step reads this file.
+- takeScreenshot: theme-light

integration/mobile/flows/session/persists-across-restart.yaml

@@ -1,12 +1,13 @@
-# Theming: verify dark mode applies the darkColors from clerk-theme.json.
-# Android only: iOS hex colors are static for v1 of the theming plugin.
+# Theming: dark mode applies the darkColors from clerk-theme.json (primary
+# #FF6666). Android only — iOS theme colors are static in v1 of the plugin.
+#
+# Captures the signed-out AuthView screenshot under dark mode. The color
+# assertion is a Node post-step in the runner (scripts/check-theme-color.js),
+# which asserts a large region of the dark-mode primary (#FF6666) is present.
 appId: com.clerk.clerkexpoquickstart
-# TODO: check-theme-color.js requires pngjs (install in the quickstart app).
-# Skip until theming tooling is wired up alongside custom-theme-applied.
 tags:
   - theming
   - androidOnly
-  - skip
 ---
 # Force the device to dark mode before launching the app.
 - launchApp:
@@ -15,7 +16,7 @@ tags:
       darkMode: true
 - waitForAnimationToEnd:
     timeout: 5000
-# Dev build: tap the dev server URL to connect (iOS: localhost, Android: 10.0.2.2).
+# Dev build: tap the dev server URL to connect (Android: 10.0.2.2:8081).
 - runFlow:
     when:
       visible: "Development Build"
@@ -34,13 +35,6 @@ tags:
 - waitForAnimationToEnd:
     timeout: 3000
 - runFlow: ../common/assert-signed-out.yaml
-- takeScreenshot: dark-theme-screenshot
-# Sample a pixel from the primary button. The dark theme primary is #FF6666.
-- runScript:
-    file: ../../scripts/check-theme-color.js
-    env:
-      THEME_IMAGE: dark-theme-screenshot.png
-      THEME_X: "200"
-      THEME_Y: "560"
-      THEME_EXPECTED: "#FF6666"
-      THEME_TOLERANCE: "20"
+# Written to integration/mobile/theme-dark.png (maestro's CWD). The runner's
+# theme-check post-step reads this file.
+- takeScreenshot: theme-dark

integration/mobile/flows/sign-up/email-verification.yaml

@@ -0,0 +1,5 @@
+# npm regenerates these whenever verify-themes.sh runs `npm install`. This is a
+# standalone helper dir (not a pnpm workspace package), so its lockfile/modules
+# are runtime-only and intentionally not tracked.
+node_modules/
+package-lock.json