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

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
  { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
- { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+ { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
  { "path": "./dist/vendors*.js", "maxSize": "7KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
  { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ * - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ * - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ * - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+ test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+ page,
+ }) => {
+ await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+ const handle = await page.waitForSelector('#f');
+ const frame = await handle.contentFrame();
+ if (!frame) {
+ throw new Error('iframe contentFrame() was null');
+ }
+
+ await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+ // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+ expect(page.url()).toContain('localhost');
+ expect(frame.url()).toContain('127.0.0.1');
+
+ const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+ const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+ // 1) The iframe is visible but does NOT have focus.
+ const initial = await liveState();
+ expect(initial.vis).toBe('visible');
+ expect(initial.hasFocus).toBe(false);
+
+ // 2) Focusing an element in the PARENT document does not focus the iframe.
+ await page.evaluate(() => {
+ const input = document.createElement('input');
+ document.body.appendChild(input);
+ input.focus();
+ });
+ const afterParentFocus = await liveState();
+ expect(afterParentFocus.vis).toBe('visible');
+ expect(afterParentFocus.hasFocus).toBe(false);
+ expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+ // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+ await handle.click();
+ await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+ const afterIframeFocus = await liveState();
+ expect(afterIframeFocus.hasFocus).toBe(true);
+ });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe host (parent)</title>
+ </head>
+ <body>
+ <h1>iframe host</h1>
+ <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+ <iframe
+ id="f"
+ style="width: 480px; height: 360px; border: 1px solid #ccc"
+ ></iframe>
+ <script>
+ // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+ const params = new URLSearchParams(location.search);
+ const framePath = params.get('framePath') || '/iframe-probe.html';
+ const frameSearch = params.get('frameSearch') || '';
+ const u = new URL(location.href);
+ u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+ u.pathname = framePath;
+ u.search = frameSearch;
+ u.hash = '';
+ window.__frameSrc = u.toString();
+ document.getElementById('f').src = window.__frameSrc;
+ </script>
+ </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ <title>iframe probe (no Clerk)</title>
+ </head>
+ <body>
+ <h1>iframe probe</h1>
+ <script>
+ // Records the events the embedded document actually receives, so a test can assert
+ // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+ window.__events = [];
+ const rec = type =>
+ window.__events.push({
+ type,
+ visibility: document.visibilityState,
+ hasFocus: document.hasFocus(),
+ t: Date.now(),
+ });
+ window.addEventListener('focus', () => rec('window.focus'));
+ window.addEventListener('blur', () => rec('window.blur'));
+ document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+ rec('init');
+ </script>
+ </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
  isNetworkError,
  isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  * - refresh the session cookie using a poller
- * - refresh the session cookie on tab visibility change
+ * - refresh the session cookie on tab focus and visibility change
  * - update the related cookies listening to the `token:update` event
  * - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  * - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
  }
 
  private refreshTokenOnFocus() {
-window.addEventListener('focus', () => {
+const refreshIfVisible = () => {
  if (document.visibilityState === 'visible') {
  // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
  // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
  // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
  void this.refreshSessionToken({ updateCookieImmediately: true });
  }
- });
+ };
+
+ // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+ // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+ // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+ window.addEventListener('focus', refreshIfVisible);
+ if (typeof document !== 'undefined') {
+ document.addEventListener('visibilitychange', refreshIfVisible);
+ }
  }
 
  private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
  }
 
  private updateSessionCookie(token: string | null) {
- // Only allow background tabs to update if both session and organization match
- if (!document.hasFocus() && !this.isCurrentContextActive()) {
+ // Only allow background tabs to update if both session and organization match.
+ // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+ // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+ if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
  return;
  }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
  }
  }
 
+ private inVisibleCrossOriginIframe() {
+ return inCrossOriginIframe() && document.visibilityState === 'visible';
+ }
+
  private isCurrentContextActive() {
  const activeContext = this.activeCookie.get();
  if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+ sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+ clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+ activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+ inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+ createDevBrowser: () => ({
+ clear: vi.fn(),
+ setup: vi.fn(() => Promise.resolve()),
+ getDevBrowser: vi.fn(() => 'deadbeef'),
+ refreshCookies: vi.fn(),
+ }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+ const actual = await importOriginal<Record<string, unknown>>();
+ return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+ Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+ Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+ const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+ const clerkStub = {
+ publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+ frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+ loaded: true,
+ session: { id: 'sess_active', getToken },
+ organization: null,
+ user: {},
+ client: {},
+ handleUnauthenticated: vi.fn(),
+ } as any;
+ const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+ const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+ const emitTokenUpdate = (raw: string) =>
+ eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+ let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.inCrossOriginIframe.mockReturnValue(false);
+ mocks.activeContextCookie.get.mockReturnValue(undefined);
+ getToken.mockResolvedValue('fresh-jwt');
+ setFocus(true);
+ setVisibility('visible');
+ });
+
+ afterEach(() => {
+ service?.stopPollingForToken();
+ service = undefined;
+ // The service registers listeners on the shared event bus on construction.
+ eventBus.off(events.TokenUpdate);
+ eventBus.off(events.UserSignOut);
+ eventBus.off(events.EnvironmentUpdate);
+ });
+
+ it('registers both focus and visibilitychange listeners', async () => {
+ const windowSpy = vi.spyOn(window, 'addEventListener');
+ const documentSpy = vi.spyOn(document, 'addEventListener');
+
+ service = await createService();
+
+ expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+ });
+
+ it('writes the session cookie on token:update when the tab is focused', async () => {
+ service = await createService();
+
+ emitTokenUpdate('jwt-focused');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+ });
+
+ it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ service = await createService();
+ setFocus(false);
+
+ emitTokenUpdate('jwt-blocked');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+ });
+
+ it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+
+ emitTokenUpdate('jwt-iframe');
+
+ expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+ });
+
+ it('does not write in a cross-origin iframe while it is hidden', async () => {
+ mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('hidden');
+
+ emitTokenUpdate('jwt-hidden');
+
+ expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+ });
+
+ it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+ mocks.inCrossOriginIframe.mockReturnValue(true);
+ service = await createService();
+ setFocus(false);
+ setVisibility('visible');
+ getToken.mockResolvedValue('jwt-on-visible');
+ mocks.sessionCookie.set.mockClear();
+
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+ expect(getToken).toHaveBeenCalled();
+ });
+});