Script Loader: Add private script modules via scoped import maps.

Introduces a `scopes` arg on `wp_register_script_module()` and `wp_enqueue_script_module()` that constrains which importers can resolve a module's bare specifier. Modules with `scopes` are emitted under the import map's top-level `scopes` field, not `imports`.

Each `scopes` entry is one of:
- A non-empty URL prefix string, emitted as-authored.
- `array( 'module_id' => $id )`, resolved at print time to the directory of the named module's filtered src URL (CDN-aware via the existing `script_module_loader_src` filter).

`scopes => array()` registers a module that is not resolvable via bare specifier from anywhere; static dependencies on such a module are treated like missing dependencies.

This is API hygiene + bare-specifier scoping per the import map spec — not a security boundary. Files remain fetchable via direct URL `import()`; resolution failure for out-of-scope importers is a runtime `TypeError`.

Author: sirreal

src/wp-includes/class-wp-script-modules.php

@@ -21,6 +21,7 @@
  *     fetchpriority: 'auto'|'low'|'high',
  *     textdomain?: string,
  *     translations_path?: string,
+ *     scopes?: array<int, string|array{ module_id: string }>,
  * }
  */
 class WP_Script_Modules {
@@ -98,36 +99,54 @@ class WP_Script_Modules {
 	 *
 	 * @since 6.5.0
 	 * @since 6.9.0 Added the $args parameter.
-	 *
-	 * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
-	 *                                                     final import map.
-	 * @param string                              $src     Optional. Full URL of the script module, or path of the script module relative
-	 *                                                     to the WordPress root directory. If it is provided and the script module has
-	 *                                                     not been registered yet, it will be registered.
-	 * @param array<string|array<string, string>> $deps    {
-	 *                                                         Optional. List of dependencies.
-	 *
-	 *                                                         @type string|array<string, string> ...$0 {
-	 *                                                             An array of script module identifiers of the dependencies of this script
-	 *                                                             module. The dependencies can be strings or arrays. If they are arrays,
-	 *                                                             they need an `id` key with the script module identifier, and can contain
-	 *                                                             an `import` key with either `static` or `dynamic`. By default,
-	 *                                                             dependencies that don't contain an `import` key are considered static.
-	 *
-	 *                                                             @type string $id     The script module identifier.
-	 *                                                             @type string $import Optional. Import type. May be either `static` or
-	 *                                                                                  `dynamic`. Defaults to `static`.
-	 *                                                         }
-	 *                                                     }
-	 * @param string|false|null                   $version Optional. String specifying the script module version number. Defaults to false.
-	 *                                                     It is added to the URL as a query string for cache busting purposes. If $version
-	 *                                                     is set to false, the version number is the currently installed WordPress version.
-	 *                                                     If $version is set to null, no version is added.
-	 * @param array<string, string|bool>          $args    {
+	 * @since 7.1.0 Added the `scopes` key to the $args parameter.
+	 *
+	 * @param string                                            $id      The identifier of the script module. Should be unique. It will be used in the
+	 *                                                                   final import map.
+	 * @param string                                            $src     Optional. Full URL of the script module, or path of the script module relative
+	 *                                                                   to the WordPress root directory. If it is provided and the script module has
+	 *                                                                   not been registered yet, it will be registered.
+	 * @param array<string|array<string, string>>               $deps    {
+	 *                                                                       Optional. List of dependencies.
+	 *
+	 *                                                                       @type string|array<string, string> ...$0 {
+	 *                                                                           An array of script module identifiers of the dependencies of this script
+	 *                                                                           module. The dependencies can be strings or arrays. If they are arrays,
+	 *                                                                           they need an `id` key with the script module identifier, and can contain
+	 *                                                                           an `import` key with either `static` or `dynamic`. By default,
+	 *                                                                           dependencies that don't contain an `import` key are considered static.
+	 *
+	 *                                                                           @type string $id     The script module identifier.
+	 *                                                                           @type string $import Optional. Import type. May be either `static` or
+	 *                                                                                                `dynamic`. Defaults to `static`.
+	 *                                                                       }
+	 *                                                                   }
+	 * @param string|false|null                                 $version Optional. String specifying the script module version number. Defaults to false.
+	 *                                                                   It is added to the URL as a query string for cache busting purposes. If $version
+	 *                                                                   is set to false, the version number is the currently installed WordPress version.
+	 *                                                                   If $version is set to null, no version is added.
+	 * @param array<string, string|bool|array<string|array<string, string>>|null> $args {
 	 *     Optional. An array of additional args. Default empty array.
 	 *
 	 *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
 	 *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
+	 *     @type array|null          $scopes        Optional. Constrains the importers that can resolve this module's bare specifier.
+	 *                                              When omitted or null, the module is public (top-level `imports`). When an array is
+	 *                                              provided, the module is emitted under the import map's `scopes` keyed by each entry,
+	 *                                              and is not present in top-level `imports`. An empty array means the module is
+	 *                                              registered but cannot be resolved via bare specifier from anywhere; static
+	 *                                              dependencies on such a module are treated like missing dependencies.
+	 *                                              Each entry is one of:
+	 *                                              - A non-empty string URL prefix, emitted as-authored. WordPress URL filters such as
+	 *                                                `script_module_loader_src` are NOT applied to string scopes; authors are
+	 *                                                responsible for matching the final browser URL.
+	 *                                              - `array( 'module_id' => string )` — at print time, resolves to the directory
+	 *                                                portion of the named registered module's filtered src URL. Recommended for
+	 *                                                CDN-aware scoping because it goes through the existing `script_module_loader_src`
+	 *                                                filter.
+	 *                                              This is an API-hygiene mechanism, not a security boundary; the file remains
+	 *                                              fetchable, and any caller can still list the module's id in `$deps` or call
+	 *                                              `wp_enqueue_script_module()` on it. Resolution failure is a runtime `TypeError`.
 	 * }
 	 */
 	public function register( string $id, string $src, array $deps = array(), $version = false, array $args = array() ) {
@@ -178,13 +197,55 @@ public function register( string $id, string $src, array $deps = array(), $versi
 				}
 			}
 
-			$this->registered[ $id ] = array(
+			$registered_module = array(
 				'src'           => $src,
 				'version'       => $version,
 				'dependencies'  => $dependencies,
 				'in_footer'     => $in_footer,
 				'fetchpriority' => $fetchpriority,
 			);
+
+			if ( array_key_exists( 'scopes', $args ) && null !== $args['scopes'] ) {
+				if ( ! is_array( $args['scopes'] ) ) {
+					_doing_it_wrong(
+						__METHOD__,
+						__( 'The "scopes" arg must be null or an array.' ),
+						'7.1.0'
+					);
+				} else {
+					$validated_scopes = array();
+					foreach ( $args['scopes'] as $scope_entry ) {
+						if ( is_string( $scope_entry ) ) {
+							if ( '' === $scope_entry ) {
+								_doing_it_wrong(
+									__METHOD__,
+									__( 'Empty string scope entry; entries must be non-empty.' ),
+									'7.1.0'
+								);
+								continue;
+							}
+							$validated_scopes[] = $scope_entry;
+						} elseif (
+							is_array( $scope_entry ) &&
+							1 === count( $scope_entry ) &&
+							isset( $scope_entry['module_id'] ) &&
+							is_string( $scope_entry['module_id'] ) &&
+							'' !== $scope_entry['module_id']
+						) {
+							$validated_scopes[] = array( 'module_id' => $scope_entry['module_id'] );
+						} else {
+							_doing_it_wrong(
+								__METHOD__,
+								__( 'Each scope entry must be a non-empty string or [ "module_id" => non-empty string ].' ),
+								'7.1.0'
+							);
+						}
+					}
+					$registered_module['scopes'] = $validated_scopes;
+				}
+			}
+
+			$this->registered[ $id ] = $registered_module;
 		}
 	}
 
@@ -270,6 +331,7 @@ public function set_in_footer( string $id, bool $in_footer ): bool {
 	 *
 	 * @since 6.5.0
 	 * @since 6.9.0 Added the $args parameter.
+	 * @since 7.1.0 Added the `scopes` key to the $args parameter.
 	 *
 	 * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
 	 *                                                     final import map.
@@ -295,11 +357,12 @@ public function set_in_footer( string $id, bool $in_footer ): bool {
 	 *                                                     It is added to the URL as a query string for cache busting purposes. If $version
 	 *                                                     is set to false, the version number is the currently installed WordPress version.
 	 *                                                     If $version is set to null, no version is added.
-	 * @param array<string, string|bool>          $args    {
+	 * @param array<string, string|bool|array<string|array<string, string>>|null> $args {
 	 *     Optional. An array of additional args. Default empty array.
 	 *
 	 *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
 	 *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
+	 *     @type array|null          $scopes        Optional. See {@see WP_Script_Modules::register()} for details.
 	 * }
 	 */
 	public function enqueue( string $id, string $src = '', array $deps = array(), $version = false, array $args = array() ) {
@@ -619,7 +682,7 @@ public function print_script_module_preloads() {
 	 */
 	public function print_import_map() {
 		$import_map = $this->get_import_map();
-		if ( ! empty( $import_map['imports'] ) ) {
+		if ( ! empty( $import_map['imports'] ) || ! empty( $import_map['scopes'] ) ) {
 			wp_print_inline_script_tag(
 				(string) wp_json_encode( $import_map, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ),
 				array(
@@ -635,11 +698,13 @@ public function print_import_map() {
 	 *
 	 * @since 6.5.0
 	 * @since 7.0.0 Script module dependencies ('module_dependencies') of classic scripts are now included.
+	 * @since 7.1.0 Scoped (private) modules are emitted under a top-level `scopes` key.
 	 *
 	 * @global WP_Scripts $wp_scripts
 	 *
-	 * @return array<string, array<string, string>> Array with an `imports` key mapping to an array of script module
-	 *                                              identifiers and their respective URLs, including the version query.
+	 * @return array Array with an `imports` key mapping module identifiers to URLs (including the version query),
+	 *               and an optional `scopes` key mapping scope-prefix URLs to per-scope import maps.
+	 * @phpstan-return array{ imports: array<string, string>, scopes?: array<string, array<string, string>> }
 	 */
 	private function get_import_map(): array {
 		global $wp_scripts;
@@ -714,13 +779,34 @@ private function get_import_map(): array {
 				array_keys( $this->get_dependencies( array_merge( $this->queue, $classic_script_module_dependencies ) ) )
 			)
 		);
+
+		$scopes = array();
 		foreach ( $ids as $id ) {
 			$src = $this->get_src( $id );
-			if ( '' !== $src ) {
+			if ( '' === $src ) {
+				continue;
+			}
+
+			if ( isset( $this->registered[ $id ]['scopes'] ) ) {
+				// Scoped (private) modules are emitted only under their resolved scope keys.
+				// Modules with `scopes => array()` resolve to no keys and are intentionally
+				// absent from both `imports` and `scopes`.
+				foreach ( $this->get_scope_keys( $id ) as $scope_key ) {
+					if ( ! isset( $scopes[ $scope_key ] ) ) {
+						$scopes[ $scope_key ] = array();
+					}
+					$scopes[ $scope_key ][ $id ] = $src;
+				}
+			} else {
 				$imports[ $id ] = $src;
 			}
 		}
-		return array( 'imports' => $imports );
+
+		$import_map = array( 'imports' => $imports );
+		if ( ! empty( $scopes ) ) {
+			$import_map['scopes'] = $scopes;
+		}
+		return $import_map;
 	}
 
 	/**
@@ -911,18 +997,49 @@ private function sort_item_dependencies( string $id, array $import_types, array
 
 		// If the item requires dependencies that do not exist, fail.
 		$missing_dependencies = array_diff( $dependency_ids, array_keys( $this->registered ) );
-		if ( count( $missing_dependencies ) > 0 ) {
+
+		// Dependencies on modules registered with empty `scopes` (`scopes => array()`)
+		// cannot be resolved via bare specifier from anywhere; treat them as missing
+		// so the dependent does not emit and a developer warning surfaces early.
+		$unreachable_dependencies = array();
+		foreach ( $dependency_ids as $dep_id ) {
+			if ( in_array( $dep_id, $missing_dependencies, true ) ) {
+				continue;
+			}
+			if (
+				isset( $this->registered[ $dep_id ]['scopes'] ) &&
+				array() === $this->registered[ $dep_id ]['scopes']
+			) {
+				$unreachable_dependencies[] = $dep_id;
+			}
+		}
+
+		if ( count( $missing_dependencies ) > 0 || count( $unreachable_dependencies ) > 0 ) {
 			if ( ! in_array( $id, $this->modules_with_missing_dependencies, true ) ) {
-				_doing_it_wrong(
-					get_class( $this ) . '::register',
-					sprintf(
-						/* translators: 1: Script module ID, 2: List of missing dependency IDs. */
-						__( 'The script module with the ID "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
-						$id,
-						implode( wp_get_list_item_separator(), $missing_dependencies )
-					),
-					'6.9.1'
-				);
+				if ( count( $missing_dependencies ) > 0 ) {
+					_doing_it_wrong(
+						get_class( $this ) . '::register',
+						sprintf(
+							/* translators: 1: Script module ID, 2: List of missing dependency IDs. */
+							__( 'The script module with the ID "%1$s" was enqueued with dependencies that are not registered: %2$s.' ),
+							$id,
+							implode( wp_get_list_item_separator(), $missing_dependencies )
+						),
+						'6.9.1'
+					);
+				}
+				if ( count( $unreachable_dependencies ) > 0 ) {
+					_doing_it_wrong(
+						get_class( $this ) . '::register',
+						sprintf(
+							/* translators: 1: Script module ID, 2: List of unreachable dependency IDs. */
+							__( 'The script module with the ID "%1$s" was enqueued with dependencies that are registered with empty scopes and cannot be resolved via bare specifier: %2$s.' ),
+							$id,
+							implode( wp_get_list_item_separator(), $unreachable_dependencies )
+						),
+						'7.1.0'
+					);
+				}
 				$this->modules_with_missing_dependencies[] = $id;
 			}
 
@@ -1000,6 +1117,77 @@ private function get_src( string $id ): string {
 		return $src;
 	}
 
+	/**
+	 * Resolves the import-map scope keys for a registered scoped script module.
+	 *
+	 * String entries are returned as-authored. `[ 'module_id' => $other_id ]` entries are
+	 * resolved to the directory portion of the named module's filtered src URL (query and
+	 * fragment stripped, path truncated to the last "/"). Lookup failures are dropped with
+	 * `_doing_it_wrong`.
+	 *
+	 * Returns an empty array for unregistered modules, public modules (no `scopes`), or
+	 * modules whose `scopes` entries all failed to resolve.
+	 *
+	 * @since 7.1.0
+	 *
+	 * @param string $id The script module identifier.
+	 * @return string[] Resolved, unique scope keys.
+	 */
+	private function get_scope_keys( string $id ): array {
+		if ( ! isset( $this->registered[ $id ]['scopes'] ) ) {
+			return array();
+		}
+
+		$keys = array();
+		foreach ( $this->registered[ $id ]['scopes'] as $entry ) {
+			if ( is_string( $entry ) ) {
+				$keys[ $entry ] = true;
+				continue;
+			}
+
+			$other_id = $entry['module_id'];
+			if ( ! isset( $this->registered[ $other_id ] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: Scope module id; 2: Owning module id. */
+						__( 'Scope entry references unregistered module "%1$s" for module "%2$s".' ),
+						$other_id,
+						$id
+					),
+					'7.1.0'
+				);
+				continue;
+			}
+
+			$other_src = $this->get_src( $other_id );
+			if ( '' === $other_src ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: Scope module id; 2: Owning module id. */
+						__( 'Scope entry references module "%1$s" with empty src for module "%2$s".' ),
+						$other_id,
+						$id
+					),
+					'7.1.0'
+				);
+				continue;
+			}
+
+			// Strip query and fragment, truncate to last "/" to derive directory.
+			$path       = preg_replace( '~[?#].*$~', '', $other_src );
+			$last_slash = strrpos( (string) $path, '/' );
+			if ( false === $last_slash ) {
+				continue;
+			}
+
+			$keys[ substr( (string) $path, 0, $last_slash + 1 ) ] = true;
+		}
+
+		return array_keys( $keys );
+	}
+
 	/**
 	 * Print data associated with Script Modules.
 	 *
@@ -1021,12 +1209,23 @@ public function print_script_module_data(): void {
 			}
 			$modules[ $id ] = true;
 		}
-		foreach ( array_keys( $this->get_import_map()['imports'] ) as $id ) {
+		$import_map = $this->get_import_map();
+		foreach ( array_keys( $import_map['imports'] ) as $id ) {
 			if ( '@wordpress/a11y' === $id ) {
 				$this->a11y_available = true;
 			}
 			$modules[ $id ] = true;
 		}
+		if ( isset( $import_map['scopes'] ) ) {
+			foreach ( $import_map['scopes'] as $scope_entries ) {
+				foreach ( array_keys( $scope_entries ) as $id ) {
+					if ( '@wordpress/a11y' === $id ) {
+						$this->a11y_available = true;
+					}
+					$modules[ $id ] = true;
+				}
+			}
+		}
 
 		foreach ( array_keys( $modules ) as $module_id ) {
 			/**