From 9b205628053d684a0a3ad7bc82b8d521f4975bb5 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Fri, 19 May 2023 14:29:13 -0700
Subject: [PATCH 01/14] Implement basic module to experiment with
 speculationrules for prerendering.

---
 .../js-and-css/speculation-rules/helper.php   | 51 +++++++++++++++++++
 .../js-and-css/speculation-rules/hooks.php    | 44 ++++++++++++++++
 modules/js-and-css/speculation-rules/load.php | 19 +++++++
 3 files changed, 114 insertions(+)
 create mode 100644 modules/js-and-css/speculation-rules/helper.php
 create mode 100644 modules/js-and-css/speculation-rules/hooks.php
 create mode 100644 modules/js-and-css/speculation-rules/load.php

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
new file mode 100644
index 0000000000..505ea30312
--- /dev/null
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -0,0 +1,51 @@
+<?php
+/**
+ * Helper functions used for Speculation Rules.
+ *
+ * @package performance-lab
+ * @since n.e.x.t
+ */
+
+/**
+ * Prints the speculation rules in a cross-browser compatible way.
+ *
+ * For browsers that do not support speculation rules yet, the rules will not be loaded.
+ *
+ * @since n.e.x.t
+ *
+ * @return array Associative array of speculation rules by type.
+ */
+function plsr_get_speculation_rules() {
+	$prerender_rules = array(
+		array(
+			'source'    => 'document',
+			'where'     => array(
+				'and' => array(
+					// Prerender any URLs within the same site.
+					array(
+						'href_matches' => '/*\\?*',
+						'relative_to'  => 'document',
+					),
+					// Except for WP login and admin URLs.
+					array(
+						'not' => array(
+							'href_matches' => array(
+								'/wp-login.php\\?*#*',
+								'/wp-admin/*\\?*#*',
+							),
+						),
+					),
+					// And except for any links marked with a class to not prerender.
+					array(
+						'not' => array(
+							'selector_matches' => '.no-prerender',
+						),
+					),
+				),
+			),
+			'eagerness' => 'moderate',
+		),
+	);
+
+	return array( 'prerender' => $prerender_rules );
+}
diff --git a/modules/js-and-css/speculation-rules/hooks.php b/modules/js-and-css/speculation-rules/hooks.php
new file mode 100644
index 0000000000..474cb7f5fb
--- /dev/null
+++ b/modules/js-and-css/speculation-rules/hooks.php
@@ -0,0 +1,44 @@
+<?php
+/**
+ * Hook callbacks used for Speculation Rules.
+ *
+ * @package performance-lab
+ * @since n.e.x.t
+ */
+
+/**
+ * Prints the speculation rules in a cross-browser compatible way.
+ *
+ * For browsers that do not support speculation rules yet, the rules will not be loaded.
+ *
+ * @since n.e.x.t
+ */
+function plsr_print_speculation_rules() {
+	$rules = plsr_get_speculation_rules();
+	if ( empty( $rules ) ) {
+		return;
+	}
+
+	$script = <<<JS
+( function() {
+	if ( ! HTMLScriptElement.supports || ! HTMLScriptElement.supports( 'speculationrules' ) ) {
+		console.log( 'speculation rules not supported' );
+		return;
+	}
+
+	var specScript = document.createElement( 'script' );
+	specScript.type = 'speculationrules';
+	specScript.textContent = '%s';
+	console.log( 'speculation rules added' );
+	document.body.append( specScript );
+} )();
+JS;
+
+	wp_print_inline_script_tag(
+		sprintf(
+			$script,
+			str_replace( '\\', '\\\\', wp_json_encode( $rules ) )
+		)
+	);
+}
+add_action( 'wp_footer', 'plsr_print_speculation_rules' );
diff --git a/modules/js-and-css/speculation-rules/load.php b/modules/js-and-css/speculation-rules/load.php
new file mode 100644
index 0000000000..dada4031d5
--- /dev/null
+++ b/modules/js-and-css/speculation-rules/load.php
@@ -0,0 +1,19 @@
+<?php
+/**
+ * Module Name: Speculation Rules
+ * Description: Uses the Speculation Rules API to prerender linked URLs upon hover.
+ * Experimental: Yes
+ *
+ * @package performance-lab
+ * @since n.e.x.t
+ */
+
+// Define the constant.
+if ( defined( 'SPECULATION_RULES_VERSION' ) ) {
+	return;
+}
+
+define( 'SPECULATION_RULES_VERSION', 'Performance Lab ' . PERFLAB_VERSION );
+
+require_once __DIR__ . '/helper.php';
+require_once __DIR__ . '/hooks.php';

