iAPI Docs: Add client-side navigation compatibility guide

[DAreRodz]

What?

Adds a new documentation page: Client-Side Navigation Compatibility Guide for the Interactivity API.

Why?

Block developers and theme authors need clear guidance on what makes their code compatible with client-side navigation. Without this, developers may unknowingly introduce patterns that break client-side navigation — causing fallbacks to full page reloads or potentially breaking the site, degrading the user experience.

There was no centralized reference for CSN compatibility, nor a checklist that developers could use to verify compatibility before declaring their blocks compatible.

How?

Adds a new document at docs/reference-guides/interactivity-api/core-concepts/client-side-navigation-compatibility.md and links it from the Core Concepts README. The guide covers:

• Declaring compatibility in block.json via supports.interactivity.clientNavigation.
• What makes a block compatible — non-interactive blocks, Interactivity API blocks, and blocks using other libraries.
• CSS requirements — no dynamic CSS injection, no runtime stylesheet modifications, stable CSS selectors (with wp_unique_id_from_values() as the recommended alternative to wp_unique_id()), and selector consistency across navigations.
• JavaScript requirements — use of script modules instead of regular scripts, and how to handle script modules outside blocks (e.g., classic PHP themes) via wp_register_script_module() with loadOnClientNavigation.
• HTML requirements — consistent HTML structures, proper use of data-wp-key for dynamic lists, avoiding DOM mutations outside the Interactivity API (with data-wp-watch as the escape hatch), and using attachTo for HTML outside router regions.
• Compatibility checklist — a pre-flight checklist for developers to verify before marking a block as CSN-compatible.
• Quick reference table summarizing block types and their compatibility status.

The guide is written to be useful for both block developers and classic PHP theme/plugin authors.

[github-actions]

Flaky tests detected in e390127.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23620565336
📝 Reported issues:

• [Flaky Test] Navigates the items list via UP/DOWN arrow keys #64334 in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js
• [Flaky Test] Should render and migrate legacy openSubmenusOnClick blocks #75559 in /test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js
• [Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: DAreRodz <[email protected]>
Co-authored-by: luisherranz <[email protected]>
Co-authored-by: ryanwelcher <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ryanwelcher]

Is there a definitive list of which packages are compatble?

[luisherranz]

I added a bunch of corrections and refinements in a6bbb97. Can you review them to make sure they are all correct?

I added cross-references to the CSN Compatibility guide across the documentation for better discoverability:

• Client-Side Navigation guide: Added a callout near the top of the page, and a link in the "Ensuring script modules load during navigation" section where clientNavigation in block.json is explained.
• Router package README: Extended the existing callout to also mention the compatibility guide.
• Block Supports reference: Simplified the clientNavigation sub-property description to defer to the compatibility guide instead of inlining partial guidelines.
• Interactivity API FAQ: Linked the "client-side navigation" mention to the CSN guide.
• toc.json and manifest.json: Added entries for both the Client-Side Navigation guide and the Client-Side Navigation Compatibility guide, which were missing from the handbook's table of contents and manifest.

And other things that I think should be clarified below.

[luisherranz]

Thanks for the changes, David 🙂

LGTM now! Approving 👍