fix(clerk-js): refresh session cookie on visibilitychange in cross-origin iframes by jacekradko · Pull Request #8923 · clerk/javascript

jacekradko · 2026-06-18T20:57:24Z

Apps running inside a cross-origin iframe (Replit's preview pane is the reported case) could get 401s after the user tabbed away and came back, until a manual page refresh. clerk-js refreshed the session cookie only on the window focus event, which never fires inside a cross-origin iframe on tab re-activation, and it gated the cookie write on document.hasFocus(), which a visible-but-embedded frame never reports. So the token went stale and the app's refetch-on-focus hit it.

This adds a visibilitychange trigger next to the existing focus one (visibilitychange does propagate into iframes) and lets a visible cross-origin iframe write the refreshed cookie. The gate change is additive: top-level multi-tab ownership still keys on document.hasFocus(), so the active-organization handoff from #3786 is untouched. The subtlety worth a look is the typeof document !== 'undefined' guard on the new listener. The mockNativeRuntime path constructs AuthCookieService with a window but no document, and an unguarded document.addEventListener throws there.

The cross-origin focus/visibility semantics this relies on are pinned down by a real-browser test (iframe-session-refresh.spec.ts): a visible cross-origin iframe reports hasFocus() === false and only receives focus when explicitly clicked into. The behavioral wiring (refresh on visibilitychange when visible-but-unfocused-in-iframe) is covered by new AuthCookieService unit tests, which had no coverage before. One honest caveat: the full "background the tab until the cookie expires, then watch it heal" leg cannot run in automated Chromium (it won't background a page, and the worker poller keeps the token fresh), so that end-to-end path is being verified manually against a real embedded app.

Follow-up filed as #8921: clerk_active_context is not partition-aware, which makes the write-gate arbitration non-deterministic in CHIPS iframes. Left out of scope here.

Summary by CodeRabbit

New Features
- Session cookies now refresh when a tab becomes visible again, preventing stale tokens and subsequent authentication errors
- Cross-origin embedded iframes can now write refreshed session cookies to maintain valid authentication state
Tests
- Added integration tests validating iframe focus and visibility behavior across cross-origin contexts

…frames The session-cookie refresh listened only to window 'focus', which never fires inside a cross-origin iframe on tab re-activation, and the cookie write was gated on document.hasFocus() (always false for an embedded frame). Embedded apps (e.g. a preview pane) could keep a stale token after tab-back and get 401s until a manual refresh. Now also refresh on visibilitychange (which reaches iframes) and let a visible cross-origin iframe write the cookie. Top-level multi-tab behavior is unchanged. Partition-aware clerk_active_context is tracked separately (#8921).

changeset-bot · 2026-06-18T20:57:28Z

🦋 Changeset detected

Latest commit: 6e14da1

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch

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 · 2026-06-18T20:57:31Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 18, 2026 8:58pm
swingset	Ready	Preview, Comment	Jun 18, 2026 8:58pm

coderabbitai · 2026-06-18T20:57:40Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 5b357364-69b2-4d88-805e-c990f6f8e82d

📥 Commits

Reviewing files that changed from the base of the PR and between 15b059c and 6e14da1.

📒 Files selected for processing (6)

.changeset/iframe-session-visibility-refresh.md
packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts
packages/clerk-js/sandbox/public/iframe-host.html
packages/clerk-js/sandbox/public/iframe-probe.html
packages/clerk-js/src/core/auth/AuthCookieService.ts
packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

📝 Walkthrough

Walkthrough

AuthCookieService is extended to register a visibilitychange listener (in addition to focus) that triggers session token refresh with immediate cookie update when the page becomes visible. Cookie-write eligibility in updateSessionCookie is expanded to allow writes from visible cross-origin iframes. Sandbox HTML pages and a Playwright integration test are added to validate iframe focus/visibility browser semantics.

Changes

iframe visibilitychange session cookie refresh

Layer / File(s)	Summary
AuthCookieService: visibilitychange listener and iframe eligibility `packages/clerk-js/src/core/auth/AuthCookieService.ts`	Adds `inCrossOriginIframe` import, refactors the focus handler into a shared `refreshIfVisible` callback registered on both `window` `focus` and `document` `visibilitychange`, expands `updateSessionCookie` write eligibility to visible cross-origin iframes, and adds the private `inVisibleCrossOriginIframe()` helper.
Unit tests for cookie refresh and iframe eligibility `packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts`	Adds Vitest hoisted mocks, focus/visibility toggle helpers, and tests covering listener registration, focused/unfocused cookie writes, visible/hidden cross-origin iframe eligibility, and `visibilitychange`-triggered refresh.
Sandbox iframe test infrastructure and integration spec `packages/clerk-js/sandbox/public/iframe-host.html`, `packages/clerk-js/sandbox/public/iframe-probe.html`, `packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts`, `.changeset/iframe-session-visibility-refresh.md`	Adds cross-origin iframe host/probe HTML pages and a Playwright spec that validates `hasFocus()`/`visibilityState` semantics inside the iframe to ground the session-refresh fix, plus the patch-release changeset entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

clerk_active_context cookie is not partition-aware (non-deterministic session-cookie write gate in CHIPS/partitioned cross-origin iframes) #8921: This PR directly implements the iframe session-cookie refresh via visibilitychange events described in that issue, including the AuthCookieService write-gate change referenced there.

Suggested labels

clerk-js, testing

🐇 When the tab comes back to light,
A cookie refresh sets things right!
No more stale tokens, no more 401 woes,
The iframe blinks and the session flows.
Hop hop, visibility saves the day! 🍪✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding session cookie refresh on visibilitychange events specifically for cross-origin iframes. It directly reflects the primary bug fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

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

pkg-pr-new · 2026-06-18T20:59:40Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 6e14da1

github-actions · 2026-06-18T21:00:22Z

API Changes Report

Generated by Break Check on 2026-06-18T21:00:20.313Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 6e14da1.}

vercel Bot deployed to Preview – clerk-js-sandbox June 18, 2026 20:57 View deployment

github-actions Bot added the clerk-js label Jun 18, 2026

vercel Bot deployed to Preview – swingset June 18, 2026 20:58 View deployment

jacekradko requested a review from brkalow June 19, 2026 01:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(clerk-js): refresh session cookie on visibilitychange in cross-origin iframes#8923

fix(clerk-js): refresh session cookie on visibilitychange in cross-origin iframes#8923
jacekradko wants to merge 1 commit into
mainfrom
jacek/clerk-js-iframe-visibility-refresh

jacekradko commented Jun 18, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jun 18, 2026

Uh oh!

vercel Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 18, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Suggested labels

Uh oh!

pkg-pr-new Bot commented Jun 18, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jacekradko commented Jun 18, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jun 18, 2026

🦋 Changeset detected

Uh oh!

vercel Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Suggested labels

Uh oh!

pkg-pr-new Bot commented Jun 18, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026

API Changes Report

Summary

No API Changes Detected

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jacekradko commented Jun 18, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jun 18, 2026 •

edited

Loading

coderabbitai Bot commented Jun 18, 2026 •

edited

Loading