From c7f365e743e0c6e1fcad09cafb114f189dca216a Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 22 May 2023 13:51:01 -0700
Subject: [PATCH 02/14] Include proper backslashes in rules source.

---
 modules/js-and-css/speculation-rules/helper.php | 6 +++---
 modules/js-and-css/speculation-rules/hooks.php  | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index 505ea30312..3e59af4006 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -23,15 +23,15 @@ function plsr_get_speculation_rules() {
 				'and' => array(
 					// Prerender any URLs within the same site.
 					array(
-						'href_matches' => '/*\\?*',
+						'href_matches' => '/*\\\\?*',
 						'relative_to'  => 'document',
 					),
 					// Except for WP login and admin URLs.
 					array(
 						'not' => array(
 							'href_matches' => array(
-								'/wp-login.php\\?*#*',
-								'/wp-admin/*\\?*#*',
+								'/wp-login.php\\\\?*#*',
+								'/wp-admin/*\\\\?*#*',
 							),
 						),
 					),
diff --git a/modules/js-and-css/speculation-rules/hooks.php b/modules/js-and-css/speculation-rules/hooks.php
index 474cb7f5fb..afb953f9d0 100644
--- a/modules/js-and-css/speculation-rules/hooks.php
+++ b/modules/js-and-css/speculation-rules/hooks.php
@@ -37,7 +37,7 @@ function plsr_print_speculation_rules() {
 	wp_print_inline_script_tag(
 		sprintf(
 			$script,
-			str_replace( '\\', '\\\\', wp_json_encode( $rules ) )
+			wp_json_encode( $rules )
 		)
 	);
 }

From 286e50a35c980cef5bc4850be075de123a4ab6b3 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 22 May 2023 16:25:34 -0700
Subject: [PATCH 03/14] Add hook to make it easy to use origin trial.

---
 .../js-and-css/speculation-rules/hooks.php    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/modules/js-and-css/speculation-rules/hooks.php b/modules/js-and-css/speculation-rules/hooks.php
index afb953f9d0..a89ae709d4 100644
--- a/modules/js-and-css/speculation-rules/hooks.php
+++ b/modules/js-and-css/speculation-rules/hooks.php
@@ -42,3 +42,25 @@ function plsr_print_speculation_rules() {
 	);
 }
 add_action( 'wp_footer', 'plsr_print_speculation_rules' );
+
+/**
+ * Prints the tag to opt in to the Chrome origin trial if the token constant is defined.
+ *
+ * After opting in to the origin trial via https://github.com/WICG/nav-speculation/blob/main/chrome-2023q1-experiment-overview.md,
+ * please set your token in a `PLSR_ORIGIN_TRIAL_TOKEN` constant, e.g. in `wp-config.php`.
+ *
+ * This function is here temporarily and will eventually be removed.
+ *
+ * @since n.e.x.t
+ * @access private
+ * @ignore
+ */
+function plsr_print_origin_trial_optin() {
+	if ( ! defined( 'PLSR_ORIGIN_TRIAL_TOKEN' ) || ! PLSR_ORIGIN_TRIAL_TOKEN ) {
+		return;
+	}
+	?>
+	<meta http-equiv="origin-trial" content="<?php echo esc_attr( PLSR_ORIGIN_TRIAL_TOKEN ); ?>">
+	<?php
+}
+add_action( 'wp_head', 'plsr_print_origin_trial_optin' );

From 5b79bb8f98367a63a2aa87e498e1c2a99451f70f Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 13 Nov 2023 12:44:50 -0800
Subject: [PATCH 04/14] Print speculationrules script tag directly without
 using JS.

---
 .../js-and-css/speculation-rules/helper.php   |  6 ++---
 .../js-and-css/speculation-rules/hooks.php    | 25 +++----------------
 2 files changed, 7 insertions(+), 24 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index 3e59af4006..505ea30312 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -23,15 +23,15 @@ function plsr_get_speculation_rules() {
 				'and' => array(
 					// Prerender any URLs within the same site.
 					array(
-						'href_matches' => '/*\\\\?*',
+						'href_matches' => '/*\\?*',
 						'relative_to'  => 'document',
 					),
 					// Except for WP login and admin URLs.
 					array(
 						'not' => array(
 							'href_matches' => array(
-								'/wp-login.php\\\\?*#*',
-								'/wp-admin/*\\\\?*#*',
+								'/wp-login.php\\?*#*',
+								'/wp-admin/*\\?*#*',
 							),
 						),
 					),
diff --git a/modules/js-and-css/speculation-rules/hooks.php b/modules/js-and-css/speculation-rules/hooks.php
index a89ae709d4..5f77704220 100644
--- a/modules/js-and-css/speculation-rules/hooks.php
+++ b/modules/js-and-css/speculation-rules/hooks.php
@@ -7,9 +7,9 @@
  */
 
 /**
- * Prints the speculation rules in a cross-browser compatible way.
+ * Prints the speculation rules.
  *
- * For browsers that do not support speculation rules yet, the rules will not be loaded.
+ * For browsers that do not support speculation rules yet, the `script[type="speculationrules"]` tag will be ignored.
  *
  * @since n.e.x.t
  */
@@ -19,26 +19,9 @@ function plsr_print_speculation_rules() {
 		return;
 	}
 
-	$script = <<<JS
-( function() {
-	if ( ! HTMLScriptElement.supports || ! HTMLScriptElement.supports( 'speculationrules' ) ) {
-		console.log( 'speculation rules not supported' );
-		return;
-	}
-
-	var specScript = document.createElement( 'script' );
-	specScript.type = 'speculationrules';
-	specScript.textContent = '%s';
-	console.log( 'speculation rules added' );
-	document.body.append( specScript );
-} )();
-JS;
-
 	wp_print_inline_script_tag(
-		sprintf(
-			$script,
-			wp_json_encode( $rules )
-		)
+		wp_json_encode( $rules ),
+		array( 'type' => 'speculationrules' )
 	);
 }
 add_action( 'wp_footer', 'plsr_print_speculation_rules' );

From 25fc9da1b305ba9d848f8f75bc7e8cdb9540f7ef Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 13 Nov 2023 13:06:41 -0800
Subject: [PATCH 05/14] Introduce filter for which paths to exclude for
 speculative prerendering.

---
 .../js-and-css/speculation-rules/helper.php   | 39 +++++++++++++++++--
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index 505ea30312..2b02125b5e 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -16,6 +16,40 @@
  * @return array Associative array of speculation rules by type.
  */
 function plsr_get_speculation_rules() {
+	$base_href_exclude_paths = array(
+		'/wp-login.php',
+		'/wp-admin/*',
+	);
+	$href_exclude_paths      = $base_href_exclude_paths;
+
+	/**
+	 * Filters the paths for which speculative prerendering should be disabled.
+	 *
+	 * All paths should start in a forward slash, relative to the root document. The `*` can be used as a wildcard.
+	 * By default, the array includes `/wp-login.php` and `/wp-admin/*`.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param array $href_exclude_paths Paths to disable speculative prerendering for.
+	 */
+	$href_exclude_paths = (array) apply_filters( 'plsr_speculation_rules_href_exclude_paths', $href_exclude_paths );
+
+	// Ensure that there are no duplicates and that the base paths cannot be removed.
+	$href_exclude_paths = array_map(
+		static function ( $exclude_path ) {
+			if ( ! str_starts_with( $exclude_path, '/' ) ) {
+				$exclude_path = '/' . $exclude_path;
+			}
+			return $exclude_path . '\\?*#*';
+		},
+		array_unique(
+			array_merge(
+				$base_href_exclude_paths,
+				$href_exclude_paths
+			)
+		)
+	);
+
 	$prerender_rules = array(
 		array(
 			'source'    => 'document',
@@ -29,10 +63,7 @@ function plsr_get_speculation_rules() {
 					// Except for WP login and admin URLs.
 					array(
 						'not' => array(
-							'href_matches' => array(
-								'/wp-login.php\\?*#*',
-								'/wp-admin/*\\?*#*',
-							),
+							'href_matches' => $href_exclude_paths,
 						),
 					),
 					// And except for any links marked with a class to not prerender.

From ce1c4696a2a571fdd59035c41519c0350c7eda51 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 13 Nov 2023 13:30:13 -0800
Subject: [PATCH 06/14] Add CODEOWNERS entry.

---
 .github/CODEOWNERS | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index d2939e8d47..b8ae808fdb 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -53,3 +53,8 @@
 /modules/images/dominant-color-images                                       @pbearne @spacedmonkey
 /tests/modules/images/dominant-color-images                                 @pbearne @spacedmonkey
 /tests/testdata/modules/images/dominant-color-images                        @pbearne @spacedmonkey
+
+# Module: Speculation Rules
+/modules/js-and-css/speculation-rules                                       @felixarntz
+/tests/modules/js-and-css/speculation-rules                                 @felixarntz
+/tests/testdata/modules/js-and-css/speculation-rules                        @felixarntz

From f32401f680f44f628007d67e189c7401f61027b7 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 13 Nov 2023 13:30:45 -0800
Subject: [PATCH 07/14] Add initial test coverage for Speculation Rules.

---
 .../speculation-rules-helper-test.php         | 57 +++++++++++++++++++
 .../speculation-rules-test.php                | 20 +++++++
 2 files changed, 77 insertions(+)
 create mode 100644 tests/modules/js-and-css/speculation-rules/speculation-rules-helper-test.php
 create mode 100644 tests/modules/js-and-css/speculation-rules/speculation-rules-test.php

diff --git a/tests/modules/js-and-css/speculation-rules/speculation-rules-helper-test.php b/tests/modules/js-and-css/speculation-rules/speculation-rules-helper-test.php
new file mode 100644
index 0000000000..7889835985
--- /dev/null
+++ b/tests/modules/js-and-css/speculation-rules/speculation-rules-helper-test.php
@@ -0,0 +1,57 @@
+<?php
+/**
+ * Tests for speculation-rules helper file.
+ *
+ * @package performance-lab
+ * @group speculation-rules
+ */
+
+class Speculation_Rules_Helper_Tests extends WP_UnitTestCase {
+
+	public function test_plsr_get_speculation_rules() {
+		$rules = plsr_get_speculation_rules();
+
+		$this->assertIsArray( $rules );
+		$this->assertArrayHasKey( 'prerender', $rules );
+		$this->assertIsArray( $rules['prerender'] );
+		foreach ( $rules['prerender'] as $entry ) {
+			$this->assertIsArray( $entry );
+			$this->assertArrayHasKey( 'source', $entry );
+			$this->assertTrue( in_array( $entry['source'], array( 'list', 'document' ), true ) );
+		}
+	}
+
+	public function test_plsr_get_speculation_rules_href_exclude_paths() {
+		$rules              = plsr_get_speculation_rules();
+		$href_exclude_paths = $rules['prerender'][0]['where']['and'][1]['not']['href_matches'];
+
+		$this->assertSameSets(
+			array(
+				'/wp-login.php\\?*#*',
+				'/wp-admin/*\\?*#*',
+			),
+			$href_exclude_paths
+		);
+
+		// Add filter that attempts to replace base exclude paths with a custom path to exclude.
+		add_filter(
+			'plsr_speculation_rules_href_exclude_paths',
+			static function () {
+				return array( 'custom-file.php' );
+			}
+		);
+
+		$rules              = plsr_get_speculation_rules();
+		$href_exclude_paths = $rules['prerender'][0]['where']['and'][1]['not']['href_matches'];
+
+		// Ensure the base exclude paths are still present and that the custom path was formatted correctly.
+		$this->assertSameSets(
+			array(
+				'/wp-login.php\\?*#*',
+				'/wp-admin/*\\?*#*',
+				'/custom-file.php\\?*#*'
+			),
+			$href_exclude_paths
+		);
+	}
+}
diff --git a/tests/modules/js-and-css/speculation-rules/speculation-rules-test.php b/tests/modules/js-and-css/speculation-rules/speculation-rules-test.php
new file mode 100644
index 0000000000..8696e4b26f
--- /dev/null
+++ b/tests/modules/js-and-css/speculation-rules/speculation-rules-test.php
@@ -0,0 +1,20 @@
+<?php
+/**
+ * Tests for speculation-rules module.
+ *
+ * @package performance-lab
+ * @group speculation-rules
+ */
+
+class Speculation_Rules_Tests extends WP_UnitTestCase {
+
+	public function test_plsr_print_speculation_rules() {
+		$output = get_echo( 'plsr_print_speculation_rules' );
+
+		// Check the tag.
+		$this->assertStringContainsString( '<script type="speculationrules">', $output );
+
+		// Check that backslashes are correctly included.
+		$this->assertStringContainsString( '\\?*#*', $output );
+	}
+}

From 346f0cbfe50c979a8d3d980b031907e418681948 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 13 Nov 2023 13:36:41 -0800
Subject: [PATCH 08/14] Fix function name caught as misspelling.

---
 modules/js-and-css/speculation-rules/hooks.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/hooks.php b/modules/js-and-css/speculation-rules/hooks.php
index 5f77704220..ab78e0992b 100644
--- a/modules/js-and-css/speculation-rules/hooks.php
+++ b/modules/js-and-css/speculation-rules/hooks.php
@@ -38,7 +38,7 @@ function plsr_print_speculation_rules() {
  * @access private
  * @ignore
  */
-function plsr_print_origin_trial_optin() {
+function plsr_print_origin_trial_opt_in() {
 	if ( ! defined( 'PLSR_ORIGIN_TRIAL_TOKEN' ) || ! PLSR_ORIGIN_TRIAL_TOKEN ) {
 		return;
 	}
@@ -46,4 +46,4 @@ function plsr_print_origin_trial_optin() {
 	<meta http-equiv="origin-trial" content="<?php echo esc_attr( PLSR_ORIGIN_TRIAL_TOKEN ); ?>">
 	<?php
 }
-add_action( 'wp_head', 'plsr_print_origin_trial_optin' );
+add_action( 'wp_head', 'plsr_print_origin_trial_opt_in' );

From 6d338abd452215165784cf9010c7cd9f8dc41465 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 20 Nov 2023 09:43:36 -0800
Subject: [PATCH 09/14] Address CR feedback.

---
 .../js-and-css/speculation-rules/helper.php   | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index 2b02125b5e..ca615062bc 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -7,9 +7,10 @@
  */
 
 /**
- * Prints the speculation rules in a cross-browser compatible way.
+ * Returns the speculation rules.
  *
- * For browsers that do not support speculation rules yet, the rules will not be loaded.
+ * Plugins with features that rely on frontend URLs to exclude from prefetching or prerendering should use the
+ * {@see 'plsr_speculation_rules_href_exclude_paths'} filter to ensure those URL patterns are excluded.
  *
  * @since n.e.x.t
  *
@@ -35,14 +36,14 @@ function plsr_get_speculation_rules() {
 	$href_exclude_paths = (array) apply_filters( 'plsr_speculation_rules_href_exclude_paths', $href_exclude_paths );
 
 	// Ensure that there are no duplicates and that the base paths cannot be removed.
-	$href_exclude_paths = array_map(
-		static function ( $exclude_path ) {
-			if ( ! str_starts_with( $exclude_path, '/' ) ) {
-				$exclude_path = '/' . $exclude_path;
-			}
-			return $exclude_path . '\\?*#*';
-		},
-		array_unique(
+	$href_exclude_paths = array_unique(
+		array_map(
+			static function ( $exclude_path ) {
+				if ( ! str_starts_with( $exclude_path, '/' ) ) {
+					$exclude_path = '/' . $exclude_path;
+				}
+				return $exclude_path . '\\?*#*';
+			},
 			array_merge(
 				$base_href_exclude_paths,
 				$href_exclude_paths

From 7404f02d2ea945e2f7621ba3de431f8af6f8bf78 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Mon, 20 Nov 2023 09:50:00 -0800
Subject: [PATCH 10/14] Add TODO regarding eventual wildcard removal.

---
 modules/js-and-css/speculation-rules/helper.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index ca615062bc..fb3bd4986b 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -42,6 +42,13 @@ static function ( $exclude_path ) {
 				if ( ! str_starts_with( $exclude_path, '/' ) ) {
 					$exclude_path = '/' . $exclude_path;
 				}
+
+				/*
+				 * TODO: Remove this eventually as it's no longer needed in Chrome 121+.
+				 * See:
+				 * * https://github.com/whatwg/urlpattern/issues/179
+				 * * https://chromium-review.googlesource.com/c/chromium/src/+/4975595
+				 */
 				return $exclude_path . '\\?*#*';
 			},
 			array_merge(

From ce0e56bb7adf52f5b2141b167226c3382099e955 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Tue, 21 Nov 2023 13:09:28 -0800
Subject: [PATCH 11/14] Add speculation rules URL pattern prefixer to support
 WordPress site in subdirectories.

---
 .../class-plsr-url-pattern-prefixer.php       | 91 +++++++++++++++++++
 .../js-and-css/speculation-rules/helper.php   | 16 ++--
 modules/js-and-css/speculation-rules/load.php |  1 +
 .../plsr-url-pattern-prefixer-test.php        | 69 ++++++++++++++
 4 files changed, 170 insertions(+), 7 deletions(-)
 create mode 100644 modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
 create mode 100644 tests/modules/js-and-css/speculation-rules/plsr-url-pattern-prefixer-test.php

diff --git a/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
new file mode 100644
index 0000000000..ddbc2410c9
--- /dev/null
+++ b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
@@ -0,0 +1,91 @@
+<?php
+/**
+ * Class 'PLSR_URL_Pattern_Prefixer'.
+ *
+ * @package performance-lab
+ * @since n.e.x.t
+ */
+
+/**
+ * Class for prefixing URL patterns.
+ *
+ * @since n.e.x.t
+ */
+class PLSR_URL_Pattern_Prefixer {
+
+	/**
+	 * Map of `$context_string => $base_path` pairs.
+	 *
+	 * @since n.e.x.t
+	 * @var array
+	 */
+	private $contexts;
+
+	/**
+	 * Constructor.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param array $contexts Optional. Map of `$context_string => $base_path` pairs. Default is the contexts returned
+	 *                        by the {@see PLSR_URL_Pattern_Prefixer::get_default_contexts()} method.
+	 */
+	public function __construct( array $contexts = array() ) {
+		if ( $contexts ) {
+			$this->contexts = array_map( 'trailingslashit', $contexts );
+		} else {
+			$this->contexts = self::get_default_contexts();
+		}
+	}
+
+	/**
+	 * Prefixes the given URL path pattern with the base path for the given context.
+	 *
+	 * This ensures that these path patterns work correctly on WordPress subdirectory sites, for example in a multisite
+	 * network, or when WordPress itself is installed in a subdirectory of the hostname.
+	 *
+	 * The given URL path pattern is only prefixed if it does not already include the expected prefix.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param string $path_pattern URL pattern starting with the path segment.
+	 * @param string $context      Optional. Either 'home' (any frontend content) or 'site' (content relative to the
+	 *                             directory that WordPress is installed in). Default 'home'.
+	 * @return string URL pattern, prefixed as necessary.
+	 */
+	public function prefix_path_pattern( string $path_pattern, string $context = 'home' ) {
+		// If context path does not exist, the context is invalid.
+		if ( ! isset( $this->contexts[ $context ] ) ) {
+			_doing_it_wrong(
+				__FUNCTION__,
+				sprintf(
+					/* translators: %s: context string */
+					esc_html__( 'Invalid context %s.', 'performance-lab' ),
+					esc_html( $context )
+				),
+				'Performance Lab n.e.x.t'
+			);
+			return $path_pattern;
+		}
+
+		// If the path already starts with the context path (including '/'), there is nothing to prefix.
+		if ( str_starts_with( $path_pattern, $this->contexts[ $context ] ) ) {
+			return $path_pattern;
+		}
+
+		return $this->contexts[ $context ] . ltrim( $path_pattern, '/' );
+	}
+
+	/**
+	 * Returns the default contexts used by the class.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array Map of `$context_string => $base_path` pairs.
+	 */
+	public static function get_default_contexts(): array {
+		return array(
+			'home' => trailingslashit( wp_parse_url( home_url( '/' ), PHP_URL_PATH ) ),
+			'site' => trailingslashit( wp_parse_url( site_url( '/' ), PHP_URL_PATH ) ),
+		);
+	}
+}
diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index fb3bd4986b..7c2b2b9e06 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -17,9 +17,11 @@
  * @return array Associative array of speculation rules by type.
  */
 function plsr_get_speculation_rules() {
+	$prefixer = new PLSR_URL_Pattern_Prefixer();
+
 	$base_href_exclude_paths = array(
-		'/wp-login.php',
-		'/wp-admin/*',
+		$prefixer->prefix_path_pattern( '/wp-login.php', 'site' ),
+		$prefixer->prefix_path_pattern( '/wp-admin/*', 'site' ),
 	);
 	$href_exclude_paths      = $base_href_exclude_paths;
 
@@ -29,6 +31,8 @@ function plsr_get_speculation_rules() {
 	 * All paths should start in a forward slash, relative to the root document. The `*` can be used as a wildcard.
 	 * By default, the array includes `/wp-login.php` and `/wp-admin/*`.
 	 *
+	 * If the WordPress site is in a subdirectory, the exclude paths will automatically be prefixed as necessary.
+	 *
 	 * @since n.e.x.t
 	 *
 	 * @param array $href_exclude_paths Paths to disable speculative prerendering for.
@@ -38,10 +42,8 @@ function plsr_get_speculation_rules() {
 	// Ensure that there are no duplicates and that the base paths cannot be removed.
 	$href_exclude_paths = array_unique(
 		array_map(
-			static function ( $exclude_path ) {
-				if ( ! str_starts_with( $exclude_path, '/' ) ) {
-					$exclude_path = '/' . $exclude_path;
-				}
+			static function ( $exclude_path ) use ( $prefixer ) {
+				$exclude_path = $prefixer->prefix_path_pattern( $exclude_path );
 
 				/*
 				 * TODO: Remove this eventually as it's no longer needed in Chrome 121+.
@@ -65,7 +67,7 @@ static function ( $exclude_path ) {
 				'and' => array(
 					// Prerender any URLs within the same site.
 					array(
-						'href_matches' => '/*\\?*',
+						'href_matches' => $prefixer->prefix_path_pattern( '/*\\?*' ),
 						'relative_to'  => 'document',
 					),
 					// Except for WP login and admin URLs.
diff --git a/modules/js-and-css/speculation-rules/load.php b/modules/js-and-css/speculation-rules/load.php
index dada4031d5..d0f070ca67 100644
--- a/modules/js-and-css/speculation-rules/load.php
+++ b/modules/js-and-css/speculation-rules/load.php
@@ -15,5 +15,6 @@
 
 define( 'SPECULATION_RULES_VERSION', 'Performance Lab ' . PERFLAB_VERSION );
 
+require_once __DIR__ . '/class-plsr-url-pattern-prefixer.php';
 require_once __DIR__ . '/helper.php';
 require_once __DIR__ . '/hooks.php';
diff --git a/tests/modules/js-and-css/speculation-rules/plsr-url-pattern-prefixer-test.php b/tests/modules/js-and-css/speculation-rules/plsr-url-pattern-prefixer-test.php
new file mode 100644
index 0000000000..6fb3849031
--- /dev/null
+++ b/tests/modules/js-and-css/speculation-rules/plsr-url-pattern-prefixer-test.php
@@ -0,0 +1,69 @@
+<?php
+/**
+ * Tests for PLSR_URL_Pattern_Prefixer class.
+ *
+ * @package performance-lab
+ * @group speculation-rules
+ */
+
+class PLSR_URL_Pattern_Prefixer_Tests extends WP_UnitTestCase {
+
+	/**
+	 * @dataProvider data_prefix_path_pattern
+	 */
+	public function test_prefix_path_pattern( $base_path, $path_pattern, $expected ) {
+		$p = new PLSR_URL_Pattern_Prefixer( array( 'demo' => $base_path ) );
+
+		$this->assertSame(
+			$expected,
+			$p->prefix_path_pattern( $path_pattern, 'demo' )
+		);
+	}
+
+	public function data_prefix_path_pattern() {
+		return array(
+			array( '/', '/my-page/', '/my-page/' ),
+			array( '/', 'my-page/', '/my-page/' ),
+			array( '/wp/', '/my-page/', '/wp/my-page/' ),
+			array( '/wp/', 'my-page/', '/wp/my-page/' ),
+			array( '/wp/', '/blog/2023/11/new-post/', '/wp/blog/2023/11/new-post/' ),
+			array( '/wp/', 'blog/2023/11/new-post/', '/wp/blog/2023/11/new-post/' ),
+			array( '/subdir', '/my-page/', '/subdir/my-page/' ),
+			array( '/subdir', 'my-page/', '/subdir/my-page/' ),
+			// Missing trailing slash still works, does not consider "cut-off" directory names.
+			array( '/subdir', '/subdirectory/my-page/', '/subdir/subdirectory/my-page/' ),
+			array( '/subdir', 'subdirectory/my-page/', '/subdir/subdirectory/my-page/' ),
+		);
+	}
+
+	public function test_get_default_contexts() {
+		$contexts = PLSR_URL_Pattern_Prefixer::get_default_contexts();
+
+		$this->assertArrayHasKey( 'home', $contexts );
+		$this->assertArrayHasKey( 'site', $contexts );
+		$this->assertSame( '/', $contexts['home'] );
+		$this->assertSame( '/', $contexts['site'] );
+	}
+
+	public function test_get_default_contexts_with_subdirectories() {
+		add_filter(
+			'home_url',
+			static function () {
+				return 'https://example.com/subdir/';
+			}
+		);
+		add_filter(
+			'site_url',
+			static function () {
+				return 'https://example.com/subdir/wp/';
+			}
+		);
+
+		$contexts = PLSR_URL_Pattern_Prefixer::get_default_contexts();
+
+		$this->assertArrayHasKey( 'home', $contexts );
+		$this->assertArrayHasKey( 'site', $contexts );
+		$this->assertSame( '/subdir/', $contexts['home'] );
+		$this->assertSame( '/subdir/wp/', $contexts['site'] );
+	}
+}

From cd536d5ef082203e1c1f36f3945927f710798878 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Tue, 28 Nov 2023 14:28:55 -0800
Subject: [PATCH 12/14] Add missing return type hint.

---
 .../speculation-rules/class-plsr-url-pattern-prefixer.php       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
index ddbc2410c9..e6a5102359 100644
--- a/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
+++ b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
@@ -52,7 +52,7 @@ public function __construct( array $contexts = array() ) {
 	 *                             directory that WordPress is installed in). Default 'home'.
 	 * @return string URL pattern, prefixed as necessary.
 	 */
-	public function prefix_path_pattern( string $path_pattern, string $context = 'home' ) {
+	public function prefix_path_pattern( string $path_pattern, string $context = 'home' ): string {
 		// If context path does not exist, the context is invalid.
 		if ( ! isset( $this->contexts[ $context ] ) ) {
 			_doing_it_wrong(

From 5c134db098c2a6ac0a7279f6949c90fdfb6958e7 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@google.com>
Date: Tue, 5 Dec 2023 15:34:55 -0800
Subject: [PATCH 13/14] Remove unnecessary relative_to directive.

---
 modules/js-and-css/speculation-rules/helper.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/modules/js-and-css/speculation-rules/helper.php b/modules/js-and-css/speculation-rules/helper.php
index 7c2b2b9e06..ffdc19a1ad 100644
--- a/modules/js-and-css/speculation-rules/helper.php
+++ b/modules/js-and-css/speculation-rules/helper.php
@@ -68,7 +68,6 @@ static function ( $exclude_path ) use ( $prefixer ) {
 					// Prerender any URLs within the same site.
 					array(
 						'href_matches' => $prefixer->prefix_path_pattern( '/*\\?*' ),
-						'relative_to'  => 'document',
 					),
 					// Except for WP login and admin URLs.
 					array(

From 813a75760455d0ab654f484cc627bee56fda9714 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felixarntz@users.noreply.github.com>
Date: Wed, 6 Dec 2023 08:53:01 -0800
Subject: [PATCH 14/14] Simplify escaping.

Co-authored-by: Weston Ruter <westonruter@google.com>
---
 .../class-plsr-url-pattern-prefixer.php                | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
index e6a5102359..7f4bd2ea8a 100644
--- a/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
+++ b/modules/js-and-css/speculation-rules/class-plsr-url-pattern-prefixer.php
@@ -57,10 +57,12 @@ public function prefix_path_pattern( string $path_pattern, string $context = 'ho
 		if ( ! isset( $this->contexts[ $context ] ) ) {
 			_doing_it_wrong(
 				__FUNCTION__,
-				sprintf(
-					/* translators: %s: context string */
-					esc_html__( 'Invalid context %s.', 'performance-lab' ),
-					esc_html( $context )
+				esc_html(
+					sprintf(
+						/* translators: %s: context string */
+						__( 'Invalid context %s.', 'performance-lab' ),
+						$context
+					)
 				),
 				'Performance Lab n.e.x.t'
 			);