feat(js): send tab state with session token requests

[nikosdouvlis]

Why
Session activity counts pretty much every /tokens call as user activity, but backgrounded tabs keep refreshing tokens on a timer, so idle sessions look active. There's nothing on the wire to tell a foreground mint from a background one.

What changed
Non-template session token requests now include a tab_state body param with one of focused, visible or hidden, derived at request time: document.hasFocus() wins, then visibilityState, and the param is omitted when document doesn't exist (service workers, headless runtimes). Template tokens and touch are untouched.

Blockers / related
Merging is safe but releasing isn't yet: FAPI rejects unknown form params with a 422, so this must not go out in a clerk-js release before clerk/clerk_go #20618 is deployed. The Session Minter passes the param through untouched, no changes needed there.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 22, 2026 8:42pm
swingset	Ready	Preview, Comment	Jul 22, 2026 8:42pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 816773d

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

This PR includes changesets to release 4 packages

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

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

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

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-22T20:43:49.236Z

Summary

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

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/ui	./styles.css	./styles.css

---

@clerk/ui

Version: 1.25.7 → 1.25.6
Recommended bump: MAJOR

Subpath ./styles.css

🔴 Breaking Changes (1)

Changed: ./styles.css

Subpath export ./styles.css was removed

Subpath ./internal

🟡 Non-breaking Changes (1)

Modified: ElementsConfig

// ... 31 unchanged lines elided ...
    logoImage: WithOptions;
    logoGroup: WithOptions;
    logoGroupItem: WithOptions;
-   logoGroupItemContainer: WithOptions;
    logoGroupIcon: WithOptions;
    logoGroupSeparator: WithOptions;
    listGroup: WithOptions;
// ... 518 unchanged lines elided ...

Static analyzer: Breaking change in type alias ElementsConfig: Type changed: {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W… → {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W…

🤖 AI review (reclassified as non-breaking) (85%): The diff shows that logoGroupItemContainer was removed and listGroupContent was added (plus other minor additions); ElementsConfig is used only as the key source for the Elements mapped type (output/read direction), so adding new keys is non-breaking, but removing logoGroupItemContainer could be breaking if consumers reference that key. However, looking at the before/after more carefully: before has logoGroupItemContainer and after does not, while after adds listGroupContent. The removal of a key from this type is observable only if consumers read/use that specific element key. Since ElementsConfig is an internal type used to derive Elements (an output union), and consumers only read the resulting Elements type rather than constructing ElementsConfig values, the removal of a key narrows the output union, which is non-breaking for consumers reading element selectors. The addition of listGroupContent is additive.

---

Report generated by Break Check

_{Last ran on 816773d.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b249ce0-0ba9-4612-8e8c-3d135b1c3953

📥 Commits

Reviewing files that changed from the base of the PR and between 524fe1a and 816773d.

📒 Files selected for processing (3)

• .changeset/tokens-tab-state.md
• packages/clerk-js/src/core/resources/Session.ts
• packages/clerk-js/src/core/resources/__tests__/Session.test.ts

🔗 Linked repositories identified

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

• clerk/clerk_go (manual) → reviewed against open PR #20618 nikos/tokens-tab-state instead of the default branch
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)

🚧 Files skipped from review as they are similar to previous changes (3)

• .changeset/tokens-tab-state.md
• packages/clerk-js/src/core/resources/Session.ts
• packages/clerk-js/src/core/resources/tests/Session.test.ts

---

📝 Walkthrough

Walkthrough

Session token requests now include tab_state values derived from browser focus and visibility state when applicable. Non-browser environments omit the parameter. Tests cover focused, visible, hidden, and document-absent cases, and a changeset documents the patch release.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding tab state to session token requests.
Description check	✅ Passed	The description is directly related to the change and accurately explains the behavior, scope, and release blocker.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 816773d