Docs: Clarify HTML Processor subtree traversal

Gruntfile.js

@@ -2370,7 +2370,7 @@ module.exports = function(grunt) {
 
 	grunt.registerTask( 'browserslist:update', 'Update the local database of browser supports', function() {
 		grunt.log.writeln( `Updating browsers list` );
-		spawn( 'npx', [ 'browserslist@latest', '--update-db' ], {
+		spawn( 'npx', [ 'update-browserslist-db@latest' ], {
 			cwd: __dirname,
 			stdio: 'inherit',
 		} );

README.md

@@ -39,9 +39,9 @@ You can get started using the local development environment with these steps:
 1. Then clone the forked repository to your computer using `git clone https://github.com/<your-username>/wordpress-develop.git`.
 1. Navigate into the directory for the cloned repository using `cd wordpress-develop`.
 1. Add the origin repo as an `upstream` remote via `git remote add upstream https://github.com/WordPress/wordpress-develop.git`.
-1. Then you can keep your branches up to date via `git pull --ff upstream/trunk`, for example.
+1. Then you can keep your branches up to date via `git pull --ff upstream trunk`, for example.
 
-Alternatively, if you have the [GitHub CLI](https://cli.github.com/) installed, you can simply run `gh repo fork WordPress/wordpress-develop --clone --remote` ([docs](https://cli.github.com/manual/gh_repo_fork)). This command will:
+Alternatively, if you have the [GitHub CLI](https://cli.github.com/) installed, you can simply run `gh repo fork WordPress/wordpress-develop --clone` ([docs](https://cli.github.com/manual/gh_repo_fork)). This command will:
 1. Fork the repository to your account (use the `--org` flag to clone into an organization).
 1. Clone the repository to your machine. 
 1. Add `WordPress/wordpress-develop` as `upstream` and set it to the default `remote` repository

src/wp-admin/css/admin-menu.css

@@ -417,6 +417,10 @@ ul#adminmenu > li.current > a.current:after {
 	border-color: transparent;
 }
 
+.js #adminmenu .wp-submenu .wp-submenu-head {
+	cursor: pointer;
+}
+
 #adminmenu li.current,
 .folded #adminmenu li.wp-menu-open {
 	border: 0 none;

src/wp-includes/css/buttons.css

@@ -194,27 +194,16 @@ TABLE OF CONTENTS:
 	color: var(--wp-admin-theme-color-darker-20, #183ad6);
 	border-color: var(--wp-admin-theme-color, #3858e9);
 	box-shadow: inset 0 2px 6px -2px  var(--wp-admin-theme-color-darker-20);
-	position: relative;
+	outline: 3px solid transparent;
+	outline-offset: -3px;
 }
 
 .wp-core-ui .button.active:focus {
 	background-color: rgba(var(--wp-admin-theme-color--rgb), 0.08);
 	color: var(--wp-admin-theme-color-darker-20, #183ad6);
 	border-color: var(--wp-admin-theme-color-darker-20, #183ad6);
 	box-shadow: inset 0 2px 6px -2px  var(--wp-admin-theme-color-darker-20), 0 0 0 var(--wp-admin-border-width-focus, 1.5px) var(--wp-admin-theme-color, #3858e9);
-}
-
-/* Only visible in Windows High Contrast mode */
-.wp-core-ui .button.active:before {
-	content: "";
-	display: block;
-	position: absolute;
-	width: 100%;
-	height: 0;
-	border-top: 3px solid transparent;
-	bottom: 0;
-	left: 0;
-	box-sizing: border-box;
+	outline-width: 4px;
 }
 
 .wp-core-ui .button[disabled],

src/wp-includes/html-api/class-wp-html-processor.php

@@ -767,9 +767,52 @@ public function next_tag( $query = null ): bool {
 	/**
 	 * Finds the next token in the HTML document.
 	 *
-	 * This doesn't currently have a way to represent non-tags and doesn't process
-	 * semantic rules for text nodes. For access to the raw tokens consider using
-	 * WP_HTML_Tag_Processor instead.
+	 * A token is a span of the document with its own meaning: a tag opener or
+	 * closer, a text node, a comment, or a doctype declaration. Use this method
+	 * instead of {@see WP_HTML_Processor::next_tag} when text or other non-tag
+	 * content matters, while keeping the HTML Processor's structural awareness.
+	 *
+	 * Unlike the Tag Processor's lexical scan, the HTML Processor visits a
+	 * closing token for every element it opens and can continue to process,
+	 * including elements the HTML specification closes implicitly and elements
+	 * left unclosed at the end of the input.
+	 *
+	 * A walk also visits elements the parser inserted into the document tree,
+	 * because HTML defines implied structure. For example, `<table><tr>` is
+	 * visited as TABLE > TBODY > TR, with the implied TBODY appearing in
+	 * {@see WP_HTML_Processor::get_breadcrumbs} and adding to
+	 * {@see WP_HTML_Processor::get_current_depth}. Anchor depth-bounded walks
+	 * on the depth recorded at a matched element rather than on absolute depth
+	 * numbers.
+	 *
+	 * `next_token()` does not stop when an element matched by an earlier
+	 * `next_tag()` call closes. Bound subtree walks with depth or breadcrumbs.
+	 *
+	 * Example:
+	 *
+	 *     // Collect the text content of the first LI element.
+	 *     $processor = WP_HTML_Processor::create_fragment( '<ul><li>Buy <strong>milk</strong> today.</ul>' );
+	 *     if ( $processor->next_tag( 'LI' ) ) {
+	 *         $li_depth = $processor->get_current_depth();
+	 *         $text     = '';
+	 *
+	 *         while ( $processor->next_token() && $processor->get_current_depth() >= $li_depth ) {
+	 *             if ( '#text' === $processor->get_token_type() ) {
+	 *                 $text .= $processor->get_modifiable_text();
+	 *             }
+	 *         }
+	 *
+	 *         // $text is 'Buy milk today.'
+	 *     }
+	 *
+	 * The `>=` comparison is required. A nested child closer, such as
+	 * `</strong>` above, reports the same depth as the LI opener did; a `>`
+	 * comparison would stop early and drop the trailing text.
+	 *
+	 * For repeated regions, prefer one `next_token()` loop with explicit state
+	 * over nested loops. Every call advances the same cursor, so an inner loop
+	 * can consume the boundary token or next sibling that the outer loop expected
+	 * to see.
 	 *
 	 * @since 6.5.0 Added for internal support; do not use.
 	 * @since 6.7.2 Refactored so subclasses may extend.
@@ -1204,6 +1247,23 @@ public function get_breadcrumbs(): array {
 	/**
 	 * Returns the nesting depth of the current location in the document.
 	 *
+	 * The depth counts every node from the root down to and including the
+	 * currently-matched token, so it matches the length of the array returned by
+	 * {@see WP_HTML_Processor::get_breadcrumbs}. Non-element tokens count
+	 * themselves: when matched on a text node directly inside BODY, the depth is
+	 * 3: HTML > BODY > #text.
+	 *
+	 * When the processor is matched on a closing tag token, the closed element
+	 * has already been removed from the stack of open elements. The reported
+	 * depth is that of the remaining parent context: one less than the depth
+	 * reported at the matching opening tag.
+	 *
+	 * This gives a reliable way to visit every token inside an element: record
+	 * the depth when matched on its opening tag and continue while the depth
+	 * remains at or above that value. Only the element's own closer reports a
+	 * shallower depth; nested child closers still report a depth within the
+	 * subtree.
+	 *
 	 * Example:
 	 *
 	 *     $processor = WP_HTML_Processor::create_fragment( '<div><p></p></div>' );
@@ -1218,10 +1278,33 @@ public function get_breadcrumbs(): array {
 	 *     $processor->next_token();
 	 *     4 === $processor->get_current_depth();
 	 *
-	 *     // The P element is closed during `next_token()` so the depth is decreased to reflect that.
+	 *     // The processor is now matched on the </p> closing token. The P
+	 *     // element has already been removed from the stack of open elements,
+	 *     // so the depth reflects its parent context: one less than at <p>.
 	 *     $processor->next_token();
 	 *     3 === $processor->get_current_depth();
 	 *
+	 *     // Likewise on the </div> closing token, the depth has returned to
+	 *     // that of the BODY context.
+	 *     $processor->next_token();
+	 *     2 === $processor->get_current_depth();
+	 *
+	 * Example:
+	 *
+	 *     // Visit every token inside the first UL element.
+	 *     $processor = WP_HTML_Processor::create_fragment( $html );
+	 *     if ( $processor->next_tag( 'UL' ) ) {
+	 *         $ul_depth = $processor->get_current_depth();
+	 *
+	 *         while ( $processor->next_token() && $processor->get_current_depth() >= $ul_depth ) {
+	 *             // Matched on each token inside the UL, including the openers
+	 *             // and closers of nested elements.
+	 *         }
+	 *     }
+	 *
+	 * In break-condition form, break when the depth drops below the depth
+	 * recorded at the opener (`< $ul_depth`), never when it is equal.
+	 *
 	 * @since 6.6.0
 	 *
 	 * @return int Nesting-depth of current location in the document.

src/wp-includes/link-template.php

@@ -2291,7 +2291,7 @@ function previous_post_link( $format = '« %link', $link = '%title', $in_sa
  *
  * @since 3.7.0
  *
- * @param string       $format         Optional. Link anchor format. Default '« %link'.
+ * @param string       $format         Optional. Link anchor format. Default '%link »'.
  * @param string       $link           Optional. Link permalink format. Default '%title'.
  * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
  *                                     Default false.
@@ -2311,7 +2311,7 @@ function get_next_post_link( $format = '%link »', $link = '%title', $in_sa
  *
  * @see get_next_post_link()
  *
- * @param string       $format         Optional. Link anchor format. Default '« %link'.
+ * @param string       $format         Optional. Link anchor format. Default '%link »'.
  * @param string       $link           Optional. Link permalink format. Default '%title'.
  * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
  *                                     Default false.

src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

@@ -2049,17 +2049,15 @@ protected function check_is_comment_content_allowed( $prepared_comment ) {
 	 */
 	private function check_post_type_supports_notes( $post_type ) {
 		$supports = get_all_post_type_supports( $post_type );
+
 		if ( ! isset( $supports['editor'] ) ) {
 			return false;
 		}
+
 		if ( ! is_array( $supports['editor'] ) ) {
 			return false;
 		}
-		foreach ( $supports['editor'] as $item ) {
-			if ( ! empty( $item['notes'] ) ) {
-				return true;
-			}
-		}
-		return false;
+
+		return array_any( $supports['editor'], fn( $item ) => ! empty( $item['notes'] ) );
 	}
 }