docs: explain Chrome focus emulation in window focus refetching guide

[chungyo]

🎯 Changes

When Chrome DevTools has Emulate a focused page enabled, switching away from a tab and returning does not trigger the default window focus refetching behavior. Chrome keeps the page visible and suppresses the visibilitychange events used by TanStack Query.

Add a troubleshooting note to the window focus refetching guide that explains this behavior and shows where to disable the setting. The note links to the Chrome DevTools documentation.

Related discussion: #6568

Validation:

• Checked the changed Markdown with the repository's Prettier configuration.
• Ran the repository's scripts/verify-links.ts via a local bundle: all 1,657 Markdown files passed its relative-link checks.
• Verified actual tab switching and local HTTP requests using the unmodified query-core source in Chromium: a stale query refetched normally, while focus emulation suppressed visibility events and refetching. Refetching resumed after the emulation CDP session ended. The DevTools checkbox itself was not automated.
• The full pnpm run test:pr suite and docs-site preview were not run for this prose-only change.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Documentation
  • Added troubleshooting guidance for queries that do not refetch after returning to a browser tab when Chrome DevTools’ “Emulate a focused page” setting is enabled.
  • Included steps to disable the setting and verify window focus refetching behavior.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-09T13:18:13.860938Z	6943c4d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 9fcb5e69-ed72-4cab-8e14-100359e148e3

📥 Commits

Reviewing files that changed from the base of the PR and between f7c6be3 and 6943c4d.

📒 Files selected for processing (1)

• docs/framework/react/guides/window-focus-refetching.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds troubleshooting guidance for stale queries that do not refetch when Chrome DevTools emulates a focused page. The guide explains the effect on document.visibilityState and visibilitychange events and links to Chrome DevTools documentation.

Changes

Window focus refetching

Layer / File(s)	Summary
Focus emulation troubleshooting docs/framework/react/guides/window-focus-refetching.md	Adds a troubleshooting section that explains how Chrome DevTools focus emulation prevents visibility changes and instructs readers to disable the setting before testing tab switches.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 6943c

This adds Chrome DevTools troubleshooting guidance for focus-triggered query refetching without changing runtime behavior, and no merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the documentation change about Chrome focus emulation in window focus refetching.
Description check	✅ Passed	The description explains the change, motivation, validation performed, test limitations, and release impact. It follows the required template. The unchecked contribution and AI-assistance checklist it…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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