From 814f50533db98920b3142e95e2c157bdcbb3c2c1 Mon Sep 17 00:00:00 2001
From: David <david.arenas@automattic.com>
Date: Fri, 7 Aug 2026 14:18:43 +0200
Subject: [PATCH 1/2] Interactivity API: mark server-rendered style assets with
 data-wp-router-managed.

---
 .../class-wp-interactivity-api.php            | 193 +++++++
 .../wpInteractivityAPI-wp-router-managed.php  | 525 ++++++++++++++++++
 tests/phpunit/tests/template.php              |   3 +
 3 files changed, 721 insertions(+)
 create mode 100644 tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php

diff --git a/src/wp-includes/interactivity-api/class-wp-interactivity-api.php b/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
index 62bfc29cfc03f..dd838edd92bb2 100644
--- a/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
+++ b/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
@@ -95,6 +95,20 @@ final class WP_Interactivity_API {
 	 */
 	private $has_processed_router_region = false;
 
+	/**
+	 * Flag that indicates whether all the blocks rendered on the page support
+	 * client-side navigation.
+	 *
+	 * It starts as `true` and it is set to `false` as soon as a block that does
+	 * not declare support for client-side navigation is rendered. It is used to
+	 * decide whether the server-generated style assets can be marked with the
+	 * `data-wp-router-managed` attribute.
+	 *
+	 * @since 7.2.0
+	 * @var bool
+	 */
+	private $all_blocks_support_client_navigation = true;
+
 	/**
 	 * Set of script modules that can be loaded after client-side navigation.
 	 *
@@ -399,11 +413,179 @@ public function register_script_modules() {
 	 *
 	 * @since 6.5.0
 	 * @since 6.9.0 Adds support for client-side navigation in script modules.
+	 * @since 7.2.0 Tracks the page-wide client-side navigation support and adds the `data-wp-router-managed`
+	 *              attribute to server-generated style assets.
 	 */
 	public function add_hooks() {
 		add_filter( 'script_module_data_@wordpress/interactivity', array( $this, 'filter_script_module_interactivity_data' ) );
 		add_filter( 'script_module_data_@wordpress/interactivity-router', array( $this, 'filter_script_module_interactivity_router_data' ) );
 		add_filter( 'wp_script_attributes', array( $this, 'add_load_on_client_navigation_attribute_to_script_modules' ) );
+
+		if ( ! is_admin() ) {
+			/*
+			 * The tracked support is only read on the front end, so there is no
+			 * need to inspect every rendered block in admin requests.
+			 */
+			add_filter( 'render_block_data', array( $this, 'filter_render_block_data_client_navigation_support' ) );
+
+			/*
+			 * The priority is set to 20 so this filter runs after the one added by
+			 * `wp_hoist_late_printed_styles()`, which uses the default priority and
+			 * can move style tags into the HEAD. That way, every style asset present
+			 * in the final markup gets the attribute.
+			 *
+			 * Note that adding this filter is what makes core start the template
+			 * enhancement output buffer, as documented in
+			 * `wp_should_output_buffer_template_for_enhancement()`.
+			 */
+			add_filter( 'wp_template_enhancement_output_buffer', array( $this, 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
+		}
+	}
+
+	/**
+	 * Tracks whether all the blocks rendered on the page support client-side
+	 * navigation.
+	 *
+	 * This method is a `render_block_data` filter callback that only inspects the
+	 * blocks being rendered; it always returns the parsed block unmodified. As
+	 * soon as a block that does not declare support for client-side navigation is
+	 * found, client-side navigation is considered unsupported for the whole page.
+	 *
+	 * The compatibility rules mirror the ones used by
+	 * {@see block_core_query_disable_enhanced_pagination()}: blocks without a
+	 * block name, i.e. freeform classic HTML, do not break compatibility, while
+	 * named blocks require either `supports.interactivity` or
+	 * `supports.interactivity.clientNavigation` to be `true`.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param array $parsed_block The block being rendered.
+	 * @return array Returns the parsed block, unmodified.
+	 */
+	public function filter_render_block_data_client_navigation_support( $parsed_block ) {
+		if ( ! $this->all_blocks_support_client_navigation ) {
+			return $parsed_block;
+		}
+
+		if ( ! isset( $parsed_block['blockName'] ) ) {
+			return $parsed_block;
+		}
+
+		$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $parsed_block['blockName'] );
+
+		/*
+		 * Client side navigation can be true in two states:
+		 *  - supports.interactivity = true;
+		 *  - supports.interactivity.clientNavigation = true;
+		 */
+		$supports_client_navigation = ( isset( $block_type->supports['interactivity']['clientNavigation'] ) && true === $block_type->supports['interactivity']['clientNavigation'] )
+			|| ( isset( $block_type->supports['interactivity'] ) && true === $block_type->supports['interactivity'] );
+
+		if ( ! $supports_client_navigation ) {
+			$this->all_blocks_support_client_navigation = false;
+		}
+
+		return $parsed_block;
+	}
+
+	/**
+	 * Adds the `data-wp-router-managed` attribute to all the style assets of the
+	 * page.
+	 *
+	 * This method is a `wp_template_enhancement_output_buffer` filter callback, so
+	 * it receives the complete server-generated markup. Working on the final
+	 * buffer is what guarantees full-page coverage: every `<style>` element and
+	 * every `<link rel="stylesheet">` element is marked regardless of how or when
+	 * it was printed. The only exceptions are the style assets contained in
+	 * `noscript` and `template` elements, which are not rendered as part of the
+	 * document.
+	 *
+	 * The attribute lets the Interactivity API router tell server-rendered style
+	 * assets apart from the ones injected later by JavaScript, so the latter can
+	 * be preserved when the head is diffed during a client-side navigation.
+	 *
+	 * The attribute is only added when all the blocks rendered on the page support
+	 * client-side navigation, at least one router region has been processed, and
+	 * client-side navigation has not been disabled.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string|mixed $buffer The template output buffer.
+	 * @return string|mixed The template output buffer, with the attribute added to the style assets.
+	 */
+	public function filter_template_output_buffer_add_router_managed_attribute( $buffer ) {
+		if ( ! is_string( $buffer ) ) {
+			return $buffer;
+		}
+
+		if ( ! $this->has_processed_router_region || ! $this->all_blocks_support_client_navigation ) {
+			return $buffer;
+		}
+
+		/*
+		 * The configuration is read directly instead of through
+		 * `WP_Interactivity_API::config()` because that method would create an
+		 * empty `core/router` entry as a side effect of reading it.
+		 */
+		if ( ! empty( $this->config_data['core/router']['clientNavigationDisabled'] ) ) {
+			return $buffer;
+		}
+
+		$processor = new WP_HTML_Tag_Processor( $buffer );
+
+		/*
+		 * Depth of the `noscript` and `template` elements currently open. The
+		 * contents of `template` elements are inert until they are cloned by
+		 * JavaScript, and `noscript` elements are only rendered when scripting is
+		 * disabled, so the style assets inside them must not be marked as
+		 * server-generated ones.
+		 */
+		$inert_depth = 0;
+
+		while ( $processor->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
+			$tag_name  = $processor->get_tag();
+			$is_closer = $processor->is_tag_closer();
+
+			if ( 'NOSCRIPT' === $tag_name || 'TEMPLATE' === $tag_name ) {
+				if ( $is_closer ) {
+					$inert_depth = max( 0, $inert_depth - 1 );
+				} elseif ( ! $processor->has_self_closing_flag() ) {
+					/*
+					 * Self-closing tags are only meaningful in foreign content,
+					 * i.e. inside SVG or MathML, where they have no closing tag.
+					 * They are skipped so they do not leave the depth counter
+					 * stuck for the rest of the document.
+					 */
+					++$inert_depth;
+				}
+				continue;
+			}
+
+			if ( $is_closer || $inert_depth > 0 ) {
+				continue;
+			}
+
+			if ( 'STYLE' === $tag_name ) {
+				$processor->set_attribute( 'data-wp-router-managed', true );
+				continue;
+			}
+
+			if ( 'LINK' !== $tag_name ) {
+				continue;
+			}
+
+			$rel = $processor->get_attribute( 'rel' );
+			if ( ! is_string( $rel ) ) {
+				continue;
+			}
+
+			$rel_tokens = preg_split( '/[\t\n\f\r ]+/', strtolower( $rel ), -1, PREG_SPLIT_NO_EMPTY );
+			if ( is_array( $rel_tokens ) && in_array( 'stylesheet', $rel_tokens, true ) ) {
+				$processor->set_attribute( 'data-wp-router-managed', true );
+			}
+		}
+
+		return $processor->get_updated_html();
 	}
 
 	/**
@@ -1485,6 +1667,17 @@ class="wp-interactivity-router-loading-bar"
 HTML;
 	}
 
+	/**
+	 * Checks whether a `data-wp-router-region` directive has been processed.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return bool Whether a router region has been processed on the page.
+	 */
+	public function has_router_region(): bool {
+		return $this->has_processed_router_region;
+	}
+
 	/**
 	 * Processes the `data-wp-router-region` directive.
 	 *
diff --git a/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php b/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php
new file mode 100644
index 0000000000000..e25e8fbad05e9
--- /dev/null
+++ b/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php
@@ -0,0 +1,525 @@
+<?php
+/**
+ * Unit tests covering the `data-wp-router-managed` attribute functionality of
+ * the WP_Interactivity_API class.
+ *
+ * @package WordPress
+ * @subpackage Interactivity API
+ *
+ * @coversDefaultClass WP_Interactivity_API
+ *
+ * @group interactivity-api
+ */
+class Tests_WP_Interactivity_API_WP_Router_Managed extends WP_UnitTestCase {
+	/**
+	 * Instance of WP_Interactivity_API.
+	 *
+	 * @var WP_Interactivity_API
+	 */
+	protected $interactivity;
+
+	/**
+	 * Original WP_Hook instance associated to `wp_footer`.
+	 *
+	 * @var WP_Hook
+	 */
+	protected $original_wp_footer;
+
+	/**
+	 * Original instance associated to `wp_styles`.
+	 *
+	 * @var WP_Styles
+	 */
+	protected $original_wp_styles;
+
+	/**
+	 * Names of the block types registered by the tests.
+	 *
+	 * @var string[]
+	 */
+	protected $registered_block_types = array();
+
+	/**
+	 * Set up.
+	 */
+	public function set_up() {
+		parent::set_up();
+		$this->interactivity = new WP_Interactivity_API();
+
+		// Removes all hooks set for `wp_footer`.
+		global $wp_filter;
+		$this->original_wp_footer = $wp_filter['wp_footer'];
+		$wp_filter['wp_footer']   = new WP_Hook();
+
+		// Removes all registered styles.
+		$this->original_wp_styles = $GLOBALS['wp_styles'] ?? null;
+		$GLOBALS['wp_styles']     = new WP_Styles();
+		remove_action( 'wp_default_styles', 'wp_default_styles' );
+		remove_action( 'wp_print_styles', 'print_emoji_styles' );
+	}
+
+	/**
+	 * Tear down.
+	 */
+	public function tear_down() {
+		foreach ( $this->registered_block_types as $block_name ) {
+			if ( WP_Block_Type_Registry::get_instance()->is_registered( $block_name ) ) {
+				unregister_block_type( $block_name );
+			}
+		}
+		$this->registered_block_types = array();
+
+		// Restores all previous hooks set for `wp_footer`.
+		global $wp_filter;
+		$wp_filter['wp_footer'] = $this->original_wp_footer;
+
+		// Restores all previous registered styles.
+		$GLOBALS['wp_styles'] = $this->original_wp_styles;
+		add_action( 'wp_default_styles', 'wp_default_styles' );
+		add_action( 'wp_print_styles', 'print_emoji_styles' );
+
+		parent::tear_down();
+	}
+
+	/**
+	 * Processes directives while temporarily replacing the global
+	 * WP_Interactivity_API instance so that global functions like
+	 * `wp_interactivity_state` operate on the test instance.
+	 *
+	 * @param string $html The HTML to process.
+	 * @return string The processed HTML.
+	 */
+	protected function process_directives( string $html ): string {
+		global $wp_interactivity;
+		$prev             = $wp_interactivity;
+		$wp_interactivity = $this->interactivity;
+
+		$result = $this->interactivity->process_directives( $html );
+
+		$wp_interactivity = $prev;
+		return $result;
+	}
+
+	/**
+	 * Marks the test instance as having processed a router region.
+	 */
+	protected function process_router_region() {
+		$this->process_directives( '<div data-wp-router-region="test">x</div>' );
+	}
+
+	/**
+	 * Removes the hooks added by `WP_Interactivity_API::add_hooks()`.
+	 */
+	protected function remove_hooks() {
+		remove_filter( 'script_module_data_@wordpress/interactivity', array( $this->interactivity, 'filter_script_module_interactivity_data' ) );
+		remove_filter( 'script_module_data_@wordpress/interactivity-router', array( $this->interactivity, 'filter_script_module_interactivity_router_data' ) );
+		remove_filter( 'wp_script_attributes', array( $this->interactivity, 'add_load_on_client_navigation_attribute_to_script_modules' ) );
+		remove_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) );
+		remove_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
+	}
+
+	/**
+	 * Registers a block type and schedules it for removal on tear down.
+	 *
+	 * @param string $block_name The block name.
+	 * @param array  $args       Optional. The block type arguments.
+	 */
+	protected function register_test_block_type( string $block_name, array $args = array() ) {
+		register_block_type( $block_name, $args );
+		$this->registered_block_types[] = $block_name;
+	}
+
+	/**
+	 * Returns a full page markup containing several style and non-style assets.
+	 *
+	 * @return string The page markup.
+	 */
+	protected function get_page_html(): string {
+		return <<<HTML
+<!DOCTYPE html>
+<html>
+<head>
+<link rel='stylesheet' id='test-css' href='http://example.org/test.css' media='all' />
+<style id='test-inline-css'>body{color:red}</style>
+<link rel="preload" href="http://example.org/font.woff2" as="font" />
+<script src="http://example.org/test.js"></script>
+</head>
+<body>
+<style>p{color:blue}</style>
+</body>
+</html>
+HTML;
+	}
+
+	/**
+	 * Returns the value of the `data-wp-router-managed` attribute for every tag
+	 * of the given markup, keyed by the order in which the tags are found.
+	 *
+	 * @param string $html  The markup to inspect.
+	 * @param array  $query The tag query, as accepted by `WP_HTML_Tag_Processor::next_tag()`.
+	 * @return array<int, mixed> The attribute values.
+	 */
+	protected function get_managed_attributes( string $html, array $query ): array {
+		$values = array();
+		$p      = new WP_HTML_Tag_Processor( $html );
+		while ( $p->next_tag( $query ) ) {
+			$values[] = $p->get_attribute( 'data-wp-router-managed' );
+		}
+		return $values;
+	}
+
+	/**
+	 * Tests that the attribute is added to all the style assets when all the
+	 * conditions are met.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_added_to_style_assets() {
+		$this->process_router_region();
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $this->get_page_html() );
+
+		// Both style tags are marked.
+		$this->assertSame( array( true, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+
+		// Only the stylesheet link is marked.
+		$this->assertSame( array( true, null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+
+		// The script tag is untouched.
+		$this->assertSame( array( null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'script' ) ) );
+
+		// The attribute is rendered in its empty, valueless form.
+		$this->assertStringContainsString( 'data-wp-router-managed', $html );
+		$this->assertStringNotContainsString( 'data-wp-router-managed=', $html );
+		$this->assertSame( 3, substr_count( $html, 'data-wp-router-managed' ) );
+	}
+
+	/**
+	 * Tests that the buffer is not modified when no router region has been
+	 * processed.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_without_router_region() {
+		$buffer = $this->get_page_html();
+
+		$this->assertSame( $buffer, $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer ) );
+	}
+
+	/**
+	 * Tests that the buffer is not modified when client-side navigation is
+	 * disabled in the `core/router` config.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_when_client_navigation_is_disabled() {
+		$this->process_router_region();
+		$this->interactivity->config( 'core/router', array( 'clientNavigationDisabled' => true ) );
+
+		$buffer = $this->get_page_html();
+
+		$this->assertSame( $buffer, $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer ) );
+	}
+
+	/**
+	 * Tests that the buffer is not modified when a block that does not support
+	 * client-side navigation has been rendered.
+	 *
+	 * @covers ::filter_render_block_data_client_navigation_support
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_with_a_block_without_client_navigation_support() {
+		$this->process_router_region();
+		$this->register_test_block_type( 'test/no-client-nav' );
+
+		$parsed_block = array(
+			'blockName' => 'test/no-client-nav',
+			'attrs'     => array(),
+		);
+		$this->assertSame( $parsed_block, $this->interactivity->filter_render_block_data_client_navigation_support( $parsed_block ) );
+
+		$buffer = $this->get_page_html();
+
+		$this->assertSame( $buffer, $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer ) );
+	}
+
+	/**
+	 * Tests that the buffer is not modified when a block that is not registered
+	 * has been rendered.
+	 *
+	 * @covers ::filter_render_block_data_client_navigation_support
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_with_an_unregistered_block() {
+		$this->process_router_region();
+
+		$parsed_block = array(
+			'blockName' => 'test/unregistered',
+			'attrs'     => array(),
+		);
+		$this->assertSame( $parsed_block, $this->interactivity->filter_render_block_data_client_navigation_support( $parsed_block ) );
+
+		$buffer = $this->get_page_html();
+
+		$this->assertSame( $buffer, $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer ) );
+	}
+
+	/**
+	 * Tests that blocks without a block name, i.e. freeform classic HTML, do not
+	 * break the client-side navigation compatibility.
+	 *
+	 * @covers ::filter_render_block_data_client_navigation_support
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_block_without_name_does_not_break_compatibility() {
+		$this->process_router_region();
+
+		$parsed_block = array(
+			'blockName' => null,
+			'attrs'     => array(),
+		);
+		$this->assertSame( $parsed_block, $this->interactivity->filter_render_block_data_client_navigation_support( $parsed_block ) );
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $this->get_page_html() );
+
+		$this->assertSame( 3, substr_count( $html, 'data-wp-router-managed' ) );
+	}
+
+	/**
+	 * Tests that blocks supporting client-side navigation do not break the
+	 * client-side navigation compatibility.
+	 *
+	 * @covers ::filter_render_block_data_client_navigation_support
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_block_with_client_navigation_support_does_not_break_compatibility() {
+		$this->process_router_region();
+		$this->register_test_block_type(
+			'test/client-nav',
+			array(
+				'supports' => array(
+					'interactivity' => array( 'clientNavigation' => true ),
+				),
+			)
+		);
+		$this->register_test_block_type(
+			'test/interactive',
+			array(
+				'supports' => array( 'interactivity' => true ),
+			)
+		);
+
+		$this->interactivity->filter_render_block_data_client_navigation_support(
+			array(
+				'blockName' => 'test/client-nav',
+				'attrs'     => array(),
+			)
+		);
+		$this->interactivity->filter_render_block_data_client_navigation_support(
+			array(
+				'blockName' => 'test/interactive',
+				'attrs'     => array(),
+			)
+		);
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $this->get_page_html() );
+
+		$this->assertSame( 3, substr_count( $html, 'data-wp-router-managed' ) );
+	}
+
+	/**
+	 * Tests that the `rel` attribute is handled as a case-insensitive,
+	 * space-separated list of tokens.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_link_rel_token_list_handling() {
+		$this->process_router_region();
+
+		$buffer = '<!DOCTYPE html><html><head>' .
+			'<link rel="alternate stylesheet" href="http://example.org/a.css">' .
+			'<link rel="StyleSheet" href="http://example.org/b.css">' .
+			'<link rel="preload stylesheets" href="http://example.org/c.css">' .
+			'<link rel href="http://example.org/d.css">' .
+			'<link href="http://example.org/e.css">' .
+			'</head><body></body></html>';
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer );
+
+		$this->assertSame(
+			array( true, true, null, null, null ),
+			$this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) )
+		);
+	}
+
+	/**
+	 * Tests that a non-string buffer is returned as is.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_non_string_buffer_is_returned_as_is() {
+		$this->process_router_region();
+
+		$this->assertNull( $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( null ) );
+		$this->assertFalse( $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( false ) );
+		$this->assertSame( array(), $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( array() ) );
+	}
+
+	/**
+	 * Tests that style assets inside `noscript` elements are not marked.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_inside_noscript() {
+		$this->process_router_region();
+
+		$buffer = '<!DOCTYPE html><html><head>' .
+			'<style id="before">a{}</style>' .
+			'<noscript>' .
+			'<style id="inside">b{}</style>' .
+			'<link rel="stylesheet" id="inside-link" href="http://example.org/a.css">' .
+			'</noscript>' .
+			'<style id="after">c{}</style>' .
+			'</head><body></body></html>';
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer );
+
+		$this->assertSame( array( true, null, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+		$this->assertSame( array( null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+	}
+
+	/**
+	 * Tests that style assets inside `template` elements, including nested ones,
+	 * are not marked.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_not_added_inside_template() {
+		$this->process_router_region();
+
+		$buffer = '<!DOCTYPE html><html><head>' .
+			'<style id="before">a{}</style>' .
+			'</head><body>' .
+			'<template><template>' .
+			'<style id="inside">b{}</style>' .
+			'<link rel="stylesheet" id="inside-link" href="http://example.org/a.css">' .
+			'</template></template>' .
+			'<style id="after">c{}</style>' .
+			'</body></html>';
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer );
+
+		$this->assertSame( array( true, null, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+		$this->assertSame( array( null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+	}
+
+	/**
+	 * Tests that a self-closing `template` tag in foreign content, which has no
+	 * closing tag, does not suppress the attribute for the rest of the document.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_self_closing_template_does_not_suppress_the_attribute() {
+		$this->process_router_region();
+
+		$buffer = '<!DOCTYPE html><html><head></head><body>' .
+			'<svg><template/></svg>' .
+			'<style id="trailing">x{}</style>' .
+			'<template><style id="inert">y{}</style></template>' .
+			'<style id="last">z{}</style>' .
+			'</body></html>';
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer );
+
+		$this->assertSame( array( true, null, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+	}
+
+	/**
+	 * Tests that `style` elements inside inline SVG are marked.
+	 *
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_attribute_is_added_to_svg_style() {
+		$this->process_router_region();
+
+		$buffer = '<!DOCTYPE html><html><head></head><body><svg><style>circle{}</style></svg></body></html>';
+
+		$html = $this->interactivity->filter_template_output_buffer_add_router_managed_attribute( $buffer );
+
+		$this->assertSame( array( true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+	}
+
+	/**
+	 * Tests that the front-end filters are registered by `add_hooks()`.
+	 *
+	 * @covers ::add_hooks
+	 */
+	public function test_add_hooks_registers_front_end_filters() {
+		$this->interactivity->add_hooks();
+
+		$this->assertSame(
+			20,
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+		$this->assertNotFalse(
+			has_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) )
+		);
+
+		$this->remove_hooks();
+	}
+
+	/**
+	 * Tests that the front-end filters are not registered in admin requests.
+	 *
+	 * @covers ::add_hooks
+	 */
+	public function test_add_hooks_does_not_register_front_end_filters_in_admin() {
+		set_current_screen( 'edit-post' );
+		$this->assertTrue( is_admin() );
+
+		$this->interactivity->add_hooks();
+
+		$this->assertFalse(
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+		$this->assertFalse(
+			has_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) )
+		);
+
+		$this->remove_hooks();
+		set_current_screen( 'front' );
+	}
+
+	/**
+	 * Tests that the registered filter is invoked when the template enhancement
+	 * output buffer is filtered.
+	 *
+	 * @covers ::add_hooks
+	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
+	 */
+	public function test_add_hooks_marks_style_assets_through_the_filter_chain() {
+		$this->interactivity->add_hooks();
+		$this->process_router_region();
+
+		$buffer = $this->get_page_html();
+		$html   = apply_filters( 'wp_template_enhancement_output_buffer', $buffer, $buffer );
+
+		$this->assertSame( array( true, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+		$this->assertSame( array( true, null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+
+		$this->remove_hooks();
+	}
+
+	/**
+	 * Tests the `has_router_region()` getter.
+	 *
+	 * @covers ::has_router_region
+	 */
+	public function test_has_router_region() {
+		$this->assertFalse( $this->interactivity->has_router_region() );
+
+		$this->process_router_region();
+
+		$this->assertTrue( $this->interactivity->has_router_region() );
+	}
+}
diff --git a/tests/phpunit/tests/template.php b/tests/phpunit/tests/template.php
index a79702554dc64..8d097a63d6ff6 100644
--- a/tests/phpunit/tests/template.php
+++ b/tests/phpunit/tests/template.php
@@ -122,6 +122,9 @@ public function set_up() {
 		remove_filter( 'should_load_block_assets_on_demand', '__return_true', 0 );
 		remove_action( 'wp_template_enhancement_output_buffer_started', 'wp_hoist_late_printed_styles' );
 
+		// Remove the hook which is added by WP_Interactivity_API::add_hooks() during bootstrapping.
+		remove_filter( 'wp_template_enhancement_output_buffer', array( wp_interactivity(), 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
+
 		global $wp_scripts, $wp_styles;
 		$this->original_wp_scripts = $wp_scripts;
 		$this->original_wp_styles  = $wp_styles;

From d46cadd73acca1d774abba7d7edf356cd16b5b7f Mon Sep 17 00:00:00 2001
From: David <david.arenas@automattic.com>
Date: Mon, 10 Aug 2026 12:38:38 +0200
Subject: [PATCH 2/2] Interactivity API: register the data-wp-router-managed
 machinery lazily.

---
 .../class-wp-interactivity-api.php            | 279 ++++++++++++++-
 .../wpInteractivityAPI-wp-router-managed.php  | 326 +++++++++++++++++-
 tests/phpunit/tests/template.php              |   3 -
 3 files changed, 580 insertions(+), 28 deletions(-)

diff --git a/src/wp-includes/interactivity-api/class-wp-interactivity-api.php b/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
index dd838edd92bb2..344dc4209f50d 100644
--- a/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
+++ b/src/wp-includes/interactivity-api/class-wp-interactivity-api.php
@@ -109,6 +109,29 @@ final class WP_Interactivity_API {
 	 */
 	private $all_blocks_support_client_navigation = true;
 
+	/**
+	 * Flag that indicates whether the template enhancement output buffer started
+	 * by core is active for the current request.
+	 *
+	 * It is set from the {@see 'wp_template_enhancement_output_buffer_started'}
+	 * action. When it is `true`, the `data-wp-router-managed` attribute is added
+	 * through the {@see 'wp_template_enhancement_output_buffer'} filter and no
+	 * additional output buffer is needed.
+	 *
+	 * @since 7.2.0
+	 * @var bool
+	 */
+	private $template_output_buffer_started = false;
+
+	/**
+	 * Flag that indicates whether starting the fallback output buffer used to add
+	 * the `data-wp-router-managed` attribute has already been considered.
+	 *
+	 * @since 7.2.0
+	 * @var bool
+	 */
+	private $router_managed_output_buffer_attempted = false;
+
 	/**
 	 * Set of script modules that can be loaded after client-side navigation.
 	 *
@@ -413,8 +436,8 @@ public function register_script_modules() {
 	 *
 	 * @since 6.5.0
 	 * @since 6.9.0 Adds support for client-side navigation in script modules.
-	 * @since 7.2.0 Tracks the page-wide client-side navigation support and adds the `data-wp-router-managed`
-	 *              attribute to server-generated style assets.
+	 * @since 7.2.0 Tracks the page-wide client-side navigation support and registers the hooks that decide how the
+	 *              `data-wp-router-managed` attribute is added to the server-generated style assets.
 	 */
 	public function add_hooks() {
 		add_filter( 'script_module_data_@wordpress/interactivity', array( $this, 'filter_script_module_interactivity_data' ) );
@@ -429,19 +452,47 @@ public function add_hooks() {
 			add_filter( 'render_block_data', array( $this, 'filter_render_block_data_client_navigation_support' ) );
 
 			/*
-			 * The priority is set to 20 so this filter runs after the one added by
-			 * `wp_hoist_late_printed_styles()`, which uses the default priority and
-			 * can move style tags into the HEAD. That way, every style asset present
-			 * in the final markup gets the attribute.
-			 *
-			 * Note that adding this filter is what makes core start the template
-			 * enhancement output buffer, as documented in
+			 * The `wp_template_enhancement_output_buffer` filter that adds the
+			 * `data-wp-router-managed` attribute is not registered here on purpose.
+			 * Merely having that filter registered when the template is included
+			 * makes core start the template enhancement output buffer for every
+			 * front-end request, which disables response streaming even on pages
+			 * that never get the attribute. See
 			 * `wp_should_output_buffer_template_for_enhancement()`.
+			 *
+			 * Instead, the filter is added from
+			 * `WP_Interactivity_API::data_wp_router_region_processor()`, i.e. only
+			 * once a router region has actually been processed, and
+			 * `WP_Interactivity_API::maybe_start_router_managed_output_buffer()`
+			 * starts a dedicated output buffer when core's one is not running.
 			 */
-			add_filter( 'wp_template_enhancement_output_buffer', array( $this, 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
+			add_action( 'wp_template_enhancement_output_buffer_started', array( $this, 'mark_template_output_buffer_started' ) );
+
+			/*
+			 * The lowest possible priority guarantees that nothing hooked to
+			 * `wp_head` prints a style asset before the fallback output buffer
+			 * starts. Marking only part of the style assets of a page would be
+			 * worse than not marking any of them, because the router would treat
+			 * the unmarked ones as client-injected and preserve them across every
+			 * client-side navigation.
+			 */
+			add_action( 'wp_head', array( $this, 'maybe_start_router_managed_output_buffer' ), PHP_INT_MIN );
 		}
 	}
 
+	/**
+	 * Records that the template enhancement output buffer started by core is
+	 * active for the current request.
+	 *
+	 * This method is a {@see 'wp_template_enhancement_output_buffer_started'}
+	 * action callback.
+	 *
+	 * @since 7.2.0
+	 */
+	public function mark_template_output_buffer_started() {
+		$this->template_output_buffer_started = true;
+	}
+
 	/**
 	 * Tracks whether all the blocks rendered on the page support client-side
 	 * navigation.
@@ -500,6 +551,12 @@ public function filter_render_block_data_client_navigation_support( $parsed_bloc
 	 * `noscript` and `template` elements, which are not rendered as part of the
 	 * document.
 	 *
+	 * The filter is not registered upfront. It is added from
+	 * {@see WP_Interactivity_API::data_wp_router_region_processor()} when a router
+	 * region is processed, because registering it earlier would force core to
+	 * start the template enhancement output buffer on every front-end request. See
+	 * {@see WP_Interactivity_API::add_hooks()}.
+	 *
 	 * The attribute lets the Interactivity API router tell server-rendered style
 	 * assets apart from the ones injected later by JavaScript, so the latter can
 	 * be preserved when the head is diffed during a client-side navigation.
@@ -518,20 +575,175 @@ public function filter_template_output_buffer_add_router_managed_attribute( $buf
 			return $buffer;
 		}
 
-		if ( ! $this->has_processed_router_region || ! $this->all_blocks_support_client_navigation ) {
+		if ( ! $this->should_add_router_managed_attribute() ) {
 			return $buffer;
 		}
 
+		return $this->add_router_managed_attribute_to_style_assets( $buffer );
+	}
+
+	/**
+	 * Starts an output buffer to add the `data-wp-router-managed` attribute to
+	 * the style assets of the page when core's template enhancement output buffer
+	 * is not running.
+	 *
+	 * This method is a {@see 'wp_head'} action callback registered with the lowest
+	 * possible priority, so the buffer captures every style asset printed from
+	 * that point on: the rest of the HEAD, the BODY and the footer.
+	 *
+	 * The buffer is only started when it is really needed. Core starts its own
+	 * template enhancement output buffer whenever something requires it, and in
+	 * that case the attribute is added through the
+	 * {@see 'wp_template_enhancement_output_buffer'} filter instead.
+	 *
+	 * This fallback relies on the block template canvas, which renders the whole
+	 * template, including the footer template parts, into a string before printing
+	 * the doctype and firing `wp_head`. In that flow all the directives have
+	 * already been processed by the time this method runs, so the conditions
+	 * checked here are final and the markup printed before the buffer starts
+	 * cannot contain style assets.
+	 *
+	 * In flows where blocks are rendered after `wp_head` instead, i.e. classic
+	 * themes, block themes serving a PHP template, or a PHP template served
+	 * through the {@see 'template_include'} filter by a plugin, no router region
+	 * has been processed at this point, so this method intentionally does nothing.
+	 * Those flows are covered by the
+	 * {@see 'wp_template_enhancement_output_buffer'} filter as long as core's
+	 * template enhancement output buffer is active, which classic themes enable by
+	 * default since WordPress 6.9. When it is not active, e.g. a site opting out
+	 * through the {@see 'wp_should_output_buffer_template_for_enhancement'} filter
+	 * or a block theme serving a PHP template, the attribute is not emitted at
+	 * all. That is a deliberate limitation: not marking any style asset is safe,
+	 * whereas marking only some of them is not.
+	 *
+	 * @since 7.2.0
+	 */
+	public function maybe_start_router_managed_output_buffer() {
+		if ( $this->router_managed_output_buffer_attempted || $this->template_output_buffer_started ) {
+			return;
+		}
+
+		$this->router_managed_output_buffer_attempted = true;
+
+		if ( ! $this->should_add_router_managed_attribute() ) {
+			return;
+		}
+
+		/*
+		 * The buffer is not closed explicitly. It is flushed through its callback
+		 * by `wp_ob_end_flush_all()` on shutdown, like the one started by
+		 * `wp_start_template_enhancement_output_buffer()`.
+		 *
+		 * As a side effect, third-party code that captures the output of `wp_head`
+		 * with its own `ob_start()` and `ob_get_clean()` pair consumes this buffer
+		 * instead of its own, because this one is started from within `wp_head`.
+		 * The markup is not lost, but it is returned unmarked. This is an accepted
+		 * tradeoff of covering the whole page from a single buffer.
+		 */
+		ob_start(
+			array( $this, 'finalize_router_managed_output_buffer' ),
+			/*
+			 * An unlimited chunk size, so the entire output is passed to the
+			 * callback at once and every style asset can be marked no matter where
+			 * it was printed.
+			 */
+			0,
+			/*
+			 * The `PHP_OUTPUT_HANDLER_FLUSHABLE` flag is omitted so a `flush()`
+			 * call cannot send a fragment of the page through the callback and
+			 * leave the rest of the markup unprocessed. The buffer is still
+			 * cleanable and removable, which is required because WordPress calls
+			 * `wp_ob_end_flush_all()` before `wp_cache_close()`. Same rationale as
+			 * `wp_start_template_enhancement_output_buffer()`.
+			 */
+			PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_FLUSHABLE
+		);
+	}
+
+	/**
+	 * Adds the `data-wp-router-managed` attribute to the style assets of the
+	 * buffer started by {@see WP_Interactivity_API::maybe_start_router_managed_output_buffer()}.
+	 *
+	 * The conditions are checked again here because this callback runs when the
+	 * buffer is finalized, i.e. at the very end of the request, and code running
+	 * after `wp_head`, e.g. a `wp_footer` callback, may still have rendered a
+	 * block without client-side navigation support or disabled client-side
+	 * navigation.
+	 *
+	 * Unlike `wp_finalize_template_enhancement_output_buffer()`, this callback
+	 * does not check the content type of the response. The buffer is only started
+	 * from `wp_head`, so the response is an HTML document, and the HTML processor
+	 * leaves markup without style assets untouched anyway.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $output The output buffer.
+	 * @param int    $phase  The output buffer phase bitmask.
+	 * @return string The output buffer, with the attribute added to the style assets.
+	 */
+	public function finalize_router_managed_output_buffer( string $output, int $phase ): string {
+		// When the output is being cleaned, e.g. it is replaced with an error page, it must not be processed.
+		if ( ( $phase & PHP_OUTPUT_HANDLER_CLEAN ) !== 0 ) {
+			return $output;
+		}
+
+		if ( ! $this->should_add_router_managed_attribute() ) {
+			return $output;
+		}
+
+		try {
+			return $this->add_router_managed_attribute_to_style_assets( $output );
+		} catch ( Throwable $e ) {
+			/*
+			 * An exception thrown from an output buffer callback is fatal and
+			 * discards the whole response, so the original output is returned
+			 * unmodified instead. The page is served without the attribute, which
+			 * only disables the optimization.
+			 */
+			return $output;
+		}
+	}
+
+	/**
+	 * Checks whether the style assets of the page can be marked with the
+	 * `data-wp-router-managed` attribute.
+	 *
+	 * The attribute is only added when all the blocks rendered on the page support
+	 * client-side navigation, at least one router region has been processed, and
+	 * client-side navigation has not been disabled.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return bool Whether the attribute can be added to the style assets.
+	 */
+	private function should_add_router_managed_attribute(): bool {
+		if ( ! $this->has_processed_router_region || ! $this->all_blocks_support_client_navigation ) {
+			return false;
+		}
+
 		/*
 		 * The configuration is read directly instead of through
 		 * `WP_Interactivity_API::config()` because that method would create an
 		 * empty `core/router` entry as a side effect of reading it.
 		 */
-		if ( ! empty( $this->config_data['core/router']['clientNavigationDisabled'] ) ) {
-			return $buffer;
-		}
+		return empty( $this->config_data['core/router']['clientNavigationDisabled'] );
+	}
 
-		$processor = new WP_HTML_Tag_Processor( $buffer );
+	/**
+	 * Adds the `data-wp-router-managed` attribute to every style asset found in
+	 * the given markup.
+	 *
+	 * Every `<style>` element and every `<link rel="stylesheet">` element is
+	 * marked. The only exceptions are the style assets contained in `noscript` and
+	 * `template` elements, which are not rendered as part of the document.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $html The markup to process.
+	 * @return string The markup, with the attribute added to the style assets.
+	 */
+	private function add_router_managed_attribute_to_style_assets( string $html ): string {
+		$processor = new WP_HTML_Tag_Processor( $html );
 
 		/*
 		 * Depth of the `noscript` and `template` elements currently open. The
@@ -1687,12 +1899,47 @@ public function has_router_region(): bool {
 	 * and 2) an `aria-live` region for accessible navigation announcements.
 	 *
 	 * @since 6.5.0
+	 * @since 7.2.0 Registers the filter that adds the `data-wp-router-managed` attribute to the style assets.
 	 *
 	 * @param WP_Interactivity_API_Directives_Processor $p               The directives processor instance.
 	 * @param string                                    $mode            Whether the processing is entering or exiting the tag.
 	 */
 	private function data_wp_router_region_processor( WP_Interactivity_API_Directives_Processor $p, string $mode ) {
-		if ( 'enter' === $mode && ! $this->has_processed_router_region ) {
+		if ( 'enter' !== $mode ) {
+			return;
+		}
+
+		if ( ! is_admin() ) {
+			/*
+			 * The filter is added here, and not in `add_hooks()`, because having
+			 * it registered when the template is included is what makes core start
+			 * the template enhancement output buffer, and that would disable
+			 * response streaming on every front-end request. See
+			 * `wp_should_output_buffer_template_for_enhancement()`.
+			 *
+			 * Adding it now cannot start a buffer that was not going to be
+			 * started: directives are processed while the template renders, so the
+			 * decision to buffer was already made at
+			 * `wp_before_include_template`. The filter chain is only applied when
+			 * the buffer is finalized, so attaching to an already started buffer
+			 * works as expected.
+			 *
+			 * It is added for every processed router region, and not only for the
+			 * first one, so the registration is restored if other code removed the
+			 * filters of this hook in between, and so it happens once per request
+			 * even though `$has_processed_router_region` is only reset when a new
+			 * instance is created. Adding the same callback with the same priority
+			 * more than once is a no-op.
+			 *
+			 * The priority is set to 20 so this filter runs after the one added by
+			 * `wp_hoist_late_printed_styles()`, which uses the default priority and
+			 * can move style tags into the HEAD. That way, every style asset
+			 * present in the final markup gets the attribute.
+			 */
+			add_filter( 'wp_template_enhancement_output_buffer', array( $this, 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
+		}
+
+		if ( ! $this->has_processed_router_region ) {
 			$this->has_processed_router_region = true;
 
 			// Initializes the `state.url` property from the server.
diff --git a/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php b/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php
index e25e8fbad05e9..da0f545c86ca8 100644
--- a/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php
+++ b/tests/phpunit/tests/interactivity-api/wpInteractivityAPI-wp-router-managed.php
@@ -39,12 +39,20 @@ class Tests_WP_Interactivity_API_WP_Router_Managed extends WP_UnitTestCase {
 	 */
 	protected $registered_block_types = array();
 
+	/**
+	 * Output buffering level at the beginning of the test.
+	 *
+	 * @var int
+	 */
+	protected $original_ob_level;
+
 	/**
 	 * Set up.
 	 */
 	public function set_up() {
 		parent::set_up();
-		$this->interactivity = new WP_Interactivity_API();
+		$this->interactivity     = new WP_Interactivity_API();
+		$this->original_ob_level = ob_get_level();
 
 		// Removes all hooks set for `wp_footer`.
 		global $wp_filter;
@@ -62,6 +70,14 @@ public function set_up() {
 	 * Tear down.
 	 */
 	public function tear_down() {
+		/*
+		 * Discards the output buffers left behind by the tests, e.g. when an
+		 * assertion between `ob_start()` and its clean up fails.
+		 */
+		while ( ob_get_level() > $this->original_ob_level ) {
+			ob_end_clean();
+		}
+
 		foreach ( $this->registered_block_types as $block_name ) {
 			if ( WP_Block_Type_Registry::get_instance()->is_registered( $block_name ) ) {
 				unregister_block_type( $block_name );
@@ -69,6 +85,8 @@ public function tear_down() {
 		}
 		$this->registered_block_types = array();
 
+		$this->remove_hooks();
+
 		// Restores all previous hooks set for `wp_footer`.
 		global $wp_filter;
 		$wp_filter['wp_footer'] = $this->original_wp_footer;
@@ -115,6 +133,8 @@ protected function remove_hooks() {
 		remove_filter( 'script_module_data_@wordpress/interactivity-router', array( $this->interactivity, 'filter_script_module_interactivity_router_data' ) );
 		remove_filter( 'wp_script_attributes', array( $this->interactivity, 'add_load_on_client_navigation_attribute_to_script_modules' ) );
 		remove_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) );
+		remove_action( 'wp_template_enhancement_output_buffer_started', array( $this->interactivity, 'mark_template_output_buffer_started' ) );
+		remove_action( 'wp_head', array( $this->interactivity, 'maybe_start_router_managed_output_buffer' ), PHP_INT_MIN );
 		remove_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
 	}
 
@@ -450,30 +470,40 @@ public function test_attribute_is_added_to_svg_style() {
 	}
 
 	/**
-	 * Tests that the front-end filters are registered by `add_hooks()`.
+	 * Tests that the front-end hooks are registered by `add_hooks()`.
+	 *
+	 * The template enhancement output buffer filter must not be registered,
+	 * because registering it is what makes core start the template enhancement
+	 * output buffer on every front-end request.
 	 *
 	 * @covers ::add_hooks
 	 */
-	public function test_add_hooks_registers_front_end_filters() {
+	public function test_add_hooks_registers_front_end_hooks() {
 		$this->interactivity->add_hooks();
 
-		$this->assertSame(
-			20,
+		$this->assertFalse(
 			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
 		);
 		$this->assertNotFalse(
 			has_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) )
 		);
+		$this->assertNotFalse(
+			has_action( 'wp_template_enhancement_output_buffer_started', array( $this->interactivity, 'mark_template_output_buffer_started' ) )
+		);
+		$this->assertSame(
+			PHP_INT_MIN,
+			has_action( 'wp_head', array( $this->interactivity, 'maybe_start_router_managed_output_buffer' ) )
+		);
 
 		$this->remove_hooks();
 	}
 
 	/**
-	 * Tests that the front-end filters are not registered in admin requests.
+	 * Tests that the front-end hooks are not registered in admin requests.
 	 *
 	 * @covers ::add_hooks
 	 */
-	public function test_add_hooks_does_not_register_front_end_filters_in_admin() {
+	public function test_add_hooks_does_not_register_front_end_hooks_in_admin() {
 		set_current_screen( 'edit-post' );
 		$this->assertTrue( is_admin() );
 
@@ -485,6 +515,92 @@ public function test_add_hooks_does_not_register_front_end_filters_in_admin() {
 		$this->assertFalse(
 			has_filter( 'render_block_data', array( $this->interactivity, 'filter_render_block_data_client_navigation_support' ) )
 		);
+		$this->assertFalse(
+			has_action( 'wp_template_enhancement_output_buffer_started', array( $this->interactivity, 'mark_template_output_buffer_started' ) )
+		);
+		$this->assertFalse(
+			has_action( 'wp_head', array( $this->interactivity, 'maybe_start_router_managed_output_buffer' ) )
+		);
+
+		$this->remove_hooks();
+		set_current_screen( 'front' );
+	}
+
+	/**
+	 * Tests that processing a router region registers the template enhancement
+	 * output buffer filter.
+	 *
+	 * @covers ::data_wp_router_region_processor
+	 */
+	public function test_processing_a_router_region_registers_the_output_buffer_filter() {
+		$this->assertFalse(
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+
+		$this->process_router_region();
+
+		$this->assertSame(
+			20,
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+
+		$this->remove_hooks();
+	}
+
+	/**
+	 * Tests that the template enhancement output buffer filter is registered
+	 * again when another router region is processed, so it survives other code
+	 * removing the filters of the hook.
+	 *
+	 * @covers ::data_wp_router_region_processor
+	 */
+	public function test_processing_another_router_region_registers_the_output_buffer_filter_again() {
+		$this->process_router_region();
+
+		remove_all_filters( 'wp_template_enhancement_output_buffer' );
+		$this->assertFalse(
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+
+		$this->process_router_region();
+
+		$this->assertSame(
+			20,
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+
+		$this->remove_hooks();
+	}
+
+	/**
+	 * Tests that processing markup without a router region does not register the
+	 * template enhancement output buffer filter.
+	 *
+	 * @covers ::data_wp_router_region_processor
+	 */
+	public function test_processing_without_a_router_region_does_not_register_the_output_buffer_filter() {
+		$this->process_directives( '<div data-wp-interactive="test"><p data-wp-text="state.text">x</p></div>' );
+
+		$this->assertFalse(
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
+	}
+
+	/**
+	 * Tests that processing a router region does not register the template
+	 * enhancement output buffer filter in admin requests.
+	 *
+	 * @covers ::data_wp_router_region_processor
+	 */
+	public function test_processing_a_router_region_does_not_register_the_output_buffer_filter_in_admin() {
+		set_current_screen( 'edit-post' );
+		$this->assertTrue( is_admin() );
+
+		$this->process_router_region();
+
+		$this->assertFalse(
+			has_filter( 'wp_template_enhancement_output_buffer', array( $this->interactivity, 'filter_template_output_buffer_add_router_managed_attribute' ) )
+		);
 
 		$this->remove_hooks();
 		set_current_screen( 'front' );
@@ -494,10 +610,10 @@ public function test_add_hooks_does_not_register_front_end_filters_in_admin() {
 	 * Tests that the registered filter is invoked when the template enhancement
 	 * output buffer is filtered.
 	 *
-	 * @covers ::add_hooks
+	 * @covers ::data_wp_router_region_processor
 	 * @covers ::filter_template_output_buffer_add_router_managed_attribute
 	 */
-	public function test_add_hooks_marks_style_assets_through_the_filter_chain() {
+	public function test_marks_style_assets_through_the_filter_chain() {
 		$this->interactivity->add_hooks();
 		$this->process_router_region();
 
@@ -510,6 +626,198 @@ public function test_add_hooks_marks_style_assets_through_the_filter_chain() {
 		$this->remove_hooks();
 	}
 
+	/**
+	 * Tests that no output buffer is started when the conditions are not met.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 */
+	public function test_output_buffer_is_not_started_without_router_region() {
+		$level = ob_get_level();
+
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		$this->assertSame( $level, ob_get_level() );
+	}
+
+	/**
+	 * Tests that no output buffer is started when client-side navigation is
+	 * disabled in the `core/router` config.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 */
+	public function test_output_buffer_is_not_started_when_client_navigation_is_disabled() {
+		$this->process_router_region();
+		$this->interactivity->config( 'core/router', array( 'clientNavigationDisabled' => true ) );
+
+		$level = ob_get_level();
+
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		$this->assertSame( $level, ob_get_level() );
+	}
+
+	/**
+	 * Tests that an output buffer handled by the class is started when the
+	 * conditions are met and core's template output buffer is not running.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 */
+	public function test_output_buffer_is_started_when_conditions_are_met() {
+		$this->process_router_region();
+
+		$level = ob_get_level();
+
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		$this->assertSame( $level + 1, ob_get_level() );
+
+		$status = ob_get_status();
+		ob_end_clean();
+
+		$this->assertSame( $level, ob_get_level() );
+		$this->assertSame( 'WP_Interactivity_API::finalize_router_managed_output_buffer', $status['name'] );
+		$this->assertSame( 0, $status['chunk_size'] );
+		$this->assertSame( 0, $status['flags'] & PHP_OUTPUT_HANDLER_FLUSHABLE );
+		$this->assertNotSame( 0, $status['flags'] & PHP_OUTPUT_HANDLER_CLEANABLE );
+		$this->assertNotSame( 0, $status['flags'] & PHP_OUTPUT_HANDLER_REMOVABLE );
+	}
+
+	/**
+	 * Tests that the output buffer is only started once.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 */
+	public function test_output_buffer_is_started_only_once() {
+		$this->process_router_region();
+
+		$level = ob_get_level();
+
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		$this->assertSame( $level + 1, ob_get_level() );
+
+		ob_end_clean();
+	}
+
+	/**
+	 * Tests that no output buffer is started when core's template enhancement
+	 * output buffer is already running.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 * @covers ::mark_template_output_buffer_started
+	 */
+	public function test_output_buffer_is_not_started_when_template_output_buffer_started() {
+		$this->interactivity->add_hooks();
+		$this->process_router_region();
+
+		/*
+		 * The callback is invoked directly instead of through the action, because
+		 * the other callbacks hooked to it, e.g. `wp_hoist_late_printed_styles()`,
+		 * have side effects that are not relevant for this test.
+		 */
+		$this->interactivity->mark_template_output_buffer_started();
+
+		$level = ob_get_level();
+
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		$this->assertSame( $level, ob_get_level() );
+
+		$this->remove_hooks();
+	}
+
+	/**
+	 * Tests that the output buffer callback marks the style assets when the
+	 * buffer is finalized.
+	 *
+	 * @covers ::finalize_router_managed_output_buffer
+	 */
+	public function test_output_buffer_callback_marks_style_assets() {
+		$this->process_router_region();
+
+		$html = $this->interactivity->finalize_router_managed_output_buffer( $this->get_page_html(), PHP_OUTPUT_HANDLER_FINAL );
+
+		$this->assertSame( array( true, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+		$this->assertSame( array( true, null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+	}
+
+	/**
+	 * Tests that the output buffer callback does not modify the output when the
+	 * buffer is being cleaned.
+	 *
+	 * @covers ::finalize_router_managed_output_buffer
+	 */
+	public function test_output_buffer_callback_does_not_modify_cleaned_output() {
+		$this->process_router_region();
+
+		$buffer = $this->get_page_html();
+
+		$this->assertSame(
+			$buffer,
+			$this->interactivity->finalize_router_managed_output_buffer( $buffer, PHP_OUTPUT_HANDLER_CLEAN )
+		);
+	}
+
+	/**
+	 * Tests that the output buffer callback rechecks the conditions when the
+	 * buffer is finalized, so markup rendered after `wp_head` is taken into
+	 * account.
+	 *
+	 * @covers ::finalize_router_managed_output_buffer
+	 */
+	public function test_output_buffer_callback_rechecks_the_conditions() {
+		$this->process_router_region();
+
+		$level = ob_get_level();
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+		$this->assertSame( $level + 1, ob_get_level() );
+		ob_end_clean();
+
+		// Client-side navigation is disabled after the buffer has started.
+		$this->interactivity->config( 'core/router', array( 'clientNavigationDisabled' => true ) );
+
+		$buffer = $this->get_page_html();
+
+		$this->assertSame(
+			$buffer,
+			$this->interactivity->finalize_router_managed_output_buffer( $buffer, PHP_OUTPUT_HANDLER_FINAL )
+		);
+	}
+
+	/**
+	 * Tests that the output buffer started by the class marks the style assets of
+	 * everything printed after it started.
+	 *
+	 * @covers ::maybe_start_router_managed_output_buffer
+	 * @covers ::finalize_router_managed_output_buffer
+	 */
+	public function test_output_buffer_marks_the_captured_output() {
+		$this->process_router_region();
+
+		/*
+		 * The buffer started by the class is nested inside a plain one, so it can
+		 * be finalized with `ob_end_flush()`, which runs the callback, without
+		 * sending anything to the actual output.
+		 */
+		ob_start();
+		$level = ob_get_level();
+		$this->interactivity->maybe_start_router_managed_output_buffer();
+
+		/*
+		 * The buffer must have started before anything is printed. Otherwise, the
+		 * clean up below would discard the buffers of the test runner.
+		 */
+		$this->assertSame( $level + 1, ob_get_level() );
+
+		echo $this->get_page_html();
+		ob_end_flush();
+		$html = ob_get_clean();
+
+		$this->assertSame( array( true, true ), $this->get_managed_attributes( $html, array( 'tag_name' => 'style' ) ) );
+		$this->assertSame( array( true, null ), $this->get_managed_attributes( $html, array( 'tag_name' => 'link' ) ) );
+	}
+
 	/**
 	 * Tests the `has_router_region()` getter.
 	 *
diff --git a/tests/phpunit/tests/template.php b/tests/phpunit/tests/template.php
index 8d097a63d6ff6..a79702554dc64 100644
--- a/tests/phpunit/tests/template.php
+++ b/tests/phpunit/tests/template.php
@@ -122,9 +122,6 @@ public function set_up() {
 		remove_filter( 'should_load_block_assets_on_demand', '__return_true', 0 );
 		remove_action( 'wp_template_enhancement_output_buffer_started', 'wp_hoist_late_printed_styles' );
 
-		// Remove the hook which is added by WP_Interactivity_API::add_hooks() during bootstrapping.
-		remove_filter( 'wp_template_enhancement_output_buffer', array( wp_interactivity(), 'filter_template_output_buffer_add_router_managed_attribute' ), 20 );
-
 		global $wp_scripts, $wp_styles;
 		$this->original_wp_scripts = $wp_scripts;
 		$this->original_wp_styles  = $wp_styles;