fix(headless): keep the element mounted when an exit is interrupted

[alexcarpenter]

Description

useTransition never cancelled the pending unmount when open flipped back true mid-exit. Element unmounted once the retargeted transition settled, then immediately remounted with data-starting-style.

In Flow: reverse steps mid-animation → returning step slides back into place, then snaps off-screen and replays its entrance.

useAnimationsFinished now returns a cancel handle; useTransition returns it as effect cleanup.

Same latent leak exists at accordion-panel.tsx:73 and collapsible-panel.tsx:71 (separate hook instances, own effects) — not touched here. Follow up required.

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:

[changeset-bot]

🦋 Changeset detected

Latest commit: e573d9d

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 (UTC)
clerk-js-sandbox	Ready	Preview	Aug 29, 2026 11:53am
swingset	Ready	Preview	Aug 29, 2026 11:53am

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: e573d9d

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: ef0201ae-6b84-45b4-8350-5da7eaed2077

📥 Commits

Reviewing files that changed from the base of the PR and between d58d913 and e573d9d.

📒 Files selected for processing (6)

• .changeset/wild-buttons-repeat.md
• packages/headless/src/hooks/use-animations-finished.test.ts
• packages/headless/src/hooks/use-animations-finished.ts
• packages/headless/src/hooks/use-transition.test.ts
• packages/headless/src/hooks/use-transition.ts
• packages/headless/src/primitives/flow/flow.test.tsx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

useAnimationsFinished now returns a cancellation function for pending animation waits. Transition tests cover reopening during an interrupted exit without unmounting or restarting the entrance animation. Flow tests add shared requestAnimationFrame flushing and verify the same interrupted-exit behavior for returning steps.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to e573d

This localized change keeps elements mounted when an exit is interrupted, preventing the documented remount and visual snap behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the primary fix: keeping elements mounted when exit transitions are interrupted.
Description check	✅ Passed	The description directly explains the interrupted exit transition bug, the cancellation-handle fix, affected behavior in Flow, and the related issue that remains out of scope.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

---

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