test(expo): add a verify skill that drives the expo-native fixture

[mikepitre]

Description

Adds verify-clerk-expo, a verification skill for @clerk/expo at .claude/skills/verify-clerk-expo/. An agent changing packages/expo can use it to prove the change on a real iOS simulator or Android emulator against a real Clerk dev instance, and attach the video to the PR. It builds on the expo-native host from #10052, and has the same layout and verbs as the clerk-ios and clerk-android verification skills.

Any agent finds it from the new Verifying changes section in AGENTS.md. .cursor/skills/verify-clerk-expo is a committed relative symlink to the same directory for Cursor; there is one copy of the files. The CLI is .claude/skills/verify-clerk-expo/bin/control-clerk-expo, and it runs from any directory. The skill is named verify-clerk-expo, not verify, so it leaves Claude Code's built-in /verify alone.

What an agent gets:

• control-clerk-expo up --platform ios|android builds the fixture as a Debug dev client, leases a lane device, and installs the app. It also starts tsdown --watch in packages/expo and an expo start on the lane's own Metro port. iOS lanes use 8082 to 8085 and Android lanes use 8086 and 8087, so lanes never share a port.
• The build key covers only native inputs: packages/expo/ios or android, app.plugin.js, src/specs/, expo-module.config.json, package.json, the native code and package.json of expo-google-signin and expo-biometrics, and the fixture's app config, pnpm-workspace.yaml, and local module. A change under packages/expo/src reuses the dev client and reaches the app on the next launch through the watch build and Metro. A native change rebuilds it.
• Scope: the skill builds and serves @clerk/expo and its Expo-module siblings (expo-biometrics, expo-google-signin, expo-passkeys) by itself. Changes to its other workspace dependencies (@clerk/clerk-js, @clerk/shared, @clerk/react) are verified after one build step the developer runs: when any of them, or a workspace package it bundles, has source newer than its dist, up and run refuse with NOT_READY before anything launches and print pnpm turbo build --filter=@clerk/expo^....
• Before every launch, run checks that the app will load current JS. Stale Expo-module siblings are rebuilt with Metro stopped. The @clerk/expo watch build must have caught up and settled. Then run fingerprints the content of every bundled dist file of @clerk/expo and its workspace dependencies, fetches the dev client's bundle from Metro, and fingerprints again. Each Metro revision is remembered with the content it was first seen with, so a revision that lags a newer edit is never confirmed, and a Metro whose first bundle cannot be dated against the current dist is restarted. Two matching reads are required. A rewrite with identical content waits for nothing. A 500 while dist is being rewritten is retried; a bundling error fails once the outputs have settled. When Metro's watcher misses a write, run touches the files after 5 seconds. If Metro never catches up, run fails with NOT_READY and names the Metro log, instead of running specs against old code. up bundles once before it reports ready, and a runtime step that fails stops the Metro and watch build that call started. Metro runs with EXPO_OFFLINE=1, because the Expo CLI's calls to expo.dev went through this Mac's HTTPS proxy and timed out.
• control-clerk-expo run <feature> runs the golden specs for that feature with video, screenshots, and every verify.state the host reported. The features are native-auth-view, user-button-and-profile, custom-flow-sign-in, custom-flow-sign-up, token-cache-persistence, and native-js-sync.
• The auth specs drive the real forms with +clerk_test users. The request-code specs stop at the code screen. The complete specs type the published test code and are tagged form-entry, so a runtime that must not type codes can pass --skip form-entry.
• control-clerk-expo down releases the devices, stops Metro and the watch build, and deletes the users the run created. It keeps the evidence.
• A spec tagged known-bug proves a defect that is not fixed yet and is skipped unless --include known-bug is passed. The inline AuthView dismiss test carries it today: on iOS, the close button of an inline dismissible AuthView does not fire onDismiss.

The complete specs were authored here but not run by this PR's author, whose agent runtime does not type sign-in codes into an app that talks to a hosted Clerk instance. Every auth flow was proven up to its code screen with --skip form-entry, and the complete specs are left for CI or a runtime that allows form entry.

src/core/, src/platform/ios/, and specs/fixtures.ts are byte-identical copies from clerk/clerk-ios#624. src/platform/android/ is byte-identical to the clerk-android skill in clerk/clerk-android#1042. src/host.ts, specs/native.ts, the golden specs, and features/ are specific to Expo. The skill's own .gitignore covers its .verify/ state and evidence and its specs/explored/, so the root .gitignore is unchanged. .prettierignore skips the skill's .ts files, because the shared copies keep the clerk-ios formatting. Markdown and JSON in the skill still go through Prettier. The skill sits outside every workspace package, so root lint, root format, and @clerk/expo's tests never see it. .claude/skills/README.md says this skill is agent-neutral and that Cursor reads it through the symlink.

Android specs find native views by text, because the clerk-android release that @clerk/expo pins has no test tags yet. iOS specs use the clerk.* accessibility identifiers. On Android the runtime also marks the expo-dev-menu onboarding finished, because a -read-only emulator forgets it on every boot. On iOS, app.log keeps the fixture process's own native log lines; JS console lines from a Debug dev client go to Metro, and the skill points there.

test/freshness.test.ts covers the gate's decisions and drives its loop with a fake Metro: a lagging revision after a second edit, a transient 500 while dist refills, a settled 500, a Metro restart, the touch for a missed watcher event, and the scope split. No live run has needed the touch yet. Metro and watch logs append across restarts; copying each run's slice of the Metro log into its run directory would need a hook in the shared core, so iOS JS log lines are read from .verify/runtime/ by runId.

down --platform <p> releases only that platform's lane but stops the worktree's whole runtime, because core's process ledger entries don't record a platform. The skill documents this. Recording the platform on those entries is a follow-up for the shared core in clerk/clerk-ios#624, which every repo copies.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other: test tooling

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 5253fee

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 3, 2026 12:50pm UTC
swingset	Ready	Preview	Oct 3, 2026 12:50pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}