WIP: Wire up Mosaic Reverification

[Ephem]

Description

This should be mostly complete and is open to review and feedback, but keeping it WIP until I can do more testing.

Some things are still missing, like UI states for loading/unavailable etc

This PR wires up the Mosaic Reverification logic.

• Moves the Reverification block into a new /features folder
  • Maybe /blocks are already meant to also include logic? If so I'll move it back, I moved it because everything in there seems to be pure UI right now, but might just be because we haven't wired things up yet.
  • Didn't want to place it in the root, that doesn't scale
• A new useReverificationWithState hook - Simple wrapper around useReverification as per the custom UI part of the useReverification docs
  • Also handles resetting verification state when session changes
• Model
  • Business logic, handles a bunch of logic around first/second factor, different strategies etc
  • Exposes the following actions:
    • start
    • verifyPasskey
    • prepare
    • attempt
    • finish
    • cancel
  • Note how the above are not split by method or factor, you pass those in and the model actions handles the logic
  • The result of these actions are parsed into a format that is accessible to the controller
    • For example it picks a starting method, handles filtering out passkey if webAuthn is not accessible etc
• Controller - Consists of a few parts:
  • Semi-complex state machine
  • Derives data from model+machine for the view layer
  • Wraps functions for the view layer
  • There are a few different things that mainly drives the UI
    • controller.status - The overall status - idle, unavailable, loading, ready - Represents "full card states"
    • When that's ready - controller.step represents which part of the flow we are in, method-picker, password etc
    • controller.isPending - Progress state for the current card, if status if a full page loading state, this is a inline spinner

The way this works is:

• First call the hook:
  • const [deleteAction, reverificationState] = useReverificationWithState(deleteMutation);
• When deleteAction is called, and the API responds that it needs reverification, reverificationState.isActive goes true
• Render <Reverification {...reverificationState}> - This will drive the process and when resolved:
  • reverificationState.isActive is going to go false again
  • The deleteMutation gets retried

So if you pass that deleteAction into another machine, when it gets called and needs reverification, it's going to stay pending until resolved. That means we can render <Reverification> inside another flow, without that machine having to know about it.

I'll try to stack a PR on top of this to showcase how it can be used, and to make testing easier. I'm sure there might be some tweaks we want to make around how this interacts with other UI etc.

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:

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 3, 2026 1:08pm UTC
swingset	Ready	Preview	Sep 3, 2026 1:08pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 60cff5d

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

[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

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9650

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9650

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9650

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9650

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9650

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9650

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9650

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9650

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9650

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9650

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9650

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9650

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9650

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9650

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9650

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9650

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9650

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9650

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9650

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9650

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9650

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9650

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9650

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9650

commit: 60cff5d